API Documentation

POST /api/v1/shipping_order

Creates a new shipping order in the database and returns a voucher to be printed and stuck on the parcel.

Instructions about the pickup date and times: The pickup date must be the date the order will be ready for pickup from the merchant location. At pickup times you can use either the morning pickup window (10:00-14:00) or the afternoon one (15:00-17:00). Please note that you can use today as a pickup date with the afternoon pickup window but only if the order is created until 14:00.

There are three supported order creation flows: Skroutz Point delivery with a preselected locker, Skroutz Point delivery where SLM selects the closest locker based on address, and home delivery to a customer-provided address.

Endpoint: POST /api/v1/shipping_order

Order creation modes:

Flow	Required destination fields	Explanation
Locker delivery with selected Skroutz Point	`skroutz_point_id`	The client has already selected a specific Skroutz Point.
Locker delivery to closest Skroutz Point	`recipient_address_text`, `recipient_zip`, `recipient_city`	The client provides area details and SLM selects the closest available Skroutz Point.
Home delivery	`recipient_street_name`, `recipient_street_number`, `recipient_city`, `recipient_zip`	The parcel is delivered to the full customer address.

Variables:

Name	Type	Explanation
customer_reference	string	The customer reference (Your internal unique identifier of the order)
is_return	boolean	Indicates if the shipment is a return (Always use false)
number_of_parcels	number	The number of parcels (Always use 1 for Skroutz Point deliveries, multiple-package orders are not supported, please spit them to more shipping orders to send them.)
pickup_date	string `("YYYY-MM-DD")`	The date of the order pickup
pickup_location_code	string	The unique code for the pickup location. It corresponds to a pre-agreed location for picking up parcels. A merchant can have multiple pickup location codes where each one corresponds to a different pickup location.
pickup_notes	string	Any additional notes for the pickup
pickup_time_from	UTC datetime	The start time of the pickup time window
pickup_time_to	UTC datetime	The end time of the pickup time window
recipient_name	string	The full name of the recipient
recipient_phone	string	The mobile phone number of the recipient
sender_phone	string	The phone number of the merchant
sender_name	string	The name of the merchant sender (optional)
skroutz_point_id	string	The ID of the chosen Skroutz Point locker from the map (Mandatory when the client has selected a locker)
recipient_address_text	string	Free-text address used to identify the closest locker (Mandatory when SLM should select the closest locker)
recipient_street_name	string	Street name of the recipient's address (Mandatory for home delivery)
recipient_street_number	string	Street number of the recipient's address (Mandatory for home delivery)
recipient_city	string	City of the recipient's address (Mandatory for home delivery and closest-locker selection)
recipient_zip	string	Zip code of the recipient's address (Mandatory for home delivery and closest-locker selection)
weight	number	The weight of the parcel
external_tracking_number	string	External partner voucher (optional)
estimated_slot_size	string	Estimated slot size where the parcel fits. Possible values: {null, 'S', 'S_SB', 'M', 'M_SB', 'L', 'L_SB', 'XL'}

Example Request Body: Locker Delivery With Selected Locker

{
  "customer_reference": "CustRef123",
  "is_return": false,
  "number_of_parcels": 1,
  "pickup_date": "2026-10-22",
  "pickup_location_code": "zbamies",
  "pickup_notes": "Απο την πλαινή πόρτα",
  "pickup_time_from": "2026-10-22T12:00:00+00:00",
  "pickup_time_to": "2026-10-22T14:00:00+00:00",
  "recipient_name": "Γιώργος Αποστολόπουλος",
  "recipient_phone": "6900000000",
  "sender_phone": "2100000000",
  "skroutz_point_id": "skroutz_demo",
  "weight": 2.5,
  "estimated_slot_size": "S_SB"
}

Example Request Body: Locker Delivery With Closest Locker Selection

{
  "customer_reference": "CustRef123",
  "is_return": false,
  "number_of_parcels": 1,
  "pickup_date": "2026-10-22",
  "pickup_location_code": "zbamies",
  "pickup_notes": "Απο την πλαινή πόρτα",
  "pickup_time_from": "2026-10-22T12:00:00+00:00",
  "pickup_time_to": "2026-10-22T14:00:00+00:00",
  "recipient_name": "Γιώργος Αποστολόπουλος",
  "recipient_phone": "6900000000",
  "sender_phone": "2100000000",
  "recipient_address_text": "Πλουτάρχου 10",
  "recipient_city": "Αθήνα",
  "recipient_zip": "10676",
  "weight": 2.5,
  "estimated_slot_size": "S_SB"
}

Example Request Body: Home Delivery

{
  "customer_reference": "CustRef123",
  "is_return": false,
  "number_of_parcels": 1,
  "pickup_date": "2026-10-22",
  "pickup_location_code": "zbamies",
  "pickup_notes": "Απο την πλαινή πόρτα",
  "pickup_time_from": "2026-10-22T12:00:00+00:00",
  "pickup_time_to": "2026-10-22T14:00:00+00:00",
  "recipient_name": "Γιώργος Αποστολόπουλος",
  "recipient_phone": "6900000000",
  "sender_phone": "2100000000",
  "recipient_street_name": "Πλουτάρχου",
  "recipient_street_number": "10",
  "recipient_city": "Αθήνα",
  "recipient_zip": "10676",
  "weight": 2.5
}

Example Response:

{
  "success": true,
  "order_id": "soid123",
  "tracking_ids": ["X84K9ZN13K0W5"]
}

GET /api/v1/shipment/track/:tracking_id

Returns tracking information on the parcel delivery and pickup.

Endpoint: GET /api/v1/shipment/track/:tracking_id

Variables:

Name	Type	Explanation
tracking_id	string	The tracking ID of the shipment

Example Response:

