Skroutz API Access Application no longer accepts requests.

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.

Table of Contents

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
{
  "order": {
    "code": "191029-5130474",
    "state": "open",
    "customer": {
      "id": "PA4oqvpz8x",
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής",
        "pickup_from_collection_point": false
      }
    },
    "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": "ACS",
    "courier_voucher": null,
    "courier_tracking_codes": [

    ],
    "line_items": [
      {
        "id": "l39vKqxqwe",
        "shop_uid": "100",
        "product_name": "Smartphone 123",
        "quantity": 2,
        "unit_price": 100,
        "total_price": 200,
        "price_includes_vat": false,
        "ean": "1234567890123"
      },
      {
        "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

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.

  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
{
  "success": true
}

Example

curl -X POST https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567/accept \
  -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 '{ "pickup_location": "YlpD0KROym", "pickup_window": 2, "number_of_parcels": 1 }'

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
{
  "success": true
}

Example

curl -X POST https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567/reject \
  -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 '{ "line_items": [ { "id": "jn231kb12u", "reason_id": 2 }, { "id": "opaoe8M3pZ", "reason_id": 4, "available_quantity": 1 } ] }'

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
{
  "success": true
}

Example

curl -X POST https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567/reject \
  -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 '{ "rejection_reason_other": "Our store is closed for personal reasons" }'

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:

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

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:

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

More on API error handling

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 String ACS, Speedex, ELTA Courier, Easy Mail, COURIER CENTER, DHL, SendX Order's shipment courier
courier_voucher String   Order's shipment courier voucher URL
courier_tracking_codes Array   Order's shipment courier tracking codes
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.id String Unique customer id
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
customer.address.pickup_from_collection_point Boolean Pickup from collection point
customer.address.collection_point_address String Collection point address (available when pickup address is a collection point)

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_items[_].ean String EAN code of product (optional)

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