Orders API Edit the file on GitHub

Important update: From 5/7/2021 onwards, more order state updates will be sent via Webhook requests. Read more

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 > Services > Skroutz Marketplace).

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.

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": "Αττικής",
        "country_code": "GR",
        "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,
        "island_vat_discount_applied": false,
        "ean": "1234567890123",
        "serial_numbers": null
      },
      {
        "id": "l39vKqxqh2",
        "shop_uid": "10",
        "product_name": "Smartphone case Silver",
        "quantity": 1,
        "unit_price": 25,
        "total_price": 25,
        "price_includes_vat": true,
        "island_vat_discount_applied": false,
        "serial_numbers": null
      }
    ],
    "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",
    "express": false,
    "gift_wrap": false,
    "fulfilled_by_skroutz": false,
    "fbs_delivery_note": null,
    "store_pickup": false,
    "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.

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.

  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" }'

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.

  POST /merchants/ecommerce/orders/:code/invoices

Example

curl -X POST https://api.skroutz.gr/merchants/ecommerce/orders/191128-1234567/invoices \
  -H 'Accept: application/vnd.skroutz+json; version=3.0' \
  -H 'Content-Type: multipart/form-data' \
  -H 'Authorization: Bearer your_access_token_here' \
  -F 'invoice_file=@/path/to/invoice.pdf'

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.

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

Update tracking details (FBM only)

To allow shipment tracking, you need to provide the courier and tracking_code for each order shipment.

This endpoint is available only for FBM (Fulfilled By Merchant) orders

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.

  POST /merchants/ecommerce/orders/:code/tracking_details

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

View Response Params
{
  "tracking_details": [
    {
      "courier": "acs",
      "tracking_code": "224085551"
    }
  ]
}
Show Headers
Status: 200
{
  "success": true
}
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" } ] }'

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."
          ]
      }
  ]
}

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.

  GET /merchants/ecommerce/orders/DEMO-OPEN

GET https://api.skroutz.gr/merchants/ecommerce/orders/DEMO-OPEN

View Response
Show Headers
Status: 200
{
  "order": {
    "code": "DEMO-OPEN",
    "state": "open",
    "customer": {
      "id": "user1234",
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής",
        "country_code": "GR",
        "pickup_from_collection_point": false
      }
    },
    "invoice": false,
    "comments": "Παράδοση στο γραφείο",
    "courier": "CourierCenter",
    "courier_voucher": null,
    "courier_tracking_codes": [

    ],
    "line_items": [
      {
        "id": "Y5jVmgKmeX",
        "shop_uid": "405753",
        "shop_variation_uid": "40575312-14",
        "product_name": "Adidas Perormance Badge of Sport Swimsuit PS/GS",
        "quantity": 2,
        "size": {
          "label": "Ηλικία",
          "value": "14 χρονών",
          "shop_value": "12-14",
          "shop_variation_uid": "40575312-14",
          "ean": "1234567890321"
        },
        "unit_price": 17.99,
        "total_price": 35.98,
        "price_includes_vat": true,
        "ean": "1234567890123",
        "serial_numbers": null,
        "tags": [
          "plus_deal",
          "price_optimizer"
        ]
      },
      {
        "id": "3XlV8ebjxm",
        "shop_uid": "10",
        "product_name": "Smartphone 123",
        "quantity": 2,
        "unit_price": 100,
        "total_price": 200,
        "price_includes_vat": true,
        "serial_numbers": null,
        "tags": [
          "coupon_deal"
        ]
      },
      {
        "id": "ZvEKMxbxr1",
        "shop_uid": "768",
        "product_name": "AIR OPTIX COLORS MHNIAIOI",
        "quantity": 2,
        "unit_price": 25.5,
        "total_price": 51,
        "price_includes_vat": true,
        "extra_info": "Χρώμα: Πράσινο\\nΒαθμοί SPH: -6.50",
        "serial_numbers": null,
        "tags": [
          "two_plus_deal"
        ]
      }
    ],
    "created_at": "2021-06-24T13:08:30+03:00",
    "expires_at": "2021-06-25T13:08:30+03:00",
    "dispatch_until": "2021-06-28T13:08:30+03:00",
    "express": false,
    "gift_wrap": false,
    "fulfilled_by_skroutz": false,
    "fbs_delivery_note": null,
    "store_pickup": false,
    "accept_options": {
      "number_of_parcels": [
        1
      ],
      "pickup_location": [
        {
          "id": "Y5jVmgKmeX",
          "label": "Πανεπιστημίου 2, Τ.Κ. 12345, Αθήνα, Αττική"
        },
        {
          "id": "3XlV8ebjxm",
          "label": "Σταδίου 1, Τ.Κ. 12345, Αθήνα, Αττική"
        }
      ],
      "pickup_window": [
        {
          "id": 1,
          "label": "15:00 - 18:00, Πέμ 24/06/21"
        },
        {
          "id": 2,
          "label": "10:00 - 12:00, Παρ 25/06/21"
        },
        {
          "id": 3,
          "label": "12:00 - 15:00, Παρ 25/06/21"
        },
        {
          "id": 4,
          "label": "15:00 - 18:00, Παρ 25/06/21"
        },
        {
          "id": 5,
          "label": "10:00 - 12:00, Δευ 28/06/21"
        }
      ]
    },
    "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
        }
      ]
    }
  }
}

