---
title: "Get category tree"
method: GET
path: "/ws/category/tree"
tags: ["Categories"]
---

# Get category tree

`GET /ws/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` :

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

## Response `200`

OK

- CategoryTree[]
  - `category_id` integer, required
  - `category_name` string, required
  - `marketplace_category_id` integer, required
  - `is_leaf` boolean, required
  - `attributes` object[], required
    - `field` string, required
    - `field_name` string, required
    - `type` 0 | 1 | 2 | 3, required — - 0: DECIMAL, 1:INTEGER, 2:STRING, 3:MULTIPLE_CHOICE
    - `allowed_values` string, required — List of allowed values for the given product attribute, separated by commas.
    - `required` boolean, required

## Other responses

- `401` — Unauthenticated.
- `403` — Forbidden. Authenticated user is not a merchant.

---

[API](https://skmtc.net/backmarket/apis/back-market-api-guidelines.md) · [All operations](https://skmtc.net/backmarket/apis/back-market-api-guidelines/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/backmarket/back-market-api-guidelines/revisions/6a1303364143/schema)