NAV Navbar
cURL

Introduction

Environments

Staging: 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, register to Merchant Dashboard and contact us to generate an access token for you.

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

Authorization: Token {token}

Entities

Address

Attribute Type Description
address string Address.
coordinates object 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 Name of contact person.
contact_phone string Phone number of contact person.
notes string 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.
packages Package[] Packages to be delivered.
required_recipient_age integer | null Optional. If provided, courier will ask recipient's ID card to check if the recipient is old enough to accept the delivery.

Delivery Fee Quote

Attribute Type Description
id integer ID of the quote. You will need to pass this number to submit an order.
exact_distance integer Total distance in straight lines between route points.
rounded_distance integer Exact distance rounded to the closest delivery fee level.
fee decimal A decimal number indicating delivery fee (e.g. 3.99).
valid_until datetime Date of quote expiration. Note that you can still submit an order with an expired quote and it will succeed unless delivery fee for the given route has changed.

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.
timed_out - order has timed out because courier has not been found.
payment_failed - could not charge your credit card to pay order fees.
pickup_address Address Pickup location.
deliveries Delivery[] Delivery locations.
pricing object Pricing information.
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).
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.
payment_type string Available only if restaurant mode is enabled for user. Indicates whether courier has to pay for the order at the restaurant. Accepted values: prepaid, cash.
payment_amount decimal Available only if restaurant mode is enabled for user. Order amount to be paid by courier.
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.
description string Description of the package.
insured_value decimal Package value to be insured. Available only if insurance is enabled for user.
size string Package size as {width}x{height}x{depth}, e.g. 60x30x20 in centimeters.
weight integer Package weight in grams.

Time Block

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

Endpoints

Get Delivery Fee Quote

Request Example

curl -X POST https://api-ext.ziticity.com/quote-delivery-fee/ \
-H "Content-Type: application/json" \
-H "Authorization: Token <Access Token>" \
-d '{
    "route": [
        {
            "address": "14 Gynėjų g. Vilnius"
        },
        {
            "address": "200 Kalvarijų g. Vilnius"
        }
    ]
}'

Response example

{
    "id": 1734,
    "exact_distance": 2624,
    "rounded_distance": 3000,
    "fee": "4.00",
    "valid_until": "2018-08-15T16:18:16"
}

Given a list of pickup and drop-off locations, returns a DeliveryFeeQuote object with delivery fee information. You'll need to pass ID of this object to submit an order.

Request

POST /quote-delivery-fee/

Parameter Type Description
route array An array of points in the courier's route.
First goes pickup location followed by locations for each delivery address. Note that location order matters - you won't be able to submit an order with this DeliveryFeeQuote if order of deliveries in your submission differs from DeliveryFeeQuote route.
Min. 2 points (pickup and drop-off) must be present in the route. Max. number of points is limited per user basis.
route[].address string[1000] Address formatted as <house number> <street> <post code> <city>. If you use a different format, you risk that address may be geocoded incorrectly and result in courier arriving at a wrong place or being charged incorrect delivery fee.
route[].coordinates object | null Optional. If you provide coordinates object, address string will not be geocoded and provided coordinates will be used instead.
route[].coordinates.lat float Latitude
route[].coordinates.lng float Longitude

Response

Returns DeliveryFeeQuote object.

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": "+37060012345",
        "address": "14 Gynėjų g. Vilnius",
        "notes": "34 butas, 4 aukštas"
    },
    "deliveries": [
        {
            "delivery_address": {
                "contact_name": "Petras Petraitis",
                "contact_phone": "+37067812345",
                "coordinates": {
                    "lat": 54.7132,
                    "lng": 25.2825238
                },
                "address": "200 Kalvarijų g. Vilnius"
            },
            "packages": [
                {
                    "description": "Batų dėžė",
                    "size": "10x25x20",
                    "weight": 1500
                }
            ],
            "required_recipient_age": 18
        }
    ],
    "pickup_time_block": null,
    "delivery_time_block": {
        "start": "2019-01-01T14:00:00",
        "end": "2019-01-02T15:00:00"
    },
    "delivery_fee_quote": 1734
}'

Response example

