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
  • Authorization
• Endpoints
  • Retrieve a single order
  • Accept a single order
  • Reject a single order
• 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

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": {
      "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

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

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
}

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

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

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
}

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

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

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
}

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

Customer details

Customer shipping address

Invoice details

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

Billing address

Vat exclusion representative

Order line items array

Line item size

Accept options

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

Accept option: Pickup location

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

Accept option: Pickup window

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

Reject options

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

Reject option: Line item rejection reason

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