NAV Navbar
Logo

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 merchants to sell 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 :

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 merchants 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 merchants with long-tail catalogs as well as a large amount of sales.

2 - Back-office:

Our back-office 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. to get answers to your questions. Contact us if you still have further questions.

Feedback

At Back Market, we always want to improve our solutions. Please Give Us Feedback 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 merchant support center that will assist you.

Taxonomy

Categorization & products

Categories tree diagram :

Diagram of matching Product with a leaf Category :


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 (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:

Only the merchant who created the Product can update it. The update can only be done before the product validation by our team.

Table 1 - Category model

Field name Type/Size Description
category_id Int Unique ID of the category.
category_name String/200 Name of the category.
marketplace_category_id Int Unique Id of the `Category` to provide on `Product` creation. Allows matching of a `Product` to its `leaf Category`.
is_leaf Bool If True, the `Category` does not have any child & `Products` can be associated with it.
attributes Array[`Attributes`] List of `Attributes` attached to a `leaf Category`.
childrens Array[`Category`] List of children `Categories`. Empty if is_leaf==True.

Table 2 - Attribute model

Field name Type/Size Description
field String/200 Field to provide during creation of a `Product`.
field_name String/200 Name of the `Attribute`.
type Int
0: “Decimal”
1: “Integer”
2: “String”
3: “Multiple_Choice”
allowed_values String/1000 If `type` is “Multiple_Choice”: accepted values separated by “,”.
required Bool True if the attribute is mandatory to create the Product.

Table 3 - Product model

Fields to provide are the same for every Product and don’t depend on its Category. A unique Back Market ID (color) is provided at the creation of a Product. Required fields are denoted using: color whereas optional fields using: color.

Field name Type/Size Description
backmarket_id Int Unique product Id. Provided by Back Market at the creation of a `Product` for purpose of matching to `Listings`.
ean String/13 `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.
category_id Int 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`.
title String/200 Product title.
description Text Product description.
brand String/100 Product brand.
price_new Decimal Market price of the product sold new.
weight Int > 1 Weight in grams (g).
image1 String/1000 First image.
image2 String/1000 Second image.
image3 String/1000 Third image.
image4 String/1000 Fourth image.
image5 String/1000 Fifth image.
image6 String/1000 Sixth image.
width String/200 Width.
height String/200 Height.
depth String/200 Depth.

Fields depending on the country_code :

For each Product, some fields depend the country and some are in common for every country.

Here is the list of every fields that are different depend on the country for the model Product (therefore that you need to specify for each country):

Product & listings

Summary of the product/listing structure :

One example of product & listing :

Every merchant can make a sell offer or a “listing” on a product in order to sell it on our marketplace. Our algorithm will choose which listing will win “The Buybox” and thus be displayed on our website.

Products sold on Back Market are refurbished so their aesthetic state can vary. To help consumers to make up their mind and avoid deception, each listing is defined by one of the following states:

For each state, merchants need to make a specific listing. A listing has mandatory and optional fields. These fields are the same for every listing you will be making on Back Market (cf Table 4).

Table 4 - Listing model

Listing models are the same for every created listing and don’t depend on its product. A unique listing ID (color) is provided by Back Market during creation of a listing. Required fields are denoted using: color whereas optional fields using: color.

Field name Type/Size Description
listing_id Int Unique listing Id. Provided by Back Market at the listing creation. Used for listing updates.
sku String/200 SKU used to match an existing listing (also a listing unique Id). A new listing is created if there is no match. Used for a listing update if the listing ID is not provided. [?]
quantity Int Stock available.
price Decimal Your price.
state Enum (Int)
0: Super Shiny (perfect state)
1: Gold (as good as new)
2: Silver (very good state)
3: Bronze (good state)
4: Stallone (acceptable) - Default
warranty_delay Int Warranty delay (6 month minimum).
comment String/500 Comment.
currency String/10 Currency used (default EUR).
shipper_1 Enum (String)
Shipper 1:
Amazon
Chronopost
Colissimo
Correos Express
DB Schenker
DHL
DPD
Exapaq
Geodis
GLS
Mondial Relay LD1
Mondial Relay LDS
NACEX
Socolissimo
TNT
Transporteur privé
UPS
Others (call us to add your shipper)
shipping_price_1 Decimal Shipping price 1.
shipping_delay_1 Int Shipping delay 1 (hour)
shipper_2 Enum (String) Shipper 2
shipping_price_2 Decimal Shipping price 2.
shipping_delay_2 Int Shipping delay 2 (hour)
shipper_3 Enum (String) Shipper 3
shipping_price_3 Decimal Shipping price 3.
shipping_delay_3 Int Shipping delay 3 (hour)
snowden Bool Only for iPhones. Values (case-sensitive): “True” if TouchID is broken, else “False”. Default (column not set or unrecognized value): “False”.
noisy_camera Bool Only for smartphones and tablets. Values (case-sensitive): “True” if a noise is emitted when pictures are taken with the camera (local legislation), else “False”. Default (column not set or unrecognized value): “False”.

A listing is matched with an existing product either with its EAN or with its Back Market ID (the Back Market ID has priority in case of conflicts).

You can create both a listing and its matching product at the same time. In this case, you will have to provide:

Or you can create a listing for an existing product. In that case, you will have to provide:

During creation of a listing, a unique listing_id is attributed to the listing.

Fields depending on the country_code :

For each Listing, some fields depend the country and some are in commun for every country.

Here is the list of every fields that are different depend on the country for the model Listing (therefore that you need to specify for each country):

Orders

Summary of the Product/Listing structure :

Orders workflow diagram :

Orderlines workflow diagram :

When a customer makes a payment on Back Market, an Order is to the merchants concerned. Each Order is composed of one or several Orderlines. An Orderline is defined by a quantity of a specific listing from an order placed by a customer to a specific merchant (Ordeline contains also specific information about the customer: billing, shipping addresses etc.). [cf. Figure: Summary of the Product/Listing structure]

Diagram beside: _Summary of the Product/Listing structure, shows an example of a Customer Z who makes a payment to buy 1 Product A and 1 Product B from Merchant X, and 4 Products C from Merchant Y._

Merchants only have to deal with Orderlines inside of an Order. All Orders will be treated automatically by our service. Therefore, the state of an Order cannot be modified by merchants. Merchants receive an Order with the state 1. The processing of an Order is not over until all its Orderlines have reached a final state (cf. Table 6).

During the shipping, all Orderlines are gathered in the same package. Therefore, it is not necessary to specify an Orderline ID when updating an Orderline to the state 3 (All Orderlines of this Order will be set to this state automatically).

Table 5 - Order State

Color-codes for the State: New Order, Temporary States, Final States.

State Description
0 New `Order`. Payment validation is pending. We are doing verifications to check the customer identity. The `Orders` in this `State` must not be shipped.
1 Payment is checked & validated. The merchant has to process (accept or cancel) the `Orderlines`.
3 `Order` shipping is pending. The payment and the `Order` (all `Orderlines`) have been validated. The merchant has to ship the package to the customer.
8 Order is not paid. Payment process has failed, the merchant must ignore this `Order`.
9 Order processed. The merchant has shipped the package.

Table 6 - States for Orderlines

Color-codes for the Orderlines: New Order, Temporary States, Final States.

State Description Possible next states
0 New `Orderline`. The merchant has to wait for payment confirmation. Not possible
1 `Orderline` is paid. The merchant has received the payment and must validate or cancel the `Orderline`. State 2 or 4
2 `Orderline` is accepted by the merchant, who must now prepare the `Product` for shipment. State 3 or 5
3 The merchant has deliver the `Orderline` to the shipping company. The package delivery is in progress. State 6
4 `Orderline` is cancelled. The customer will be refunded for the `Orderline`. Not possible
5 Orderline is refunded before shipping. Not possible
6 Orderline is refunded after shipping. The customer made a refund request. Not possible
7 Orderline is not paid. The payment has been refused by the bank. Not possible

Table 7 - Order model

Field name Type/Size Description
order_id Int Unique id of the `Order`. Used to update `Orderline(s)` of an `Order` .
merchant_id Int Unique id of the merchant.
shipping_address Address Shipping address: please refer to the Table 8 for address description.
billing_address Address Billing address: please refer to the Table 8 for address description.
price Decimal `Order` total price (including taxes) without the shipping price.
shipping_price Decimal Shipping total price (including taxes).
currency String/3 Used currency.
shipper String/200 Designated shipping company.
tracking_number String/200 Tracking number of the package.
tracking_url String/300 Tracking Url of the package.
date_creation Datetime Date of the Order. Format: YYYY-MM-DD:hh:mm:ss.
date_modification Datetime Date of the last modification. Format: YYYY-MM-DD:hh:mm:ss.
date_payment Datetime Date of the payment. Format: YYYY-MM-DD:hh:mm:ss.
date_shipping Datetime Date of the shipping. Format: YYYY-MM-DD:hh:mm:ss.
state Enum (Int) Refere to Table 5 for the Order states details.
orderlines [OrderLine] List of `Orderlines` indexed by SKU (stock keeping unit).
country_code Enum (String)
Accepted-values:
fr-fr: France (default)
fr-be: Belgium
es-es: Spain
de-de: Germany
it-it: Italy
en-gb: United Kingdom
nl-nl: Netherlands

Table 8 - Address model

Field name Type/Size Description
company String/254 Company name.
last_name String/200 Last name.
first name String/200 First name.
gender Enum (Int)
0: Mr
1: Mrs
street String/254 Street number and designation.
street2 String/254 Floor, door code.
postal_code String/10 Zip code.
city String/200 City.
country String/100 Country.
phone String/14 Phone number.
email String/200 Email address.

Table 9 - OrderLine model

Field name Type/Size Description
listing Listing `Listing` that matches the `Orderline`.
quantity Int Quantity of ordered products.
price Decimal Unitary price (including taxes) of the `Listing` without shipping costs.
shipping_price Decimal Unitary price of the shipping (including taxes).
currency String/3 Used currency.
state Enum (Int) Refere to Table 6 for Orderlines states description.
return_reason Enum (Int)
0: Stock mistake.
1: Withdrawal during the legal 14 day period.
11: Does not live at provided address.
12: The parcel did not reach its destination.
13: Lost parcel.
21: Faulty product on opening of the package.
22: Failure during first use.
23: Failure during warranty period.
24: Non-compliant product.
25: Other.
return_message String/500 Message sent to the customer for a cancellation or a refund.
backcare Bool True if this orderline is covered by the Backcare service
backcare_price Int The backcare price in cents.

Getting Started

If you did not yet read the page on taxonomy, please do it before proceeding.

Account :

After validation by our team, each merchant 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 create an account 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: * Registration on EU platform * Registration on US platform

If you already have an account, you can directly access your Back Office:

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 :

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):

Content-type: application/json
Accept: application/json
Accept-Language: COUNTRY_CODE
Authorization: Basic YOUR_ACCESS_TOKEN
User-Agent: YOUR_USER_AGENT

