NAV
cURL

Introduction

Environments

Sandbox: https://api-ext.staging.ziticity.com (this is your sandbox, do whatever you want, you won't be charged).

Production: https://api-ext.ziticity.com (do not use this environment for testing as you will be charged).

Limits

API usage is limited to 300 requests per minute. Once you hit the limit, API will start responding with 429 HTTP status code (Too many requests).

Authentication

ZITICITY uses tokens to allow access to the API.

To obtain your token, create an account and sign in on an appropriate environment following the links below:

Once registered, click on your brand name in the top right corner and choose menu item "Integrations". You can generate an API token from there.

API token has to be included in every API request as an authorization header:

Authorization: Token {token}

Support

If you have any questions about our API or encounter a bug, please send us an email to .

Service types

ZITICITY provides multiple delivery services that differ in delivery speed, price and the way how your parcels are handled.

You are required to send a service type for each order in Submit Order request.

Express

Orders submitted with express service type are delivered straight from pickup address to one or more delivery addresses by a single courier.

Common use-cases:

Restrictions:

Same-day

Orders submitted with same_day service type are delivered the same or next evening (excl. Sundays).

Common use-cases:

Restrictions:

Parcel lockers

Orders submitted with parcel_locker service type are delivered to a parcel locker the same evening.

Common use-cases:

Restrictions:

Rendering a list of parcel lockers on the checkout

To retrieve a list of parcel lockers, use one of these endpoints: - List parcel lockers - List parcel lockers by proximity

To ensure good shopper experience, we suggest one of these UX solutions on your checkout:

Submitting an order to parcel locker

An example of request Submit Order endpoint to create a Parcel Locker order.

Request Example

curl -X POST https://api-ext.ziticity.com/orders/ \
-H "Content-Type: application/json" \
-H "Authorization: Token <Access Token>" \
-d '{
    "pickup_address": {
        "contact_name": "Sender name",
        "contact_phone": "+37064721776",
        "street_address": "3 Ozo g.",
        "city": "Vilnius",
        "postal_code": "08204",
        "country_code": "LT"
    },
    "deliveries": [
        {
            "parcel_locker_delivery": {
                "contact_name": "Recipient name",
                "contact_phone": "+37064721776",
                "parcel_locker_id": 91,
                "box_size": "M"
            },
            "packages": [
                {
                    "description": "#1022-1",
                    "weight": 3500
                }
            ]
        }
    ],
    "service_type": "parcel_locker"
}'

Entities

Address

Address can be provided as a text string or a breakdown of street address, city, country and a postal code.

Attribute Type Constraints Description
address string Either this or street_address + city + postal_code + country_code must be provided. Full address, e.g. "5 Gedimino st., Vilnius, LT-01234, Lithuania"
street_address string Required if address is not provided. Street address with building number, e.g. "5 Gedimino st."
city string Required if address is not provided. City.
postal_code string Required if address is not provided. Postal code.
country_code string Required if address is not provided. Two-letter country code.
coordinates object Optional Address coordinates. If you are creating an order or delivery, coordinates are optional as address will be geocoded.
coordinates.lat float Latitude.
coordinates.lng float Longitude.
contact_name string Optional Name of contact person or a company name.
contact_phone string Required Phone number of contact person.
notes string Optional Address notes (apartment number, floor, door code etc.).

Delivery

Attribute Type Description
id string Delivery ID.
status string new - delivery is created (default).
pickup - courier is picking up items.
dropoff - courier is driving to drop-off location.
completed - all of the packages were delivered or not (see statuses of individual packages).
delivery_address Address Delivery address for express and same_day service types.
parcel_locker_delivery ParcelLockerDelivery Parcel locker delivery details for parcel_locker service type.
packages Package[] Packages to be delivered.
payment_type string Indicates how a recipient pays for the packages. Accepted values:
prepaid - courier does not need to collect money
card - Courier will collect payment using bank card terminal. Available only for same_day service type.
payment_amount decimal The amount to be collected from the recipient in selected payment_type.
has_alcohol boolean If alcoholic drinks are being delivered, courier will check recipient's age upon delivery.
has_energy_drinks boolean If energy drinks are being delivered, courier will check recipient's age upon delivery.
has_prescription_medicine boolean If prescription medicine is being delivered, courier will check recipient's age upon delivery and will verify if the recipient's name matches what is provided as delivery contact.
proof_of_delivery object Contains recipient delivery information after delivery is completed. Requires this feature to be turned on by ZITICITY.
proof_of_delivery.recipient_name string Name of the person who signed that he received the delivery.
proof_of_delivery.signature_image_url string URL of PNG image with recipient's signature.

