orders_api.html.md.erb

---
parent: smart_cart
title: orders_api
---

<%= partial 'partials/page_locales' %>

# Orders API <%= edit_link %>

> <i class="fa fa-exclamation-triangle"></i>
> **Important update:** From 5/7/2021 onwards, more order state updates will be sent via Webhook requests. [Read more](/smart_cart/webhook#webhook-events)

Orders API allows Skroutz Merchants to perform actions on their Smart Cart orders,
such as accepting or rejecting an order.

You may find a high level overview of the service and descriptive guides for its activation in the
[merchant support guidelines](https://<%= settings.merchants_domain %>/merchants/support/guidelines/skroutz_marketplace_integration).

<%= partial 'partials/toc' %>

## Setup

### Obtaining an API token

In order to be able to use the API, you need to generate an **API token** from within Smart Cart settings
page in merchant's panel (Merchants > Services > [Skroutz Marketplace](https://<%= settings.merchants_domain %>/merchants/account/shop/ecommerce_details)).

> <i class="fa fa-exclamation-triangle"></i>
> There can only be one active **API key** per shop at a certain time.
> Creating a new API key will expire any previous one.

### Authorization

Pass in a valid **API token** in the `Authorization` header, prefixed with `Bearer `
as in the following curl example.

A specific `Accept` header is also required.

<pre class="terminal">
curl -X GET https://<%= settings.api_domain %>/merchants/ecommerce/orders/191128-1234567 \
  -H 'Accept: application/vnd.<%= settings.site_name %>+json; version=3.0' \
  -H 'Authorization: Bearer your_access_token_here'
</pre>

## Endpoints

All endpoints require the order `code` as a URL parameter. This is available in all incoming order
[Webhook](/smart_cart/webhook) events, as well as the merchants' panel.

### Retrieve a single order

When an order is in a state that can be accepted or rejected, `accept_options` and `reject_options`
attributes are included in the response, providing all the available options for
issuing "accept" or "reject" requests for the order, respectively.

<pre class="terminal">
  GET /merchants/ecommerce/orders/:code
</pre>

<%= render_recording :merchants_ecommerce_orders_show %>

### Accept a single order

To accept an order you need to provide the `pickup_location` and the `pickup_window` which are required. You can also specify `number_of_parcels` which is optional with a default value of `1` if missing.

> <i class="fa fa-exclamation-triangle"></i>
> Express orders cannot be accepted via the API. An automated mechanism will handle the order acceptance.

The available param values used are provided in `accept_options` when retrieving a single order.

<pre class="terminal">
  POST /merchants/ecommerce/orders/:code/accept
</pre>

<%= render_recording :merchants_ecommerce_orders_accept %>

#### Example
<pre class="terminal">
curl -X POST https://<%= settings.api_domain %>/merchants/ecommerce/orders/191128-1234567/accept \
  -H 'Accept: application/vnd.<%= settings.site_name %>+json; version=3.0' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer your_access_token_here' \
  -d '{ "pickup_location": "YlpD0KROym", "pickup_window": 2, "number_of_parcels": 1 }'
</pre>

### Reject a single order

#### Reject specific line items with reasons

To reject specific line items you need to provide a `line_items` params which would hold an
array of line items. Each line items should have the line item `id` and the rejection
`reason_id`. In case the rejection reason `requires_available_quantity`,
an `available_quantity` attribute is also required.

The available rejection reason IDs are provided in `reject_options` when retrieving a single order.

<pre class="terminal">
  POST /merchants/ecommerce/orders/:code/reject
</pre>

<%= render_recording :merchants_ecommerce_orders_reject %>

#### Example
<pre class="terminal">
curl -X POST https://<%= settings.api_domain %>/merchants/ecommerce/orders/191128-1234567/reject \
  -H 'Accept: application/vnd.<%= settings.site_name %>+json; version=3.0' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer your_access_token_here' \
  -d '{ "line_items": [ { "id": "jn231kb12u", "reason_id": 2 }, { "id": "opaoe8M3pZ", "reason_id": 4, "available_quantity": 1 } ] }'
</pre>

#### Reject whole order with "other" reason

<pre class="terminal">
  POST /merchants/ecommerce/orders/:code/reject
</pre>

<%= render_recording :merchants_ecommerce_orders_reject_other %>

#### Example
<pre class="terminal">
curl -X POST https://<%= settings.api_domain %>/merchants/ecommerce/orders/191128-1234567/reject \
  -H 'Accept: application/vnd.<%= settings.site_name %>+json; version=3.0' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer your_access_token_here' \
  -d '{ "rejection_reason_other": "Our store is closed for personal reasons" }'
</pre>

### Upload receipt/invoice

To upload the receipt/invoice of the order, you need to set the `invoice_file` param with the contents of the document.

<pre class="terminal">
  POST /merchants/ecommerce/orders/:code/invoices
</pre>

#### Example
<pre class="terminal">
curl -X POST https://<%= settings.api_domain %>/merchants/ecommerce/orders/191128-1234567/invoices \
  -H 'Accept: application/vnd.<%= settings.site_name %>+json; version=3.0' \
  -H 'Content-Type: multipart/form-data' \
  -H 'Authorization: Bearer your_access_token_here' \
  -F 'invoice_file=@/path/to/invoice.pdf'
</pre>

Only one file is allowed per order. If the file is already uploaded, it will by replaced by the new file in a subsequent submission.

<blockquote>
  <p>
    Allowed file types are: pdf/png/jpg. The maximum file size is 7MB.
  </p>
</blockquote>

### Update tracking details (FBM only)
To allow shipment tracking, you need to provide the `courier` and `tracking_code` for each order shipment.

> <i class="fa fa-exclamation-triangle"></i>
> This endpoint is available only for FBM (Fulfilled By Merchant) orders
>
> <i class="fa fa-exclamation-triangle"></i>
>The existing API endpoint is limited to updating tracking details only for orders shipped to customers and does not currently support return orders.
>These should be still handled through merchants panel for the time being.

<pre class="terminal">
  POST /merchants/ecommerce/orders/:code/tracking_details
</pre>


<%= render_recording :merchants_ecommerce_orders_tracking_details %>

<pre class="terminal">
curl -X POST https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567/tracking_details \
  -H 'Accept: application/vnd.skroutz+json; version=3.0' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer your_access_token_here' \
  -d '{ "tracking_details": [ { "courier":"acs", "tracking_code":"224085551" } ] }'
</pre>


## Error handling

In case of errors, the response will have a representative HTTP status code
in the `4xx` or `5xx` range. The body would contain an array of `errors`.

For example, if you try to accept an order that is already accepted, you will
get a `422` HTTP status code (Unprocessable Entity), with the following body:

<%= render_code '{
  "errors": [
      {
          "code": "order_status",
          "messages": [
              "Order already accepted."
          ]
      }
  ]
}', 'javascript' %>

And if you try to reject an order that is already rejected, you will
also get a `422` HTTP status code (Unprocessable Entity), with the following body:

<%= render_code '{
  "errors": [
      {
          "code": "order_status",
          "messages": [
              "Order already rejected."
          ]
      }
  ]
}', 'javascript' %>