Each Integrator or Merchant 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. Please use your Seller name on Back Market or your ERP / Integrator name.

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 or on Update specific listing) and 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 part of the documentation.

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 merchant support center that will assist you.

Fields to Provide

What would you like to create ?



{$ actionText $}


Something went wrong while trying to retrieve possible categories!
Please try later to get correct inputs for the column “category_id” of your CSV.

Please choose a `Category` for the new `Product`:

You chose category = {$ specificCategory.category_name $}

… of marketplace_category_id = {$ specificCategory.marketplace_category_id $}

You should enter “{$ specificCategory.marketplace_category_id $}” in the column “category_id” of your CSV.


OR

Select a category by branch:


Category 1 (category level 1) :

Category 2 (category level 2) :

Category 3 (leaf Category) :

You chose category = {$ selectedCategory3.category_name $}

… of marketplace_category_id = {$ selectedCategory3.marketplace_category_id $}

You should enter “{$ selectedCategory3.marketplace_category_id $}” in the column “category_id” of your CSV.

You wont be able to create the Product without choosing its leaf Category.


Press the button to download a template of a CSV file matching the action you want to perform:



We use ‘ean’ rather than the ‘backmarket_id’ in the generated CSV file.

For CSV imports through Back-Office:

Column ‘lang’ designating the country, in which the `Listing/product` is sold, must be provided. The country codes are formed as follows: xx-xx (ex: fr-fr for France). See possible values in the section Getting Started.


Color-codes:
Must provide one of the 2 fields.
Field is required.
Field is optional.

Table summarizing all fields for selected action:

Type field Field name Type/Size
Matching `Listing` with `Product`. {$ z.fieldname $} {$ z.type_size $}
`Listing` field {$ x.fieldname $} {$ x.type_size $}
`Product` field {$ y.fieldname $} {$ y.type_size $}
category `Attribute` {$ d.field $} {$ get_attributes_type(d.type, d.allowed_values) $}
category `Attribute` {$ d.field $} {$ get_attributes_type(d.type, d.allowed_values) $}

Back-office

Back-office guide

To access your Back Office on Back Market, click HERE.

Import CSV for products and listings creation:

Fields to provide

Please check the section Fields To Provide for more information about fields you have to provide depending on the Category of your new Product.

Country code

Be careful, if during Product and/or Listing creation you select “All languages” you must also add the ‘lang’ column to the CSV file. You then need to specify a language for each line in this column.

If during Product and/or Listing creation you select a specific language, you wont need to specify ‘lang’/adding the language column.

Import tracking numbers

On your orders page, you can import a CSV file containing all your new tracking numbers. Provide a CSV file following this template:

"Numéro de commande";"Numéro de tracking";"Tracking URL";"Shipper"
"1111";"AZERTY";"https://....";"XXX"

Only orders waiting for shipment will be updated.

Note that Tracking URL and Shipper are optional.

Back-office presentation

Click HERE to download our Back-office presentation.

API Generics

API Generics guide

HTTP Header (will remain the same for every API call):

Content-type: application/json
Accept: application/json
Accept-Language: COUNTRY_CODE
Authorization: Basic YOUR_ACCESS_TOKEN
User-Agent: YOUR_USER_AGENT

Our API is the most efficient way to work with Back Market, for big merchants as well as merchants with large quantities of Products. It allows to synchronize information with our database in real time and it is designed to save you time.

Account :

At this point you should already have an account (at least pending validation). You can use your username & password to access our API through the basic authentication.

With the same password, you can ask for an access token. To ask for a token.

[In the US] please go to: “Support” tab in your Back Office.

[In Europe] please go to: “Support” tab in your Back Office.

At the very bottom of the page you should introduce your password and push the button:

Your token gives you a more secure access to our API. It will remain the same as long as you don’t change your password. You should request a new token every time you change your password.

Endpoint URL format :

Please note that, when calling our endpoints, you should be aware of those specifities:

Example: HTTP GET request: https://preprod.backmarket.com/ws/orders

Example: HTTP GET request: https://www.backmarket.com/ws/orders

Country code :

For each API call, you will choose a concerned country by adding the country code in the header. If the country code is not provided, the default value will be fr-fr.

Test environment :

Back Market provides also a test environment platform. You will need to create another merchant account dedicated to the test environment. This can be done here:

https://preprod.backmarket.fr/bo_merchant/subscribe.

This account will be validated by our team. You should also request a sandbox token as well.

You will be then able to test each endpoint by replacing 'www' by 'preprod' in the URL. For instance, in order to recover your Listings in your test environment:

GET request https://preprod.backmarket.fr/ws/listings

Best practices

In this section, we will talk about the best practices on Back Market. This will help you prevent being penalized by our algorithm and to win more Buyboxes.

Info

You should NOT send us any information twice if you received the 200 HTTP response the first time. This status code means that the information has been processed by our services. If you received another response status, this is not due to a missing information in your request (404 or 500 for instance), try again 5 minutes later.

Update to put a listing offline

DO NOT send us a quantity of 0 for a Listing if it is already 0 (listing offline) in our database. Sending us this information once is enough. Once a Listing is closed, it won’t come back online without any reason.

Update a specific listing online

Instantly update the difference in products quantity: (we will refer to this difference further on as the _delta) whenever a quantity has changed on your side (you have sold a Listing on another marketplace), you should send us this information as soon as possible for corresponding specific listing. No HTTP GET request is necessary in this case, since you already know that there should be a delta. If you receive the HTTP response: 200, the information has been taken into account.

More information about updating the delta is provided in the Section Update specific listing.

Update catalog

When you use our endpoint allowing for update of several Listings (described in the section Update listings) an additional time delays can be expected. As a consequence a delta can be generated because of these delay (our database is not synchronized with yours), which can further penalize you (if an Order was cancelled).

Send us your full catalog including every new available stock once a day: Make an HTTP GET request on the following endpoint: https://www.backmarket.fr/ws/listings/ to retrieve the actual state of your Listings in our database, before making a POST request. You will then know which listing quantities need to be changed and it will prevent you from sending us the duplicates. DO only POST request for the Listings with a Delta or new Listings.

If you are not able to update specific listings after a HTTP GET request and thus calculate the corresponding delta, please proceed with the POST request at a certain frequency:

If you are not able to calculate the delta nor check available quantities at a certain frequency, please proceed with a POST request (one per hour at most). Note, that this is not the best solution because our databases will not be synchronised resulting further in you penalization, in case of an Order cancellation. Moreover, sending us information every 5 minutes without taking anything into account is considered as Spam by Back Market. It can jeopardize our website, therefore will be even more penalized.

If you have noticed a bug on our side or if you have any difficulties, please contact us.

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.

Please refer to the section Fields To Provide to know, which fields are mandatory depending on the Category you choose for the Product. This section gives also an overview of every possible Category .

Endpoint :

HTTP request :

No request Body (refer to Header in the Intro section)

# 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 :

Field name Type/Size Description
category_id Int Unique ID of the `Category`.
category_name String/200 Name of the `Category`.
marketplace_category_id Int Unique Id of the `Category` to provide during the creation of a `Product`. Allows matching a `Product` & its `leaf Category`.
is_leaf Bool If True, the `Category` does not have any children & `Products` can assigned to it.
attributes Array[Attributes] List of `Attributes` attached to a `leaf Category`.
childrens Array[Category] List of children `Categories`. Empty if is_leaf==True.

Attribute fields :

Field name Type/Size Description
field String/200 Field to provide at `Products` creation.
field_name String/200 Name of the `Attribute`.
type Int
0: “Decimal”
1: “Integer”
2: “String”
3: “Multiple_Choice”
allowed_values String/1000 If `type` is “Multiple_Choice”: accepted values separated by “,”.
required Bool True if the `Attribute` is mandatory to create the `Product`.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Webservices unavailable.

Get category branch

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:

Section Fields To Provide gives an overview of all fields for a given Category as well as all Categories.

The Endpoint :

HTTP request :

No request Body (refer to Header in the Intro section)

Request filter params for URL :

Fieldname Description Example
category_id Unique `category_id` of the root `Category` of a given branch. https://www.backmarket.fr/ws/category/tree/2
# Example of a JSON response - with Status code 200:

// Let s take an example of a Category on level 2 with category_id=2.
// URL: https://www.backmarket.fr/ws/category/tree/2

{
    "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 écran (pouces)",
            "type": 2,
            "allowed_values":"",
            "required":true
            },
            {
            "field":"storage",
            "field_name":"Capacité de stockage (Go)",
            "type": 2,
            "allowed_values":"",
            "required":false
            },
            {...}
        ],
        "childrens":[]
        },
        {...}
    ]
}

Response parameters :

Category fields :

Field name Type/Size Description
category_id Int Unique ID of the `Category`.
category_name String/200 Name of the `Category`.
marketplace_category_id Int Unique Id of the Category to provide during creation of a `Product`. Allows matching a `Product` to its `leaf Category`.
is_leaf Bool If True, the `Category` doesn’t have any children & `Products` can be attributed to it.
attributes Array[Attributes] List of `Attributes` related with a `leaf Category`.
childrens Array[Category] List of children `Categories`. Empty if is_leaf==True.

Attribute fields :

Field name Type/Size Description
field String/200 Field to provide at the creation of a `Product`.
field_name String/200 Name of the `Attribute`.
type Int
0: “Decimal”
1: “Integer”
2: “String”
3: “Multiple_Choice”
allowed_values String/1000 If `type` is “Multiple_Choice”: accepted values separated by “,”.
required Bool True if the `Attribute` is mandatory to create a `Product`.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Webservices unavailable.

Get my listings

Retrieve all your Listings.

Endpoint :

HTTP request :

No request Body (refer to Header in the Intro section)

Request filter params for URL :

Fieldname Description Example
publication_state Return only the listings having the given publication state. `publication_state` is an integer, for the available choices, please refer to the response table. https://www.backmarket.fr/ws/listings/?publication_state=2
min_quantity Return only the listings with quantity strictly above the indicated number. https://www.backmarket.fr/ws/listings/?min_quantity=2
max_quantity Return only the listings with quantity strictly below the indicated number. https://www.backmarket.fr/ws/listings/?max_quantity=10
# Example of a JSON response - with Status code 200:

{
    "count":1257,
    "next":"https://www.backmarket.fr/ws/listings/?page=2",
    "previous":null,
    "results":[
        {
            "listing_id":1,
            "sku":"0885909406531-2",
            "title":"iPhone 4 16 - Black - Unlocked",
            "state":3,
            "price":"90.00",
            "max_price": "150.50",
            "quantity":30,
            "publication_state":2,
            "comment":"Vendeur pro - garantie 6 mois - contr\u00f4l\u00e9 nettoy\u00e9 d\u00e9bloqu\u00e9 tout op\u00e9rateur - reconditionn\u00e9 en bon \u00e9tat pouvant pr\u00e9senter des micros rayures - accessoires compatibles - Livr\u00e9 sous 24-48h",
            "warranty_delay":6,
            "shippings":[
                {
                    "shipping_price":"0.00",
                    "shipping_delay":48,
                    "shipper":"Autre",
                    "shipper_display":"Autre",
                    "country_code":"fr-fr"
                }
            ],
            "currency":"EUR",
            "backmarket_id":1,
            "images":[]
        },
        {
            "listing_id":2,
            "sku":"IPHONE416GONLIB0",
            "state":0,
            "price":"284.00",
            "max_price": "250.00",
            "quantity":100,
            "publication_state":3,
            "comment":"Vendeur pro - garantie 6 mois - contr\u00f4l\u00e9 nettoy\u00e9 d\u00e9bloqu\u00e9 tout op\u00e9rateur - reconditionn\u00e9 et remis \u00e0 neuf - accessoires compatibles - Livr\u00e9 sous 24-48h",
            "warranty_delay":6,
            "shippings":[],
            "currency":"EUR",
            "backmarket_id":1,
            "images":[
                {
                    "image_url": "https://backmarket-dev.s3.amazonaws.com/product_images/145771 7270.08.jpg"
                }
            ]
        },
        {...}
    ]
}

Response parameters :

Listing fields :

Field name Type/Size Description
listing_id Int Unique listing Id. Provided by Back Market at the creation of a `Listing`. Used for listing updates.
sku String SKU used to match to an existing `Listing` (also a listing’s unique Id). A new `Listing` is created if there is no match. Used for a `Listing` update if the listing ID is not provided.
title String The product title.
state Enum (Int)
0: Shiny (perfect state)
1: Gold (as good as new)
2: Silver (very good state)
3: Bronze (good state)
4: Stallone (acceptable)
price Decimal Your price.
max_price Decimal Maximum allowed price for your listing to be online.
quantity Int Stock available.
publication_state Enum (Int)
0: Missing price or comment
1: Pending validation
2: Online
3: Offline
4: Deactivated
comment String Comment.
warranty_delay Int Warranty period (6 month minimum).
shippings Array[Shipping] List of shippings.
backmarket_id Int Enables matching with the listing’s `Product`.
images Array[Images] List of images (image url).

Shipping fields :

Field name Type Description
shipping_price Decimal Price of the `Shipping`.
shipping_delay Int `Shipping` time.
shipper Enum (String)
Amazon
Chronopost
Colissimo
Correos Express
DB Schenker
DHL
DPD
Exapaq
Geodis
GLS
Mondial Relay LD1
Mondial Relay LDS
NACEX
Socolissimo
TNT
Transporteur privé
UPS
Others (call us to add your shipper)
shipper_display String Name displayed to customers.
country_code COUNTRY_CODE Country assigned to the shipping.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Webservices unavailable.

Get buybox data

Allows you to know for each listings if you have some data concerning the buybox. You can call this endpoint once every hour for each country. The pages are not concerned by this limitation: you can call different pages of the API on the same hour.

Endpoint :

HTTP request :

No request Body (refer to Header in the Intro section)

# Example of a JSON response - with Status code 200:

{
   "count": 907,
   "next": "https://www.backmarket.fr/ws/listings_bi/?page=2",
   "previous": null,
   "results": [
       {
           "product": 1219,
           "sku": "SuperSKU",
           "quantity": 10,
           "price": "70.00",
           "buybox": false,
           "price_for_buybox": 60.00,
           "currency": "EUR"
       },
   ...
}

Response parameters :

Listing fields :

Field name Type/Size Description
product Integer The product id
sku String SKU used to match to an existing `Listing` (also a listing’s unique Id). A new `Listing` is created if there is no match. Used for a `Listing` update if the listing ID is not provided.
price Decimal Your price.
quantity Integer Stock available.
buybox Boolean Does your listing has the buybox.
price_for_buybox String If your listing does not have the buybox, the price you will have to set to have it (aka red price).
currency String Currency of the listing, it will depend on the market (“GBP” for UK for instance).

Response status codes :

Status code Description
200 OK.
403 Forbidden.
429 Too many calls.
404 Webservices unavailable.

Get specific listing

Retrieve a specific Listing to check its information.

Endpoint :

The 2 following endpoints provide exactly the same response:

Or working with a filter on:

HTTP request :

No request Body (refer to Header in the Intro section)

Request filter params for URL :

Fieldname Description Example
listing_id Unique listing’s identifier provided by Back Market at the creation of a `Listing`. Field listing_id in previous section (Get my listings).
https://www.backmarket.fr/ws/listings/detail/?listing_id=1718
https://www.backmarket.fr/ws/listings/1718
sku Listing’s SKU provided by merchant at the creation of a `Listing`. https://www.backmarket.fr/ws/listings/detail/?sku=0802975651245

If you don’t have either the sku nor the listing_id, you can retrieve them by:

GET https://www.backmarket.fr/ws/listings/

# Example of JSON response - Status code 200:

{
    "listing_id":1718,
    "sku":"MBP15C2D241B-2",
    "title":"Apple MacBook Pro 2016",
    "state":3,
    "price":"1800.00",
    "quantity":11,
    "publication_state":2,
    "comment":"Grade B: Produit reconditionné parfaitement fonctionnel, comportant des traces d'usures avancées sur la partie extérieure (rayures et petits chocs) - Livré avec un chargeur dans les 48 heures.",
    "warranty_delay":6,
    "shippings":[
        {
            "shipping_price":"6.00",
            "shipping_delay":48,
            "shipper":"Colissimo",
            "shipper_display":"Colissimo",
            "country_code":"fr-fr"
        }
    ],
    "currency":"EUR",
    "backmarket_id":1136,
    "images":[
        {
            "image_url":"http://www.journaldugeek.com/wp-content/blogs.dir/1/files/2015/11/maxresdefault.jpg"
        },
        {
            "image_url":"http://neurogadget.com/wp-content/uploads/2015/08/MacBook-Pro-2016.jpg"
        },
        {
            "image_url":"http://www.dayherald.com/wp-content/uploads/2015/10/2016-Apple-MacBook-Pro.jpg"
        }
    ],
    "statuscode":200
}

Response parameters :

Listing fields :

Field name Type/Size Description
listind_id Int Unique listing Id. Provided by Back Market at the creation of a `Listing`. Used for `Listing` updates.
sku String SKU used to match with an existing `Listing` (also a listing unique Id). A new listing is created if there is no match. Used for `Listing` update if the listing ID is not provided.
title String The product title.
state Enum (Int)
0: Shiny (perfect state)
1: Gold (as good as new)
2: Silver (very good state)
3: Bronze (good state)
4: Stallone (acceptable)
price Decimal Your price.
quantity Int Stock available.
publication_state Enum (Int)
0: Missing price or comment
1: Pending validation
2: Online
3: Offline
4: Deactivated
comment String Comment.
warranty_delay Int Warranty period (6 month minimum).
shippings Array[Shipping] List of shippings.
backmarket_id Int Enables matching with the listing’s `Product`.
images Array[Images] List of images (image url).

Shipping fields :

Field name Type Description
shipping_price Decimal Price of the `Shipping`.
shipping_delay Int `Shipping` time.
shipper Enum (String)
Type of shipper, accepted values:
Amazon
Chronopost
Colissimo
Correos Express
DB Schenker
DHL
DPD
Exapaq
Geodis
GLS
Mondial Relay LD1
Mondial Relay LDS
NACEX
Socolissimo
TNT
Transporteur privé
UPS
Others (call us to add your shipper)
shipper_display String Name displayed to customers.
country_code COUNTRY_CODE Country assigned to the shipping.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Listing does not exist.

Get my orders

Retrieve all my orders that are neither in state=0 (New Order) nor state=8 (Order not paid).

Please refer to State Description in the Table 5 in Orders Section for details about different possible state

Endpoint :

HTTP request :

No request Body (refer to Header in the Intro section)

Request filter params for URL :

Note: You shouldn’t put the date parameters in between quotes.

Fieldname Description Example
page Page number to recover. The order recovery has 10 entries per page. https://www.backmarket.fr/ws/orders/?page=2
date_creation Filter recovered `Orders` by this date of Order creation. Date format: ‘%Y-%m-%d %H:%M:%S’. https://www.backmarket.fr/ws/orders/?date_creation=2014-06-24 12:55:57
date_payment Filter recovered `Orders` by this date of payment. Date format: ‘%Y-%m-%d %H:%M:%S’. https://www.backmarket.fr/ws/orders/?date_payment=2014-06-24 12:55:57
date_modification Filter recovered `Orders` by this date of last modification. Date format: ‘%Y-%m-%d %H:%M:%S’. https://www.backmarket.fr/ws/orders/?date_modification=2014-06-24 12:55:57
country_code Recover only `Orders` from this country code.
Accepted-value:
fr-fr: France (default)
fr-be: Belgium
es-es: Spain
de-de: Germany
de-at: Austria
it-it: Italy
en-gb: United Kingdom
nl-nl: Netherlands
https://www.backmarket.fr/ws/orders/?country_code=fr-fr
state Recover only `Orders` with this state. https://www.backmarket.fr/ws/orders/?state=1
page-size Define the number of items in the page (maximum is 50) https://www.backmarket.fr/ws/orders/?page-size=50
# Example of a JSON response - with Status code 200:

{
    "count":114,
    "next":"https://www.backmarket.fr/ws/orders/?page=2",
    "previous":null,
    "results":[
        {
            "order_id":69,
            "shipping_address":{
                "company":"",
                "first_name":"Jack",
                "last_name":"Black",
                "gender":0,
                "street":"8 rue du grenier saint-lazare",
                "street2":"",
                "postal_code":"75003",
                "country":"fr-fr",
                "city":"Paris",
                "phone":"0679393232",
                "email":""
            },
            "billing_address":{
                "company":"",
                "first_name":"Jack",
                "last_name":"Black",
                "gender":0,
                "street":"8 rue du grenier saint-lazare",
                "street2":"",
                "postal_code":"75003",
                "country":"fr-fr",
                "city":"Paris",
                "phone":"0679393232",
                "email":""
            },
            "delivery_note": "https://d28i4xct2kl5lp.cloudfront.net/delivery_note/1519221434.69.pdf",
            "tracking_number":"My tracking number",
            "tracking_url":"www.colissimo.fr/my_tracking_url",
            "shipper_display":"Colissimo",
            "date_creation":"2014-10-26T03:13:33Z",
            "date_modification":"2016-06-08T10:13:41Z",
            "date_shipping":null,
            "date_payment":null,
            "state":9,
            "price":"229.00",
            "shipping_price":"0.00",
            "currency":"EUR",
            "country_code":"fr-fr",
            "paypal_reference": null,
            "installment_payment": false,
            "payment_method": "CARD",
            "sales_taxes": "25.80",
            "orderlines":[
                {
                    "id":76,
                    "date_creation":"2016-05-26T02:13:33Z",
                    "state":5,
                    "price":"229.00",
                    "shipping_price":"0.00",
                    "shipping_delay":48, 
                    "currency":"EUR",
                    "return_reason":0,
                    "return_message":"",
                    "listing":"IPHONE416GONLIB0",
                    "listing_id":142,
                    "product":"Apple Iphone 4 16 Go - Noir - D\u00e9bloqu\u00e9",
                    "quantity":1,
                    "imei_numbers":[],
                    "brand": "apple",
                    "product_id": 141,
                    "backcare": true,
                    "backcare_price": 500,
                    "sales_taxes": "15.80"
                },
                {...}
            ]
        },
        {...}
    ]
}

Response parameters :

Fieldname Type Description
count Int Number of `Orders` on this page.
next String Url to the next page. The `Orders` list is paginated by 100 entries.
previous String Url to the previous page. The `Orders` list is paginated by 100 entries.
results [Order] List of `Orders`.

Order fields :

Field name Type/Size Description
order_id Int Unique id of the `Order`. Used to update `Orderline(s)` of a given `Order`.
shipping_address Address Shipping address.
billing_address Address Billing address.
delivery_note String/300 Document to add in package which contains useful information for the client, related to his order.
tracking_number String/200 Tracking number of the package.
tracking_url String/300 Tracking Url of the package.
shipper_display String/200 Name of the Shipper
date_creation Datetime Date of order. Format: YYYY-MM-DD:hh:mm:ss.
date_modification Datetime Date of last modification. Format: YYYY-MM-DD:hh:mm:ss.
date_shipping Datetime Date of shipping. Format: YYYY-MM-DD:hh:mm:ss.
date_payment Datetime Date of payment. Format: YYYY-MM-DD:hh:mm:ss.
state Enum (Int) Present state of the `Order`. See Table 5 from Taxonomy
orderlines [OrderLine] List of `Orderlines` indexed by sku.
price Decimal Total order price (including taxes) without the shipping price.
shipping_price Decimal Total shipping price (including taxes).
currency String/3 Used currency.
country_code Enum (String) Recover only orders from this country.
Accepted-value:
fr-fr: France (default)
fr-be: Belgium
es-es: Spain
de-de: Germany
it-it: Italy
en-gb: United Kingdom
nl-nl: Netherlands
paypal_reference String/17 Paypal reference id.
installment_payment Bool True if the customer choose a payment in ¾ times, if not False.
payment_method String The client payment method. (Eg: CARD, PAYPAL).
sales_taxes Decimal Sales taxes (country/state dependent)

Orderline fields :

Field name Type Description
id Int Unique id of the `Orderline`.
date_creation Datetime Date of creation of the `Orderline`. Date format: ‘%Y-%m-%d %H:%M:%S’.
state Enum (Int) Present state of the `Orderline`. Refer to Table 6 from Taxonomy
price Decimal Price (including taxes) of a `Listing` & warranty without the shipping price.
shipping_price Decimal Unitary shipping price (including taxes).
shipping_delay Int `Shipping` time.
currency String Used currency.
return_reason Enum (Int)
0: Stock mistake.
1: Withdrawal during the legal 14 day period.
11: Does not live at provided address.
12: The parcel did not reach its destination.
13: Lost parcel.
21: Faulty product on opening of the package.
22: Failure during first use.
23: Failure during warranty period.
24: Non-compliant product.
25: Other.
return_message String Message sent to the customer for a cancellation or a refund.
listing String SKU of the `Listing` (matched to a `Listing`).
listing_id Int ID of the `Listing` (matched to a `Listing`).
product String ordered Product (title).
quantity Int Quantity of ordered `Products`.
imei_numbers List of Strings Listing of IMEI.
brand String The brand.
product_id Int The product ID (matched to a `Product`).
backcare Bool True if this orderline is covered by the Backcare service
backcare_price Int The backcare price in cents.
sales_taxes Decimal Sales taxes (country/state dependent)

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Webservices unavailable.

Get specific order

Retrieve a specific Order to get its information and related OrderLines.

Endpoint :

HTTP request :

No request Body (refer to Header in the Intro section)

Request filter parameters for the URL :

Fieldname Description Example
order_id Unique ID of the `Order`. https://www.backmarket.fr/ws/orders/147
# Example of a JSON response - with Status code 200:

{
    "order_id": 171,
      "shipping_address": {
          "company": "",
        "first_name": "Pauline",
        "last_name": "Francis",
        "gender": 1,
        "street": "15 rue Jean Jaures",
        "street2": "",
        "postal_code": "75020",
        "country": "fr-fr",
        "city": "Paris",
        "phone": "0679390411",
        "email": ""
    },
      "billing_address": {
          "company": "",
        "first_name": "Pauline",
        "last_name": "Francis",
        "gender": 1,
        "street": "15 rue Jean Jaures",
        "street2": "",
        "postal_code": "75020",
        "country": "fr-fr",
        "city": "Paris",
        "phone": "0679390411",
        "email": ""
    },
    "delivery_note": "https://d28i4xct2kl5lp.cloudfront.net/delivery_note/1519221434.69.pdf",
      "tracking_number": "",
      "tracking_url": "",
      "shipper": "Colissimo",
      "date_creation": "2016-05-30T22:13:33Z",
      "date_modification": "2016-06-08T10:13:38Z",
      "date_shipping": null,
      "date_payment": "2014-11-25T18:47:45Z",
      "state": 8,
      "price": "199.00",
      "shipping_price": "8.00",
      "currency": "EUR",
      "country_code": "fr-fr",
      "paypal_reference": null,
      "installment_payment": false,
    "payment_method": "CARD",
      "orderlines": [
          {
              "id": 198,
              "date_creation": "2016-05-30T22:13:33Z",
              "state": 1,
              "price": "199.00",
              "shipping_price": "8.00",
              "currency": "EUR",
              "return_reason": 0,
              "return_message": "",
              "listing": "IPHONE48WHITEDEBLO",
              "product": "APPLE IPHONE 4 8 GO BLANC DEBLOQUE TOUT OPERATEUR",
              "quantity": 1,
              "imei_numbers": [],
              "brand": "apple",
              "product_id": 141,
            "backcare": true,
            "backcare_price": 500
        },
        {...}
    ]
}

Response parameters :

Order fields :

Field name Type/Size Description
order_id Int Unique id of the `Order`. Used to update `Orderline(s)` of an `Order`.
shipping_address Address Shipping address.
billing_address Address Billing address.
delivery_note String/300 Document to add in package which contains useful information for the client, related to his order.
tracking_number String/200 Tracking number of the package.
tracking_url String/300 Tracking Url of the package.
shipper String/200 Designated Shipping Company .
date_creation Datetime Date of order. Format: YYYY-MM-DD:hh:mm:ss.
date_modification Datetime Date of last modification. Format: YYYY-MM-DD:hh:mm:ss.
date_shipping Datetime Date of shipping. Format: YYYY-MM-DD:hh:mm:ss.
date_payment Datetime Date of payment. Format: YYYY-MM-DD:hh:mm:ss.
state Enum (Int) Present state of the `Order`. Refer to Table 5 from Taxonomy
orderlines [OrderLine] List of `Orderlines` indexed by sku.
price Decimal Total order price (including taxes) without the shipping price.
shipping_price Decimal Total shipping price (including taxes).
currency String/3 Used Currency.
country_code Enum (String) Recover only Orders from this country code.
Accepted-value:
fr-fr: France (default)
fr-be: Belgium
es-es: Spain
de-de: Germany
de-at: Austria
it-it: Italy
en-gb: United Kingdom
nl-nl: Netherlands
paypal_reference String/17 Paypal reference id.
installment_payment Bool True if the customer choose a payment in ¾ times, if not False.
payment_method String The client payment method. (Eg: CARD, PAYPAL).

Orderline fields :

Field name Type Description
id Int Unique id of the `Orderline`.
date_creation Datetime Date of creation of the `Orderline`. Date format: ‘%Y-%m-%d %H:%M:%S’.
state Enum (Int) Present state of the Orderline. See Table 6 from Taxonomy
price Decimal listing & warranty price (including taxes) without the shipping price.
shipping_price Decimal Unitary shipping price (including taxes).
currency String Used Currency.
return_reason Enum (Int)
0: Stock mistake.
1: Withdrawal during the legal 14 day period.
11: Does not live at provided address.
12: The parcel did not reach its destination.
13: Lost parcel.
21: Faulty product on opening of the package.
22: Failure during first use.
23: Failure during warranty period.
24: Non-compliant product.
25: Other.
return_message String Message sent to the customer for a cancellation or a refund.
listing String SKU of the `Listing` (match to a `Listing`).
product String Ordered product (title).
quantity Int Quantity of ordered products.
imei_numbers List of Strings Listing of IMEI.
brand String The brand.
product_id Int The product ID (matched to a `Product`).
backcare Bool True if this orderline is covered by the Backcare service
backcare_price Int The backcare price in cents.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Webservices unavailable.

Get batch

When a merchant creates a Product and/or Listing, we have to check there is no problem i.e. that all the mandatory information has been provided. For every creation a batch ID will be provided thus allowing you to check the corresponding batch (all errors will be returned).

You will have to check the batch every time you perform a POST request on:

https://www.backmarket.fr/ws/listings/.

To create Listings and/or Products (or update several Listings), you need to provide a CSV file through this HTTP POST. You will then get a batch ID in the response of your call.

Afterwards you can do another API call on this endpoint (after an average delay of 5 minutes) to get the result of the corresponding batch. The field action_status will be equal to 9 if the batch is completed with success, or else it will be equal to 0.

If the batch is done, you will get the result for each SKU/EAN. If the creation of the Listing/Product has failed, the errors details will be returned to you.

Endpoint :

HTTP request :

No request Body (refer to Header in the Intro section)

Request filter params for URL :

Fieldname Description Example
batch_id Returned after POST request: https://www.backmarket.fr/ws/listings/. https://www.backmarket.fr/ws/listings/134

We will now show different examples of 200 responses:


// 1 - The task hasn't been processed.
// You should wait 5 more minutes and check again if the 'action_status' moved to 9.

{
    "task_id": 356,
    "action_status": 0,
    "last_action_error": null,
    "result": {},
    "statuscode": 200
}


// 2 - The task has been processed. The creation was a success.

{
    "task_id": 355,
    "action_status": 9,
    "last_action_error": null,
    "result": {
        "product_errors": {},
        "product_success": {
            "ACERICONIA50032777x99x": {
                "sku": "ACERICONIA50032777x99x",
                "publication_state": 1,
                "backmarket_id": 1151,
                "listing_id": 1738,
                "ean": "5517876947666"
            }
        }
    },
    "statuscode": 200
}


// 3 - The task has been processed. There was an error, which has been identified.

{
    "task_id": 357,
    "action_status": 9,
    "last_action_error": null,
    "result": {
        "product_errors": {
            "ACERICONIA50032777x99x": {
                "ean": "Ce champ ne peut pas être vide."
            }
        },
        "product_success": {}
    },
    "statuscode": 200
}


// 4 - The task has been processed. There was an error, which couldn't been identified.

{
    "task_id": 356,
    "action_status": 9,
    "last_action_error": null,
    "result": {
        "product_errors": {},
        "product_success": {}
    },
    "statuscode": 200
}


Response parameters :

Fieldname Type Description
task_id Int Unique Id of the batch
action_status Int
0: Task incomplete (still in queue).
9: Task completed.
last_action_error Text Task execution error.
result Dict
‘product_success’: if not empty, the creation/update was a success.
‘product_errors’: if not empty, it gives you the error.
It is possible that both are empty, this means that there was an error when action_status=9.
statuscode Int HTTP status code

Contact us if you experience any problems.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Batch does not exist.

Get repair product returns

If you are registered to the BackRepair service, this API will retrieve the list of products that are returned to be repaired.

It will return the products that have been either 1) pickup by the carrier or 2) delivered to a repair factory within the last 30 days.