Order

Attribute Type Description
id string Order ID.
status string scheduled - order is scheduled.
pending - waiting until courier accepts the order.
accepted - order is accepted, but courier is not working on it.
in_progress - courier is working on the order, look at delivery statuses for more information.
completed - order is completed, all the deliveries are finalized.
cancelled - order has been cancelled by user or ZITICITY.
pickup_address Address Pickup location.
deliveries Delivery[] Deliveries.
pricing OrderPricing Pricing information.
courier object Courier information. Attribute is available only while order is in accepted or in_progress status.
courier.short_name string Courier's name.
courier.phone string Courier's phone number.
courier.location object Courier real-time location. Available only when order status is in_progress.
courier.location.lat float Courier address latitude.
courier.location.lng float Courier address longitude.
pickup_eta datetime | null Experimental. Available only while courier is going to the pickup location and the order is first in the queue. Property might be not available or value might be null otherwise.
pickup_time_block TimeBlock | null Pickup time window.
delivery_time_block TimeBlock | null Delivery time window.

Package

Attribute Type Description
id string Package ID.
status string new - package is created.
picked_up - package was picked up for drop-off.
pickup_failed - package wasn't picked up.
delivered - package was handed over to the recipient.
delivery_failed - package was not delivered.
returned - package was returned to the sender.
description string Description of the package.
notes string Additional notes about the package
insured_value decimal Package value to be insured. Available only if insurance is enabled for user.
weight integer Package weight in grams.
thermal_mode integer Optional

Parcel Locker Delivery

Attribute Type Description
contact_name string Recipient's full name.
contact_phone string Recipient's phone number.
contact_email string Recipient's email.
parcel_locker ParcelLocker Parcel locker selected for delivery.
box_size string | null A parcel locker's box size that is sufficiently large to contain the package. Valid values: XS/S/M/L/XL.

Time Block

Attribute Type Description
start datetime Start of time window.
end datetime End of time window.

Parcel Locker

Attribute Type Description
id number Parcel locker ID
name string Name of parcel locker
label string Pretty label to display in the checkout, e.g. in a dropdown.
address dict Address
address.street_address string
address.city string
address.country string A 2-letter ISO country code.
address.postal_code string
address.coordinates object
address.coordinates.lat float Latitude.
address.coordinates.lng float Longitude.
address.notes string Additional instructions for the recipient how to locate the locker.
available_box_sizes string[] An array of available box sizes (XS, S, M, L, XL).

Order Pricing

Attribute Type Description
pricing.cod_fee decimal Fee for payment collection on delivery service. Available if payment collection on delivery is enabled for your account.
pricing.delivery_fee decimal Delivery fee.
pricing.insurance_fee decimal Insurance fee for all the insured packages. Available only if insurance is enabled for user.
pricing.extra_cargo_fee decimal Additional fee applied to orders with larger than standard or heavier packages.
pricing.estimated_total decimal Estimated total.
pricing.final_total decimal | null Final total (available after order is completed).

Endpoints

Get Available Service Types

Request Example

curl -X POST https://api-ext.ziticity.com/available-service-types/ \
-H "Content-Type: application/json" \
-H "Authorization: Token <Access Token>" \
-d '{
    "pickups": [
        {
            "pickup_address": {
                "street_address": "Skapo g. 5",
                "city": "Vilnius",
                "postal_code": "01122",
                "country_code": "LT"
            }
        }
    ],
    "deliveries": [
        {
            "delivery_address": {
                "street_address": "Skapo g. 5",
                "city": "Vilnius",
                "postal_code": "01122",
                "country_code": "LT"
            },
            "number_of_packages": 3,
            "total_weight_grams": 1000,
            "collect_payment_on_delivery": {
                "payment_type": "card",
                "payment_amount": 1.00
            }
        }
    ]
}'

Response example

