Orders API Edit the file on GitHub

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.

Setup
- Obtaining an API token
- Authorization
Endpoints
Error handling
Order object attributes appendix

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 > Υπηρεσίες > Έξυπνο Καλάθι).

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.

curl -X GET https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567 \
  -H 'Accept: application/vnd.skroutz+json; version=3.0' \
  -H 'Authorization: Bearer your_access_token_here'

Endpoints

All endpoints require the order code as a URL parameter. This is available in all incoming order 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.

  GET /merchants/ecommerce/orders/:code

GET https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567

View Response

Show Headers

Status: 200

Age: 0
Cache-Control: no-cache
Connection: keep-alive
Content-Length: 6400
Content-Type: application/json; charset=utf-8
Date: Thu, 19 Nov 2019 15:01:26 GMT
Server: h2o (Debian)
Via: 1.1 varnish (Varnish/5.0)
X-App: as103_ssl
X-Cache: MISS
X-Cached: skroutz miss(0)
X-Meta-Client-Id: 27951bdf06a65ea4
X-Origin: lb2
X-Request-Id: 989369834
X-Runtime: 0.021923
X-Varnish: 989369834

{
  "order": {
    "code": "191029-5130474",
    "state": "open",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής"
      }
    },
    "invoice": true,
    "invoice_details": {
      "company": "ACME",
      "profession": "Internet Services",
      "vat_number": "111119191",
      "doy": "ΙΒ Αθηνών",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής"
      },
      "vat_exclusion_requested": true,
      "vat_exclusion_representative": {
        "id_type": "ΑΤ Αστυνομική Ταυτότητα",
        "id_number": "12345",
        "otp": "123456"
      }
    },
    "comments": "Παράδοση στο γραφείο",
    "courier_voucher": null,
    "line_items": [
      {
        "id": "l39vKqxqwe",
        "shop_uid": "100",
        "product_name": "Smartphone 123",
        "quantity": 2,
        "unit_price": 100,
        "total_price": 200,
        "price_includes_vat": false
      },
      {
        "id": "l39vKqxqh2",
        "shop_uid": "10",
        "product_name": "Smartphone case Silver",
        "quantity": 1,
        "unit_price": 25,
        "total_price": 25,
        "price_includes_vat": true
      }
    ],
    "created_at": "2019-11-28T13:24:37+02:00",
    "expires_at": "2019-12-04T10:24:00+02:00",
    "dispatch_until": "2019-12-04T18:00:00+02:00",
    "accept_options": {
      "number_of_parcels": [
        1
      ],
      "pickup_location": [
        {
          "id": "YlpD0KROym",
          "label": "Πανεπιστημίου 2, Τ.Κ. 12345, Αθήνα, Αττική"
        },
        {
          "id": "onpL6DXG4l",
          "label": "Σταδίου 1, Τ.Κ. 12345, Αθήνα, Αττική"
        },
        {
          "id": "wgO1N22OaQ",
          "label": "Κρήτης 50, Τ.Κ. 73100, Χανιά, Χανιά"
        }
      ],
      "pickup_window": [
        {
          "id": 1,
          "label": "15:00 - 18:00, Τρί 03/12/19"
        },
        {
          "id": 2,
          "label": "10:00 - 12:00, Τετ 04/12/19"
        },
        {
          "id": 3,
          "label": "12:00 - 15:00, Τετ 04/12/19"
        },
        {
          "id": 4,
          "label": "15:00 - 18:00, Τετ 04/12/19"
        }
      ]
    },
    "reject_options": {
      "line_item_rejection_reasons": [
        {
          "id": 1,
          "label": "Εκτός αποθέματος στο κατάστημα ή στον προμηθευτή",
          "requires_available_quantity": false
        },
        {
          "id": 2,
          "label": "Λάθος καταχωρημένη τιμή(ες)",
          "requires_available_quantity": false
        },
        {
          "id": 4,
          "label": "Περιορισμένα τεμάχια",
          "requires_available_quantity": true
        },
        {
          "id": 5,
          "label": "To προϊόν καταργήθηκε",
          "requires_available_quantity": false
        }
      ]
    }
  }
}