Endpoint :

HTTP request :

No request Body (refer to Header in the Intro section)

Request filter params for URL :

Fieldname Description Example
page Page number to recover. The product return recovery has 10 entries per page. https://www.backmarket.fr/ws/repair/v1/product-returns?page=3
# Example of a JSON response - with Status code 200:

GET https://www.backmarket.fr/ws/repair/v1/product-returns?page=3

{
  "count": 10000,
  "next": "https://www.backmarket.fr/ws/repair/v1/product-returns?page=4",
  "previous": "https://www.backmarket.fr/ws/repair/v1/product-returns?page=2"
  "results": [
    {
      "imeis": [
        "200",
        {...}
      ],
      "serialNumbers": [
        "200",
        {...}
      ],
      "trackingNumber": "tracking number 20",
      "quantity": 1,
      "sku": "xqjspozcgb",
      "orderId": 38,
      "merchantId": 8,
      "carrier": "ReturnCarrier",
      "customerAddress": {
        "firstName": null,
        "lastName": null,
        "company": "Woodward Group",
        "street": "946 Morgan Plain",
        "street2": "",
        "city": "East Melissa",
        "postalCode": "84606",
        "country": "MG",
        "stateOrProvince": "",
        "phone": null
      },
      "factoryAddress": {
        "firstName": null,
        "lastName": null,
        "company": "Li, Mcdaniel and Goodman",
        "street": "93350 Novak Alley",
        "street2": "",
        "city": "Snyderport",
        "postalCode": "94825",
        "country": "IL",
        "stateOrProvince": "",
        "phone": null
      },
      "pickupDate": "2020-08-20T13:16:49.481133+00:00",
      "deliveryDate": null
    },
    {...}
}


Response parameters :

Fieldname Type Description
count Int Number of `Product returns` on this page.
next String Url to the next page. The `Product returns` list is paginated by 10 entries.
previous String Url to the previous page. The `Product returns` list is paginated by 10 entries.
results [Product return] List of `Product returns`.

Product return fields :

Field name Type/Size Description
imeis [String] List of imeis associated with the product if any.
serialNumbers [String] List of serial numbers associated with the product if any.
trackingNumber String The tracking number of the product return.
quantity Int Quantity of products returned.
sku String Unique identifier of the product listing.
orderId String The uniquer id of the order
merchantId String Unique identifier of merchant who sold the product.
carrier String Name of carrier doing the product return.
customerAddress Address Address of the customer returning the product.
factoryAddress Address Name of the repair factory the product is returned to.
pickupDate Datetime Date of pickup of the product return by the carrier. Format: YYYY-MM-DDThh:mm:ss.sss±hh:mm
deliveryDate Datetime Date of delivery of the product return by the carrier. Format: YYYY-MM-DDThh:mm:ss.sss±hh:mm

Address fields :

Field name Type Description
firstName String First name related to the Address
lastName String Last name related to the Address
company String Company related to the Address
street String Street of the Address
street2 String Complement on the street of the Address
city String City of the Address
postalCode String Postal code of the city of the Address
country String Country of the Address
stateOrProvince String State or province of the Address
phone String Phone number related to the Address

Response status codes :

Status code Description
200 OK.
401 Unauthorized.
404 Not found.

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 let us know.

Create products

In this section we will deal with a creation of a Product.

If you want to sell a Product, which does not already exist on Back Market, you can create a new Product. More precisely, you can suggest a Product creation, which will be validated or not by our team.

It is NOT POSSIBLE to create a Product without a matching Listing through our API.

In this section we will see how to create both Products and their matching Listings in the same API call.

Each line of the CSV file you send in the API call can perform a different action depending on the values you provide.

This way, you can also create and update Listings for existing Products with the same API call.

In the following overview, we summarize fields you need to provide :

Overview for POST https://www.backmarket.fr/ws/listings :

1 - Create both Products and matching Listings :

2 - Create Listings matching existing products :

Explained in more detail in the following section: Create listings

3 - Update Listings :

Explained in more detail in the following section: Update several listings

Endpoint :

# Request Body example :

{
    "encoding": "latin1",
    "delimiter": ";",
    "quotechar": "\"",
    "header": true,
    "catalog": "ean;category_id;title;description;brand;price_new;weight;image1;color;sim_lock;screen_size;model;storage;sku;quantity;price;state;warranty_delay;\n8018417227790;2;iPhone 7 White 64 Go;This is the iphone 7 of state super shiny description;Apple;960;325;http://images.neteven.com/evenmarketplace/images_telephone/iphone7.jpg;White;SFR;4,7;iPhone 7;64;iphone7sku1;25;700;0;6;\n8018417227790;2;iPhone 7 White 64 Go;This is the iphone 7 of state bronze description;Apple;960;325;http://images.neteven.com/evenmarketplace/images_telephone/iphone7.jpg;White;SFR;4,7;iPhone 7;64;iphone7sku2;20;600;3;6;\n0190198067456;1;Old school phone title;This is an old school phone of state super shiny description;Nokia;310;325;http://images.neteven.com/evenmarketplace/images_telephone/nokia.jpg;White;SFR;2,2;Nokia 32xx;;nokia32xxsku1;25;200;0;6;\n0190198067456;1;Old school phone title;This is an old school phone of state bronze  description;Nokia;310;325;http://images.neteven.com/evenmarketplace/images_telephone/nokia.jpg;White;SFR;2,2;Nokia 32xx;;nokia32xxsku2;10;140;3;6;\n"
}

Click HERE to download the CSV file sent in this “catalog”

Example of a HTTP request Body (refer to Header in the Intro section) :

In the request body example, we will demonstrate the first case of the previous overview, we will create two Products and 2 matching Listings for each one of them). First created Product will be of the leaf Category: “Old School”, which has its marketplace_category_id equal to 1. The second one will be of the leaf Category: “Smartphone” with corresponding marketplace_category_id=2.

Required parameters (we will provide no optional fields for this example):

Body request parameters :

Please refer to the section Fields To Provide to know which fields you need to provide.

# Example of a JSON response - with Status code 200 :

{
  "bodymessage": 408,
  "statuscode": 200
}

# Example of a batch JSON response for the request above :

{
    "task_id": 408,
    "action_status": 9,
    "last_action_error": null,
    "result": {
        "product_errors": {},
        "product_success": {
            "nokia32xxsku1": {
                "sku": "nokia32xxsku1",
                "publication_state": 1,
                "backmarket_id": 1154,
                "listing_id": 1744,
                "ean": "0190198067456"
            },
            "nokia32xxsku2": {
                "sku": "nokia32xxsku2",
                "publication_state": 1,
                "backmarket_id": 1154,
                "listing_id": 1745,
                "ean": "0190198067456"
            },
            "iphone7sku1": {
                "sku": "iphone7sku1",
                "publication_state": 1,
                "backmarket_id": 1153,
                "listing_id": 1742,
                "ean": "8018417227790"
            },
            "iphone7sku2": {
                "sku": "iphone7sku2",
                "publication_state": 1,
                "backmarket_id": 1153,
                "listing_id": 1743,
                "ean": "8018417227790"
            }
        }
    },
    "statuscode": 200
}

Response parameters :

Fieldname Type Description
bodymessage Int The batch_id allowing you to check the batch.
statuscode Int HTTP status code.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Webservices unavailable.
429 Too Many Requests. You’ve been rate limited.

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 Buybox” 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 to know how to create both Products and Listings for these Products in the same API call.

Endpoint :

Example of a HTTP request Body (see Header in intro section) :

In the example, we only use the mandatory fields in order to create 2 Listings for an existing Product with the Back Market ID 1151. Note, that it is possible to create several listings matching several products in the same call but this example will not be covered here.

# Request Body example :

{
    "encoding": "latin1",
    "delimiter": ";",
    "quotechar": "\"",
    "header": true,
    "catalog": "sku;backmarket_id;quantity;warranty_delay;price;state;\n1111111111112;1151;2;6;180;2;\n1111111111113;1151;13;12;220;1;"
}

Click HERE to download the CSV file sent in this “catalog”

Body request parameters :

Fieldname Type Description
encoding String Encoding used for the CSV file provided by the merchant.
delimiter String Cells delimiter.
quotechar String Text separator.
header Bool True
catalog String Refer to the table below

For the Catalog field, a unique sku must be provided by the merchant to identify the Listing.

Besides, either the backmarket_id field or ean must be provided to match the Product you’d like to make an offer on. Backmarket_id prevails in case of conflict.

You must provide one of the 2 fields in blue, as well as the field in green. In addition to those, you must also provide all mandatory fields:

Catalog fields :

Field name Type/Size Description
backmarket_id Int Unique product Id. Provided by Back Market at the creation of a `Product`. Used to match the `Product`.
ean String/13 Used to match `Product` if the Back Market ID is not provided.
sku String/200 Unique listing Id. Used to match existing `Listing`.
quantity Int Stock available.
price Decimal Your price.
state Enum (Int)
0: Shiny (perfect state)
1: Gold (as good as new)
2: Silver (very good state)
3: Bronze (good state)
4: Stallone (acceptable) - Default
warranty_delay Int Warranty period (6 months minimum).
comment String/500 Comment.
currency String/10 Used Currency (default EUR).
shipper_1 Enum (String)
Shipper 1:
Amazon
Chronopost
Colissimo
Correos Express
DB Schenker
DHL
DPD
Exapaq
Geodis
GLS
Mondial Relay LD1
Mondial Relay LDS
NACEX
Socolissimo
TNT
Transporteur privé
UPS
Others (call us to add your shipper)
shipping_price_1 Decimal Shipping price 1.
shipping_delay_1 Int Shipping time 1 (hour)
shipper_2 Enum (String) Shipper 2
shipping_price_2 Decimal Shipping price 2.
shipping_delay_2 Int Shipping time 2 (hour)
shipper_3 Enum (String) Shipper 3
shipping_price_3 Decimal Shipping price 3.
shipping_delay_3 Int Shipping time 3 (hour)
snowden Bool Only for iPhones. Values (case-sensitive): “True” if TouchID is broken, else “False”. Default (column not set or unrecognized value): “False”.
noisy_camera Bool Only for smartphones and tablets. Values (case-sensitive): “True” if a noise is emitted when pictures are taken with the camera (local legislation), else “False”. Default (column not set or unrecognized value): “False”.
images Array[Images] List of images (image_url).