{
    "express": {
        "available": false,
        "pricing": null
    },
    "same_day": {
        "available": false,
        "pricing": {
            "delivery_fee": 4.64,
            "cargo_fee": 0.0,
            "cod_fee": 1.02,
            "insurance_fee": 0.0
        }
    }
}

Given a partial order information, returns available service types and their costs.

Request

POST /available-service-types/

Parameter Type Contraints Description
pickups array Required An array of pickups. Must always have a single element.
pickups[].pickup_address Address Required Pickup location.
deliveries array Required An array of deliveries.
deliveries[].delivery_address Address Required Delivery location
deliveries[].number_of_packages integer Required Total number of packages. Min value: 1.
deliveries[].total_weight_grams integer Optional Total weight of all packages in the delivery in grams, e.g. 3.5 kg is 3500 grams.
deliveries[].insured_value decimal Optional Insured value of all items in the delivery. Available for selected merchants. Might incur additional charges.
deliveries[].collect_payment_on_delivery dict Optional
deliveries[].collect_payment_on_delivery.payment_type string Required Indicates how a recipient pays for the delivery. Accepted values:
card - Courier will collect payment using bank card terminal. Not available for Express Service Type.
deliveries[].collect_payment_on_delivery.payment_amount decimal Required Amount to be collected.

Response

Returns availability for each service type.

Parameter Type Description
express/same_day object Service type availability options
<service_type>.available bool Is service type available?
<service_type>.pricing object Pricing
<service_type>.pricing.cod_fee decimal Fee for payment collection on delivery service.
<service_type>.pricing.delivery_fee decimal Delivery fee.
<service_type>.pricing.insurance_fee decimal Insurance fee for all the insured packages. Available only if insurance is enabled for user.
<service_type>.pricing.extra_cargo_fee decimal Additional fee applied to orders with larger than standard or heavier packages.

Submit Order

Request Example

curl -X POST https://api-ext.ziticity.com/orders/ \
-H "Content-Type: application/json" \
-H "Authorization: Token <Access Token>" \
-d '{
    "pickup_address": {
        "contact_name": "Jonas Jonaitis",
        "contact_phone": "+37064721776",
        "address": "14 Gynėjų st, Vilnius, Lithuania",
        "notes": "Apt 34, 4th floor"
    },
    "deliveries": [
        {
            "delivery_address": {
                "contact_name": "Petras Petraitis",
                "contact_phone": "+37064721776",
                "coordinates": {
                    "lat": 54.7132,
                    "lng": 25.2825238
                },
                "address": "200 Kalvarijų st, Vilnius, Lithuania"
            },
      "payment_type": "prepaid",
      "payment_amount": "50.00",
            "packages": [
                {
                    "description": "Box #123",
          "notes": "A pair of shoes",
                    "weight": 1500
                }
            ]
        }
    ],
    "service_type": "express",
    "pickup_time_block": null,
    "delivery_time_block": {
        "start": "2019-01-01T14:00:00",
        "end": "2019-01-02T15:00:00"
    }
}'

Response example

{
  "id": "e4746538-caad-4b2c-9572-56a4b15a90d9",
  "status": "scheduled",
  "pickup_address": {
    "contact_name": "Jonas Jonaitis",
    "contact_phone": "+37064721776",
    "notes": "Apt 34, 4th floor",
    "coordinates": {
      "lat": 54.692131,
      "lng": 25.2642393
    },
    "address": "14 Gynėjų st, Vilnius, Lithuania"
  },
  "deliveries": [
    {
      "id": "cb79c2f5-957d-4bc5-9e92-f874d6843291",
      "status": "new",
      "delivery_address": {
        "contact_name": "Petras Petraitis",
        "contact_phone": "+37064721776",
        "notes": "",
        "coordinates": {
          "lat": 54.7132,
          "lng": 25.2825238
        },
        "address": "200 Kalvarijų st, Vilnius, Lithuania"
      },
      "proof_of_delivery": null,
      "packages": [
        {
          "id": "aace4dbb-8370-4b8f-a834-29d5b08027ad",
          "status": "new",
          "description": "Box #123",
          "notes": "A pair of shoes",
          "insured_value": null,
          "weight": 1500,
          "thermal_mode": null,
          "tracking_number": "Z-NBW4-UT"
        }
      ],
      "tracking_url": "https://tracking.staging.ziticity.com/Z-NBW4",
      "feedback": null,
      "payment_amount": "50.00",
      "payment_type": "prepaid",
      "has_alcohol": false,
      "has_energy_drinks": false,
            "has_prescription_medicine": false
    }
  ],
  "courier": null,
  "pricing": {
    "cod_fee": "0.00",
    "insurance_fee": "0.00",
    "delivery_fee": "6.39",
    "extra_cargo_fee": "0.00",
    "estimated_total": "6.39",
    "final_total": null
  },
    "service_type": "express",
  "pickup_time_block": null,
  "delivery_time_block": {
    "start": "2019-01-01T14:00:00",
    "end": "2019-01-02T15:00:00"
  }
}

