latestOpenAPI 3.0.32026-08-193973220.1 KB

6a1303364143

Get category tree

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 :

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.

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

get/ws/category/tree

Response

category_idinteger required

category_namestring required

marketplace_category_idinteger required

is_leafboolean required

Example response

[
  {
    "category_id": 1,
    "category_name": "Smartphone",
    "marketplace_category_id": 123,
    "attributes": [
      {
        "field": "color",
        "field_name": "Couleur",
        "type": 2,
        "allowed_values": "Unlocked GSM, Unlocked CMDA,AT&T,Verizon,Sprint,T Mobile,Boost Mobile,No SIM slot",
        "required": true
      }
    ]
  }
]