To add images, please refer to: Update specific listing for examples.

# Example of a JSON response - with Status code 200 :

{
    "bodymessage": 399,
    "statuscode": 200
}

# Example of a batch JSON response for the following request :

{
    "task_id": 399,
    "action_status": 9,
    "last_action_error": null,
    "result": {
        "product_errors": {},
        "product_success": {
            "1111111111113": {
                "sku": "1111111111113",
                "publication_state": 1,
                "backmarket_id": 1151,
                "listing_id": 1741,
                "ean": "5517876947666"
            },
            "1111111111112": {
                "sku": "1111111111112",
                "publication_state": 1,
                "backmarket_id": 1151,
                "listing_id": 1740,
                "ean": "5517876947666"
            }
        }
    },
    "statuscode": 200
}

Response parameters :

Fieldname Type Description
bodymessage Int The batch_id allowing to check the batch.
statuscode Int HTTP status code.

Please refer to the section: ‘Get batch’ to see how to check the batch.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Batch does not exist.
429 Too Many Requests. You’ve been rate limited.

Update products

After creation, since Products are multi-merchant, they cannot be directly updated after validation by our team. You will have to contact our support team 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, 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.

Update specific Listing

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: Update listings. See the section Best practices for more details.

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 BuyBoxes.

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.

Endpoint :

Request filter parameters for a URL :

Fieldname Description Example
listing_id Unique listing ID provided by Back Market. https://www.backmarket.fr/ws/listings/1718
# Request Body example :

{
    "quantity": 12,
    "warranty_delay": 12,
    "images": [
        {
            "image_url": "https://backmarket.fr/product_images/1457703391.43.jpg"
        },
        {
            "image_url": "https://backmarket.fr/product_images/1457703391.6.jpg"
        },
        {
            "image_url": "https://backmarket.fr/product_images/1457703392.05.jpg"
        }
    ]
}
# Example of a JSON response - with Status code 200 :

// This call will return the modified listing. For listing 1718 where we have modified the warranty delay, the quantity & the images (_cf._ body request example above).

{
    "listing_id": 1718,
    "sku": "MBP15C2D241B-2",
    "state": 3,
    "price": "1800.00",
    "quantity": 12,
    "publication_state": 2,
    "comment": "Grade B: Produit reconditionné parfaitement fonctionnel, comportant des traces d'usures avancées sur la partie extérieure (rayures et petits chocs) - Livré avec un chargeur dans les 48 heures.",
    "warranty_delay": 12,
    "shipping_price_1": "6.00",
    "shipping_price_2": null,
    "shipping_price_3": null,
    "shipping_delay_1": 48,
    "shipping_delay_2": null,
    "shipping_delay_3": null,
    "shipper_1": "Colissimo",
    "shipper_2": null,
    "shipper_3": null,
    "currency": "EUR",
    "backmarket_id": 1136,
    "snowden": false,
    "images": [
        {
            "image_url": "https://backmarket.fr/product_images/1457703391.43.jpg"
        },
        {
            "image_url": "https://backmarket.fr/product_images/1457703391.6.jpg"
        },
        {
            "image_url": "https://backmarket.fr/product_images/1457703392.05.jpg"
        }
    ],
    "statuscode": 200
}


Example of a HTTP request Body (refer to Header in the Intro section) :

You just need to specify field(s) you would like to change. All the others will be kept intact.

Updating images is a special case, since every request on the images field will override existing images.

To add an image to a set of existing images you will have to list every existing image Urls as well as the new one.

If the images field is not provided during an update, the existing Urls won’t be updated nor deleted.

If the images field is provided empty, all existing images will be deleted from the Listing.

Body request & response parameters :

Field name Type/Size Description
quantity Int Stock available.
price Decimal Your price.
state Enum (Int)
0: Shiny (perfect state)
1: Gold (as good as new)
2: Silver (very good state)
3: Bronze (good state)
4: Stallone (acceptable) - Default
warranty_delay Int Warranty period (6 months minimum).
comment String/500 Comment.
currency String/10 Used Currency (default EUR).
shipper_1 Enum (String)
Shipper 1:
Amazon
Chronopost
Colissimo
Correos Express
DB Schenker
DHL
DPD
Exapaq
Geodis
GLS
Mondial Relay LD1
Mondial Relay LDS
NACEX
Socolissimo
TNT
Transporteur privé
UPS
Others (call us to add your shipper)
shipping_price_1 Decimal Shipping price 1.
shipping_delay_1 Int Shipping period 1 (hour)
shipper_2 Enum (String) Shipper 2
shipping_price_2 Decimal Shipping price 2.
shipping_delay_2 Int Shipping period 2 (hour)
shipper_3 Enum (String) Shipper 3
shipping_price_3 Decimal Shipping price 3.
shipping_delay_3 Int Shipping period 3 (hour)
snowden Bool Only for iPhones, True if TouchID is broken, if not False.
images Array[Images] List of images (image url).

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 The listing doest not exist.
429 Too Many Requests. You’ve been rate limited.

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 a 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 (5 minutes in average) and to check the batch 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 a specific listing.

See the section Best practices for more details.

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.

Endpoint :

# Request Body example :

{
    "encoding": "latin1",
    "delimiter": ";",
    "quotechar": "\"",
    "header": true,
    "catalog": "sku;quantity;\n1111111111112;1;\n1111111111113;1151;10;"
}

Click HERE to download the CSV file sent in this “catalog”

Example of HTTP request Body (refer to Header in the Intro section) :

In the example above, we just updated the available stock for the Listing created in the section Create listings.

Note that it is also possible to update several Listings matching several Products with just one call, however this example will not be covered here.

Body request parameters :

Fieldname Type Description
encoding String Encoding used for the CSV file provided by the merchant.
delimiter String Cells delimiter.
quotechar String Text separator.
header Bool True
catalog String See table below

For the Catalog field, the sku must be provided to match the Listing you want to update.

Besides, either the backmarket_id field or ean must be provided to match the Product. Backmarket_id prevails in case of conflicts.

You must provide the field in green. In addition, you need to provide all fields you wish to modify. The backmarket_id and the ean are not mandatory. Only the SKU will be used as a key to retrieve the listing you want to update.

Catalog fields :

Field name Type/Size Description
backmarket_id Int Unique product Id. Provided by Back Market at the creation of a `Product`. Used to match the `Product`.
ean String/13 Used to match a `Product` if the Back Market ID is not provided.
sku String/200 Unique listing Id. Used to match an existing `Listing`.
quantity Int Stock available.
price Decimal Your price.
state Enum (Int)
0: Shiny (perfect state)
1: Gold (as good as new)
2: Silver (very good state)
3: Bronze (good state)
4: Stallone (acceptable) - Default
warranty_delay Int Warranty period (6 months minimum).
comment String/500 Comment.
currency String/10 Used Currency (default EUR).
shipper_1 Enum (String)
Shipper 1:
Amazon
Chronopost
Colissimo
Correos Express
DB Schenker
DHL
DPD
Exapaq
Geodis
GLS
Mondial Relay LD1
Mondial Relay LDS
NACEX
Socolissimo
TNT
Transporteur privé
UPS
Others (call us to add your shipper)
shipping_price_1 Decimal Shipping price 1.
shipping_delay_1 Int Shipping period 1 (hour)
shipper_2 Enum (String) Shipper 2
shipping_price_2 Decimal Shipping price 2.
shipping_delay_2 Int Shipping period 2 (hour)
shipper_3 Enum (String) Shipper 3
shipping_price_3 Decimal Shipping price 3.
shipping_delay_3 Int Shipping period 3 (hour)
snowden Bool Only for iPhones. Values (case-sensitive): “True” if TouchID is broken, else “False”. Default (column not set or unrecognized value): “False”.
noisy_camera Bool Only for smartphones and tablets. Values (case-sensitive): “True” if a noise is emitted when pictures are taken with the camera (local legislation), else “False”. Default (column not set or unrecognized value): “False”.
images Array[Images] List of images (image url).
# Example of a JSON response - with Status code 200 :

{
  "bodymessage": 401,
  "statuscode": 200
}

# Example of a batch JSON response for the request above :

{
    "task_id": 401,
    "action_status": 9,
    "last_action_error": null,
    "result": {
        "product_errors": {},
        "product_success": {
            "1111111111113": {
                "sku": "1111111111113",
                "publication_state": 1,
                "backmarket_id": 1151,
                "listing_id": 1741,
                "ean": "5517876947666"
            },
            "1111111111112": {
                "sku": "1111111111112",
                "publication_state": 1,
                "backmarket_id": 1151,
                "listing_id": 1740,
                "ean": "5517876947666"
            }
        }
    },
    "statuscode": 200
}

Response parameters :

Fieldname Type Description
bodymessage Int The batch_id allowing you to check the batch.
statuscode Int HTTP status code.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Webservices unavailable.
429 Too Many Requests. You’ve been rate limited.

Update orderlines

This section explains how to process your orders.

Refer to the taxonomy if you haven’t done so already, for more details about our order workflow and other information you will need in this section.

Endpoint :

Request filter params for URL :

Fieldname Description Example
order_id Unique ID of the `Order` (not the `Orderline`) https://www.backmarket.fr/ws/orders/175
# Example of a JSON response - with Status code 200 :

{
    "order_id": 540,
    "new_state": 3,
    "sku": "iphone7sku1",
    "tracking_number": "123123"
}

Example of a HTTP request Body (refer to Header in the Intro section) :

We take an example of an Orderline that we want to move from state 2 to state 3.

Please refer to the taxonomy for detailed status codes explanations.

Body request parameters :

During shipping all Orderlines are gathered in the same package. It is not necessary to specify the SKU when updating an Orderline to state 3; indeed, every Orderline of this Order will be set to this state automatically.

Merchants recover an order on state 1.

Please refer to the taxonomy for more details on Orders and Orderlines workflows.

Fieldname Type Description Required
order_id Int Unique ID of the `Order`. Specify the same order_id in the URL and in the body. Always required.
new_state Enum (Int) New state to apply to the `Orderline`. Refer to the table 6 in Taxonomy.
Always required.
Former state -> new state:
1 -> 2 or 4
2 -> 3 or 5
3 -> 6
sku String Merchant unique identifier of the `Listing`. Matching the `Orderline`. Required if new_state is: 2, 4, 5, 6.
imei String/15 Identifier of product - if SMARTPHONE only
Optional and processed if new_state is 3.
Only if the SKU is a SMARTPHONE
And the order has only one orderline with a quantity of 1
The value needs to be a valid IMEI
serial_number String/50 Identifier of product - All categories BUT smartphone
Optional and processed if new_state is 3.
Only if the SKU IS NOT a smartphone
And the order has only one orderline with a quantity of 1
tracking_number String/200 Tracking number of the package. Required if new_state is 3.
tracking_url String/200 Tracking url of the package. Optional and processed if new_state is 3.
date_shipping Datetime Date of package expedition in format: YYYY-MM-DD hh:mm:ss Optional and processed if new_state is 3.
shipper String/200 Shipper designated. Shipper can be replaced if new_state is 3.
return_reason Enum (Int)
Status code of the return reason.
0: Stock mistake.
1: Withdrawal during the legal 14 day period.
11: Does not live at provided address.
12: The parcel did not reach its destination.
13: Lost parcel.
21: Faulty product on opening of the package.
22: Failure during first use.
23: Failure during warranty period.
24: Non-compliant product.
25: Other.
Required if new_state is 6.
return_message String/500 Message sent to the customer for a cancellation or a refund. Optional and processed if new_state is 6.
# Example of a JSON response - with Status code 200 :