Accept a single order

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

  POST /merchants/ecommerce/orders/:code/accept

POST https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567/accept

View Response Params

{
  "number_of_parcels": 1,
  "pickup_location": "YlpD0KROym",
  "pickup_window": 2
}

Show Headers

Status: 200

Age: 0
Cache-Control: no-cache
Connection: keep-alive
Content-Length: 64
Content-Type: application/json; charset=utf-8
Date: Thu, 19 Nov 2019 15:01:26 GMT
Server: h2o (Debian)
Via: 1.1 varnish (Varnish/5.0)
X-App: as103_ssl
X-Cache: MISS
X-Cached: skroutz miss(0)
X-Meta-Client-Id: 27951bdf06a65ea4
X-Origin: lb2
X-Request-Id: 989369834
X-Runtime: 0.021923
X-Varnish: 989369834

{
  "success": true
}

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.

  POST /merchants/ecommerce/orders/:code/reject

POST https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567/reject

View Response Params

{
  "line_items": [
    {
      "id": "jn231kb12u",
      "reason_id": 2
    },
    {
      "id": "opaoe8M3pZ",
      "reason_id": 4,
      "available_quantity": 1
    }
  ]
}

Show Headers

Status: 200

Age: 0
Cache-Control: no-cache
Connection: keep-alive
Content-Length: 64
Content-Type: application/json; charset=utf-8
Date: Thu, 19 Nov 2019 15:01:26 GMT
Server: h2o (Debian)
Via: 1.1 varnish (Varnish/5.0)
X-App: as103_ssl
X-Cache: MISS
X-Cached: skroutz miss(0)
X-Meta-Client-Id: 27951bdf06a65ea4
X-Origin: lb2
X-Request-Id: 989369834
X-Runtime: 0.021923
X-Varnish: 989369834

{
  "success": true
}

Reject whole order with "other" reason

  POST /merchants/ecommerce/orders/:code/reject

POST https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567/reject

View Response Params

{
  "rejection_reason_other": "Our store is closed for personal reasons"
}

Show Headers

Status: 200

Age: 0
Cache-Control: no-cache
Connection: keep-alive
Content-Length: 6400
Content-Type: application/json; charset=utf-8
Date: Thu, 19 Nov 2019 15:01:26 GMT
Server: h2o (Debian)
Via: 1.1 varnish (Varnish/5.0)
X-App: as103_ssl
X-Cache: MISS
X-Cached: skroutz miss(0)
X-Meta-Client-Id: 27951bdf06a65ea4
X-Origin: lb2
X-Request-Id: 989369834
X-Runtime: 0.021923
X-Varnish: 989369834

{
  "success": true
}

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 reject an order that is already rejected, you will get a 422 HTTP status code (Unprocessable Entity), with the following body:

{
  "errors": [
      {
          "code": "order_status",
          "messages": [
              "Order already rejected."
          ]
      }
  ]
}

Order object attributes appendix

The order object returned retrieving a single order via the API is the same as in webhook events about a new/updated order.

Order object

Name	Type	Value	Description
`code`	String		Order code
`state`	String	`open`, `accepted`, `rejected`, `cancelled`, `expired`, `dispatched`, `delivered`, `partially_returned`, `returned`	Order state
`customer`	Object		Customer details
`invoice`	Boolean		Invoice requested
`invoice_details`	Object		Invoice details (available when invoice is requested)
`comments`	String		Order comments
`courier_voucher`	String		Order's shipment courier voucher URL
`line_items`	Array		Order line items (products)
`created_at`	Date String in format `YYYY-MM-DDTHH:MM:SS+HH:M`		Order creation date
`expires_at`	Date String in format `YYYY-MM-DDTHH:MM:SS+HH:M`		Order expiration date
`dispatch_until`	Date String in format `YYYY-MM-DDTHH:MM:SS+HH:M`		Order maximum dispatch date
`accept_options`	Object		Accept options (available for orders with state `"open"`)
`reject_options`	Object		Reject options (available for orders with state `"open"`)

Customer details

Name	Type	Description
`customer.first_name`	String	First name
`customer.last_name`	String	Last name
`customer.address`	Object	Customer shipping address

Customer shipping address

