OpenAPI Specification
openapi: 3.1.0
info:
title: Seller API status Insights API
version: 1.0.0
description: 'Externally facing API to allow enterprise partners to automate listing on Depop.
## OAuth 2.0 Scopes
This API uses OAuth 2.0 scopes to control access to different resources. Each endpoint requires specific scopes to access:
- **`products_read`** - Required to read product information and listings
- **`products_write`** - Required to create, update, or delete products
- **`orders_read`** - Required to read order information and order history
- **`orders_write`** - Required to mark orders as shipped or process refunds
- **`offers_read`** - Required to read offer pricing information (auto send offer price, auto negotiate offer price)
- **`offers_write`** - Required to set or modify offer prices (auto send offer price, auto negotiate offer price)
- **`shop_read`** - Required to read shop information including seller addresses and available shipping providers
API key tokens have access to all scopes, while OAuth tokens are limited to the scopes specified in the token.
If you attempt to access an endpoint without the required scope, you will receive a `403 Forbidden` response with the error code `insufficient_scope`.'
servers:
- url: https://partnerapi-staging.depop.com
- url: https://partnerapi.depop.com
security:
- BearerAuth: []
tags:
- name: Insights
description: Shop and product insights
paths:
/api/v1/insights/shop/live/:
get:
tags:
- Insights
summary: Get shop insights
description: 'This endpoint returns insights about the authenticated seller''s shop, including product counts, shop rating, offers awaiting review, boost ad counts and orders awaiting shipping.
**Required OAuth Scopes:** at least one of the scopes below. Each section of the response is included only when its corresponding scope is present, and omitted otherwise. A `403` is returned only when none of these scopes are present.
- `products_read` - Include product counts (`products`) and boost ad counts (`boost`). - `shop_read` - Include shop rating (`rating`). - `offers_read` - Include offers awaiting seller review (`offers`). - `orders_read` - Include orders awaiting shipping (`orders`).
A section is included in the response only when its corresponding scope is present, and is omitted entirely otherwise. A `403` is returned only when the token has none of the four scopes above.
**Note:** Counters may be delayed by up to 60 minutes and may not reflect the most recent changes to your shop inventory.'
operationId: getShopInsightsLive
responses:
'200':
description: Shop insights. Each section is present only when the token holds the scope that section requires; sections for missing scopes are omitted. The `orders` section is additionally omitted when there are no orders awaiting shipping.
content:
application/json:
schema:
$ref: '#/components/schemas/ShopInsightsResponse'
example:
products:
on_sale_count: 42
total_count: 150
rating:
average: 4.8
count: 120
offers:
awaiting_seller_review_count: 8
boost:
live_count: 25
sold_count: 4
orders:
awaiting_shipping_count: 7
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'502':
$ref: '#/components/responses/BadGateway'
/api/v1/insights/products/by-sku/{sku}/live/:
get:
tags:
- Insights
summary: Get product insights by SKU
description: 'This endpoint returns live insights about a single product in the authenticated seller''s shop, identified by its SKU, including likes, bag adds, offers awaiting review and boosted-listing performance.
**Required OAuth Scopes:** at least one of the scopes below. Each section of the response is included only when its corresponding scope is present, and omitted otherwise. A `403` is returned only when none of these scopes are present.
- `products_read` - Include likes (`likes_count`) and bag adds (`bag_count`). - `offers_read` - Include offers awaiting review (`offers`).'
operationId: getProductInsightsLiveBySku
parameters:
- name: sku
in: path
description: SKU of the product to fetch insights for.
required: true
schema:
type: string
maxLength: 50
example: ABC-12345-S-BL
responses:
'200':
description: Product insights. Each section is present only when the token holds the scope that section requires; sections for missing scopes are omitted.
content:
application/json:
schema:
$ref: '#/components/schemas/ProductInsightsResponse'
example:
likes_count: 34
bag_count: 12
offers:
awaiting_seller_review_count: 3
awaiting_buyer_review_count: 1
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/ProductNotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'502':
$ref: '#/components/responses/BadGateway'
/api/v1/insights/products/by-slug/{slug}/live/:
get:
tags:
- Insights
summary: Get product insights by slug
description: 'This endpoint returns live insights about a single product in the authenticated seller''s shop, identified by its slug, including likes, bag adds, offers awaiting review and boosted-listing performance.
**Required OAuth Scopes:** at least one of the scopes below. Each section of the response is included only when its corresponding scope is present, and omitted otherwise. A `403` is returned only when none of these scopes are present.
- `products_read` - Include likes (`likes_count`) and bag adds (`bag_count`). - `offers_read` - Include offers awaiting review (`offers`).'
operationId: getProductInsightsLiveBySlug
parameters:
- name: slug
in: path
description: The slug of the product to fetch insights for.
required: true
schema:
type: string
example: vintage-nike-t-shirt-7033001
responses:
'200':
description: Product insights. Each section is present only when the token holds the scope that section requires; sections for missing scopes are omitted.
content:
application/json:
schema:
$ref: '#/components/schemas/ProductInsightsResponse'
example:
likes_count: 34
bag_count: 12
offers:
awaiting_seller_review_count: 3
awaiting_buyer_review_count: 1
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/ProductNotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'502':
$ref: '#/components/responses/BadGateway'
/api/v1/insights/products/by-product-id/{productId}/live/:
get:
tags:
- Insights
summary: Get product insights by product ID
description: 'This endpoint returns live insights about a single product in the authenticated seller''s shop, identified by its internal product ID, including likes, bag adds, offers awaiting review and boosted-listing performance.
**Required OAuth Scopes:** at least one of the scopes below. Each section of the response is included only when its corresponding scope is present, and omitted otherwise. A `403` is returned only when none of these scopes are present.
- `products_read` - Include likes (`likes_count`) and bag adds (`bag_count`). - `offers_read` - Include offers awaiting review (`offers`).'
operationId: getProductInsightsLiveByProductId
parameters:
- name: productId
in: path
description: The internal product ID of the product to fetch insights for.
required: true
schema:
type: integer
format: int64
example: 7033001
responses:
'200':
description: Product insights. Each section is present only when the token holds the scope that section requires; sections for missing scopes are omitted.
content:
application/json:
schema:
$ref: '#/components/schemas/ProductInsightsResponse'
example:
likes_count: 34
bag_count: 12
offers:
awaiting_seller_review_count: 3
awaiting_buyer_review_count: 1
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/ProductNotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'502':
$ref: '#/components/responses/BadGateway'
components:
schemas:
ShopOrdersInsights:
type: object
description: Order insights for the shop.
required:
- awaiting_shipping_count
properties:
awaiting_shipping_count:
type: integer
description: Count of orders awaiting shipping. Counts orders whose receipt is within the recent cut-off window and that have not been refunded. Capped at 20.
example: 5
maximum: 20
ErrorItem:
type: object
required:
- code
- message
properties:
code:
type: string
example: missing_attribute
description: The error code.
message:
type: string
example: Missing mandatory field
description: The error message.
ProductBoostInsights:
type: object
description: Boosted listing (ads) performance for the product. Included only when the token has the `products_read` scope. Individual counters are omitted when the underlying data is unavailable.
properties:
organic_clicks:
type: integer
description: Number of clicks from organic (non-boosted) placements.
example: 120
boosted_clicks:
type: integer
description: Number of clicks from boosted placements.
example: 45
organic_impressions:
type: integer
description: Number of impressions from organic (non-boosted) placements.
example: 3400
boosted_impressions:
type: integer
description: Number of impressions from boosted placements.
example: 900
ShopInsightsResponse:
type: object
description: Insights for the authenticated seller's shop. Counters may be delayed by up to 60 minutes.
properties:
products:
$ref: '#/components/schemas/ShopProductsInsights'
rating:
$ref: '#/components/schemas/ShopRatingInsights'
boost:
$ref: '#/components/schemas/ShopBoostInsights'
orders:
$ref: '#/components/schemas/ShopOrdersInsights'
offers:
$ref: '#/components/schemas/ShopOffersInsights'
ShopRatingInsights:
type: object
description: Seller rating insights for the shop.
required:
- average
- count
properties:
average:
type: number
format: double
description: Average seller rating across all reviews.
example: 4.8
count:
type: integer
description: Number of seller reviews received.
example: 120
ProductOffersInsights:
type: object
description: Offer insights for the product. Included only when the token has the `offers_read` scope.
required:
- awaiting_seller_review_count
- awaiting_buyer_review_count
properties:
awaiting_seller_review_count:
type: integer
description: Number of offers on the product awaiting the seller's review.
example: 3
awaiting_buyer_review_count:
type: integer
description: Number of offers on the product awaiting the buyer's review.
example: 1
ShopOffersInsights:
type: object
description: Offer insights for the shop.
required:
- awaiting_seller_review_count
properties:
awaiting_seller_review_count:
type: integer
description: Number of offers across the shop awaiting the seller's review.
example: 8
ShopProductsInsights:
type: object
description: Product count insights for the shop.
required:
- on_sale_count
- total_count
properties:
on_sale_count:
type: integer
description: Number of products currently on sale.
example: 42
total_count:
type: integer
description: Total number of products in the shop.
example: 150
ErrorResponse:
type: object
properties:
id:
type: string
example: a210923f-c1f3-4d84-a2bd-7f18c68553e2
description: A unique identifier for the error response.
errors:
type: array
items:
$ref: '#/components/schemas/ErrorItem'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: product_not_found
message: 'Product (sku: womens-tshirt-1, id: 123) not found'
ProductInsightsResponse:
type: object
description: Live insights for a single product. Each section is present only when the token holds the scope that section requires; sections for missing scopes are omitted.
properties:
likes_count:
type: integer
description: Number of likes on the product. Included only when the token has the `products_read` scope.
example: 34
bag_count:
type: integer
description: Number of users who have added the product to their bag. Included only when the token has the `products_read` scope.
example: 12
offers:
$ref: '#/components/schemas/ProductOffersInsights'
boost:
$ref: '#/components/schemas/ProductBoostInsights'
ShopBoostInsights:
type: object
description: Boosted listings (ads) insights for the shop.
required:
- live_count
- sold_count
properties:
live_count:
type: integer
description: Number of boosted listings currently live.
example: 12
sold_count:
type: integer
description: Number of boosted listings that have sold.
example: 34
responses:
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: unauthorized
message: invalid api key
TooManyRequests:
description: Too Many Requests - a rate limit has been exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: too_many_requests
message: Rate limit exceeded. Please retry later.
Forbidden:
description: Forbidden - Insufficient scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: insufficient_scope
message: 'Required scope: products_write'
BadGateway:
description: Bad Gateway - an upstream service required to build the insights response failed or returned an unexpected response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: unexpected_response
message: An upstream request at depop has failed to be processed.
ProductNotFound:
description: Not Found - the product does not exist or is not owned by the authenticated seller
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: product_not_found
message: 'Product (sku: ABC-12345-S-BL, id: None, slug: None) not found'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API key