DEMO-ACCEPTED

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

  GET /merchants/ecommerce/orders/DEMO-ACCEPTED

GET https://api.skroutz.gr/merchants/ecommerce/orders/DEMO-ACCEPTED

View Response
Show Headers
Status: 200
{
  "order": {
    "code": "DEMO-ACCEPTED",
    "state": "accepted",
    "customer": {
      "id": "user1234",
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής",
        "country_code": "GR",
        "pickup_from_collection_point": false
      }
    },
    "invoice": false,
    "comments": "Παράδοση στο γραφείο",
    "courier": "CourierCenter",
    "courier_voucher": "https://skroutz.gr/merchants/sample_vouchers/courier_center.pdf",
    "courier_tracking_codes": [
      "123456789"
    ],
    "line_items": [
      {
        "id": "Y5jVmgKmeX",
        "shop_uid": "405753",
        "shop_variation_uid": "40575312-14",
        "product_name": "Adidas Perormance Badge of Sport Swimsuit PS/GS",
        "quantity": 2,
        "size": {
          "label": "Ηλικία",
          "value": "14 χρονών",
          "shop_value": "12-14",
          "shop_variation_uid": "40575312-14",
          "ean": "1234567890321"
        },
        "unit_price": 17.99,
        "total_price": 35.98,
        "price_includes_vat": true,
        "ean": "1234567890123",
        "serial_numbers": null
      },
      {
        "id": "3XlV8ebjxm",
        "shop_uid": "10",
        "product_name": "Smartphone 123",
        "quantity": 2,
        "unit_price": 100,
        "total_price": 200,
        "price_includes_vat": true,
        "serial_numbers": null
      },
      {
        "id": "ZvEKMxbxr1",
        "shop_uid": "768",
        "product_name": "AIR OPTIX COLORS MHNIAIOI",
        "quantity": 2,
        "unit_price": 25.5,
        "total_price": 51,
        "price_includes_vat": true,
        "extra_info": "Χρώμα: Πράσινο\\nΒαθμοί SPH: -6.50",
        "serial_numbers": null
      }
    ],
    "created_at": "2021-06-24T13:11:41+03:00",
    "expires_at": "2021-06-25T13:11:41+03:00",
    "dispatch_until": "2021-06-28T13:11:41+03:00",
    "express": false,
    "gift_wrap": false,
    "fulfilled_by_skroutz": false,
    "fbs_delivery_note": null,
    "store_pickup": false
  }
}

DEMO-REJECTED

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

  GET /merchants/ecommerce/orders/DEMO-REJECTED

GET https://api.skroutz.gr/merchants/ecommerce/orders/DEMO-REJECTED