Request

POST /orders/

Parameter Type Constraints Description
pickup_address Address Required Pickup location.
deliveries array Required An array of deliveries. At least a single delivery is required.
deliveries[].delivery_address Address Required for express and same_day service types
deliveries[].parcel_locker_delivery object Required for parcel_locker service type
deliveries[].parcel_locker_delivery.contact_name string Required Recipient's full name.
deliveries[].parcel_locker_delivery.contact_phone string Required Recipient's phone number. Make sure that it is valid as we will send an SMS with an unlock PIN code to this number.
deliveries[].parcel_locker_delivery.contact_email string Optional Recipient's email.
deliveries[].parcel_locker_delivery.parcel_locker_id number Required ID of a selected parcel locker.
deliveries[].parcel_locker_delivery.box_size string Optional A parcel locker's box size that is sufficiently large to contain the package. Valid values: XS/S/M/L/XL.
deliveries[].payment_type string Optional Indicates how a recipient pays for the packages. Accepted values:
prepaid - courier does not need to collect money
card - Courier will collect payment using bank card terminal. Not available for express and parcel_locker service types.
deliveries[].payment_amount decimal Optional The amount to be collected from the recipient in selected payment_type.
deliveries[].has_alcohol boolean Optional (default false) Set to true if alcoholic drinks are being delivered. Courier will check recipient's age upon delivery. Not available for parcel_locker service type.
deliveries[].has_energy_drinks boolean Optional (default false) Set to true if energy drinks are being delivered. Courier will check recipient's age upon delivery. Not available for parcel_locker service type.
deliveries[].has_prescription_medicine boolean Optional (default false) Set to true if prescription medicine is being delivered. Courier will check recipient's age upon delivery and will verify if the recipient's name matches what is provided as delivery contact. Not available for parcel_locker service type.
deliveries[].packages array Required An array of packages. At least a single package is required.
deliveries[].packages[].description string[80] Required Package identifier or description. Courier will see this information and you have to be able to identify the package by this text.
deliveries[].packages[].notes string Optional Any additional information you think it is good to provide about the package (e.g. contents).
deliveries[].packages[].insured_value decimal Optional Insured package value. Available only if insurance is enabled for user.
deliveries[].packages[].weight number Optional Package weight in grams.
deliveries[].packages[].thermal_mode number Optional Thermal mode. Additional service, terms needs to be agreed separately. Accepted values: null - no thermal mode is needed, 1 - temperature: 15-25 Celsius, 2 - temperature: 2-8 Celsius. Not available for parcel_locker service type.
service_type string Required Available values:
- express
- same_day
- parcel_locker

Read more about service types here.
pickup_time_block TimeBlock Optional Time window when courier is expected to arrive at the pickup location. For express service type it should be a one-hour wide time slot. For same_day and parcel_locker service types, this has to be a time slot pre-agreed with ZITICITY. If an invalid value is provided, it is overriden with the next available time slot.
delivery_time_block TimeBlock Optional Time window when courier is expected to deliver items to the recipient. If neither pickup_time_block, nor delivery_time_block is provided, courier will arrive ASAP to deliver the packages straight to the recipient. Available for express service type only.

Response

If order has been created successfully, API returns Order object with status code 201 (Created).

Generate Shipping Labels

Request Example

curl -X POST https://api-ext.ziticity.com/orders/aaba0abf-cc4e-47d8-93aa-1e82b9538c08/generate-shipping-labels/ \
-H "Authorization: Token <Access Token>"

Request

POST /orders/{orderID}/generate-shipping-labels/

This endpoint is available only to selected users.

Response

