Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
---
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 > Υπηρεσίες > Έξυπνο Καλάθι).
> <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. For more information on API requests check the [API overview](/api/v3/).
<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.
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>
## 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' %>
[More on API error handling](/api/v3/#error-handling)
## 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 %>
## 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' %>