View Response
Show Headers
Status: 200
{
  "order": {
    "code": "DEMO-REJECTED",
    "state": "rejected",
    "customer": {
      "id": "user1234",
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής",
        "country_code": "GR",
        "pickup_from_collection_point": false
      }
    },
    "invoice": false,
    "comments": "Παράδοση στο γραφείο",
    "courier": "CourierCenter",
    "courier_voucher": null,
    "courier_tracking_codes": [

    ],
    "line_items": [
      {
        "id": "Y5jVmgKmeX",
        "shop_uid": "405753",
        "shop_variation_uid": "40575312-14",
        "product_name": "Adidas Perormance Badge of Sport Swimsuit PS/GS",
        "quantity": 2,
        "size": {
          "label": "Ηλικία",
          "value": "14 χρονών",
          "shop_value": "12-14",
          "shop_variation_uid": "40575312-14",
          "ean": "1234567890321"
        },
        "unit_price": 17.99,
        "total_price": 35.98,
        "price_includes_vat": true,
        "ean": "1234567890123",
        "serial_numbers": null,
        "tags": [
          "plus_deal",
          "price_optimizer"
        ]
      },
      {
        "id": "3XlV8ebjxm",
        "shop_uid": "10",
        "product_name": "Smartphone 123",
        "quantity": 2,
        "unit_price": 100,
        "total_price": 200,
        "price_includes_vat": true,
        "serial_numbers": null,
        "tags": [
          "coupon_deal"
        ]
      },
      {
        "id": "ZvEKMxbxr1",
        "shop_uid": "768",
        "product_name": "AIR OPTIX COLORS MHNIAIOI",
        "quantity": 2,
        "unit_price": 25.5,
        "total_price": 51,
        "price_includes_vat": true,
        "extra_info": "Χρώμα: Πράσινο\\nΒαθμοί SPH: -6.50",
        "serial_numbers": null,
        "tags": [
          "two_plus_deal"
        ]
      }
    ],
    "created_at": "2021-06-24T13:11:58+03:00",
    "expires_at": "2021-06-25T13:11:58+03:00",
    "dispatch_until": "2021-06-28T13:11:58+03:00",
    "express": false,
    "gift_wrap": false,
    "fulfilled_by_skroutz": false,
    "fbs_delivery_note": null,
    "store_pickup": false,
    "rejection_info": {
      "reason": "Το κατάστημά μας είναι κλειστό για προσωπικούς λόγους",
      "actor": "merchant"
    }
  }
}

DEMO-INVOICE

A new order, requesting an invoice.

  GET /merchants/ecommerce/orders/DEMO-INVOICE

GET https://api.skroutz.gr/merchants/ecommerce/orders/DEMO-INVOICE

View Response
Show Headers
Status: 200
{
  "order": {
    "code": "DEMO-INVOICE",
    "state": "open",
    "customer": {
      "id": "user1234",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "2109999999",
      "mobile": "(+30) 6999999999",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής",
        "country_code": "GR",
        "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": false
    },
    "comments": "Παράδοση στο γραφείο",
    "courier": "CourierCenter",
    "courier_voucher": null,
    "courier_tracking_codes": [

    ],
    "line_items": [
      {
        "id": "Y5jVmgKmeX",
        "shop_uid": "405753",
        "shop_variation_uid": "40575312-14",
        "product_name": "Adidas Perormance Badge of Sport Swimsuit PS/GS",
        "quantity": 2,
        "size": {
          "label": "Ηλικία",
          "value": "14 χρονών",
          "shop_value": "12-14",
          "shop_variation_uid": "40575312-14",
          "ean": "1234567890321"
        },
        "unit_price": 17.99,
        "total_price": 35.98,
        "price_includes_vat": true,
        "ean": "1234567890123",
        "serial_numbers": null,
        "tags": [
          "plus_deal",
          "price_optimizer"
        ]
      },
      {
        "id": "3XlV8ebjxm",
        "shop_uid": "10",
        "product_name": "Smartphone 123",
        "quantity": 2,
        "unit_price": 100,
        "total_price": 200,
        "price_includes_vat": true,
        "serial_numbers": null,
        "tags": [
          "coupon_deal"
        ]
      },
      {
        "id": "ZvEKMxbxr1",
        "shop_uid": "768",
        "product_name": "AIR OPTIX COLORS MHNIAIOI",
        "quantity": 2,
        "unit_price": 25.5,
        "total_price": 51,
        "price_includes_vat": true,
        "extra_info": "Χρώμα: Πράσινο\\nΒαθμοί SPH: -6.50",
        "serial_numbers": null,
        "tags": [
          "two_plus_deal"
        ]
      }
    ],
    "created_at": "2021-06-24T13:12:12+03:00",
    "expires_at": "2021-06-25T13:12:12+03:00",
    "dispatch_until": "2021-06-28T13:12:12+03:00",
    "express": false,
    "gift_wrap": false,
    "fulfilled_by_skroutz": false,
    "fbs_delivery_note": null,
    "store_pickup": false,
    "accept_options": {
      "number_of_parcels": [
        1
      ],
      "pickup_location": [
        {
          "id": "Y5jVmgKmeX",
          "label": "Πανεπιστημίου 2, Τ.Κ. 12345, Αθήνα, Αττική"
        },
        {
          "id": "3XlV8ebjxm",
          "label": "Σταδίου 1, Τ.Κ. 12345, Αθήνα, Αττική"
        }
      ],
      "pickup_window": [
        {
          "id": 1,
          "label": "15:00 - 18:00, Πέμ 24/06/21"
        },
        {
          "id": 2,
          "label": "10:00 - 12:00, Παρ 25/06/21"
        },
        {
          "id": 3,
          "label": "12:00 - 15:00, Παρ 25/06/21"
        },
        {
          "id": 4,
          "label": "15:00 - 18:00, Παρ 25/06/21"
        },
        {
          "id": 5,
          "label": "10:00 - 12:00, Δευ 28/06/21"
        }
      ]
    },
    "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
        }
      ]
    }
  }
}

