Seller API 1.0.0
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 listingsproducts_write- Required to create, update, or delete productsorders_read- Required to read order information and order historyorders_write- Required to mark orders as shipped or process refundsoffers_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
| Description | URL |
|---|---|
| https://partnerapi-staging.depop.com | https://partnerapi-staging.depop.com |
| https://partnerapi.depop.com | https://partnerapi.depop.com |
Products - By SKU
PUT /api/v1/products/by-sku/{sku}/
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
skudoes not exist, a new product listing will be created. -
Updating a listing: If the provided
skualready 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 documentation.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | 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. |
Request body
{
"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"
]
},
"is_boosted": false
}
Schema of the request body
{
"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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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.\n**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.\n**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.\nCurrently we support: womenswear, menswear, kidswear and everything-else. These rarely change.\nFor 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.\nNote 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.\nFor example, in \"menswear >> swim-beach-wear >> swimsuit-one-piece\", we only need to know the department \"menswear\" and the product type \"swimsuit-one-piece\".\nFor 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.\nThis 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.\nThis 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\".\nOur 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.\n**Required field:** Must be included in the request. Use an empty object `{}` if the product has no attributes.\nFor 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.\nFor 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\".\nFor 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.\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"
]
},
"is_boosted": false
}
}
Responses
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the response body
{
"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.\n- 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"
}
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
PATCH /api/v1/products/by-sku/{sku}/
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
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | SKU of the product. |
Request body
{
"price_amount": "39.99",
"discount_price": "37.00",
"auto_send_offer_price": "35.00",
"auto_negotiate_offer_price": "35.00"
}
Schema of the request body
{
"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.\nMust 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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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
}
}
}
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
GET /api/v1/products/by-sku/{sku}/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | The SKU of the product. |
Responses
{
"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",
"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"
}
Schema of the response body
{
"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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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.\n**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.\n**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.\nCurrently we support: womenswear, menswear, kidswear and everything-else. These rarely change.\nFor 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.\nNote 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.\nFor example, in \"menswear >> swim-beach-wear >> swimsuit-one-piece\", we only need to know the department \"menswear\" and the product type \"swimsuit-one-piece\".\nFor 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.\nFor 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"
]
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
DELETE /api/v1/products/by-sku/{sku}/
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
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
fail_if_active_offers |
query | boolean | False | No | 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. |
sku |
path | string | No | SKU of the product. |
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_has_active_offers",
"message": "Product has active offers and cannot be deleted."
}
]
}
Schema of the response body
{
"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"
}
]
}
}
POST /api/v1/products/by-sku/{sku}/mark-as-sold/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | SKU of the product. |
Responses
Refer to the common response description: BadRequest.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Refer to the common response description: Unauthorized.
POST /api/v1/products/by-sku/{sku}/purchase/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | SKU of the product. |
Responses
Refer to the common response description: BadRequest.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Refer to the common response description: Unauthorized.
POST /api/v1/products/by-sku/{sku}/offer/
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: Thesize_idwill be automatically populated - Products with multiple sizes: You must provide a validsize_idthat exists for the product
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | SKU of the product. |
Request body
Schema of the request body
{
"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.\n- **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
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "validation-error",
"message": "Offer currency GBP does not match product currency USD"
}
]
}
{
"id": "b320134g-d2g4-5e95-b3ce-8g29d79664f3",
"errors": [
{
"code": "validation-error",
"message": "Offer value must be at least 5% lower than the product price"
}
]
}
{
"id": "c431245h-e3h5-6f06-c4df-9h30e80775g4",
"errors": [
{
"code": "validation-error",
"message": "Size Id 99 does not exist for product 7033001"
}
]
}
{
"id": "d542356i-f4i6-7g17-d5eg-0i41f91886h5",
"errors": [
{
"code": "validation-error",
"message": "Product 7033001 has multiple sizes, a size ID must be provided"
}
]
}
{
"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"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Products
POST /api/v1/products/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
Request body
{
"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"
]
},
"is_boosted": false
}
Schema of the request body
{
"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.\nMust be unique. Can't be reused.\nThis 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\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"
},
"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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\nMust 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.\n**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.\n**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.\nCurrently we support: womenswear, menswear, kidswear and everything-else. These rarely change.\nFor 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.\nNote 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.\nFor example, in \"menswear >> swim-beach-wear >> swimsuit-one-piece\", we only need to know the department \"menswear\" and the product type \"swimsuit-one-piece\".\nFor 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.\nThis 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.\nThis 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).\nPlease 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.\nPlease 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.\nPlease 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.\nPlease 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.\nYou 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
}
}
}
Responses
Schema of the response body
{
"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.\n- 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"
}
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
GET /api/v1/products/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
cursor |
query | string | No | Request products created after this cursor. | |
limit |
query | integer | No | The number of products to return. Default is 20. |
Responses
{
"meta": {
"cursor": "NzIwODg1MXwyMDI1LTA2LTE3VDE2OjM3OjMwLjQ0ODI0NTU1NFp8MjQw",
"has_more": false
},
"data": []
}
Schema of the response body
{
"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": []
}
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
Products - By Product ID
GET /api/v1/products/by-product-id/{productId}/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
productId |
path | integer | No | The internal product ID of the product. |
Responses
{
"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",
"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"
}
Schema of the response body
{
"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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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.\n**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.\n**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.\nCurrently we support: womenswear, menswear, kidswear and everything-else. These rarely change.\nFor 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.\nNote 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.\nFor example, in \"menswear >> swim-beach-wear >> swimsuit-one-piece\", we only need to know the department \"menswear\" and the product type \"swimsuit-one-piece\".\nFor 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.\nFor 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"
]
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (id: 7033001) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
PUT /api/v1/products/by-product-id/{productId}/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
productId |
path | integer | No | The internal product ID of the product to update. |
Request body
{
"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"
]
},
"is_boosted": false
}
Schema of the request body
{
"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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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.\n**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.\n**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.\nCurrently we support: womenswear, menswear, kidswear and everything-else. These rarely change.\nFor 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.\nNote 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.\nFor example, in \"menswear >> swim-beach-wear >> swimsuit-one-piece\", we only need to know the department \"menswear\" and the product type \"swimsuit-one-piece\".\nFor 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.\nThis 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.\nThis 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\".\nOur 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.\n**Required field:** Must be included in the request. Use an empty object `{}` if the product has no attributes.\nFor 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.\nFor 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\".\nFor 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.\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"
]
},
"is_boosted": false
}
}
Responses
Schema of the response body
{
"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.\n- 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"
}
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (id: 7033001) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
PATCH /api/v1/products/by-product-id/{productId}/
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
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
productId |
path | integer | No | The internal product ID of the product to patch. |
Request body
{
"price_amount": "39.99",
"discount_price": "37.00",
"auto_send_offer_price": "35.00",
"auto_negotiate_offer_price": "35.00"
}
Schema of the request body
{
"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.\nMust 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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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
}
}
}
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (id: 7033001) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
DELETE /api/v1/products/by-product-id/{productId}/
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
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
fail_if_active_offers |
query | boolean | False | No | 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. |
productId |
path | integer | No | The internal product ID of the product to delete. |
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_has_active_offers",
"message": "Product has active offers and cannot be deleted."
}
]
}
Schema of the response body
{
"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"
}
]
}
}
POST /api/v1/products/by-product-id/{productId}/mark-as-sold/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
productId |
path | integer | No | The internal product ID of the product. |
Responses
Refer to the common response description: BadRequest.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (id: 7033001) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Refer to the common response description: Unauthorized.
POST /api/v1/products/by-product-id/{productId}/purchase/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
productId |
path | integer | No | The internal product ID of the product. |
Responses
Refer to the common response description: BadRequest.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Refer to the common response description: Unauthorized.
POST /api/v1/products/by-product-id/{productId}/offer/
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: Thesize_idwill be automatically populated if not provided - Products with multiple sizes: You must provide a validsize_idthat exists for the product
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
productId |
path | integer | No | The internal product ID of the product. |
Request body
Schema of the request body
{
"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.\n- **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
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "validation-error",
"message": "Offer currency GBP does not match product currency USD"
}
]
}
{
"id": "b320134g-d2g4-5e95-b3ce-8g29d79664f3",
"errors": [
{
"code": "validation-error",
"message": "Offer value must be at least 5% lower than the product price"
}
]
}
{
"id": "c431245h-e3h5-6f06-c4df-9h30e80775g4",
"errors": [
{
"code": "validation-error",
"message": "Size Id 99 does not exist for product 7033001"
}
]
}
{
"id": "d542356i-f4i6-7g17-d5eg-0i41f91886h5",
"errors": [
{
"code": "validation-error",
"message": "Product 7033001 has multiple sizes, a size ID must be provided"
}
]
}
{
"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"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Products - Legacy (Deprecated)
PUT /api/v1/products/{sku}/
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
skudoes not exist, a new product listing will be created. -
Updating a listing: If the provided
skualready 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 documentation.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | 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. |
Request body
{
"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"
]
},
"is_boosted": false
}
Schema of the request body
{
"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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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.\n**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.\n**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.\nCurrently we support: womenswear, menswear, kidswear and everything-else. These rarely change.\nFor 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.\nNote 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.\nFor example, in \"menswear >> swim-beach-wear >> swimsuit-one-piece\", we only need to know the department \"menswear\" and the product type \"swimsuit-one-piece\".\nFor 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.\nThis 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.\nThis 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\".\nOur 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.\n**Required field:** Must be included in the request. Use an empty object `{}` if the product has no attributes.\nFor 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.\nFor 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\".\nFor 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.\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"
]
},
"is_boosted": false
}
}
Responses
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the response body
{
"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.\n- 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"
}
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
PATCH /api/v1/products/{sku}/
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
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | SKU of the product. |
Request body
{
"price_amount": "39.99",
"auto_send_offer_price": "35.00",
"auto_negotiate_offer_price": "35.00"
}
Schema of the request body
{
"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.\nMust 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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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
}
}
}
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
GET /api/v1/products/{sku}/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | The SKU of the product. |
Responses
{
"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",
"current_price": "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"
],
"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"
}
Schema of the response body
{
"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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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.\n**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.\n**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.\nCurrently we support: womenswear, menswear, kidswear and everything-else. These rarely change.\nFor 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.\nNote 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.\nFor example, in \"menswear >> swim-beach-wear >> swimsuit-one-piece\", we only need to know the department \"menswear\" and the product type \"swimsuit-one-piece\".\nFor 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.\nFor 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"
]
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
DELETE /api/v1/products/{sku}/
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
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
fail_if_active_offers |
query | boolean | False | No | 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. |
sku |
path | string | No | SKU of the product. |
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_has_active_offers",
"message": "Product has active offers and cannot be deleted."
}
]
}
Schema of the response body
{
"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"
}
]
}
}
POST /api/v1/products/{sku}/mark-as-sold/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | SKU of the product. |
Responses
Refer to the common response description: BadRequest.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Refer to the common response description: Unauthorized.
POST /api/v1/products/{sku}/purchase/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
sku |
path | string | No | SKU of the product. |
Responses
Refer to the common response description: BadRequest.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Refer to the common response description: Unauthorized.
Products - By Slug
GET /api/v1/products/by-slug/{slug}/
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).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
slug |
path | string | No | The slug of the product. |
Responses
{
"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",
"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
}
],
"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"
}
Schema of the response body
{
"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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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.\n**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.\n**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.\nCurrently we support: womenswear, menswear, kidswear and everything-else. These rarely change.\nFor 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.\nNote 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.\nFor example, in \"menswear >> swim-beach-wear >> swimsuit-one-piece\", we only need to know the department \"menswear\" and the product type \"swimsuit-one-piece\".\nFor 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.\nFor 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"
]
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (slug: vintage-nike-t-shirt-7033001) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
PUT /api/v1/products/by-slug/{slug}/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
slug |
path | string | No | The slug of the product to update. |
Request body
{
"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"
]
},
"is_boosted": false
}
Schema of the request body
{
"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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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.\n**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.\n**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.\nCurrently we support: womenswear, menswear, kidswear and everything-else. These rarely change.\nFor 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.\nNote 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.\nFor example, in \"menswear >> swim-beach-wear >> swimsuit-one-piece\", we only need to know the department \"menswear\" and the product type \"swimsuit-one-piece\".\nFor 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.\nThis 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.\nThis 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\".\nOur 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.\n**Required field:** Must be included in the request. Use an empty object `{}` if the product has no attributes.\nFor 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.\nFor 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\".\nFor 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.\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"
]
},
"is_boosted": false
}
}
Responses
Schema of the response body
{
"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.\n- 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"
}
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (slug: vintage-nike-t-shirt-7033001) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
PATCH /api/v1/products/by-slug/{slug}/
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
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
slug |
path | string | No | The slug of the product to patch. |
Request body
{
"price_amount": "39.99",
"discount_price": "37.00",
"auto_send_offer_price": "35.00",
"auto_negotiate_offer_price": "35.00"
}
Schema of the request body
{
"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.\nMust 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.\nThere's a fixed 1h delay before an offer is sent.\nIf not set, the product will not automatically send offers.\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"
},
"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
}
}
}
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (slug: vintage-nike-t-shirt-7033001) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
DELETE /api/v1/products/by-slug/{slug}/
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
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
fail_if_active_offers |
query | boolean | False | No | 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. |
slug |
path | string | No | The slug of the product to delete. |
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_has_active_offers",
"message": "Product has active offers and cannot be deleted."
}
]
}
Schema of the response body
{
"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"
}
]
}
}
POST /api/v1/products/by-slug/{slug}/mark-as-sold/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
slug |
path | string | No | The slug of the product. |
Responses
Refer to the common response description: BadRequest.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (slug: vintage-nike-t-shirt-7033001) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Refer to the common response description: Unauthorized.
POST /api/v1/products/by-slug/{slug}/offer/
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: Thesize_idwill be automatically populated if not provided - Products with multiple sizes: You must provide a validsize_idthat exists for the product
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
slug |
path | string | No | The slug of the product. |
Request body
Schema of the request body
{
"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.\n- **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
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "validation-error",
"message": "Offer currency GBP does not match product currency USD"
}
]
}
{
"id": "b320134g-d2g4-5e95-b3ce-8g29d79664f3",
"errors": [
{
"code": "validation-error",
"message": "Offer value must be at least 5% lower than the product price"
}
]
}
{
"id": "c431245h-e3h5-6f06-c4df-9h30e80775g4",
"errors": [
{
"code": "validation-error",
"message": "Size Id 99 does not exist for product vintage-nike-t-shirt-7033001"
}
]
}
{
"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"
}
]
}
{
"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"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Pricing Inspiration
POST /api/v1/pricing/inspiration/
Get pricing inspiration when given product listing details
Description
This endpoint returns a price prediction range and a list of similar sold items for a product listing. This endpoint does not require OAuth Scopes and is only valid for specific countries (US and GB).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
Request body
{
"description": "A sporty nike t-shirt with abstract patterns",
"country": "GB",
"currency": "GBP",
"product_type": "t-shirts",
"department": "menswear",
"condition": "used_like_new",
"brand_name": "Nike",
"size_set_id": "52",
"size_id": "4",
"colour": [
"black",
"white"
],
"style": [
"casual",
"sportswear"
],
"source": [
"vintage"
]
}
Schema of the request body
{
"title": "PricingInspirationRequest",
"required": [
"description",
"country",
"currency",
"product_type",
"department",
"condition",
"brand_name"
],
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "A detailed description of the product. The more detail the better the prediction",
"example": "A sporty nike t-shirt with abstract patterns"
},
"country": {
"type": "string",
"description": "The country the product is listed in.",
"example": "GB"
},
"currency": {
"type": "string",
"description": "The currency code for the listing.",
"example": "GBP"
},
"product_type": {
"type": "string",
"description": "The type of product. Find out more in the taxonomy section of the API docs.",
"example": "t-shirts"
},
"department": {
"type": "string",
"description": "The product department. Find out more in the taxonomy section of the API docs.",
"example": "menswear"
},
"condition": {
"type": "string",
"description": "The condition of the product. Find out more in the taxonomy section of the API docs.",
"example": "used_like_new"
},
"brand_name": {
"type": "string",
"description": "The canonical brand name of the product.",
"example": "Nike"
},
"size_set_id": {
"type": "string",
"description": "The size set ID for the given Department and Product Type.",
"example": "52"
},
"size_id": {
"type": "string",
"description": "The size identifier.",
"example": "4"
},
"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"
]
}
]
},
"description": "List of colours for the product.",
"example": [
"black",
"white"
]
},
"style": {
"type": "array",
"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"
]
}
]
},
"description": "List of styles for the product.",
"example": [
"casual",
"sportswear"
]
},
"source": {
"type": "array",
"maxItems": 2,
"items": {
"type": "string",
"anyOf": [
{
"type": "string",
"enum": [
"vintage",
"preloved",
"reworked",
"custom",
"handmade",
"deadstock",
"designer",
"repaired"
]
}
]
},
"example": [
"vintage"
]
}
}
}
Responses
{
"price_prediction": {
"lower_bound": "17.00",
"prediction": "19.00",
"upper_bound": "22.00"
},
"similar_sold_items": [
{
"brand_name": "Nike",
"condition": "used_excellent",
"picture": {
"height": 1280,
"url": "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P0.jpg",
"width": 1280
},
"product_slug": "nice-t-shirt-1a3",
"sold_price_amount": "50.00",
"sold_price_currency": "GBP"
}
]
}
Schema of the response body
{
"title": "PricingInspirationResponse",
"type": "object",
"required": [
"price_prediction",
"similar_sold_items"
],
"properties": {
"price_prediction": {
"$ref": "#/components/schemas/PricePrediction"
},
"similar_sold_items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SimilarSoldItem"
},
"example": [
{
"brand_name": "Nike",
"condition": "used_excellent",
"picture": {
"height": 1280,
"url": "https://media-photos-staging.depop.com/b0/18220/5612584_b6795bc34778465293e45647518906d6/P0.jpg",
"width": 1280
},
"product_slug": "nice-t-shirt-1a3",
"sold_price_amount": "50.00",
"sold_price_currency": "GBP"
}
]
}
}
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
{
"unsupportedCountry": {
"summary": "Unsupported country",
"value": {
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "unsupported_country",
"message": "Country 'AU' is not supported. Supported countries: GB, US"
}
]
}
}
}
Schema of the response body
{
"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"
}
]
}
}
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Orders
GET /api/v1/orders/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
cursor |
query | string | No | The cursor to start from. This is the ID of the last purchase order ID returned in the previous request. | |
from |
query | string | No | The start date of the orders to return. | |
limit |
query | integer | No | The number of orders to return. Default is 20. | |
to |
query | string | No | The end date of the orders to return. |
Responses
Schema of the response body
{
"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"
},
"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_tax_amount": "3.24",
"buyer_address": {
"name": "John Doe",
"address": "123 Main St",
"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,
"slug": "vintage-nike-t-shirt-7021251",
"parcel_id": "6e3538ca-6653-3c25-bf0a-a2be876b17e4",
"description": "Vintage Nike T-Shirt",
"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"
}
],
"created_at": "2025-01-01T00:00:00Z"
}
]
}
}
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
GET /api/v1/orders/{purchase_id}/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
purchase_id |
path | string | No | The purchase ID of the order. |
Responses
{
"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_tax_amount": "3.24",
"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,
"slug": "vintage-nike-t-shirt-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"
},
{
"fee_type": "SHIPPING_FEE",
"amount": "0.00",
"currency": "GBP"
}
],
"created_at": "2025-01-01T12:00:00Z"
}
Schema of the response body
{
"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_tax_amount": {
"type": "string",
"description": "The tax amount paid by the buyer. This will only be present if tax was collected for the order.",
"example": "3.24"
},
"buyer_address": {
"$ref": "#/components/schemas/ShippingAddress"
},
"line_items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderLineItem"
},
"example": [
{
"purchase_item_id": 2385551,
"sku": "ABC-12345-S-BL",
"product_id": 7021251,
"slug": "vintage-nike-t-shirt-7021251",
"parcel_id": "6e3538ca-6653-3c25-bf0a-a2be876b17e4",
"description": "Vintage Nike T-Shirt in excellent condition",
"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": {
"type": "array",
"description": "Breakdown of all fees charged to the seller for this order.",
"items": {
"$ref": "#/components/schemas/FeeBreakdown"
},
"example": [
{
"fee_type": "DEPOP_FEE",
"amount": "3.00",
"currency": "GBP"
},
{
"fee_type": "PAYMENT_FEE",
"amount": "2.00",
"currency": "GBP"
}
]
},
"depop_shipping": {
"allOf": [
{
"$ref": "#/components/schemas/DepopShippingResponse"
}
],
"description": "Depop managed shipping information for this order, if applicable.\nThis field will only be present if the product was listed with Depop managed shipping.",
"example": {
"shipping_provider_id": "USPS"
}
},
"refund_summary": {
"type": "object",
"required": [
"buyer_refund_amount",
"refund_date",
"refunded_by",
"breakdown"
],
"description": "Summary of the refund for the order, if applicable.\nThis 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",
"deprecated": true,
"description": "**DEPRECATED**: This field currently returns incorrect values and should not be relied upon. Please use `breakdown.refunded_to_seller` for accurate seller refund information.",
"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.\nPARTNER indicates the refund was requested by a partner via the API, or in the Depop app.\nDEPOP 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"
}
}
}
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "product_not_found",
"message": "Product (sku: womens-tshirt-1, id: 123) not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
POST /api/v1/orders/{purchase_id}/parcels/{parcel_id}/mark-as-shipped/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
parcel_id |
path | string | No | The parcel ID of the order. | |
purchase_id |
path | string | No | The purchase ID of the order. |
Request body
Schema of the request body
{
"type": "object",
"properties": {
"tracking_number": {
"type": "string",
"description": "The tracking number of the shipment.\nIf 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"
]
}
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
POST /api/v1/orders/{purchase_id}/refund/
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.
Important note about shipping refunds with Depop shipping:
- For orders using Depop shipping (where a Depop shipping label was used), shipping can only be refunded as part of a full refund. You cannot do a partial refund that includes shipping costs for these orders.
- For orders with manual shipping, shipping can be refunded with either full or partial refunds.
- To determine if an order uses Depop shipping, check if the depop_shipping field is present in the order response.
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).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
purchase_id |
path | string | No | The purchase ID of the order. |
Request body
{
"items_refund_amount": "50.99",
"shipping_refund_amount": "4.99",
"send_buyer_message": "Your order has been refunded. We apologize for the inconvenience."
}
Schema of the request body
{
"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 shipping price (buyer or seller paid).\n\n**Important:** For orders with Depop shipping (where `depop_shipping` is present), shipping can only be refunded as part of a full refund. Partial refunds cannot include shipping for these orders.\n\nFor orders with manual shipping, shipping can be refunded with either full or partial refunds.",
"example": "4.99"
}
}
}
Responses
Refer to the common response description: BadRequest.
Refer to the common response description: Unauthorized.
Refer to the common response description: Forbidden.
{
"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."
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Shop Management
GET /api/v1/shop/
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
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
Responses
Schema of the response body
{
"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"
}
}
Refer to the common response description: Unauthorized.
{
"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"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
GET /api/v1/shop/seller-addresses/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
Responses
{
"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"
}
]
}
Schema of the response body
{
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"type": "object",
"required": [
"has_more"
],
"properties": {
"cursor": {
"type": [
"string",
"null"
],
"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": []
}
}
}
Refer to the common response description: Unauthorized.
{
"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"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
GET /api/v1/shop/seller-addresses/{address_id}/shipping-providers/
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
address_id |
path | integer | No | The ID of the seller address. |
Responses
[
{
"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"
}
]
}
]
Refer to the common response description: Unauthorized.
{
"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"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "address_not_found",
"message": "Address with ID 999999 not found"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Docs
GET /api-docs/openapi.yaml
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.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
Responses
Authentication
POST /api/v1/oauth2/access-token/
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).
Request body
{
"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"
}
{
"grant_type": "refresh_token",
"refresh_token": "prt_26f4f74b761c83ef0d383bcfc419e114fd554331",
"client_id": "a1b2c3d4e5f6g7h8i9j0",
"client_secret": "client_secret_abc123"
}
Schema of the request body
{
"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.\nRequired for all authorization code flows (PKCE is mandatory).\nMust be 43-128 characters long and contain only [A-Za-z0-9._~-] characters.\nNot used for refresh_token grant.\n",
"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"
]
}
Responses
{
"access_token": "pat_4eea1fdb98106005fea67ed65138df69afa0e6aa",
"refresh_token": "prt_26f4f74b761c83ef0d383bcfc419e114fd554331",
"expires_in": 3600,
"token_type": "Bearer"
}
Schema of the response body
{
"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"
]
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
Schema of the response body
{
"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"
]
}
{
"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"
}
Schema of the response body
{
"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"
]
}
API status
GET /status
Get status
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".
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
BearerAuth |
header | string | N/A | No | JWT Bearer token |
Responses
Webhooks
WEBHOOK newOrder
v1:order.new New order webhook
Description
This webhook is sent whenever a new order is placed on Depop. The webhook will contain the details of the order, including the buyer's address and the items purchased. You can use this webhook to update your inventory and other platforms that the item is no longer available. Please make sure you're using the orders endpoint to reconcile the orders you have received via webhooks, as these will have a best effort delivery.
Request body
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"event_type": "v1:order.new",
"created_at": "2025-01-01T00:00:00Z",
"data": {
"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_tax_amount": "3.24",
"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,
"slug": "vintage-nike-t-shirt-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"
},
{
"fee_type": "SHIPPING_FEE",
"amount": "0.00",
"currency": "GBP"
}
],
"created_at": "2025-01-01T00:00:00Z"
}
}
Schema of the request body
{
"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"
},
{
"$ref": "#/components/schemas/ProductLike"
}
]
}
}
}
WEBHOOK orderRefunded
v1:order.refund Order refunded webhook
Description
This webhook is sent whenever an order is refunded on Depop. The webhook will contain the details of the refund, including who refunded (either PARTNER or DEPOP) and the purchase id for the order.
Request body
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"event_type": "v1:order.refund",
"created_at": "2025-01-01T00:00:00Z",
"data": {
"purchase_id": "123456",
"refunded_by": "PARTNER"
}
}
Schema of the request body
{
"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"
},
{
"$ref": "#/components/schemas/ProductLike"
}
]
}
}
}
WEBHOOK productLiked
v1:product.like Product liked webhook
Description
This webhook is sent whenever a user likes a product. You can use this webhook to track engagement with your products and identify which items are popular with buyers.
Request body
{
"id": "b320934f-d2g4-5e95-b3ce-8g29d79664f3",
"event_type": "v1:product.like",
"created_at": "2025-01-01T00:00:00Z",
"data": {
"seller_id": 123456,
"product_id": 7021251,
"sku": "ABC-12345-S-BL",
"slug": "vintage-nike-t-shirt-7021251",
"liker_id": 789012
}
}
Schema of the request body
{
"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"
},
{
"$ref": "#/components/schemas/ProductLike"
}
]
}
}
}
WEBHOOK productUnliked
v1:product.unlike Product unliked webhook
Description
This webhook is sent whenever a user unlikes a product.
Request body
{
"id": "c431045g-e3h5-6f06-c4df-9h30e80775g4",
"event_type": "v1:product.unlike",
"created_at": "2025-01-01T00:00:00Z",
"data": {
"seller_id": 123456,
"product_id": 7021251,
"sku": "ABC-12345-S-BL",
"slug": "vintage-nike-t-shirt-7021251",
"liker_id": 789012
}
}
Schema of the request body
{
"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"
},
{
"$ref": "#/components/schemas/ProductLike"
}
]
}
}
}
Schemas
Address
| Name | Type | Description |
|---|---|---|
country_code |
string | |
state |
string | The state/county of the product's address. |
DepopShippingDetails
| Name | Type | Description |
|---|---|---|
address_id |
integer(int64) | 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. |
parcel_size_id |
string | 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. |
payer |
string | 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) |
shipping_provider_id |
string | 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. |
DepopShippingResponse
| Name | Type | Description |
|---|---|---|
shipping_provider_id |
string | The identifier for the shipping provider used for this order. Common providers include: USPS, MY_HERMES (EVRI), SENDLE. |
ErrorItem
| Name | Type | Description |
|---|---|---|
code |
string | The error code. |
message |
string | The error message. |
ErrorResponse
| Name | Type | Description |
|---|---|---|
errors |
Array<ErrorItem> | |
id |
string | A unique identifier for the error response. |
FeeBreakdown
| Name | Type | Description |
|---|---|---|
amount |
string | The amount of the fee. |
currency |
string | The currency. |
fee_type |
string | The type of fee charged to the seller: - `PAYMENT_FEE`: Payment processing fee - `DEPOP_FEE`: Depop marketplace fee - `BOOSTED_FEE`: Fee for boosted listings (optional) - `SHIPPING_FEE`: Depop Shipping label cost when seller pays for shipping. This will be 0.00 when the buyer pays for shipping label. |
MarkAsShippedRequest
| Name | Type | Description |
|---|---|---|
carrier |
string | The carrier of the shipment. |
tracking_number |
string | The tracking number of the shipment. If multiple tracking numbers are provided, they should be separated by commas without spaces. |
OAuthErrorResponse
| Name | Type | Description |
|---|---|---|
code |
integer | HTTP status code |
detail |
string | Detailed error description |
error |
string | OAuth 2.0 error code |
error_description |
string | Error description (legacy field) |
error_message |
string | Error message (legacy field) |
id |
string(uuid) | Unique error identifier for tracking |
message |
string | High-level error message |
OAuthTokenResponse
| Name | Type | Description |
|---|---|---|
access_token |
string | Partner access token with 1 hour expiry |
expires_in |
integer | Access token expiry time in seconds (3600 = 1 hour) |
refresh_token |
string | Partner refresh token with 1 year expiry |
token_type |
string |
Order
| Name | Type | Description |
|---|---|---|
buyer_address |
ShippingAddress | |
buyer_pays_amount |
string | 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. |
buyer_shipping_price |
string | The shipping price paid by the buyer. |
buyer_tax_amount |
string | The tax amount paid by the buyer. This will only be present if tax was collected for the order. |
created_at |
string(date-time) | The date and time when the order was created. |
currency |
string | The currency code of the item's price. |
depop_shipping |
Depop managed shipping information for this order, if applicable. This field will only be present if the product was listed with Depop managed shipping. | |
line_items |
Array<OrderLineItem> | |
purchase_id |
string | Depop's internal purchase ID. Useful to be logged and to report any issues back to us. |
refund_summary |
Properties: buyer_refund_amount, seller_refund_amount, refund_date, refunded_by, breakdown |
Summary of the refund for the order, if applicable. This will only be present if the order has been refunded. |
seller_fee_breakdown |
Array<FeeBreakdown> | Breakdown of all fees charged to the seller for this order. |
seller_id |
number | The seller's Depop user ID. |
seller_receives_amount |
string | The amount you'll receive after Depop's fees are deducted. |
status |
string | The status of the order. |
OrderLineItem
| Name | Type | Description |
|---|---|---|
description |
string | The description of the product. |
image_url |
string | The URL of the first image of the product. |
original_price |
string | The original price of the product before any discounts or offers. |
parcel_id |
string | 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. |
product_id |
number | Depop's internal product ID. |
purchase_item_id |
number | Depop's internal purchase line item ID. Useful to be logged and to report any issues back to us. |
sku |
string | null | SKU of the product. This field is optional and will be null if no SKU was assigned to the product. |
slug |
string | The unique slug identifier for the product on Depop. |
sold_price |
string | How much it sold for, which includes any discounts or negotiated offers. |
sold_via_offers |
boolean | Whether the item was sold via an offer negotiation with the buyer. |
OrdersPage
| Name | Type | Description |
|---|---|---|
data |
Array<Order> | |
meta |
Properties: cursor, has_more |
PaginatedSellerAddressResponse
| Name | Type | Description |
|---|---|---|
data |
Array<SellerAddress> | |
meta |
Properties: cursor, has_more |
PatchProductRequest
| Name | Type | Description |
|---|---|---|
auto_negotiate_offer_price |
string | 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. |
auto_send_offer_price |
string | 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. |
discount_price |
string | The discount price of the item. Must be less than the price_amount. Up to 2 decimal places. |
price_amount |
string | The price of the item. Must be at least $1.00 or £1.00. Up to 2 decimal places. |
quantity |
number | The quantity of the product available for sale. Must be at least 1. (Use the marked as sold endpoint to reduce quantity to 0) |
Picture
| Name | Type | Description |
|---|---|---|
height |
number | |
url |
string | URL of the picture. |
width |
number |
PricePrediction
| Name | Type | Description |
|---|---|---|
lower_bound |
string | The lower bound of the predicted price range. |
prediction |
string | The predicted price for the product. |
upper_bound |
string | The upper bound of the predicted price range. |
PricingInspirationRequest
| Name | Type | Description |
|---|---|---|
brand_name |
string | The canonical brand name of the product. |
colour |
Array<string> | List of colours for the product. |
condition |
string | The condition of the product. Find out more in the taxonomy section of the API docs. |
country |
string | The country the product is listed in. |
currency |
string | The currency code for the listing. |
department |
string | The product department. Find out more in the taxonomy section of the API docs. |
description |
string | A detailed description of the product. The more detail the better the prediction |
product_type |
string | The type of product. Find out more in the taxonomy section of the API docs. |
size_id |
string | The size identifier. |
size_set_id |
string | The size set ID for the given Department and Product Type. |
source |
Array<string> | |
style |
Array<string> | List of styles for the product. |
PricingInspirationResponse
| Name | Type | Description |
|---|---|---|
price_prediction |
PricePrediction | |
similar_sold_items |
Array<SimilarSoldItem> |
Product
| Name | Type | Description |
|---|---|---|
address |
Address | |
age |
Array<string> | |
attributes |
Example: {'sleeve-length': ['short'], 'occasion': ['wedding']} |
Additional attributes of the product. For an up to date list, please make use of our attributes endpoint. |
auto_negotiate_offer_price |
string | 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. |
auto_send_offer_price |
string | 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. |
brand |
string | The brand name of the product. For example, "Nike". |
colour |
Array<string> | |
condition |
string | |
created_at |
string(date-time) | The date and time when the product was created. |
current_price |
string | The current effective price of the item, reflecting any active discount. Equal to price_amount when no discount is applied. |
department |
string | 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`. |
depop_shipping |
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. | |
description |
string | 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). |
international_shipping_cost |
string | The cost of shipping the product internationally. Only set this if the product can be shipped internationally. Same currency as price_currency. |
is_boosted |
boolean | Whether the product is currently boosted. |
national_shipping_cost |
string | 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. |
pictures |
Array<Picture> | |
price_amount |
string | The price of the item. Must be at least $1.00 or £1.00. Up to 2 decimal places. |
price_currency |
string | The currency code of the item's price. |
product_id |
number | The id of the product. |
product_type |
string | 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`. |
quantity |
number | The quantity of the product available for sale. Must be at least 1. |
size_id |
number | The size ID for a given size Set ID. |
size_set_id |
number | The size set ID for the given Department and Product Type. |
sku |
string | null | SKU of the product. This field is optional and will be null if no SKU was assigned to the product. |
slug |
string | The URL-friendly slug of the product. Can be used to construct the product URL as `https://www.depop.com/products/{slug}/`. |
source |
Array<string> | |
status |
string | The status of the product. |
style |
Array<string> | |
updated_at |
string(date-time) | The date and time when the product was last updated. |
ProductCreateOrUpdateResponse
| Name | Type | Description |
|---|---|---|
product_id |
number | The product id of the created or updated product. |
sku |
string | null | 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. |
slug |
string | The URL-friendly identifier for the product on Depop. This can be used with the `/api/v1/products/by-slug/{slug}/` endpoints. |
ProductCreateRequest
| Name | Type | Description |
|---|---|---|
address |
Address | |
age |
Array<string> | 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. |
attributes |
Example: {'sleeve-length': ['short'], 'occasion': ['wedding']} |
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/ |
auto_negotiate_offer_price |
string | 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. |
auto_send_offer_price |
string | 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. |
brand_name |
string | The brand name of the product, e.g. "Nike". |
colour |
Array<string> | 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. |
condition |
string | |
department |
string | 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`. |
depop_shipping |
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. | |
description |
string | 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). |
discount_price |
string | 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. |
international_shipping_cost |
string | The cost of shipping the product internationally. Only set this if the product can be shipped internationally. Same currency as price_currency. |
is_boosted |
boolean | 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". |
national_shipping_cost |
string | 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. |
pictures |
Array<PublicPicture> | 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. |
price_amount |
string | The price of the item. Must be at least $1.00 or £1.00. Up to 2 decimal places. |
price_currency |
string | The currency code of the item's price. |
product_type |
string | 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`. |
quantity |
number | The quantity of the product available for sale. Must be at least 1. |
size_id |
number | The size ID for a given size Set ID. This field is mandatory for product types that have a size set available. |
size_set_id |
number | The size set ID for the given Department and Product Type. This field is mandatory for product types that have a size set available. |
sku |
string | 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. |
source |
Array<string> | 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. |
style |
Array<string> | 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. |
ProductLike
| Name | Type | Description |
|---|---|---|
liker_id |
number | The Depop user ID of the user who liked or unliked the product. |
product_id |
number | The unique identifier of the product. |
seller_id |
number | The Depop user ID of the product seller. |
sku |
string | The SKU of the product. |
slug |
string | The URL-friendly identifier for the product on Depop. |
ProductPutRequest
| Name | Type | Description |
|---|---|---|
address |
Address | |
age |
Array<string> | |
attributes |
Example: {'sleeve-length': ['short'], 'occasion': ['wedding']} |
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. |
auto_negotiate_offer_price |
string | 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. |
auto_send_offer_price |
string | 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. |
brand_name |
string | 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". |
colour |
Array<string> | |
condition |
string | |
department |
string | 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`. |
depop_shipping |
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. | |
description |
string | 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). |
international_shipping_cost |
string | The cost of shipping the product internationally. Only set this if the product can be shipped internationally. Same currency as price_currency. |
is_boosted |
boolean | 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". |
national_shipping_cost |
string | 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. |
pictures |
Array<PublicPicture> | 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. |
price_amount |
string | The price of the item. Must be at least $1.00 or £1.00. Up to 2 decimal places. |
price_currency |
string | The currency code of the item's price. |
product_type |
string | 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`. |
quantity |
number | The quantity of the product available for sale. Must be at least 1. |
size_id |
number | The size ID for a given size Set ID. This field is mandatory for product types that have a size set available. |
size_set_id |
number | The size set ID for the given Department and Product Type. This field is mandatory for product types that have a size set available. |
source |
Array<string> | |
style |
Array<string> |
PublicPicture
| Name | Type | Description |
|---|---|---|
url |
string | Publicly accessible URL of the picture. Non-square images are also supported. Currently, we support JPG, WebP and PNG image formats. |
RefundedOrder
| Name | Type | Description |
|---|---|---|
purchase_id |
string | Depop's internal purchase ID. Useful to be logged and to report any issues back to us. |
refunded_by |
string | 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. |
RefundedToBuyerRefunds
| Name | Type | Description |
|---|---|---|
depop_fee_refund_amount |
string | The total amount of depop fee refunded to the buyer. |
item_refund_amount |
string | The total amount of item price refunded to the buyer. |
shipping_refund_amount |
string | The total amount of shipping price refunded to the buyer. |
tax_refund_amount |
string | The total amount of tax refunded to the buyer. |
RefundedToSellerRefunds
| Name | Type | Description |
|---|---|---|
ads_fee_refund_amount |
string | The total amount of ads fee refunded to the seller. |
depop_fee_refund_amount |
string | The total amount of depop fee refunded to the seller. |
payment_fee_refund_amount |
string | The total amount of payment fee refunded to the seller. |
shipping_refund_amount |
string | The total amount of shipping fee refunded to the seller. This will only be greater than 0 if the seller was responsible for the depop shipping label cost (i.e. free shipping for buyers) and the refund is a total refund. |
RefundOrderRequest
| Name | Type | Description |
|---|---|---|
items_refund_amount |
string | The amount to refund on the items in the order. Must be less than or equal to the total amount paid by the buyer. |
send_buyer_message |
string | The message to send to the buyer when processing the refund. This is optional but recommended. |
shipping_refund_amount |
string | The amount to refund on the shipping in the order. Must be less than or equal to the shipping price (buyer or seller paid). **Important:** For orders with Depop shipping (where `depop_shipping` is present), shipping can only be refunded as part of a full refund. Partial refunds cannot include shipping for these orders. For orders with manual shipping, shipping can be refunded with either full or partial refunds. |
SellerAddress
| Name | Type | Description |
|---|---|---|
address |
string | The primary address line. |
address2 |
string | null | The secondary address line (optional). |
city |
string | The city of the address. |
country |
string | The ISO 3166-1 alpha-2 country code. |
id |
integer(int64) | The unique identifier for the address. |
last_modified |
string(date-time) | null | The timestamp when the address was last modified (optional). |
name |
string | The name associated with the address. |
postal_code |
string | The postal code or ZIP code of the address. |
state |
string | The state or county of the address. |
SellerDetails
| Name | Type | Description |
|---|---|---|
country_code |
string | The ISO 3166-1 alpha-2 country code of the seller. |
id |
integer(int64) | The unique identifier for the seller. |
username |
string | The Depop username of the seller. |
ShippingAddress
| Name | Type | Description |
|---|---|---|
address |
string | The first line of the buyer's address. |
address2 |
string | The second line of the buyer's address. |
city |
string | The city of the buyer's address. |
country_code |
string | The country code of the buyer's address. |
name |
string | The name of the buyer. |
postal_code |
string | The postal code of the buyer's address. |
state |
string | The state of the buyer's address. |
ShippingParcelCost
| Name | Type | Description |
|---|---|---|
amount |
string | The cost amount (may be converted to buyer's currency). |
currency |
string | The currency code for the amount. |
original_amount |
string | The original cost amount before any conversions. |
original_currency |
string | The original currency code. |
ShippingParcelSize
| Name | Type | Description |
|---|---|---|
cost |
ShippingParcelCost | |
courier_service |
string | 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) |
id |
string | The unique identifier for the parcel size. |
subtitle |
string | Additional information about the parcel size (e.g., dimensions). |
title |
string | The display title for the parcel size. |
ShippingProviderInfo
| Name | Type | Description |
|---|---|---|
id |
string | The unique identifier for the shipping provider. |
parcel_sizes |
Array<ShippingParcelSize> | Available parcel sizes for this shipping provider. |
SimilarSoldItem
| Name | Type | Description |
|---|---|---|
brand_name |
string | The canonical brand name of the product. |
condition |
string | The condition of the sold item. |
picture |
Picture | |
product_slug |
string | The slug of the sold product, used to deep-link to it in the app. |
sold_price_amount |
string | The sale price of the item. |
sold_price_currency |
string | The currency of the sale price. |
Status
| Name | Type | Description |
|---|---|---|
status |
string | The status of the API. |
SubmitOfferRequest
| Name | Type | Description |
|---|---|---|
offer_currency |
string | The currency code for the offer (e.g., GBP, USD, EUR). Must match the product's currency. |
offer_recipient_id |
integer(int64) | The user ID of the buyer who will receive the offer. |
offer_value |
number(double) | The offer amount. Must be at least 5% lower than the product price_amount. |
size_id |
integer(int32) | 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 |
TotalRefundBreakdown
| Name | Type | Description |
|---|---|---|
refunded_to_buyer |
The breakdown of all amounts refunded to the buyer. | |
refunded_to_seller |
The breakdown of all amounts refunded to the seller. |
Webhook
| Name | Type | Description |
|---|---|---|
created_at |
string(date-time) | The date and time the webhook was created. |
data |
The data of the webhook. | |
event_type |
string | The type of event that triggered the webhook. |
id |
string | The unique identifier of the webhook. |
Common responses
This section describes common responses that are reused across operations.
BadRequest
Bad request
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "bad-request",
"message": "invalid request"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Unauthorized
Unauthorized
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "unauthorized",
"message": "invalid api key"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Forbidden
Forbidden - Insufficient scope
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "insufficient_scope",
"message": "Required scope: products_write"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
UnprocessableEntity
Unprocessable Entity
{
"id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
"errors": [
{
"code": "validation",
"message": "Missing fields for request"
}
]
}
Schema of the response body
{
"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"
}
]
}
}
Security schemes
| Name | Type | Scheme | Description |
|---|---|---|---|
| BearerAuth | http | bearer |
Tags
| Name | Description |
|---|---|
| Authentication | OAuth 2.0 authentication endpoints for partner integration |
| Products - By SKU | Product operations using SKU (Stock Keeping Unit) identifiers |
| Products - By Product ID | Product operations using internal product ID identifiers |
| Products - By Slug | Product operations using URL-friendly slug identifiers |
| Products | General product operations |
| Pricing Inspiration | ML-powered price recommendations and pricing guidance |
| Products - Legacy (Deprecated) | Deprecated product endpoints - use By SKU or By Product ID alternatives instead |
| Orders | Order management and fulfillment operations |
| Shop Management | Shop and seller information endpoints |
| API status | Service health and status endpoints |