openapi: 3.0.3 info: version: 0.1.1 title: Back Market - API Guidelines description: | ## Table of contents 1. [Introduction](#introduction) 1. [Getting started](#getting-started) 1. [Technical requirements](#technical-requirements) 1. [F.A.Q. and Contact](#faq-and-contact) 1. [Cookbooks](#cookbooks) ## Introduction Welcome to Back Market, the leading online marketplace dedicated to refurbished products. Our back-office and our web-services have been created in order to allow Seller to manage their products easily on our marketplace. This documentation is meant to help you integrate our marketplace and learn how to manage your `Products`, `Offers` and `Orders` on Back Market. ### Overview of what this documentation is talking about * Our Taxonomy : This part will describe the organization and classification of our marketplace * Products & Offers : You will learn how to create `Products` as well as create, update and list `Offers` on Back Market * Your Orders : The `Orders` workflow, listing and update will be explained Different solutions are offered in order to use our marketplace. It's possible to work with a combination of these solutions or to switch from one to another at a later stage. 1 - Back Market API: This is the best solution for big and/or small sellers with their own technical team. Working with our API will enable you to synchronize your information with our database in real time. It is especially suitable for sellers with long-tail catalogs as well as a large amount of sales. 2 - Back-office: Our 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 to help you to setup an API connexion. ### Other information On this website, we've collected all the information you might need to get on board as smoothly as possible. Also, be sure to check our [F.A.Q.](#f-a-q-and-contact) to get answers to your questions. [Contact us](#f-a-q-and-contact) if you still have further questions. ### Feedback At Back Market, we always want to improve our solutions. Please [Give Us Feedback](mailto:?subject=Feedback Back Market Doc) and let us know about possible improvement we could make, be it on this documentation, our web services, our back-office or whatever you might think of. Please note that this mail is temporary as we will deploy a new Seller support center that will assist you. ## Getting Started If you did not yet read the page on [taxonomy](operations/get-bm-catalog-category#taxonomy), please do it before proceeding. ### Account After validation by our team, each Seller gains access to an account. This account gives you access to the Back Market Back Office and our API. Use one of the following links to access your Back Office account or create one if you haven't done so already. You will need to provide information about your company and we will get back to you as soon as possible: * AP platform * EU platform * US platform For creating or accessing an account on the preprod, you can use the following links: * AP preprod platform * EU preprod platform * US preprod platform ### Country code Back Market is international so you can sell products abroad. The country code matches both the targeted language and country for the action you'd like to perform (ex: update the price for a listing in Italy). Information about every countries are contained in the same instance of an object `Product` or a `Listing`. Indeed, you don't need to create one `Listing` for each country. This `Listing` will contain some fields which are the same for all the countries (_listing_id, quantity, ..._) and other country specific fields (_comment, price and warranty_delay_). Therefore, if you wish to edit the _**stock**_ (field : 'quantity'), the change will apply to all the countries, but for the _**comment**_ you will have to change it for each country. In the same way, some fields of the `Product` are common for all countries (_weight, EAN, ..._), and others depend on the country (_description, title and price_new_). **COUNTRY_CODES** - Accepted values are : * AP platform: * ja-jp : Japan * en-au : Australia * EU platform: * fr-fr : France * fr-be : Belgium * es-es : Spain * de-de : Germany * de-at : Austria * it-it : Italy * en-gb : United Kingdom * nl-nl : Netherlands * pt-pt : Portugal * en-ie : Ireland * el-gr : Greece * sk-sk : Slovakia * sv-se : Sweden * US platform: * en-us : United States ### CSV file format All files imported through our Back Office or imported using Back Market's API must be in CSV format. Required field separator is ';'. Required line separator is the line feed '\n'. Fields must be surrounded by double quotes. ## Technical Requirements ### API Identification > > HTTP Header (will remain the same for every API call): ```http Content-type: application/json Accept: application/json Accept-Language: COUNTRY_CODE Authorization: Basic YOUR_ACCESS_TOKEN User-Agent: YOUR_USER_AGENT ``` Each Integrator or Seller should use the following HTTP Header when calling Back Market API endpoints. The User-Agent is mandatory. Any request without it might be refused by our System. It should include your company name, application name, version, and a contact email address in this format: ```http BM-{CompanyName}-{IntegrationName};company@companydomain.com. ``` For example: ```http BM-Ebay-Invoices;contact@ebay.com BM-bouygues-automations;contact@bouygues.fr ``` ### Web application firewall (WAF) and Bot management The WAF or bot management may block your requests for security reason. You'll typically receive an HTTP 403 Forbidden response, possibly with a response body to tell you to challenge your client with Cloudflare. In case you judge that your request should not be blocked by Cloudflare, from the response headers, you can get the value of cf-ray and send it to your seller contact for investigation. Example HTTP 403 response from WAF: ```http HTTP/2 403 date: Wed, 16 Apr 2025 11:26:41 GMT content-type: text/html; charset=UTF-8 referrer-policy: same-origin cache-control: max-age=15 expires: Wed, 16 Apr 2025 11:26:56 GMT ... x-content-type-options: nosniff x-frame-options: SAMEORIGIN server: cloudflare cf-ray: 931354450813d142-CDG alt-svc: h3=":443"; ma=86400 ``` Example HTTP 403 response for Bot Management protected endpoints: ```json { "errors": [ { "code": "bot-need-challenge", "message": "Forbidden", "challengePath": "/testchallengepage" } ] } ``` ### Traffic limitation Our standard rate limits are will allow your automations to run fast enough to finish your processes. However, in case of too many requests beyond what we except on sellers endpoints, you will be presented with an HTTP 429 response from Cloudflare. Usually you will find the range above 200 requests in 10 seconds being blocked for 10 seconds and for more sensible endpoints like catalog for example above 20 requests in 10 seconds being blocked for 10 seconds. ### Data limitation To make sure we can handle and process all the incoming data correctly, we have set-up the following limitation: **We might not accept more than 2k lines of SKUs to process per hour** on the following endpoints ([Update Several listings](#update-several-listings) or on [Update specific listing](#update-specific-listing)) and [Update Listings](#update-listings)) files. FTP in Back Market is deprecated. If you used to use FTP in order to connect to Back Market Please contact to help you to setup an API connexion. **If this limit is reached, Back Market may refuse the task**, in this case you will receive HTTP responses with the "429 Too Many Requests" status. If you have lots of active SKUs, please take into account the [Best Practice](#best-practices) part of the documentation. ### Questions ? If you have any questions, please send an email to Please note that this mail is temporary as we will deploy a new seller support center that will assist you. ## F.A.Q. and Contact Please [click here](https://merchant-support.backmarket.com/hc/en-us) to access your Seller Support Center where you can find our F.A.Q. or contact us. If you have never signed in to the Seller Support Center, you can read this [tutorial](statics/How-to-connect-to-SSC.pdf) which helps you setup you connection for the first time. If you have any more questions and are already selling on Back Market, we invite you to contact your account manager. ## Cookbooks A list of notebooks showcasing different API use cases: [Winning the BackBox based on small price efforts](https://colab.research.google.com/drive/12jHZ3AQG8mQjjAvulG9zVvfC_psEOKjh?usp=sharing) contact: name: Seller Support Center url: https://merchant-support.backmarket.com/hc/en-us x-slack: NA email: NA@NA.com servers: - url: https://preprod.backmarket.co.jp description: Preprod - AP - url: https://www.backmarket.co.jp description: Prod - AP - url: https://preprod.backmarket.fr description: Preprod - EU - url: https://www.backmarket.fr description: Prod - EU - url: https://preprod.backmarket.com description: Preprod - NA - url: https://www.backmarket.com description: Prod - NA paths: /ws/category/tree: get: summary: Get category tree description: | ## Taxonomy ### Categorization & products `Categories` tree diagram : 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 (usually within 12 hours of a working day) before being put online. In addition to some mandatory fields for each `Products` (_cf._ Table 3), the `leaf Category` defines `Attributes` (which can be **mandatory** or **optional**) to provide during the creation of a `Product`. Therefore, when creating a `Product`, some fields will depend on the `leaf Category` of the `Product` (category `Attributes`) you create. Others will always be the same for every `Products` you create (_cf._ Table 3). **In summary, if you want to create a `Product`, you will have to provide**: * The `EAN` (European Article Number) of the `Product`. * **Mandatory** product fields (_cf._ Table 3). * The `marketplace_category_id` (to match the `Product` with its `leaf Category`). * **Mandatory** category `Attributes` (which depend on the `leaf Category`). Only the merchant who created the `Product` can update it. **The update can only be done before our team validates the product.**. #### Table 1 - `Category` model
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 product ID** is provided at the creation of a `Product`.
Field name Type/Size Description
product_id String Unique product Id. Provided by Back Market at the creation of a `Product` for purpose of matching to `Listings`.
**Required fields:**
Field name Type/Size Description
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.
**Optional fields:**
Field name Type/Size Description
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 on the country and some are in common for every country. Here is the list of fields for the Product model that vary by country (and need to be specified for each country): * 'title' * 'description' * 'price_new' ## Get category tree If you want to sell a new `Product`, which has not already been added on our marketplace by another merchant, you will need to create it. In this case, you need to select one `leaf Category` and check the corresponding `Attributes`. This will let you know all mandatory or optional `Attributes` you need to provide during the creation of the `Product`. This section allows to retrieve Back Market's `Category tree`, including all its branches. ### Endpoint ### HTTP request No request Body. ```javascript # Example of JSON response - Status code 200 [ { "category_id":1, "category_name":"T\u00e9l\u00e9phones", "marketplace_category_id":-1, "is_leaf":false, "attributes":[], "childrens":[ { "category_id":2, "category_name":"Old School", "marketplace_category_id":-10001, "is_leaf":false, "attributes":[], "childrens":[ { "category_id":3, "category_name":"Old School", "marketplace_category_id":1, "is_leaf":true, "attributes":[ { "field":"color", "field_name":"Couleur", "type": 2, "allowed_values":"", "required":true }, { "field":"screen_size", "field_name":"Taille \u00e9cran (pouces)", "type": 2, "allowed_values":"", "required":true }, {...} ], "childrens":[] } ] }, {...} ] }, {...} ] ``` ### Response parameters _**`Category` fields :**_
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.
## 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. x-tier: 3 tags: - Categories operationId: get-bm-catalog-category security: - ApiKeyAuth: [] - BasicAuth: [] responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/CategoryTree' '401': description: Unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV2' '403': description: Forbidden. Authenticated user is not a merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV2' parameters: - name: Accept-Language in: header description: | Select what market will be used to apply filters and export data. Passed as the language code related to this market. required: false example: fr-fr schema: $ref: '#/components/schemas/Locale' /ws/category/tree/{categoryId}: parameters: - in: path name: categoryId required: true example: 1 schema: type: integer - name: Accept-Language in: header description: | Select what market will be used to apply filters and export data. Passed as the language code related to this market. required: false example: fr-fr schema: $ref: '#/components/schemas/Locale' get: summary: Get category branch description: | Retrieve a specific `Category` branch. This will only give you access to what's below on the branch. This means that you won't be able to access the parent `Categories`, but only children `Categories` and `Attributes`. You can retrieve `Attributes` from a specific `leaf Category` with the following endpoint, by providing its category ID. x-tier: 3 tags: - Categories responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CategoryTree' '401': description: Unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '403': description: Forbidden. Authenticated user is not a merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '404': description: Category not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' /ws/listings: get: x-tier: 1 summary: Get listings description: | Retrieve all your `Listings`. security: - ApiKeyAuth: [] - BasicAuth: [] parameters: - example: 2 in: query name: publication_state required: false schema: enum: - 0 - 1 - 2 - 3 - 4 type: integer - example: 0 in: query name: min_quantity required: false schema: type: integer - example: 100 in: query name: max_quantity required: false schema: type: integer - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' - description: | Select what market will be used to apply filters and export data. Passed as the language code related to this market. example: fr-fr in: header name: Accept-Language required: false schema: $ref: '#/components/schemas/Locale' responses: '200': content: application/json: schema: properties: count: example: 123 type: integer next: example: https://www.backmarket.fr/ws/listings?page=2 nullable: true type: string previous: example: null nullable: true type: string results: items: $ref: '#/components/schemas/ListingPublic' type: array required: - count - next - previous - results type: object description: OK '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' description: Unauthenticated. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' description: Forbidden. Authenticated user is not a merchant. tags: - Listings post: tags: - Listings x-tier: 1 summary: Create or update products and listings description: | ## Create listings Every merchant working with us can create a sale offer or a "`Listing`" of a `Product` in order to sell it on our marketplace. Our algorithm decides which `Listing` will win "The Backbox" and therefore which `Listing` will be displayed on our website for the consumer to purchase. In this section we will describe an endpoint that allows you either to create `Listings` matching existing `Products` or to create both `Products` and `Listings` for these products at the same time. We will also present how to create `Listings` matching existing `Products`. _Please refer to the section [Create products](#create-products) to know how to create both Products and Listings for these Products in the same API call._ Note that we limit the size of the CSV file that you can send to 15000 lines. You can find the list of columns for the `catalog` field in the Back Market back-office following the tab "Options > Batch Listing Creation". In the `catalog` field, a unique (case insensitive) `sku` must be provided by the merchant to identify the `Listing`. Besides, either the `product_id` field or `ean` must be provided to match the `Product` you'd like to make an offer on. `product_id` prevails in case of conflict. You can find the list of columns for the `catalog` field in the Back Market back-office following the tab "Options > Batch Listing Creation". ## Update several listings It is possible to update several `Listings` at a time using CSV files, which you can send with an API call. For example _you might want to add another country to the listings. You might also need to change their prices, comments or the available stocks (quantities)._ To put a `Listing` offline, just set its quantity to 0. The endpoint below is not as efficient as the one described in "update specific listing", because the update will NOT be taken into account in real-time. Indeed, you will have to wait for the task to be processed and to check the task for possible errors. Yet, you will be able to update several `Listings` at a time using the endpoint below, as opposed to the one described in "update specific listing". We advise you not to use this endpoint to deal with stocks. Nevertheless, it can be useful if you'd like to update prices for your whole catalog for instance. Note that we limit the size of the CSV file that you can send to 15000 lines. For the `catalog` field, the `sku` must be provided to match the `Listing` you want to update (sku is case insensitive). ## Create products In this section, we'll guide you through the process of creating a `Product` on Back Market. ### Overview If you wish to sell a `Product` that is not currently available on Back Market, you can propose the creation of a new `Product`. This proposal will be reviewed and either approved or rejected by our team. **Important:** It is not possible to create a `Product` without a corresponding `Listing` using our API. ### Creating Products and Listings This section explains how to create both `Products` and their corresponding `Listings` in a single API call. - Each row in the CSV file you upload via the API can perform different actions based on the values provided. - You can also [create](#create-listings) and [update](#update-several-listings) `Listings` for existing `Products` within the same API call. ### CSV File Requirements - The CSV file you submit must not exceed 15,000 lines. - You can generate a CSV file with all the required columns based on the product category in your back office by navigating to: **Options > Batch Listing Creation**. By following these guidelines, you can efficiently manage your product listings on Back Market. ## Update products After creation, since `Products` are multi-merchant, they cannot be directly updated after validation by our team. You will have to contact us for all requests related to this matter. In the case a `Product` hasn't been validated by our team yet, the merchant who created this `Product` can update it as long as it's not been validated. To do so, you need to perform the same actions you made during the [product creation](#create-products), but this time providing modified values. If you try to update a `Product`, which is already existing (`EAN` or `Back Market id` match a `Product` in our Database) and has already been validated by our team, it won't return any error but the modification won't be taken into account. The product will still remain unchanged. security: - ApiKeyAuth: [] - BasicAuth: [] parameters: - name: Accept-Language in: header description: | Select what market will be used to apply filters and export data. Passed as the language code related to this market. required: false example: fr-fr schema: $ref: '#/components/schemas/Locale' requestBody: content: application/json: schema: type: object required: - catalog - quotechar - delimiter - encoding properties: catalog: type: string minLength: 1 description: | A CSV file content as a string. example: |- sku,quantity,price MY_SKU,50,123.45 quotechar: type: string minLength: 1 maxLength: 1 description: The separator of columns for the 'catalog' CSV. example: '"' delimiter: type: string minLength: 1 maxLength: 1 description: The delimiter of data for the 'catalog' CSV. example: ',' encoding: type: string minLength: 2 maxLength: 64 description: The encoding of data for the 'catalog' CSV. example: utf-8 responses: '200': description: OK. Task has been created and will be processed. content: application/json: schema: type: object required: - bodymessage - statuscode properties: bodymessage: type: integer description: | The batch identifier that can be used to retrieve its status with the Get batch API [/ws/tasks/{taskId}](https://api.backmarket.dev/#/paths/ws-tasks-taskId/get). statuscode: type: integer example: 200 '400': description: Request data is invalid. A required field might be missing. content: application/json: schema: type: string description: An error message example: parameter catalog not found '401': description: Unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '403': description: Forbidden. This ingestion channel could be disabled for the merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '429': $ref: '#/components/responses/RateLimited' /ws/listings/{listingId}: parameters: - in: path name: listingId description: Unique listing ID provided by Back Market. The UUID format is preferred. required: true example: da72cf47-1b1f-434a-9224-1f8684ac1bd4 schema: oneOf: - type: string format: uuid - type: integer - name: Accept-Language in: header description: | Select what market will be used to apply filters and export data. Passed as the language code related to this market. required: false example: fr-fr schema: $ref: '#/components/schemas/Locale' get: tags: - Listings x-tier: 1 summary: Get specific listing description: | Retrieve a specific `Listing` to check its information. ### Endpoint The 2 following endpoints provide exactly the same response: Or working with a filter on: If you don't have either the sku nor the listing_id, you can retrieve them by: **GET** `https://www.backmarket.fr/ws/listings/` security: - ApiKeyAuth: [] - BasicAuth: [] responses: '200': description: OK content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ListingPublic' - type: object required: - statuscode properties: statuscode: type: integer example: 200 '400': description: Invalid inputs (bad type…). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '401': description: Unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '403': description: Forbidden. Authenticated user is not a merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '404': description: Listing not found, or it does not belong to the authenticated merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' post: tags: - Listings x-tier: 1 summary: Update specific listing description: | It is possible to update some fields of a specific `Listing`. For example _you might want to add another country to the `Listing`. You might also need to change the price, comment or the available stock (quantity)._ To put a `Listing` offline, just set its quantity to 0. The endpoint below provides the most efficient way to update a specific `Listing`, as the update will be taken into account in real-time. Yet, you can only update one `Listing` at a time on this endpoint as opposed to the endpoint to update several listings. If you work with other marketplaces, **DO NOT forget** to update your stocks on Back Market in order not to be compelled to cancel orders. We strongly penalize high cancellation rates in our algorithm, which allocates `Backbox`. Updating in real time is especially important when your stock for the listing is close to 0. When an order is made on Back Market, you don't need to decrease the stock in our database since we decrease it automatically. You just need to specify field(s) you would like to change. All the others will be kept intact. security: - ApiKeyAuth: [] - BasicAuth: [] requestBody: content: application/json: schema: type: object properties: price: description: | Price of the listing in the 'currency'. String format is prefered to avoid any issue related to the floating-point number precision. anyOf: - type: string example: '160.99' - type: number example: 160.99 currency: type: string description: | Currency of 'price' in ISO 4217 code format. If 'price' is in the request, this field must match the currency of the market selected with the 'Accept-Language' header. Defaults to EUR for the EU marketplace, USD for the US one. Thus this field is required for markets where the currency is not these defaults. example: EUR comment: nullable: true description: Comment. Maximum 500 characters. type: string example: This is an iPhone 6S - 64Go - Blue working with all operators warranty_delay: description: Warranty period in months (12 months minimum). anyOf: - type: integer example: 24 - type: string example: '24' quantity: description: Available stock. anyOf: - type: integer example: 12 - type: string example: '12' shipper_1: $ref: '#/components/schemas/Shipper' shipper_display_1: type: string nullable: true description: The displayed name for the shipper. example: DHL Express shipping_delay_1: description: Expected shipping delay in hours. nullable: true type: integer example: 36 shipping_price_1: description: | Price of the shipping option, using currency of listing. String format is prefered to avoid any issue related to the floating-point number precision. anyOf: - type: string example: '3.90' - type: number example: 3.9 nullable: true shipper_2: $ref: '#/components/schemas/Shipper' shipper_display_2: type: string nullable: true description: The displayed name for the shipper. example: DHL Express shipping_delay_2: description: Expected shipping delay in hours. nullable: true type: integer example: 36 shipping_price_2: description: | Price of the shipping option, using currency of listing. String format is prefered to avoid any issue related to the floating-point number precision. anyOf: - type: string example: '3.90' - type: number example: 3.9 nullable: true shipper_3: $ref: '#/components/schemas/Shipper' shipper_display_3: type: string nullable: true description: The displayed name for the shipper. example: DHL Express shipping_delay_3: description: Expected shipping delay in hours. nullable: true type: integer example: 36 shipping_price_3: description: | Price of the shipping option, using currency of listing. String format is prefered to avoid any issue related to the floating-point number precision. anyOf: - type: string example: '3.90' - type: number example: 3.9 nullable: true min_price: nullable: true description: | Your minimum acceptable price. The BackPricer needs to be enabled in your seller configuration. More information about BackPricer at https://merchant-support.backmarket.com/hc/en-us/articles/4415101044370-How-to-use-the-BackPricer- min_price must be satisfy: * `1.08 * min_price >= price` * `min_price <= price` If these conditions are not respected, min_price is automatically set to the current price: the request's minimum price will not be applied as submitted. anyOf: - type: string example: '160.99' - type: number example: 160 responses: '200': description: | OK. Update processed. Note that some processing can be done asynchronously (Backbox, search indexing, etc). content: application/json: schema: type: object required: - id - listing_id - backmarket_id - title - shippings - state - grade - quantity - currency - sku - publication_state - warranty_delay - price - comment - max_price - statuscode - min_price properties: id: type: string format: uuid description: Listing ID example: 7a97a1b6-547e-4718-bc72-5b84aca91b09 listing_id: type: integer description: Listing ID (deprecated) example: 4567 product_id: type: string format: uuid description: Product ID example: 6d4ad966-db97-4d88-b409-b28cc2a0f8c9 backmarket_id: type: integer description: Product ID (deprecated) example: 42 title: type: string description: Product title example: iPhone 6S - 64Go - Blue - Unlocked shippings: type: array description: | Shippings defined at listing level (if any). Does not include shippings defined at category level nor the global ones. items: type: object required: - shipping_price - shipping_delay - shipper - shipper_display - country_code properties: shipping_price: type: string description: Price of the shipping option, using currency of listing. example: '0.00' shipping_delay: type: integer description: Expected shipping delay in hours. example: 24 shipper: type: string description: The company that manages the delivery. example: UPS shipper_display: type: string description: The company that manages the delivery. example: UPS country_code: type: string description: | The market where this shipping option is available. Passed as the language code of this market. example: it-it state: $ref: '#/components/schemas/ListingStateValue' grade: $ref: '#/components/schemas/AestheticGradeValue' quantity: description: Available stock. type: integer example: 12 currency: type: string description: Currency of 'price' example: EUR sku: description: SKU provided by the seller on listing creation. type: string example: IPHONE_6S_64GO_BLUE_CORRECT publication_state: type: integer example: 2 enum: - 0 - 1 - 2 - 3 - 4 warranty_delay: description: Warranty period in months (12 months minimum). type: integer example: 24 price: type: string description: Price of the listing in the 'currency' example: '160.99' comment: nullable: true type: string example: This is an iPhone 6S - 64Go - Blue working with all operators description: Comment. Maximum 500 characters. max_price: type: string description: Maximum allowed price for this listing, or it will not be online. example: '199.90' shippings_response: type: array description: Success and failure messages related to processing of shippings data. items: type: string example: Shipping method 2 (ACME Company) updated statuscode: type: integer example: 200 min_price: type: string nullable: true description: Minimum acceptable price for the Backpricer. example: '160.99' '400': description: Request data is invalid. A required field might be missing. content: application/json: schema: type: string description: An error message example: parameter catalog not found '401': description: Unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '403': description: Forbidden. This ingestion channel could be disabled for the merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '404': description: Listing not found, or it does not belong to the authenticated merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '429': $ref: '#/components/responses/RateLimited' /ws/listings/detail: parameters: - in: query name: sku description: A listing's SKU provided by the seller on listing creation. required: false example: THEMODEL_RED schema: type: string - in: query name: listing_id description: Unique listing ID provided by Back Market. The UUID format is preferred, see 'id'. required: false example: 123 schema: type: integer - in: query name: id description: Unique listing ID provided by Back Market. required: false example: ceb5f83a-50d5-4d3b-85a4-a5da80abb64e schema: type: string format: uuid - name: Accept-Language in: header description: | Select what market will be used to apply filters and export data. Passed as the language code related to this market. required: false example: fr-fr schema: $ref: '#/components/schemas/Locale' get: tags: - Listings x-tier: 1 summary: Get listing details description: | Retrieve a specific `Listing` to check its information. ### Endpoint The 2 following endpoints provide exactly the same response: Or working with a filter on: If you don't have either the sku nor the listing_id, you can retrieve them by: **GET** `https://www.backmarket.fr/ws/listings/` security: - ApiKeyAuth: [] - BasicAuth: [] responses: '200': description: OK content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ListingPublic' - type: object required: - statuscode properties: statuscode: type: integer example: 200 '400': description: Invalid inputs (bad type…). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '401': description: Unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '403': description: Forbidden. Authenticated user is not a merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '404': description: Listing not found, or it does not belong to the authenticated merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' /ws/tasks/{taskId}: get: tags: - TaskManager summary: Get (batch) task x-tier: 1 description: | 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. security: - ApiKeyAuth: [] - BasicAuth: [] parameters: - name: taskId in: path required: true example: 4312 schema: type: integer responses: '200': description: OK content: application/json: schema: type: object properties: task_id: type: integer example: 1011013 action_status: type: integer example: 9 description: | Current task status (0 and 2: todo or in progress, 8: failed, 9: success). Check the TaskStatus enum to get the others. enum: - 0 - 2 - 3 - 7 - 8 - 9 last_action_error: description: Only filled when the processing has a major failure (status '8'). anyOf: - nullable: true - type: string example: Task has been interrupted. result: description: Report of task processing. Content depends on the task action. example: {} statuscode: type: integer example: 200 required: - task_id - action_status - last_action_error - result - statuscode '401': description: Unauthorized. The client making the request is not authenticated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' '404': description: Task does not exist, or is not accessible for the authenticated user. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1' /ws/buyback/v1/orders: get: x-tier: 2 summary: List of BuyBack orders tags: - BuyBack operationId: get-ws-buyback-v1-orders description: | List of paginated buyback orders. Caller must be an authenticated merchant. security: - ApiKeyAuth: [] - BasicAuth: [] parameters: - $ref: '#/components/parameters/status' - $ref: '#/components/parameters/productId' - $ref: '#/components/parameters/creationDate' - $ref: '#/components/parameters/modificationDate' - $ref: '#/components/parameters/shippingDate' - $ref: '#/components/parameters/receivedDate' - $ref: '#/components/parameters/suspendedDate' - $ref: '#/components/parameters/paymentDate' - $ref: '#/components/parameters/page' responses: '200': description: OK content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/buyback-base-paginated' - type: object properties: results: type: array uniqueItems: true items: $ref: '#/components/schemas/buyback-order' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' /ws/buyback/v1/orders/pending-reply: get: x-tier: 2 summary: List of BuyBack orders pending reply tags: - BuyBack operationId: get-ws-buyback-v1-orders-pending-reply description: | List of paginated BuyBack orders that are pending a reply from the refurbisher. Caller must be an authenticated refurbisher. parameters: - $ref: '#/components/parameters/page' responses: '200': description: OK content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/buyback-base-paginated' - type: object properties: results: type: array uniqueItems: true items: $ref: '#/components/schemas/buyback-order' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' /ws/buyback/v1/orders/suspend-reasons: get: x-tier: 2 summary: List of suspend reasons tags: - BuyBack operationId: get-ws-buyback-v1-orders-suspend-reasons description: | List of suspend reasons that could be used to put a BuyBack order in SUSPENDED state. Caller must be an authenticated merchant. security: - ApiKeyAuth: [] - BasicAuth: [] responses: '200': description: OK content: application/json: schema: type: array minItems: 0 items: $ref: '#/components/schemas/buyback-reason' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' /ws/buyback/v1/orders/{buybackOrderId}: get: x-tier: 2 summary: Retrieve a BuyBack order tags: - BuyBack operationId: get-ws-buyback-v1-order description: | Retrieve a single BuyBack order. Caller must be an authenticated merchant. security: - ApiKeyAuth: [] - BasicAuth: [] parameters: - $ref: '#/components/parameters/buybackOrderId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/buyback-order' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '404': description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' 5XX: description: Internal Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' /ws/buyback/v1/orders/{buybackOrderId}/messages: get: x-tier: 2 summary: List of a BuyBack order messages tags: - BuyBack operationId: get-ws-buyback-v1-orders-messages description: | List of paginated BuyBack order messages. Caller must be an authenticated refurbisher, owner of the provided buyback order. parameters: - $ref: '#/components/parameters/buybackOrderId' - $ref: '#/components/parameters/page' responses: '200': description: OK content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/buyback-base-paginated' - type: object properties: results: type: array uniqueItems: true items: $ref: '#/components/schemas/buyback-message' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '404': description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' 5XX: description: Internal Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' post: x-tier: 2 summary: Post a message on a BuyBack order tags: - BuyBack operationId: post-ws-buyback-v1-orders-messages description: | Create BuyBack order messages. Caller must be an authenticated refurbisher, owner of the provided buyback order. parameters: - $ref: '#/components/parameters/buybackOrderId' requestBody: description: A payload containing the message and supporting photos if any. content: application/json: schema: $ref: '#/components/schemas/buyback-message-payload' required: true responses: '201': description: OK content: application/json: schema: $ref: '#/components/schemas/buyback-message' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '404': description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '422': description: Unprocessable Entity content: application/problem+json: schema: $ref: '#/components/schemas/ValidationErrorResponseV3' 5XX: description: Internal Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' /ws/buyback/v1/orders/{buybackOrderId}/suspend: put: x-tier: 2 summary: Suspend a BuyBack order tags: - BuyBack operationId: put-ws-buyback-v1-orders-suspend description: | Suspend a BuyBack order with the provided reasons. Caller must be an authenticated refurbisher, owner of the provided buyback order. parameters: - $ref: '#/components/parameters/buybackOrderId' requestBody: description: A list of suspend reasons identifiers to put an order in SUSPENDED state. content: application/json: schema: $ref: '#/components/schemas/buyback-order-suspension-payload' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/buyback-order' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '404': description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '422': description: Unprocessable Entity content: application/problem+json: schema: $ref: '#/components/schemas/ValidationErrorResponseV3' 5XX: description: Internal Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' /ws/buyback/v1/orders/{buybackOrderId}/validate: put: x-tier: 2 summary: Validate BuyBack order tags: - BuyBack operationId: put-ws-buyback-v1-orders-validate description: Validate a BuyBack order by setting the state to VALIDATED. Caller must be an authenticated merchant, owner of the provided buyback order. parameters: - $ref: '#/components/parameters/buybackOrderId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/buyback-order' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '422': description: Unprocessable Entity content: application/problem+json: schema: $ref: '#/components/schemas/ValidationErrorResponseV3' 5XX: description: Internal Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' /ws/buyback/v1/orders/{buybackOrderId}/counter-offers/reasons: get: x-tier: 3 summary: Retrieve counter offer reasons tags: - BuyBack operationId: get-ws-counter-offer-reason description: | Get eligible reasons counter offer reasons for a given buyback order. Caller must be an authenticated refurbisher, owner of the provided buyback order. parameters: - $ref: '#/components/parameters/buybackOrderId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/buyback-counter-offer-reasons' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '404': description: Order not Found content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' 5XX: description: Internal Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' /ws/buyback/v2/orders/{buybackOrderId}/counter-offers: put: x-tier: 2 summary: Make a counteroffer tags: - BuyBack operationId: put-ws-refurbisher-counter-offer description: | Make a counter offer on an order. Caller must be an authenticated refurbisher, owner of the provided buyback order. parameters: - $ref: '#/components/parameters/buybackOrderId' requestBody: description: A payload containing the counter offer data. content: multipart/form-data: schema: $ref: '#/components/schemas/buyback-counter-offer-payload' required: true responses: '204': description: No content '400': description: Invalid request payload content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '404': description: Order id not found content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '422': description: Unprocessable request content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '429': description: Too Many Requests content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' 5XX: description: Internal Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' /ws/buyback/v1/listings: get: x-tier: 2 summary: List of BuyBack listings tags: - BuyBack operationId: get-ws-buyback-v1-listings description: | This endpoint returns a list of buyback listings based on a set of parameters. security: - ApiKeyAuth: [] - BasicAuth: [] parameters: - name: productId in: query required: false description: Product ID example: 1f9be4c7-19e6-4ebb-a8e2-1995130339f7 schema: type: string format: uuid title: ProductId nullable: true - name: cursor in: query required: false description: Cursor for the pagination example: bfc3e105-7209-4da2-9c25-1dc392e8d68c schema: type: string format: uuid title: Cursor nullable: true - name: pageSize in: query required: false description: Page size example: 6 schema: type: integer maximum: 100 minimum: 0 exclusiveMinimum: true default: 100 title: Pagesize responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/buyback-paginated-listing-response' '400': content: application/json: schema: $ref: '#/components/schemas/ProblemValidation' example: type: /errors/validation-error title: Validation error status: 400 errors: - type: /errors/missing title: Missing detail: Field required target: header.Bm-User-Id text/plain: schema: type: string example: Invalid HTTP request received. description: Bad Request '422': content: application/json: schema: $ref: '#/components/schemas/ProblemValidation' example: type: /errors/validation-error title: Validation error status: 422 errors: - type: /errors/missing title: Missing detail: Field required target: header.Bm-User-Id text/plain: schema: type: string example: Invalid HTTP request received. description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: /errors//errors/internal-error title: Internal server error status: 500 detail: An internal error happened. instance: https://example.org/error/condition description: Internal Server Error '503': content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: /errors//errors/service-unavailable title: Service unavailable status: 503 detail: The server was not ready to handle your request. instance: https://example.org/error/condition description: Service Unavailable /ws/buyback/v1/listings/{buybackListingId}: get: x-tier: 2 summary: Retrieve a Buyback listing tags: - BuyBack operationId: get-ws-buyback-v1-listing description: | This endpoint returns a single BuyBack listing based on its public id. security: - ApiKeyAuth: [] - BasicAuth: [] parameters: - $ref: '#/components/parameters/buybackListingId' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/buyback-listing' '400': content: application/json: schema: $ref: '#/components/schemas/ProblemValidation' example: type: /errors/validation-error title: Validation error status: 400 errors: - type: /errors/missing title: Missing detail: Field required target: header.Bm-User-Id text/plain: schema: type: string example: Invalid HTTP request received. description: Bad Request '422': content: application/json: schema: $ref: '#/components/schemas/ProblemValidation' example: type: /errors/validation-error title: Validation error status: 422 errors: - type: /errors/missing title: Missing detail: Field required target: header.Bm-User-Id text/plain: schema: type: string example: Invalid HTTP request received. description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: /errors//errors/internal-error title: Internal server error status: 500 detail: An internal error happened. instance: https://example.org/error/condition description: Internal Server Error '503': content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: /errors//errors/service-unavailable title: Service unavailable status: 503 detail: The server was not ready to handle your request. instance: https://example.org/error/condition description: Service Unavailable put: x-tier: 2 summary: Update a Buyback listing tags: - BuyBack operationId: put-ws-buyback-v1-listing description: | This endpoint updates a single BuyBack listing based on its public id. Only price updates are supported as of now. Note that, if you want to deactivate a buyback listing, you can simply update the listing price to zero (0) : It will automatically turn the listing offline. security: - ApiKeyAuth: [] - BasicAuth: [] parameters: - $ref: '#/components/parameters/buybackListingId' requestBody: required: true content: application/json: schema: type: object properties: prices: type: object additionalProperties: $ref: '#/components/schemas/Price' title: Payload example: prices: FR: amount: '34.50' currency: EUR responses: '202': description: Successful Response content: application/json: schema: type: object additionalProperties: false example: {} '400': content: application/json: schema: $ref: '#/components/schemas/ProblemValidation' example: type: /errors/validation-error title: Validation error status: 400 errors: - type: /errors/missing title: Missing detail: Field required target: header.Bm-User-Id text/plain: schema: type: string example: Invalid HTTP request received. description: Bad Request '422': content: application/json: schema: $ref: '#/components/schemas/ProblemValidation' example: type: /errors/validation-error title: Validation error status: 422 errors: - type: /errors/missing title: Missing detail: Field required target: header.Bm-User-Id text/plain: schema: type: string example: Invalid HTTP request received. description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: /errors//errors/internal-error title: Internal server error status: 500 detail: An internal error happened. instance: https://example.org/error/condition description: Internal Server Error '503': content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: /errors//errors/service-unavailable title: Service unavailable status: 503 detail: The server was not ready to handle your request. instance: https://example.org/error/condition description: Service Unavailable /ws/buyback/v1/competitors/{listingId}: get: description: | Get the buyback Backbox data related to your competitors, i.e. your online listings competing in a Backbox. parameters: - in: path name: listingId required: true schema: format: uuid title: Buyback listing Id type: string example: 7e1f4a8d-b1bb-47aa-9f77-2cca759eb41b responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/buybackCompetitor' type: array description: Each item is a competitor, ie. a `listing x market`, competing for a single buyback Backbox. description: Successful Response '401': description: Unauthorized '404': description: Not Found '422': description: Unprocessable Entity security: - ApiKeyAuth: [] - BasicAuth: [] summary: Get buyback competitors tags: - BuyBack x-category: domain x-tier: 2 /ws/orders: get: summary: Get the orders description: | Gets the orders for a given merchant and set of filters. Retrieves all the orders that are neither in state=0 (New Order) nor state=8 (Order not paid). ## Orders Summary of the `Product`/`Listing` structure : Product / Listing structure `Orders` workflow diagram : Orders workflow diagram `Orderlines` 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 _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.
10 `Order` is pending. The customer have ordered but still have time to pay. Merchant has to wait for payment, 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
9 `Orderline` is on hold. It needs to be validated by one of our partners before being accepted by the merchant. Not possible
8 `Orderline` is pending. The customer have ordered but still have time to pay. Merchant has to wait for payment. 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 in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) format
date_modification Datetime Date of the last modification in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) format
date_payment Datetime Date of the payment in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) format
date_shipping Datetime Date of the shipping in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) format
state Enum (Int) Refere to Table 5 for the Order states details.
orderlines Array[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-at: Austria
de-de: Germany
it-it: Italy
ja-jp: Japan
en-au: Australia
en-gb: United Kingdom
en-us: United States
nl-nl: Netherlands
pt-pt: Portugal
en-ie: Ireland
el-gr: Greece
sk-sk: Slovakia
sv-se: Sweden
### Table 8 - Address model
Field name Type/Size Description
company String/254 Company name.
last_name String/200 Last name.
last_name_pronunciation String/200 Last name pronunciation. This field is only used to handle Kana names for Japan.
first name String/200 First name.
first_name_pronunciation String/200 First name pronunciation. This field is only used to handle Kana names for Japan.
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 products ordered
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.
x-tier: 2 operationId: get-ws-list-order tags: - Orders security: - BasicAuth: [] parameters: - name: date_creation in: query description: Filter to get orders by their date of creation in RFC3339 format schema: type: string format: date-time example: '2014-06-24T12:55:57Z' required: false - name: date_modification in: query description: Filter to get orders by their date of last modification in RFC3339 format schema: type: string format: date-time example: '2014-06-24T12:55:57Z' required: false - name: country_code in: query description: Filter on the order country of origin schema: $ref: '#/components/schemas/CountryCode' example: fr-fr required: false - name: state in: query description: Filter on the order state. See OrderState object for more details. schema: $ref: '#/components/schemas/OrderState' example: 1 required: false - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' responses: '200': description: Return the orders matching the filter in the query parameters content: application/json: schema: type: object properties: count: type: integer example: 25 next: type: string nullable: true example: https://www.backmarket.fr/bm/merchants/users?page=3 previous: type: string nullable: true example: https://www.backmarket.fr/bm/merchants/users?page=1 results: type: array items: $ref: '#/components/schemas/Order' '400': description: Bad request '403': description: Forbidden '404': description: Webservices unavailable /ws/orders/{order_id}: get: summary: Get a specific order x-tier: 2 operationId: get-ws-specific-order tags: - Orders security: - BasicAuth: [] parameters: - in: path name: order_id schema: type: integer required: true description: The order identifier example: 1 responses: '200': description: Return the order with the specified id content: application/json: schema: $ref: '#/components/schemas/Order' '400': description: Bad request '403': description: Forbidden '404': description: Webservices unavailable post: summary: | Update a specific order description: | During shipping all orderlines are gathered in the same package. It is not necessary to specify the SKU when updating an order to state 3; indeed, every orderline of this order will be set to this state automatically. Merchants recover an order on state 1. x-tier: 2 operationId: update-ws-specific-order tags: - Orders security: - BasicAuth: [] parameters: - in: path name: order_id schema: type: integer required: true description: The order identifier example: 1 requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateOrder' responses: '200': description: Return the order with the specified id content: application/json: schema: $ref: '#/components/schemas/Order' '400': description: Bad request '403': description: Forbidden '404': description: The listing doesn't exist /ws/orders/{order_id}/invoice: post: summary: | Update customer invoice for order x-tier: 2 operationId: post-ws-specific-order-invoice tags: - Orders security: - BasicAuth: [] parameters: - in: path name: order_id schema: type: integer required: true description: The order identifier example: 1 requestBody: content: multipart/form-data: schema: type: object properties: invoice: type: array items: type: string format: binary responses: '200': description: The invoice has been updated '400': description: Bad request '403': description: Forbidden '404': description: Order doesn't exist /ws/orderlines/{orderline_id}: patch: summary: | Update a specific orderline x-tier: 2 operationId: update-ws-specific-orderline tags: - Orderline security: - BasicAuth: [] parameters: - in: path name: orderline_id schema: type: integer required: true description: The orderline identifier example: 1 requestBody: content: application/json: schema: type: object minProperties: 1 properties: imei: type: string maxLength: 15 example: '153124587625348' description: | Unique device identifier. Applicable to any product category. Once registered, the value cannot be corrected. serial_number: type: string maxLength: 50 example: SN-ABC123XYZ description: | Unique product serial number. Applicable to any product category. Once registered, the value cannot be corrected. description: | At least one of `imei` or `serial_number` must be provided. Both can be submitted in a single request. responses: '200': description: Returns the identifiers updated on the orderline content: application/json: schema: type: object properties: imei: type: string maxLength: 15 example: '153124587625348' serial_number: type: string maxLength: 50 example: SN-ABC123XYZ '400': description: Bad request '403': description: Forbidden '404': description: The orderline doesn't exist '422': description: Unprocessable entity /ws/shipping/v1/deliveries: get: description: | This API is for merchants who are subscribed to the BackShip service. Once an orderline has been accepted via the Orderline API, a shipping label is automatically created corresponding to this orderline and can be retrieved from this endpoint via the field `labelUrl`. The state of the orderline must be updated once the product has been shipped. operationId: GetDeliveries parameters: - description: Page number example: 2 in: query name: page schema: type: integer - description: Order ID example: 42 in: query name: order_id schema: type: integer - description: Get deliveries created at and after this datetime example: '2021-05-05T06:58:31' in: query name: start_date schema: format: date-time type: string - description: Get deliveries created before and at this datetime example: '2021-05-05T06:58:31' in: query name: end_date schema: format: date-time type: string - description: Get deliveries picked up at and after this datetime example: '2021-05-05T06:58:31' in: query name: pickup_start_date schema: format: date-time type: string - description: Get deliveries picked up before and at this datetime example: '2021-05-05T06:58:31' in: query name: pickup_end_date schema: format: date-time type: string - description: State of the order example: 3 in: query name: order_state schema: enum: - 0 - 1 - 3 - 8 - 9 type: integer - description: Whether shipments label have been scanned example: true in: query name: hub_scanned schema: type: boolean responses: '200': content: application/json: schema: properties: count: description: Total number of deliveries example: 42 type: integer next: description: Url to get the next paginated deliveries list. Null if no next page example: https://preprod.backmarket.fr/ws/shipping/v1/deliveries?page=2 nullable: true type: string previous: description: Url to get the previous paginated deliveries list. Null if no previous page example: https://preprod.backmarket.fr/ws/shipping/v1/deliveries?page=1 nullable: true type: string results: description: List of deliveries items: $ref: '#/components/schemas/Delivery' type: array required: - count - next - previous - results type: object description: List of deliveries '422': content: application/json: schema: $ref: '#/components/schemas/OrderIdValidationError' description: Unprocessable Entity summary: Return deliveries list tags: - Backship x-category: domain x-tier: 2 security: - ApiKeyAuth: [] - BasicAuth: [] /ws/shipping/v1/returns: get: summary: Return product returns list description: | This API is for merchants who are subscribed to the BackShip service. Once a product return has been created, a shipping label is automatically created corresponding to this return and can be retrieved from this endpoint via the field `label`. operationId: GetReturns tags: - Backship x-tier: 2 security: - ApiKeyAuth: [] - BasicAuth: [] parameters: - name: page in: query description: Page number schema: type: integer example: 2 - name: order_id in: query description: Order ID schema: type: integer example: 42 - name: start_date in: query description: Get returns created at and after this datetime schema: type: string format: date-time example: '2021-05-05T06:58:31' - name: end_date in: query description: Get returns created before and at this datetime schema: type: string format: date-time example: '2021-05-05T06:58:31' - name: pickup_start_date in: query description: Get returns picked up at and after this datetime schema: type: string format: date-time example: '2021-05-05T06:58:31' - name: pickup_end_date in: query description: Get returns picked up before and at this datetime schema: type: string format: date-time example: '2021-05-05T06:58:31' - name: order_state in: query description: State of the order schema: type: integer enum: - 0 - 1 - 3 - 8 - 9 example: 3 - name: hub_scanned in: query description: Whether shipments label have been scanned schema: type: boolean example: true responses: '200': description: List of returns content: application/json: schema: type: object required: - count - next - previous - results properties: count: type: integer description: Total number of returns example: 42 next: type: string description: Url to get the next paginated returns list. Null if no next page example: https://preprod.backmarket.fr/ws/shipping/v1/returns?page=2 nullable: true previous: type: string description: Url to get the previous paginated returns list. Null if no previous page example: https://preprod.backmarket.fr/ws/shipping/v1/returns?page=1 nullable: true results: type: array description: List of returns items: $ref: '#/components/schemas/Return' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/OrderIdValidationError' /ws/shipping/v1/deliveries/{id}: get: description: | This API is for merchants who are subscribed to the BackShip service. Once an orderline has been accepted via the Orderline API, a shipping label is automatically created corresponding to this orderline and can be retrieved from this endpoint via the field `labelUrl`. The state of the orderline must be updated once the product has been shipped. operationId: GetDelivery parameters: - description: Delivery ID example: 42 in: path name: id required: true schema: type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/Delivery' description: Delivery details '404': description: Delivery entry not found summary: Return details about a specific delivery tags: - Backship x-category: domain x-tier: 2 security: - ApiKeyAuth: [] - BasicAuth: [] /ws/shipping/v1/returns/{id}: get: description: | This API is for merchants who are subscribed to the BackShip service. Once a product return has been created, a shipping label is automatically created corresponding to this return and can be retrieved from this endpoint via the field `label`. operationId: GetReturn parameters: - description: Return ID example: 42 in: path name: id required: true schema: type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/Return' description: Return details '404': description: Return entry not found summary: Return details about a specific product return tags: - Backship x-category: domain x-tier: 2 security: - ApiKeyAuth: [] - BasicAuth: [] /ws/sav: get: operationId: getCareFolderList x-tier: 2 parameters: - description: Retrieve Care Folders with an ID higher than `last_id` example: 123 in: query name: last_id required: false schema: type: integer - description: | Retrieve Care Folders with state equal to `state`. * 0 - OPEN * 9 - CLOSED example: 9 in: query name: state required: false schema: enum: - 0 - 9 type: integer - description: Retrieve Care Folders for a specific Orderline example: 456 in: query name: orderline required: false schema: type: integer - description: Retrieve Care Folders more recent than `last_modification_date`. Format is YYYY-MM-DD-hh-mm example: 1970-01-01-00-00 in: query name: last_modification_date required: false schema: type: string - description: Retrieve Care Folders having messages more recent than `last_message_date`. Format is YYYY-MM-DD-hh-mm example: 1970-01-01-00-00 in: query name: last_message_date required: false schema: type: string - description: Page number to retrieve (10 entries per page). example: 2 in: query name: page required: false schema: type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/getCareFolderListResponse' description: Retrieved '401': description: Guest user not allowed '403': description: Authenticated user not allowed summary: Get a list of Care Folders attached to a Seller description: | ## Rate Limiting This endpoint is rate limited to 520 requests per minute and 4000 per day. If you exceed this limit, you will receive a `429` status code. tags: - Care security: - ApiKeyAuth: [] - BasicAuth: [] /ws/sav/{careFolderId}: get: operationId: getCareFolderDetails x-tier: 2 parameters: - description: ID of the Care Folder to retrieve example: 123 in: path name: careFolderId required: true schema: type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/getCareFolderDetailsResponse' description: Retrieved '401': description: Guest user not allowed '403': description: Authenticated user not allowed '404': description: Care Folder does not exist summary: Get the details of a Care Folder description: | ## Rate limiting This endpoint is rate limited to 600 requests per minute and 40000 requests per day. If you exceed this limit, you will receive a `429` status code. tags: - Care security: - ApiKeyAuth: [] - BasicAuth: [] /ws/sav/{careFolderId}/problem: post: operationId: postProblem x-tier: 2 parameters: - description: ID of the Care Folder on which the problem is declared example: 123 in: path name: careFolderId required: true schema: type: integer requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/postProblemRequest' responses: '201': description: Declared '401': description: Guest user not allowed '403': description: Forbidden '404': description: Care Folder does not exist '413': description: File too large or too many attachments '422': description: Attachments are mandatory for this problem type / Only OTHER problem type is allowed for IDs lower than 100,000,000 / Cannot declare problem on this Care Folder summary: Declare a problem on a Care Folder description: | Declare a problem on a Care Folder. The `problem_type` field specifies the type of problem. If omitted, it defaults to `OTHER`. Attachments are **mandatory** for the following problem types: `DAMAGED_PACKAGE`, `ITEM_NOT_RECEIVED`, `OOW_ITEM`. For Care Folders with ID below 100,000,000, only `OTHER` is accepted and no message or attachments can be provided. ## Rate limiting This endpoint is rate limited to 750 requests per minute and 1000 requests per day. If you exceed this limit, you will receive a `429` status code. tags: - Care security: - ApiKeyAuth: [] - BasicAuth: [] /ws/sav/refund: post: operationId: postRefundCreate x-tier: 2 requestBody: content: application/json: schema: $ref: '#/components/schemas/postRefundCreateRequest' responses: '201': content: text/plain: schema: description: Summary of the created refund example: 99€ refunded on the sku 123456 type: string description: Refund Created '400': description: Payload not acceptable '401': description: Guest user not allowed '403': description: Authenticated user not allowed '404': description: Orderline does not exist summary: Create a refund on an Orderline description: | ## Rate limiting This endpoint is rate limited to 500 requests per day. If you exceed this limit, you will receive a `429` status code. tags: - Care security: - ApiKeyAuth: [] - BasicAuth: [] /ws/sav/{careFolderId}/msg: post: operationId: postMessage x-tier: 2 parameters: - description: ID of the Care Folder to retrieve example: 123 in: path name: careFolderId required: true schema: type: integer requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/postMessageRequest' responses: '201': content: application/json: schema: $ref: '#/components/schemas/postMessageResponse' description: Created '400': description: Payload not acceptable '401': description: Guest user not allowed '403': description: Authenticated user not allowed '404': description: Care Folder does not exist summary: Post a message on the After Sales Platform for a Care Folder description: | Posting a message to a closed folder will reopen it. ## Rate limiting This endpoint is rate limited to 560 requests per minute and 40000 requests per day. If you exceed this limit, you will receive a `429` status code. tags: - Care security: - ApiKeyAuth: [] - BasicAuth: [] /ws/sav/{careFolderId}/item-transfer: post: operationId: postItemTransfer x-tier: 2 parameters: - description: ID of the Care Folder on which the item is transferred back to the customer example: 123 in: path name: careFolderId required: true schema: type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/postItemTransferCreateRequest' required: true responses: '201': description: Success '400': description: An item transfer with this tracking number already exists '403': description: Authenticated user not allowed '404': description: Care folder does not exit '422': description: Cannot create item transfer / Care folders with ID above 100,000,000 are not yet supported on this endpoint due to an ongoing internal migration '500': description: Shipment registration failed or Internal server error summary: Declare an item transfer back to customer description: | ## Rate limiting This endpoint is rate limited to 292 requests per minute and 500 requests per day. If you exceed this limit, you will receive a `429` status code. tags: - Care security: - ApiKeyAuth: [] - BasicAuth: [] /ws/listings_bi: get: description: | Get the Backbox data related to your competitors, i.e. your online listings competing in a Backbox. You can call this endpoint twice every hour for each country. Backbox (previously named Buybox) is the listing displayed at a given time on the website when it has the best ratio quality score per price. This endpoint is being deprecated in favor of the /ws/backbox/v1/competitors endpoint. operationId: GetBackboxData parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' responses: '200': content: application/json: schema: properties: count: description: Total number of backbox data per listing example: 42 type: integer next: description: URL to get the next paginated backbox data per listing list. Null if no next page example: https://www.backmarket.fr/ws/listings_bi/?page=2 nullable: true type: string previous: description: URL to get the previous paginated backbox data per listing list. Null if no previous page example: https://www.backmarket.fr/ws/listings_bi/?page=1 nullable: true type: string results: description: List of backbox data per listing items: $ref: '#/components/schemas/Backbox' type: array required: - count - next - previous - results type: object description: List of backbox data per listing '403': description: Permission denied content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '404': description: Webservices unavailable content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' '429': description: Too many calls content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponseV3' summary: Return backbox data per listing list tags: - Backbox x-category: domain x-tier: 2 /ws/backbox/v1/competitors/{listingId}: get: description: | Get the Backbox data related to your competitors, i.e. your online listings competing in a Backbox. You can call this endpoint twice per second per API token. [Here is an example](https://colab.research.google.com/drive/12jHZ3AQG8mQjjAvulG9zVvfC_psEOKjh?usp=sharing) of how you can use the Listings and the BackBox APIs together, in order to adjust your listings' prices in case there are some good opportunities. This can allow you to win more BackBoxes automatically with small prices reductions. parameters: - in: path name: listingId required: true schema: format: uuid title: Listing Id type: string example: 7e1f4a8d-b1bb-47aa-9f77-2cca759eb41b responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/Competitor' type: array description: Each item is a competitor, ie. a `listing x market`, competing for a single Backbox. description: Successful Response '401': description: Unauthorized '404': description: Not Found '422': description: Unprocessable Entity security: - ApiKeyAuth: [] - BasicAuth: [] summary: Get competitors tags: - Backbox x-category: domain x-tier: 2 components: securitySchemes: ApiKeyAuth: in: header name: Authorization type: apiKey description: |- Token authentication is done with Basic authentication. Prefix the value with \"Basic\" and use the token you created in the backoffice in the Integrations option page. BasicAuth: type: http scheme: basic schemas: Locale: pattern: ^[a-z]{2}-[a-z]{2}$ type: string CategoryTree: type: object properties: category_id: type: integer example: 1 category_name: type: string example: Smartphone marketplace_category_id: type: integer example: 123 is_leaf: type: boolean example: false attributes: type: array items: type: object properties: field: type: string example: color field_name: type: string example: Couleur type: type: integer description: | - 0: DECIMAL, 1:INTEGER, 2:STRING, 3:MULTIPLE_CHOICE example: 2 enum: - 0 - 1 - 2 - 3 allowed_values: type: string description: List of allowed values for the given product attribute, separated by commas. example: Unlocked GSM, Unlocked CMDA,AT&T,Verizon,Sprint,T Mobile,Boost Mobile,No SIM slot required: type: boolean example: true required: - field - field_name - type - allowed_values - required required: - category_id - category_name - marketplace_category_id - is_leaf - childrens - attributes Error: description: '' properties: code: type: string data: type: object docLink: type: string message: type: string target: type: string required: - code - message type: object ErrorResponseV2: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' minItems: 1 requestId: type: string description: Let you trace errors in applicative logs required: - errors ErrorResponseV1: type: object properties: error: $ref: '#/components/schemas/Error' requestId: description: Let you trace errors in applicative logs type: string required: - error ListingStateValue: type: integer description: | Deprecated, please use the "grade" field. Aethestic grade. Values: 9 (Premium), 0 (Excellent), 1 (Very good), 2 (Good), 3 (Fair), 4 (Stallone) example: 4 enum: - 9 - 0 - 1 - 2 - 3 - 4 AestheticGradeValue: type: string description: Aethestic grade. example: EXCELLENT enum: - PREMIUM - EXCELLENT - VERY_GOOD - GOOD - FAIR - STALLONE ListingPublic: properties: backmarket_id: description: Deprecated product ID. Please use the UUID format, see field 'product_id'. example: 42 type: integer comment: nullable: true description: Comment. Maximum 500 characters. example: This is an iPhone 6S - 64Go - Blue working with all operators type: string currency: description: Currency of 'price' example: EUR type: string id: description: Listing ID example: 7a97a1b6-547e-4718-bc72-5b84aca91b09 type: string format: uuid listing_id: description: Listing ID (deprecated). Please use the UUID format, see field 'id'. example: 4567 type: integer max_price: description: Maximum allowed price for this listing, or it will not be online. example: '199.90' type: string min_price: description: Minimum acceptable price for the Backpricer. example: '160.99' nullable: true type: string price: description: Price of the listing in the 'currency' example: '160.99' type: string product_id: type: string description: Product ID format: uuid example: 7a97a1b6-547e-4718-bc72-5b84aca91b09 publication_state: enum: - 0 - 1 - 2 - 3 - 4 example: 2 type: integer quantity: description: Available stock. example: 12 type: integer shippings: description: | Shippings defined at listing level (if any). Does not include shippings defined at category level nor the global ones. items: properties: country_code: description: | The market where this shipping option is available. Passed as the language code of this market. example: it-it type: string shipper: description: The company that manages the delivery. example: UPS type: string shipper_display: description: The company that manages the delivery. example: UPS type: string shipping_delay: description: Expected shipping delay in hours. example: 24 type: integer shipping_price: description: Price of the shipping option, using currency of listing. example: '0.00' type: string required: - shipping_price - shipping_delay - shipper - shipper_display - country_code type: object type: array sku: description: SKU provided by the seller on listing creation. example: IPHONE_6S_64GO_BLUE_CORRECT type: string state: $ref: '#/components/schemas/ListingStateValue' grade: $ref: '#/components/schemas/AestheticGradeValue' title: description: Product title example: iPhone 6S - 64Go - Blue - Unlocked type: string warranty_delay: description: Warranty period in months (12 months minimum). example: 24 type: integer new_battery: description: |- The device has a new battery. Values (case-insensitive): “true” if the device has a new battery, else “false”. Seller must be eligible to sell new battery devices to be able to list such listings. default: false example: true type: boolean required: - id - listing_id - product_id - backmarket_id - title - shippings - state - grade - quantity - currency - sku - publication_state - warranty_delay - price - comment - min_price - max_price type: object Shipper: type: string nullable: true description: | Name of the shipper, the company that manages the delivery. Some shippers may not be available in all countries. Call us to add your shipper. example: DHL Express enum: - Allied Express - Aramex Australia - Australia Post - Australia Post Express - Austrian Post - BPost - BRT - Chronopost - Chronopost Express - ColisPrivé - Colissimo - Correos - Correos Express - Couriers Please - CTT - Cubyn - Cubyn Express - DB Schenker - Deutsche Post - DHL - DHL DE - DHL Express - DHL EXPRESS - DHL NL - DHL Parcel Spain - DHL SP - DPD - DPD Benelux - DPD DE - DPD FR - DPD International - DPD UK - DPD UK Express - DTDC Australia - FedEx - FedEx - 2Days - FedEx Express - FedEx International - FedEx - Overnight - Geodis - Girard Agediss - Livraison dans la pièce de votre choix sur RDV - GLS - GLS - DE - GLS - FR - GLS International - GLS - IT - GLS-SPAIN - GLS Spain Express - Hermes - DE - Hermes - UK - Japan Post - Livraison au pied du camion - Livraison dans la pièce de votre choix - Logoix - MRW - Murfy transporteur - NACEX - ParcelForce Express - Parcelforce (Worldwide) - Parcelpoint Pty Ltd - Poste Italiane - Post NL - Private Transporter - Royal Mail - Royal Mail Express - Sagawa - Seino - Sendle - Seur - Socolissimo - Star Track Express - TIPSA - TIPSA Express - TNT - TNT Australia - TNT Express - Tourline - UPS - UPS 2 days - UPS 2nd Day Air - UPS Express - UPS express save - UPS Ground - UPS next day - UPS Overnight - UPS standard - USPS - USPS Express - USPS - First Class - USPS - Priority Mail - USPS - Priority Mail Express - VIR - Yamato - Zeleris - Other buybackOrderState: type: string description: Buyback order state enum: - NEW - PENDING - TO_SEND - SENT - RECEIVED - COUNTER_PROPOSAL - VALIDATED - PAID - MONEY_TRANSFERED - SUSPENDED example: TO_SEND buyback-base-paginated: title: base_paginated type: object properties: count: type: number description: Total number of objects or items example: 133 next: type: string description: URL pointing to the next page example: https://www.backmarket.fr/ws/buyback/v1/orders?page=3 nullable: true previous: type: string description: URL pointing to the previous page example: https://www.backmarket.fr/ws/buyback/v1/orders?page=1 nullable: true required: - count - next - previous buybackListingGrade: type: string description: Quality grade of the buyback order enum: - DIAMOND - PLATINUM - GOLD - SILVER - BRONZE - STALLONE example: DIAMOND buybackKycDocuments: type: string description: Type of the KYC document enum: - PASSPORT - ID - ID_CARD_FRONT - ID_CARD_BACK - BANK_STATEMENT - DRIVING_LICENCE_FRONT - DRIVING_LICENCE_BACK example: PASSPORT buyback-reason: title: Suspend or counter offer reason description: Reason used to suspend a buyback order or make a counter offer on it type: object properties: message: type: string description: Details of the reason example: Empty parcel identifier: type: string description: Identifier of the reason example: parcel_empty category: type: string description: Category of the reason example: Transport issue required: - message - identifier buyback-order: description: Buyback order sent back by 'ws/buyback/' endpoints type: object properties: orderPublicId: type: string description: buyback order public identifier example: US-24527-ABCDE creationDate: type: string description: Buyback Order creation date example: '2019-03-21T14:28:30+01:00' modificationDate: type: string description: Buyback Order last modification date example: '2019-03-26T08:00:53+01:00' shippingDate: type: string description: Buyback Order shipping date example: '2019-03-21T14:37:54+01:00' suspensionDate: type: string description: Buyback Order suspension date example: '2019-03-21T14:37:54+01:00' receivalDate: type: string description: Buyback Order reception date example: '2019-03-21T14:37:54+01:00' paymentDate: type: string description: Buyback Order payment date example: '2019-03-21T14:38:11+01:00' counterProposalDate: type: string description: Last counter proposal date example: '2019-03-21T14:37:54+01:00' status: $ref: '#/components/schemas/buybackOrderState' market: type: string description: Idenfitication code of the market in which the buyback order was placed example: FR transferCertificateLink: type: string description: URL where the transfer certificate can be downloaded example: https://tranfer-certificate.com listing: type: object required: - productId - title - grade properties: sku: type: string example: '21000021' description: (Stock-keeping unit) Identification number of the product productId: type: number example: 2311 description: Identification number of the product bought back by the merchant title: type: string description: Name of the product bought back by the merchant example: Apple iPhone XS 64 Go grade: $ref: '#/components/schemas/buybackListingGrade' customer: type: object properties: firstName: type: string description: First name of the customer who wants to sell a device example: John lastName: type: string description: Last name of the customer who wants to sell a device example: Doe phone: type: string description: Phone number of the customer example: '+33699887766' dateOfBirth: type: string description: Birthdate of the customer example: '1970-03-21' documents: type: array items: type: object properties: type: $ref: '#/components/schemas/buybackKycDocuments' url: type: string description: URL where the document can be downloaded example: https://bucket.com/user_document/passport.jpeg required: - type - url returnAddress: type: object description: Address where the parcel can be returned required: - country properties: address1: type: string description: Main address description example: 10, Downing street address2: type: string example: 3rd floor description: Details on the address city: type: string example: London description: City of the address zipcode: type: string example: '93100' description: Zipcode of the address country: type: string example: United Kingdom description: Country of the address originalPrice: type: object description: Initial offer price required: - value - currency properties: value: type: number description: Initial offer amount example: 1000 currency: type: string description: Initial price currency example: EUR counterOfferPrice: type: object description: Counter offer price set by the merchant properties: value: type: number description: Amount set by the merchant example: 900 currency: type: string description: Currency of the counter offer price set by the merchant example: EUR required: - value - currency trackingNumber: type: string description: Tracking number of the parcel example: 8R41352499203 shipper: type: string description: Shipper of the parcel example: DHL suspendReasons: type: array description: List of reasons set by the merchant when putting the buyback order on hold items: $ref: '#/components/schemas/buyback-reason' counterOfferReasons: type: array description: List of reasons set by the merchant when making a counter offer on the buyback order items: $ref: '#/components/schemas/buyback-reason' required: - orderPublicId - creationDate - modificationDate - shippingDate - status - market - listing - customer - returnAddress - originalPrice - transferCertificateLink ErrorResponseV3: type: object properties: error: $ref: '#/components/schemas/Error' status: description: HTTP status code type: integer title: description: summary of the problem type type: string nullable: true type: description: unique problem identifier type: string nullable: true requestId: description: ID of the request type: string required: - error - status - title - type buybackMessageAuthor: type: string description: Message author enum: - Merchant - Client - BackMarket - Unknown example: Merchant buyback-message: description: Buyback order message sent back by 'ws/buyback/' endpoints type: object properties: body: type: string description: Message content example: Hello world! date: type: string description: Message creation date example: '2019-04-04T14:10:00+02:00' attachments: type: array items: type: string description: Url of the attachments example: https://storage-server/sourcing_pj/my_attachement.txt author: $ref: '#/components/schemas/buybackMessageAuthor' required: - date - author buyback-message-payload: type: object properties: message: type: string minLength: 1 description: Counter offer explanation message example: Scratched screen files: type: array uniqueItems: true description: Photos supporting the message. If there is no photo, an empty array should be passed. items: type: object properties: name: type: string minLength: 1 description: Name of the photo example: photo_1.jpg content: type: string minLength: 1 description: Content of the photo example: binary-content required: - name - content required: - files - message ValidationErrorResponseV3: type: object allOf: - $ref: '#/components/schemas/ErrorResponseV3' - type: object properties: errors: type: array items: type: object properties: type: type: string minLength: 1 example: /errors/email-conflict title: type: string minLength: 1 example: Email conflict error detail: type: string minLength: 1 example: This email is already taken target: type: string minLength: 1 example: email context: type: object example: {} required: - type - title - target buyback-order-suspension-payload: type: object properties: reasons: type: array description: List of suspension reasons identifiers example: - parcel_damaged - broken_device items: type: string example: parcel_damaged required: - reasons buybackCounterOfferReasonCategory: type: string description: identifier of the counter offer reason category enum: - functional - esthetics - other example: functional buyback-counter-offer-reasons: type: array description: List of eligible counter offer reasons for a given buyback order items: type: object properties: id: $ref: '#/components/schemas/buybackCounterOfferReasonCategory' label: type: string example: Aesthetics description: Translated description of the category of counteroffer reasons reasons: type: array description: possible counter offer reasons items: type: object properties: id: type: string description: Identifier of the counter offer reason to be declared, this identifier should be sent example: broken_screen label: type: string description: Translated description of the counter offer example: Broken screen required: - id - label required: - id - label - reasons buyback-counter-offer-payload: type: object properties: price: type: number description: counteroffer price nullable: false comment: type: string maxLength: 200 description: Counteroffer explanation message nullable: true example: The screen is too scratched. reasons: type: array description: List of counteroffer reasons identifiers. Must come from the /counter-offers/reasons endpoint. items: type: string example: parcel_damaged files: type: array uniqueItems: true description: Files that prove the counteroffer is legitimate (.jp(e)g, .png, .pdf) items: type: string format: binary required: - price - reasons - files MonetaryAmount: title: MonetaryAmount type: object example: amount: '42' currency: EUR properties: amount: type: string pattern: ^\d*(\.\d*)?$ description: |- Amount is a human representation of a decimal, without any localization. Trailing zero in decimal places MAY be passed (eg: "13.0") Values with more decimal places than the minor unit of the currency MUST NOT be considered as valid. The trailing zero guideline has priority over it. ``` {"amount": "13.000", "currency": "EUR"} is also valid, but {"amount": "13.123", "currency": "EUR"} is not. ``` Leading zero SHOULD be in the amount if the value is between 0 and 1. Decimal separator MAY be supplied without decimal places. example: '42' currency: type: string pattern: ^[A-Z]{3}$ description: | The currency MUST be represented as a code following the ISO 4217 standard: "EUR" for euro, "USD" for U.S. dollar, etc. example: EUR required: - amount - currency description: |- Back Market common monetary amount model. Empty monetary amount (ie amount equals 0) property SHOULD be exposed according to the following rules: - `{ amount: '0.00', currency: 'EUR|USD|...' }` When a monetary amount is 0, and is intended to be displayed. Ex: free warranty, etc. - `null` when a monetary amount is 0, and is intended to be hidden. Ex: discount: `null`, when a user has no discount. - omitted, when a monetary amount is non-existent. Ex, when a feature is disabled: backlabel: `null` means BackLabel feature is enabled but not on one particular item, while not having backlabel field at all means BackLabel feature is disabled. x-internal: false Price: title: Price description: Back Market common Price model oneOf: - $ref: '#/components/schemas/MonetaryAmount' x-internal: false buyback-aesthetic-grade-code: title: Buyback aesthetic grade code type: string example: FUNCTIONAL_FLAWLESS enum: - FUNCTIONAL_FLAWLESS - FUNCTIONAL_GOOD - FUNCTIONAL_USED - FUNCTIONAL_CRACKED - NOT_FUNCTIONAL_USED - NOT_FUNCTIONAL_CRACKED buyback-listing: description: Buyback listing type: object title: Buyback listing properties: id: type: string format: uuid title: Id example: d80340a5-6460-4a9c-a8a6-c1c6d56b11c7 productId: type: string format: uuid title: Productid example: 263b4873-3b6b-413e-815e-c3451117893c prices: type: object title: Prices additionalProperties: $ref: '#/components/schemas/Price' example: FR: amount: '34.50' currency: EUR aestheticGradeCode: $ref: '#/components/schemas/buyback-aesthetic-grade-code' sku: type: string nullable: true title: Sku description: SKU defined by the seller. In case of a trade-in listing, it can be null. example: seller-sku markets: items: type: string pattern: ^[A-Z]{2}$ description: 'List of markets in which the listing is online. Market Code MUST be represented as a two-letter code following the ISO 3166-1 alpha-2 standard: "FR" for France, "GB" for Great Britain, etc.' example: FR type: array title: Markets required: - id - productId - prices - aestheticGradeCode - sku - markets buyback-paginated-listing-response: title: BuyBack paginated listing response type: object properties: next: type: string nullable: true title: Next page example: https://www.backmarket.fr/ws/buyback/v1/listings?cursor=87eeccf7-7b1a-4897-8f71-09899b337a97 results: items: $ref: '#/components/schemas/buyback-listing' type: array title: Results required: - next - results Problem: title: Problem Details for HTTP APIs description: Definition of [RFC7807](https://tools.ietf.org/html/rfc7807) problem detail type: object properties: type: type: string description: | Unique problem identifier. The RFC says that it should be an URI but we prefere not to use that as it's not scalable and user friendly. Only readable format are accepted follwoing this pattern "[a-z-/]*", eg (`/errors/authorization-failed`). default: /errors/unknown example: /errors/authorization-failed title: type: string description: | A short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem except for purposes of localization. example: Unable to process payment status: type: integer format: int32 description: | The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 100 maximum: 599 example: 503 detail: type: string description: | A human readable explanation specific to this occurrence of the problem. example: Payment authorization failed because your card is expired instance: type: string description: | An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: https://example.org/error/condition required: - type - title - status x-internal: false ProblemValidationErrorMember: description: '' type: object example: type: /errors/email-conflict title: Email conflict error detail: This email is already taken target: email context: suggestedEmails: - john.doe.123@gmail.com - john.doe.456@gmail.com ageLimit: 18 properties: type: type: string minLength: 1 example: /errors/email-conflict title: type: string minLength: 1 example: Email conflict error detail: type: string minLength: 1 example: This email is already taken target: type: string minLength: 1 example: email context: type: object example: {} required: - type - title - target x-internal: false ProblemValidation: title: ProblemValidation type: object allOf: - $ref: '#/components/schemas/Problem' - type: object properties: errors: type: array items: $ref: '#/components/schemas/ProblemValidationErrorMember' example: type: /errors/bad-request title: Your request parameters didn't validate. instance: /user/signup status: 400 errors: - type: /errors/validation-error title: Email conflict error detail: This email is already taken target: email context: suggestedEmails: - john.doe.123@gmail.com - john.doe.456@gmail.com ageLimit: 18 - type: /errors/validation-error title: Password not accepted detail: Password is not accepted due to reason.... target: password context: minimumTotal: 8 minimumNumber: 2 minimumUppercase: 3 minimumSpecialCharacter: 2 description: '' x-internal: false MarketCode: type: string description: Two-letter country code of the market. Format ISO_3166-2 enum: - FR - BE - DE - IT - ES - GB - AT - NL - US - FI - PT - IE - GR - SK - SE - JP example: FR buybackCompetitor: properties: listing_id: description: The listing public id of this competitor. format: uuid title: Listing Id type: string product_id: description: The product public id of this competitor. format: uuid title: Product Id type: string market: anyOf: - $ref: '#/components/schemas/MarketCode' description: Two-letter country code of the market. Format ISO_3166-2. price: allOf: - $ref: '#/components/schemas/MonetaryAmount' description: The buyback price set for this competitor. price_to_win: allOf: - $ref: '#/components/schemas/MonetaryAmount' description: The price that the competitor must set to win the buyback backbox. is_winning: description: Whether or not this competitor is winning the buyback backbox. title: Is Winning type: boolean required: - listing_id - product_id - market - price_to_win - winner_price - is_winning title: BuybackCompetitor type: object CountryCode: type: string enum: - fr-fr - fr-be - es-es - de-de - de-at - it-it - ja-jp - en-au - en-gb - en-us - nl-nl - pt-pt - en-ie - el-gr - sk-sk - sv-se example: fr-fr OrderState: type: integer enum: - 0 - 10 - 1 - 3 - 8 - 9 description: | Order state. | 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. | | 10 | Order is pending. The customer has ordered but still has time to pay. The merchant has to wait for payment, and the orders in this state must not be shipped. | | 1 | Payment is checked and validated. The merchant has to process (accept or cancel) the orderlines. | | 3 | Order shipping is pending. The payment and the order (i.e. all orderlines) have been validated. The merchant has to ship the package to the customer. | | 8 | Order is not paid. Payment process has failed, and the merchant must ignore this order. | | 9 | Order processed. The merchant has shipped the package. | example: 1 Address: type: object properties: id: type: integer example: 1 country: type: string description: ISO 3166-1 alpha-2 country code. example: FR city: type: string example: Paris postalCode: type: string example: '75003' firstName: type: string example: Victor lastName: type: string example: Hugo company: type: string example: backmarket phoneNumber: type: string description: E.164 formatted phone number. example: '+33639981234' state: type: string example: California street: type: string example: 3, Imaginary Street street2: type: string example: Apartement X OrderLineState: type: integer enum: - 0 - 9 - 8 - 1 - 2 - 3 - 4 - 5 - 6 - 7 description: | Orderline state. | State | Description | Possible next states | |-------|--------------------------------------------------------------------------------------------------------------|----------------------| | 0 | New orderline. The merchant has to wait for payment confirmation. | Not possible | | 9 | Orderline is on hold. It needs to be validated by our partner before being accepted by the merchant. | Not possible | | 8 | Orderline is pending. The customer has ordered but still have time to pay. Merchant has to wait for payment. | Not possible | | 1 | Orderline is paid. The merchant has received the payment and must validate or cancel the orderline. | 2 or 4 | | 2 | Orderline is accepted by the merchant, who must now prepare the product for shipment. | 3 or 5 | | 3 | The merchant has delivered the orderline to the shipping company. The package delivery is in progress. | 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 | example: 1 ReturnReason: type: integer enum: - 0 - 1 - 11 - 12 - 13 - 21 - 22 - 23 - 24 - 25 description: | Reason for the return. | Value | Description | |-------|-------------------------------------------| | 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 | example: 0 ProductCondition: type: integer enum: - 9 - 10 - 11 - 12 description: | Condition of the product. | Value | Description | |-------|---------------------| | 9 | Premium condition | | 1O | Excellent condition | | 11 | Good condition | | 12 | Fair condition | example: 10 OrderLine: type: object properties: id: type: integer description: The orderline unique ID example: 37195 date_creation: type: string format: date-time example: '2022-04-29T09:35:24.123456Z' description: Date of creation of the orderline state: $ref: '#/components/schemas/OrderLineState' price: description: Price (including taxes) of the listing associated & warranty without the shipping price type: string example: '229.0' shipping_price: description: Unitary shipping price (including taxes) type: string example: '0.00' shipping_delay: description: Shipping time type: integer example: 48 currency: type: string description: Currency used example: EUR return_reason: $ref: '#/components/schemas/ReturnReason' return_message: description: Message sent to the customer for a cancellation or a refund type: string example: '' listing: description: SKU of the listing type: string example: IPHONE416GONLIB0 listing_id: description: ID of the listing type: integer example: 142 orderline_fee: description: BackMarket commission fee amount type: string example: '22.9' product: description: Title of the product type: string example: Apple Iphone 4 16 Go - Noir - D\u00e9bloqu\u00e9 quantity: type: integer description: Quantity of products ordered example: 2 brand: description: The brand of the product type: string example: apple product_id: description: The product ID type: integer example: 141 backcare: description: True if this orderline is covered by the Backcare service type: boolean example: true backcare_price: type: integer description: The backcare price in cents example: 500 sales_taxes: description: Sales taxes (country/state dependent) type: string example: '25.8' imei: description: Unique product identifier type: string example: '011415009346880' serial_number: description: Unique product identifier type: string example: '' condition: $ref: '#/components/schemas/ProductCondition' Order: type: object properties: order_id: type: integer description: The unique id of the order. Used to update orderlines of a given order example: 5978 delivery_mode: type: string enum: - HOME_DELIVERY - COLLECTION_POINT example: HOME_DELIVERY description: | The delivery mode associated with the shipping address of the order. - `HOME_DELIVERY`: The shipping address is a home-delivery address. - `COLLECTION_POINT`: The shipping address is a collection-point address. shipping_address: $ref: '#/components/schemas/Address' billing_address: $ref: '#/components/schemas/Address' delivery_note: type: string maxLength: 300 format: url example: https://example.com/delivery_note/1519221434.69.pdf description: Document to add in package which contains useful information for the customer, related to his order. expected_dispatch_date: type: string format: date-time example: '2022-04-29T09:35:24' description: The shipment expected dispatch date (only applicable for orders not already SENT). tracking_number: type: string maxLength: 200 example: my_tracking_number description: Tracking number of the package tracking_url: type: string maxLength: 300 format: url example: http://www.colissimo.fr/my_tracking_url description: Tracking Url of the package shipper_display: type: string maxLength: 200 example: Colissimo description: Name of the shipper is_backship: type: boolean example: false description: True if the shipper of the order is backship date_creation: type: string format: date-time example: '2022-04-29T09:35:24.123456Z' description: Date of order date_modification: type: string format: date-time example: '2022-04-29T09:35:24Z' description: Date of last modification date_shipping: type: string format: date-time example: '2022-04-29T09:35:24.123456Z' description: Date of shipping date_payment: type: string format: date-time example: '2022-04-29T09:35:24.123Z' description: Date of payment state: $ref: '#/components/schemas/OrderState' orderlines: type: array items: $ref: '#/components/schemas/OrderLine' description: List of orderlines of the order. Indexed by SKU price: type: string description: The total price of the order (including taxes) without the shipping price example: '299.25' shipping_price: type: string description: Total shipping price (including taxes) example: '5.99' currency: type: string maxLength: 3 description: Currency used for the order example: EUR country_code: $ref: '#/components/schemas/CountryCode' paypal_reference: type: string maxLength: 17 description: Paypal reference ID example: null nullable: true installment_payment: type: boolean example: false description: Whether the customer chose a payment in multiple increments payment_method: description: 'The customer payment method (Eg: CARD, PAYPAL)' type: string example: PAYPAL sales_taxes: description: Sales taxes (country/state dependent) type: string example: '25.8' VatType: type: string enum: - REGULAR - MARGINAL example: MARGINAL UpdateOrder: type: object required: - id - new_state properties: order_id: type: integer description: Unique ID of the order. Specify the same order_id in the URL and in the body example: 5978 new_state: $ref: '#/components/schemas/OrderLineState' sku: description: Merchant unique identifier of the listing, enables to match an orderline type: string example: IPHONE416GONLIB0 imei: description: | Identifier of product. Optional and processed if new_state is 3. Applicable to any product category. Once registered, the value cannot be corrected. Only if the order has only one orderline with a quantity of 1. The value needs to be a valid IMEI. Once registered, the value cannot be corrected. type: string maxLength: 15 example: 01141500934XXXX serial_number: description: | Identifier of product. Optional and processed if new_state is 3. Applicable to any product category. Only if the order has only one orderline with a quantity of 1. Once registered, the value cannot be corrected. type: string maxLength: 50 example: '' tracking_number: type: string maxLength: 200 example: my_tracking_number description: | Tracking number of the package. Required if new_state is 3. tracking_url: type: string maxLength: 300 format: url example: http://www.colissimo.fr/my_tracking_url description: | Tracking Url of the package. Optional and processed if new_state is 3. vat_type: $ref: '#/components/schemas/VatType' date_shipping: type: string format: date-time example: '2022-04-29T09:35:24Z' description: | Date of shipping. Optional and processed if new_state is 3. shipper: type: string maxLength: 200 description: | Shipper designated. Shipper can be replaced if new_state is 3. return_reason: $ref: '#/components/schemas/ReturnReason' return_message: maxLength: 500 description: | Message sent to the customer for a cancellation or a refund. Optional and processed if new_state is 6. type: string example: We're sorry an error occurred with the order. You'll be reimbursed soon. PickupInfo: title: Pickup Info type: object required: - confirmationNumber - datePickupActual - datePickupRangeStart - datePickupRangeEnd - datePickupRequested - isCanceled - pickupId properties: confirmationNumber: type: string description: Confirmation number example: 1231NB datePickupActual: type: string description: Actual pickup date example: '2021-05-05T06:58:31+02:00' datePickupRangeStart: type: string description: Start date of pickup example: '2021-05-05T06:58:31+02:00' datePickupRangeEnd: type: string description: End date of pickup example: '2021-05-05T06:58:31+02:00' datePickupRequested: type: string description: Requested date for pickup example: '2021-05-05' isCanceled: type: boolean description: Pickup cancellation state example: false pickupId: type: integer description: Pickup ID example: 42 Delivery: title: Delivery type: object required: - order - shipmentId - carrierId - orderlines - referenceNumber - trackingNumber - trackingUrl - carrierName - hubScanned - invoicedCurrency - invoicedPrice - datePickup - dateCreation - dateDelivery - labelUrl - type - pickupInfo properties: order: type: integer description: Order ID example: 42 shipmentId: type: integer description: Shipment ID example: 42 carrierId: type: integer description: Carrier ID example: 42 orderlines: type: array description: Orderlines items: type: integer example: - 42 referenceNumber: type: string description: Reference number example: '1' trackingNumber: type: string description: Tracking number example: Jc2rnTAc4L trackingUrl: type: string description: Tracking url example: https://carrier.com/tracking/Jc2rnTAc4L carrierName: type: string description: Carrier name example: Chronopost hubScanned: type: boolean description: Whether the related shipment label have been scanned example: false invoicedCurrency: type: string description: Invoice currency example: EUR invoicedPrice: type: integer description: Invoiced amount example: 30 datePickup: type: string format: date-time description: Pickup date example: '2021-05-05T06:58:31+02:00' dateCreation: type: string format: date-time description: Creation date example: '2021-05-05T06:58:31+02:00' dateDelivery: type: string format: date-time description: Delivery date example: '2021-05-05T06:58:31+02:00' labelUrl: type: string description: Label url example: /static/shipment_labels/eu-9075b45c-d736-4e51-83ec-3f2ae2888e3e-1.pdf type: type: string description: Type of delivery example: DELIVERY pickupInfo: $ref: '#/components/schemas/PickupInfo' OrderIdValidationError: type: object properties: error: type: object properties: code: type: string example: E009 message: type: string example: Validation error required: - code - message data: type: object properties: fields: type: object example: orderId: - An integer is needed. required: - fields required: - error - data Return: title: Return type: object required: - orderId - orderlineId - shipmentId - dateCreation - referenceNumber - trackingNumber - trackingUrl - carrierId - carrierName - hubScanned - datePickup - dateDelivery - label - invoicedPrice - invoicedCurrency - type properties: orderId: type: integer description: Order ID example: 42 orderlineId: type: integer description: Orderline ID example: 42 shipmentId: type: integer description: Shipment ID example: 42 carrierId: type: integer description: Carrier ID example: 42 carrierName: type: string description: Carrier name example: Chronopost dateCreation: type: string format: date-time description: Creation date example: '2021-05-05T06:58:31+02:00' referenceNumber: type: string description: Reference number example: 1-123123-22334 trackingNumber: type: string description: Tracking number example: Jc2rnTAc4L trackingUrl: type: string description: Tracking url example: https://carrier.com/tracking/Jc2rnTAc4L hubScanned: type: boolean description: Whether the related shipment label have been scanned example: true datePickup: type: string format: date-time description: Pickup date example: '2021-05-05T06:58:31+02:00' dateDelivery: type: string format: date-time description: Delivery date example: '2021-05-05T06:58:31+02:00' label: type: string description: Label example: http://testserver/static/document.pdf invoicedPrice: type: integer description: Invoiced amount example: 30 invoicedCurrency: type: string description: Invoice currency example: EUR type: type: string description: Type of return example: RETURN careFolder: type: object properties: id: type: integer description: ID of the Care Folder example: 123 client: type: integer description: ID of the customer related to the Care Folder example: 456 merchant: type: integer description: ID of the Seller related to the Care Folder example: 789 orderline: type: integer description: ID of the orderline example: 321 date_creation: type: string description: Date of the Care Folder's creation (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' date_modification: type: string description: Date of the Care Folder's last modification (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' date_last_message: type: string description: Date of the Care Folder's last posted message (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' date_closed: type: string description: Date of the Care Folder's closing (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' state: type: integer description: | State of the Care Folder: * 0 - OPEN * 9 - CLOSED example: 9 lines: type: array description: List of Claim IDs related to the Care Folder items: type: integer example: - 731 - 1252 - 57189 country_code: type: string description: Country locale of the order, lowercase example: fr-fr backcare: type: boolean description: True if Seller is backcare example: true getCareFolderListResponse: properties: count: description: Number of Care Folders on the current page example: 3 type: integer next: description: URL to the next page example: https://backmarket.fr/ws/sav/?page=2 type: string previous: description: URL to the previous page example: 'null' type: string results: description: List of Care Folders items: $ref: '#/components/schemas/careFolder' type: array type: object client: type: object properties: id: type: integer description: ID of the customer (always returns a static value of 0) deprecated: true example: 0 username: type: string description: Username of the customer (always returns empty) deprecated: true example: '' first_name: type: string description: First name of the customer example: John last_name: type: string description: Last name of the customer example: Doe email: type: string description: Email of the customer example: john.doe@mymail.com tile: type: object properties: id: type: integer description: ID of the tile example: 123 name: type: string description: Name of the tile example: Technical issue: type: object properties: customerIssue: type: string description: The detailed name of the issue example: BATTERY_NOT_CHARGING tag: type: string description: The tag of the issue example: TECHNICAL returnLabel: type: object properties: date_creation: type: string description: Label's creation date (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' state: type: string description: Label's state enum: - USED - ALIVE - EXPIRED example: ALIVE label: type: string description: URL to the label document example: https://www.mycdn.com/path/to/label.document initiator: type: string description: Entity that initiated the return enum: - Merchant - BackMarket example: Merchant kind: type: string description: The return's direction (SENDER_TO_RECEIVER) enum: - UNSET - CUSTOMER_TO_MERCHANT - MERCHANT_TO_CUSTOMER example: MERCHANT_TO_CUSTOMER claim: type: object properties: id: type: integer description: ID of the Claim example: 123 tiles: type: array description: This field shouldn't be used anymore deprecated: true items: $ref: '#/components/schemas/tile' issues: type: array items: $ref: '#/components/schemas/issue' rate: type: integer description: This field shouldn't be used anymore deprecated: true example: 1 score: type: integer description: This field shouldn't be used anymore deprecated: true example: 1 state: type: integer description: | State of the Claim: * 0 - OPEN * 9 - CLOSED example: 1 withdraw: type: boolean description: This field shouldn't be used anymore deprecated: true example: false gras_savoye: type: boolean description: This field shouldn't be used anymore deprecated: true example: false warnings: type: array description: This field shouldn't be used anymore deprecated: true example: [] resolution_choice: type: string description: Resolution option chosen by the customer enum: - REMOTE_ASSISTANCE - REPAIR - REPLACE - REPAIR_REPLACE - REFUND example: REPLACE declared_warranty_state: type: string description: Warranty state declared by the customer enum: - IN_WARRANTY - WATER_OR_DROPPED - THIRD_PARTY_REPAIR example: IN_WARRANTY return_labels: type: array items: $ref: '#/components/schemas/returnLabel' seller: type: object properties: id: type: integer description: ID of the Seller example: 123 username: type: string description: Username of the Seller example: rose.bush@companymail.com first_name: type: string description: First name of the Seller example: Rose last_name: type: string description: Last name of the Seller example: Bush lightAttachment: type: object properties: id: type: integer description: ID of the attachment example: 123 attachment: type: string description: URL of the attachment example: https://www.mycdn.com/path/to/the/attachment.file date_creation: type: string description: Attachment's creation date format: date-time example: '1970-01-01T00:00:00+00:00' message: type: object properties: id: type: integer description: ID of the message example: 123 message: type: string description: Content of the message example: Lorem ipsum dolor sit amet date_creation: type: string description: Message's creation date (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' attachments: type: array items: $ref: '#/components/schemas/lightAttachment' initiator: type: string description: Entity that sent the message example: Merchant kind: type: string description: Kind of the message (SENDER_TO_RECEIVER) example: MERCHANT_TO_ALL is_informative: type: boolean description: _true_ if message is informative. Informative message do not trigger LRR example: false address: type: object properties: company: type: string description: Company related to the address example: My Company first_name: type: string description: First name related to the address example: John last_name: type: string description: Last name related to the address example: Smith street: type: string description: Street of the adress example: 1 rue du Paradis street2: type: string description: Complement on the street of the address example: ' ' postal_code: type: string description: Postal code of the city of the address example: '33000' country: type: string description: Country of the address example: FR city: type: string description: City of the address example: Bordeaux phone: type: string description: Phone number related to the address example: '0123456789' email: type: string description: Email related to the address example: john.smith@mycompany.com customer_id_number: type: string description: ID of the customer related to the address example: '123' order: type: object properties: order_id: type: integer description: ID of the order example: 123 shipping_address: $ref: '#/components/schemas/address' billing_address: $ref: '#/components/schemas/address' tracking_number: type: string description: Tracking number example: ABC123 tracking_url: type: string description: Tracking URL example: https://www.mycarrier.com/delivery/track shipper: type: integer description: ID of the shipper example: 456 shipper_display: type: string description: Name of the Shipper example: Shipper date_creation: type: string description: Date of the order's creation (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' date_modification: type: string description: Date of the order's last modification (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' date_shipping: type: string description: Date of the order's shipping (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' date_payment: type: string description: Date of the order's payment (ISO 8601 format) format: date-time example: '1970-01-01T00:00:00+00:00' state: type: integer description: | Sate of the order: * 0 - New * 1 - Validated * 3 - Merchant needs to send * 8 - Failed * 9 - Sent enum: - 0 - 1 - 3 - 8 - 9 example: 1 price: type: string description: Price of the order example: '89.99' shipping_price: type: string description: Price of the order's shipping example: '5.99' currency: type: string description: Currency of the payment example: EUR country_code: type: string description: Country locale code of the plateform's location, lowercase example: fr-fr category_3: type: object properties: category_name: type: string description: Name of the product's category example: Smartphones parent: deprecated: true description: This field shouldn't be used anymore $ref: '#/components/schemas/category_3' product: type: object properties: product_id: type: integer description: ID of the product example: 123 category_3: $ref: '#/components/schemas/category_3' snapshot: type: object properties: id: type: integer description: ID of the snapshot (always returns a static value of 0) deprecated: true example: 0 product: $ref: '#/components/schemas/product' listing: type: integer description: id of the listing example: 456 sku: type: string description: SKU of the product example: '0123456789012' snowden: type: boolean description: Only for iPhones. _true_ if TouchID is broken, _false_ otherwise. This field shouldn't be used anymore deprecated: true example: false image: type: string description: URL of the image example: https://www.mycdn.com/path/to/the/image.file orderline: type: object properties: id: type: integer description: ID of the orderline example: 123 order: $ref: '#/components/schemas/order' snapshot: $ref: '#/components/schemas/snapshot' quantity: type: integer description: Number of products example: 2 price: type: string description: Price of the product example: '89.99' state: type: integer description: | State of the orderline: * NEW - 0 * PAID - 1 * VALIDATED - 2 * SHIPPED - 3 * CANCELLED - 4 * REFUNDED_PRE_DELIVERY - 5 * REFUNDED_POST_DELIVERY - 6 * NOT_PAID - 7 example: 2 trust_pack_plus: type: boolean description: Customer bought Trust Pack Plus. This field shouldn't be used anymore deprecated: true example: false getCareFolderDetailsResponse: properties: backcare: description: True if Seller subscribed to BackCare example: true type: boolean client: $ref: '#/components/schemas/client' country_code: description: Country locale code, lowercase example: fr-fr type: string date_closed: description: Date of the Care Folder's closing (ISO 8601 format) example: '1970-01-01T00:00:00+00:00' format: date-time type: string date_creation: description: Date of the Care Folder's creation (ISO 8601 format) example: '1970-01-01T00:00:00+00:00' format: date-time type: string date_last_message: description: Date of the Care Folder's last posted message (ISO 8601 format) example: '1970-01-01T00:00:00+00:00' format: date-time type: string date_modification: description: Date of the Care Folder's last modification (ISO 8601 format) example: '1970-01-01T00:00:00+00:00' format: date-time type: string id: description: ID of the Care Folder example: 123 type: integer lines: items: $ref: '#/components/schemas/claim' type: array merchant: $ref: '#/components/schemas/seller' messages: items: $ref: '#/components/schemas/message' type: array orderline: $ref: '#/components/schemas/orderline' state: description: | State of the Care Folder: * 0 - OPEN * 9 - CLOSED enum: - 0 - 9 example: 9 type: integer type: object postProblemRequest: properties: problem_type: description: | The type of problem to declare on the Care Folder. If not provided, defaults to `OTHER`. **Attachment requirements:** - `DAMAGED_PACKAGE`, `ITEM_NOT_RECEIVED`, and `OOW_ITEM` require at least one attachment. - All other problem types have optional attachments. type: string enum: - ACCOUNT_LOCKED - CODE_LOCKED - DAMAGED_PACKAGE - ITEM_NOT_RECEIVED - MISSING_PART - OOW_ITEM - PROBLEM_NOT_IDENTIFIED - WRONG_ITEM - OTHER default: OTHER example: OTHER message: description: Optional message to include with the problem declaration. type: string example: The package arrived damaged attachment: description: | The local file(s) to be uploaded with the problem declaration. **Mandatory** for problem types `DAMAGED_PACKAGE`, `ITEM_NOT_RECEIVED`, and `OOW_ITEM`. **Limits:** - Maximum file size: 3 MB per file - Maximum number of files: 10 files example: [] items: format: binary type: string type: array type: object postRefundCreateRequest: properties: amount: description: Amount of the refund. Only if refund type is 6 example: 89.99 type: number orderline_pk: description: ID of the Orderline to be refund example: 123 type: integer refund_type: description: | Type of the refund: * 4 - Full refund for an orderline with state 1 * 5 - Full refund for an orderline with state 2 * 6 - Partial or full refund for an orderline with state 3 Details of the orderline states: | State | Description | |-------|------------------------------------------------| | 0 | New Orderline | | 1 | Orderline paid by the customer | | 2 | Orderline accepted by the seller | | 3 | Orderline delivered to the shipping provider | | 4 | Orderline cancelled | | 5 | Orderline refunded before shipping | | 6 | Orderline refunded after shipping | | 7 | Orderline not paid | | 8 | Orderline pending customer payment | enum: - 4 - 5 - 6 example: 4 type: integer type: object postMessageRequest: properties: attachment: description: | The local file to be uploaded with the message. **Limits:** - Maximum file size: 3 MB per file - Maximum number of files: 10 files example: [] items: format: binary type: string type: array message: description: Message content to be sent on the conversation example: Hi there type: string required: - message type: object attachment: type: object properties: msg: type: integer description: ID of the message this attachment is attached to example: 123 group: type: integer description: ID of the Care Folder this attachement is attached to example: 456 sender: type: integer description: ID of the user that uploaded the attachment example: 789 attachment: type: string description: Path to the attachment file example: /path/to/my/attachment.file postMessageResponse: properties: attachment: $ref: '#/components/schemas/attachment' attachments: items: $ref: '#/components/schemas/attachment' type: array date_creation: description: The message's creation date (ISO 8601 format) example: '1970-01-01T00:00:00+00:00' format: date-time type: string group: description: ID of the Care Folder linked to the message example: 456 type: integer id: description: ID of the message example: 123 type: integer message: description: Message content example: Hi, how can I help? type: string sender: description: ID of the user who created the message example: 789 type: integer type: object postItemTransferCreateRequest: required: - shipperName - trackingNumber properties: shipperName: description: Name of the carrier used for the shipment example: DHL type: string trackingNumber: description: Tracking id issued by the carrier example: 123AZ0672 type: string action: description: Action taken by the seller example: REPAIR enum: - REPAIR - REPLACE - NOTHING type: string type: object Backbox: title: Backbox type: object required: - product - sku - price - quantity - buybox - price_for_buybox - current - condition - same_merchant_winner properties: product: type: integer description: Product ID example: 42 sku: type: string description: | SKU used to match to an existing listing (also a listing's unique Id) example: SuperSKU price: type: number description: Listing price example: 70 quantity: type: integer description: Stock available example: 10 buybox: type: boolean description: Does this listing have Backbox example: false price_for_buybox: type: number description: If your listing does not have Backbox, the price you will have to set to have it (aka red price) example: 60 currency: type: string description: Currency of the listing, it will depend on the market ("GBP" for UK for instance) example: EUR condition: $ref: '#/components/schemas/ProductCondition' same_merchant_winner: type: boolean description: Does one of your listing have Backbox example: false Competitor: properties: is_winning: description: Whether or not this competitor is winning the backbox. title: Is Winning type: boolean listing_id: description: The listing public id of this competitor. format: uuid title: Listing Id type: string min_price: anyOf: - $ref: '#/components/schemas/MonetaryAmount' description: The mimimum price set by the competitor. nullable: true price: allOf: - $ref: '#/components/schemas/MonetaryAmount' description: The target price set by the competitor. price_to_win: allOf: - $ref: '#/components/schemas/MonetaryAmount' description: The price that the competitor must set to win the backbox. product_id: description: The product public id of this competitor. format: uuid title: Product Id type: string winner_price: anyOf: - $ref: '#/components/schemas/MonetaryAmount' description: The price of the backbox i.e. the selling price of the winner. nullable: true market: anyOf: - $ref: '#/components/schemas/MarketCode' description: The market of the backbox. required: - listing_id - product_id - price - min_price - price_to_win - winner_price - is_winning - market title: Competitor type: object parameters: Page: description: The page number for pagination example: 2 in: query name: page required: false schema: default: 1 type: integer PageSize: description: The page size for pagination example: 20 in: query name: page-size required: false schema: default: 10 type: integer maximum: 50 status: schema: $ref: '#/components/schemas/buybackOrderState' in: query name: status description: Buyback Order status example: PAID productId: schema: type: integer in: query name: productId description: BuyBack product ID example: 123 creationDate: schema: type: string format: datetime in: query name: creationDate description: BuyBack order minimum creation date example: '2020-12-02' modificationDate: schema: type: string format: datetime in: query name: modificationDate description: BuyBack order minimum modification date example: '2020-12-02' shippingDate: schema: type: string format: datetime in: query name: shippingDate description: BuyBack order minimum shipping date example: '2020-12-02' receivedDate: schema: type: string format: datetime in: query name: receivedDate description: BuyBack order minimum received date example: '2020-12-02' suspendedDate: schema: type: string format: datetime in: query name: suspendedDate description: BuyBack order minimum suspended date example: '2020-12-02' paymentDate: schema: type: string format: datetime in: query name: paymentDate description: BuyBack order minimum payment date example: '2020-12-02' page: schema: type: integer in: query name: page example: 1 description: Page number buybackOrderId: schema: type: string example: US-24527-ABCDE name: buybackOrderId in: path description: BuyBack order id required: true buybackListingId: schema: type: string format: uuid example: 3b99e96d-9db7-480f-a32f-2e05edbff30c name: buybackListingId in: path description: BuyBack listing id required: true responses: RateLimited: description: Too many requests. Client has been rate limited. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV1'