DEMO-INVOICE39A

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

  GET /merchants/ecommerce/orders/DEMO-INVOICE39A

GET https://api.skroutz.gr/merchants/ecommerce/orders/DEMO-INVOICE39A

View Response
Show Headers
Status: 200
{
  "order": {
    "code": "DEMO-INVOICE39A",
    "state": "open",
    "customer": {
      "id": "user1234",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "2109999999",
      "mobile": "(+30) 6999999999",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής",
        "country_code": "GR",
        "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": "CourierCenter",
    "courier_voucher": null,
    "courier_tracking_codes": [

    ],
    "line_items": [
      {
        "id": "Y5jVmgKmeX",
        "shop_uid": "405753",
        "shop_variation_uid": "40575312-14",
        "product_name": "Adidas Perormance Badge of Sport Swimsuit PS/GS",
        "quantity": 2,
        "size": {
          "label": "Ηλικία",
          "value": "14 χρονών",
          "shop_value": "12-14",
          "shop_variation_uid": "40575312-14",
          "ean": "1234567890321"
        },
        "unit_price": 17.99,
        "total_price": 35.98,
        "price_includes_vat": true,
        "island_vat_discount_applied": false,
        "ean": "1234567890123",
        "serial_numbers": null,
        "tags": [
          "plus_deal",
          "price_optimizer"
        ]
      },
      {
        "id": "3XlV8ebjxm",
        "shop_uid": "10",
        "product_name": "Smartphone 123",
        "quantity": 2,
        "unit_price": 100,
        "total_price": 200,
        "price_includes_vat": false,
        "island_vat_discount_applied": false,
        "serial_numbers": null,
        "tags": [
          "coupon_deal"
        ]
      },
      {
        "id": "ZvEKMxbxr1",
        "shop_uid": "768",
        "product_name": "AIR OPTIX COLORS MHNIAIOI",
        "quantity": 2,
        "unit_price": 25.5,
        "total_price": 51,
        "price_includes_vat": true,
        "island_vat_discount_applied": false,
        "extra_info": "Χρώμα: Πράσινο\\nΒαθμοί SPH: -6.50",
        "serial_numbers": null,
        "tags": [
          "two_plus_deal"
        ]
      }
    ],
    "created_at": "2021-06-24T13:12:29+03:00",
    "expires_at": "2021-06-25T13:12:29+03:00",
    "dispatch_until": "2021-06-28T13:12:29+03:00",
    "express": false,
    "gift_wrap": false,
    "fulfilled_by_skroutz": false,
    "fbs_delivery_note": null,
    "store_pickup": false,
    "accept_options": {
      "number_of_parcels": [
        1
      ],
      "pickup_location": [
        {
          "id": "Y5jVmgKmeX",
          "label": "Πανεπιστημίου 2, Τ.Κ. 12345, Αθήνα, Αττική"
        },
        {
          "id": "3XlV8ebjxm",
          "label": "Σταδίου 1, Τ.Κ. 12345, Αθήνα, Αττική"
        }
      ],
      "pickup_window": [
        {
          "id": 1,
          "label": "15:00 - 18:00, Πέμ 24/06/21"
        },
        {
          "id": 2,
          "label": "10:00 - 12:00, Παρ 25/06/21"
        },
        {
          "id": 3,
          "label": "12:00 - 15:00, Παρ 25/06/21"
        },
        {
          "id": 4,
          "label": "15:00 - 18:00, Παρ 25/06/21"
        },
        {
          "id": 5,
          "label": "10:00 - 12:00, Δευ 28/06/21"
        }
      ]
    },
    "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
        }
      ]
    }
  }
}

