openapi: 3.1.0 info: title: Seller API status Orders 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: Orders description: Order management and fulfillment operations paths: /api/v1/orders/: get: summary: 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.' operationId: getAllOrders tags: - Orders parameters: - name: limit in: query description: The number of orders to return. Default is 20. schema: type: integer minimum: 1 maximum: 200 example: 20 - name: cursor in: query description: The cursor to start from. This is the ID of the last purchase order ID returned in the previous request. schema: type: string example: NDM0NjMyOTI5Njg3 - name: from in: query description: The start date of the orders to return. schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - name: to in: query description: The end date of the orders to return. schema: type: string format: date-time example: '2025-01-31T23:59:59Z' responses: '200': description: 'A page with orders. This endpoint must be used to reconcile the orders you have received via webhooks. You can do this either by polling the endpoint and using the cursor until you reach an order you have already processed. Alternatively, you can use the `from` and `to` parameters to get orders in a specific time frame.' content: application/json: schema: $ref: '#/components/schemas/OrdersPage' example: meta: cursor: '123456789' has_more: false data: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /api/v1/orders/{purchase_id}/: get: summary: 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.' operationId: getOrderByPurchaseId tags: - Orders parameters: - name: purchase_id in: path description: The purchase ID of the order. required: true schema: type: string example: '123456' responses: '200': description: A single order content: application/json: schema: $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 address2: Apt 1 city: London postal_code: EC1V 4PW state: Greater London country_code: GB phone_number: 07123456789 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' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': description: Order not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /api/v1/orders/{purchase_id}/parcels/{parcel_id}/mark-as-shipped/: post: summary: 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.' operationId: markOrderAsShipped tags: - Orders parameters: - name: purchase_id in: path description: The purchase ID of the order. required: true schema: type: string example: '123456' - name: parcel_id in: path description: The parcel ID of the order. required: true schema: type: string example: 6e3538ca-6653-3c25-bf0a-a2be876b17e4 requestBody: description: Tracking information content: application/json: schema: $ref: '#/components/schemas/MarkAsShippedRequest' example: tracking_number: '123456789' carrier: Royal Mail responses: '200': description: Successful operation, no content returned content: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /api/v1/orders/{purchase_id}/refund/: post: summary: Refund an order description: "This endpoint allows you to refund an order and send a message to the buyer.\n**Required OAuth Scope:** `orders_write`\n\nA refund can be a full refund or a partial refund by specifying the amount to refund on items and/or shipping within the order.\n\n**Important note about shipping refunds with Depop shipping:**\n- 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.\n- For orders with **manual shipping**, shipping can be refunded with either full or partial refunds.\n- To determine if an order uses Depop shipping, check if the `depop_shipping` field is present in the order response. \n\nThe 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.\n\nThe order will still be visible in your orders but marked as REFUNDED.\n\nAll fees will automatically be calculated and refunded to the buyer and the seller (partner)." operationId: refundOrder tags: - Orders parameters: - name: purchase_id in: path description: The purchase ID of the order. required: true schema: type: string example: '123456' requestBody: description: Refund details content: application/json: schema: $ref: '#/components/schemas/RefundOrderRequest' example: items_refund_amount: '50.99' shipping_refund_amount: '4.99' send_buyer_message: Your order has been refunded. We apologize for the inconvenience. responses: '200': description: Successful operation, no content returned content: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: 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. components: schemas: ShippingAddress: required: - city - postal_code - country_code type: object properties: name: type: string description: The name of the buyer. example: John Doe address: type: string description: The first line of the buyer's address. example: 123 Main St address2: type: string description: The second line of the buyer's address. example: Apt 1 city: type: string description: The city of the buyer's address. example: Los Angeles postal_code: type: string description: The postal code of the buyer's address. example: 90022-3049 state: type: string description: The state of the buyer's address. example: CA country_code: type: string description: The country code of the buyer's address. example: US phone_number: type: string description: The phone number of the buyer. example: 07123456789 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. TotalRefundBreakdown: type: object required: - refunded_to_buyer - refunded_to_seller properties: refunded_to_buyer: allOf: - $ref: '#/components/schemas/RefundedToBuyerRefunds' description: The breakdown of all amounts refunded to the buyer. refunded_to_seller: allOf: - $ref: '#/components/schemas/RefundedToSellerRefunds' description: The breakdown of all amounts refunded to the seller. example: refunded_to_buyer: item_refund_amount: '15.00' shipping_refund_amount: '3.00' depop_fee_refund_amount: '0.50' tax_refund_amount: '2.00' refunded_to_seller: ads_fee_refund_amount: '1.50' payment_fee_refund_amount: '0.80' depop_fee_refund_amount: '0.30' shipping_refund_amount: '4.00' MarkAsShippedRequest: type: object properties: tracking_number: type: string description: 'The tracking number of the shipment. If 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 RefundedToBuyerRefunds: type: object properties: item_refund_amount: type: string description: The total amount of item price refunded to the buyer. example: '15.00' shipping_refund_amount: type: string description: The total amount of shipping price refunded to the buyer. example: '3.00' depop_fee_refund_amount: type: string description: The total amount of depop fee refunded to the buyer. example: '0.50' tax_refund_amount: type: string description: The total amount of tax refunded to the buyer. example: '2.00' required: - item_refund_amount - shipping_refund_amount - depop_fee_refund_amount - tax_refund_amount example: item_refund_amount: '15.00' shipping_refund_amount: '3.00' depop_fee_refund_amount: '0.50' tax_refund_amount: '2.00' OrderLineItem: type: object required: - purchase_item_id - product_id - slug - parcel_id - description - original_price - sold_price - sold_via_offers - image_url properties: purchase_item_id: type: number description: Depop's internal purchase line item ID. Useful to be logged and to report any issues back to us. example: 2385551 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: Depop's internal product ID. example: 7021251 slug: type: string description: The unique slug identifier for the product on Depop. example: vintage-levis-501-jeans-w32-l34 parcel_id: type: string description: '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.' example: 6e3538ca-6653-3c25-bf0a-a2be876b17e4 description: type: string description: The description of the product. example: 'Product 403d667d-eb4d-49fd-aa10-18a54119d9fb created by the RestAssured automated test framework hashtags #vintage #rare #tee #grunge #y2k' original_price: type: string description: The original price of the product before any discounts or offers. example: '10.00' sold_price: type: string description: How much it sold for, which includes any discounts or negotiated offers. example: '5.00' sold_via_offers: type: boolean description: Whether the item was sold via an offer negotiation with the buyer. example: true image_url: type: string description: The URL of the first image of the product. example: https://media-photos-staging.depop.com/r1/67655700/2147971983_93864b20a2ad4b78833cb92c2154810c/P0.jpg Order: 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. This 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. This 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. 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.' 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' FeeBreakdown: type: object required: - fee_type - amount - currency properties: fee_type: type: string description: '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.' enum: - PAYMENT_FEE - BOOSTED_FEE - DEPOP_FEE - SHIPPING_FEE example: PAYMENT_FEE amount: type: string description: The amount of the fee. example: '5.00' currency: type: string description: The currency. example: GBP 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' RefundOrderRequest: 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). **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.' example: '4.99' OrdersPage: 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 phone_number: 07123456789 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' RefundedToSellerRefunds: type: object properties: ads_fee_refund_amount: type: string description: The total amount of ads fee refunded to the seller. example: '2.50' payment_fee_refund_amount: type: string description: The total amount of payment fee refunded to the seller. example: '2.50' depop_fee_refund_amount: type: string description: The total amount of depop fee refunded to the seller. example: '0.00' shipping_refund_amount: type: string description: 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. example: '4.00' required: - ads_fee_refund_amount - payment_fee_refund_amount - depop_fee_refund_amount - shipping_refund_amount example: ads_fee_refund_amount: '1.50' payment_fee_refund_amount: '0.80' depop_fee_refund_amount: '0.30' shipping_refund_amount: '4.00' DepopShippingResponse: type: object required: - shipping_provider_id properties: shipping_provider_id: type: string description: 'The identifier for the shipping provider used for this order. Common providers include: USPS, MY_HERMES (EVRI), SENDLE.' example: USPS example: shipping_provider_id: USPS responses: Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: a210923f-c1f3-4d84-a2bd-7f18c68553e2 errors: - code: unauthorized message: invalid api key BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: a210923f-c1f3-4d84-a2bd-7f18c68553e2 errors: - code: bad-request message: invalid request Forbidden: description: Forbidden - Insufficient scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: a210923f-c1f3-4d84-a2bd-7f18c68553e2 errors: - code: insufficient_scope message: 'Required scope: products_write' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API key