openapi: 3.0.3
info:
  title: Seller API
  version: 1.0.0
  description: |-
    Externally facing API to allow enterprise partners to automate listing on Depop.

    ## OAuth 2.0 Scopes

    This API uses OAuth 2.0 scopes to control access to different resources. Each endpoint requires specific scopes to access:

    - **`products_read`** - Required to read product information and listings
    - **`products_write`** - Required to create, update, or delete products
    - **`orders_read`** - Required to read order information and order history
    - **`orders_write`** - Required to mark orders as shipped or process refunds
    - **`offers_read`** - Required to read offer pricing information (auto send offer price, auto negotiate offer price)
    - **`offers_write`** - Required to set or modify offer prices (auto send offer price, auto negotiate offer price)
    - **`shop_read`** - Required to read shop information including seller addresses and available shipping providers

    API key tokens have access to all scopes, while OAuth tokens are limited to the scopes specified in the token.

    If you attempt to access an endpoint without the required scope, you will receive a `403 Forbidden` response with the error code `insufficient_scope`.

servers:
  - url: https://partnerapi-staging.depop.com
  - url: https://partnerapi.depop.com
security:
  - BearerAuth: [ ]

paths:
  /api/v1/products/by-sku/{sku}/:
    put:
      tags:
        - Products
      summary: Create or update a listing on Depop
      description: >-
        This endpoint allows you to create or update a new listing on Depop. The product will be available for sale immediately.

        **Required OAuth Scopes:**
        - `products_write` - Required for all product operations
        - `offers_write` - Required when setting `auto_send_offer_price` or `auto_negotiate_offer_price`

        ## Creating vs. Updating a Listing

        - **Creating a listing:** If the provided `sku` does not exist, a new product listing will be created.
        
        
        - **Updating a listing:** If the provided `sku` already exists, the existing product will be updated with the new details in the request.

        ## Taxonomy
        
        When you're creating a new listing, you'll need to provide a "department" and a "product_type".
        
        
        The "department" is our top-level category, for example, "womenswear" or "menswear".
        
        
        The "product_type" is a more specific category, for example, "tshirts" or "jeans".
        
        
        Note that there's an intermediate level between department and product type called "group".
        We don't need to receive this when an item is being listed but it's used in the apps/website to organize
        the product types.


        For example, in "menswear >> swim-beach-wear >> swimsuit-one-piece", we only need to know the department "menswear"
        and the product type "swimsuit-one-piece".
        
        
        Each product type has a list of assigned attributes, these are optional. For example "swimsuit-one-piece" has the attributes 
        "material" "body-fit" and "occasion".

        ## Sizes
        
        Each department >> product type has their own set of sizes, for example, "womenswear" >> "ballet-shoes" will have a different set of sizes available. 
        These are broken down by region, we currently support US, GB and EU. For example in the US size 4 will be size 2 in GB and 35 in EU. 
        We call these groups of sizes "size_sets". Some "size_sets" can be applied over multiple product types, so for 
        "ballet-shoes" it may have the same "size_set_id" as "boots". 
        
        
        For a given "size_set_id" there is multiple "size_id" each will represent a particular size.
        For example, for the product type "ballet-shoes" and the GB "size_set_id" 44, it has a "size_id" 18 which represents "UK 2" size.
        Please note that "size_id" is not unique, it is dependent on "size_set_id".
        
        
        Please note certain group types will not have any sizes, for example accessories.
        
        ## Fetching Taxonomy
        
        To get the list of departments, you can run the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.department'`:


        ~~~
        
        [
          {
            "id": "menswear",
            "status": "active",
            "name_i18n": {
              "en-US": "Men"
            }
          },
          ...
        ]
        
        ~~~
        
        
        To get the list of product types, you can run the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.group'`:


        ~~~
        
        [
          {
            "id": "bottoms",
            "name_i18n": {
              "en-US": "Bottoms"
            },
            "status": "active",
            "department": [
              "menswear",
              "womenswear",
              "kidswear"
            ],
            "product_types": [
              {
                "id": "jeans",
                "status": "active",
                "name_i18n": {
                  "en-US": "Jeans"
                },
                "attribute_ids": [
                  "bottom-fit",
                  "bottom-style",
                  "occasion",
                  "material",
                  "body-fit"
                ]
              },
              {
                "id": "joggers-tracksuits",
                "status": "active",
                "name_i18n": {
                  "en-US": "Sweatpants"
                },
                "attribute_ids": [
                  "bottom-fit",
                  "bottom-style",
                  "occasion",
                  "material",
                  "body-fit"
                ]
              },
              ...
            ]
          },
          ...
        ]
        
        ~~~
        
        Each product type has a list of attribute ids.
        Each attribute id has a set of possible values which can be found by running the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.generic_attributes'`:
        
        ~~~
        
        [
          {
            "id": "dress-type",
            "name_i18n": {
              "en-US": "Type"
            },
            "status": "active",
            "max_selection": 1,
            "is_mandatory": false,
            "attributes": [
              {
                "id": "a-line",
                "status": "active",
                "name_i18n": {
                  "en-US": "A-line"
                }
              },
              ...
            ]
          },
          ...
        ]

        ~~~
        
        To get the list of size_set_id, you can run the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.category_size_mapping'`:
        
        
        ~~~
        
        [
          {
            "department": "menswear",
            "group": "accessories",
            "product_type": "other-accessories"
          },
          {
            "department": "womenswear",
            "group": "dresses",
            "product_type": "dresses",
            "size_set_by_region": {
              "IT": 81, 
              "US": 84,
              "GB": 86
            }
          },
          ...
        ]
        
        ~~~
        
        Note: "IT" represents Europe.
        
        To get the size_id, you can run the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.size_sets'`:


        ~~~
        
        [
          {
            "id": 101,
            "sizes": [
              {
                "id": 1,
                "name_i18n": {
                  "en-US": "One size"
                },
                "position": 1668
              },
              {
                "id": 2,
                "name_i18n": {
                  "en-US": "0-3 months"
                },
                "position": 1669
              },
              {
                "id": 3,
                "name_i18n": {
                  "en-US": "3-6 months"
                },
                "position": 1670
              },
              ...
            ]
          },
          ...
        ]

        ~~~
        
        As an example lets say we want to list a menswear suit in size M in the UK.
        The department is "menswear", the product type is "suits" and the size_set_id is "93" and the size_id is "4".

      operationId: createOrUpdateProduct
      parameters:
        - name: sku
          in: path
          description: >-
            SKU of the product. Must be unique. It can't be reused.
            
            This SKU will be used in other endpoints to reference this particular product and also in the webhooks.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      requestBody:
        description: Product details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
            example:
              address:
                country_code: "GB"
                state: "Greater London"
              description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
              price_currency: "GBP"
              price_amount: "25.99"
              discount_price: "24.00"
              auto_send_offer_price: "20.00"
              auto_negotiate_offer_price: "20.00"
              national_shipping_cost: "3.50"
              international_shipping_cost: "12.00"
              quantity: 1
              pictures:
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=cover-image"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=back"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=tag"
              department: "menswear"
              product_type: "tshirts"
              size_set_id: 52
              size_id: 10
              condition: "used_excellent"
              colour:
                - "black"
                - "white"
              style:
                - "streetwear"
                - "retro"
                - "sportswear"
              age:
                - "90s"
              source:
                - "vintage"
                - "preloved"
              brand_name: "Nike"
              attributes:
                sleeve-length: [ "short" ]
                material: [ "cotton" ]
                occasion: [ "casual" ]
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCreateOrUpdateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    patch:
      tags:
        - Products
      summary: Patch an existing product on Depop
      description: >-
        This endpoint allows you to patch an `ON SALE` products fields on Depop.

        If you want to restock a product, call the PUT endpoint with the same SKU with the available quantity.

        **Required OAuth Scopes:**
        - `products_write` - Required for all product operations
        - `offers_write` - Required when setting `auto_send_offer_price` or `auto_negotiate_offer_price`
      operationId: patchProduct
      parameters:
        - name: sku
          in: path
          description: SKU of the product.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      requestBody:
        description: Product fields to patch on the existing product.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchProductRequest'
            example:
              price_amount: "39.99"
              discount_price: "37.00"
              auto_send_offer_price: "35.00"
              auto_negotiate_offer_price: "35.00"
        required: true
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      tags:
        - Products
      summary: Get product details by SKU
      description: >-
        This endpoint allows you to get the details of a product by its SKU.

        **Required OAuth Scopes:**
        - `products_read` - Required to access product information
        - `offers_read` - Optional. Required to include offer pricing information (`auto_send_offer_price`, `auto_negotiate_offer_price`) in the response. If this scope is not provided, these fields will be omitted from the response.


        The SKU is the unique identifier for the product and is used in other endpoints to reference this particular product.

        The SKU will be used in the webhooks.

        Note that the SKU will _not_ be reusable.
      operationId: getProductBySku
      parameters:
        - name: sku
          in: path
          description: The SKU of the product.
          required: true
          schema:
            type: string
          example: "ABC-12345-S-BL"
      responses:
        '200':
          description: A single product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              example:
                sku: "ABC-12345-S-BL"
                product_id: 123456789
                slug: "vintage-nike-t-shirt-123456789"
                status: "STATUS_ONSALE"
                address:
                  country_code: "GB"
                  state: "Greater London"
                description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
                price_currency: "GBP"
                price_amount: "25.99"
                discount_price: "24.00"
                auto_send_offer_price: "20.00"
                auto_negotiate_offer_price: "20.00"
                national_shipping_cost: "3.50"
                international_shipping_cost: "12.00"
                quantity: 1
                pictures:
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P0.jpg"
                    height: 1280
                    width: 1280
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P1.jpg"
                    height: 1280
                    width: 1280
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P2.jpg"
                    height: 1280
                    width: 1280
                department: "menswear"
                product_type: "tshirts"
                size_set_id: 52
                size_id: 10
                condition: "used_excellent"
                colour:
                  - "black"
                  - "white"
                style:
                  - "streetwear"
                  - "retro"
                  - "sportswear"
                age:
                  - "90s"
                source:
                  - "vintage"
                  - "preloved"
                attributes:
                  sleeve-length: [ "short" ]
                  material: [ "cotton" ]
                  occasion: [ "casual" ]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      tags:
        - Products
      summary: Delete a product on Depop
      description: >-
        This endpoint allows you to delete a product on Depop.
        The product will no longer be available for sale and will be removed from your shop.
        This endpoint is idempotent - it will return a successful response (200) even if the product doesn't exist.

        **Required OAuth Scope:** `products_write`
      operationId: deleteProduct
      parameters:
        - name: sku
          in: path
          description: SKU of the product.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      responses:
        '200':
          description: Successful operation
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/products/by-sku/{sku}/mark-as-sold/:
    post:
      tags:
        - Products
      summary: Mark a product as sold
      description: >-
        This endpoint allows you to mark a product as sold on your Depop shop.
        The product will no longer be available for sale but it will still be visible in your shop with a "sold" overlay.

        **Required OAuth Scope:** `products_write`

        You're expected to call this as soon as you make a sale on a different platform.
        You don't need to call this if the product sells on Depop.

        If the product is not in a selling state, this endpoint will still return successfully but will remain in the same state.
      operationId: markProductAsSold
      parameters:
        - name: sku
          in: path
          description: SKU of the product.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (sku: womens-tshirt-1, id: 123) not found"
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/products/:
    post:
      tags:
        - Products
      summary: Create a new product
      description: >-
        This endpoint allows you to create a new product listing on Depop. The product will be available for sale immediately.


        **Required OAuth Scopes:**
        - `products_write` - Required for all product operations
        - `offers_write` - Required when setting `auto_send_offer_price` or `auto_negotiate_offer_price`


        **SKU is optional**: If you don't provide a SKU, the product will be created without one (it can be managed by product_id).
        If you provide a SKU and it already exists, the request will fail with a 400 error.

        To update an existing product, use the PUT `/api/v1/products/by-product-id/{productId}/` endpoint instead.
      operationId: createProduct
      requestBody:
        description: Product details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreateRequest'
            example:
              address:
                country_code: "GB"
                state: "Greater London"
              description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
              price_currency: "GBP"
              price_amount: "25.99"
              auto_send_offer_price: "20.00"
              auto_negotiate_offer_price: "20.00"
              national_shipping_cost: "3.50"
              international_shipping_cost: "12.00"
              quantity: 1
              pictures:
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=cover-image"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=back"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=tag"
              department: "menswear"
              product_type: "tshirts"
              size_set_id: 52
              size_id: 10
              condition: "used_excellent"
              colour:
                - "black"
                - "white"
              style:
                - "streetwear"
                - "retro"
                - "sportswear"
              age:
                - "90s"
              source:
                - "vintage"
                - "preloved"
              brand_name: "Nike"
              attributes:
                sleeve-length: [ "short" ]
                material: [ "cotton" ]
                occasion: [ "casual" ]
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCreateOrUpdateResponse'
              example:
                product_id: 12345678
                slug: "vintage-nike-t-shirt-12345678"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      tags:
        - Products
      summary: Get all products
      description: >-
        This endpoint returns all the products you have listed on Depop with details about each product.

        **Required OAuth Scopes:**
        - `products_read` - Required to access product information
        - `offers_read` - Optional. Required to include offer pricing information (`auto_send_offer_price`, `auto_negotiate_offer_price`) in the response. If this scope is not provided, these fields will be omitted from the response.


        It can return a maximum of 100 products at a time and can be paginated using the `cursor` parameter by providing the `cursor` found in the `meta` object.


        The products are returned in descending order, with the latest product added shown first.
      operationId: getAllProducts
      parameters:
        - name: limit
          in: query
          description: The number of products to return. Default is 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
          example: 20
        - name: cursor
          in: query
          description: Request products created after this cursor.
          schema:
            type: string
      responses:
        '200':
          description: >-
            This returns all the products you have listed on Depop.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      cursor:
                        type: string
                        example: "NzIwODg1MXwyMDI1LTA2LTE3VDE2OjM3OjMwLjQ0ODI0NTU1NFp8MjQw"
                      has_more:
                        type: boolean
                        example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                    example: [ ]
                example:
                  meta:
                    cursor: "NzIwODg1MXwyMDI1LTA2LTE3VDE2OjM3OjMwLjQ0ODI0NTU1NFp8MjQw"
                    has_more: false
                  data: [ ]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/products/by-product-id/{productId}/:
    get:
      tags:
        - Products
      summary: Get product details by product ID
      description: >-
        This endpoint allows you to get the details of a product by its internal product ID.

        **Required OAuth Scopes:**
        - `products_read` - Required to access product information
        - `offers_read` - Optional. Required to include offer pricing information (`auto_send_offer_price`, `auto_negotiate_offer_price`) in the response. If this scope is not provided, these fields will be omitted from the response.
      operationId: getProductById
      parameters:
        - name: productId
          in: path
          description: The internal product ID of the product.
          required: true
          schema:
            type: integer
            format: int64
          example: 7033001
      responses:
        '200':
          description: A single product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              example:
                product_id: 7033001
                slug: "vintage-nike-t-shirt-7033001"
                status: "STATUS_ONSALE"
                address:
                  country_code: "GB"
                  state: "Greater London"
                description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
                price_currency: "GBP"
                price_amount: "25.99"
                discount_price: "24.00"
                auto_send_offer_price: "20.00"
                auto_negotiate_offer_price: "20.00"
                national_shipping_cost: "3.50"
                international_shipping_cost: "12.00"
                quantity: 1
                pictures:
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P0.jpg"
                    height: 1280
                    width: 1280
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P1.jpg"
                    height: 1280
                    width: 1280
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P2.jpg"
                    height: 1280
                    width: 1280
                department: "menswear"
                product_type: "tshirts"
                size_set_id: 52
                size_id: 10
                condition: "used_excellent"
                colour:
                  - "black"
                  - "white"
                style:
                  - "streetwear"
                  - "retro"
                  - "sportswear"
                age:
                  - "90s"
                source:
                  - "vintage"
                  - "preloved"
                brand: "nike"
                attributes:
                  sleeve-length: [ "short" ]
                  material: [ "cotton" ]
                  occasion: [ "casual" ]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (id: 7033001) not found"
    put:
      tags:
        - Products
      summary: Update an existing product by product ID
      description: >-
        This endpoint allows you to update an existing product on Depop using its internal product ID.
        The product will be updated with the new details in the request.

        **Required OAuth Scopes:**
        - `products_write` - Required for all product operations
        - `offers_write` - Required when setting `auto_send_offer_price` or `auto_negotiate_offer_price`

        **Note:** This endpoint only supports updating existing products. If the product ID does not exist, a 404 error will be returned.
        To create a new product, use the POST `/api/v1/products/` endpoint instead.
      operationId: updateProductById
      parameters:
        - name: productId
          in: path
          description: >-
            The internal product ID of the product to update.
          required: true
          schema:
            type: integer
            format: int64
          example: 7033001
      requestBody:
        description: Product details to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
            example:
              address:
                country_code: "GB"
                state: "Greater London"
              description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
              price_currency: "GBP"
              price_amount: "25.99"
              discount_price: "24.00"
              auto_send_offer_price: "20.00"
              auto_negotiate_offer_price: "20.00"
              national_shipping_cost: "3.50"
              international_shipping_cost: "12.00"
              quantity: 1
              pictures:
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=cover-image"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=back"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=tag"
              department: "menswear"
              product_type: "tshirts"
              size_set_id: 52
              size_id: 10
              condition: "used_excellent"
              colour:
                - "black"
                - "white"
              style:
                - "streetwear"
                - "retro"
                - "sportswear"
              age:
                - "90s"
              source:
                - "vintage"
                - "preloved"
              brand_name: "Nike"
              attributes:
                sleeve-length: [ "short" ]
                material: [ "cotton" ]
                occasion: [ "casual" ]
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCreateOrUpdateResponse'
              example:
                product_id: 7033001
                slug: "vintage-nike-t-shirt-7033001"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (id: 7033001) not found"
    patch:
      tags:
        - Products
      summary: Patch an existing product by product ID
      description: >-
        This endpoint allows you to patch an `ON SALE` product's fields on Depop using its internal product ID.

        If you want to restock a product, call the PUT endpoint with the same product ID with the available quantity.

        **Required OAuth Scopes:**
        - `products_write` - Required for all product operations
        - `offers_write` - Required when setting `auto_send_offer_price` or `auto_negotiate_offer_price`
      operationId: patchProductById
      parameters:
        - name: productId
          in: path
          description: The internal product ID of the product to patch.
          required: true
          schema:
            type: integer
            format: int64
          example: 7033001
      requestBody:
        description: Product fields to patch on the existing product.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchProductRequest'
            example:
              price_amount: "39.99"
              discount_price: "37.00"
              auto_send_offer_price: "35.00"
              auto_negotiate_offer_price: "35.00"
        required: true
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (id: 7033001) not found"
    delete:
      tags:
        - Products
      summary: Delete a product by product ID
      description: >-
        This endpoint allows you to delete a product on Depop using its internal product ID.
        The product will no longer be available for sale and will be removed from your shop.
        This endpoint is idempotent - it will return a successful response (200) even if the product doesn't exist.

        **Required OAuth Scope:** `products_write`
      operationId: deleteProductById
      parameters:
        - name: productId
          in: path
          description: The internal product ID of the product to delete.
          required: true
          schema:
            type: integer
            format: int64
          example: 7033001
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/products/by-product-id/{productId}/mark-as-sold/:
    post:
      tags:
        - Products
      summary: Mark a product as sold by product ID
      description: >-
        This endpoint allows you to mark a product as sold on your Depop shop using its internal product ID.
        The product will no longer be available for sale but it will still be visible in your shop with a "sold" overlay.

        **Required OAuth Scope:** `products_write`

        You're expected to call this as soon as you make a sale on a different platform.
        You don't need to call this if the product sells on Depop.

        If the product is not in a selling state, this endpoint will still return successfully but will remain in the same state.
      operationId: markProductAsSoldById
      parameters:
        - name: productId
          in: path
          description: The internal product ID of the product.
          required: true
          schema:
            type: integer
            format: int64
          example: 7033001
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (id: 7033001) not found"
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/products/{sku}/:
    put:
      deprecated: true
      tags:
        - Products
      summary: Create or update a listing on Depop
      description: >-
        **This endpoint is deprecated. Please use `/api/v1/products/by-sku/{sku}/` instead.**


        This endpoint allows you to create or update a new listing on Depop. The product will be available for sale immediately.

        **Required OAuth Scopes:**
        - `products_write` - Required for all product operations
        - `offers_write` - Required when setting `auto_send_offer_price` or `auto_negotiate_offer_price`

        ## Creating vs. Updating a Listing

        - **Creating a listing:** If the provided `sku` does not exist, a new product listing will be created.


        - **Updating a listing:** If the provided `sku` already exists, the existing product will be updated with the new details in the request.

        ## Taxonomy

        When you're creating a new listing, you'll need to provide a "department" and a "product_type".


        The "department" is our top-level category, for example, "womenswear" or "menswear".


        The "product_type" is a more specific category, for example, "tshirts" or "jeans".


        Note that there's an intermediate level between department and product type called "group".
        We don't need to receive this when an item is being listed but it's used in the apps/website to organize
        the product types.


        For example, in "menswear >> swim-beach-wear >> swimsuit-one-piece", we only need to know the department "menswear"
        and the product type "swimsuit-one-piece".


        Each product type has a list of assigned attributes, these are optional. For example "swimsuit-one-piece" has the attributes
        "material" "body-fit" and "occasion".

        ## Sizes

        Each department >> product type has their own set of sizes, for example, "womenswear" >> "ballet-shoes" will have a different set of sizes available.
        These are broken down by region, we currently support US, GB and EU. For example in the US size 4 will be size 2 in GB and 35 in EU.
        We call these groups of sizes "size_sets". Some "size_sets" can be applied over multiple product types, so for
        "ballet-shoes" it may have the same "size_set_id" as "boots".


        For a given "size_set_id" there is multiple "size_id" each will represent a particular size.
        For example, for the product type "ballet-shoes" and the GB "size_set_id" 44, it has a "size_id" 18 which represents "UK 2" size.
        Please note that "size_id" is not unique, it is dependent on "size_set_id".


        Please note certain group types will not have any sizes, for example accessories.

        ## Fetching Taxonomy

        To get the list of departments, you can run the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.department'`:


        ~~~

        [
          {
            "id": "menswear",
            "status": "active",
            "name_i18n": {
              "en-US": "Men"
            }
          },
          ...
        ]

        ~~~


        To get the list of product types, you can run the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.group'`:


        ~~~

        [
          {
            "id": "bottoms",
            "name_i18n": {
              "en-US": "Bottoms"
            },
            "status": "active",
            "department": [
              "menswear",
              "womenswear",
              "kidswear"
            ],
            "product_types": [
              {
                "id": "jeans",
                "status": "active",
                "name_i18n": {
                  "en-US": "Jeans"
                },
                "attribute_ids": [
                  "bottom-fit",
                  "bottom-style",
                  "occasion",
                  "material",
                  "body-fit"
                ]
              },
              {
                "id": "joggers-tracksuits",
                "status": "active",
                "name_i18n": {
                  "en-US": "Sweatpants"
                },
                "attribute_ids": [
                  "bottom-fit",
                  "bottom-style",
                  "occasion",
                  "material",
                  "body-fit"
                ]
              },
              ...
            ]
          },
          ...
        ]

        ~~~

        Each product type has a list of attribute ids.
        Each attribute id has a set of possible values which can be found by running the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.generic_attributes'`:

        ~~~

        [
          {
            "id": "dress-type",
            "name_i18n": {
              "en-US": "Type"
            },
            "status": "active",
            "max_selection": 1,
            "is_mandatory": false,
            "attributes": [
              {
                "id": "a-line",
                "status": "active",
                "name_i18n": {
                  "en-US": "A-line"
                }
              },
              ...
            ]
          },
          ...
        ]

        ~~~

        To get the list of size_set_id, you can run the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.category_size_mapping'`:


        ~~~

        [
          {
            "department": "menswear",
            "group": "accessories",
            "product_type": "other-accessories"
          },
          {
            "department": "womenswear",
            "group": "dresses",
            "product_type": "dresses",
            "size_set_by_region": {
              "IT": 81,
              "US": 84,
              "GB": 86
            }
          },
          ...
        ]

        ~~~

        Note: "IT" represents Europe.

        To get the size_id, you can run the following command `curl -s -H'User-agent: Partner' 'https://api.depop.com/api/v3/attributes/' | jq '.size_sets'`:


        ~~~

        [
          {
            "id": 101,
            "sizes": [
              {
                "id": 1,
                "name_i18n": {
                  "en-US": "One size"
                },
                "position": 1668
              },
              {
                "id": 2,
                "name_i18n": {
                  "en-US": "0-3 months"
                },
                "position": 1669
              },
              {
                "id": 3,
                "name_i18n": {
                  "en-US": "3-6 months"
                },
                "position": 1670
              },
              ...
            ]
          },
          ...
        ]

        ~~~

        As an example lets say we want to list a menswear suit in size M in the UK.
        The department is "menswear", the product type is "suits" and the size_set_id is "93" and the size_id is "4".

      operationId: createProductLegacy
      parameters:
        - name: sku
          in: path
          description: >-
            SKU of the product. Must be unique. It can't be reused.

            This SKU will be used in other endpoints to reference this particular product and also in the webhooks.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      requestBody:
        description: Product details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
            example:
              address:
                country_code: "GB"
                state: "Greater London"
              description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
              price_currency: "GBP"
              price_amount: "25.99"
              auto_send_offer_price: "20.00"
              auto_negotiate_offer_price: "20.00"
              national_shipping_cost: "3.50"
              international_shipping_cost: "12.00"
              quantity: 1
              pictures:
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=cover-image"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=back"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=tag"
              department: "menswear"
              product_type: "tshirts"
              size_set_id: 52
              size_id: 10
              condition: "used_excellent"
              colour:
                - "black"
                - "white"
              style:
                - "streetwear"
                - "retro"
                - "sportswear"
              age:
                - "90s"
              source:
                - "vintage"
                - "preloved"
              brand_name: "Nike"
              attributes:
                sleeve-length: [ "short" ]
                material: [ "cotton" ]
                occasion: [ "casual" ]
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCreateOrUpdateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    patch:
      deprecated: true
      tags:
        - Products
      summary: Patch an existing product on Depop
      description: >-
        **This endpoint is deprecated. Please use `/api/v1/products/by-sku/{sku}/` instead.**


        This endpoint allows you to patch an `ON SALE` products fields on Depop.

        If you want to restock a product, call the PUT endpoint with the same SKU with the available quantity.

        **Required OAuth Scopes:**
        - `products_write` - Required for all product operations
        - `offers_write` - Required when setting `auto_send_offer_price` or `auto_negotiate_offer_price`
      operationId: patchProductLegacy
      parameters:
        - name: sku
          in: path
          description: SKU of the product.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      requestBody:
        description: Product fields to patch on the existing product.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchProductRequest'
            example:
              price_amount: "39.99"
              auto_send_offer_price: "35.00"
              auto_negotiate_offer_price: "35.00"
        required: true
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      deprecated: true
      tags:
        - Products
      summary: Get product details by SKU
      description: >-
        **This endpoint is deprecated. Please use `/api/v1/products/by-sku/{sku}/` instead.**


        This endpoint allows you to get the details of a product by its SKU.

        **Required OAuth Scopes:**
        - `products_read` - Required to access product information
        - `offers_read` - Optional. Required to include offer pricing information (`auto_send_offer_price`, `auto_negotiate_offer_price`) in the response. If this scope is not provided, these fields will be omitted from the response.


        The SKU is the unique identifier for the product and is used in other endpoints to reference this particular product.

        The SKU will be used in the webhooks.

        Note that the SKU will _not_ be reusable.
      operationId: getProductBySkuLegacy
      parameters:
        - name: sku
          in: path
          description: The SKU of the product.
          required: true
          schema:
            type: string
          example: "ABC-12345-S-BL"
      responses:
        '200':
          description: A single product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              example:
                sku: "ABC-12345-S-BL"
                product_id: 123456789
                slug: "vintage-nike-t-shirt-123456789"
                status: "STATUS_ONSALE"
                address:
                  country_code: "GB"
                  state: "Greater London"
                description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
                price_currency: "GBP"
                price_amount: "25.99"
                auto_send_offer_price: "20.00"
                auto_negotiate_offer_price: "20.00"
                national_shipping_cost: "3.50"
                international_shipping_cost: "12.00"
                quantity: 1
                pictures:
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P0.jpg"
                    height: 1280
                    width: 1280
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P1.jpg"
                    height: 1280
                    width: 1280
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P2.jpg"
                    height: 1280
                    width: 1280
                department: "menswear"
                product_type: "tshirts"
                size_set_id: 52
                size_id: 10
                condition: "used_excellent"
                colour:
                  - "black"
                  - "white"
                style:
                  - "streetwear"
                  - "retro"
                  - "sportswear"
                age:
                  - "90s"
                source:
                  - "vintage"
                  - "preloved"
                attributes:
                  sleeve-length: [ "short" ]
                  material: [ "cotton" ]
                  occasion: [ "casual" ]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      deprecated: true
      tags:
        - Products
      summary: Delete a product on Depop
      description: >-
        **This endpoint is deprecated. Please use `/api/v1/products/by-sku/{sku}/` instead.**


        This endpoint allows you to delete a product on Depop.
        The product will no longer be available for sale and will be removed from your shop.
        This endpoint is idempotent - it will return a successful response (200) even if the product doesn't exist.

        **Required OAuth Scope:** `products_write`
      operationId: deleteProductLegacy
      parameters:
        - name: sku
          in: path
          description: SKU of the product.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      responses:
        '200':
          description: Successful operation
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/products/{sku}/mark-as-sold/:
    post:
      deprecated: true
      tags:
        - Products
      summary: Mark a product as sold
      description: >-
        **This endpoint is deprecated. Please use `/api/v1/products/by-sku/{sku}/mark-as-sold/` instead.**


        This endpoint allows you to mark a product as sold on your Depop shop.
        The product will no longer be available for sale but it will still be visible in your shop with a "sold" overlay.

        **Required OAuth Scope:** `products_write`

        You're expected to call this as soon as you make a sale on a different platform.
        You don't need to call this if the product sells on Depop.

        If the product is not in a selling state, this endpoint will still return successfully but will remain in the same state.
      operationId: markProductAsSoldLegacy
      parameters:
        - name: sku
          in: path
          description: SKU of the product.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (sku: womens-tshirt-1, id: 123) not found"
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/products/by-product-id/{productId}/purchase/:
    post:
      tags:
        - Products
      summary: Trigger a purchase of a product by product ID (for testing)
      description: >-
        This endpoint allows you to trigger a purchase of a product on Depop using its internal product ID.
        This is useful if you want to test the purchase flow.

        The product will be sold to a test user and the purchase will be visible in your orders.
        You will also receive a webhook for the purchase.

        This endpoint is only available in the staging environment.
      operationId: triggerPurchaseById
      parameters:
        - name: productId
          in: path
          description: The internal product ID of the product.
          required: true
          schema:
            type: integer
            format: int64
          example: 7033001
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/products/by-sku/{sku}/purchase/:
    post:
      tags:
        - Products
      summary: Trigger a purchase of a product by SKU (for testing)
      description: >-
        This endpoint allows you to trigger a purchase of a product on Depop using its SKU.
        This is useful if you want to test the purchase flow.

        The product will be sold to a test user and the purchase will be visible in your orders.
        You will also receive a webhook for the purchase.

        This endpoint is only available in the staging environment.
      operationId: triggerPurchaseBySku
      parameters:
        - name: sku
          in: path
          description: SKU of the product.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/products/{sku}/purchase/:
    post:
      deprecated: true
      tags:
        - Products
      summary: Trigger a purchase of a product (for testing)
      description: >-
        This endpoint allows you to trigger a purchase of a product on Depop.
        This is useful if you want to test the purchase flow.

        The product will be sold to a test user and the purchase will be visible in your orders.
        You will also receive a webhook for the purchase.

        This endpoint is only available in the staging environment.

        **Deprecated**: Use `/api/v1/products/by-sku/{sku}/purchase/` instead.
      operationId: triggerPurchase
      parameters:
        - name: sku
          in: path
          description: SKU of the product.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/products/by-product-id/{productId}/offer/:
    post:
      tags:
        - Products
      summary: Submit an offer for a product by product ID
      description: >-
        This endpoint allows you to submit an offer on behalf of a seller to a specific buyer for a product using its internal product ID.
        The offer will be sent to the specified buyer.
        You can only send offers to buyers who have shown interest in your products (likes, bags, messages)

        **Required OAuth Scope:** `offers_write`


        ## Validation Rules

        The following validations are enforced:

        - **Offer value:** Must be at least 5% lower than product price_amount
        - **Currency:** Must match the product's currency exactly
        - **Size ID:** Must follow size handling rules (see below)


        ## Multiple sizes Handling

        - **Products without multiple sizes:** Do not provide `size_id`
        - **Products with a single size:** The `size_id` will be automatically populated if not provided
        - **Products with multiple sizes:** You must provide a valid `size_id` that exists for the product
      operationId: submitOfferByProductId
      parameters:
        - name: productId
          in: path
          description: The internal product ID of the product.
          required: true
          schema:
            type: integer
            format: int64
          example: 7033001
      requestBody:
        description: Offer details payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitOfferRequest'
            example:
              offer_recipient_id: 456789
              offer_value: 25.00
              offer_currency: "GBP"
              size_id: 2
      responses:
        '200':
          description: Offer submitted successfully, no content returned.
          content: { }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                currencyMismatch:
                  summary: Currency mismatch
                  value:
                    id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                    errors:
                      - code: "validation-error"
                        message: "Offer currency GBP does not match product currency USD"
                priceNotAtOfferThreshold:
                  summary: Offer price not 5% lower than the product price
                  value:
                    id: "b320134g-d2g4-5e95-b3ce-8g29d79664f3"
                    errors:
                      - code: "validation-error"
                        message: "Offer value must be at least 5% lower than the product price"
                invalidSizeId:
                  summary: Invalid size ID for product
                  value:
                    id: "c431245h-e3h5-6f06-c4df-9h30e80775g4"
                    errors:
                      - code: "validation-error"
                        message: "Size Id 99 does not exist for product 7033001"
                multipleSizesNoSizeId:
                  summary: Multiple sizes but no size ID provided
                  value:
                    id: "d542356i-f4i6-7g17-d5eg-0i41f91886h5"
                    errors:
                      - code: "validation-error"
                        message: "Product 7033001 has multiple sizes, a size ID must be provided"
                noSizesButSizeProvided:
                  summary: No sizes but size ID provided
                  value:
                    id: "e653467j-g5j7-8h28-e6fh-1j52g02997i6"
                    errors:
                      - code: "validation-error"
                        message: "Product 7033001 does not have multiple sizes, a size ID must not be provided"
  /api/v1/products/by-sku/{sku}/offer/:
    post:
      tags:
        - Products
      summary: Submit an offer for a product by SKU
      description: >-
        This endpoint allows you to submit an offer on behalf of a seller to a specific buyer for a product using its SKU.
        The offer will be sent to the specified buyer.
        You can only send offers to buyers who have shown interest in your products (likes, bags, messages)

        **Required OAuth Scope:** `offers_write`


        ## Validation Rules

        The following validations are enforced:

        - **Offer value:** Must be at least 5% lower than product price_amount
        - **Currency:** Must match the product's currency exactly
        - **Size ID:** Must follow size handling rules (see below)


        ## Multiple sizes Handling

        - **Products without multiple sizes:** Do not provide `size_id`
        - **Products with a single size:** The `size_id` will be automatically populated
        - **Products with multiple sizes:** You must provide a valid `size_id` that exists for the product
      operationId: submitOfferBySku
      parameters:
        - name: sku
          in: path
          description: SKU of the product.
          required: true
          schema:
            type: string
            maxLength: 50
          example: ABC-12345-S-BL
      requestBody:
        description: Offer details payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitOfferRequest'
            example:
              offer_recipient_id: 456789
              offer_value: 25.00
              offer_currency: "GBP"
              size_id: 2
      responses:
        '200':
          description: Offer submitted successfully, no content returned.
          content: { }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                currencyMismatch:
                  summary: Currency mismatch
                  value:
                    id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                    errors:
                      - code: "validation-error"
                        message: "Offer currency GBP does not match product currency USD"
                priceNotAtOfferThreshold:
                  summary: Offer price not 5% lower than the product price
                  value:
                    id: "b320134g-d2g4-5e95-b3ce-8g29d79664f3"
                    errors:
                      - code: "validation-error"
                        message: "Offer value must be at least 5% lower than the product price"
                invalidSizeId:
                  summary: Invalid size ID for product
                  value:
                    id: "c431245h-e3h5-6f06-c4df-9h30e80775g4"
                    errors:
                      - code: "validation-error"
                        message: "Size Id 99 does not exist for product 7033001"
                multipleSizesNoSizeId:
                  summary: Multiple sizes but no size ID provided
                  value:
                    id: "d542356i-f4i6-7g17-d5eg-0i41f91886h5"
                    errors:
                      - code: "validation-error"
                        message: "Product 7033001 has multiple sizes, a size ID must be provided"
                noSizesButSizeProvided:
                  summary: No sizes but size ID provided
                  value:
                    id: "e653467j-g5j7-8h28-e6fh-1j52g02997i6"
                    errors:
                      - code: "validation-error"
                        message: "Product 7033001 does not have multiple sizes, a size ID must not be provided"
  /api/v1/products/by-slug/{slug}/:
    get:
      tags:
        - Products
      summary: Get product details by slug
      description: >-
        This endpoint allows you to get the details of a product by its slug.

        **Required OAuth Scopes:**
        - `products_read` - Required to access product information
        - `offers_read` - Optional. Required to include offer pricing information (`auto_send_offer_price`, `auto_negotiate_offer_price`) in the response. If this scope is not provided, these fields will be omitted from the response.


        The slug is a URL-friendly identifier for the product and can be obtained from any endpoint that returns product details (e.g. `GET /api/v1/products/by-sku/{sku}/` or create/update responses).
      operationId: getProductBySlug
      parameters:
        - name: slug
          in: path
          description: The slug of the product.
          required: true
          schema:
            type: string
          example: "vintage-nike-t-shirt-7033001"
      responses:
        '200':
          description: A single product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              example:
                product_id: 7033001
                slug: "vintage-nike-t-shirt-7033001"
                status: "STATUS_ONSALE"
                address:
                  country_code: "GB"
                  state: "Greater London"
                description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
                price_currency: "GBP"
                price_amount: "25.99"
                discount_price: "24.00"
                auto_send_offer_price: "20.00"
                auto_negotiate_offer_price: "20.00"
                national_shipping_cost: "3.50"
                international_shipping_cost: "12.00"
                quantity: 1
                pictures:
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P0.jpg"
                    height: 1280
                    width: 1280
                  - url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P1.jpg"
                    height: 1280
                    width: 1280
                department: "menswear"
                product_type: "tshirts"
                size_set_id: 52
                size_id: 10
                condition: "used_excellent"
                colour:
                  - "black"
                  - "white"
                style:
                  - "streetwear"
                  - "retro"
                  - "sportswear"
                age:
                  - "90s"
                source:
                  - "vintage"
                  - "preloved"
                brand: "nike"
                attributes:
                  sleeve-length: [ "short" ]
                  material: [ "cotton" ]
                  occasion: [ "casual" ]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (slug: vintage-nike-t-shirt-7033001) not found"
    put:
      tags:
        - Products
      summary: Update an existing product by slug
      description: >-
        This endpoint allows you to update an existing product on Depop using its slug.
        The product will be updated with the new details in the request.

        **Required OAuth Scopes:**
        - `products_write` - Required for all product operations
        - `offers_write` - Required when setting `auto_send_offer_price` or `auto_negotiate_offer_price`

        **Note:** This endpoint only supports updating existing products. If the slug does not exist, a 404 error will be returned.
        To create a new product, use the POST `/api/v1/products/` or PUT `/api/v1/products/by-sku/{sku}/` endpoint instead.
      operationId: updateProductBySlug
      parameters:
        - name: slug
          in: path
          description: The slug of the product to update.
          required: true
          schema:
            type: string
          example: "vintage-nike-t-shirt-7033001"
      requestBody:
        description: Product details to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
            example:
              address:
                country_code: "GB"
                state: "Greater London"
              description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
              price_currency: "GBP"
              price_amount: "25.99"
              discount_price: "24.00"
              auto_send_offer_price: "20.00"
              auto_negotiate_offer_price: "20.00"
              national_shipping_cost: "3.50"
              international_shipping_cost: "12.00"
              quantity: 1
              pictures:
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=cover-image"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=back"
                - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=tag"
              department: "menswear"
              product_type: "tshirts"
              size_set_id: 52
              size_id: 10
              condition: "used_excellent"
              colour:
                - "black"
                - "white"
              style:
                - "streetwear"
                - "retro"
                - "sportswear"
              age:
                - "90s"
              source:
                - "vintage"
                - "preloved"
              brand_name: "Nike"
              attributes:
                sleeve-length: [ "short" ]
                material: [ "cotton" ]
                occasion: [ "casual" ]
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCreateOrUpdateResponse'
              example:
                product_id: 7033001
                slug: "vintage-nike-t-shirt-7033001"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (slug: vintage-nike-t-shirt-7033001) not found"
    patch:
      tags:
        - Products
      summary: Patch an existing product by slug
      description: >-
        This endpoint allows you to patch an `ON SALE` product's fields on Depop using its slug.

        If you want to restock a product, call the PUT endpoint with the same slug with the available quantity.

        **Required OAuth Scopes:**
        - `products_write` - Required for all product operations
        - `offers_write` - Required when setting `auto_send_offer_price` or `auto_negotiate_offer_price`
      operationId: patchProductBySlug
      parameters:
        - name: slug
          in: path
          description: The slug of the product to patch.
          required: true
          schema:
            type: string
          example: "vintage-nike-t-shirt-7033001"
      requestBody:
        description: Product fields to patch on the existing product.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchProductRequest'
            example:
              price_amount: "39.99"
              discount_price: "37.00"
              auto_send_offer_price: "35.00"
              auto_negotiate_offer_price: "35.00"
        required: true
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (slug: vintage-nike-t-shirt-7033001) not found"
    delete:
      tags:
        - Products
      summary: Delete a product by slug
      description: >-
        This endpoint allows you to delete a product on Depop using its slug.
        The product will no longer be available for sale and will be removed from your shop.
        This endpoint is idempotent - it will return a successful response (200) even if the product doesn't exist.

        **Required OAuth Scope:** `products_write`
      operationId: deleteProductBySlug
      parameters:
        - name: slug
          in: path
          description: The slug of the product to delete.
          required: true
          schema:
            type: string
          example: "vintage-nike-t-shirt-7033001"
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/products/by-slug/{slug}/mark-as-sold/:
    post:
      tags:
        - Products
      summary: Mark a product as sold by slug
      description: >-
        This endpoint allows you to mark a product as sold on your Depop shop using its slug.
        The product will no longer be available for sale but it will still be visible in your shop with a "sold" overlay.

        **Required OAuth Scope:** `products_write`

        You're expected to call this as soon as you make a sale on a different platform.
        You don't need to call this if the product sells on Depop.

        If the product is not in a selling state, this endpoint will still return successfully but will remain in the same state.
      operationId: markProductAsSoldBySlug
      parameters:
        - name: slug
          in: path
          description: The slug of the product.
          required: true
          schema:
            type: string
          example: "vintage-nike-t-shirt-7033001"
      responses:
        '200':
          description: Successful operation, no content returned.
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "product_not_found"
                    message: "Product (slug: vintage-nike-t-shirt-7033001) not found"
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/products/by-slug/{slug}/offer/:
    post:
      tags:
        - Products
      summary: Submit an offer for a product by slug
      description: >-
        This endpoint allows you to submit an offer on behalf of a seller to a specific buyer for a product using its slug.
        The offer will be sent to the specified buyer.
        You can only send offers to buyers who have shown interest in your products (likes, bags, messages)

        **Required OAuth Scope:** `offers_write`


        ## Validation Rules

        The following validations are enforced:

        - **Offer value:** Must be at least 5% lower than product price_amount
        - **Currency:** Must match the product's currency exactly
        - **Size ID:** Must follow size handling rules (see below)


        ## Multiple sizes Handling

        - **Products without multiple sizes:** Do not provide `size_id`
        - **Products with a single size:** The `size_id` will be automatically populated if not provided
        - **Products with multiple sizes:** You must provide a valid `size_id` that exists for the product
      operationId: submitOfferBySlug
      parameters:
        - name: slug
          in: path
          description: The slug of the product.
          required: true
          schema:
            type: string
          example: "vintage-nike-t-shirt-7033001"
      requestBody:
        description: Offer details payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitOfferRequest'
            example:
              offer_recipient_id: 456789
              offer_value: 25.00
              offer_currency: "GBP"
              size_id: 2
      responses:
        '200':
          description: Offer submitted successfully, no content returned.
          content: { }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                currencyMismatch:
                  summary: Currency mismatch
                  value:
                    id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                    errors:
                      - code: "validation-error"
                        message: "Offer currency GBP does not match product currency USD"
                priceNotAtOfferThreshold:
                  summary: Offer price not 5% lower than the product price
                  value:
                    id: "b320134g-d2g4-5e95-b3ce-8g29d79664f3"
                    errors:
                      - code: "validation-error"
                        message: "Offer value must be at least 5% lower than the product price"
                invalidSizeId:
                  summary: Invalid size ID for product
                  value:
                    id: "c431245h-e3h5-6f06-c4df-9h30e80775g4"
                    errors:
                      - code: "validation-error"
                        message: "Size Id 99 does not exist for product vintage-nike-t-shirt-7033001"
                multipleSizesNoSizeId:
                  summary: Multiple sizes but no size ID provided
                  value:
                    id: "d542356i-f4i6-7g17-d5eg-0i41f91886h5"
                    errors:
                      - code: "validation-error"
                        message: "Product vintage-nike-t-shirt-7033001 has multiple sizes, a size ID must be provided"
                noSizesButSizeProvided:
                  summary: No sizes but size ID provided
                  value:
                    id: "e653467j-g5j7-8h28-e6fh-1j52g02997i6"
                    errors:
                      - code: "validation-error"
                        message: "Product vintage-nike-t-shirt-7033001 does not have multiple sizes, a size ID must not be provided"
  /api/v1/orders/:
    get:
      summary: Get all orders
      description: >-
        This endpoint returns all the orders you have received on Depop.

        **Required OAuth Scope:** `orders_read`


        It can return a maximum of 200 orders at a time and can be paginated using the `cursor` parameter by providing the `cursor` found in the `meta` object.
      operationId: getAllOrders
      tags:
        - Orders
      parameters:
        - name: limit
          in: query
          description: The number of orders to return. Default is 20.
          schema:
            type: integer
            minimum: 1
            maximum: 200
          example: 20
        - name: cursor
          in: query
          description: The cursor to start from. This is the ID of the last purchase order ID returned in the previous request.
          schema:
            type: string
          example: "NDM0NjMyOTI5Njg3"
        - name: from
          in: query
          description: The start date of the orders to return.
          schema:
            type: string
            format: date-time
          example: "2025-01-01T00:00:00Z"
        - name: to
          in: query
          description: The end date of the orders to return.
          schema:
            type: string
            format: date-time
          example: "2025-01-31T23:59:59Z"
      responses:
        '200':
          description: >-
            A page with orders.
            
            This endpoint must be used to reconcile the orders you have received via webhooks.
            You can do this either by polling the endpoint and using the cursor until you reach an order you have already processed.
            Alternatively, you can use the `from` and `to` parameters to get orders in a specific time frame.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersPage'
              example:
                meta:
                  cursor: "123456789"
                  has_more: false
                data: [ ]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/orders/{purchase_id}/:
    get:
      summary: Get order details by purchase ID
      description: >-
        This endpoint allows you to get the details of an order by its purchase ID.

        **Required OAuth Scope:** `orders_read`


        The purchase ID is the unique identifier for the order and is used in other endpoints to reference this particular order.
      operationId: getOrderByPurchaseId
      tags:
        - Orders
      parameters:
        - name: purchase_id
          in: path
          description: The purchase ID of the order.
          required: true
          schema:
            type: string
          example: "123456"
      responses:
        '200':
          description: A single order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              example:
                seller_id: 123456
                purchase_id: "123456"
                status: "SHIPPING_PENDING"
                currency: "GBP"
                buyer_pays_amount: "50.99"
                seller_receives_amount: "45.99"
                buyer_shipping_price: "5.00"
                buyer_address:
                  name: "John Doe"
                  address: "123 Main St"
                  address2: "Apt 1"
                  city: "London"
                  postal_code: "EC1V 4PW"
                  state: "Greater London"
                  country_code: "GB"
                line_items:
                  - purchase_item_id: 2385551
                    sku: "ABC-12345-S-BL"
                    product_id: 7021251
                    parcel_id: "6e3538ca-6653-3c25-bf0a-a2be876b17e4"
                    description: "Vintage Nike T-Shirt in excellent condition. Black with white swoosh logo on the front."
                    original_price: "29.99"
                    sold_price: "25.99"
                    sold_via_offers: false
                    image_url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P0.jpg"
                seller_fee_breakdown:
                  - fee_type: "DEPOP_FEE"
                    amount: "3.00"
                    currency: "GBP"
                  - fee_type: "PAYMENT_FEE"
                    amount: "2.00"
                    currency: "GBP"
                created_at: "2025-01-01T12:00:00Z"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/orders/{purchase_id}/parcels/{parcel_id}/mark-as-shipped/:
    post:
      summary: Mark an order as shipped, providing tracking information.
      description: >-
        This endpoint allows you to mark an order as shipped, providing tracking information.

        **Required OAuth Scope:** `orders_write`


        The order will be marked as shipped and the tracking information will be sent to the buyer.

      operationId: markOrderAsShipped
      tags:
        - Orders
      parameters:
        - name: purchase_id
          in: path
          description: The purchase ID of the order.
          required: true
          schema:
            type: string
          example: "123456"
        - name: parcel_id
          in: path
          description: The parcel ID of the order.
          required: true
          schema:
            type: string
          example: "6e3538ca-6653-3c25-bf0a-a2be876b17e4"
      requestBody:
        description: Tracking information
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkAsShippedRequest'
            example:
              tracking_number: "123456789"
              carrier: "Royal Mail"
      responses:
        '200':
          description: Successful operation, no content returned
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/orders/{purchase_id}/refund/:
    post:
      summary: Refund an order
      description: >-
        This endpoint allows you to refund an order and send a message to the buyer.

        **Required OAuth Scope:** `orders_write`


        A refund can be a full refund or a partial refund by specifying the amount to refund on items and/or shipping within the order.


        The order will be marked as refunded and the buyer will be notified. If a message is provided, it will be sent to the buyer directly in Depop chat.


        The order will still be visible in your orders but marked as REFUNDED.


        All fees will automatically be calculated and refunded to the buyer and the seller (partner).
      operationId: refundOrder
      tags:
        - Orders
      parameters:
        - name: purchase_id
          in: path
          description: The purchase ID of the order.
          required: true
          schema:
            type: string
          example: "123456"
      requestBody:
        description: Refund details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundOrderRequest'
            example:
              items_refund_amount: "50.99"
              shipping_refund_amount: "4.99"
              send_buyer_message: "Your order has been refunded. We apologize for the inconvenience."
      responses:
        '200':
          description: Successful operation, no content returned
          content: { }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "validation"
                    message: "Refund for purchase id 123456 must have an item amount or a shipping amount to refund."
                  - code: "validation"
                    message: "Refund for purchase id 123456 must have a positive amount to refund."
                  - code: "validation"
                    message: "Refund for purchase id 123456 has items_refund_amount greater than product price."
                  - code: "validation"
                    message: "Refund for purchase id 123456 has shipping_refund_amount greater than shipping price."

  /api/v1/shop/:
    get:
      summary: Get seller details
      description: >-
        This endpoint allows you to retrieve details about your Depop shop, including your seller ID, username, and country code.

        **Required OAuth Scope:** `shop_read`
      operationId: getSellerDetails
      tags:
        - Shop Management
      responses:
        '200':
          description: Seller details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerDetails'
              example:
                id: 97082934
                username: "good_will_charity"
                country_code: "US"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden - Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "insufficient_scope"
                    message: "The request requires higher privileges than provided by the access token. Required scope: shop_read"

  /api/v1/shop/seller-addresses/:
    get:
      summary: Get seller addresses
      description: >-
        This endpoint allows you to retrieve all active addresses associated with your Depop shop.

        **Required OAuth Scope:** `shop_read`


        These addresses can be used to determine available shipping providers for your shop.
      operationId: getSellerAddresses
      tags:
        - Shop Management
      responses:
        '200':
          description: A paginated list of seller addresses
          content:
            application/json:
              schema:
                type: object
                required:
                  - meta
                  - data
                properties:
                  meta:
                    type: object
                    required:
                      - has_more
                    properties:
                      cursor:
                        type: string
                        nullable: true
                        description: Cursor for pagination. Null when there are no more results.
                        example: "MTIzNDU2fDIwMjUtMDEtMTVUMTA6MzA6MDBafDEyMw"
                      has_more:
                        type: boolean
                        description: Indicates whether there are more results available.
                        example: false
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SellerAddress'
                    example: []
              example:
                meta:
                  cursor: "MTIzNDU2fDIwMjUtMDEtMTVUMTA6MzA6MDBafDEyMw"
                  has_more: false
                data:
                  - id: 123456
                    name: "John Doe"
                    address: "123 Main Street"
                    address2: "Apt 4B"
                    city: "London"
                    state: "Greater London"
                    postal_code: "SW1A 1AA"
                    country: "GB"
                    last_modified: "2025-01-15T10:30:00Z"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden - Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "insufficient_scope"
                    message: "The request requires higher privileges than provided by the access token. Required scope: shop_read"

  /api/v1/shop/seller-addresses/{address_id}/shipping-providers/:
    get:
      summary: Get available shipping providers for an address
      description: >-
        This endpoint allows you to retrieve the available shipping providers for a specific seller address.

        **Required OAuth Scope:** `shop_read`


        The response includes the shipping providers and their available parcel sizes with pricing information.
        
        If no shipping providers are available for the given address, manual shipping will be returned as the provider Id.
      operationId: getShippingProviders
      tags:
        - Shop Management
      parameters:
        - name: address_id
          in: path
          description: The ID of the seller address.
          required: true
          schema:
            type: integer
            format: int64
          example: 123456
      responses:
        '200':
          description: A list of available shipping providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShippingProviderInfo'
              example:
                - id: "MY_HERMES"
                  parcel_sizes:
                    - id: "small"
                      title: "Small"
                      subtitle: "Tops, jeans, dresses and jewellery"
                      cost:
                        original_amount: "2.99"
                        original_currency: "GBP"
                        amount: "2.99"
                        currency: "GBP"
                      courier_service: "DROP_OFF"
                    - id: "medium"
                      title: "Medium"
                      subtitle: "Coats, jackets, trainers and shoes"
                      cost:
                        original_amount: "4.99"
                        original_currency: "GBP"
                        amount: "4.99"
                        currency: "GBP"
                      courier_service: "DROP_OFF"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden - Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "insufficient_scope"
                    message: "The request requires higher privileges than provided by the access token. Required scope: shop_read"
        '404':
          description: Address not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
                errors:
                  - code: "address_not_found"
                    message: "Address with ID 999999 not found"

  /api-docs/openapi.yaml:
    get:
      summary: Get the latest version of the OpenAPI specification (this document).
      description: >-
        This endpoint returns the latest version of the OpenAPI specification for the Depop API.
        
        You can use this to generate client libraries or to understand the API better.
        
        The OpenAPI specification is in YAML format and can be used with tools like Swagger UI or Postman.
      operationId: getOpenAPISpec
      tags:
        - Docs
      responses:
        '200':
          description: OK
  /api/v1/oauth2/access-token/:
    post:
      tags:
        - Authentication
      summary: OAuth 2.0 token endpoint (authorization code exchange and refresh token)
      description: >-
        Token endpoint supporting multiple grant types according to RFC 6749:
        - Authorization Code (Section 4.1.3): Exchange authorization code for access tokens
        - Refresh Token (Section 6): Exchange refresh token for new access tokens

        **Authorization Code Flow:**
        Requires PKCE (Proof Key for Code Exchange) with S256 challenge method according to RFC 7636.
        The code_verifier parameter is required and must match the code_challenge from the authorization request.
        The scopes granted during authorization are retrieved and included in the generated access token.

        **Refresh Token Flow:**
        Exchange a partner refresh token for a new access token and refresh token pair.
        The original refresh token is consumed and cannot be reused.
        The new refresh token maintains the same expiry as the original (1 year from initial creation).
      operationId: exchangeToken
      security: [ ]
      requestBody:
        required: true
        description: Authorization code exchange request with client credentials
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum: [ "authorization_code", "refresh_token" ]
                  description: OAuth 2.0 grant type - 'authorization_code' to exchange code for tokens, 'refresh_token' to refresh access token
                  example: "authorization_code"
                code:
                  type: string
                  description: Authorization code received from the authorization endpoint (required for authorization_code grant)
                  example: "placeholder_auth_code_12345"
                redirect_uri:
                  type: string
                  format: uri
                  description: Redirect URI that must match the one used in authorization request (required for authorization_code grant)
                  example: "https://example.com/auth/callback"
                client_id:
                  type: string
                  description: OAuth client identifier
                  example: "a1b2c3d4e5f6g7h8i9j0"
                client_secret:
                  type: string
                  description: OAuth client secret for authentication
                  example: "client_secret_abc123"
                code_verifier:
                  type: string
                  description: |
                    PKCE code verifier used to verify the code_challenge from the authorization request.
                    Required for all authorization code flows (PKCE is mandatory).
                    Must be 43-128 characters long and contain only [A-Za-z0-9._~-] characters.
                    Not used for refresh_token grant.
                  example: "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
                refresh_token:
                  type: string
                  description: Partner refresh token to exchange for new tokens (required for refresh_token grant)
                  example: "prt_26f4f74b761c83ef0d383bcfc419e114fd554331"
              required:
                - grant_type
                - client_id
                - client_secret
            examples:
              authorization_code:
                summary: Exchange authorization code for tokens
                value:
                  grant_type: "authorization_code"
                  code: "placeholder_auth_code_12345"
                  redirect_uri: "https://example.com/auth/callback"
                  client_id: "a1b2c3d4e5f6g7h8i9j0"
                  client_secret: "client_secret_abc123"
                  code_verifier: "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
              refresh_token:
                summary: Refresh access token
                value:
                  grant_type: "refresh_token"
                  refresh_token: "prt_26f4f74b761c83ef0d383bcfc419e114fd554331"
                  client_id: "a1b2c3d4e5f6g7h8i9j0"
                  client_secret: "client_secret_abc123"
      responses:
        '200':
          description: Successfully exchanged authorization code or refresh token for access and refresh tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
              example:
                access_token: "pat_4eea1fdb98106005fea67ed65138df69afa0e6aa"
                refresh_token: "prt_26f4f74b761c83ef0d383bcfc419e114fd554331"
                expires_in: 3600
                token_type: "Bearer"
        '400':
          description: Invalid token exchange request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
              examples:
                invalid_grant:
                  summary: Invalid or expired authorization code or refresh token
                  value:
                    code: 400
                    error: "invalid_grant"
                    message: "Depop OAuth2 error"
                    detail: "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client"
                    error_message: "Depop OAuth2 error"
                    error_description: "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client"
                    id: "550e8400-e29b-41d4-a716-446655440000"
                invalid_refresh_token:
                  summary: Invalid, expired, or revoked refresh token
                  value:
                    code: 400
                    error: "invalid_grant"
                    message: "Depop OAuth2 error"
                    detail: "The refresh token is invalid, expired, revoked, or does not belong to the client"
                    error_message: "Depop OAuth2 error"
                    error_description: "The refresh token is invalid, expired, revoked, or does not belong to the client"
                    id: "550e8400-e29b-41d4-a716-446655440004"
                invalid_client:
                  summary: Client authentication failed
                  value:
                    code: 401
                    error: "client secret does not match"
                    message: "Depop OAuth2 error"
                    detail: "Depop OAuth2 error"
                    error_message: "Depop OAuth2 error"
                    error_description: "Depop OAuth2 error"
                    id: "550e8400-e29b-41d4-a716-446655440001"
                invalid_request:
                  summary: Missing or invalid request parameters
                  value:
                    code: 400
                    error: "invalid_request"
                    message: "Depop OAuth2 error"
                    detail: "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed"
                    error_message: "Depop OAuth2 error"
                    error_description: "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed"
                    id: "550e8400-e29b-41d4-a716-446655440002"
                pkce_verification_failed:
                  summary: PKCE code verifier does not match challenge
                  value:
                    code: 400
                    error: "invalid_request"
                    message: "Depop OAuth2 error"
                    detail: "PKCE verification failed - code verifier does not match the stored code challenge"
                    error_message: "Depop OAuth2 error"
                    error_description: "PKCE verification failed - code verifier does not match the stored code challenge"
                    id: "550e8400-e29b-41d4-a716-446655440003"
        '401':
          description: Unauthorized - Client authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
              example:
                code: 401
                error: "client secret does not match"
                message: "Depop OAuth2 error"
                detail: "Depop OAuth2 error"
                error_message: "Depop OAuth2 error"
                error_description: "Depop OAuth2 error"
                id: "43d738a4-a3bf-4c79-bdd0-97a61ecf022a"
  /status:
    get:
      responses:
        '200':
          description: OK
          headers: { }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              example:
                status: OK
      summary: Get status
      operationId: getStatus
      description: >-
        This endpoint can be used to check the availability of the API.

        If the API is up and running, it will return a 200 status code with the message "OK".
      tags:
        - API status
      parameters: [ ]
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
  schemas:
    ProductCreateOrUpdateResponse:
      type: object
      required:
        - product_id
        - slug
      properties:
        product_id:
          type: number
          example: 12345678
          description: The product id of the created or updated product.
        slug:
          type: string
          example: "vintage-nike-t-shirt-12345678"
          description: >-
            The URL-friendly identifier for the product on Depop.
            This can be used with the `/api/v1/products/by-slug/{slug}/` endpoints.
        sku:
          type: string
          nullable: true
          example: "ABC-12345-S-BL"
          description: >-
            The SKU of the product.

            - For PUT `/api/v1/products/by-sku/{sku}/`: Always present (same as the SKU in the URL path).
            - For PUT `/api/v1/products/by-slug/{slug}/`: Present if the product has a SKU, otherwise null.
            - For PUT `/api/v1/products/by-product-id/{productId}/`: Present if the product has a SKU, otherwise null.
            - For POST `/api/v1/products/`: Present if SKU was provided in the request, otherwise null.
      example:
        product_id: 12345678
        slug: "vintage-nike-t-shirt-12345678"
        sku: "ABC-12345-S-BL"
    ProductCreateRequest:
      type: object
      required:
        - address
        - description
        - price_currency
        - price_amount
        - quantity
        - pictures
        - department
        - product_type
        - condition
        - brand_name
      properties:
        sku:
          type: string
          description: >-
            SKU of the product. Optional - if not provided, the product will be created without a SKU.

            Must be unique. Can't be reused.

            This SKU will be used in other endpoints to reference this particular product and also in the webhooks.
          maxLength: 50
          example: ABC-12345-S-BL
        address:
          $ref: '#/components/schemas/Address'
        description:
          type: string
          description: >-
            A good description should contain key attribute information (brand, category, color, size, age etc),
            clarifying information about flaws, condition, fit, size and measurements.
            Commonly they end with hash tags (for example, \#summer).

            Constraints:
             * Limited to 1000 characters
             * Email addresses are not allowed
             * Can only have up to 5 hashtags (for example, \#summer).
          maxLength: 1000
          example: >-
            Women's Burgundy and Purple Vest

            Mauve and white striped tank top
            Small mark at the bottom of the hem

            #stripes #summer
        price_currency:
          type: string
          description: The currency code of the item's price.
          example: GBP
        price_amount:
          type: string
          description: The price of the item. Must be at least $1.00 or £1.00. Up to 2 decimal places.
          example: "50.99"
        auto_send_offer_price:
          type: string
          description: >-
            The price to automatically send to buyers who liked or have bagged the product.

            There's a fixed 1h delay before an offer is sent.

            If not set, the product will not automatically send offers.

            Must be less at least 5% off the price_amount.
            Up to 2 decimal places.
          example: "45.00"
        auto_negotiate_offer_price:
          type: string
          description: >-
            The price to automatically respond with when a buyer sends an offer in this product:
             * If the buyer offer is higher or equal to this value, then the offer will be automatically accepted.
             * If the buyer offer is lower than this value, then the offer will be automatically countered with this price.

            If the buyer counters again, the same value will be used to counter the buyer's offer.

            If not set, the offers will not be automatically responded to.

            Must be less at least 5% off the price_amount or the discount_price if the discount_price is set
            Up to 2 decimal places.
          example: "45.00"
        international_shipping_cost:
          type: string
          description: The cost of shipping the product internationally. Only set this if the product can be shipped internationally. Same currency as price_currency.
          example: "5.0"
        national_shipping_cost:
          type: string
          description: >-
            The cost of shipping the product nationally. Same currency as price_currency.
            If set to 0, the product has free shipping for buyers.

            **Important:** Either `national_shipping_cost` OR `depop_shipping` must be provided.
            If using Depop managed shipping, use `depop_shipping` instead and omit this field.
          example: "2.0"
        depop_shipping:
          allOf:
            - $ref: '#/components/schemas/DepopShippingRequest'
          description: >-
            Depop managed shipping configuration. When provided, Depop will handle the shipping logistics
            and automatically calculate the national shipping cost based on the selected provider and parcel size.

            **Important:** Either `depop_shipping` OR `national_shipping_cost` must be provided (but not both).
            If you provide `depop_shipping`, the `national_shipping_cost` will be automatically derived
            from the shipping provider's pricing.
        quantity:
          type: number
          description: The quantity of the product available for sale. Must be at least 1.
          example: 1
        pictures:
          type: array
          minItems: 1
          maxItems: 8
          items:
            $ref: '#/components/schemas/PublicPicture'
          description: >-
            Array of product images. Minimum 1 image is required, maximum 8 images allowed.
            The first image will be used as the main product image shown in search results.
          example:
            - url: "https://images.example.com/products/vintage-nike-tshirt-front.jpg"
            - url: "https://images.example.com/products/vintage-nike-tshirt-back.jpg"
            - url: "https://images.example.com/products/vintage-nike-tshirt-detail.jpg"
        department:
          type: string
          description: >-
            Top level category of the product.

            Currently we support: womenswear, menswear, kidswear and everything-else.
            These rarely change.

            For an up to date list, please make use of our taxonomy endpoint.
            Currently, in https://api.depop.com/api/v3/attributes/ under the key `department`.
          example: womenswear
        product_type:
          type: string
          description:
            The more specific category of the product.

            Note that there's an intermediate level between department and product type called "group".
            We don't need to receive this when an item is being listed but it's used in the apps/website to organize
            the product types.

            For example, in "menswear >> swim-beach-wear >> swimsuit-one-piece", we only need to know the department "menswear"
            and the product type "swimsuit-one-piece".

            For an up to date list, please make use of our taxonomy endpoint.
            Currently, in https://api.depop.com/api/v3/attributes/ under the key `group`.
          example: tshirts
        size_set_id:
          type: number
          description: >-
            The size set ID for the given Department and Product Type.

            This field is mandatory for product types that have a size set available.
          example: 2
        size_id:
          description: >-
            The size ID for a given size Set ID.

            This field is mandatory for product types that have a size set available.
          type: number
          example: 10
        condition:
          type: string
          anyOf:
            - type: string
              enum:
                - brand_new
                - used_like_new
                - used_excellent
                - used_good
                - used_fair
          example: brand_new
        colour:
          type: array
          items:
            type: string
          maxItems: 2
          description: >-
            Array of colours that apply to the product (maximum 2).

            Please refer to https://api.depop.com/api/v3/attributes/ for the full list of supported colours.
          example: [ "black", "white" ]
        style:
          type: array
          items:
            type: string
          description: >-
            Array of styles that apply to the product.

            Please refer to https://api.depop.com/api/v3/attributes/ for the full list of supported styles.
          example: [ "streetwear", "goth" ]
        age:
          type: array
          items:
            type: string
          description: >-
            Array of ages that apply to the product.

            Please refer to https://api.depop.com/api/v3/attributes/ for the full list of supported ages.
          example: [ "90s" ]
        source:
          type: array
          items:
            type: string
          description: >-
            Array of sources that apply to the product.

            Please refer to https://api.depop.com/api/v3/attributes/ for the full list of supported sources.
          example: [ "vintage" ]
        brand_name:
          type: string
          description: The brand name of the product, e.g. "Nike".
          example: Nike
        attributes:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Additional product type-specific attributes as a map of attribute IDs to arrays of attribute values.
            Each product_type has a set of optional attributes.
            To get the full list of supported attributes, please use our taxonomy endpoint: https://api.depop.com/api/v3/attributes/
          example:
            sleeve-length: [ "short" ]
            occasion: [ "wedding" ]
    CreateProductRequest:
      type: object
      required:
        - address
        - description
        - price_currency
        - price_amount
        - quantity
        - pictures
        - department
        - product_type
        - condition
        - brand_name
      properties:
        address:
          $ref: '#/components/schemas/Address'
        description:
          type: string
          description: >-
            A good description should contain key attribute information (brand, category, color, size, age etc),
            clarifying information about flaws, condition, fit, size and measurements.
            Commonly they end with hash tags (for example, \#summer).
            
            Constraints:
             * Limited to 1000 characters
             * Email addresses are not allowed
             * Can only have up to 5 hashtags (for example, \#summer).
          maxLength: 1000
          example: >-
            Women's Burgundy and Purple Vest
            
            Mauve and white striped tank top 
            Small mark at the bottom of the hem 
            
            #stripes #summer
        price_currency:
          type: string
          description: The currency code of the item's price.
          example: GBP
        price_amount:
          type: string
          description: The price of the item. Must be at least $1.00 or £1.00. Up to 2 decimal places.
          example: "50.99"
        auto_send_offer_price:
          type: string
          description: >-
            The price to automatically send to buyers who liked or have bagged the product.

            There's a fixed 1h delay before an offer is sent.

            If not set, the product will not automatically send offers.

            Must be less at least 5% off the price_amount.
            Up to 2 decimal places.

            **Note:** Requires `offers_write` OAuth scope.
          example: "45.00"
        auto_negotiate_offer_price:
          type: string
          description: >-
            The price to automatically respond with when a buyer sends an offer in this product:
             * If the buyer offer is higher or equal to this value, then the offer will be automatically accepted.
             * If the buyer offer is lower than this value, then the offer will be automatically countered with this price.

            If the buyer counters again, the same value will be used to counter the buyer's offer.

            If not set, the offers will not be automatically responded to.

            Must be less at least 5% off the price_amount.
            Up to 2 decimal places.

            **Note:** Requires `offers_write` OAuth scope.
          example: "45.00"
        international_shipping_cost:
          type: string
          description: The cost of shipping the product internationally. Only set this if the product can be shipped internationally. Same currency as price_currency.
          example: "5.0"
        national_shipping_cost:
          type: string
          description: >-
            The cost of shipping the product nationally. Same currency as price_currency.
            If set to 0, the product has free shipping for buyers.

            **Important:** Either `national_shipping_cost` OR `depop_shipping` must be provided.
            If using Depop managed shipping, use `depop_shipping` instead and omit this field.
          example: "2.0"
        depop_shipping:
          allOf:
            - $ref: '#/components/schemas/DepopShippingRequest'
          description: >-
            Depop managed shipping configuration. When provided, Depop will handle the shipping logistics
            and automatically calculate the national shipping cost based on the selected provider and parcel size.

            **Important:** Either `depop_shipping` OR `national_shipping_cost` must be provided (but not both).
            If you provide `depop_shipping`, the `national_shipping_cost` will be automatically derived
            from the shipping provider's pricing.
        quantity:
          type: number
          description: The quantity of the product available for sale. Must be at least 1.
          example: 1
        pictures:
          type: array
          minItems: 1
          maxItems: 8
          items:
            $ref: '#/components/schemas/PublicPicture'
          description: >-
            Array of product images. Minimum 1 image is required, maximum 8 images allowed.
            The first image will be used as the main product image shown in search results.
          example:
            - url: "https://images.example.com/products/vintage-nike-tshirt-front.jpg"
            - url: "https://images.example.com/products/vintage-nike-tshirt-back.jpg"
            - url: "https://images.example.com/products/vintage-nike-tshirt-detail.jpg"
        department:
          type: string
          description: >-
            Top level category of the product.

            Currently we support: womenswear, menswear, kidswear and everything-else.
            These rarely change.

            For an up to date list, please make use of our taxonomy endpoint.
            Currently, in https://api.depop.com/api/v3/attributes/ under the key `department`.
          example: womenswear
        product_type:
          type: string
          description:
            The more specific category of the product.

            Note that there's an intermediate level between department and product type called "group".
            We don't need to receive this when an item is being listed but it's used in the apps/website to organize
            the product types.

            For example, in "menswear >> swim-beach-wear >> swimsuit-one-piece", we only need to know the department "menswear"
            and the product type "swimsuit-one-piece".

            For an up to date list, please make use of our taxonomy endpoint.
            Currently, in https://api.depop.com/api/v3/attributes/ under the key `group`.
          example: tshirts
        size_set_id:
          type: number
          description: >-
            The size set ID for the given Department and Product Type.

            This field is mandatory for product types that have a size set available.
          example: 2
        size_id:
          description: >-
            The size ID for a given size Set ID.

            This field is mandatory for product types that have a size set available.
          type: number
          example: 10
        condition:
          type: string
          anyOf:
            - type: string
              enum:
                - brand_new
                - used_like_new
                - used_excellent
                - used_good
                - used_fair
          example: brand_new
        colour:
          type: array
          maxItems: 2
          items:
            type: string
            anyOf:
              - type: string
                enum:
                  - black
                  - grey
                  - white
                  - brown
                  - tan
                  - cream
                  - yellow
                  - red
                  - burgundy
                  - orange
                  - pink
                  - purple
                  - blue
                  - navy
                  - green
                  - khaki
                  - multi
                  - silver
                  - gold
          example:
            - black
            - white
        style:
          type: array
          maxItems: 3
          items:
            type: string
            anyOf:
              - type: string
                enum:
                  - streetwear
                  - sportswear
                  - loungewear
                  - goth
                  - retro
                  - boho
                  - western
                  - indie
                  - skater
                  - rave
                  - costume
                  - cosplay
                  - grunge
                  - emo
                  - minimalist
                  - preppy
                  - avant_garde
                  - punk
                  - glam
                  - regency
                  - casual
                  - techwear
                  - futuristic
                  - cottage
                  - fairy
                  - kidcore
                  - y2k
                  - biker
                  - gorpcore
                  - twee
                  - coquette
                  - whimsygoth
          example:
            - streetwear
            - goth
        age:
          type: array
          maxItems: 1
          items:
            type: string
            anyOf:
              - type: string
                enum:
                  - modern
                  - y2k
                  - 90s
                  - 80s
                  - 70s
                  - 60s
                  - 50s
                  - antique
          example:
            - 90s
        source:
          type: array
          maxItems: 2
          items:
            type: string
            anyOf:
              - type: string
                enum:
                  - vintage
                  - preloved
                  - reworked
                  - custom
                  - handmade
                  - deadstock
                  - designer
                  - repaired
          example:
            - vintage
        brand_name:
          type: string
          description: >-
            The brand name of the product. For example, "Nike".
            If your product does not have a brand, please send "unbranded" which will show to our users as "Other".
            
            Our API will perform the brand matching based on this field to find the most accurate brand representation.
            If no match is found, we will default to "unbranded".
          example: Nike
        attributes:
          type: object
          description: >-
            Additional attributes of the product.
            
            For an up to date list, please make use of our attributes endpoint.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            sleeve-length: [ 'short' ]
            occasion: [ 'wedding' ]
      example:
        address:
          country_code: "GB"
          state: "Greater London"
        description: "Vintage Nike T-Shirt in excellent condition.\nBlack with white swoosh logo on the front.\nSize medium, fits true to size.\nSmall mark on the left sleeve (see last image).\n\n#vintage #nike #streetwear #90s"
        price_currency: "GBP"
        price_amount: "25.99"
        auto_send_offer_price: "20.00"
        auto_negotiate_offer_price: "20.00"
        national_shipping_cost: "3.50"
        international_shipping_cost: "12.00"
        quantity: 1
        pictures:
          - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=cover-image"
          - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=back"
          - url: "https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg#type=tag"
        department: "menswear"
        product_type: "tshirts"
        size_set_id: 52
        size_id: 10
        condition: "used_excellent"
        colour:
          - "black"
          - "white"
        style:
          - "streetwear"
          - "retro"
          - "sportswear"
        age:
          - "90s"
        source:
          - "vintage"
          - "preloved"
        brand_name: "Nike"
        attributes:
          sleeve-length: [ "short" ]
          material: [ "cotton" ]
          occasion: [ "casual" ]
    PatchProductRequest:
      type: object
      properties:
        price_amount:
          type: string
          description: The price of the item. Must be at least $1.00 or £1.00. Up to 2 decimal places.
          example: "50.99"
        discount_price:
          type: string
          description: >-
            The discount price of the item.
            
            Must be less than the price_amount.
            Up to 2 decimal places.
          example: "48.00"
        auto_send_offer_price:
          type: string
          description: >-
            The price to automatically send to buyers who liked or have bagged the product.

            There's a fixed 1h delay before an offer is sent.

            If not set, the product will not automatically send offers.

            Must be less at least 5% off the price_amount or the discount_price if the discount_price is set.
            Up to 2 decimal places.
          example: "45.00"
        auto_negotiate_offer_price:
          type: string
          description: >-
            The price to automatically respond with when a buyer sends an offer in this product:
             * If the buyer offer is higher or equal to this value, then the offer will be automatically accepted.
             * If the buyer offer is lower than this value, then the offer will be automatically countered with this price.

            If the buyer counters again, the same value will be used to counter the buyer's offer.

            If not set, the offers will not be automatically responded to.

            Must be less at least 5% off the price_amount.
            Up to 2 decimal places.

            **Note:** Requires `offers_write` OAuth scope.
          example: "45.00"
        quantity:
          type: number
          description: The quantity of the product available for sale. Must be at least 1. (Use the marked as sold endpoint to reduce quantity to 0)
          example: 1
    Product:
      type: object
      properties:
        sku:
          type: string
          nullable: true
          description: SKU of the product. This field is optional and will be null if no SKU was assigned to the product.
          example: ABC-12345-S-BL
        product_id:
          type: number
          description: The id of the product.
          example: 123456789
        slug:
          type: string
          description: The URL-friendly slug of the product. Can be used to construct the product URL as `https://www.depop.com/products/{slug}/`.
          example: "vintage-nike-t-shirt-123456789"
        status:
          type: string
          description: The status of the product.
          anyOf:
            - type: string
              enum:
                - STATUS_ONSALE
                - STATUS_PURCHASED
                - STATUS_MARKED_AS_SOLD
                - STATUS_DELETED
                - STATUS_DELETED_ONSALE
                - STATUS_DELETED_PURCHASED
                - STATUS_DELETED_MARKED_AS_SOLD
                - STATUS_PRODUCT_BANNED_ONSALE
                - STATUS_USER_BANNED_ONSALE
                - STATUS_PRODUCT_BANNED_PURCHASED
                - STATUS_USER_BANNED_PURCHASED
          example: STATUS_ONSALE
        address:
          $ref: '#/components/schemas/Address'
        description:
          type: string
          description: >-
            A good description should contain key attribute information (brand, category, color, size, age etc),
            clarifying information about flaws, condition, fit, size and measurements.
            Commonly they end with hash tags (for example, \#summer).
            
            Constraints:
             * Limited to 1000 characters
             * Email addresses are not allowed
             * Can only have up to 5 hashtags (for example, \#summer).
          maxLength: 1000
          example: >-
            Women's Burgundy and Purple Vest

            Mauve and white striped tank top 
            Small mark at the bottom of the hem 

            #stripes #summer
        price_currency:
          type: string
          description: The currency code of the item's price.
          example: GBP
        price_amount:
          type: string
          description: The price of the item. Must be at least $1.00 or £1.00. Up to 2 decimal places.
          example: "50.99"
        auto_send_offer_price:
          type: string
          description: >-
            The price to automatically send to buyers who liked or have bagged the product.

            There's a fixed 1h delay before an offer is sent.

            If not set, the product will not automatically send offers.

            Must be less at least 5% off the price_amount.
            Up to 2 decimal places.

            **Note:** Requires `offers_read` OAuth scope to include this field in the response. If scope is not provided, this field will be omitted.
          example: "45.00"
        auto_negotiate_offer_price:
          type: string
          description: >-
            The price to automatically respond with when a buyer sends an offer in this product:
             * If the buyer offer is higher or equal to this value, then the offer will be automatically accepted.
             * If the buyer offer is lower than this value, then the offer will be automatically countered with this price.

            If the buyer counters again, the same value will be used to counter the buyer's offer.

            If not set, the offers will not be automatically responded to.

            Must be less at least 5% off the price_amount.
            Up to 2 decimal places.

            **Note:** Requires `offers_read` OAuth scope to include this field in the response. If scope is not provided, this field will be omitted.
          example: "45.00"
        international_shipping_cost:
          type: string
          description: The cost of shipping the product internationally. Only set this if the product can be shipped internationally. Same currency as price_currency.
          example: "5.0"
        national_shipping_cost:
          type: string
          description: >-
            The cost of shipping the product nationally. Same currency as price_currency.
            If set to 0, the product has free shipping for buyers.

            **Important:** Either `national_shipping_cost` OR `depop_shipping` must be provided.
            If using Depop managed shipping, use `depop_shipping` instead and omit this field.
          example: "2.0"
        depop_shipping:
          allOf:
            - $ref: '#/components/schemas/DepopShippingRequest'
          description: >-
            Depop managed shipping configuration. When provided, Depop will handle the shipping and
            automatically calculate the national shipping cost based on the selected provider and parcel size.

            **Important:** Either `depop_shipping` OR `national_shipping_cost` must be provided (but not both).
            If you provide `depop_shipping`, the `national_shipping_cost` will be automatically derived
            from the shipping provider's pricing.
          example:
              address_id: 123456
              shipping_provider_id: "USPS"
              parcel_size_id: "SMALL"
              payer: "buyer"
        quantity:
          type: number
          description: The quantity of the product available for sale. Must be at least 1.
          example: 1
        pictures:
          type: array
          minItems: 1
          maxItems: 8
          items:
            $ref: '#/components/schemas/Picture'
          example:
            - url: "https://images.example.com/products/vintage-nike-tshirt-front.jpg"
              height: 1280
              width: 1280
            - url: "https://images.example.com/products/vintage-nike-tshirt-back.jpg"
              height: 1280
              width: 1280
            - url: "https://images.example.com/products/vintage-nike-tshirt-detail.jpg"
              height: 1280
              width: 1280
        department:
          type: string
          description: >-
            Top level category of the product.

            Currently we support: womenswear, menswear, kidswear and everything-else.
            These rarely change.

            For an up to date list, please make use of our taxonomy endpoint.
            Currently, in https://api.depop.com/api/v3/attributes/ under the key `department`.
          example: womenswear
        product_type:
          type: string
          description:
            The more specific category of the product.

            Note that there's an intermediate level between department and product type called "group".
            We don't need to receive this when an item is being listed but it's used in the apps/website to organize
            the product types.

            For example, in "menswear >> swim-beach-wear >> swimsuit-one-piece", we only need to know the department "menswear"
            and the product type "swimsuit-one-piece".

            For an up to date list, please make use of our taxonomy endpoint.
            Currently, in https://api.depop.com/api/v3/attributes/ under the key `group`.
          example: tshirts
        size_set_id:
          type: number
          description: The size set ID for the given Department and Product Type.
          example: 2
        size_id:
          description: The size ID for a given size Set ID.
          type: number
          example: 10
        condition:
          type: string
          anyOf:
            - type: string
              enum:
                - brand_new
                - used_like_new
                - used_excellent
                - used_good
                - used_fair
          example: brand_new
        colour:
          type: array
          maxItems: 2
          items:
            type: string
            anyOf:
              - type: string
                enum:
                  - black
                  - grey
                  - white
                  - brown
                  - tan
                  - cream
                  - yellow
                  - red
                  - burgundy
                  - orange
                  - pink
                  - purple
                  - blue
                  - navy
                  - green
                  - khaki
                  - multi
                  - silver
                  - gold
          example:
            - black
            - white
        style:
          type: array
          maxItems: 3
          items:
            type: string
            anyOf:
              - type: string
                enum:
                  - streetwear
                  - sportswear
                  - loungewear
                  - goth
                  - retro
                  - boho
                  - western
                  - indie
                  - skater
                  - rave
                  - costume
                  - cosplay
                  - grunge
                  - emo
                  - minimalist
                  - preppy
                  - avant_garde
                  - punk
                  - glam
                  - regency
                  - casual
                  - techwear
                  - futuristic
                  - cottage
                  - fairy
                  - kidcore
                  - y2k
                  - biker
                  - gorpcore
                  - twee
                  - coquette
                  - whimsygoth
          example:
            - streetwear
            - goth
        age:
          type: array
          maxItems: 1
          items:
            type: string
            anyOf:
              - type: string
                enum:
                  - modern
                  - y2k
                  - 90s
                  - 80s
                  - 70s
                  - 60s
                  - 50s
                  - antique
          example:
            - 90s
        source:
          type: array
          maxItems: 2
          items:
            type: string
            anyOf:
              - type: string
                enum:
                  - vintage
                  - preloved
                  - reworked
                  - custom
                  - handmade
                  - deadstock
                  - designer
                  - repaired
          example:
            - vintage
        brand:
          type: string
          description: >-
            The brand name of the product. For example, "Nike".
          example: Nike
        attributes:
          type: object
          description: >-
            Additional attributes of the product.

            For an up to date list, please make use of our attributes endpoint.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            sleeve-length: [ 'short' ]
            occasion: [ 'wedding' ]
        created_at:
          type: string
          format: date-time
          description: The date and time when the product was created.
          example: "2025-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: The date and time when the product was last updated.
          example: "2025-01-01T00:00:00Z"
      required:
        - product_id
        - slug
        - status
        - address
        - description
        - price_currency
        - price_amount
        - quantity
        - pictures
        - department
        - product_type
        - colour
        - style
        - age
        - source
        - brand
        - attributes
        - created_at
        - updated_at
    MarkAsShippedRequest:
      type: object
      properties:
        tracking_number:
          type: string
          description: >-
            The tracking number of the shipment.
            
            If multiple tracking numbers are provided, they should be separated by commas without spaces.
          example: "GB1234567890GB,GB0987654321GB"
        carrier:
          type: string
          description: The carrier of the shipment.
          example: "Royal Mail"
      required:
        - tracking_number
        - carrier
    Address:
      type: object
      required:
        - country_code
      properties:
        country_code:
          type: string
          example: GB
        state:
          type: string
          description: The state/county of the product's address.
          example: Greater London
      example:
        country_code: GB
        state: Greater London
    SellerDetails:
      type: object
      required:
        - id
        - username
        - country_code
      properties:
        id:
          type: integer
          format: int64
          description: The unique identifier for the seller.
          example: 97082934
        username:
          type: string
          description: The Depop username of the seller.
          example: "good_will_charity"
        country_code:
          type: string
          description: The ISO 3166-1 alpha-2 country code of the seller.
          example: "US"
      example:
        id: 97082934
        username: "good_will_charity"
        country_code: "US"
    SellerAddress:
      type: object
      required:
        - id
        - name
        - address
        - city
        - state
        - postal_code
        - country
      properties:
        id:
          type: integer
          format: int64
          description: The unique identifier for the address.
          example: 123456
        name:
          type: string
          description: The name associated with the address.
          example: "John Doe"
        address:
          type: string
          description: The primary address line.
          example: "123 Main Street"
        address2:
          type: string
          nullable: true
          description: The secondary address line (optional).
          example: "Apt 4B"
        city:
          type: string
          description: The city of the address.
          example: "London"
        state:
          type: string
          description: The state or county of the address.
          example: "Greater London"
        postal_code:
          type: string
          description: The postal code or ZIP code of the address.
          example: "SW1A 1AA"
        country:
          type: string
          description: The ISO 3166-1 alpha-2 country code.
          example: "GB"
        last_modified:
          type: string
          nullable: true
          format: date-time
          description: The timestamp when the address was last modified (optional).
          example: "2025-01-15T10:30:00Z"
      example:
        id: 123456
        name: "John Doe"
        address: "123 Main Street"
        address2: "Apt 4B"
        city: "London"
        state: "Greater London"
        postal_code: "SW1A 1AA"
        country: "GB"
        last_modified: "2025-01-15T10:30:00Z"
    ShippingProviderInfo:
      type: object
      required:
        - id
        - parcel_sizes
      properties:
        id:
          type: string
          description: The unique identifier for the shipping provider.
          example: "USPS"
        parcel_sizes:
          type: array
          description: Available parcel sizes for this shipping provider.
          items:
            $ref: '#/components/schemas/ShippingParcelSize'
      example:
        id: "USPS"
        parcel_sizes:
          - id: "small"
            title: "Extra small"
            subtitle: "Under 8oz"
            cost:
              original_amount: "5.99"
              original_currency: "USD"
              amount: "5.00"
              currency: "USD"
            courier_service: "DROP_OFF"
    ShippingParcelSize:
      type: object
      required:
        - id
        - title
        - subtitle
        - cost
        - courier_service
      properties:
        id:
          type: string
          description: The unique identifier for the parcel size.
          example: "SMALL"
        title:
          type: string
          description: The display title for the parcel size.
          example: "Small parcel"
        subtitle:
          type: string
          description: Additional information about the parcel size (e.g., dimensions).
          example: "Up to 35 x 25 x 16cm"
        cost:
          $ref: '#/components/schemas/ShippingParcelCost'
        courier_service:
          type: string
          description: |
            The courier service type for this parcel size.

            - `DROP_OFF`: Seller drops off the parcel at a designated location
            - `COURIER_COLLECT`: Courier collects the parcel from the seller
            - `OTHER`: Other courier service types (reserved for future use)
          enum:
            - DROP_OFF
            - COURIER_COLLECT
            - OTHER
          example: "DROP_OFF"
      example:
        id: "small"
        title: "Extra small"
        subtitle: "Under 8oz"
        cost:
          original_amount: "5.99"
          original_currency: "USD"
          amount: "5.00"
          currency: "USD"
        courier_service: "DROP_OFF"
    ShippingParcelCost:
      type: object
      required:
        - original_amount
        - original_currency
        - amount
        - currency
      properties:
        original_amount:
          type: string
          description: The original cost amount before any conversions.
          example: "3.50"
        original_currency:
          type: string
          description: The original currency code.
          example: "GBP"
        amount:
          type: string
          description: The cost amount (may be converted to buyer's currency).
          example: "3.50"
        currency:
          type: string
          description: The currency code for the amount.
          example: "GBP"
      example:
        original_amount: "3.50"
        original_currency: "GBP"
        amount: "3.50"
        currency: "GBP"
    DepopShippingRequest:
      type: object
      required:
        - address_id
        - shipping_provider_id
        - parcel_size_id
        - payer
      properties:
        address_id:
          type: integer
          format: int64
          description: >-
            The ID of the seller address to ship from.

            This must be an address ID obtained from the `/api/v1/shop/seller-addresses/` endpoint.

            The address determines which shipping providers and parcel sizes are available.
          example: 123456
        shipping_provider_id:
          type: string
          description: >-
            The identifier for the shipping provider.

            This must be a provider ID returned from the
            `/api/v1/shop/seller-addresses/{address_id}/shipping-providers/` endpoint for the specified address.

            Common providers include: USPS, MY_HERMES (EVRI), SENDLE.
          example: "USPS"
        parcel_size_id:
          type: string
          description: >-
            The identifier for the parcel size.

            This must be a parcel size ID available for the specified shipping provider, obtained from the
            `/api/v1/shop/seller-addresses/{address_id}/shipping-providers/` endpoint.

            Common sizes include: SMALL, MEDIUM, LARGE, etc.
          example: "SMALL"
        payer:
          type: string
          description: >-
            Who pays for the shipping cost.

            - `buyer`: The buyer pays for shipping (shipping cost is added to the total price)
            - `seller`: The seller pays for shipping (free shipping for buyers)
          enum:
            - buyer
            - seller
          example: "buyer"
      example:
        address_id: 123456
        shipping_provider_id: "USPS"
        parcel_size_id: "SMALL"
        payer: "buyer"
    PublicPicture:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: >-
            Publicly accessible URL of the picture.
            
            Non-square images are also supported.
            
            Currently, we support JPG, WebP and PNG image formats.
          example: https://images.ctfassets.net/itoh30v6uh9a/3c1QQDGUAEHH9A76ovYSTA/1837e557daee3c763b6fbedd19785094/WW.jpg
    Picture:
      type: object
      required:
        - url
        - height
        - width
      properties:
        url:
          type: string
          description: URL of the picture.
          example: https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P0.jpg
        height:
          type: number
          example: 1280
        width:
          type: number
          example: 1280
    OrdersPage:
      type: object
      properties:
        meta:
          type: object
          properties:
            cursor:
              type: string
              example: "NDM0NjMyOTI5Njg3"
            has_more:
              type: boolean
              example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    Order:
      type: object
      required:
        - seller_id
        - purchase_id
        - status
        - currency
        - buyer_pays_amount
        - seller_receives_amount
        - buyer_shipping_price
        - buyer_address
        - line_items
        - seller_fee_breakdown
        - created_at
      properties:
        seller_id:
          type: number
          description: The seller's Depop user ID.
          example: 123456
        purchase_id:
          type: string
          description: Depop's internal purchase ID. Useful to be logged and to report any issues back to us.
          example: "123456"
        status:
          type: string
          description: The status of the order.
          anyOf:
            - type: string
              enum:
                - SHIPPING_PENDING
                - SHIPPED
                - REFUNDED
                - CANCELLED
                - COMPLETED
          example: SHIPPING_PENDING
        currency:
          type: string
          description: The currency code of the item's price.
          example: "GBP"
        buyer_pays_amount:
          type: string
          description: The final amount the buyer paid for the item. This includes the item price considering discounts and offers, shipping cost and any taxes we may need to collect.
          example: "50.99"
        seller_receives_amount:
          type: string
          description: The amount you'll receive after Depop's fees are deducted.
          example: "45.99"
        buyer_shipping_price:
          type: string
          description: The shipping price paid by the buyer.
          example: "5.00"
        buyer_address:
          $ref: '#/components/schemas/ShippingAddress'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItem'
        seller_fee_breakdown:
          type: array
          items:
            $ref: '#/components/schemas/FeeBreakdown'
        refund_summary:
          type: object
          required:
            - buyer_refund_amount
            - seller_refund_amount
            - refund_date
            - refunded_by
            - breakdown
          description: >-
            Summary of the refund for the order, if applicable.
            
            This will only be present if the order has been refunded.
          properties:
            buyer_refund_amount:
              type: string
              description: The amount refunded to the buyer.
              example: "12.99"
            seller_refund_amount:
              type: string
              description: The amount refunded to the seller.
              example: "1.00"
            refund_date:
              type: string
              format: date-time
              description: The date and time when the refund was processed.
              example: "2014-03-18T12:00:00Z"
            refunded_by:
              type: string
              description: >-
                Who triggered the refund. Can be either PARTNER or DEPOP.
                
                PARTNER indicates the refund was requested by a partner via the API, or in the Depop app.
                
                DEPOP indicates the refund was triggered by Depop, for example due to a dispute or if the order was auto-cancelled.
              enum:
                - PARTNER
                - DEPOP
              example: PARTNER
            breakdown:
              $ref: '#/components/schemas/TotalRefundBreakdown'
        created_at:
          type: string
          format: date-time
          description: The date and time when the order was created.
          example: "2025-01-01T12:00:00Z"
    TotalRefundBreakdown:
      type: object
      required:
        - refunded_to_buyer
        - refunded_to_seller
      properties:
        refunded_to_buyer:
          allOf:
            - $ref: '#/components/schemas/RefundedToBuyerRefunds'
          description: The breakdown of all amounts refunded to the buyer.
        refunded_to_seller:
          allOf:
            - $ref: '#/components/schemas/RefundedToSellerRefunds'
          description: The breakdown of all amounts refunded to the seller.
      example:
        refunded_to_buyer:
          item_refund_amount: "15.00"
          shipping_refund_amount: "3.00"
          depop_fee_refund_amount: "0.50"
        refunded_to_seller:
          ads_fee_refund_amount: "1.50"
          payment_fee_refund_amount: "0.80"
          depop_fee_refund_amount: "0.30"
    RefundedToBuyerRefunds:
      type: object
      properties:
        item_refund_amount:
          type: string
          description: The total amount of item price refunded to the buyer.
          example: "15.00"
        shipping_refund_amount:
          type: string
          description: The total amount of shipping price refunded to the buyer.
          example: "3.00"
        depop_fee_refund_amount:
          type: string
          description: The total amount of depop fee refunded to the buyer.
          example: "0.50"
      required:
        - item_refund_amount
        - shipping_refund_amount
        - depop_fee_refund_amount
      example:
        item_refund_amount: "15.00"
        shipping_refund_amount: "3.00"
        depop_fee_refund_amount: "0.50"
    RefundedToSellerRefunds:
      type: object
      properties:
        ads_fee_refund_amount:
          type: string
          description: The total amount of ads fee refunded to the seller.
          example: "2.50"
        payment_fee_refund_amount:
          type: string
          description: The total amount of payment fee refunded to the seller.
          example: "2.50"
        depop_fee_refund_amount:
          type: string
          description: The total amount of depop fee refunded to the seller.
          example: "0.00"
      required:
        - ads_fee_refund_amount
        - payment_fee_refund_amount
        - depop_fee_refund_amount
      example:
        ads_fee_refund_amount: "1.50"
        payment_fee_refund_amount: "0.80"
        depop_fee_refund_amount: "0.30"
    RefundedOrder:
      type: object
      required:
        - purchase_id
        - refunded_by
      properties:
        purchase_id:
          type: string
          description: Depop's internal purchase ID. Useful to be logged and to report any issues back to us.
          example: "123456"
        refunded_by:
          type: string
          description: >-
            Who triggered the refund. Can be either PARTNER or DEPOP.
            
            PARTNER indicates the refund was requested by a partner via the API, or in the Depop app.
            
            DEPOP indicates the refund was triggered by Depop, for example due to a dispute or if the order was auto-cancelled.
          enum:
            - PARTNER
            - DEPOP
          example: PARTNER
    OrderLineItem:
      type: object
      required: [ purchase_item_id, product_id, parcel_id, description, original_price, sold_price, sold_via_offers, image_url ]
      properties:
        purchase_item_id:
          type: number
          description: Depop's internal purchase line item ID. Useful to be logged and to report any issues back to us.
          example: 2385551
        sku:
          type: string
          nullable: true
          description: SKU of the product. This field is optional and will be null if no SKU was assigned to the product.
          example: "ABC-12345-S-BL"
        product_id:
          type: number
          description: Depop's internal product ID.
          example: 7021251
        parcel_id:
          type: string
          description: >-
            Depop's internal parcel ID.
            
            Note that multiple line items can share in the same parcel. This is currently true for all buyer orders with multiple items.
          example: "6e3538ca-6653-3c25-bf0a-a2be876b17e4"
        description:
          type: string
          description: The description of the product.
          example: "Product 403d667d-eb4d-49fd-aa10-18a54119d9fb created by the RestAssured automated test framework hashtags #vintage #rare #tee #grunge #y2k"
        original_price:
          type: string
          description: The original price of the product before any discounts or offers.
          example: "10.00"
        sold_price:
          type: string
          description: How much it sold for, which includes any discounts or negotiated offers.
          example: "5.00"
        sold_via_offers:
          type: boolean
          description: Whether the item was sold via an offer negotiation with the buyer.
          example: true
        image_url:
          type: string
          description: The URL of the first image of the product.
          example: "https://media-photos-staging.depop.com/r1/67655700/2147971983_93864b20a2ad4b78833cb92c2154810c/P0.jpg"
    FeeBreakdown:
      type: object
      required: [ fee_type, amount, currency ]
      properties:
        fee_type:
          type: string
          description: The type of fee.
          enum:
            - PAYMENT_FEE
            - BOOSTED_FEE
            - DEPOP_FEE
          example: "PAYMENT_FEE"
        amount:
          type: string
          description: The amount of the fee.
          example: "5.00"
        currency:
          type: string
          description: The currency.
          example: "GBP"
    ShippingAddress:
      required: [ city, postal_code, country_code ]
      type: object
      properties:
        name:
          type: string
          description: The name of the buyer.
          example: "John Doe"
        address:
          type: string
          description: The first line of the buyer's address.
          example: "123 Main St"
        address2:
          type: string
          description: The second line of the buyer's address.
          example: "Apt 1"
        city:
          type: string
          description: The city of the buyer's address.
          example: "Los Angeles"
        postal_code:
          type: string
          description: The postal code of the buyer's address.
          example: "90022-3049"
        state:
          type: string
          description: The state of the buyer's address.
          example: "CA"
        country_code:
          type: string
          description: The country code of the buyer's address.
          example: "US"
    PaginatedSellerAddressResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            cursor:
              type: string
              nullable: true
              example: null
            has_more:
              type: boolean
              example: false
        data:
          type: array
          items:
            $ref: '#/components/schemas/SellerAddress'
    Status:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          example: OK
          description: The status of the API.
    ErrorResponse:
      type: object
      properties:
        id:
          type: string
          example: 'a210923f-c1f3-4d84-a2bd-7f18c68553e2'
          description: A unique identifier for the error response.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
      example:
        id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
        errors:
          - code: "product_not_found"
            message: "Product (sku: womens-tshirt-1, id: 123) not found"
    ErrorItem:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: "missing_attribute"
          description: The error code.
        message:
          type: string
          example: Missing mandatory field
          description: The error message.
    Webhook:
      type: object
      required:
        - id
        - event_type
        - created_at
        - data
      properties:
        id:
          type: string
          description: The unique identifier of the webhook.
          example: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
        event_type:
          type: string
          description: The type of event that triggered the webhook.
          example: "v1:order.new"
        created_at:
          type: string
          format: date-time
          description: The date and time the webhook was created.
          example: "2025-01-01T00:00:00Z"
        data:
          description: The data of the webhook.
          oneOf:
            - $ref: '#/components/schemas/Order'
            - $ref: '#/components/schemas/RefundedOrder'
          example:
            seller_id: 123456
            purchase_id: "123456"
            status: "SHIPPING_PENDING"
            currency: "GBP"
            buyer_pays_amount: "50.99"
            seller_receives_amount: "45.99"
            buyer_shipping_price: "5.00"
            buyer_address:
              name: "John Doe"
              address: "123 Main St"
              address2: "Apt 1"
              city: "London"
              postal_code: "EC1V 4PW"
              state: "Greater London"
              country_code: "GB"
            line_items:
              - purchase_item_id: 2385551
                sku: "ABC-12345-S-BL"
                product_id: 7021251
                parcel_id: "6e3538ca-6653-3c25-bf0a-a2be876b17e4"
                description: "Vintage Nike T-Shirt in excellent condition. Black with white swoosh logo on the front."
                original_price: "24.99"
                sold_price: "19.99"
                sold_via_offers: true
                image_url: "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P0.jpg"
            seller_fee_breakdown:
              - fee_type: "DEPOP_FEE"
                amount: "3.00"
                currency: "GBP"
              - fee_type: "PAYMENT_FEE"
                amount: "2.00"
                currency: "GBP"
            created_at: "2025-01-01T12:00:00Z"
            refunded_by: "PARTNER"
    RefundOrderRequest:
      type: object
      properties:
        send_buyer_message:
          type: string
          description: The message to send to the buyer when processing the refund. This is optional but recommended.
          example: "Sorry for the inconvenience, we have processed your refund."
        items_refund_amount:
          type: string
          description: The amount to refund on the items in the order. Must be less than or equal to the total amount paid by the buyer.
          example: "50.99"
        shipping_refund_amount:
          type: string
          description: The amount to refund on the shipping in the order. Must be less than or equal to the total amount paid by the buyer.
          example: "4.99"
    SubmitOfferRequest:
      type: object
      description: Request body for submitting an offer on behalf of a seller to a buyer for a specific product.
      required:
        - offer_recipient_id
        - offer_value
        - offer_currency
      properties:
        offer_recipient_id:
          type: integer
          format: int64
          description: The user ID of the buyer who will receive the offer.
          example: 456789
        offer_value:
          type: number
          format: double
          description: The offer amount. Must be at least 5% lower than the product price_amount.
          example: 25.00
          minimum: 0.01
        offer_currency:
          type: string
          description: The currency code for the offer (e.g., GBP, USD, EUR). Must match the product's currency.
          example: "GBP"
          maxLength: 3
        size_id:
          type: integer
          format: int32
          description: >-
            The size ID for products with multiple sizes.

            - **Not required** for products without sizes or products with a single size
            - **Required** for products with multiple sizes
            - Must be a valid size ID that exists for the product
          example: 2
    OAuthTokenResponse:
      type: object
      description: Partner OAuth authentication response with access and refresh tokens for authorization code flow
      properties:
        access_token:
          type: string
          description: Partner access token with 1 hour expiry
          example: "pat_4eea1fdb98106005fea67ed65138df69afa0e6aa"
        refresh_token:
          type: string
          description: Partner refresh token with 1 year expiry
          example: "prt_26f4f74b761c83ef0d383bcfc419e114fd554331"
        expires_in:
          type: integer
          description: Access token expiry time in seconds (3600 = 1 hour)
          example: 3600
        token_type:
          type: string
          enum: [ Bearer ]
          example: "Bearer"
      required:
        - access_token
        - refresh_token
        - expires_in
    OAuthErrorResponse:
      type: object
      description: OAuth 2.0 error response from the clientauth service
      properties:
        code:
          type: integer
          description: HTTP status code
          example: 400
        error:
          type: string
          description: OAuth 2.0 error code
          example: "invalid_grant"
        message:
          type: string
          description: High-level error message
          example: "Depop OAuth2 error"
        detail:
          type: string
          description: Detailed error description
          example: "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client"
        error_message:
          type: string
          description: Error message (legacy field)
          example: "Depop OAuth2 error"
        error_description:
          type: string
          description: Error description (legacy field)
          example: "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client"
        id:
          type: string
          format: uuid
          description: Unique error identifier for tracking
          example: "550e8400-e29b-41d4-a716-446655440000"
      required:
        - code
        - error
        - message
        - id
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
            errors:
              - code: "bad-request"
                message: "invalid request"
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
            errors:
              - code: "unauthorized"
                message: "invalid api key"
    Forbidden:
      description: Forbidden - Insufficient scope
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
            errors:
              - code: "insufficient_scope"
                message: "Required scope: products_write"
    UnprocessableEntity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            id: "a210923f-c1f3-4d84-a2bd-7f18c68553e2"
            errors:
              - code: "validation"
                message: "Missing fields for request"
tags:
  - name: Authentication
    description: OAuth 2.0 authentication endpoints for partner integration
  - name: API status
    description: Everything needed to list a product on Depop