DEMO-FBS

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

  GET /merchants/ecommerce/orders/DEMO-FBS

GET https://api.skroutz.gr/merchants/ecommerce/orders/DEMO-FBS

View Response
Show Headers
Status: 200
{
  "order": {
    "code": "DEMO-FBS",
    "state": "accepted",
    "customer": {
      "id": "user1234",
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής",
        "country_code": "GR",
        "pickup_from_collection_point": false
      }
    },
    "invoice": false,
    "comments": "Παράδοση στο γραφείο",
    "courier": "CourierCenter",
    "courier_voucher": null,
    "courier_tracking_codes": [
      "123456789"
    ],
    "line_items": [
      {
        "id": "Y5jVmgKmeX",
        "shop_uid": "405753",
        "shop_variation_uid": "40575312-14",
        "product_name": "Adidas Perormance Badge of Sport Swimsuit PS/GS",
        "quantity": 2,
        "size": {
          "label": "Ηλικία",
          "value": "14 χρονών",
          "shop_value": "12-14",
          "shop_variation_uid": "40575312-14",
          "ean": "1234567890321"
        },
        "unit_price": 17.99,
        "total_price": 35.98,
        "price_includes_vat": true,
        "ean": "1234567890123",
        "serial_numbers": null
      },
      {
        "id": "3XlV8ebjxm",
        "shop_uid": "10",
        "product_name": "Smartphone 123",
        "quantity": 2,
        "unit_price": 100,
        "total_price": 200,
        "price_includes_vat": true,
        "serial_numbers": "SN12345,SN56789"
      },
      {
        "id": "ZvEKMxbxr1",
        "shop_uid": "768",
        "product_name": "AIR OPTIX COLORS MHNIAIOI",
        "quantity": 2,
        "unit_price": 25.5,
        "total_price": 51,
        "price_includes_vat": true,
        "extra_info": "Χρώμα: Πράσινο\\nΒαθμοί SPH: -6.50",
        "serial_numbers": null
      }
    ],
    "created_at": "2021-06-24T13:11:41+03:00",
    "expires_at": "2021-06-25T13:11:41+03:00",
    "dispatch_until": "2021-06-28T13:11:41+03:00",
    "express": false,
    "gift_wrap": false,
    "fulfilled_by_skroutz": true,
    "fbs_delivery_note": null,
    "store_pickup": false
  }
}

DEMO-FBS-DISPATCHED

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

  GET /merchants/ecommerce/orders/DEMO-FBS-DISPATCHED

GET https://api.skroutz.gr/merchants/ecommerce/orders/DEMO-FBS-DISPATCHED

View Response
Show Headers
Status: 200
{
  "order": {
    "code": "DEMO-FBS-DISPATCHED",
    "state": "dispatched",
    "customer": {
      "id": "user1234",
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής",
        "country_code": "GR",
        "pickup_from_collection_point": false
      }
    },
    "invoice": false,
    "comments": "Παράδοση στο γραφείο",
    "courier": "CourierCenter",
    "courier_voucher": null,
    "courier_tracking_codes": [
      "123456789"
    ],
    "line_items": [
      {
        "id": "Y5jVmgKmeX",
        "shop_uid": "405753",
        "shop_variation_uid": "40575312-14",
        "product_name": "Adidas Perormance Badge of Sport Swimsuit PS/GS",
        "quantity": 2,
        "size": {
          "label": "Ηλικία",
          "value": "14 χρονών",
          "shop_value": "12-14",
          "shop_variation_uid": "40575312-14",
          "ean": "1234567890321"
        },
        "unit_price": 17.99,
        "total_price": 35.98,
        "price_includes_vat": true,
        "ean": "1234567890123",
        "serial_numbers": null
      },
      {
        "id": "3XlV8ebjxm",
        "shop_uid": "10",
        "product_name": "Smartphone 123",
        "quantity": 2,
        "unit_price": 100,
        "total_price": 200,
        "price_includes_vat": true,
        "serial_numbers": "SN12345,SN56789"
      },
      {
        "id": "ZvEKMxbxr1",
        "shop_uid": "768",
        "product_name": "AIR OPTIX COLORS MHNIAIOI",
        "quantity": 2,
        "unit_price": 25.5,
        "total_price": 51,
        "price_includes_vat": true,
        "extra_info": "Χρώμα: Πράσινο\\nΒαθμοί SPH: -6.50",
        "serial_numbers": null
      }
    ],
    "created_at": "2021-06-24T13:11:41+03:00",
    "expires_at": "2021-06-25T13:11:41+03:00",
    "dispatch_until": "2021-06-28T13:11:41+03:00",
    "express": false,
    "gift_wrap": false,
    "fulfilled_by_skroutz": true,
    "fbs_delivery_note": "ΤΛΑΠΟ0454022",
    "store_pickup": false
  }
}