{
      "order_id": 540,
      "shipping_address": {
        "company": "DC comics",
        "first_name": "Wonder",
        "last_name": "Woman",
        "gender": 0,
        "street": "1 Place de la republique",
        "street2": "",
        "postal_code": "75011",
        "country": "FR",
        "city": "London",
        "phone": "0606060606",
        "email": "client_174_540@backmarket.fr"
      },
      "billing_address": {
        "company": "DC comics",
        "first_name": "Wonder",
        "last_name": "Woman",
        "gender": 0,
        "street": "1 Place de la republique",
        "street2": "",
        "postal_code": "75011",
        "country": "FR",
        "city": "London",
        "phone": "0606060606",
        "email": "client_174_540@backmarket.fr"
      },
      "tracking_number": "123123",
      "tracking_url": "",
      "shipper": "Chronopost",
      "date_creation": "2016-12-29T10:00:44Z",
      "date_modification": "2016-12-29T10:32:22Z",
      "date_shipping": "2016-12-29T10:32:21Z",
      "date_payment": "2016-12-29T10:12:50Z",
      "state": 9,
      "price": "1.00",
      "shipping_price": "0.00",
      "currency": "EUR",
      "country_code": "fr-fr",
      "success": "Le nouvel état de la ligne de commande (540 iphone7sku1) est : Expédiée.</br>Le nouvel état de la commande (540) est : Traitée.</br>",
      "errors": "",
      "warnings": "",
      "orderlines": [
        {
              "id": 591,
              "date_creation": "2016-12-29T10:00:44Z",
              "state": 3,
              "price": "1.00",
              "shipping_price": "0.00",
              "currency": "EUR",
              "return_reason": 0,
              "return_message": "",
              "listing": "iphone7sku1",
              "product": "iPhone 7 White 64 Go",
              "quantity": 1,
              "imei_numbers": [],
              "brand": "apple",
              "product_id": 141,
            "backcare": true,
            "backcare_price": 500
        }
      ]
}

Response parameters :

Shipping & billing addresses : Refer to the Table 8 from the taxonomy.

‘success’, ‘errors’ & ‘warning’ contain eventual messages about the update process.

Order fields :

Field name Type/Size Description
order_id Int Unique id of the `Order`. Used to update `Orderline(s)` of an `Order`.
shipping_address Address Shipping address.
billing_address Address Billing address.
tracking_number String/200 Tracking number of the package.
tracking_url String/300 Tracking Url of the package.
shipper String/200 Shipper designated.
date_creation Datetime Date of order. Format: YYYY-MM-DD:hh:mm:ss.
date_modification Datetime Date of last modification. Format: YYYY-MM-DD:hh:mm:ss.
date_shipping Datetime Date of shipping. Format: YYYY-MM-DD:hh:mm:ss.
date_payment Datetime Date of payment. Format: YYYY-MM-DD:hh:mm:ss.
state Enum (Int) Present state of the order. See Table 5 from Taxonomy
orderlines [OrderLine] List of `Orderlines` indexed by `sku`.
price Decimal Total order price (including taxes) without the shipping price.
shipping_price Decimal Total shipping price (including taxes).
currency String/3 Used Currency.
country_code Enum (String) Recover only orders from this country code.
Accepted-value:
fr-fr: France (default)
fr-be: Belgium
es-es: Spain
de-de: Germany
de-at: Austria
it-it: Italy
en-gb: United Kingdom
nl-nl: Netherlands

Orderline fields :

Field name Type Description
id Int Unique id of the `Orderline`.
date_creation Datetime Date of the creation of `Orderline`. Date format: ‘%Y-%m-%d %H:%M:%S’.
state Enum (Int) Present state of the `Orderline`. See Table 6 from Taxonomy
price Decimal listing & warranty price (including taxes) without the shipping price.
shipping_price Decimal Unitary shipping price (including taxes).
currency String Used Currency.
return_reason Enum (Int)
0: Stock mistake.
1: Withdrawal during the legal 14 day period.
11: Does not live at provided address.
12: The parcel did not reach its destination.
13: Lost parcel.
21: Faulty product on opening of the package.
22: Failure during first use.
23: Failure during warranty period.
24: Non-compliant product.
25: Other.
return_message String Message sent to the customer for a cancellation or a refund.
listing String SKU of the `Listing` (matching `Listing`).
product String Ordered product (title) .
quantity Int Quantity of ordered products.
imei_numbers List of Strings Listing of IMEI.
brand String The brand.
product_id Int The product ID (matched to a `Product`).
backcare Bool True if this orderline is covered by the Backcare service
backcare_price Int The backcare price in cents.

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 The `Listing` doest not exist.

Test environment

To create test Orders, go to: Back Market test website and buy a Product from a Listing you have created with your test account. You will be provided with some test credit card numbers in order to be able to proceed to the payment when necessary.

If any problems occur when paying using test credit cards, logout from you merchant account, and create a new user account. Then repeat the previous steps again.

Upload clients’ invoices

Merchants can upload clients’ invoices using this endpoint. When uploaded, invoices will be linked to a given Order.

Warning: this request is different from previous requests. It’s a multipart/form-data request and requires more than a json body (see the RFC7578 for details).

Endpoint :

The body should be formatted according to the multipart/form-data content type :

Headers part. Must come first, and must have a Content-Disposition header : Content-Disposition: form-data; name="invoice"; filename="NAME OF YOUR FILE" and a Content-Type header (Content-Type: application/x-object if the invoice is a PDF).

File’s data part.

Surround the whole body with a boundary string, preceded by two hyphens. In addition, add two hyphens after the final boundary string.

Add these top-level HTTP headers:

Example of an HTTP request (see Header in intro section) :

In the example, we only use the mandatory fields in order to upload one invoice for an existing Order with the Back Market ID 1151.

# Additionnal required headers :

Content-Length: LENGTH OF YOUR FILE IN BYTES
Content-Type: multipart/form-data; boundary=YOUR_BOUNDARY

# Body

--YOUR_BOUNDARY
Content-Disposition: form-data; name="invoice"; filename="NAME OF YOUR FILE"
Content-Type: application/x-object

... CONTENT OF FILE ...
--YOUR_BOUNDARY--

Body request parameters :

Fieldname Type Description
invoice File The invoice file to upload.

Response parameters :

Fieldname Type Description

Response status codes :

Status code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Order doesn’t exist.

API SAV (Customer Claims)

Create a Message in a Sav_Group

This section will describe how a Merchant can create a Message with or without an Attachment in one of his Sav_Group.

Endpoint :

Body request parameters :

Fieldname Type Description Mandatory
message String The message to be added Yes
attachment File Path to the local file to be linked to the message No

Exemple of a request body :

In the example, we only use the mandatory field in order to create a Message.

# Request Body example :
{
    "message": "Hi lovely API user"
}

Response body parameters :

Message fields :

Field name Type Description
message String The message
group Int Id of the Sav_Group related to the Message
sender Int Id of the User who created the message
date_creation Datetime Date of Message creation (YYYY-MM-DD:hh:mm:ss)

Attachment fields :

Field name Type Description
msg Integer Id of the Message which the Attachment is linked to
group Int Id of the Sav_Group related to the Message
sender Int Id of the User sending the attachment
attachment File Path to the uploaded file

Exemple of a response body :

# Example of a JSON response - with Status code 201:
{
    "id": 2,
    "message": "Hi lovely API user",
    "group": 19,
    "sender": 6,
    "date_creation": "2018-02-01T09:36:59.788Z",
    "attachment": {
        "msg": 503,
        "group": 19,
        "sender": 6,
        "attachment": "sav_attachment/test_file"
    }
}

Response status codes :

Status code Description
201 Message created
400 Bad request
403 Forbidden
404 Sav_Group does not exist

Create a Refund

This section will describe how to create a Refund for an existing OrderLine.

As described in the taxonomy, every OrderLine is described by a state:

State Description Comment
0 New Orderline The Merchant has to wait for payment confirmation
1 Orderline paid by the Customer The Merchant has to validate or cancel the Orderline
2 Orderline accepted by the Merchant The Merchant has to prepare the product for shipment
3 Orderline delivered to the shipping company The package delivery is in progress
4 Orderline cancelled The Customer will be entirely refunded for the Orderline
5 Orderline refunded before shipping The Customer will be entirely refunded for the Orderline
6 Orderline refunded after shipping The Customer made a refund request
7 Orderline not paid The payment has been refused by the bank

Creating a refund for an Orderline can be done using the following table as a guideline:

Current state Refund type (next state) Amount of refund
1 4 Complete
2 5 Complete
3 6 Complete/Partial

Endpoint :

Request body parameters :

Fieldname Type Description Mandatory
orderline_pk Int Id of the Orderline Yes
refund_type Int Type of Refund Yes
amount Float Amount of the Refund Only if Refund type is 6

Exemple of a request body:

In this example, we create a Refund for an Orderline which is in state 3, therefore asking for a Refund type 6.

# Request body example :
{
    "orderline_pk": 1,
    "refund_type": 6,
    "amount": 49.99
}

Response body parameters :

Fieldname Type Description
None String Summary of the created Refund

Exemple of a response body :

# Example of a JSON response - with Status code 201 :

{
    "49.99€ remboursé sur le sku 1"
}

Response status codes :

Status code Description
201 Refund created
400 Bad request
403 Forbidden
404 Orderline does not exist

Get all Sav_Groups

This section will describe how a Merchant can retrieve all his Sav_Group (tickets).

Every Sav_Group is described by a state:

State Description
0 Waiting for Merchant response
1 Waiting for Customer response
2 Waiting for Backmarket response
3 Return procedure
9 Closed

Endpoint :

Body request parameters :

None.

Request filter parameters for URL :

Note: You shouldn’t put the url parameters in between quotes.

Fieldname Description Example
page Page number to retrieve (10 entries per page) https://www.backmarket.fr/ws/sav/?page=2
last_id Retrieve Sav_Groups with an id higher than `last_id` https://www.backmarket.fr/ws/sav/?last_id=15
state Retrieve Sav_Groups with a state equal to `state` https://www.backmarket.fr/ws/sav/?state=1
orderline Retrieve Sav_Groups for a specific `orderline` https://www.backmarket.fr/ws/sav/?orderline=156789
last_modification_date Retrieve Sav_Groups more recent than `last_modification_date` (format: %Y-%m-%d-%H-%M) https://www.backmarket.fr/ws/sav/?last_modification_date=2018-12-31-12-12