## Test requests (sandbox)

The following d​emo order codes​ are available on production for testing reasons and represent different order states.

> It is safe to issue "accept" and "reject" API calls for the following demo order codes multiple times for testing,
> since no actions on them would persist any data.

#### DEMO-OPEN

A new order that is not accepted yet, and has no courier voucher.

<pre class="terminal">
  GET /merchants/ecommerce/orders/DEMO-OPEN
</pre>

<%= render_recording :merchants_ecommerce_orders_demo_open %>

#### DEMO-ACCEPTED

An already-accepted order that also has a courier voucher. Trying to accept it would return an error.

<pre class="terminal">
  GET /merchants/ecommerce/orders/DEMO-ACCEPTED
</pre>

<%= render_recording :merchants_ecommerce_orders_demo_accepted %>

#### DEMO-REJECTED

An already-rejected order. Trying to reject it would return an error.

<pre class="terminal">
  GET /merchants/ecommerce/orders/DEMO-REJECTED
</pre>

<%= render_recording :merchants_ecommerce_orders_demo_rejected %>

#### DEMO-INVOICE

A new order, requesting an invoice.

<pre class="terminal">
  GET /merchants/ecommerce/orders/DEMO-INVOICE
</pre>

<%= render_recording :merchants_ecommerce_orders_demo_invoice %>

#### DEMO-INVOICE39A

A new order including an item with VAT exclusion based on “​Άρθρο 39α​”.

<pre class="terminal">
  GET /merchants/ecommerce/orders/DEMO-INVOICE39A
</pre>

<%= render_recording :merchants_ecommerce_orders_demo_invoice39a %>

#### DEMO-FBS

An already-accepted order without a courier voucher that will be fulfilled by Skroutz. Trying to accept it would return an error.

<pre class="terminal">
  GET /merchants/ecommerce/orders/DEMO-FBS
</pre>

<%= render_recording :merchants_ecommerce_orders_demo_fbs %>

#### DEMO-FBS-DISPATCHED

A dispatched order without a courier voucher that will be fulfilled by Skroutz. Delivery note included.

<pre class="terminal">
  GET /merchants/ecommerce/orders/DEMO-FBS-DISPATCHED
</pre>

<%= render_recording :merchants_ecommerce_orders_demo_fbs_dispatched %>

#### DEMO-STORE-PICKUP

An open order without a courier or courier voucher that will be picked up by the user at the store.

<pre class="terminal">
  GET /merchants/ecommerce/orders/DEMO-STORE-PICKUP
</pre>

<%= render_recording :merchants_ecommerce_orders_demo_store_pickup %>

## Order object attributes appendix

> The order object returned retrieving a single order via the API is the same as
> in [webhook events](/smart_cart/webhook) about a new/updated order.

<%= partial 'localizable/smart_cart/order_object' %>