DEMO-STORE-PICKUP

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

  GET /merchants/ecommerce/orders/DEMO-STORE-PICKUP

GET https://api.skroutz.gr/merchants/ecommerce/orders/DEMO-STORE-PICKUP

View Response
Show Headers
Status: 200
{
  "order": {
    "code": "DEMO-STORE-PICKUP",
    "state": "open",
    "customer": {
      "id": "user1234",
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "street_name": "Πανεπιστημίου",
        "street_number": "4",
        "zip": "12345",
        "city": "Αθήνα",
        "region": "Αττικής",
        "country_code": "GR",
        "pickup_from_collection_point": false
      }
    },
    "invoice": false,
    "comments": "Παράδοση στο γραφείο",
    "courier": null,
    "courier_voucher": null,
    "courier_tracking_codes": [

    ],
    "line_items": [
      {
        "id": "Y5jVmgKmeX",
        "shop_uid": "405753",
        "shop_variation_uid": "40575312-14",
        "product_name": "Adidas Perormance Badge of Sport Swimsuit PS/GS",
        "quantity": 2,
        "size": {
          "label": "Ηλικία",
          "value": "14 χρονών",
          "shop_value": "12-14",
          "shop_variation_uid": "40575312-14",
          "ean": "1234567890321"
        },
        "unit_price": 17.99,
        "total_price": 35.98,
        "price_includes_vat": true,
        "ean": "1234567890123",
        "serial_numbers": null,
        "tags": [
          "plus_deal",
          "price_optimizer"
        ]
      }
    ],
    "created_at": "2021-06-24T13:08:30+03:00",
    "expires_at": "2021-06-25T13:08:30+03:00",
    "dispatch_until": null,
    "express": false,
    "gift_wrap": false,
    "fulfilled_by_skroutz": false,
    "fbs_delivery_note": null,
    "store_pickup": true,
    "accept_options": {
      "number_of_parcels": [
        1
      ],
      "pickup_location": [
        {
          "id": "Y5jVmgKmeX",
          "label": "Πανεπιστημίου 2, Τ.Κ. 12345, Αθήνα, Αττική"
        }
      ],
      "pickup_window": [

      ]
    },
    "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
        }
      ]
    }
  }
}

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, for_return, partially_delivered
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 Skroutz Last Mile, ACS, Speedex, Elta, EasyMail, DHL, Dpd, Diakinisis, Delatolas, Beinoglou, Geniki Taxydromiki 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
express Boolean   Whether the order is marked as express delivery
gift_wrap Boolean   Whether gift wrap was requested
rejection_info Object   Rejection info (available for orders rejected with other reason)
accept_options Object   Accept options (available for orders with state "open")
reject_options Object   Reject options (available for orders with state "open")
fulfilled_by_skroutz Boolean   Whether the order is fulfilled by skroutz
fbs_delivery_note String   Order's delivery note from warehouse for orders that are fulfilled by Skroutz
store_pickup Boolean   Whether the order will be picked up by the user at the store
shipping_cost Double   The order's shipping cost in euros (only available for FBM (Fulfilled By Merchant) orders)
commission Double   Order's total commission in euros
pickup_window Object   Selected Pickup window
pickup_address String   Pickup location address
number_of_parcels Integer   Number of parcels

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.phone String Phone number (only available for FBM (Fulfilled By Merchant) orders or orders with invoice.)
customer.mobile String Mobile phone number (only available for FBM (Fulfilled By Merchant) orders or orders with invoice.)

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.country_code String Address country code
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
invoice_details.vat_exclusion_representative.mobile String Representative's mobile phone number