Name	Type	Description
`customer.address.street_name`	String	Address street
`customer.address.street_number`	String	Address number
`customer.address.zip`	String	Address postal code
`customer.address.city`	String	Address city
`customer.address.region`	String	Address region

Invoice details

This attribute is present only when a user requests an invoice for the order.

Name	Type	Description
`invoice_details.company`	String	Company's name
`invoice_details.profession`	String	Company's profession
`invoice_details.vat_number`	String	Company's VAT number
`invoice_details.doy`	String	Company's public economic service
`invoice_details.address`	Object	Billing address
`invoice_details.vat_exclusion_requested`	Boolean	VAT exclusion requested (Υπηρεσία άρθρου 39α)
`invoice_details.vat_exclusion_representative`	Object	39α representative details (when VAT exclusion is requested)

Billing address

Name	Type	Description
`invoice_details.address.street_name`	String	Address street
`invoice_details.address.street_number`	String	Address number
`invoice_details.address.zip`	String	Address postal code
`invoice_details.address.city`	String	Address city
`invoice_details.address.region`	String	Address region

Vat exclusion representative

Name	Type	Description
`invoice_details.vat_exclusion_representative.id_type`	String	Provided ID document type
`invoice_details.vat_exclusion_representative.id_number`	String	Provided ID document number (last 5 digits)
`invoice_details.vat_exclusion_representative.otp`	String	Provided representative one-time password

Order line items array

Name	Type	Description
`line_items[_].id`	String	Unique item id
`line_items[_].shop_uid`	String	Item id in shop
`line_items[_].product_name`	String	Item product name
`line_items[_].quantity`	Integer	Item quantity
`line_items[_].size`	Object	Item size values (optional)
`line_items[_].unit_price`	Double	Price per item in euros
`line_items[_].total_price`	Double	Total item price in euros: `unit_price` * `quantity`
`line_items[_].price_includes_vat`	Boolean	Price includes VAT (could be `false` for invoice with VAT exclusion)

Line item size

Name	Type	Value	Description
`line_items[_].size.label`	String	`Νούμερο`, `Μέγεθος`, `Ηλικία`	Item size label
`line_items[_].size.value`	String		Item size value
`line_items[_].size.shop_value`	String		Item original size as provided by the shop

Accept options

These are valid values to POST to the corresponding keys when accepting a single order (only available for orders with state "open").

Name	Type	Example	Description
`accept_options.number_of_parcels`	Array	`[1, 2, 3]`	Valid values to post on `number_of_parcels`
`accept_options.pickup_location`	Array		Pickup location
`accept_options.pickup_window`	Array		Pickup window

Accept option: Pickup location

Valid pickup locations to post when accepting a single order (use id).

Name	Type	Description
`pickup_location.id`	String	The location ID to use
`pickup_location.label`	String	A human readable address

Accept option: Pickup window

Valid pickup windows to post when accepting a single order (use id).

Name	Type	Description
`pickup_window.id`	Integer	The pickup window ID to use
`pickup_window.label`	String	A human readable time range

Reject options

These are possible values to POST to the corresponding keys when rejecting a single order (only available for orders with state "open").

Name	Type	Description
`reject_options.line_item_rejection_reasons`	Array	Line item rejection reason

Reject option: Line item rejection reason

Available reasons to post along line_item ids when rejecting a single order (use id).

Name	Type	Description
`line_item_rejection_reason.id`	Integer	The rejection reason ID to use
`line_item_rejection_reason.label`	String	A human readable label
`line_item_rejection_reason.requires_available_quantity`	Boolean	Whether or not `available_quantity` is required

Search

Developer Documentation

Looking for something else?

Orders API Edit the file on GitHub

Table of Contents

Setup

Obtaining an API token

Authorization

Endpoints

Retrieve a single order

Accept a single order

Reject a single order

Reject specific line items with reasons

Reject whole order with "other" reason

Error handling

Order object attributes appendix

Order object

Customer details

Customer shipping address

Invoice details

Billing address

Vat exclusion representative

Order line items array

Line item size

Accept options

Accept option: Pickup location

Accept option: Pickup window

Reject options

Reject option: Line item rejection reason