openapi: 3.1.0 info: title: Seller API status Products - By SKU 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: [] tags: - name: Products - By SKU description: Product operations using SKU (Stock Keeping Unit) identifiers paths: /api/v1/products/by-sku/{sku}/: put: tags: - Products - By SKU 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 For more information on Depop''s taxonomy, please refer to the [Concepts/Taxonomy](https://partnerapi.depop.com/api-docs/concepts/taxonomy/) documentation.' 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/ProductPutRequest' example: address: country_code: GB state: Greater London description: 'Vintage Nike T-Shirt in excellent condition. Black with white swoosh logo on the front. Size medium, fits true to size. Small mark on the left sleeve (see last image). #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 is_boosted: false 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' '422': $ref: '#/components/responses/ProductUnprocessableEntity' patch: tags: - Products - By SKU 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 - By SKU 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. Black with white swoosh logo on the front. Size medium, fits true to size. Small mark on the left sleeve (see last image). #vintage #nike #streetwear #90s' price_currency: GBP price_amount: '25.99' current_price: '24.00' 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 attributes: sleeve-length: - short material: - cotton occasion: - casual brand: Nike is_boosted: false source: - vintage - preloved created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T14:20:00Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' delete: tags: - Products - By SKU 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 - name: fail_if_active_offers in: query description: 'If set to `true`, the delete will fail with a 409 Conflict error if the product has any active offers. If set to `false` or omitted, the product will be deleted regardless of active offers. **Note:** This is a temporary flag until insights are available to help you manage active offers. If you plan to use this feature, please let us know so we can understand your use case and ensure a smooth transition when insights become available.' required: false schema: type: boolean default: false example: true responses: '200': description: Successful operation content: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: Conflict - Product has active offers content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: a210923f-c1f3-4d84-a2bd-7f18c68553e2 errors: - code: product_has_active_offers message: Product has active offers and cannot be deleted. /api/v1/products/by-sku/{sku}/mark-as-sold/: post: tags: - Products - By SKU 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/by-sku/{sku}/purchase/: post: tags: - Products - By SKU 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/by-sku/{sku}/offer/: post: tags: - Products - By SKU 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.0 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: d5423561-f416-4a17-b5e0-0141f91886c5 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: e6534670-a5b7-4c28-ae6f-1a52c02997d6 errors: - code: validation-error message: Product 7033001 does not have multiple sizes, a size ID must not be provided components: schemas: DepopShippingDetails: 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 Product: type: object properties: sku: type: - string - 'null' 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).\nConstraints:\n * Limited to 1000 characters\n * Email addresses are not allowed\n * Can only have up to 5 hashtags (for example, \\#summer)." maxLength: 1000 example: "Women's Burgundy and Purple Vest\nMauve and white striped tank top Small mark at the bottom of the hem \n#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' current_price: type: string description: The current effective price of the item, reflecting any active discount. Equal to price_amount when no discount is applied. example: '45.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:\n * If the buyer offer is higher or equal to this value, then the offer will be automatically accepted.\n * If the buyer offer is lower than this value, then the offer will be automatically countered with this price.\n\nIf the buyer counters again, the same value will be used to counter the buyer's offer.\nIf not set, the offers will not be automatically responded to.\nMust be less at least 5% off the price_amount. Up to 2 decimal places.\n**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/DepopShippingDetails' 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 - y2_k - 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 is_boosted: type: boolean description: Whether the product is currently boosted. example: false 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 - is_boosted - created_at - updated_at 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 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. 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 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 - 'null' 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 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:\n * If the buyer offer is higher or equal to this value, then the offer will be automatically accepted.\n * If the buyer offer is lower than this value, then the offer will be automatically countered with this price.\n\nIf the buyer counters again, the same value will be used to counter the buyer's offer.\nIf not set, the offers will not be automatically responded to.\nMust be less at least 5% off the price_amount. Up to 2 decimal places.\n**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 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' 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 ProductPutRequest: type: object required: - address - description - price_currency - price_amount - quantity - pictures - department - product_type - condition - brand_name - attributes 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).\nConstraints:\n * Limited to 1000 characters\n * Email addresses are not allowed\n * Can only have up to 5 hashtags (for example, \\#summer)." maxLength: 1000 example: "Women's Burgundy and Purple Vest\nMauve and white striped tank top Small mark at the bottom of the hem \n#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:\n * If the buyer offer is higher or equal to this value, then the offer will be automatically accepted.\n * If the buyer offer is lower than this value, then the offer will be automatically countered with this price.\n\nIf the buyer counters again, the same value will be used to counter the buyer's offer.\nIf not set, the offers will not be automatically responded to.\nMust be less at least 5% off the price_amount. Up to 2 decimal places.\n**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/DepopShippingDetails' 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.' 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/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 - y2_k - 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. **Required field:** Must be included in the request. Use an empty object `{}` if the product has no attributes. 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 is_boosted: type: boolean description: 'Whether to boost the product. For new products, you don''t need to send this with `true` if you have a "boosted shop" or you''re part of the "free boost trial". For existing products, when omitting, the current boost state is preserved. This is important as an explicit `false` will disable "boosted shop" feature or end the "free boost trial".' example: false example: address: country_code: GB state: Greater London description: 'Vintage Nike T-Shirt in excellent condition. Black with white swoosh logo on the front. Size medium, fits true to size. Small mark on the left sleeve (see last image). #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 is_boosted: false 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.0 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 responses: 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 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 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' ProductUnprocessableEntity: description: Unprocessable Entity - product validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: tooManyPictures: summary: Too many pictures provided value: id: a210923f-c1f3-4d84-a2bd-7f18c68553e2 errors: - code: too_many_pictures message: 'Failed to create or update product (sku: ABC-12345-S-BL) because too many pictures were provided. The maximum is 8 pictures.' invalidBrand: summary: Invalid brand name value: id: b320134g-d2g4-5e95-b3ce-8g29d79664f3 errors: - code: invalid_brand message: 'Failed to create or update product (sku: ABC-12345-S-BL) due to invalid brand. Please check the brand configuration.' invalidSize: summary: Invalid size configuration value: id: c431245h-e3h5-6f06-c4df-9h30e80775g4 errors: - code: invalid_size message: 'Failed to create or update product (sku: ABC-12345-S-BL) due to invalid size. Please check the size configuration.' invalidDescription: summary: Invalid description (too many hashtags) value: id: d5423561-f416-4a17-b5e0-0141f91886c5 errors: - code: invalid_description message: 'Failed to create or update product (sku: ABC-12345-S-BL) due to invalid description. Use a maximum of 5 hashtags and only tag the brand your item belongs to.' invalidCategory: summary: Invalid category (missing department/gender) value: id: e6534670-a5b7-4c28-ae6f-1a52c02997d6 errors: - code: invalid_department message: 'Failed to create or update product (sku: ABC-12345-S-BL) due to invalid category. Please ensure a valid department (gender) is provided.' manualShippingNotAllowed: summary: Manual shipping not allowed for user value: id: f7645780-a6b8-4c39-b7e1-2a63c13008d7 errors: - code: manual_shipping_not_allowed message: 'Failed to create or update product (sku: ABC-12345-S-BL) because manual shipping is not allowed for this user.' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API key