---
title: "Get the orders"
method: GET
path: "/ws/orders"
tags: ["Orders"]
---

# Get the orders

`GET /ws/orders`

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>

## Query parameters

- `date_creation` string, date-time
- `date_modification` string, date-time
- `country_code` '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'
- `state` 0 | 10 | 1 | 3 | 8 | 9 — 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. |
- `page` integer
- `page-size` integer

## Response `200`

Return the orders matching the filter in the query parameters

- object
  - `count` integer
  - `next` string, nullable
  - `previous` string, nullable
  - `results` Order[]
    - `order_id` integer — The unique id of the order. Used to update orderlines of a given order
    - `delivery_mode` 'HOME_DELIVERY' | 'COLLECTION_POINT' — The delivery mode associated with the shipping address of the order. - `HOME_DELIVERY`: The shipping address is a home-delivery address. - `COLLECTION_POINT`: The shipping address is a collection-point address.
    - `shipping_address` Address
      - `id` integer
      - `country` string — ISO 3166-1 alpha-2 country code.
      - `city` string
      - `postalCode` string
      - `firstName` string
      - `lastName` string
      - `company` string
      - `phoneNumber` string — E.164 formatted phone number.
      - `state` string
      - `street` string
      - `street2` string
    - `billing_address` Address
      - `id` integer
      - `country` string — ISO 3166-1 alpha-2 country code.
      - `city` string
      - `postalCode` string
      - `firstName` string
      - `lastName` string
      - `company` string
      - `phoneNumber` string — E.164 formatted phone number.
      - `state` string
      - `street` string
      - `street2` string
    - `delivery_note` string, url — Document to add in package which contains useful information for the customer, related to his order.
    - `expected_dispatch_date` string, date-time — The shipment expected dispatch date (only applicable for orders not already SENT).
    - `tracking_number` string — Tracking number of the package
    - `tracking_url` string, url — Tracking Url of the package
    - `shipper_display` string — Name of the shipper
    - `is_backship` boolean — True if the shipper of the order is backship
    - `date_creation` string, date-time — Date of order
    - `date_modification` string, date-time — Date of last modification
    - `date_shipping` string, date-time — Date of shipping
    - `date_payment` string, date-time — Date of payment
    - `state` 0 | 10 | 1 | 3 | 8 | 9 — 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. |
    - `orderlines` OrderLine[] — List of orderlines of the order. Indexed by SKU
      - `id` integer — The orderline unique ID
      - `date_creation` string, date-time — Date of creation of the orderline
      - `state` 0 | 9 | 8 | 1 | 2 | 3 | 4 | 5 | 6 | 7 — 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 |
      - `price` string — Price (including taxes) of the listing associated & warranty without the shipping price
      - `shipping_price` string — Unitary shipping price (including taxes)
      - `shipping_delay` integer — Shipping time
      - `currency` string — Currency used
      - `return_reason` 0 | 1 | 11 | 12 | 13 | 21 | 22 | 23 | 24 | 25 — 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 |
      - `return_message` string — Message sent to the customer for a cancellation or a refund
      - `listing` string — SKU of the listing
      - `listing_id` integer — ID of the listing
      - `orderline_fee` string — BackMarket commission fee amount
      - `product` string — Title of the product
      - `quantity` integer — Quantity of products ordered
      - `brand` string — The brand of the product
      - `product_id` integer — The product ID
      - `backcare` boolean — True if this orderline is covered by the Backcare service
      - `backcare_price` integer — The backcare price in cents
      - `sales_taxes` string — Sales taxes (country/state dependent)
      - `imei` string — Unique product identifier
      - `serial_number` string — Unique product identifier
      - `condition` 9 | 10 | 11 | 12 — Condition of the product. | Value | Description | |-------|---------------------| | 9 | Premium condition | | 1O | Excellent condition | | 11 | Good condition | | 12 | Fair condition |
    - `price` string — The total price of the order (including taxes) without the shipping price
    - `shipping_price` string — Total shipping price (including taxes)
    - `currency` string — Currency used for the order
    - `country_code` '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'
    - `paypal_reference` string, nullable — Paypal reference ID
    - `installment_payment` boolean — Whether the customer chose a payment in multiple increments
    - `payment_method` string — The customer payment method (Eg: CARD, PAYPAL)
    - `sales_taxes` string — Sales taxes (country/state dependent)

## Other responses

- `400` — Bad request
- `403` — Forbidden
- `404` — Webservices unavailable

---

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