openapi: 3.0.3
info:
version: 0.1.1
title: Back Market - API Guidelines
description: |
## Table of contents
1. [Introduction](#introduction)
1. [Getting started](#getting-started)
1. [Technical requirements](#technical-requirements)
1. [F.A.Q. and Contact](#faq-and-contact)
1. [Cookbooks](#cookbooks)
## Introduction
Welcome to Back Market, the leading online marketplace dedicated to refurbished products.
Our back-office and our web-services have been created in order to allow Seller to manage their products
easily on our marketplace. This documentation is meant to help you integrate our marketplace and learn how to manage
your `Products`, `Offers` and `Orders` on Back Market.
### Overview of what this documentation is talking about
* Our Taxonomy : This part will describe the organization and classification of our marketplace
* Products & Offers : You will learn how to create `Products` as well as create, update and list `Offers` on Back Market
* Your Orders : The `Orders` workflow, listing and update will be explained
Different solutions are offered in order to use our marketplace. It's possible to work with a combination of
these solutions or to switch from one to another at a later stage.
1 - Back Market API:
This is the best solution for big and/or small sellers with their own technical team. Working with our API will
enable you to synchronize your information with our database in real time. It is especially suitable for sellers
with long-tail catalogs as well as a large amount of sales.
2 - Back-office:
Our <a target="_blank" href="https://www.backmarket.fr/bo_merchant/"> back-office</a> offers a graphic user
interface which allows you to manage everything simply and efficiently.
Our back-office also gives you the possibility to import and export CSV files
with `Products`, `Offers` and `Orders` information.
This allows you to work with more `Offers` comfortably.
3 - DEPRECATED FTP :
FTP in Back Market is deprecated. If you used to use FTP in order to connect to Back Market
Please contact <partner-support@backmarket.com> to help you to setup an API connexion.
### Other information
On this website, we've collected all the information you might need to get on board as smoothly as possible.
Also, be sure to check our [F.A.Q.](#f-a-q-and-contact) to get answers to your questions.
[Contact us](#f-a-q-and-contact) if you still have further questions.
### Feedback
At Back Market, we always want to improve our solutions.
Please [Give Us Feedback](mailto:<partner-support@backmarket.com>?subject=Feedback Back Market Doc) and let us
know about possible improvement we could make, be it on this documentation, our web services,
our back-office or whatever you might think of.
Please note that this mail is temporary as we will deploy a new Seller support center
that will assist you.
## Getting Started
If you did not yet read the page on [taxonomy](operations/get-bm-catalog-category#taxonomy), please do it before proceeding.
### Account
After validation by our team, each Seller gains access to an account. This account gives you access to the Back
Market Back Office and our API.
Use one of the following links to access your Back Office account or create one if you haven't done so already.
You will need to provide information about your company and we will get back to you as soon as possible:
* <a target="_blank" href="https://www.backmarket.co.jp/bo-seller">AP platform</a>
* <a target="_blank" href="https://www.backmarket.fr/bo-seller">EU platform</a>
* <a target="_blank" href="https://www.backmarket.com/bo-seller">US platform</a>
For creating or accessing an account on the preprod, you can use the following links:
* <a target="_blank" href="https://preprod.backmarket.co.jp/bo-seller">AP preprod platform</a>
* <a target="_blank" href="https://preprod.backmarket.fr/bo-seller">EU preprod platform</a>
* <a target="_blank" href="https://preprod.backmarket.com/bo-seller">US preprod platform</a>
### Country code
Back Market is international so you can sell products abroad. The
country code matches both the targeted language and country for the
action you'd like to perform (ex: update the price for a listing in
Italy).
Information about every countries are contained in the same instance
of an object `Product` or a `Listing`.
Indeed, you don't need to create one `Listing` for each country. This
`Listing` will contain some fields which are the same for all the countries (_listing_id, quantity, ..._) and other
country specific fields (_comment, price and warranty_delay_).
Therefore, if you wish to edit the _**stock**_ (field :
'quantity'), the change will apply to all the countries, but for the
_**comment**_ you will have to change it for each country.
In the same way, some fields of the `Product` are common for all
countries (_weight, EAN, ..._), and others depend on the country
(_description, title and price_new_).
**COUNTRY_CODES** - Accepted values are :
* AP platform:
* ja-jp : Japan
* en-au : Australia
* EU platform:
* fr-fr : France
* fr-be : Belgium
* es-es : Spain
* de-de : Germany
* de-at : Austria
* it-it : Italy
* en-gb : United Kingdom
* nl-nl : Netherlands
* pt-pt : Portugal
* en-ie : Ireland
* el-gr : Greece
* sk-sk : Slovakia
* sv-se : Sweden
* US platform:
* en-us : United States
### CSV file format
All files imported through our Back Office or imported using Back Market's API must be in CSV format.
Required field separator is ';'.
Required line separator is the line feed '\n'.
Fields must be surrounded by double quotes.
## Technical Requirements
### API Identification
>
> HTTP Header (will remain the same for every API call):
```http
Content-type: application/json
Accept: application/json
Accept-Language: COUNTRY_CODE
Authorization: Basic YOUR_ACCESS_TOKEN
User-Agent: YOUR_USER_AGENT
```
Each Integrator or Seller should use the following HTTP Header when calling Back Market API endpoints.
The User-Agent is mandatory. Any request without it might be refused by our System.
It should include your company name, application name, version, and a contact email address in this format:
```http
BM-{CompanyName}-{IntegrationName};company@companydomain.com.
```
For example:
```http
BM-Ebay-Invoices;contact@ebay.com
BM-bouygues-automations;contact@bouygues.fr
```
### Web application firewall (WAF) and Bot management
The WAF or bot management may block your requests for security reason. You'll typically receive an HTTP 403 Forbidden
response, possibly with a response body to tell you to challenge your client with Cloudflare.
In 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.
Example HTTP 403 response from WAF:
```http
HTTP/2 403
date: Wed, 16 Apr 2025 11:26:41 GMT
content-type: text/html; charset=UTF-8
referrer-policy: same-origin
cache-control: max-age=15
expires: Wed, 16 Apr 2025 11:26:56 GMT
...
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
server: cloudflare
cf-ray: 931354450813d142-CDG
alt-svc: h3=":443"; ma=86400
```
Example HTTP 403 response for Bot Management protected endpoints:
```json
{
"errors": [
{
"code": "bot-need-challenge",
"message": "Forbidden",
"challengePath": "/testchallengepage"
}
]
}
```
### Traffic limitation
Our standard rate limits are will allow your automations to run fast enough to finish your processes.
However, in case of too many requests beyond what we except on sellers endpoints, you will be presented with an HTTP 429 response from Cloudflare.
Usually you will find the range above 200 requests in 10 seconds being blocked for 10 seconds and for more sensible
endpoints like catalog for example above 20 requests in 10 seconds being blocked for 10 seconds.
### Data limitation
To make sure we can handle and process all the incoming data correctly, we have set-up the following limitation:
**We might not accept more than 2k lines of SKUs to process per hour** on the
following endpoints ([Update Several listings](#update-several-listings) or
on [Update specific listing](#update-specific-listing)) and [Update Listings](#update-listings)) files.
FTP in Back Market is deprecated. If you used to use FTP in order to connect to Back Market
Please contact <partner-support@backmarket.com> to help you to setup an API connexion.
**If this limit is reached, Back Market may refuse the task**, in this case you will receive HTTP responses
with the "429 Too Many Requests" status.
If you have lots of active SKUs, please take into account the [Best Practice](#best-practices)
part of the documentation.
### Questions ?
If you have any questions, please send an email to <partner-support@backmarket.com>
Please note that this mail is temporary as we will deploy a new seller support center
that will assist you.
## F.A.Q. and Contact
Please [click here](https://merchant-support.backmarket.com/hc/en-us) to access your Seller Support Center
where you can find our F.A.Q. or contact us.
If you have never signed in to the Seller Support Center, you can
read this [tutorial](statics/How-to-connect-to-SSC.pdf) which helps you setup you connection for the first time.
If you have any more questions and are already selling on Back Market, we invite you to contact your account manager.
## Cookbooks
A list of notebooks showcasing different API use cases:
[Winning the BackBox based on small price efforts](https://colab.research.google.com/drive/12jHZ3AQG8mQjjAvulG9zVvfC_psEOKjh?usp=sharing)
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
paths:
/ws/category/tree:
get:
summary: Get category tree
description: |
## Taxonomy
### Categorization & products
`Categories` tree diagram :
<img class="myImg" src="https://s3-eu-west-1.amazonaws.com/backmarket-doc-developer/images_to_download/
category_tree_schema.png" width=100% height=auto alt="">
Diagram of matching `Product` with a leaf `Category` :
<img class="myImg"
src="https://s3-eu-west-1.amazonaws.com/backmarket-doc-developer/images_to_download/category_product.png"
width=100% height=auto alt="">
<br>
The matching of a `Product` to a `Category` is made using its `marketplace_category_id`. The `category_id` of
the model `Product` matches the `marketplace_category_id` of the model `Category` (and not the `category_id`).
On Back Market, many types of `Products` are being sold: smartphones, phones, computers, coffee machines, etc.
Each `Product` created on our marketplace is classified within the 3 levels of `Categories`.
A `Product` can only be attached to one `Category leaf` (the last level of the Category tree).
`Category 2` and `Category 3` can only have one parent `Category`.
If it is a `leaf Category`, it cannot have any `child Category`. Otherwise,
`Category` can have several `children Categories`.
For each `Product` on Back Market several merchants can publish an offer.
If a `Product` does not exist on our platform, a merchant can create the `Product`.
The newly created `Product` will then go through a validation process by our
team (usually within 12 hours of a working day) before being put online.
In addition to some mandatory fields for each `Products` (_cf._ Table 3), the `leaf Category` defines `Attributes`
(which can be **mandatory** or **optional**) to provide
during the creation of a `Product`.
Therefore, when creating a `Product`, some fields will depend on the `leaf Category` of
the `Product` (category `Attributes`) you create.
Others will always be the same for every `Products` you create (_cf._ Table 3).
**In summary, if you want to create a `Product`, you will have to provide**:
* The `EAN` (European Article Number) of the `Product`.
* **Mandatory** product fields (_cf._ Table 3).
* The `marketplace_category_id` (to match the `Product` with its `leaf Category`).
* **Mandatory** category `Attributes` (which depend on the `leaf Category`).
Only the merchant who created the `Product` can update it.
**The update can only be done before our team validates the product.**.
#### Table 1 - `Category` model
<table class="table">
<thead>
<tr>
<th>Field name</th>
<th>Type/Size</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>category_id</td>
<td>Int</td>
<td>Unique ID of the category.</td>
</tr>
<tr>
<td>category_name</td>
<td>String/200</td>
<td>Name of the category.</td>
</tr>
<tr>
<td>marketplace_category_id</td>
<td>Int</td>
<td>Unique Id of the `Category` to provide on `Product` creation. Allows matching
of a `Product` to its `leaf Category`.</td>
</tr>
<tr>
<td>is_leaf</td>
<td>Bool</td>
<td>If True, the `Category` does not have any child & `Products` can be associated with
it.</td>
</tr>
<tr>
<td>attributes</td>
<td>Array[`Attributes`]</td>
<td>List of `Attributes` attached to a `leaf Category`.</td>
</tr>
<tr>
<td>childrens</td>
<td>Array[`Category`]</td>
<td>List of children `Categories`. Empty if is_leaf==True.</td>
</tr>
</tbody>
</table>
#### Table 2 - `Attribute` model
<table class="table">
<thead>
<tr>
<th>Field name</th>
<th>Type/Size</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>field</td>
<td>String/200</td>
<td>Field to provide during creation of a `Product`.</td>
</tr>
<tr>
<td>field_name</td>
<td>String/200</td>
<td>Name of the `Attribute`.</td>
</tr>
<tr>
<td>type</td>
<td>Int</td>
<td>
<div>0: "Decimal"</div>
<div>1: "Integer"</div>
<div>2: "String"</div>
<div>3: "Multiple_Choice"</div>
</td>
</tr>
<tr>
<td>allowed_values</td>
<td>String/1000</td>
<td>If `type` is "Multiple_Choice": accepted values separated by ",".</td>
</tr>
<tr>
<td>required</td>
<td>Bool</td>
<td>True if the attribute is mandatory to create the Product.</td>
</tr>
</tbody>
</table>
#### Table 3 - `Product` model
Fields to provide are the same for every `Product` and don't depend on its `Category`.
A **unique product ID** is provided at the creation of a `Product`.
<table class="table">
<thead>
<tr>
<th>Field name</th>
<th>Type/Size</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>product_id</td>
<td>String</td>
<td>Unique product Id. Provided by Back Market at the creation of a `Product` for purpose of matching to `Listings`.</td>
</tr>
</tbody>
</table>
**Required fields:**
<table class="table">
<thead>
<tr>
<th>Field name</th>
<th>Type/Size</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ean</td>
<td>String/13</td>
<td>`EAN` used to match an already existing `Product`. A new `Product` is created
if there is no match. Also used to match a Listing at its creation if the Back Markert ID is not provided.</td>
</tr>
<tr>
<td>category_id</td>
<td>Int</td>
<td>Matches the marketplace_category_id. Unique ID of a selected `Category`,
to be provided during creation of a `Product`. Allows matching a `Product` to its `leaf Category`.</td>
</tr>
<tr>
<td>title</td>
<td>String/200</td>
<td>Product title.</td>
</tr>
<tr>
<td>description</td>
<td>Text</td>
<td>Product description.</td>
</tr>
<tr>
<td>brand</td>
<td>String/100</td>
<td>Product brand.</td>
</tr>
<tr>
<td>price_new</td>
<td>Decimal</td>
<td>Market price of the product sold new.</td>
</tr>
<tr>
<td>weight</td>
<td>Int > 1</td>
<td>Weight in grams (g).</td>
</tr>
<tr>
<td>image1</td>
<td>String/1000</td>
<td>First image.</td>
</tr>
</tbody>
</table>
**Optional fields:**
<table class="table">
<thead>
<tr>
<th>Field name</th>
<th>Type/Size</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>image2</td>
<td>String/1000</td>
<td>Second image.</td>
</tr>
<tr>
<td>image3</td>
<td>String/1000</td>
<td>Third image.</td>
</tr>
<tr>
<td>image4</td>
<td>String/1000</td>
<td>Fourth image.</td>
</tr>
<tr>
<td>image5</td>
<td>String/1000</td>
<td>Fifth image.</td>
</tr>
<tr>
<td>image6</td>
<td>String/1000</td>
<td>Sixth image.</td>
</tr>
<tr>
<td>width</td>
<td>String/200</td>
<td>Width.</td>
</tr>
<tr>
<td>height</td>
<td>String/200</td>
<td>Height.</td>
</tr>
<tr>
<td>depth</td>
<td>String/200</td>
<td>Depth.</td>
</tr>
</tbody>
</table>
<aside class="notice">
To create a `Product` you need to at least provide mandatory product fields and mandatory category `Attributes` of the `leaf
Category`.
</aside>
#### Fields depending on the country_code
For each `Product`, some fields depend on the country and some are in common for every country.
Here is the list of fields for the Product model that vary by country (and need to be specified for each country):
* 'title'
* 'description'
* 'price_new'
## Get category tree
If you want to sell a new `Product`, which has not already been added on our marketplace by another merchant, you will need to create it.
In this case, you need to select one `leaf Category` and check the corresponding `Attributes`.
This will let you know all mandatory or optional `Attributes` you need to provide during the creation of the `Product`.
This section allows to retrieve Back Market's `Category tree`, including all its branches.
### Endpoint
<aside class="success">
HTTP GET request: <a target="_blank" href="https://www.backmarket.fr/ws/category/tree/"> https://www.backmarket.fr/ws/category/tree/</a>
</aside>
### HTTP request
No request Body.
```javascript
# Example of JSON response - Status code 200
[
{
"category_id":1,
"category_name":"T\u00e9l\u00e9phones",
"marketplace_category_id":-1,
"is_leaf":false,
"attributes":[],
"childrens":[
{
"category_id":2,
"category_name":"Old School",
"marketplace_category_id":-10001,
"is_leaf":false,
"attributes":[],
"childrens":[
{
"category_id":3,
"category_name":"Old School",
"marketplace_category_id":1,
"is_leaf":true,
"attributes":[
{
"field":"color",
"field_name":"Couleur",
"type": 2,
"allowed_values":"",
"required":true
},
{
"field":"screen_size",
"field_name":"Taille \u00e9cran (pouces)",
"type": 2,
"allowed_values":"",
"required":true
},
{...}
],
"childrens":[]
}
]
},
{...}
]
},
{...}
]
```
### Response parameters
_**`Category` fields :**_
<table class="table">
<thead>
<tr>
<th>Field name</th>
<th>Type/Size</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>category_id</td>
<td>Int</td>
<td>Unique ID of the `Category`.</td>
</tr>
<tr>
<td>category_name</td>
<td>String/200</td>
<td>Name of the `Category`.</td>
</tr>
<tr>
<td>marketplace_category_id</td>
<td>Int</td>
<td>Unique Id of the `Category` to provide during the creation of a `Product`. Allows matching
a `Product` & its `leaf Category`.</td>
</tr>
<tr>
<td>is_leaf</td>
<td>Bool</td>
<td>If True, the `Category` does not have any children & `Products` can assigned to it.</td>
</tr>
<tr>
<td>attributes</td>
<td>Array[Attributes]</td>
<td>List of `Attributes` attached to a `leaf Category`.</td>
</tr>
<tr>
<td>childrens</td>
<td>Array[Category]</td>
<td>List of children `Categories`. Empty if is_leaf==True.</td>
</tr>
</tbody>
</table>
_**`Attribute` fields :**_
<table class="table">
<thead>
<tr>
<th>Field name</th>
<th>Type/Size</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>field</td>
<td>String/200</td>
<td>Field to provide at `Products` creation.</td>
</tr>
<tr>
<td>field_name</td>
<td>String/200</td>
<td>Name of the `Attribute`.</td>
</tr>
<tr>
<td>type</td>
<td>Int</td>
<td>
<div>0: "Decimal"</div>
<div>1: "Integer"</div>
<div>2: "String"</div>
<div>3: "Multiple_Choice"</div>
</td>
</tr>
<tr>
<td>allowed_values</td>
<td>String/1000</td>
<td>If `type` is "Multiple_Choice": accepted values separated by ",".</td>
</tr>
<tr>
<td>required</td>
<td>Bool</td>
<td>True if the `Attribute` is mandatory to create the `Product`.</td>
</tr>
</tbody>
</table>
### Response status codes
<table class="table">
<thead>
<tr>
<th>Status code</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="success">
<td>200</td>
<td>
OK.
</td>
</tr>
<tr class="danger">
<td>400</td>
<td>
Bad request.
</td>
</tr>
<tr class="danger">
<td>403</td>
<td>
Forbidden.
</td>
</tr>
<tr class="danger">
<td>404</td>
<td>
Webservices unavailable.
</td>
</tr>
</tbody>
</table>
## Create/Update category
`Category` cannot be created nor updated by merchants.
You might want to create a `Category` if you wish to sell a new kind of `Product`, which cannot be referenced in already existing Categories.
You might also want to update a `Category` in the event that you wish to create a `Product` that already exists in the relevant `Category` but for which you can't provide all the mandatory `Attributes`. In this case, you would want the **mandatory** field to become **optional**.
If you wish to create or update a `Category`, please <a target="_blank" href="https://merchant-support.backmarket.com/hc/en-us">let us know</a>.
x-tier: 3
tags:
- Categories
operationId: get-bm-catalog-category
security:
- ApiKeyAuth: []
- BasicAuth: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CategoryTree'
'401':
description: Unauthenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV2'
'403':
description: Forbidden. Authenticated user is not a merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV2'
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'
/ws/category/tree/{categoryId}:
parameters:
- in: path
name: categoryId
required: true
example: 1
schema:
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:
summary: Get category branch
description: |
Retrieve a specific `Category` branch. This will only give you access to what's below on the branch. This means that you won't be able to access the parent `Categories`, but only children `Categories` and `Attributes`.
You can retrieve `Attributes` from a specific `leaf Category` with the following endpoint, by providing its category ID.
x-tier: 3
tags:
- Categories
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryTree'
'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: Category not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV1'
/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:
# --- truncated at 32 KB (219 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/back-market/refs/heads/main/openapi/back-market-openapi-original.yml
ⓘ
Where this information came from
This is an independent, third-party profile of Back Market API, published by
API Evangelist. We do not operate, host, resell, or
support these APIs, and we are not affiliated with or endorsed by the company unless stated above.
Everything here is built from publicly available information — the company's own site,
developer portal, documentation, public repositories, and the specifications it publishes for public use.
Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's
public API artifacts, scored against a published rubric. They are not certifications,
endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and
you do not need to justify the request. A removed company is recorded as unrated, never scored
zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.