Returns a PDF file with a shipping label on each page for each package.

Bulk Generate Shipping Labels

Request Example

curl -X POST https://api-ext.ziticity.com/orders/generate-shipping-labels/ \
-H "Authorization: Token <Access Token>" \
-H "Content-Type: application/json" \
-d '{
    "orders": [
        "caeb1d9f-6d77-40ee-f1c9-bb297b1965a5",
        "776c3c22-t850-4b88-aeb4-45fe63ad1355"
    ]
}'

Request

POST /orders/generate-shipping-labels/

Parameter Type Description
orders array An array of order ids to get shipping labels for

This endpoint is available only to selected users.

Response

Returns a PDF file with a shipping label on each page for each package.

Cancel Order

Request Example

curl -X POST https://api-ext.ziticity.com/orders/d3306893-8f3d-45c0-a9e7-a7e701c68145/cancel/ \
-H "Authorization: Token <Access Token>"

Response example

{
  "id": "e4746538-caad-4b2c-9572-56a4b15a90d9",
  "status": "cancelled",
  "pickup_address": {
    "contact_name": "Jonas Jonaitis",
    "contact_phone": "+37064721776",
    "notes": "Apt 34, 4th floor",
    "coordinates": {
      "lat": 54.692131,
      "lng": 25.2642393
    },
    "address": "14 Gynėjų st, Vilnius, Lithuania"
  },
  "deliveries": [
    {
      "id": "cb79c2f5-957d-4bc5-9e92-f874d6843291",
      "status": "new",
      "delivery_address": {
        "contact_name": "Petras Petraitis",
        "contact_phone": "+37064721776",
        "notes": "",
        "coordinates": {
          "lat": 54.7132,
          "lng": 25.2825238
        },
        "address": "200 Kalvarijų st, Vilnius, Lithuania"
      },
      "proof_of_delivery": null,
      "packages": [
        {
          "id": "aace4dbb-8370-4b8f-a834-29d5b08027ad",
          "status": "new",
          "description": "Box #123",
          "notes": "A pair of shoes",
          "insured_value": null,
          "weight": 1500,
          "tracking_number": "Z-NBW4-UT"
        }
      ],
      "tracking_url": null,
      "feedback": null,
      "payment_amount": "50.00",
      "payment_type": "prepaid",
      "required_recipient_age": null,
      "has_alcohol": false,
      "has_energy_drinks": false,
            "has_prescription_medicine": false
    }
  ],
  "courier": null,
  "pricing": {
    "cod_fee": "0.00",
    "insurance_fee": "0.00",
    "delivery_fee": "0.00",
    "extra_cargo_fee": "0.00",
    "estimated_total": "0.00",
    "final_total": "0.00"
  },
  "pickup_time_block": null,
  "delivery_time_block": {
    "start": "2019-01-01T14:00:00",
    "end": "2019-01-02T15:00:00"
  }
}

Order can be cancelled while in either scheduled or pending status. Trying to cancel an order when it is in any other status will result in 409 (Conflict) response.

Request

POST /orders/{orderID}/cancel/

Response

Returns Order object with status code 200 (OK).

List Orders

Request Example

curl https://api-ext.ziticity.com/orders/ \
-H "Authorization: Token <Access Token>"

Response example

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
          "id": "36abf830-8751-418e-9fc6-1ac4caee3929",
          "status": "scheduled",
          "pickup_address": {
            "contact_name": "Jonas Jonaitis",
            "contact_phone": "+37064721776",
            "notes": "Apt 34, 4th floor",
            "coordinates": {
              "lat": 54.692131,
              "lng": 25.2642393
            },
            "address": "14 Gynėjų st, Vilnius, Lithuania"
          },
          "deliveries": [
            {
              "id": "de4d910e-4d11-4717-8add-b2316eaa7612",
              "status": "new",
              "delivery_address": {
                "contact_name": "Petras Petraitis",
                "contact_phone": "+37064721776",
                "notes": "",
                "coordinates": {
                  "lat": 54.7132,
                  "lng": 25.2825238
                },
                "address": "200 Kalvarijų st, Vilnius, Lithuania"
              },
              "proof_of_delivery": null,
              "packages": [
                {
                  "id": "2a36fb2a-c6fa-45a8-a2a1-a998ff3c2921",
                  "status": "new",
                  "description": "Box #123",
                  "notes": "A pair of shoes",
                  "insured_value": null,
                  "weight": 1500,
                  "size_preset": "M",
                  "tracking_number": "Z-ZDWW-47"
                }
              ],
              "tracking_url": "https://tracking.staging.ziticity.com/Z-ZDWW",
              "feedback": null,
              "payment_amount": "50.00",
              "payment_type": "prepaid",
              "has_alcohol": false,
              "has_energy_drinks": false
            }
          ],
          "courier": null,
          "pricing": {
            "cod_fee": "0.00",
            "insurance_fee": "0.00",
            "delivery_fee": "6.39",
            "extra_cargo_fee": "0.00",
            "estimated_total": "6.39",
            "final_total": null
          },
          "pickup_time_block": null,
          "delivery_time_block": {
            "start": "2019-01-01T14:00:00",
            "end": "2019-01-02T15:00:00"
          }
        }
    ]
}