Response body parameters :

Fieldname Type Description
count Int Number of Sav_Groups on this page
next String URL to the next page
previous String URL to the previous page
results [Sav_Group] List of Sav_Groups

Sav_Group fields :

Field name Type/Size Description
id Int Id of the Sav_Group
client Int Id of the Customer related to the Sav_Group
merchant Int Id of the merchant related to the Sav_Group
orderline Int Id of the Orderline
date_creation Datetime Date of order (YYYY-MM-DD:hh:mm:ss)
date_modification Datetime Date of Sav_Group last modification (YYYY-MM-DD:hh:mm:ss)
date_last_message Datetime Date of last message posted in the Sav_Group (YYYY-MM-DD:hh:mm:ss)
date_closed Datetime Date of Sav_Group closing (YYYY-MM-DD:hh:mm:ss)
state Int State of the Sav_Group
lines [Sav_Line] List of Sav_Lines id related to the Sav_Group

Exemple of a response body :

# Example of a JSON response - with Status code 200:
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 11,
            "client": 191,
            "merchant": 1,
            "orderline": 524,
            "date_creation": "2017-01-04T11:13:39Z",
            "date_modification": "2017-01-04T11:13:39Z",
            "date_last_message": "2017-01-04T11:13:39Z",
            "date_closed": null,
            "state": 0,
            "lines": [
                452
            ]
        }
    ]
}

Response status codes :

Status code Description
200 OK
400 Bad request
403 Forbidden

Get a specific Sav_Group

This section will describe how a Merchant can retrieve one of his Sav_Group (tickets).

Every Sav_Group is described by a state:

State Description
0 Waiting for Merchant response
9 Closed

Endpoint :

Body request parameters :

None.

Request filter parameters for URL :

Fieldname Description Example
sav_group_id Id of the Sav_Group
https://www.backmarket.fr/ws/sav_group/15

Response body parameters :

See taxonomy for more details.

Field name Type/Size Description
id Int If of the Sav_Group
client See below
merchant See below
orderline See below
messages See below
date_creation Datetime Date of order (YYYY-MM-DD:hh:mm:ss)
date_modification Datetime Date of Sav_Group last modification (YYYY-MM-DD:hh:mm:ss)
date_last_message Datetime Date of last message posted in the Sav_Group (YYYY-MM-DD:hh:mm:ss)
date_closed Datetime Date of Sav_Group closing (YYYY-MM-DD:hh:mm:ss)
state Datetime State of the Sav_Group

Client/Customer fields :

Field name Type Description
id Int Id of the Customer
username String Username of the Customer
first_name String First name of the Customer
last_name String Last name of the Customer
email String Email of the Customer

Merchant fields :

Field name Type Description
id Int Id of the Merchant
username String Username of the Merchant
first_name String First name of the Merchant
last_name String Last name of the Merchant

Orderline fields :

Field name Type/Size Description
id Int Id of the Orderline
order See below
quantity Int Number of products
price String Price of product
state Int State of the Orderline
trust_pack_plus Bool Customer bought Trust Pack Plus

Order fields :

Field name Type/Size Description
order_id Int Id of the Order
shipping_address See below
shipping_address See below
tracking_number String Tracking number
tracking_url String Tracking URL
shipper Int Id of the Shipper
shipper_display String Name of the Shipper
date_creation Datetime Date of Order creation (YYYY-MM-DD:hh:mm:ss)
date_modification Datetime Date of Order last modification (YYYY-MM-DD:hh:mm:ss)
date_shipping String Date of Order shipping (YYYY-MM-DD:hh:mm:ss)
date_payment Datetime Date of Order payment (YYYY-MM-DD:hh:mm:ss)
state Int State of Order
price String Price of Order
shipping_price String Price of Order shipping
currency String Currency of payment
country_code String Country code of plateform location

Shipping_address/Billing_address fields :

Field name Type Description
company String Company related to the Address
first_name String First name related to the Address
last_name String Last name related to the Address
gender Int Male or female
street String Street of the Address
street2 String Complement on the street of the Address
postal_code String Postal code of the city of the Address
country String Country of the Address
city String City of the Address
phone String Phone number related to the Address
email String Email related to the Address
customer_id_number String If of the Customer related to the Address

Message fields :

Field name Type Description
id Int Id of the message
initiator String The initiator for the message (Merchant, Customer, BackMarket)
message String The text content of the message
kind String The kind of the message (ADMIN_TO_ALL, ADMIN_TO_MERCHANT, MERCHANT_TO_ALL, MERCHANT_TO_BACKCARE, CLIENT_TO_ALL, BACKCARE_TO_ALL, BACKCARE_TO_MERCHANT, AUTO)
date_creation Datetime The date and time of the creation of the message
attachments List of strings A list of URLs pointing towards the attachements of the message

Exemple of a response body :

# Example of JSON response - Status code 200:
{
    "id": 18,
    "client": {
        "id": 174,
        "username": "test_WW@backmarket.fr",
        "first_name": "Wonder",
        "last_name": "Woman",
        "email": "client_174_344_384@backmarket.fr"
    },
    "merchant": {
        "id": 1,
        "username": "dev_test_123@backmarket.fr",
        "first_name": "Feedyé",
        "last_name": "Feederé"
    },
    "orderline": {
        "id": 384,
        "order": {
            "order_id": 344,
            "shipping_address": {
                "company": "DC comics",
                "first_name": "Wonder",
                "last_name": "Woman",
                "gender": 0,
                "street": "1 Place de la republique",
                "street2": "",
                "postal_code": "75011",
                "country": "FR",
                "city": "London",
                "phone": "0606060606",
                "email": "",
                "customer_id_number": ""
            },
            "billing_address": {
                "company": "DC comics",
                "first_name": "Wonder",
                "last_name": "Woman",
                "gender": 0,
                "street": "1 Place de la republique",
                "street2": "",
                "postal_code": "75011",
                "country": "fr-fr",
                "city": "Paris",
                "phone": "0606060606",
                "email": "",
                "customer_id_number": ""
            },
            "tracking_number": "",
            "tracking_url": "",
            "shipper": null,
            "shipper_display": "",
            "date_creation": "2016-06-06T12:13:33Z",
            "date_modification": "2016-06-08T10:13:34Z",
            "date_shipping": "2017-07-20T14:15:57Z",
            "date_payment": "2015-11-13T15:24:35Z",
            "state": 9,
            "price": "81.00",
            "shipping_price": "129.00",
            "currency": "EUR",
            "country_code": "fr-fr",
            "orderlines": [
                {
                    "id": 384,
                    "date_creation": "2016-06-06T12:13:33Z",
                    "state": 3,
                    "price": "81.00",
                    "shipping_price": "129.00",
                    "shipping_delay": 1,
                    "shipper": null,
                    "currency": "EUR",
                    "return_reason": 0,
                    "return_message": "",
                    "listing": "71",
                    "product": "Apple Iphone 4 16 Go - Noir - Débloqué",
                    "quantity": 1,
                    "imei_numbers": [],
                    "brand": "apple",
                    "product_id": 141
                }
            ]
        },
        "snapshot": {
            "id": 275,
            "product": {
                "product_id": 1,
                "category_3": {
                    "category_name": "Smartphones",
                    "parent": {
                        "category_name": "Smartphones",
                        "parent": {
                            "category_name": "Téléphones",
                            "parent": {
                                "category_name": ""
                            }
                        }
                    }
                },
                "title": "iPhone 4 16 Go - Noir - Débloqué",
                "brand": "APPLE",
                "model": "Iphone 4"
            },
            "listing": 783,
            "sku": "71",
            "snowden": false
        },
        "quantity": 1,
        "price": "81.00",
        "state": 3,
        "trust_pack_plus": true
    },
    "messages": [
        {
            "id": 2,
            "initiator": "BackMarket",
            "message": "Hello Feed Inc.  ®,\n\nWonder Woman (commande numéro 344) rencontre un problème avec son produit :\n\n -Déjà reçue > Problème technique.\n\nElle souhaite exercer son droit de rétractation.\n\n\"qegqegqeg\"\n\nMerci pour votre aide !\nGreg de Back Market",
            "date_creation": "2017-06-19T12:27:18Z",
            "attachments": []
        }
    ],
    "date_creation": "2017-06-19T12:27:18Z",
    "date_modification": "2017-06-19T12:27:18Z",
    "date_last_message": "2017-06-19T12:27:18Z",
    "date_closed": null,
    "state": 0,
    "lines": [
        {
            "id": 461,
            "tiles": [
                {
                    "id": 18,
                    "name": "Technical"
                }
            ],
            "rate": 0,
            "score": 9,
            "state": 0,
            "withdraw": false,
            "gras_savoye": true,
            "warnings": []
        }
    ]
}

Response status codes :

Status code Description
200 OK
400 Bad request
403 Forbidden
404 Sav_Group does not exist

Update a Sav_Group state

This section will describe how a Merchant can update one of his Sav_Group state.

Every Sav_Group is described by a state:

State Description
0 Waiting for Merchant response
1 Waiting for Customer response
2 Waiting for Backmarket response
3 Return procedure
9 Closed

As a Merchant, you are allowed to update the Sav_Group state using:

State Description
0 Waiting for Merchant response
9 Closed

Endpoint :

Body request parameters :

Fieldname Type Description
state Integer New state of the Sav_Group

Exemple of a request body:

# Request body example :
{
    "state": "9"
}

Response parameters :

Field name Type Description
id Integer Id of the Sav_Group
client Integer Id of the Customer related to the Sav_Group
merchant Integer Id of the Merchant related to the Sav_Group
orderline Integer Id of the Orderline
date_creation Datetime Date of order (YYYY-MM-DD:hh:mm:ss)
date_modification Datetime Date of Sav_Group last modification (YYYY-MM-DD:hh:mm:ss)
date_last_message Datetime Date of last message posted in the Sav_Group (YYYY-MM-DD:hh:mm:ss)
date_closed Datetime Date of Sav_Group closing (YYYY-MM-DD:hh:mm:ss)
state Integer State of the Sav_Group
lines [Sav_Line] List of Sav_Lines id related to the Sav_Group

Example of a HTTP response Body :

# Example of a JSON response - with Status code 200:
{
    "id": 11,
    "client": 191,
    "merchant": 1,
    "orderline": 524,
    "date_creation": "2017-01-04T11:13:39Z",
    "date_modification": "2017-01-04T11:13:45Z",
    "date_last_message": "2017-01-04T11:13:39Z",
    "date_closed": null,
    "state": 3,
    "lines": [
        452
    ]
}

Response status codes :

Status code Description
200 Sav_Group updated
400 Bad request
403 Forbidden
404 Sav_Group does not exist

F.A.Q.

Please click here to access the FAQ

Contact Us

If you have any questions and you are already selling on Back Market please contact your account manager.

If you have technical issues or questions, please send an email to partner-support@backmarket.com. Please note that this mail is temporary as we will deploy a new merchant support center that will assist you.

Pro-Services for the win <3