{
  "success": true,
  "status_description": "picked_up",
  "courier_notes": "Parcel picked up",
  "picked_up_at": "2023-06-05T12:30:00+00:00",
  "delivered_at": null,
  "updated_at": "2023-06-05T12:30:00+00:00",
  "expected_day_of_delivery": null,
  "shipping_order_id": "order123",
  "TrackingDetails": [
    {
      "created_at": "2023-06-05T12:30:00+00:00",
      "description": "Shipment was picked up",
      "notes": "Parcel collected from sender"
    }
  ]
 }

This is the exact response format returned by the GET /api/v1/shipment/track/:tracking_id endpoint.

DELETE /api/v1/shipping_order/:order_id

Cancel an order any time before it is received by the customer.

Endpoint: DELETE /api/v1/shipping_order/:order_id

Example Response:

{
  "success": true
}

GET api/v1/shipping_order/voucher/:tracking_id

Returns the voucher on pdf or base64 encoded string

Endpoint: GET api/v1/shipping_order/voucher/:tracking_id

Variables:

Name	Type	Explanation
tracking_id	string	The tracking ID of the shipment
paper_size	string	The form of the voucher to print, can be 'thermal' or 'A4'
direct_download	boolean	If it is true it returns the voucher as pdf file, else as a base64 encoded string

PUT api/v1/shipping_order/:order_id

Used to reschedule the pickup date and time window for an order. Use the same instruction for these fields as in the order creation endpoint.

Endpoint: PUT api/v1/shipping_order/:order_id

Variables:

Name	Type	Explanation
pickup_date	string`("YYYY-MM-DD")`	The date of the order pickup
pickup_time_from	UTC datetime	The start time of the pickup time window
pickup_time_to	UTC datetime	The end time of the pickup time window

Example Request Body:

{
  "pickup_date": "2023-06-19",
  "pickup_time_from": "2023-06-19T12:00:00+00:00",
  "pickup_time_to": "2023-06-19T14:00:00+00:00"
}

Example Response:

{
  "success": true,
  "order_id": "soid123",
  "tracking_ids": ["X84K9ZN13K0W5"]
}

GET /mapwidget/list_all

Returns all available lockers for the consumer to choose from.

Endpoint: GET /mapwidget/list_all

Example Response:

{
    "skroutz_points": [
      {
        "id": "sb_roma_pizza_glyfada",
        "type": "locker",
        "name": "Skroutz Point Roma Pizza Γλυφάδα (Σοφίας Βέμπο)",
        "street_name": "Σοφίας Βέμπο",
        "street_number": "33",
        "city": "Γλυφάδα",
        "zip": "16561",
        "region": "Αττική",
        "working_hours": [
          {
            "to": "24:00",
            "day": "Monday",
            "from": "12:00"
          },
          {
            "to": "24:00",
            "day": "Tuesday",
            "from": "12:00"
          },
          {
            "to": "24:00",
            "day": "Wednesday",
            "from": "12:00"
          },
          {
            "to": "24:00",
            "day": "Thursday",
            "from": "12:00"
          },
          {
            "to": "24:00",
            "day": "Sunday",
            "from": "12:00"
          }
        ],
        "indoor": true,
        "lng": 37.880232923,
        "lat": 23.758159832,
        "model": "SwipboxInfinity",
        "active": true,
        "obsolete": false,
        "swipbox_version": "v2"
      }
    ]
  }

Webhook Tracking Payload

Webhook notifications for shipment tracking use the same payload structure as the GET /api/v1/shipment/track/:tracking_id response.

Payload Structure:

{
  "status_description": "Enum",
  "courier_notes": "string | null",
  "picked_up_at": "datetime | null",
  "delivered_at": "datetime | null",
  "updated_at": "datetime",
  "expected_day_of_delivery": "datetime | null",
  "shipping_order_id": "string",
  "TrackingDetails": [
    {
      "created_at": "datetime",
      "description": "string",
      "notes": "string"
    }
  ]
}

Shipment States

status_description	Explanation
awaiting_pickup	Not yet collected from sender.
picked_up	Collected from sender.
assigned_to_courier_for_delivery	Handed off to a courier for final delivery.
delivered	Successfully delivered to recipient.
recipient_rejected	Recipient refused the parcel.
returning_to_sender	In transit back to sender.
returned_to_sender	Parcel fully returned to the sender.
attempted_delivery	Delivery was attempted but failed.
lost_or_damaged	Parcel confirmed lost or damaged.
at_locker	Parcel is stored in a locker awaiting pickup.
at_courier_store	Parcel is in a PUDO store awaiting pickup.

Tracking Details

TrackingDetails.description	Explanation
Waiting For Pickup	Parcel is registered and awaiting collection from the sender.
Shipment was assigned to courier for delivery	Parcel has been assigned to a courier for final delivery.
Shipment was picked up	Parcel was collected from the sender.
Shipment was delivered	Parcel was successfully delivered to the recipient.
Shipment was not delivered	Delivery attempt failed (generic reason).
Shipment was not delivered. Recipient rejected	Recipient explicitly refused to accept the parcel.
Order was cancelled	The shipment order has been cancelled.
Collected expired order	Courier collected an order not picked up from a locker in time.
Order was marked as lost	Parcel confirmed as lost.
Order was marked as damaged	Parcel confirmed as damaged.

API Documentation

General Instructions

Contents

API Endpoints

POST /api/v1/shipping_order

GET /api/v1/shipment/track/:tracking_id

DELETE /api/v1/shipping_order/:order_id

GET api/v1/shipping_order/voucher/:tracking_id

PUT api/v1/shipping_order/:order_id

GET /mapwidget/list_all

Webhook Info

Webhook Tracking Payload

Shipment Statuses And Tracking Details

Shipment States

Tracking Details