Returns all orders.

Request

GET /orders/

Response

Attribute Type Description
count integer Total count of orders.
next string | null Next page URL
previous string | null Previous page URL
results Order[] Array of orders

Get Order by ID

Request Example

curl https://api-ext.ziticity.com/orders/36abf830-8751-418e-9fc6-1ac4caee3929/ \
-H "Authorization: Token <Access Token>"

Response example

{
  "id": "36abf830-8751-418e-9fc6-1ac4caee3929",
  "status": "scheduled",
  "pickup_address": {
    "contact_name": "Jonas Jonaitis",
    "contact_phone": "+37064721776",
    "notes": "Apt 34, 4th floor",
    "coordinates": {
      "lat": 54.692131,
      "lng": 25.2642393
    },
    "address": "14 Gynėjų st, Vilnius, Lithuania"
  },
  "deliveries": [
    {
      "id": "de4d910e-4d11-4717-8add-b2316eaa7612",
      "status": "new",
      "delivery_address": {
        "contact_name": "Petras Petraitis",
        "contact_phone": "+37064721776",
        "notes": "",
        "coordinates": {
          "lat": 54.7132,
          "lng": 25.2825238
        },
        "address": "200 Kalvarijų st, Vilnius, Lithuania"
      },
      "proof_of_delivery": null,
      "packages": [
        {
          "id": "2a36fb2a-c6fa-45a8-a2a1-a998ff3c2921",
          "status": "new",
          "description": "Box #123",
          "notes": "A pair of shoes",
          "insured_value": null,
          "weight": 1500,
          "tracking_number": "Z-ZDWW-47"
        }
      ],
      "tracking_url": "https://tracking.staging.ziticity.com/Z-ZDWW",
      "feedback": null,
      "payment_amount": "50.00",
      "payment_type": "prepaid",
      "has_alcohol": false,
      "has_energy_drinks": false,
            "has_prescription_medicine": false
    }
  ],
  "courier": null,
  "pricing": {
    "cod_fee": "0.00",
    "insurance_fee": "0.00",
    "delivery_fee": "6.39",
    "extra_cargo_fee": "0.00",
    "estimated_total": "6.39",
    "final_total": null
  },
  "pickup_time_block": null,
  "delivery_time_block": {
    "start": "2019-01-01T14:00:00",
    "end": "2019-01-02T15:00:00"
  }
}

Retrieve order by ID.

Request

GET /orders/{orderID}/

Response

Returns Order object with status code 200 (OK).

Update Scheduled Order

Request Example

curl -X PUT https://api-ext.ziticity.com/orders/e83b6d43-7ac3-4f06-83be-0a051e2b4ac9/ \
-H "Content-Type: application/json" \
-H "Authorization: Token <Access Token>" \
-d '{
    "pickup_address": {
        "contact_name": "Jonas Jonaitis",
        "contact_phone": "+37064721776",
        "coordinates": {
            "lat": 54.6921309,
            "lng": 25.2642393
        },
        "address": "14 Gynėjų g. Vilnius"
    },
    "deliveries": [
        {
            "id": "b7d8372d-01a7-46c9-a047-0275e2c07c19",
            "delivery_address": {
                "contact_name": "Petras Petraitis",
                "contact_phone": "+37064721776",
                "coordinates": {
                    "lat": 54.7132,
                    "lng": 25.2825238
                },
                "address": "200 Kalvarijų g. Vilnius"
            },
            "payment_type": "prepaid",
      "payment_amount": "50.00",
            "packages": [
                {
                    "id": "5cba987c-3868-4762-9c2d-d02d66fd7563",           
                    "description": "Batų dėžė"
                },
                {
                    "description": "Nauja pakuotė"
                }
            ]
        }
    ],
    "pickup_time_block": null,
    "delivery_time_block": {
        "start": "2019-01-01T15:00:00",
        "end": "2019-01-02T16:00:00"
    }
}'

