OpenAPI Specification
openapi: 3.1.0
info:
title: Seller API status Shop Management 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: Shop Management
description: Shop and seller information endpoints
paths:
/api/v1/shop/:
get:
summary: Get seller details
description: 'This endpoint allows you to retrieve details about your Depop shop, including your seller ID, username, and country code.
**Required OAuth Scope:** `shop_read`'
operationId: getSellerDetails
tags:
- Shop Management
responses:
'200':
description: Seller details
content:
application/json:
schema:
$ref: '#/components/schemas/SellerDetails'
example:
id: 97082934
username: good_will_charity
country_code: US
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden - Insufficient scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: insufficient_scope
message: 'The request requires higher privileges than provided by the access token. Required scope: shop_read'
/api/v1/shop/seller-addresses/:
get:
summary: Get seller addresses
description: 'This endpoint allows you to retrieve all active addresses associated with your Depop shop.
**Required OAuth Scope:** `shop_read`
These addresses can be used to determine available shipping providers for your shop.'
operationId: getSellerAddresses
tags:
- Shop Management
responses:
'200':
description: A paginated list of seller addresses
content:
application/json:
schema:
type: object
required:
- meta
- data
properties:
meta:
type: object
required:
- has_more
properties:
cursor:
type:
- string
- '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: []
example:
meta:
cursor: MTIzNDU2fDIwMjUtMDEtMTVUMTA6MzA6MDBafDEyMw
has_more: false
data:
- id: 123456
name: John Doe
address: 123 Main Street
address2: Apt 4B
city: London
state: Greater London
postal_code: SW1A 1AA
country: GB
last_modified: '2025-01-15T10:30:00Z'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden - Insufficient scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: insufficient_scope
message: 'The request requires higher privileges than provided by the access token. Required scope: shop_read'
/api/v1/shop/seller-addresses/{address_id}/shipping-providers/:
get:
summary: Get available shipping providers for an address
description: 'This endpoint allows you to retrieve the available shipping providers for a specific seller address.
**Required OAuth Scope:** `shop_read`
The response includes the shipping providers and their available parcel sizes with pricing information.
If no shipping providers are available for the given address, manual shipping will be returned as the provider Id.'
operationId: getShippingProviders
tags:
- Shop Management
parameters:
- name: address_id
in: path
description: The ID of the seller address.
required: true
schema:
type: integer
format: int64
example: 123456
responses:
'200':
description: A list of available shipping providers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ShippingProviderInfo'
example:
- id: MY_HERMES
parcel_sizes:
- id: small
title: Small
subtitle: Tops, jeans, dresses and jewellery
cost:
original_amount: '2.99'
original_currency: GBP
amount: '2.99'
currency: GBP
courier_service: DROP_OFF
- id: medium
title: Medium
subtitle: Coats, jackets, trainers and shoes
cost:
original_amount: '4.99'
original_currency: GBP
amount: '4.99'
currency: GBP
courier_service: DROP_OFF
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden - Insufficient scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: insufficient_scope
message: 'The request requires higher privileges than provided by the access token. Required scope: shop_read'
'404':
description: Address not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
id: a210923f-c1f3-4d84-a2bd-7f18c68553e2
errors:
- code: address_not_found
message: Address with ID 999999 not found
components:
schemas:
ShippingParcelSize:
type: object
required:
- id
- title
- subtitle
- cost
- courier_service
properties:
id:
type: string
description: The unique identifier for the parcel size.
example: SMALL
title:
type: string
description: The display title for the parcel size.
example: Small parcel
subtitle:
type: string
description: Additional information about the parcel size (e.g., dimensions).
example: Up to 35 x 25 x 16cm
cost:
$ref: '#/components/schemas/ShippingParcelCost'
courier_service:
type: string
description: 'The courier service type for this parcel size.
- `DROP_OFF`: Seller drops off the parcel at a designated location
- `COURIER_COLLECT`: Courier collects the parcel from the seller
- `OTHER`: Other courier service types (reserved for future use)
'
enum:
- DROP_OFF
- COURIER_COLLECT
- OTHER
example: DROP_OFF
example:
id: small
title: Extra small
subtitle: Under 8oz
cost:
original_amount: '5.99'
original_currency: USD
amount: '5.00'
currency: USD
courier_service: DROP_OFF
SellerDetails:
type: object
required:
- id
- username
- country_code
properties:
id:
type: integer
format: int64
description: The unique identifier for the seller.
example: 97082934
username:
type: string
description: The Depop username of the seller.
example: good_will_charity
country_code:
type: string
description: The ISO 3166-1 alpha-2 country code of the seller.
example: US
example:
id: 97082934
username: good_will_charity
country_code: US
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.
ShippingParcelCost:
type: object
required:
- original_amount
- original_currency
- amount
- currency
properties:
original_amount:
type: string
description: The original cost amount before any conversions.
example: '3.50'
original_currency:
type: string
description: The original currency code.
example: GBP
amount:
type: string
description: The cost amount (may be converted to buyer's currency).
example: '3.50'
currency:
type: string
description: The currency code for the amount.
example: GBP
example:
original_amount: '3.50'
original_currency: GBP
amount: '3.50'
currency: GBP
ShippingProviderInfo:
type: object
required:
- id
- parcel_sizes
properties:
id:
type: string
description: The unique identifier for the shipping provider.
example: USPS
parcel_sizes:
type: array
description: Available parcel sizes for this shipping provider.
items:
$ref: '#/components/schemas/ShippingParcelSize'
example:
id: USPS
parcel_sizes:
- id: small
title: Extra small
subtitle: Under 8oz
cost:
original_amount: '5.99'
original_currency: USD
amount: '5.00'
currency: USD
courier_service: DROP_OFF
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'
SellerAddress:
type: object
required:
- id
- name
- address
- city
- state
- postal_code
- country
properties:
id:
type: integer
format: int64
description: The unique identifier for the address.
example: 123456
name:
type: string
description: The name associated with the address.
example: John Doe
address:
type: string
description: The primary address line.
example: 123 Main Street
address2:
type:
- string
- 'null'
description: The secondary address line (optional).
example: Apt 4B
city:
type: string
description: The city of the address.
example: London
state:
type: string
description: The state or county of the address.
example: Greater London
postal_code:
type: string
description: The postal code or ZIP code of the address.
example: SW1A 1AA
country:
type: string
description: The ISO 3166-1 alpha-2 country code.
example: GB
last_modified:
type:
- string
- 'null'
format: date-time
description: The timestamp when the address was last modified (optional).
example: '2025-01-15T10:30:00Z'
example:
id: 123456
name: John Doe
address: 123 Main Street
address2: Apt 4B
city: London
state: Greater London
postal_code: SW1A 1AA
country: GB
last_modified: '2025-01-15T10:30:00Z'
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
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API key