Provided ID document type

All possible id_type values regarding the Vat exclusion representative:

ID (Provided by AADE) Skroutz value
1 ΑΤ Αστυνομική Ταυτότητα
2 ΕΣ Ελληνικός Στρατός
3 ΠΝ Πολεμικό Ναυτικό
4 ΠΑ Πολεμική Αεροπορία
5 ΕΑ Ελληνική Αστυνομία
6 ΛΣ Λιμενικό Σώμα
7 ΠΣ Πυροσβεστικό Σώμα
8 Διαβατήριο
9 ΚΑ Κέντρο Αλλοδαπών
11 Εντολέας ΦΠ
12 ΚΠ Κάρτα Παραμονής Περιορισμένης Χρονικής Διάρκειας
13 Ταυτότητα Ευρωπαϊκής Ένωσης
14 Ταυτότητα Ανιθαγενή (Ν.139/1975)
15 Ταυτότητα Ομογενούς
16 Αριθμός Κοινωνικής Ασφάλισης Η.Π.Α.
17 ΕΔΤ Πολιτικού Πρόσφυγα Υπό Αναγνώριση
18 Ειδικό Δελτίο Πολιτικού Φυγάδα
19 Άδεια Παραμονής Πρόσφυγα Ατελώς
20 Ειδικό Δελτίο Πρόσφυγα Ανθρωπιστικού Καθεστώτος
22 Πιστοποιητικό γέννησης αλλοδαπού
23 Ταυτότητα Χώρας Εκτός Ευωπαϊκής Ένωσης
24 ΑΓ Ελληνική Αγροφυλακή
25 Δελτίο Αιτούντος Διεθνή Προστασία
26 Άδεια Διαμονής Υπηκόου Τρίτης Χώρας Χωρίς Διαβατήριο
27 Άδεια Διαμονής/Δικαιούχος Διεθνούς Προστασίας

Rejection info

Name Type Description
rejection_info.reason String The rejection reason text
rejection_info.actor String The actor who performed the rejection. Possible values: skroutz, merchant

Pickup window

Name Type Description
pickup_window.from Date String in format
YYYY-MM-DDTHH:MM:SS+HH:M
Pickup window starting date/time
pickup_window.to Date String in format
YYYY-MM-DDTHH:MM:SS+HH:M
Pickup window ending date/time

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[_].shop_variation_uid String Variation ID in shop (optional for items with size)
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[_].commission Double Commission in euros: total_price * (commission_rate/100)
line_items[_].commission_rate Double Commission rate as percentage, e.g. 8.34
line_items[_].island_vat_discount_applied Boolean VAT discount applied (could be true for invoice orders, billed to customers in 5 specific Greek islands)
line_items[_].ean String EAN code of product (optional)
line_items[_].mpn String MPN code of product (optional)
line_items[_].extra_info String Additional information for item, eg. color preference or prescription details for contact lenses (optional) webhook example
line_items[_].rejection_reason String Rejection reason (possible values: limited_stock, no_stock, discontinuation, wrong_price, content_mistake)
line_items[_].return_reason String User return reason (possible values: faulty, wrong_product, withdrawal, wrong_size)
line_items[_].serial_numbers String Serial numbers for item, concatenated by ',', e.g. SN12345,SN56789
line_items[_].tags Array A list of tags that characterize the line item (optional). Supported tags: ["plus_deal", "coupon_deal", "two_plus_deal", "price_optimizer", "cc_installments"]

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
line_items[_].size.shop_variation_uid String   Variation ID in shop for an item
line_items[_].size.ean String   EAN code of variation
line_items[_].size.mpn String   MPN code of variation

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

Possible values

ID Label Requires Available Quantity
1 Εκτός αποθέματος στο κατάστημα ή στον προμηθευτή False
2 Λάθος καταχωρημένη τιμή(ες) False
4 Περιορισμένα τεμάχια True
5 To προϊόν καταργήθηκε False
6 Λάθος ταξινόμηση προϊόντος False

Tracking details option: Courier

These are the possible courier values when updating tracking details

Name Type Value
courier String acs, dhl, geniki_taxydromiki, dpd, gls