Response example

{
  "id": "36abf830-8751-418e-9fc6-1ac4caee3929",
  "status": "pending",
  "pickup_address": {
    "contact_name": "Jonas Jonaitis",
    "contact_phone": "+37064721776",
    "notes": "Apt 34, 4th floor",
    "coordinates": {
      "lat": 54.692131,
      "lng": 25.2642393
    },
    "address": "14 Gynėjų st, Vilnius, Lithuania"
  },
  "deliveries": [
    {
      "id": "de4d910e-4d11-4717-8add-b2316eaa7612",
      "status": "new",
      "delivery_address": {
        "contact_name": "Petras Petraitis",
        "contact_phone": "+37064721776",
        "notes": "",
        "coordinates": {
          "lat": 54.7132,
          "lng": 25.2825238
        },
        "address": "200 Kalvarijų st, Vilnius, Lithuania"
      },
      "proof_of_delivery": null,
      "packages": [
        {
          "id": "2a36fb2a-c6fa-45a8-a2a1-a998ff3c2921",
          "status": "new",
          "description": "Box #123",
          "notes": "A pair of shoes",
          "insured_value": null,
          "weight": 1500,
          "tracking_number": "Z-ZDWW-47"
        }
      ],
      "tracking_url": "https://tracking.staging.ziticity.com/Z-ZDWW",
      "feedback": null,
      "payment_amount": "50.00",
      "payment_type": "prepaid",
      "has_alcohol": false,
      "has_energy_drinks": false,
            "has_prescription_medicine": false
    }
  ],
  "courier": null,
  "pricing": {
    "cod_fee": "0.00",
    "insurance_fee": "0.00",
    "delivery_fee": "6.39",
    "extra_cargo_fee": "0.00",
    "estimated_total": "6.39",
    "final_total": null
  },
  "pickup_time_block": null,
  "delivery_time_block": {
    "start": "2019-01-01T14:00:00",
    "end": "2019-01-02T15:00:00"
  }
}

Request

PUT /orders/{orderID}/

Request data is the same as for submit order request, with some exceptions:

Attribute Type Constraints Description
deliveries[].id string Optional Delivery ID if delivery is supposed to be updated. If you do not pass a delivery ID, new delivery will be created. If you do not send existing deliveries with update request, deliveries will be deleted.
deliveries[].packages[].id string Optional If package ID is not provided, a new package is created. If you do not send existing packages with update request, packages will be deleted.

Response

Returns updated Order object with status code 200 (OK).

If order status is not scheduled, responds with status code 409 (Conflict).

Tracking Events

You can get tracking events that occurred in a specific time period to specific or all of your deliveries using this endpoint.

Note that this API returns package events that occurred after 2021-06-03.

Request Example

curl -X GET https://api-ext.ziticity.com/package-events/ \
-H "Content-Type: application/json" \
-H "Authorization: Token <Access Token>"

Response example

{
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
        {
            "package": "Z-JPKVY-KE",
            "event_type": "collected",
            "timestamp": "2021-05-13T16:02:11",
            "message": "Courier collected package"
        },
        {
            "package": "Z-JPKVY-KE",
            "event_type": "collecting",
            "timestamp": "2021-05-13T16:02:11",
            "message": "Courier arrived at pick-up address"
        },
        {
            "package": "Z-JPKVY-KE",
            "event_type": "en_route_pickup",
            "timestamp": "2021-05-13T16:02:11",
            "message": "Courier en route to collect package"
        },
        {
            "package": "Z-JPKVY-KE",
            "event_type": "registered",
            "timestamp": "2021-05-13T16:02:11",
            "message": "Package was created"
        }
    ]
}

Request

GET /package-events/