{
    "id": "d3306893-8f3d-45c0-a9e7-a7e701c68145",
    "status": "scheduled",
    "pickup_address": {
        "contact_name": "Jonas Jonaitis",
        "contact_phone": "+37060012345",
        "coordinates": {
            "lat": 54.6921309,
            "lng": 25.2642393
        },
        "address": "14 Gynėjų g. Vilnius"
    },
    "deliveries": [
        {
            "id": "d2d024ca-33ae-4cb4-9480-1fb14b60defd",
            "status": "new",
            "delivery_address": {
                "contact_name": "Petras Petraitis",
                "contact_phone": "+37067812345",
                "coordinates": {
                    "lat": 54.7132,
                    "lng": 25.2825238
                },
                "address": "200 Kalvarijų g. Vilnius"
            },
            "packages": [
                {
                    "id": "5cba987c-3868-4762-9c2d-d02d66fd7563",   
                    "status": "new",        
                    "description": "Batų dėžė",
                    "size": "10x25x20",
                    "weight": 1500
                }
            ],
            "required_recipient_age": 18
        }
    ],
    "pricing": {
        "delivery_fee": "4.00",
        "extra_cargo_fee": "0.00",
        "estimated_total": "4.00",
        "final_total": null
    },
    "pickup_time_block": null,
    "delivery_time_block": {
        "start": "2019-01-01T14:00:00",
        "end": "2019-01-02T15:00:00"
    }
}

Request

POST /orders/

