openapi: 3.1.0 info: title: Seller API status Products 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 description: General product operations paths: /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. 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' 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' '422': $ref: '#/components/responses/ProductUnprocessableEntity' 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 - name: sort_by in: query description: Sort order for products by product ID. `id_desc` returns products in descending order (newest first), `id_asc` returns products in ascending order (oldest first). Default is `id_desc`. schema: type: string enum: - id_desc - id_asc default: id_desc example: id_desc - name: state in: query description: Filter products by state. `selling` returns products currently on sale, `sold` returns products that have been sold. When not provided, all products are returned regardless of state. `all` returns all products regardless of state. schema: type: string enum: - selling - sold - all example: selling 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' 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 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).\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 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' discount_price: type: string description: The discounted price of the item. When set, the original price will be shown crossed out and this price will be shown as the current price. Up to 2 decimal places. example: '24.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. 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 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/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 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 is_boosted: type: boolean description: 'Whether to boost the product. You don''t need to send this with `true` if you have a "boosted shop" or you''re part of the "free boost trial".' example: false 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 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