Accepted Query Params

Query Parameter Description Value Type
limit pagination limit integer
offset pagination offset integer
from_datetime filter events from datetime YYYY-mm-ddTHH:MM:SS
to_datetime filter events to datetime YYYY-mm-ddTHH:MM:SS
event_type filter events by type string, see available event types below
packages comma separated package tracking numbers eg. Z-1234-ZZ,Z-1235-ZZ
deliveries comma separated delivery tracking numbers eg. Z-1234,Z-1235
latest filter only the latest package event boolean

Response

Returns all package events matching query params or all package events if no query params given.

Parameter Type Description
package string package tracking number
event_type string code relating to the package event
timestamp string when package event occurred
message string message relating to the package event

Event Types

Event Description
registered Package registered on ZITICITY system
cancelled Order cancelled
en_route_pickup Courier started travelling to pick-up location
collecting Courier arrived at pick-up location
collection_failed Courier unable to pick up package
collected Courier collected the package
arrived_at_hub Package arrived at ZITICITY delivery hub
out_for_delivery Courier has package for delivery on route
delivery_failed Courier failed to deliver package
delivered Courier delivered package to home
delivered_to_locker Courier delivered package to parcel locker
recipient_collected_from_locker Recipient collected the package from parcel locker
returned Courier returned package

List parcel lockers

Returns a list of available parcel lockers to be displayed on your store's checkout. Results are ordered alphabetically.

Request Example

curl https://api-ext.ziticity.com/parcel-lockers/ \
-H "Content-Type: application/json" \
-H "Authorization: Token <Access Token>"

Response example

[
  {
    "id": 91,
    "name": "LIDL",
    "label": "Kaunas, A. Juozapavičiaus pr. 125 (LIDL, LP Express)",
    "address": {
      "street_address": "A. Juozapavičiaus pr. 125",
      "city": "Kaunas",
      "country": "LT",
      "postal_code": "45267",
      "coordinates": {
        "lat": 54.878781,
        "lng": 23.932774
      },
      "notes": "Terminalas yra lauke, matomas iš prekybos centro automobilių stovėjimo aikštelės. "
    },
    "available_box_sizes": [
      "XS",
      "S",
      "M",
      "L",
      "XL"
    ]
  }
]

Request

GET /parcel-lockers/

Response

An array of ParcelLocker objects.

The result is not supposed to change frequently, therefore we suggest caching it for 24 hours instead of polling our API on every checkout load.

List parcel lockers by proximity

Returns a list of available parcel lockers to be displayed on your store's checkout ordered by proximity to the provided address.

Request Example

curl -X POST https://api-ext.ziticity.com/parcel-lockers/order-by-proximity/ \
-H "Content-Type: application/json" \
-H "Authorization: Token <Access Token>" \
-d '{
  "street_address": "3 Ozo g.",
  "city": "Vilnius",
  "postal_code": "08204",
  "country_code": "LT"
}'

Response example

[
  {
    "id": 91,
    "name": "LIDL",
    "label": "Kaunas, A. Juozapavičiaus pr. 125 (LIDL, LP Express)",
    "address": {
      "street_address": "A. Juozapavičiaus pr. 125",
      "city": "Kaunas",
      "country": "LT",
      "postal_code": "45267",
      "coordinates": {
        "lat": 54.878781,
        "lng": 23.932774
      },
      "notes": "Terminalas yra lauke, matomas iš prekybos centro automobilių stovėjimo aikštelės. "
    },
    "available_box_sizes": [
      "XS",
      "S",
      "M",
      "L",
      "XL"
    ],
    "distance": 1323
  }
]

Request

POST /parcel-lockers/order-by-proximity/

Parameter Type Constraints Description
street_address string Required Street address with building number, e.g. "5 Gedimino st."
city string Required
postal_code string Required
country_code string Required Two-letter country code.
coordinates object Optional If not provided, we will try to geocode the address. If geocoding fails, the request will respond with status code 400.
coordinates.lat float Required Latitude.
coordinates.lng float Required Longitude.

Response

An array of ParcelLocker objects. An additional distance attribute is added to each parcel locker that denotes the distance in meters.

Note: this endpoint might respond with a status code 400 if the provided address cannot be geocoded. As a fallback, you should use List parcel lockers endpoint.

cURL