Parameter Type Description
pickup_address Address Order pickup location.
deliveries array Array of drop-off points. At least a single delivery is required.
deliveries[].delivery_address Address Delivery drop-off location.
deliveries[].required_recipient_age integer | null Optional. If provided, courier will ask recipient's ID card to check if the recipient is old enough to accept the delivery.
deliveries[].packages array A list of packages. At least a single package is required.
deliveries[].packages[].description string[80] Human-friendly description of the package (e.g. round box of sweets).
deliveries[].packages[].notes string Optional. Any additional information you think it is good to provide about the package.
deliveries[].packages[].insured_value decimal Insured package value. Available only if insurance is enabled for user.
deliveries[].packages[].size string | null Package size as {width}x{height}x{depth}, e.g. 60x30x20 in centimeters.
deliveries[].packages[].weight number | null Package weight in grams.
payment_type string Available only if restaurant mode is enabled for user. Indicates whether courier has to pay for the order at the restaurant. Accepted values: prepaid, cash.
payment_amount decimal Available only if restaurant mode is enabled for user. Order amount to be paid by courier.
pickup_time_block TimeBlock| null Time window when courier is expected to arrive at the pickup location.
delivery_time_block TimeBlock| null Time window when courier is expected to deliver items to the recipient.
delivery_fee_quote number ID of previously created DeliveryFeeQuote.

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.

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": "d3306893-8f3d-45c0-a9e7-a7e701c68145",
    "status": "cancelled",
    "pickup_address": {
        "contact_name": "Jonas Jonaitis",
        "contact_phone": "+37060012345",
        "coordinates": {
            "lat": 54.6921309,
            "lng": 25.2642393
        },
        "address": "14 Gynėjų g. Vilnius"
    },
    "deliveries": [
        {
            "id": "d2d024ca-33ae-4cb4-9480-1fb14b60defd",
            "status": "new",
            "delivery_address": {
                "contact_name": "Petras Petraitis",
                "contact_phone": "+37067812345",
                "coordinates": {
                    "lat": 54.7132,
                    "lng": 25.2825238
                },
                "address": "200 Kalvarijų g. Vilnius"
            },
            "packages": [
                {
                    "id": "5cba987c-3868-4762-9c2d-d02d66fd7563",
                    "status": "new",
                    "description": "Batų dėžė",
                    "size": null,
                    "weight": null
                }
            ]
        }
    ],
    "pricing": {
        "delivery_fee": "4.00",
        "extra_cargo_fee": "0.00",
        "estimated_total": "4.00",
        "final_total": null
    },
    "pickup_time_block": null,
    "delivery_time_block": {
        "start": "2019-01-01T12:00:00",
        "end": "2019-01-02T13: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": "aaba0abf-cc4e-47d8-93aa-1e82b9538c08",
            "status": "pending",
            "pickup_address": null,
            "deliveries": [
                {
                    "id": "21704c78-64ed-4d81-89ac-d63b0dcc21d5",
                    "status": "new",
                    "delivery_address": {
                        "contact_name": "",
                        "contact_phone": "tel nr",
                        "coordinates": {
                            "lat": 54.71272190000001,
                            "lng": 25.270701299999928
                        },
                        "address": "Ozo gatvė 65, Vilnius, Lietuva"
                    },
                    "packages": [
                        {
                            "id": "5cba987c-3868-4762-9c2d-d02d66fd7563",           
                            "status": "new",
                            "description": "Batų dėžė",
                            "size": null,
                            "weight": null
                        }
                    ]
                }
            ],
            "pricing": {
                "delivery_fee": "3951.40",
                "extra_cargo_fee": "0.00",
                "estimated_total": "3951.40",
                "final_total": null
            },
            "pickup_time_block": null,
            "delivery_time_block": {
                "start": "2018-08-03T08:00:00",
                "end": "2018-08-03T08:30: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/aaba0abf-cc4e-47d8-93aa-1e82b9538c08/ \
-H "Authorization: Token <Access Token>"

Response example

{
    "id": "aaba0abf-cc4e-47d8-93aa-1e82b9538c08",
    "status": "pending",
    "pickup_address": null,
    "deliveries": [
        {
            "id": "21704c78-64ed-4d81-89ac-d63b0dcc21d5",
            "status": "new",
            "delivery_address": {
                "contact_name": "",
                "contact_phone": "tel nr",
                "coordinates": {
                    "lat": 54.71272190000001,
                    "lng": 25.270701299999928
                },
                "address": "Ozo gatvė 65, Vilnius, Lietuva"
            },
            "packages": [
                {
                    "id": "5cba987c-3868-4762-9c2d-d02d66fd7563",   
                    "status": "new",        
                    "description": "Batų dėžė",
                    "size": null,
                    "weight": null
                }
            ]
        }
    ],
    "pricing": {
        "delivery_fee": "3951.40",
        "extra_cargo_fee": "0.00",
        "estimated_total": "3951.40",
        "final_total": null
    },
    "pickup_time_block": null,
    "delivery_time_block": {
        "start": "2018-08-03T08:00:00",
        "end": "2018-08-03T08:30: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": "+37060012345",
        "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": "+37067812345",
                "coordinates": {
                    "lat": 54.7132,
                    "lng": 25.2825238
                },
                "address": "200 Kalvarijų g. Vilnius"
            },
            "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"
    },
    "delivery_fee_quote": 1734
}'

Response example

{
    "id": "9e368afb-27b5-4e7b-a541-96269ee5592e",
    "status": "scheduled",
    "pickup_address": {
        "contact_name": "Jonas Jonaitis",
        "contact_phone": "+37060012345",
        "coordinates": {
            "lat": 54.6921309,
            "lng": 25.2642393
        },
        "address": "14 Gynėjų g. Vilnius"
    },
    "deliveries": [
        {
            "id": "b7d8372d-01a7-46c9-a047-0275e2c07c19",
            "status": "new",
            "delivery_address": {
                "contact_name": "Petras Petraitis",
                "contact_phone": "+37067812345",
                "coordinates": {
                    "lat": 54.7132,
                    "lng": 25.2825238
                },
                "address": "200 Kalvarijų g. Vilnius"
            },
            "packages": [
                {
                    "id": "5cba987c-3868-4762-9c2d-d02d66fd7563",       
                    "status": "new",    
                    "description": "Batų dėžė",
                    "size": null,
                    "weight": null
                },
                {
                    "id": "c89be8be-7311-44e0-8687-931f175619ea",   
                    "status": "new",        
                    "description": "Nauja pakuotė",
                    "size": null,
                    "weight": null
                }
            ]
        }
    ],
    "pricing": {
        "delivery_fee": "4.00",
        "extra_cargo_fee": "0.00",
        "estimated_total": "4.00",
        "final_total": null
    },
    "pickup_time_block": null,
    "delivery_time_block": {
        "start": "2019-01-01T15:00:00",
        "end": "2019-01-02T16:00:00"
    }
}

Request

PUT /orders/{orderID}/

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

Attribute Type Description
deliveries[].id string | null Delivery ID if delivery is supposed to be updated. If you do not pass 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 | null 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.
delivery_fee_quote number ID of a new DeliveryFeeQuote.

Response

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

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