openapi: 3.0.3
info:
  version: 0.1.1
  title: Back Market - API Guidelines
  description: |
    ## Table of contents

    1. [Introduction](#introduction)
    1. [Getting started](#getting-started)
    1. [Technical requirements](#technical-requirements)
    1. [F.A.Q. and Contact](#faq-and-contact)
    1. [Cookbooks](#cookbooks)

    ## Introduction

    Welcome to Back Market, the leading online marketplace dedicated to refurbished products.

    Our back-office and our web-services have been created in order to allow Seller to manage their products
    easily on our marketplace. This documentation is meant to help you integrate our marketplace and learn how to manage
    your `Products`, `Offers` and `Orders` on Back Market.

    ### Overview of what this documentation is talking about

    * Our Taxonomy : This part will describe the organization and classification of our marketplace
    * Products & Offers : You will learn how to create `Products` as well as create, update and list `Offers` on Back Market
    * Your Orders : The `Orders` workflow, listing and update will be explained

    Different solutions are offered in order to use our marketplace. It's possible to work with a combination of
    these solutions or to switch from one to another at a later stage.

    1 - Back Market API:

    This is the best solution for big and/or small sellers with their own technical team. Working with our API will
    enable you to synchronize your information with our database in real time. It is especially suitable for sellers
    with long-tail catalogs as well as a large amount of sales.

    2 - Back-office:

    Our <a target="_blank" href="https://www.backmarket.fr/bo_merchant/"> back-office</a> offers a graphic user
    interface which allows you to manage everything simply and efficiently.

    Our back-office also gives you the possibility to import and export CSV files
    with `Products`, `Offers` and `Orders` information.
    This allows you to work with more `Offers` comfortably.

    3 - DEPRECATED FTP :

    FTP in Back Market is deprecated. If you used to use FTP in order to connect to Back Market
    Please contact <partner-support@backmarket.com> to help you to setup an API connexion.

    ### Other information

    On this website, we've collected all the information you might need to get on board as smoothly as possible.
    Also, be sure to check our [F.A.Q.](#f-a-q-and-contact) to get answers to your questions.
    [Contact us](#f-a-q-and-contact) if you still have further questions.

    ### Feedback

    At Back Market, we always want to improve our solutions.
    Please [Give Us Feedback](mailto:<partner-support@backmarket.com>?subject=Feedback Back Market Doc) and let us
     know about possible improvement we could make, be it on this documentation, our web services,
     our back-office or whatever you might think of.
    Please note that this mail is temporary as we will deploy a new Seller support center
    that will assist you.

    ## Getting Started

    If you did not yet read the page on [taxonomy](operations/get-bm-catalog-category#taxonomy), please do it before proceeding.

    ### Account

    After validation by our team, each Seller gains access to an account. This account gives you access to the Back
    Market Back Office and our API.

    Use one of the following links to access your Back Office account or create one if you haven't done so already.
    You will need to provide information about your company and we will get back to you as soon as possible:

    * <a target="_blank" href="https://www.backmarket.co.jp/bo-seller">AP platform</a>
    * <a target="_blank" href="https://www.backmarket.fr/bo-seller">EU platform</a>
    * <a target="_blank" href="https://www.backmarket.com/bo-seller">US platform</a>

    For creating or accessing an account on the preprod, you can use the following links:

    * <a target="_blank" href="https://preprod.backmarket.co.jp/bo-seller">AP preprod platform</a>
    * <a target="_blank" href="https://preprod.backmarket.fr/bo-seller">EU preprod platform</a>
    * <a target="_blank" href="https://preprod.backmarket.com/bo-seller">US preprod platform</a>

    ### Country code

    Back Market is international so you can sell products abroad. The
    country code matches both the targeted language and country for the
    action you'd like to perform (ex: update the price for a listing in
    Italy).
    Information about every countries are contained in the same instance
    of an object `Product` or a `Listing`.

    Indeed, you don't need to create one `Listing` for each country. This
    `Listing` will contain some fields which are the same for all the countries (_listing_id, quantity, ..._) and other
     country specific fields (_comment, price and warranty_delay_).
    Therefore, if you wish to edit the _**stock**_ (field :
    'quantity'), the change will apply to all the countries, but for the
    _**comment**_ you will have to change it for each country.

    In the same way, some fields of the `Product` are common for all
    countries (_weight, EAN, ..._), and others depend on the country
    (_description, title and price_new_).

    **COUNTRY_CODES** - Accepted values are :

    * AP platform:

      * ja-jp     : Japan
      * en-au     : Australia

    * EU platform:

      * fr-fr     : France
      * fr-be     : Belgium
      * es-es     : Spain
      * de-de     : Germany
      * de-at     : Austria
      * it-it     : Italy
      * en-gb     : United Kingdom
      * nl-nl     : Netherlands
      * pt-pt     : Portugal
      * en-ie     : Ireland
      * el-gr     : Greece
      * sk-sk     : Slovakia
      * sv-se     : Sweden

    * US platform:

      * en-us     : United States

    ### CSV file format

    All files imported through our Back Office or imported using Back Market's API must be in CSV format.

    Required field separator is ';'.

    Required line separator is the line feed '\n'.

    Fields must be surrounded by double quotes.
    ## Technical Requirements

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

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

    Each Integrator or Seller should use the following HTTP Header when calling Back Market API endpoints.

    The User-Agent is mandatory. Any request without it might be refused by our System.

    It should include your company name, application name, version, and a contact email address in this format:

    ```http
    BM-{CompanyName}-{IntegrationName};company@companydomain.com.
    ```

    For example:

    ```http
    BM-Ebay-Invoices;contact@ebay.com
    BM-bouygues-automations;contact@bouygues.fr
    ```

    ### Web application firewall (WAF) and Bot management

    The WAF or bot management may block your requests for security reason. You'll typically receive an HTTP 403 Forbidden
    response, possibly with a response body to tell you to challenge your client with Cloudflare.

    In case you judge that your request should not be blocked by Cloudflare, from the response headers, you can get the value of cf-ray and send it to your seller contact for investigation.

    Example HTTP 403 response from WAF:

    ```http
    HTTP/2 403
    date: Wed, 16 Apr 2025 11:26:41 GMT
    content-type: text/html; charset=UTF-8
    referrer-policy: same-origin
    cache-control: max-age=15
    expires: Wed, 16 Apr 2025 11:26:56 GMT
    ...
    x-content-type-options: nosniff
    x-frame-options: SAMEORIGIN
    server: cloudflare
    cf-ray: 931354450813d142-CDG
    alt-svc: h3=":443"; ma=86400
    ```

    Example HTTP 403 response for Bot Management protected endpoints:

    ```json
    {
      "errors": [
        {
          "code": "bot-need-challenge",
          "message": "Forbidden",
          "challengePath": "/testchallengepage"
        }
      ]
    }
    ```

    ### Traffic limitation

    Our standard rate limits are will allow your automations to run fast enough to finish your processes.
    However, in case of too many requests beyond what we except on sellers endpoints, you will be presented with an HTTP 429 response from Cloudflare.

    Usually you will find the range above 200 requests in 10 seconds being blocked for 10 seconds and for more sensible
    endpoints like catalog for example above 20 requests in 10 seconds being blocked for 10 seconds.

    ### Data limitation

    To make sure we can handle and process all the incoming data correctly, we have set-up the following limitation:
    **We might not accept more than 2k lines of SKUs to process per hour** on the
     following endpoints ([Update Several listings](#update-several-listings) or
      on [Update specific listing](#update-specific-listing)) and [Update Listings](#update-listings)) files.
    FTP in Back Market is deprecated. If you used to use FTP in order to connect to Back Market
    Please contact <partner-support@backmarket.com> to help you to setup an API connexion.

    **If this limit is reached, Back Market may refuse the task**, in this case you will receive HTTP responses
    with the "429 Too Many Requests" status.

    If you have lots of active SKUs, please take into account the [Best Practice](#best-practices)
    part of the documentation.

    ### Questions ?

    If you have any questions, please send an email to <partner-support@backmarket.com>
    Please note that this mail is temporary as we will deploy a new seller support center
    that will assist you.
    ## F.A.Q. and Contact

    Please [click here](https://merchant-support.backmarket.com/hc/en-us) to access your Seller Support Center
     where you can find our F.A.Q. or contact us.

    If you have never signed in to the Seller Support Center, you can
     read this [tutorial](statics/How-to-connect-to-SSC.pdf) which helps you setup you connection for the first time.

    If you have any more questions and are already selling on Back Market, we invite you to contact your account manager.
    ## Cookbooks

    A list of notebooks showcasing different API use cases:

    [Winning the BackBox based on small price efforts](https://colab.research.google.com/drive/12jHZ3AQG8mQjjAvulG9zVvfC_psEOKjh?usp=sharing)
  contact:
    name: Seller Support Center
    url: https://merchant-support.backmarket.com/hc/en-us
    x-slack: NA
    email: NA@NA.com
servers:
  - url: https://preprod.backmarket.co.jp
    description: Preprod - AP
  - url: https://www.backmarket.co.jp
    description: Prod - AP
  - url: https://preprod.backmarket.fr
    description: Preprod - EU
  - url: https://www.backmarket.fr
    description: Prod - EU
  - url: https://preprod.backmarket.com
    description: Preprod - NA
  - url: https://www.backmarket.com
    description: Prod - NA
paths:
  /ws/category/tree:
    get:
      summary: Get category tree
      description: |

        ## Taxonomy

        ### Categorization & products

        `Categories` tree diagram :
        <img class="myImg" src="https://s3-eu-west-1.amazonaws.com/backmarket-doc-developer/images_to_download/
        category_tree_schema.png" width=100% height=auto alt="">

        Diagram of matching `Product` with a leaf `Category` :

        <img class="myImg"
         src="https://s3-eu-west-1.amazonaws.com/backmarket-doc-developer/images_to_download/category_product.png"
         width=100% height=auto alt="">
        <br>

        The matching of a `Product` to a `Category` is made using its `marketplace_category_id`. The `category_id` of
         the model `Product` matches the `marketplace_category_id` of the model `Category` (and not the `category_id`).

         On Back Market, many types of `Products` are being sold: smartphones, phones, computers, coffee machines, etc.

          Each `Product` created on our marketplace is classified within the 3 levels of `Categories`.
          A `Product` can only be attached to one `Category leaf` (the last level of the Category tree).

          `Category 2`  and  `Category 3` can only have one parent `Category`.
          If it is a `leaf Category`, it cannot have any `child Category`. Otherwise,
           `Category` can have several `children Categories`.

          For each `Product` on Back Market  several merchants can publish an offer.
          If a `Product` does not exist on our platform, a merchant can create the `Product`.
          The newly created `Product` will then go through a validation process by our
           team (usually within 12 hours of a working day) before being put online.

          In addition to some mandatory fields for each `Products` (_cf._ Table 3), the `leaf Category` defines `Attributes`
           (which can be **mandatory** or **optional**) to provide
            during the creation of a `Product`.
          Therefore, when creating a `Product`, some fields will depend on the `leaf Category` of
           the `Product` (category `Attributes`) you create.
           Others will always be the same for every `Products` you create (_cf._ Table 3).

          **In summary, if you want to create a `Product`, you will have to provide**:

        * The `EAN` (European Article Number) of the `Product`.
        * **Mandatory** product fields (_cf._ Table 3).
        * The `marketplace_category_id` (to match the `Product` with its `leaf Category`).
        * **Mandatory** category `Attributes` (which depend on the `leaf Category`).

         Only the merchant who created the `Product` can update it.
         **The update can only be done before our team validates the product.**.

        #### Table 1 - `Category` model

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

        #### Table 2 - `Attribute` model

        <table class="table">
          <thead>
            <tr>
                <th>Field name</th>
                <th>Type/Size</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
              <tr>
                  <td>field</td>
                  <td>String/200</td>
                  <td>Field to provide during creation of a `Product`.</td>
              </tr>
              <tr>
                  <td>field_name</td>
                  <td>String/200</td>
                  <td>Name of the `Attribute`.</td>
              </tr>
              <tr>
                  <td>type</td>
                  <td>Int</td>
                  <td>
                      <div>0: "Decimal"</div>
                      <div>1: "Integer"</div>
                      <div>2: "String"</div>
                      <div>3: "Multiple_Choice"</div>
                  </td>
              </tr>
              <tr>
                  <td>allowed_values</td>
                  <td>String/1000</td>
                  <td>If `type` is "Multiple_Choice": accepted values separated by ",".</td>
              </tr>
              <tr>
                  <td>required</td>
                  <td>Bool</td>
                  <td>True if the attribute is mandatory to create the Product.</td>
              </tr>
          </tbody>
        </table>

        #### Table 3 - `Product` model

         Fields to provide are the same for every `Product` and don't depend on its `Category`.
         A **unique product ID** is provided at the creation of a `Product`.

        <table class="table">
          <thead>
            <tr>
                <th>Field name</th>
                <th>Type/Size</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
              <tr>
                  <td>product_id</td>
                  <td>String</td>
                  <td>Unique product Id. Provided by Back Market at the creation of a `Product` for purpose of matching to `Listings`.</td>
              </tr>
        </tbody>
        </table>

        **Required fields:**
        <table class="table">
          <thead>
            <tr>
                <th>Field name</th>
                <th>Type/Size</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
           <tr>
                  <td>ean</td>
                  <td>String/13</td>
                  <td>`EAN` used to match an already existing `Product`. A new `Product` is created
                      if there is no match. Also used to match a Listing at its creation if the Back Markert ID is not provided.</td>
              </tr>
              <tr>
                  <td>category_id</td>
                  <td>Int</td>
                  <td>Matches the marketplace_category_id. Unique ID of a selected `Category`,
                   to be provided during creation of a `Product`. Allows matching a `Product` to its `leaf Category`.</td>
              </tr>
              <tr>
                  <td>title</td>
                  <td>String/200</td>
                  <td>Product title.</td>
              </tr>
              <tr>
                  <td>description</td>
                  <td>Text</td>
                  <td>Product description.</td>
              </tr>
              <tr>
                  <td>brand</td>
                  <td>String/100</td>
                  <td>Product brand.</td>
              </tr>
              <tr>
                  <td>price_new</td>
                  <td>Decimal</td>
                  <td>Market price of the product sold new.</td>
              </tr>
              <tr>
                  <td>weight</td>
                  <td>Int > 1</td>
                  <td>Weight in grams (g).</td>
              </tr>
              <tr>
                  <td>image1</td>
                  <td>String/1000</td>
                  <td>First image.</td>
              </tr>
          </tbody>
        </table>

        **Optional fields:**
        <table class="table">
          <thead>
            <tr>
                <th>Field name</th>
                <th>Type/Size</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
              <tr>
                  <td>image2</td>
                  <td>String/1000</td>
                  <td>Second image.</td>
              </tr>
              <tr>
                  <td>image3</td>
                  <td>String/1000</td>
                  <td>Third image.</td>
              </tr>
              <tr>
                  <td>image4</td>
                  <td>String/1000</td>
                  <td>Fourth image.</td>
              </tr>
              <tr>
                  <td>image5</td>
                  <td>String/1000</td>
                  <td>Fifth image.</td>
              </tr>
              <tr>
                  <td>image6</td>
                  <td>String/1000</td>
                  <td>Sixth image.</td>
              </tr>
              <tr>
                  <td>width</td>
                  <td>String/200</td>
                  <td>Width.</td>
              </tr>
              <tr>
                  <td>height</td>
                  <td>String/200</td>
                  <td>Height.</td>
              </tr>
              <tr>
                  <td>depth</td>
                  <td>String/200</td>
                  <td>Depth.</td>
              </tr>
          </tbody>
        </table>

        <aside class="notice">
        To create a `Product` you need to at least provide mandatory product fields and mandatory category `Attributes` of the `leaf
        Category`.
        </aside>

        #### Fields depending on the country_code

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

        Here is the list of fields for the Product model that vary by country (and need to be specified for each country):

        * 'title'
        * 'description'
        * 'price_new'

        ## Get category tree

        If you want to sell a new `Product`, which has not already been added on our marketplace by another merchant, you will need to create it.

        In this case, you need to select one `leaf Category` and check the corresponding `Attributes`.
        This will let you know all mandatory or optional `Attributes` you need to provide during the creation of the `Product`.

        This section allows to retrieve Back Market's `Category tree`, including all its branches.

        ### Endpoint

        <aside class="success">
         HTTP GET request: <a target="_blank" href="https://www.backmarket.fr/ws/category/tree/"> https://www.backmarket.fr/ws/category/tree/</a>
        </aside>

        ### HTTP request

        No request Body.

        ```javascript
        # Example of JSON response - Status code 200

        [
            {
                "category_id":1,
                "category_name":"T\u00e9l\u00e9phones",
                "marketplace_category_id":-1,
                "is_leaf":false,
                "attributes":[],
                "childrens":[
                    {
                        "category_id":2,
                        "category_name":"Old School",
                        "marketplace_category_id":-10001,
                        "is_leaf":false,
                        "attributes":[],
                        "childrens":[
                            {
                                "category_id":3,
                                "category_name":"Old School",
                                "marketplace_category_id":1,
                                "is_leaf":true,
                                "attributes":[
                                    {
                                        "field":"color",
                                        "field_name":"Couleur",
                                        "type": 2,
                                        "allowed_values":"",
                                        "required":true
                                    },
                                    {
                                        "field":"screen_size",
                                        "field_name":"Taille \u00e9cran (pouces)",
                                        "type": 2,
                                        "allowed_values":"",
                                        "required":true
                                    },
                                    {...}
                                ],
                                "childrens":[]
                            }
                        ]
                    },
                    {...}
                ]
            },
            {...}
        ]

        ```

        ### Response parameters

        _**`Category` fields :**_

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

        _**`Attribute` fields :**_

        <table class="table">
          <thead>
            <tr>
                <th>Field name</th>
                <th>Type/Size</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
              <tr>
                  <td>field</td>
                  <td>String/200</td>
                  <td>Field to provide at `Products` creation.</td>
              </tr>
              <tr>
                  <td>field_name</td>
                  <td>String/200</td>
                  <td>Name of the `Attribute`.</td>
              </tr>
              <tr>
                  <td>type</td>
                  <td>Int</td>
                  <td>
                      <div>0: "Decimal"</div>
                      <div>1: "Integer"</div>
                      <div>2: "String"</div>
                      <div>3: "Multiple_Choice"</div>
                  </td>
              </tr>
              <tr>
                  <td>allowed_values</td>
                  <td>String/1000</td>
                  <td>If `type` is "Multiple_Choice": accepted values separated by ",".</td>
              </tr>
              <tr>
                  <td>required</td>
                  <td>Bool</td>
                  <td>True if the `Attribute` is mandatory to create the `Product`.</td>
              </tr>
          </tbody>
        </table>

        ### Response status codes

        <table class="table">
          <thead>
            <tr>
                <th>Status code</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
              <tr class="success">
                  <td>200</td>
                  <td>
                      OK.
                  </td>
              </tr>
              <tr class="danger">
                  <td>400</td>
                  <td>
                      Bad request.
                  </td>
              </tr>
              <tr class="danger">
                  <td>403</td>
                  <td>
                      Forbidden.
                  </td>
              </tr>
              <tr class="danger">
                  <td>404</td>
                  <td>
                      Webservices unavailable.
                  </td>
              </tr>
          </tbody>
        </table>

        ## Create/Update category

        `Category` cannot be created nor updated by merchants.

        You might want to create a `Category` if you wish to sell a new kind of `Product`, which cannot be referenced in already existing Categories.

        You might also want to update a `Category` in the event that you wish to create a `Product` that already exists in the relevant `Category` but for which you can't provide all the mandatory `Attributes`. In this case, you would want the **mandatory** field to become **optional**.

        If you wish to create or update a `Category`, please <a target="_blank" href="https://merchant-support.backmarket.com/hc/en-us">let us know</a>.
      x-tier: 3
      tags:
        - Categories
      operationId: get-bm-catalog-category
      security:
        - ApiKeyAuth: []
        - BasicAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryTree'
        '401':
          description: Unauthenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV2'
        '403':
          description: Forbidden. Authenticated user is not a merchant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV2'
    parameters:
      - name: Accept-Language
        in: header
        description: |
          Select what market will be used to apply filters and export data.
          Passed as the language code related to this market.
        required: false
        example: fr-fr
        schema:
          $ref: '#/components/schemas/Locale'
  /ws/category/tree/{categoryId}:
    parameters:
      - in: path
        name: categoryId
        required: true
        example: 1
        schema:
          type: integer
      - name: Accept-Language
        in: header
        description: |
          Select what market will be used to apply filters and export data.
          Passed as the language code related to this market.
        required: false
        example: fr-fr
        schema:
          $ref: '#/components/schemas/Locale'
    get:
      summary: Get category branch
      description: |

        Retrieve a specific `Category` branch. This will only give you access to what's below on the branch. This means that you won't be able to access the parent `Categories`, but only children `Categories` and `Attributes`.

        You can retrieve `Attributes` from a specific `leaf Category` with the following endpoint, by providing its category ID.
      x-tier: 3
      tags:
        - Categories
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryTree'
        '401':
          description: Unauthenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV1'
        '403':
          description: Forbidden. Authenticated user is not a merchant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV1'
        '404':
          description: Category not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseV1'
  /ws/listings:
    get:
      x-tier: 1
      summary: Get listings
      description: |

        Retrieve all your `Listings`.
      security:
        - ApiKeyAuth: []
        - BasicAuth: []
      parameters:
        - example: 2
          in: query
          name: publication_state
          required: false
          schema:
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
            type: integer
        - example: 0
          in: query
          name: min_quantity
          required: false
          schema:
            type: integer
        - example: 100
          in: query
          name: max_quantity
          required: false
          schema:
            type: integer
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - description: |
            Select what market will be used to apply filters and export data.
            Passed as the language code related to this market.
          example: fr-fr
          in: header
          name: Accept-Language
          required: 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:

        <aside class="success">
         HTTP GET request: https://www.backmarket.fr/ws/listings/LISTING_ID
        </aside>

        Or working with a filter on:

        <aside class="success">
         HTTP GET request: https://www.backmarket.fr/ws/listings/detail/
        </aside>

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

        <aside class="success">
         HTTP GET request: https://www.backmarket.fr/ws/listings/LISTING_ID
        </aside>

        Or working with a filter on:

        <aside class="success">
         HTTP GET request: https://www.backmarket.fr/ws/listings/detail/
        </aside>

        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 :
        <img src="https://s3-eu-west-1.amazonaws.com/backmarket-doc-developer/images_to_download/group_order.png"
        width="100%" height="auto" alt="Product / Listing structure">

        `Orders` workflow diagram :
        <img src="https://s3-eu-west-1.amazonaws.com/backmarket-doc-developer/images_to_download/orders_workflow.png"
        width="100%" height="auto" alt="Orders workflow diagram">

        `Orderlines` workflow diagram :
        <img src="https://s3-eu-west-1.amazonaws.com/backmarket-doc-developer/images_to_download/orderlines_workflow.png"
        width="100%" height="auto" alt="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
        <span class="success">final state</span> (_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 <span class="warning">state 3</span> (All `Orderlines` of this
        `Order` will be set to this state automatically).

        ### Table 5 - Order State

        Color-codes for the `State`:
        <span class="info">New Order</span>, <span class="warning">Temporary States</span>,
        <span class="success"> Final States</span>.

        <table class="table">
          <thead>
            <tr>
                <th>State</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
              <tr class="info">
                  <td>0</td>
                  <td>
                      New `Order`. Payment validation is pending. We are doing verifications to check the customer identity.
                      The `Orders` in this `State` must not be shipped.
                  </td>
              </tr>
              <tr class="warning">
                  <td>10</td>
                  <td>
                      `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.
                  </td>
              </tr>
              <tr class="warning">
                  <td>1</td>
                  <td>
                      Payment is checked & validated. The merchant has to process (accept or cancel) the
                      `Orderlines`.
                  </td>
              </tr>
              <tr class="warning">
                  <td>3</td>
                  <td>
                      `Order` shipping is pending. The payment and the `Order` (all `Orderlines`) have been validated.
                      The merchant has to ship the package to the customer.
                  </td>
              </tr>
              <tr class="success">
                  <td>8</td>
                  <td>
                      Order is not paid. Payment process has failed, the merchant must ignore this `Order`.
                  </td>
              </tr>
              <tr class="success">
                  <td>9</td>
                  <td>
                      Order processed. The merchant has shipped the package.
                  </td>
              </tr>
          </tbody>
        </table>

        ### Table 6 - States for Orderlines

        Color-codes for the `Orderlines`:
        <span class="info">New Order</span>, <span class="warning">Temporary States</span>, <span class="success">
        Final States</span>.

        <table class="table">
          <thead>
            <tr>
                <th>State</th>
                <th>Description</th>
                <th>Possible next states</th>
            </tr>
          </thead>
          <tbody>
              <tr class="info">
                  <td>0</td>
                  <td>
                      New `Orderline`. The merchant has to wait for payment confirmation.
                  </td>
                  <td>Not possible</td>
              </tr>
              <tr class="warning">
                  <td>9</td>
                  <td>
                      `Orderline` is on hold. It needs to be validated by one of our partners before being accepted by the
                      merchant.
                  </td>
                  <td>Not possible</td>
              </tr>
              <tr class="warning">
                  <td>8</td>
                  <td>
                      `Orderline` is pending. The customer have ordered but still have time to pay. Merchant has to wait for
                      payment.
                  </td>
                  <td>Not possible</td>
              </tr>
              <tr class="warning">
                  <td>1</td>
                  <td>
                      `Orderline` is paid. The merchant has received the payment and must validate or cancel the `Orderline`.
                  </td>
                  <td>State 2 or 4</td>
              </tr>
              <tr class="warning">
                  <td>2</td>
                  <td>
                      `Orderline` is accepted by the merchant, who must now prepare the `Product` for shipment.
                  </td>
                  <td>State 3 or 5</td>
              </tr>
              <tr class="success">
                  <td>3</td>
                  <td>
                      The merchant has deliver the `Orderline` to the shipping company. The package delivery is in progress.
                  </td>
                  <td>State 6</td>
              </tr>
              <tr class="success">
                  <td>4</td>
                  <td>
                      `Orderline` is cancelled. The customer will be refunded for the `Orderline`.
                  </td>
                  <td>Not possible</td>
              </tr>
              <tr class="success">
                  <td>5</td>
                  <td>
                      Orderline is refunded before shipping.
                  </td>
                  <td>Not possible</td>
              </tr>
              <tr class="success">
                  <td>6</td>
                  <td>
                      Orderline is refunded after shipping. The customer made a refund request.
                  </td>
                  <td>Not possible</td>
              </tr>
              <tr class="success">
                  <td>7</td>
                  <td>
                      Orderline is not paid. The payment has been refused by the bank.
                  </td>
                  <td>Not possible</td>
              </tr>
          </tbody>
        </table>

        ### Table 7 - Order model

        <table class="table">
          <thead>
            <tr>
                <th>Field name</th>
                <th>Type/Size</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
              <tr>
                  <td>order_id</td>
                  <td>Int</td>
                  <td>Unique id of the `Order`. Used to update `Orderline(s)` of an `Order` .</td>
              </tr>
              <tr>
                  <td>merchant_id</td>
                  <td>Int</td>
                  <td>Unique id of the merchant.</td>
              </tr>
              <tr>
                  <td>shipping_address</td>
                  <td>Address</td>
                  <td>Shipping address: please refer to the Table 8 for address description.</td>
              </tr>
              <tr>
                  <td>billing_address</td>
                  <td>Address</td>
                  <td>Billing address: please refer to the Table 8 for address description.</td>
              </tr>
              <tr>
                  <td>price</td>
                  <td>Decimal</td>
                  <td>`Order` total  price (including taxes) without the shipping price.</td>
              </tr>
              <tr>
                  <td>shipping_price</td>
                  <td>Decimal</td>
                  <td>Shipping total price (including taxes).</td>
              </tr>
              <tr>
                  <td>currency</td>
                  <td>String/3</td>
                  <td>Used currency.</td>
              </tr>
              <tr>
                  <td>shipper</td>
                  <td>String/200</td>
                  <td>Designated shipping company.</td>
              </tr>
              <tr>
                  <td>tracking_number</td>
                  <td>String/200</td>
                  <td>Tracking number of the package.</td>
              </tr>
              <tr>
                  <td>tracking_url</td>
                  <td>String/300</td>
                  <td>Tracking Url of the package.</td>
              </tr>
              <tr>
                  <td>date_creation</td>
                  <td>Datetime</td>
                  <td>Date of the Order in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) format</td>
              </tr>
              <tr>
                  <td>date_modification</td>
                  <td>Datetime</td>
                  <td>Date of the last modification in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) format</td>
              </tr>
              <tr>
                  <td>date_payment</td>
                  <td>Datetime</td>
                  <td>Date of the payment in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) format</td>
              </tr>
              <tr>
                  <td>date_shipping</td>
                  <td>Datetime</td>
                  <td>Date of the shipping in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) format</td>
              </tr>
              <tr>
                  <td>state</td>
                  <td>Enum (Int)</td>
                  <td>Refere to Table 5 for the Order states details.</td>
              </tr>
              <tr>
                  <td>orderlines</td>
                  <td>Array[OrderLine]</td>
                  <td>List of `Orderlines` indexed by SKU (stock keeping unit).</td>
              </tr>
              <tr>
                  <td>country_code</td>
                  <td>Enum (String)</td>
                  <td>
                      <div>Accepted-values:</div>
                      <div>fr-fr: France (default)</div>
                      <div>fr-be: Belgium</div>
                      <div>es-es: Spain</div>
                      <div>de-at: Austria</div>
                      <div>de-de: Germany</div>
                      <div>it-it: Italy</div>
                      <div>ja-jp: Japan</div>
                      <div>en-au: Australia</div>
                      <div>en-gb: United Kingdom</div>
                      <div>en-us: United States</div>
                      <div>nl-nl: Netherlands</div>
                      <div>pt-pt: Portugal</div>
                      <div>en-ie: Ireland</div>
                      <div>el-gr: Greece</div>
                      <div>sk-sk: Slovakia</div>
                      <div>sv-se: Sweden</div>
                  </td>
              </tr>
          </tbody>
        </table>

        ### Table 8 - Address model

        <table class="table">
          <thead>
            <tr>
                <th>Field name</th>
                <th>Type/Size</th>
                <th>Description</th>
            </tr>
          </thead>
          <tbody>
              <tr>
                  <td>company</td>
                  <td>String/254</td>
                  <td>Company name.</td>
              </tr>
              <tr>
                  <td>last_name</td>
                  <td>String/200</td>
                  <td>Last name.</td>
              </tr>
              <tr>
                  <td>last_name_pronunciation</td>
                  <td>String/200</td>
                  <td>Last name pronunciation. This field is only used to handle Kana names for Japan.</td>
              </tr>
              <tr>
                  <td>first name</td>
                  <td>String/200</td>
                  <td>First name.</td>
              </tr>
              <tr>
                  <td>first_name_pronunciation</td>
                  <td>String/200</td>
                  <td>First name pronunciation. This field is only used to handle Kana names for Japan.</td>
              </tr>
              <tr>
                  <td>street</td>
                  <td>String/254</td>
                  <td>Street number and designation.</td>
              </tr>
              <tr>
                  <td>street2</td>
                  <td>String/254</td>
                  <td>Floor, door code.</td>
              </tr>
              <tr>
                  <td>postal_code</td>
                  <td>String/10</td>
                  <td>Zip code.</td>
              </tr>
              <tr>
                  <td>city</td>
                  <td>String/200</td>
                  <td>City.</td>
              </tr>
              <tr>
                  <td>country</td>
                  <td>String/100</td>
                  <td>Country.</td>
              </tr>
              <tr>
                  <td>phone</td>
                  <td>String/14</td>
                  <td>Phone number.</td>
              </tr>
              <tr>
                  <td>email</td>
                  <td>String/200</td>
                  <td>Email address.</td>
              </tr>
          </tbody>
        </table>

        ### Table 9 - OrderLine model

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