openapi: 3.2.0
info:
version: 0.1.1
title: Back Market - API Guidelines Listings API
description: "## Table of contents\n\n1. [Introduction](#introduction)\n1. [Getting started](#getting-started)\n1. [Technical requirements](#technical-requirements)\n1. [F.A.Q. and Contact](#faq-and-contact)\n1. [Cookbooks](#cookbooks)\n\n## Introduction\n\nWelcome to Back Market, the leading online marketplace dedicated to refurbished products.\n\nOur back-office and our web-services have been created in order to allow Seller to manage their products\neasily on our marketplace. This documentation is meant to help you integrate our marketplace and learn how to manage\nyour `Products`, `Offers` and `Orders` on Back Market.\n\n### Overview of what this documentation is talking about\n\n* Our Taxonomy : This part will describe the organization and classification of our marketplace\n* Products & Offers : You will learn how to create `Products` as well as create, update and list `Offers` on Back Market\n* Your Orders : The `Orders` workflow, listing and update will be explained\n\nDifferent solutions are offered in order to use our marketplace. It's possible to work with a combination of\nthese solutions or to switch from one to another at a later stage.\n\n1 - Back Market API:\n\nThis is the best solution for big and/or small sellers with their own technical team. Working with our API will\nenable you to synchronize your information with our database in real time. It is especially suitable for sellers\nwith long-tail catalogs as well as a large amount of sales.\n\n2 - Back-office:\n\nOur <a target=\"_blank\" href=\"https://www.backmarket.fr/bo_merchant/\"> back-office</a> offers a graphic user\ninterface which allows you to manage everything simply and efficiently.\n\nOur back-office also gives you the possibility to import and export CSV files\nwith `Products`, `Offers` and `Orders` information.\nThis allows you to work with more `Offers` comfortably.\n\n3 - DEPRECATED FTP :\n\nFTP in Back Market is deprecated. If you used to use FTP in order to connect to Back Market\nPlease contact <partner-support@backmarket.com> to help you to setup an API connexion.\n\n### Other information\n\nOn this website, we've collected all the information you might need to get on board as smoothly as possible.\nAlso, be sure to check our [F.A.Q.](#f-a-q-and-contact) to get answers to your questions.\n[Contact us](#f-a-q-and-contact) if you still have further questions.\n\n### Feedback\n\nAt Back Market, we always want to improve our solutions.\nPlease [Give Us Feedback](mailto:<partner-support@backmarket.com>?subject=Feedback Back Market Doc) and let us\n know about possible improvement we could make, be it on this documentation, our web services,\n our back-office or whatever you might think of.\nPlease note that this mail is temporary as we will deploy a new Seller support center\nthat will assist you.\n\n## Getting Started\n\nIf you did not yet read the page on [taxonomy](operations/get-bm-catalog-category#taxonomy), please do it before proceeding.\n\n### Account\n\nAfter validation by our team, each Seller gains access to an account. This account gives you access to the Back\nMarket Back Office and our API.\n\nUse one of the following links to access your Back Office account or create one if you haven't done so already.\nYou will need to provide information about your company and we will get back to you as soon as possible:\n\n* <a target=\"_blank\" href=\"https://www.backmarket.co.jp/bo-seller\">AP platform</a>\n* <a target=\"_blank\" href=\"https://www.backmarket.fr/bo-seller\">EU platform</a>\n* <a target=\"_blank\" href=\"https://www.backmarket.com/bo-seller\">US platform</a>\n\nFor creating or accessing an account on the preprod, you can use the following links:\n\n* <a target=\"_blank\" href=\"https://preprod.backmarket.co.jp/bo-seller\">AP preprod platform</a>\n* <a target=\"_blank\" href=\"https://preprod.backmarket.fr/bo-seller\">EU preprod platform</a>\n* <a target=\"_blank\" href=\"https://preprod.backmarket.com/bo-seller\">US preprod platform</a>\n\n### Country code\n\nBack Market is international so you can sell products abroad. The\ncountry code matches both the targeted language and country for the\naction you'd like to perform (ex: update the price for a listing in\nItaly).\nInformation about every countries are contained in the same instance\nof an object `Product` or a `Listing`.\n\nIndeed, you don't need to create one `Listing` for each country. This\n`Listing` will contain some fields which are the same for all the countries (_listing_id, quantity, ..._) and other\n country specific fields (_comment, price and warranty_delay_).\nTherefore, if you wish to edit the _**stock**_ (field :\n'quantity'), the change will apply to all the countries, but for the\n_**comment**_ you will have to change it for each country.\n\nIn the same way, some fields of the `Product` are common for all\ncountries (_weight, EAN, ..._), and others depend on the country\n(_description, title and price_new_).\n\n**COUNTRY_CODES** - Accepted values are :\n\n* AP platform:\n\n * ja-jp : Japan\n * en-au : Australia\n\n* EU platform:\n\n * fr-fr : France\n * fr-be : Belgium\n * es-es : Spain\n * de-de : Germany\n * de-at : Austria\n * it-it : Italy\n * en-gb : United Kingdom\n * nl-nl : Netherlands\n * pt-pt : Portugal\n * en-ie : Ireland\n * el-gr : Greece\n * sk-sk : Slovakia\n * sv-se : Sweden\n\n* US platform:\n\n * en-us : United States\n\n### CSV file format\n\nAll files imported through our Back Office or imported using Back Market's API must be in CSV format.\n\nRequired field separator is ';'.\n\nRequired line separator is the line feed '\\n'.\n\nFields must be surrounded by double quotes.\n## Technical Requirements\n\n### API Identification\n>\n> HTTP Header (will remain the same for every API call):\n\n```http\nContent-type: application/json\nAccept: application/json\nAccept-Language: COUNTRY_CODE\nAuthorization: Basic YOUR_ACCESS_TOKEN\nUser-Agent: YOUR_USER_AGENT\n```\n\nEach Integrator or Seller should use the following HTTP Header when calling Back Market API endpoints.\n\nThe User-Agent is mandatory. Any request without it might be refused by our System.\n\nIt should include your company name, application name, version, and a contact email address in this format:\n\n```http\nBM-{CompanyName}-{IntegrationName};company@companydomain.com.\n```\n\nFor example:\n\n```http\nBM-Ebay-Invoices;contact@ebay.com\nBM-bouygues-automations;contact@bouygues.fr\n```\n\n### Web application firewall (WAF) and Bot management\n\nThe WAF or bot management may block your requests for security reason. You'll typically receive an HTTP 403 Forbidden\nresponse, possibly with a response body to tell you to challenge your client with Cloudflare.\n\nIn case you judge that your request should not be blocked by Cloudflare, from the response headers, you can get the value of cf-ray and send it to your seller contact for investigation.\n\nExample HTTP 403 response from WAF:\n\n```http\nHTTP/2 403\ndate: Wed, 16 Apr 2025 11:26:41 GMT\ncontent-type: text/html; charset=UTF-8\nreferrer-policy: same-origin\ncache-control: max-age=15\nexpires: Wed, 16 Apr 2025 11:26:56 GMT\n...\nx-content-type-options: nosniff\nx-frame-options: SAMEORIGIN\nserver: cloudflare\ncf-ray: 931354450813d142-CDG\nalt-svc: h3=\":443\"; ma=86400\n```\n\nExample HTTP 403 response for Bot Management protected endpoints:\n\n```json\n{\n \"errors\": [\n {\n \"code\": \"bot-need-challenge\",\n \"message\": \"Forbidden\",\n \"challengePath\": \"/testchallengepage\"\n }\n ]\n}\n```\n\n### Traffic limitation\n\nOur standard rate limits are will allow your automations to run fast enough to finish your processes.\nHowever, in case of too many requests beyond what we except on sellers endpoints, you will be presented with an HTTP 429 response from Cloudflare.\n\nUsually you will find the range above 200 requests in 10 seconds being blocked for 10 seconds and for more sensible\nendpoints like catalog for example above 20 requests in 10 seconds being blocked for 10 seconds.\n\n### Data limitation\n\nTo make sure we can handle and process all the incoming data correctly, we have set-up the following limitation:\n**We might not accept more than 2k lines of SKUs to process per hour** on the\n following endpoints ([Update Several listings](#update-several-listings) or\n on [Update specific listing](#update-specific-listing)) and [Update Listings](#update-listings)) files.\nFTP in Back Market is deprecated. If you used to use FTP in order to connect to Back Market\nPlease contact <partner-support@backmarket.com> to help you to setup an API connexion.\n\n**If this limit is reached, Back Market may refuse the task**, in this case you will receive HTTP responses\nwith the \"429 Too Many Requests\" status.\n\nIf you have lots of active SKUs, please take into account the [Best Practice](#best-practices)\npart of the documentation.\n\n### Questions ?\n\nIf you have any questions, please send an email to <partner-support@backmarket.com>\nPlease note that this mail is temporary as we will deploy a new seller support center\nthat will assist you.\n## F.A.Q. and Contact\n\nPlease [click here](https://merchant-support.backmarket.com/hc/en-us) to access your Seller Support Center\n where you can find our F.A.Q. or contact us.\n\nIf you have never signed in to the Seller Support Center, you can\n read this [tutorial](statics/How-to-connect-to-SSC.pdf) which helps you setup you connection for the first time.\n\nIf you have any more questions and are already selling on Back Market, we invite you to contact your account manager.\n## Cookbooks\n\nA list of notebooks showcasing different API use cases:\n\n[Winning the BackBox based on small price efforts](https://colab.research.google.com/drive/12jHZ3AQG8mQjjAvulG9zVvfC_psEOKjh?usp=sharing)\n"
contact:
name: Seller Support Center
url: https://merchant-support.backmarket.com/hc/en-us
x-slack: NA
email: NA@NA.com
servers:
- url: https://preprod.backmarket.co.jp
description: Preprod - AP
- url: https://www.backmarket.co.jp
description: Prod - AP
- url: https://preprod.backmarket.fr
description: Preprod - EU
- url: https://www.backmarket.fr
description: Prod - EU
- url: https://preprod.backmarket.com
description: Preprod - NA
- url: https://www.backmarket.com
description: Prod - NA
tags:
- name: Listings
paths:
/ws/listings:
get:
x-tier: 1
summary: Get listings
description: '
Retrieve all your `Listings`.
'
security:
- ApiKeyAuth: []
- BasicAuth: []
parameters:
- example: 2
in: query
name: publication_state
required: false
schema:
enum:
- 0
- 1
- 2
- 3
- 4
type: integer
- example: 0
in: query
name: min_quantity
required: false
schema:
type: integer
- example: 100
in: query
name: max_quantity
required: false
schema:
type: integer
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
- description: 'Select what market will be used to apply filters and export data.
Passed as the language code related to this market.
'
example: fr-fr
in: header
name: Accept-Language
required: false
schema:
$ref: '#/components/schemas/Locale'
responses:
'200':
content:
application/json:
schema:
properties:
count:
example: 123
type: integer
next:
example: https://www.backmarket.fr/ws/listings?page=2
type:
- string
- 'null'
previous:
example: null
type:
- string
- 'null'
results:
items:
$ref: '#/components/schemas/ListingPublic'
type: array
required:
- count
- next
- previous
- results
type: object
description: OK
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV1'
description: Unauthenticated.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV1'
description: Forbidden. Authenticated user is not a merchant.
tags:
- Listings
post:
tags:
- Listings
x-tier: 1
summary: Create or update products and listings
description: '
## Create listings
Every merchant working with us can create a sale offer or a
"`Listing`" of a `Product` in order to sell it on our marketplace. Our algorithm decides which `Listing` will win "The Backbox" and therefore which `Listing` will be displayed on our website for the consumer to purchase.
In this section we will describe an endpoint that allows you either to create `Listings` matching existing `Products` or to create both `Products` and `Listings` for these products at the same time.
We will also present how to create `Listings` matching existing `Products`. _Please refer to the section [Create products](#create-products) to know how to create both Products and Listings for these Products in the same API call._
Note that we limit the size of the CSV file that you can send to 15000 lines.
You can find the list of columns for the `catalog` field in the Back Market back-office following the tab "Options > Batch Listing Creation".
In the `catalog` field, a unique (case insensitive) `sku` must be provided by the merchant to identify the `Listing`.
Besides, either the `product_id` field or `ean` must be provided to match the `Product` you''d like to make an offer on. `product_id` prevails in case of conflict.
You can find the list of columns for the `catalog` field in the Back Market back-office following the tab "Options > Batch Listing Creation".
## Update several listings
It is possible to update several `Listings` at a time using CSV
files, which you can send with an API call. For example _you might want to add another country to the listings. You might also need to change their prices, comments or the available stocks (quantities)._
To put a `Listing` offline, just set its quantity to 0.
The endpoint below is not as efficient as the one described in "update specific listing", because the update will NOT be taken into account in real-time.
Indeed, you will have to wait for the task to be processed and to check the task for possible errors. Yet, you will be able to update several `Listings` at a time using the endpoint below, as opposed to the one described in "update specific listing".
We advise you not to use this endpoint to deal with stocks. Nevertheless, it can be useful if you''d like to update prices for your whole catalog for instance.
Note that we limit the size of the CSV file that you can send to 15000 lines.
For the `catalog` field, the `sku` must be provided to match the `Listing` you want to update (sku is case insensitive).
## Create products
In this section, we''ll guide you through the process of creating a `Product` on Back Market.
### Overview
If you wish to sell a `Product` that is not currently available on Back Market, you can propose the creation of a new `Product`. This proposal will be reviewed and either approved or rejected by our team.
**Important:** It is not possible to create a `Product` without a corresponding `Listing` using our API.
### Creating Products and Listings
This section explains how to create both `Products` and their corresponding `Listings` in a single API call.
- Each row in the CSV file you upload via the API can perform different actions based on the values provided.
- You can also [create](#create-listings) and [update](#update-several-listings) `Listings` for existing `Products` within the same API call.
### CSV File Requirements
- The CSV file you submit must not exceed 15,000 lines.
- You can generate a CSV file with all the required columns based on the product category in your back office by navigating to: **Options > Batch Listing Creation**.
By following these guidelines, you can efficiently manage your product listings on Back Market.
## Update products
After creation, since `Products` are multi-merchant, they cannot be directly updated after validation by our team.
You will have to contact us for all requests related to this matter.
In the case a `Product` hasn''t been validated by our team yet, the merchant who created this `Product` can update it as long as it''s not been validated. To do so, you need to perform the same actions you made during the [product creation](#create-products), but this time providing modified values.
If you try to update a `Product`, which is already existing (`EAN` or `Back Market id` match a `Product` in our Database) and has already been validated by our team, it won''t return any error but the modification won''t be taken into account. The product will still remain unchanged.
'
security:
- ApiKeyAuth: []
- BasicAuth: []
parameters:
- name: Accept-Language
in: header
description: 'Select what market will be used to apply filters and export data.
Passed as the language code related to this market.
'
required: false
example: fr-fr
schema:
$ref: '#/components/schemas/Locale'
requestBody:
content:
application/json:
schema:
type: object
required:
- catalog
- quotechar
- delimiter
- encoding
properties:
catalog:
type: string
minLength: 1
description: 'A CSV file content as a string.
'
example: 'sku,quantity,price
MY_SKU,50,123.45'
quotechar:
type: string
minLength: 1
maxLength: 1
description: The separator of columns for the 'catalog' CSV.
example: '"'
delimiter:
type: string
minLength: 1
maxLength: 1
description: The delimiter of data for the 'catalog' CSV.
example: ','
encoding:
type: string
minLength: 2
maxLength: 64
description: The encoding of data for the 'catalog' CSV.
example: utf-8
responses:
'200':
description: OK. Task has been created and will be processed.
content:
application/json:
schema:
type: object
required:
- bodymessage
- statuscode
properties:
bodymessage:
type: integer
description: 'The batch identifier that can be used to retrieve its status with
the Get batch API [/ws/tasks/{taskId}](https://api.backmarket.dev/#/paths/ws-tasks-taskId/get).
'
statuscode:
type: integer
example: 200
'400':
description: Request data is invalid. A required field might be missing.
content:
application/json:
schema:
type: string
description: An error message
example: parameter catalog not found
'401':
description: Unauthenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV1'
'403':
description: Forbidden. This ingestion channel could be disabled for the merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV1'
'429':
$ref: '#/components/responses/RateLimited'
/ws/listings/{listingId}:
parameters:
- in: path
name: listingId
description: Unique listing ID provided by Back Market. The UUID format is preferred.
required: true
example: da72cf47-1b1f-434a-9224-1f8684ac1bd4
schema:
oneOf:
- type: string
format: uuid
- type: integer
- name: Accept-Language
in: header
description: 'Select what market will be used to apply filters and export data.
Passed as the language code related to this market.
'
required: false
example: fr-fr
schema:
$ref: '#/components/schemas/Locale'
get:
tags:
- Listings
x-tier: 1
summary: Get specific listing
description: "\nRetrieve a specific `Listing` to check its information.\n\n### Endpoint\n\nThe 2 following endpoints provide exactly the same response:\n\n<aside class=\"success\">\n HTTP GET request: https://www.backmarket.fr/ws/listings/LISTING_ID\n</aside>\n\nOr working with a filter on:\n\n<aside class=\"success\">\n HTTP GET request: https://www.backmarket.fr/ws/listings/detail/\n</aside>\n\nIf you don't have either the sku nor the listing_id, you can retrieve\n them by:\n\n**GET** `https://www.backmarket.fr/ws/listings/`\n"
security:
- ApiKeyAuth: []
- BasicAuth: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/ListingPublic'
- type: object
required:
- statuscode
properties:
statuscode:
type: integer
example: 200
'400':
description: Invalid inputs (bad type…).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV1'
'401':
description: Unauthenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV1'
'403':
description: Forbidden. Authenticated user is not a merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV1'
'404':
description: Listing not found, or it does not belong to the authenticated merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV1'
post:
tags:
- Listings
x-tier: 1
summary: Update specific listing
description: '
It is possible to update some fields of a specific `Listing`. For example _you might want to add another country to the `Listing`. You might also need to change the price, comment or the available stock (quantity)._
To put a `Listing` offline, just set its quantity to 0.
The endpoint below provides the most efficient way to update a specific `Listing`, as the update will be taken into account in real-time. Yet, you can only update one `Listing` at a time on this endpoint as opposed to the endpoint to update several listings.
If you work with other marketplaces, **DO NOT forget** to update your stocks on Back Market in order not to be compelled to cancel orders. We strongly penalize high cancellation rates in our algorithm, which allocates `Backbox`.
Updating in real time is especially important when your stock for the listing is close to 0.
When an order is made on Back Market, you don''t need to decrease the stock in our database since we decrease it automatically.
You just need to specify field(s) you would like to change. All the others will be kept intact.
'
security:
- ApiKeyAuth: []
- BasicAuth: []
requestBody:
content:
application/json:
schema:
type: object
properties:
price:
description: 'Price of the listing in the ''currency''. String format is prefered to avoid any issue related to
the floating-point number precision.
'
anyOf:
- type: string
example: '160.99'
- type: number
example: 160.99
currency:
type: string
description: 'Currency of ''price'' in ISO 4217 code format.
If ''price'' is in the request, this field must match the currency of the market selected with
the ''Accept-Language'' header.
Defaults to EUR for the EU marketplace, USD for the US one. Thus this field is required for
markets where the currency is not these defaults.
'
example: EUR
comment:
description: Comment. Maximum 500 characters.
type:
- string
- 'null'
example: This is an iPhone 6S - 64Go - Blue working with all operators
warranty_delay:
description: Warranty period in months (12 months minimum).
anyOf:
- type: integer
example: 24
- type: string
example: '24'
quantity:
description: Available stock.
anyOf:
- type: integer
example: 12
- type: string
example: '12'
shipper_1:
$ref: '#/components/schemas/Shipper'
shipper_display_1:
type:
- string
- 'null'
description: The displayed name for the shipper.
example: DHL Express
shipping_delay_1:
description: Expected shipping delay in hours.
type:
- integer
- 'null'
example: 36
shipping_price_1:
description: 'Price of the shipping option, using currency of listing.
String format is prefered to avoid any issue related to the floating-point number precision.
'
anyOf:
- type: string
example: '3.90'
- type: number
example: 3.9
shipper_2:
$ref: '#/components/schemas/Shipper'
shipper_display_2:
type:
- string
- 'null'
description: The displayed name for the shipper.
example: DHL Express
shipping_delay_2:
description: Expected shipping delay in hours.
type:
- integer
- 'null'
example: 36
shipping_price_2:
description: 'Price of the shipping option, using currency of listing.
String format is prefered to avoid any issue related to the floating-point number precision.
'
anyOf:
- type: string
example: '3.90'
- type: number
example: 3.9
shipper_3:
$ref: '#/components/schemas/Shipper'
shipper_display_3:
type:
- string
- 'null'
description: The displayed name for the shipper.
example: DHL Express
shipping_delay_3:
description: Expected shipping delay in hours.
type:
- integer
- 'null'
example: 36
shipping_price_3:
description: 'Price of the shipping option, using currency of listing.
String format is prefered to avoid any issue related to the floating-point number precision.
'
anyOf:
- type: string
example: '3.90'
- type: number
example: 3.9
min_price:
description: 'Your minimum acceptable price. The BackPricer needs to be enabled in your seller configuration.
More information about BackPricer at
https://merchant-support.backmarket.com/hc/en-us/articles/4415101044370-How-to-use-the-BackPricer-
'
anyOf:
- type: string
example: '160.99'
- type: number
example: 160
responses:
'200':
description: 'OK. Update processed.
Note that some processing can be done asynchronously (Backbox, search indexing, etc).
'
content:
application/json:
schema:
type: object
required:
- id
- listing_id
- backmarket_id
- title
- shippings
- state
- grade
- quantity
- currency
- sku
- publication_state
- warranty_delay
- price
- comment
- max_price
- statuscode
- min_price
properties:
id:
type: string
format: uuid
description: Listing ID
example: 7a97a1b6-547e-4718-bc72-5b84aca91b09
listing_id:
type: integer
description: Listing ID (deprecated)
example: 4567
product_id:
type: string
format: uuid
description: Product ID
example: 6d4ad966-db97-4d88-b409-b28cc2a0f8c9
backmarket_id:
type: integer
description: Product ID (deprecated)
example: 42
title:
type: string
description: Product title
example: iPhone 6S - 64Go - Blue - Unlocked
shippings:
type: array
description: 'Shippings defined at listing level (if any). Does not include shippings defined
at category level nor the global ones.
'
items:
type: object
required:
- shipping_price
- shipping_delay
- shipper
- shipper_display
- country_code
properties:
shipping_price:
type: string
description: Price of the shipping option, using currency of listing.
example: '0.00'
shipping_delay:
type: integer
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/back-market/refs/heads/main/openapi/back-market-listings-api-openapi.yml