# Widget API
Documentation for Store Pickup + Delivery by Zapiet
{% content-ref url="/pages/-MFAbFDAYwMfJlXVk97Q" %}
[Reference](/reference/store-pickup)
{% endcontent-ref %}
# Authentication
Requests should include the Shopify store's Zapiet API key as a query parameter named "api\_key". Store Pickup + Delivery -> Settings -> Developer.
```
GET https://api-us.zapiet.com/v1.0/locations?api_key=API_KEY
```
# Base url
```
https://api.zapiet.com/v1.0/
```
We are currently migrating all merchants to our api-us.zapiet.com region. This region provides high-availability infrastructure and other significant performance improvements over our legacy endpoints.
# Store pickup
# Locations
## Get pickup locations
`POST` `https://api.zapiet.com/v1.0/pickup/locations`
This endpoint will return an array of eligible pickup locations.
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | ----------------------------------------------------------------------- |
| page | number | Used for pagination. |
| limit | number | Number of locations to return in the response. Default 10. Maximum 200. |
| shop\* | string | The merchant's myshopify.com store url. |
#### Request Body
| Name | Type | Description |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| geoSearchQuery | string | Returns locations in distance order from the customer. If no value is provided, we will return locations in the order specified within the app. |
| shoppingCart | string | The contents of the customer's shopping cart. If no value is provided, we will not check inventory levels or product availability. |
{% tabs %}
{% tab title="200 Locations successfully retrieved." %}
```json
{
"locations": [{
"id": 1,
"external_id": "72950677728",
"distance": null,
"company_name": "Zapiet UK",
"address_line_1": "Buckingham Palace",
"address_line_2": null,
"city": "Westminster",
"postal_code": "SW1A 1AA",
"region": "London",
"country": "United Kingdom",
"latitude": 51.501009,
"longitude": -0.141588,
"timezone": "Europe\/London",
"custom_attribute_1": null,
"custom_attribute_2": null,
"custom_attribute_3": null,
"date_picker_enabled": true,
"time_picker_enabled": true,
"opening_hours": {
"monday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"tuesday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"wednesday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"thursday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"friday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"saturday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"sunday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
}
},
"more_information": null,
"limits_enabled": null
}],
"pagination": {
"total": 1,
"per_page": 10,
"current_page": 1,
"total_pages": 0,
"last_page": 1,
"next_page_url": null,
"prev_page_url": null,
"from": 1,
"to": 1
}
}
```
{% endtab %}
{% endtabs %}
### Pickup available
{% tabs %}
{% tab title="Request" %}
```javascript
{
"geoSearchQuery": "90210",
"shoppingCart": [
{
"variant_id": 9226255761451,
"product_id": 852798275627,
"quantity": 5
},
{
"variant_id": 9226255761452,
"product_id": 852798275628,
"quantity": 2
}
]
}
```
{% endtab %}
{% tab title="Response" %}
```javascript
{
"locations": [{
"id": 1,
"distance": null,
"company_name": "Zapiet UK",
"address_line_1": "Buckingham Palace",
"address_line_2": null,
"city": "Westminster",
"postal_code": "SW1A 1AA",
"region": "London",
"country": "United Kingdom",
"latitude": 51.501009,
"longitude": -0.141588,
"timezone": "Europe\/London",
"custom_attribute_1": null,
"custom_attribute_2": null,
"custom_attribute_3": null,
"date_picker_enabled": true,
"time_picker_enabled": true,
"opening_hours": {
"monday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"tuesday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"wednesday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"thursday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"friday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"saturday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
},
"sunday": {
"opens": "09:00",
"closes": "18:00",
"closed": false
}
},
"more_information": null,
"limits_enabled": null
}],
"pagination": {
"total": 1,
"per_page": 10,
"current_page": 1,
"total_pages": 0,
"last_page": 1,
"next_page_url": null,
"prev_page_url": null,
"from": 1,
"to": 1
}
}
```
{% endtab %}
{% endtabs %}
### Pickup not available
If no pickup locations are found, we will return an empty array.
```javascript
{
"locations": []
}
```
# Dates
## Get pickup dates and times
`POST` `https://api.zapiet.com/v1.0/pickup/locations/:locationId/calendar`
This endpoint allows you to fetch calendar rules for a specific location
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------ | ----------------------------- |
| locationId\* | string | The ID of the Zapiet location |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------- |
| shop\* | string | The myshopify.com store url |
#### Request Body
| Name | Type | Description |
| ------------ | ------ | ---------------------------------------------- |
| shoppingCart | string | The contents of the customers shopping basket. |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"minDateTime": "2021-05-13 09:00:00",
"minDate": "2021-05-13",
"maxDate": null,
"minTime": ["09", "00"],
"maxTime": ["17", "00"],
"disabled": [],
"interval": 60,
"daysOfWeek": {
"sunday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"monday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"tuesday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"wednesday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"thursday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"friday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"saturday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
}
},
"timezone": "America\/New_York"
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Request" %}
```javascript
{
"shoppingCart": [
{
"variant_id": 9226255761451,
"product_id": 852798275627,
"quantity": 5
},
{
"variant_id": 9226255761452,
"product_id": 852798275628,
"quantity": 2
}
]
}
```
{% endtab %}
{% tab title="Response" %}
```javascript
{
"minDateTime": "2021-05-13 09:00:00",
"minDate": "2021-05-13",
"maxDate": null,
"minDateSlots" : [],
"minTime": ["09", "00"],
"maxTime": ["17", "00"],
"disabled": [],
"interval": 60,
"daysOfWeek": {
"sunday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"monday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"tuesday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"wednesday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"thursday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"friday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
},
"saturday": {
"min": {
"hour": "09",
"minute": "00"
},
"max": {
"hour": "17",
"minute": "00"
}
}
},
"timezone": "America\/New_York"
}
```
{% endtab %}
{% endtabs %}
## Minimum Date Slots
If the merchant has pickup order limits, we will return an array of time slots available for the minDate
```javascript
{
"minDate": "2024-01-16",
"minDateSlots": [
{
"id": 1,
"location_id": 1,
"day_of_week": "tuesday",
"available_from": "11:30",
"available_until": "12:00",
"limited": true,
"limit": 10
},
{
"id": 2,
"location_id": 1,
"day_of_week": "tuesday",
"available_from": "12:00",
"available_until": "12:30",
"limited": true,
"limit": 10
}
}
```
## Blackout dates
If the merchant wants to prevent customers from selecting pickup on specific dates of the year we will return an array of dates as shown below.
{% hint style="info" %}
Months are javascript zero-based meaning December is 11 rather than 12
{% endhint %}
{% tabs %}
{% tab title="Blackout dates" %}
```javascript
/**
Pickup not allowed on:
13th May 2021
25th December 2021
**/
{
"disabled": [
"2021-04-13",
"2021-11-25"
]
}
```
{% endtab %}
{% endtabs %}
## Disabled days of the week
If merchants want to prevent customers from selecting pickup on specific days of the week then we will return an array of integers.
{% hint style="info" %}
Months are javascript zero-based meaning December is 11 rather than 12
{% endhint %}
```javascript
/**
Pickup not allowed on Sunday or Monday
1: Sunday
2: Monday
3: Tuesday
4: Wednesday
5: Thursday
6: Friday
7: Saturday
**/
{
"disabled": [
1,
2
]
}
```
## Specifically allowed pickup dates
If a merchant wants to allow pickups only on specific dates of the year we will return the available pickup dates in the disabled array. Note the first element of the array will be `true`
{% hint style="info" %}
Months are javascript zero-based meaning December is 11 rather than 12
{% endhint %}
```javascript
/**
Pickup is only available on:
13th May 2021
25th December 2021
**/
{
"disabled": [
true,
"2021-04-13",
"2021-11-25"
]
}
```
## Advanced date rules
Merchants can combine both specifically allowed pickup dates and days of the week.
{% hint style="info" %}
Months are javascript zero-based meaning December is 11 rather than 12
{% endhint %}
```javascript
/**
Pickup is only available on:
Sundays
Mondays
13th May 2021
25th December 2021
**/
{
"disabled": [
true,
1,
2,
"2021-04-13",
"2021-11-25"
]
}
```
```javascript
/**
Pickup is not available on:
Sundays
Mondays
13th May 2021
25th December 2021
**/
{
"disabled": [
1,
2,
"2021-04-13",
"2021-11-25"
]
}
```
# Times
## Get pickup times
`POST` `https://api.zapiet.com/v1.0/pickup/locations/:locationId/calendar/:date`
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------ | ------------------------------------------------------------- |
| date\* | string | The date you would like to get delivery times for YYYY-MM-DD. |
| locationId\* | string | The Zapiet location ID. |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
{% tabs %}
{% tab title="200: OK " %}
```json
[
{
"id": 1,
"location_id": 1,
"day_of_week": "wednesday",
"available_from": "09:00",
"available_until": "09:30",
"limited": true,
"limit": 10
},
{
"id": 2,
"location_id": 1,
"day_of_week": "wednesday",
"available_from": "09:30",
"available_until": "10:00",
"limited": true,
"limit": 10
}
]
```
{% endtab %}
{% endtabs %}
# Regions
## Get regions
`GET` `https://api.zapiet.com/v1.0/pickup/regions`
Returns an array of regions based on the "region" field of a store's active pickup locations.
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
{% tabs %}
{% tab title="200 Pickup regions successfully retrieved." %}
```javascript
[
"Boston",
"New York",
"Washington DC"
]
```
{% endtab %}
{% endtabs %}
# Local delivery
# Locations
## Get eligible delivery location
`POST` `https://api.zapiet.com/v1.0/delivery/locations`
This endpoint will return the nearest eligible delivery location based on the customer's location and shopping cart.
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
#### Request Body
| Name | Type | Description |
| -------------- | ------ | ----------------------------- |
| shoppingCart | array | The customer's shopping cart. |
| geoSearchQuery | string | 10001 |
{% tabs %}
{% tab title="200 Local delivery available " %}
```json
{
"id": 433,
"external_id": "72950677728"
"distance": null,
"driving_distance": null,
"company_name": "Apple",
"address_line_1": "767 5th Ave",
"address_line_2": null,
"city": "New York",
"postal_code": "10153",
"region": "New York",
"country": "United States",
"latitude": 40.7638414,
"longitude": -73.9729718,
"timezone": "America\/New_York",
"custom_attribute_1": null,
"custom_attribute_2": null,
"custom_attribute_3": null,
"delivery": {
"flip_blackout_dates": false,
"blackouts": ["2023-11-21", "2023-11-28"],
"monday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 831969,
"day_of_week": "monday",
"from": "10:15",
"until": "12:45",
"limited": true,
"limit": 12
}, {
"id": 831970,
"day_of_week": "monday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 831971,
"day_of_week": "monday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"tuesday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2406,
"day_of_week": "tuesday",
"from": "10:45",
"until": "12:30",
"limited": true,
"limit": 15
}, {
"id": 402219,
"day_of_week": "tuesday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 6
}, {
"id": 402220,
"day_of_week": "tuesday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"wednesday": {
"blackout_dates": ["2020-11-21", "2020-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2407,
"day_of_week": "wednesday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 846035,
"day_of_week": "wednesday",
"from": "11:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402221,
"day_of_week": "wednesday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402222,
"day_of_week": "wednesday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"thursday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2408,
"day_of_week": "thursday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402223,
"day_of_week": "thursday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402224,
"day_of_week": "thursday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"friday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2409,
"day_of_week": "friday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402225,
"day_of_week": "friday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402226,
"day_of_week": "friday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"saturday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2410,
"day_of_week": "saturday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402227,
"day_of_week": "saturday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402228,
"day_of_week": "saturday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"sunday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2411,
"day_of_week": "sunday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402229,
"day_of_week": "sunday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402230,
"day_of_week": "sunday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
}
},
"current_time": "2024-02-13 08:54:24"
}
```
{% endtab %}
{% endtabs %}
## Location available
{% tabs %}
{% tab title="Request" %}
```json
{
"geoSearchQuery": "10001",
"shoppingCart": [
{
"variant_id": 9226255761451,
"product_id": 852798275627,
"quantity": 1
}
]
}
```
{% endtab %}
{% tab title="Response" %}
```json
{
"id": 433,
"external_id": "72950677728"
"distance": null,
"driving_distance": null,
"company_name": "Apple",
"address_line_1": "767 5th Ave",
"address_line_2": null,
"city": "New York",
"postal_code": "10153",
"region": "New York",
"country": "United States",
"latitude": 40.7638414,
"longitude": -73.9729718,
"timezone": "America\/New_York",
"custom_attribute_1": null,
"custom_attribute_2": null,
"custom_attribute_3": null,
"delivery": {
"deliv_enabled": false,
"flip_blackout_dates": false,
"blackouts": ["2023-11-21", "2023-11-28"],
"monday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 831969,
"day_of_week": "monday",
"from": "10:15",
"until": "12:45",
"limited": true,
"limit": 12
}, {
"id": 831970,
"day_of_week": "monday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 831971,
"day_of_week": "monday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"tuesday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2406,
"day_of_week": "tuesday",
"from": "10:45",
"until": "12:30",
"limited": true,
"limit": 15
}, {
"id": 402219,
"day_of_week": "tuesday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 6
}, {
"id": 402220,
"day_of_week": "tuesday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"wednesday": {
"blackout_dates": ["2020-11-21", "2020-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2407,
"day_of_week": "wednesday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 846035,
"day_of_week": "wednesday",
"from": "11:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402221,
"day_of_week": "wednesday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402222,
"day_of_week": "wednesday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"thursday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2408,
"day_of_week": "thursday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402223,
"day_of_week": "thursday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402224,
"day_of_week": "thursday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"friday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2409,
"day_of_week": "friday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402225,
"day_of_week": "friday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402226,
"day_of_week": "friday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"saturday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2410,
"day_of_week": "saturday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402227,
"day_of_week": "saturday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402228,
"day_of_week": "saturday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
},
"sunday": {
"blackout_dates": ["2023-11-21", "2023-11-28"],
"breakpoint": "14:00",
"useBreakpoint": false,
"before": {
"value": 24,
"format": "days"
},
"after": {
"value": 24,
"format": "days"
},
"slots": {
"enabled": true,
"slots": [{
"id": 2411,
"day_of_week": "sunday",
"from": "10:00",
"until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402229,
"day_of_week": "sunday",
"from": "12:00",
"until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402230,
"day_of_week": "sunday",
"from": "13:00",
"until": "14:00",
"limited": true,
"limit": 10
}]
}
}
},
"current_time": "2024-02-13 08:54:24"
}
```
{% endtab %}
{% endtabs %}
## Location not available
```json
{
"error": {
"code": "NO_LOCATIONS_FOUND",
"message": "No locations were found based upon the provided parameters."
}
}
```
# Dates
## Get calendar
`POST` `https://api.zapiet.com/v1.0/delivery/locations/:locationId/calendar`
This endpoint allows you to get a list of available and unavailable dates for a location.
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------ | ----------------------- |
| locationId\* | string | The Zapiet location ID. |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
#### Request Body
| Name | Type | Description |
| ------------ | ----- | ----------------------------- |
| shoppingCart | array | The customer's shopping cart. |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"minDateTime": "2021-05-13 10:00:00",
"minDate": "2021-05-13",
"maxDate": null,
"minTime": ["10", "00"],
"maxTime": ["13", "00"],
"disabled": [
[2020, 10, 21],
[2020, 10, 28]
],
"minDateSlots": [{
"id": 2408,
"day_of_week": "thursday",
"available_from": "10:00",
"available_until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402223,
"day_of_week": "thursday",
"available_from": "12:00",
"available_until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402224,
"day_of_week": "thursday",
"available_from": "13:00",
"available_until": "14:00",
"limited": true,
"limit": 10
}],
"datePickerEnabled": true,
"timePickerEnabled": true,
"timezone": "America\/New_York"
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Request" %}
```javascript
{
"shoppingCart": [
{
"variant_id": 9226255761451,
"product_id": 852798275627,
"quantity": 5
},
{
"variant_id": 9226255761452,
"product_id": 852798275628,
"quantity": 2
}
]
}
```
{% endtab %}
{% tab title="Response" %}
```javascript
{
"minDateTime": "2021-05-13 10:00:00",
"minDate": "2021-05-13",
"maxDate": null,
"minTime": ["10", "00"],
"maxTime": ["13", "00"],
"disabled": [
[2020, 10, 21],
[2020, 10, 28]
],
"minDateSlots": [{
"id": 2408,
"day_of_week": "thursday",
"available_from": "10:00",
"available_until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402223,
"day_of_week": "thursday",
"available_from": "12:00",
"available_until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402224,
"day_of_week": "thursday",
"available_from": "13:00",
"available_until": "14:00",
"limited": true,
"limit": 10
}],
"datePickerEnabled": true,
"timePickerEnabled": true,
"timezone": "America\/New_York"
}
```
{% endtab %}
{% endtabs %}
# Times
## Get delivery times
`GET` `https://api.zapiet.com/v1.0/delivery/locations/:locationId/calendar/:date`
This endpoint allows you to get delivery times for a given date.
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------ | ------------------------------------------------------------- |
| date\* | string | The date you would like to get delivery times for YYYY-MM-DD. |
| locationId\* | string | The Zapiet location ID. |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
{% tabs %}
{% tab title="200 " %}
```javascript
[{
"id": 2408,
"day_of_week": "thursday",
"available_from": "10:00",
"available_until": "12:00",
"limited": true,
"limit": 10
}, {
"id": 402223,
"day_of_week": "thursday",
"available_from": "12:00",
"available_until": "14:00",
"limited": true,
"limit": 10
}, {
"id": 402224,
"day_of_week": "thursday",
"available_from": "13:00",
"available_until": "14:00",
"limited": true,
"limit": 10
}]
```
{% endtab %}
{% endtabs %}
# Shipping
# Dates
## Get shipping dates
`GET` `https://api.zapiet.com/v1.0/shipping/calendar`
This endpoint allows you to get possible shipping dates.
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
#### Request Body
| Name | Type | Description |
| ------------ | ----- | ----------------------------- |
| shoppingCart | array | The customer's shopping cart. |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"minDate": "2021-05-14",
"maxDate": "2021-05-27",
"disabled": [
[2020, 11, 25],
[2020, 11, 26], 1
],
"timezone": "Europe\/London"
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Request" %}
```javascript
{
"shoppingCart": [
{
"variant_id": 9226255761451,
"product_id": 852798275627,
"quantity": 5
},
{
"variant_id": 9226255761452,
"product_id": 852798275628,
"quantity": 2
}
]
}
```
{% endtab %}
{% tab title="Response" %}
```javascript
{
"minDate": "2021-05-14",
"maxDate": "2021-05-27",
"disabled": [
[2020, 11, 25],
[2020, 11, 26], 1
],
"timezone": "Europe\/London"
}
```
{% endtab %}
{% endtabs %}
# Validation
## Validate cart for checkout method
`POST` `https://api.zapiet.com/v1.0/:checkoutMethod/validate`
This endpoint allows you to check if the customer's cart is eligible for a given checkout method.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------- |
| checkoutMethod\* | string | The checkout method you would like to validate against. Valid values are; pickup, delivery, and shipping. |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
#### Request Body
| Name | Type | Description |
| ------------ | ----- | ----------------------------- |
| shoppingCart | array | The customer's shopping cart. |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"productsEligible": true
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Request" %}
```javascript
{
"shoppingCart": [
{
"variant_id": 9226255761451,
"product_id": 852798275627,
"quantity": 5
},
{
"variant_id": 9226255761452,
"product_id": 852798275628,
"quantity": 2
}
]
}
```
{% endtab %}
{% tab title="Response" %}
```javascript
{
"productsEligible": true
}
```
{% endtab %}
{% endtabs %}
# Geolocate
## Get latitude/longitude
`GET` `https://api.zapiet.com/v1.0/geolocate`
This endpoint allows you to pass a zip code or address and will return the latitude/longitude.
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------ |
| shop\* | string | The merchant's myshopify.com store url. |
| query | string | Valid zip code or address you would like to retrieve a latitude/longitude for. |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"latitude": 53.3671889,
"longitude": -0.017696
}
```
{% endtab %}
{% endtabs %}
# Conditional activation
## Get conditional activation
`POST` `https://api.zapiet.com/v1.0/:checkoutMethod/conditional_activation`
This endpoint will return a list of conditional activations.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------- |
| checkoutMethod\* | string | The checkout method you would like to validate against. Valid values are; pickup, delivery, and shipping. |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
#### Request Body
| Name | Type | Description |
| --------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| shoppingCart.items\* | array | The contents of the customer's shopping cart. If no value is provided we will not check inventory levels or product availability. |
| shoppingCart.original\_total\_price\* | numeric | |
| shopppingCart.total\_weight\* | numeric | |
| shoppingCart.items.\*.tags | string | |
| shoppingCart.items.\*.vendor | string | |
| shoppingCart.items.\*.product\_type | string | |
| shoppingCart.items.\*.collections | string | |
{% tabs %}
{% tab title="200 Conditions successfully retrieved." %}
```javascript
{
"weight_price": {
"enabled": true,
"valid": true,
"condition": "price",
"operator": "morethan",
"value": 0
},
"property_based": {
"enabled": false,
"valid": true
},
"hide_checkout_method": false,
"valid_shopping_cart": true
}
```
{% endtab %}
{% endtabs %}
### Conditions available
{% tabs %}
{% tab title="Request" %}
```javascript
{
"shoppingCart": {
"original_total_price": 599,
"total_weight": 10000,
"items": [
{
"collections": "Adidas Shoes",
"vendor": "Adidas",
"product_type": "Sneaker",
"tags": "Adidas, Pickup Only"
},
{
"collections": "New Balance Shoes",
"vendor": "New Balance",
"product_type": "Sneaker",
"tags": "New Balance, Pickup Only"
}
]
}
}
```
{% endtab %}
{% tab title="Response" %}
```javascript
{
"weight_price": {
"enabled": true,
"valid": true,
"condition": "price",
"operator": "morethan",
"value": 0
},
"property_based": {
"enabled": false,
"valid": true
},
"hide_checkout_method": false,
"valid_shopping_cart": true
}
```
{% endtab %}
{% endtabs %}
# Preparation times
## Get preparation times
`GET` `https://api.zapiet.com/v1.0/:checkoutMethod/location/:locationId/preparation_times`
This endpoint will return a list of preparation times.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------- |
| checkoutMethod\* | string | The checkout method you would like to validate against. Valid values are; pickup, delivery, and shipping. |
| locationId\* | numeric | The Zapiet location ID. |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
{% tabs %}
{% tab title="200 Preparation times successfully retrieved." %}
```javascript
{
"general": {
"enabled": true,
"monday": {
"breakpoint": {
"enabled": false,
"value": "14:00"
},
"before": {
"format": "hours",
"value": 1
},
"after": {
"format": "hours",
"value": 2
}
},
"tuesday": {
"breakpoint": {
"enabled": false,
"value": "14:00"
},
"before": {
"format": "hours",
"value": 1
},
"after": {
"format": "hours",
"value": 2
}
},
"wednesday": {
"breakpoint": {
"enabled": true,
"value": "14:00"
},
"before": {
"format": "hours",
"value": 1
},
"after": {
"format": "hours",
"value": 2
}
},
"thursday": {
"breakpoint": {
"enabled": true,
"value": "14:00"
},
"before": {
"format": "hours",
"value": 1
},
"after": {
"format": "hours",
"value": 2
}
},
"friday": {
"breakpoint": {
"enabled": true,
"value": "14:00"
},
"before": {
"format": "minutes",
"value": 30
},
"after": {
"format": "minutes",
"value": 30
}
},
"saturday": {
"breakpoint": {
"enabled": true,
"value": "14:00"
},
"before": {
"format": "days",
"value": 1
},
"after": {
"format": "days",
"value": 2
}
},
"sunday": {
"breakpoint": {
"enabled": true,
"value": "14:00"
},
"before": {
"format": "days",
"value": 1
},
"after": {
"format": "days",
"value": 3
}
}
},
"product_based": [
{
"product_external_id": "8184259576032",
"preparation_enabled": 1,
"preperation_value": 300,
"preparation_format": "hours"
},
{
"product_external_id": "8184259674336",
"preparation_enabled": 1,
"preperation_value": 2880,
"preparation_format": "days"
},
{
"product_external_id": "8184259346656",
"preparation_enabled": 1,
"preperation_value": 30,
"preparation_format": "minutes"
}
]
}
```
{% endtab %}
{% endtabs %}
# Settings
## Get settings
`GET` `https://api.zapiet.com/v1.0/settings`
This endpoint allows you to retrieve a store's settings.
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------- |
| shop\* | string | The merchant's myshopify.com store url. |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"base_country_name": "United Kingdom",
"measurement_format": "kilometers",
"pickup": {
"enabled": true,
"pagination_limit": 10,
"sort_order": "manual",
"discount_code": "10STOCKPICKUP",
"prepopulate_shipping_address": true,
"filter_by_region": false,
"preselect_first_available_location": true,
"preselect_first_available_time": true,
"noted_enabled": false,
"note_required": false
},
"delivery": {
"enabled": true,
"validation_mode": "within_max_radius",
"driving_distance_preferences": null
"driving_distance_route": "fastest",
"discount_code": null,
"prepopulate_shipping_address": true,
"noted_enabled": false,
"note_required": false,
"preselect_first_available_time": true
},
"shipping": {
"enabled": true,
"blackout_dates": [],
"monday_enabled": true,
"tuesday_enabled": true,
"wednesday_enabled": true,
"thursday_enabled": true,
"friday_enabled": true,
"saturday_enabled": true,
"sunday_enabled": true,
"timezone": "America\/New_York",
"discount_code": null,
"preparation_time": {
"enabled": false,
"monday": {
"value": 10,
"format": "days",
"cutoff_time": {
"enabled": false,
"time": "12:00",
"value": 2
}
},
"tuesday": {
"value": 10,
"format": "days",
"cutoff_time": {
"enabled": false,
"time": "12:00",
"value": 2
}
},
"wednesday": {
"value": 10,
"format": "days",
"cutoff_time": {
"enabled": false,
"time": "12:00",
"value": 2
}
},
"thursday": {
"value": 10,
"format": "days",
"cutoff_time": {
"enabled": false,
"time": "12:00",
"value": 2
}
},
"friday": {
"value": 10,
"format": "days",
"cutoff_time": {
"enabled": false,
"time": "12:00",
"value": 2
}
},
"saturday": {
"value": 10,
"format": "days",
"cutoff_time": {
"enabled": false,
"time": "12:00",
"value": 2
}
},
"sunday": {
"value": 10,
"format": "days",
"cutoff_time": {
"enabled": false,
"time": "12:00",
"value": 2
}
}
},
"maximum_date": {
"enabled": false,
"metric": "days",
"value": 14
},
"order_limits": {
"enabled": false,
"monday": 2,
"tuesday": 1,
"wednesday": 0,
"thursday": 0,
"friday": 0,
"saturday": 0,
"sunday": 0
},
"note_enabled": false,
"note_required": false
}
}
```
{% endtab %}
{% endtabs %}
# Events
## Events
{% hint style="info" %}
The following are the most recently added events, including any previous events.
{% endhint %}
```
getDeliveryLocations
noShippingDates
checkoutDisabled
eligibilityError
locationSelected
missingNote
enableCheckout
disableCheckout
missingNote
```
{% hint style="info" %}
The following events are available in **v7.0.5** and above.
{% endhint %}
```
widget_loaded
selected_method
delivery.datepicker.rendered
delivery.datepicker.opened
delivery.timepicker.rendered
delivery.timepicker.opened
pickup.datepicker.rendered
pickup.datepicker.opened
pickup.timepicker.rendered
pickup.timepicker.opened
shipping.datepicker.rendered
shipping.datepicker.opened
checkoutEnabled
```
## Example
You can access the above events using the following code:
```javascript
$(document).ready(function() {
window.ZapietEvent.listen('selected_method', function(checkout_method) {
switch (checkout_method) {
case "pickup":
// Do something when pickup is selected
break;
case "delivery":
// Do something when delivery is selected
break;
case "shipping":
// Do something when shipping is selected
break;
}
});
});
```
{% hint style="info" %}
If you use the example above, please ensure that [jQuery](https://code.jquery.com) is included in your theme.
{% endhint %}
# Methods
The following method can be used to reload the widget. Primarily used for ajax cart support.
```javascript
Zapiet.start(ZapietWidgetConfig);
```
The following method can be used to detect whether or not customers should be able to proceed to checkout process. This ensures customers have selected a checkout method, date and time.
```
Zapiet.Widget.checkoutEnabled();
```
# ZapietId
## What is the ZapietId?
The \_ZapietId is integral to our Rates functionality. At least one item in your customers basket must contain a valid \_ZapietId line item property otherwise rates will fail to generate correctly within the checkout process.
The \_ZapietId is made up of the following three parameters:
| Parameter | Data type | Example | Notes |
| --------- | --------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| M | string | P |
The value can be either P, D or S.
P = pickup
D = delivery
S = shipping
Required for all orders
|
| L | integer | 1002 |
The Zapiet location ID
Required for pickup and delivery orders
|
| D | datetime | 2021-05-13T12:00:00Z |
The customers selected date and time for delivery, pickup or shipping
Required for date based pickup, delivery and shipping orders
|
## Adding the \_ZapietId to a line item
If you are using our default widget the \_ZapietId property is automatically added to your order. Should you be building your own storefront widget you can use Shopify's Cart API .
Alternatively if you are building a mobile app or using a headless commerce solution you may prefer to use the Draft Orders API .
{% hint style="info" %}
The line item must be called \_ZapietId including the prepending underscore.
{% endhint %}
```javascript
$.post('/cart/change.js', data);
```
## Generating the \_ZapietId
Below is a javascript example of how you might generate a \_ZapietId.
```javascript
function getZapietId(params)
{
var fomatted_date = '';
if (params.date && !params.time) {
var fomatted_date = params.date.replace(/\//g, "-");
fomatted_date = fomatted_date + 'T00:00:00Z';
} else if (params.date && params.start_time) {
var fomatted_date = params.date.replace(/\//g, "-");
fomatted_date = fomatted_date + 'T' + params.start_time + ':00Z';
}
return this.encodeZapietId({
M: this.getMethodKey(params.method),
L: (params.location_id) ? params.location_id : "",
D: fomatted_date,
P: ""
});
}
function getMethodKey(method) {
if (method == 'delivery') {
return 'D';
} else if (method == 'pickup') {
return 'P';
} else {
return 'S';
}
}
function encodeZapietId(params) {
const ret = [];
for (let d in params) {
if (params[d]) {
ret.push(d + '=' + params[d]);
}
}
return ret.join('&');
}
const ZapietId = getZapietId({
date: '2021-05-13',
start_time: '10:00',
location_id: 10001,
method: 'pickup'
});
```
# Attributes
To ensure your pickup, delivery and shipping orders are processed correctly (tagged, notifications sent, appear in our dashboard) they must contain the correct attributes attached. Below we have documented the required attributes for each checkout method.
## Adding attributes
The best way of adding these attributes to an order is by using Shopify's Cart API .
If you are building a mobile app or using a headless commerce solution then you may prefer the Draft Orders API .
## Pickup orders
{% hint style="info" %}
Date and times must be provided in the format(s) listed shown below
{% endhint %}
| Attribute name | Example |
| ------------------------------ | --------------- |
| Checkout-Method | pickup |
| Pickup-Location-Id | 100001 |
| Pickup-Location-Company | Zapiet NY |
| Pickup-Location-Address-Line-1 | 5th Avenue |
| Pickup-Location-Address-Line-2 | |
| Pickup-Location-City | New York |
| Pickup-Location-Region | New York |
| Pickup-Location-Postal-Code | 10001 |
| Pickup-Location-Country | United States |
| Pickup-Date | 2021-05-13 |
| Pickup-Time | 13:00 / 1:00 PM |
| Custom-Attribute-1 | |
| Custom-Attribute-2 | |
| Custom-Attribute-3 | |
## Delivery orders
{% hint style="info" %}
Date and times must be provided in the format(s) shown below
{% endhint %}
| Attribute name | Example |
| -------------------- | -------------------------------- |
| Checkout-Method | delivery |
| Delivery-Location-Id | 10002 |
| Delivery-Date | 2021-05-13 |
| Delivery-Time | 13:00 - 14:00 / 1:00 PM - 2:00PM |
| Custom-Attribute-1 | |
| Custom-Attribute-2 | |
| Custom-Attribute-3 | |
## Shipping orders
{% hint style="info" %}
Date must be provided in the format shown below
{% endhint %}
| Attribute name | Example |
| --------------- | ---------- |
| Checkout-Method | shipping |
| Shipping-Date | 2021-05-13 |
# Unsupported features
**Location-specific settings**
The following settings are **not viewable or editable through the API**, but are still applied internally and reflected when querying through the Calendar API:
* Product date restrictions (including tags and collections)
* Blackout dates
* Future orders
* Order limits
* Product availability
* Business hours
* Timezone
* Custom attributes
* Latitude and longitude
* Date/time picker–related settings
**Pickup, delivery, and shipping settings**
The following settings are **also not viewable or editable through the API**, but are still enforced and will be reflected when querying through the Calendar API:
* Validation
* Date and time pickers
* Delivery notes
* Location filters
* Sort order
* Preselected values
* Address format
* Pickup notes
* Pickup/delivery/shipping order tags
* Discount codes
* Payment methods
* Address prepopulation
* Order processing
* Pickup security codes
* Shipping days
* Blackout dates
* Future orders
* Product date restrictions (including tags and collections)
* Timezone
# Vulnerability Reporting
To report a security vulnerability (bug bounty):
We only accept vulnerabilities with a CVSSv3 score of 5.0 or higher via email.
Your submission should include:
* Detailed instructions for reproducing the bug (Proof of Concept);
* A screen capture of the bug execution on a Zapiet resource, either attached or linked;
* Relevant reference links and associated CVEs.
Disclaimer: Any external testing that disrupts the Confidentiality, Integrity, or Availability of Zapiet assets without prior agreement will be considered unlawful, and Zapiet may pursue legal action.
To report an issue that has a security impact, please report to:
Once a vulnerability report is received, Zapiet will acknowledge receipt within 3 business days and take the following steps to address the issue:
* Zapiet will assess and verify the validity of the reported vulnerability.
* The vulnerability will be classified by Zapiet according to its potential impact and severity.
* Based on this assessment, Zapiet will create a remediation plan and work to implement a fix. In most cases, Zapiet aims to prepare and publish advisories for newly identified vulnerabilities within approximately 90 days of verification. Breakdowns of timelines are highlighted below:
* **Critical (CVSS 9.0-10.0): 24 hours** - For vulnerabilities posing immediate risk
* **High (CVSS 7.0-8.9): 7 days** - For significant security risks
* **Medium (CVSS 4.0-6.9): 30 days** - For moderate risk vulnerabilities
* **Low (CVSS 0.1-3.9): 90 days** - For limited impact vulnerabilities
# Widget API
This is early pre-release API documentation for the available events, methods and API requests used by the Zapiet Eats storefront widget
# Events
The following events are available
`zapieteats:init`\
Fired when the widget initializes.
```
window.ZapietEvent.listen('zapieteats:init', function() {
console.log('Widget initialized');
});
```
\
`zapieteats:ready`
Fired when the widget is ready.
```
window.ZapietEvent.listen('zapieteats:ready', function() {
console.log('Widget ready');
});
```
\
`zapieteats:settings:loading`\
Fired when settings are loading.
```
window.ZapietEvent.listen('zapieteats:settings:loading', function() {
console.log('Settings loading');
});
```
`zapieteats:settings:loaded`\
Fired when settings are loaded.
```
window.ZapietEvent.listen('zapieteats:settings:loaded', function(settings) {
console.log('Settings loaded', settings);
});
```
`zapieteats:restaurants:loading`
Fired when restaurants are loading.
```
window.ZapietEvent.listen('zapieteats:restaurants:loading', function() {
console.log('Restaurants loading');
});
```
`zapieteats:restaurants:loaded`
Fired when restaurants are loaded.
```
window.ZapietEvent.listen('zapieteats:restaurants:loaded', function(restaurants) {
console.log('Restaurants loaded', restaurants);
});
```
\
`zapieteats:language:changed`\
Fired when the language changes.
```
window.ZapietEvent.listen('zapieteats:language:changed', function(language) {
console.log('Language changed to', language);
});
```
`zapieteats:restaurant:changed`\
Fired when the selected restaurant changes.
```
window.ZapietEvent.listen('zapieteats:restaurant:changed', function(restaurant) {
console.log('Restaurant changed', restaurant);
});
```
`zapieteats:menu:changed`
Fired when the selected menu changes.
```
window.ZapietEvent.listen('zapieteats:menu:changed', function(menu) {
console.log('Menu changed', menu);
});
```
`zapieteats:deliveryoption:changed`
Fired when the delivery option changes.
```
window.ZapietEvent.listen('zapieteats:deliveryoption:changed', function() {
console.log('Delivery option changed');
});
```
`zapieteats:modal:opened`
Fired when the modal is opened.
```
window.ZapietEvent.listen('zapieteats:modal:opened', function() {
console.log('Modal opened');
});
```
`zapieteats:modal:closed`
Fired when the modal is closed.
```
window.ZapietEvent.listen('zapieteats:modal:closed', function() {
console.log('Modal closed');
});
```
# Methods
The following methods are available on the global window\.ZapietEats object
`getLanguage()`
Returns the current language locale.
```
const locale = window.ZapietEats.getLanguage();
// Returns: "en"
```
`setLanguage(newLanguage)`
Sets the language for the widget.
```
window.ZapietEats.setLanguage('fr');
```
`getDeliveryOption()`
Returns the currently selected delivery option.
```
const option = window.ZapietEats.getDeliveryOption();
// Returns: "pickup" or "delivery"
```
\
`setDeliveryOption(deliveryOption)`
Sets the delivery option.
1. `deliveryOption` (string): "pickup" or "delivery".
```
window.ZapietEats.setDeliveryOption('delivery');
```
`getSelectedRestaurant()`
Returns the currently selected restaurant object.
```
const restaurant = window.ZapietEats.getSelectedRestaurant();
```
`getSelectedMenu()`
Returns the currently selected menu object.
```
const menu = window.ZapietEats.getSelectedMenu();
```
`getSelectedDate()`
Returns the currently selected date as a ZapietDate object.
```
const date = window.ZapietEats.getSelectedDate();
```
`getLocationInventoryDate()`
Returns the date to be used for inventory checks, based on the selected location's timezone.
```
const inventoryDate = window.ZapietEats.getLocationInventoryDate();
// Returns: "YYYY-MM-DD"
```
`getSelectedTime()`
Returns the currently selected time as a ZapietTime object.
```
const time = window.ZapietEats.getSelectedTime();
```
`getSettings()`
Returns the account settings.
```
const settings = window.ZapietEats.getSettings();
```
`showTopBar()`
Shows the top bar of the widget.
```
window.ZapietEats.showTopBar();
```
`hideTopBar()`
Hides the top bar of the widget.
```
window.ZapietEats.hideTopBar();
```
`getZapietId()`
Generates the Zapiet ID string based on the current selection.
```
const zapietId = window.ZapietEats.getZapietId(); // Returns: "A=E&M=D&L=123&Z=456&D=2023-10-25&T=14:00"
```
`getAttributes()`
Returns an object containing the cart attributes based on the current selection.
```
const attributes = window.ZapietEats.getAttributes();
```
`addZapietId()`
Adds the Zapiet ID and attributes to the current cart.
```
window.ZapietEats.addZapietId().then((cart) => {
console.log('Zapiet ID added to cart', cart);
});
```
\
`getCartLineItemsWithZapietId(cart)`
Returns the cart items with the `_ZapietId` property added to them.
* `cart` (optional): The Shopify cart object. If not provided, it fetches the current cart.
```
window.ZapietEats.getCartLineItemsWithZapietId().then((items) => {
console.log('Items with Zapiet ID', items);
});
```
`openModal()`
Opens the widget modal.
```
window.ZapietEats.openModal();
```
`closeModal()`
Closes the widget modal.
```
window.ZapietEats.closeModal();
```
`showMessage(data)`
Shows a message in the widget.
* `data` (object | string): The message data or string.
* `message` (string): The message text.
* `type` (string): "info" or "error".
* `primaryAction` (object): Optional primary action button.
* `secondaryAction` (object): Optional secondary action button.
```
window.ZapietEats.showMessage({
message: 'Please select a location',
type: 'error'
});
```
`closeMessage()`
Closes the currently displayed message.
```
window.ZapietEats.closeMessage();
```
# Cart attributes
We use the Shopify Cart API to add the necessary attributes to your orders
List of the possible attributes:
* `Checkout-Method` "pickup" | "delivery"
* `Delivery-Location-Id` ID of the selected delivery location.
* `Delivery-Date` Selected delivery date (YYYY-MM-DD).
* `Delivery-Time` Selected delivery time (24h format).
* `Delivery-Location-Distance` Distance to the delivery location.
* `Delivery-Widget-Query` Search query used for delivery.
* `Pickup-Location-Id` ID of the selected pickup location.
* `Pickup-Location-Company` Name of the pickup location company.
* `Pickup-Location-Address-Line-1` Address line 1 of the pickup location.
* `Pickup-Location-Address-Line-2` Address line 2 of the pickup location.
* `Pickup-Location-City` City of the pickup location.
* `Pickup-Location-Region` Region of the pickup location.
* `Pickup-Location-Postal-Code` Postal code of the pickup location.
* `Pickup-Location-Country` Country of the pickup location.
* `Pickup-Location-Distance` Distance to the pickup location.
* `Pickup-Widget-Query` Search query used for pickup.
* `Pickup-Date` Selected pickup date (YYYY-MM-DD).
* `Pickup-Time` Selected pickup time (24h format).
* `Menu-Id` ID of the selected menu.
* `Zone-Id` ID of the selected zone.
* `Order-Notes` Notes added to the order.
# API endpoints
The widget communicates with the backend via the following endpoints
### `GET /settings`
Retrieves the account settings and configuration for the widget.
Status Codes:
* `200 OK`: Success.
Parameters:
* `locale` (string): The current locale (e.g., "en").
* `include_restaurants` (boolean): Whether to include restaurant data (default: false).
Response:
```
{
"is_test_mode": false,
"pickup_restaurants_count": 5,
"delivery_restaurants_count": 3,
"pickup_restaurants": [
{
"id": 1,
"name": "Downtown Branch",
"address_line_1": "123 Main St",
"city": "New York",
"region": "NY",
"is_pickup_enabled": true,
"is_delivery_enabled": false
}
],
"delivery_restaurants": [
{
"id": 2,
"name": "Uptown Branch",
"address_line_1": "456 Broadway",
"city": "New York",
"region": "NY",
"is_pickup_enabled": true,
"is_delivery_enabled": true
}
],
"settings": {
"base_country": "United States",
"advanced": {
"show_restaurant_name": true,
"show_restaurant_address": true,
"address_format": "{address_line_1}, {city}",
"always_show_order_note": false
},
"google": {
"maps_api_key": "AIzaSy...",
"enable_widget_map": true
},
"widget": {
"google": {
"maps_api_key": "AIzaSy...",
"enable_widget_map": true
},
"advanced": {
"show_restaurant_name": true,
"show_restaurant_address": true,
"address_format": "{address_line_1}, {city}",
"always_show_order_note": false
},
"restaurant": {
"select_delivery_location": true,
"adjust_location_with_map": true
},
"location_types": {
"sort_by_type": true
}
},
"company_name": "My Store",
"language": "en",
"currency_code": "USD",
"country_code": "US",
"time_format": "12h",
"developer": {
"selectors": {
"product_add_to_cart": "form[action='/cart/add']",
"product_add_to_cart_text": ".add-to-cart-text"
}
},
"checkout_locales": {
"pickup": "en",
"delivery": "en",
"shipping": "en"
}
},
"translations": [
{
"id": 1,
"translation_key": "front_widget",
"values": {
"en": "Order Now",
"es": "Ordenar Ahora"
}
}
]
}
```
### `POST /product-options`
Retrieves available product options for a given product, used for checking availability and restrictions.\
Status Codes:
* `200 OK`: Success.
* `400 Bad Request`: Missing product data.
* `404 Not Found`: Shop or account not found.
Payload:
```
{
"shop": "my-shop.myshopify.com",
"product": {
"id": 1234567890,
"variants": [
{
"id": 9876543210,
"title": "Small",
"price": "10.00"
}
],
"type": "Food",
"vendor": "My Vendor",
"tags": ["tag1", "tag2", "gluten-free"]
}
}
```
Response:
```
{
"data": {
"options": [
{
"id": 1,
"name": "Size",
"is_required": 1,
"help_text": "Choose a size",
"max_selections": 1,
"min_selections": 1,
"values": [
{ "id": 1, "value": "Small" },
{ "id": 2, "value": "Large" }
]
},
{
"id": 2,
"name": "Toppings",
"is_required": 0,
"help_text": "Add extra toppings",
"max_selections": 3,
"min_selections": 0,
"values": [
{ "id": 3, "value": "Cheese" },
{ "id": 4, "value": "Pepperoni" },
{ "id": 5, "value": "Mushrooms" }
]
}
]
}
}
```
### `POST /search`
Searches for available restaurants based on location and delivery option.
\
Status Codes:
* `200 OK`: Success.
Payload:
```
{
"deliveryOption": "pickup", // or "delivery"
"query": "10001",
"latitude": 40.7128,
"longitude": -74.0060,
"page": 1,
"requestTime": "2023-10-25T12:00:00",
"postcode": "10001"
}
```
Response:
```
{
"data": [
{
"id": 1,
"name": "Downtown Store",
"distance": 1.2,
"status": "open",
"full_address": "123 Main St, New York, NY 10001",
"address_line_1": "123 Main St",
"city": "New York",
"region": "NY",
"country_code": "US",
"menus": [
{
"id": 1,
"name": { "en": "Lunch Menu" },
"status": "published"
}
],
"restaurant_type": {
"id": 1,
"name": "Italian"
},
"config": {
"delivery_options": {
"store_pickup": { "enabled": true },
"local_delivery": { "enabled": false }
}
}
}
],
"meta": {
"current_page": 1,
"from": 1,
"last_page": 5,
"per_page": 5,
"to": 5,
"total": 25
},
"account_status": "active",
"all_restaurants_closed": false,
"count": true,
"distance_unit": "km",
"has_more_pages": true
}
```
### `POST /checkouts`
Creates a draft order or processes the checkout.
Status Codes:
* `200 OK`: Success.
* `422 Unprocessable Entity`: Validation errors (e.g., out of stock).
Payload:
```
{
"restaurant_id": 123,
"menu_id": 456,
"zone_id": 789, // Required for delivery if zones are used
"store_url": "my-shop.myshopify.com",
"checkout_method": "pickup", // or "delivery"
"date": "2023-10-25",
"time": "14:00",
"start_time": "14:00", // Optional, for slots
"end_time": "15:00", // Optional, for slots
"slot_id": 101, // Optional, specific slot ID
"note": "Leave at door",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"phone": "+15551234567",
"customer_id": "987654321", // Optional Shopify Customer ID
"locale": "en",
"line_items": [
{
"id": 11223344, // Variant ID
"quantity": 2,
"properties": {
"_ZapietId": "M=P&D=2023-10-25&T=14:00",
"Custom Option": "Value"
}
}
],
"customer_address": {
"formatted_address": "123 Main St, New York, NY 10001, USA",
"postcode": "10001",
"city": "New York",
"province_code": "NY",
"country_code": "US",
"country": "United States"
},
"attributes": [
{
"key": "Checkout-Method",
"value": "pickup"
},
{
"key": "Pickup-Date",
"value": "2023-10-25"
},
{
"key": "Pickup-Time",
"value": "14:00"
}
]
}
```
Success Response (200 Ok):
```
{
"url": "https://my-shop.myshopify.com/6324234/checkouts/0123456789abcdef0123456789abcdef"
}
```
Error Response (422 Unprocessable Entity):
```
{
"errors": [
{
"field": ["line_items"],
"message": "Some items are out of stock"
}
]
}
```
### `GET /restaurant/{restaurant}/menu/{menu}`
Retrieves the details of a specific menu for a restaurant.\
Status Codes:
* `200 OK`: Success.
* `404 Not Found`: Restaurant or menu not found.
Parameters:
* `restaurant` (integer): The restaurant ID.
* `menu` (integer): The menu ID.
Response:
```
{
"data": {
"id": 1,
"name": "Lunch Menu",
"menu_sections": [
{
"id": 1,
"name": "Starters",
"sort_order": 1,
"menu_section_items": [
{
"id": 101,
"sort_order": 1,
"product": {
"id": 501,
"name": "Garlic Bread",
"title": "Garlic Bread",
"variant_name": "Regular",
"image_url": "https://example.com/garlic-bread.jpg",
"variant_id": "1234567890",
"product_id": "9876543210",
"daily_limit": 50,
"orderCount": {
"variant_id": 1234567890,
"remaining": 45
},
"config": {
"preparation_time": 15,
"allergens": [
{ "id": 1, "name": { "en": "Gluten" } }
],
"dietry_restrictions": [
{ "id": 1, "name": { "en": "Vegetarian" } }
]
},
"variants": [
{
"id": 1234567890,
"limit": 50,
"title": "Regular"
}
]
}
}
]
}
]
}
}
```
# Data
Get and set data to the widget
## Delivery options
Available delivery options for the current zip code
### Get
```javascript
ZapietEats.getDeliveryOptions()
```
#### Example response
```json
{
"zipCode": 123456,
"settings": {
"all_restaurants_closed": false,
"pickup": {
"count": 1,
"estimated_ready_for_pickup_time": 15,
"restaurants": {
"current_page": 1,
"data": [
{
"id": 1,
"zapiet_id": 1,
"company_name": "Restaurant",
"address_line_1": "",
"address_line_2": "",
"phone": "",
"phone_formatted": "",
"postal_code": "",
"region": "",
"country_code": "",
"country_name": "",
"latitude": "",
"longitude": "",
"distance": "",
"max_radius": "",
"city": "",
"estimated_pickup_time": "",
"accepting_orders": true,
"status": "open",
"zone": null,
"menus": [
{
"id": 1,
"name": {
"en": "Menu"
},
"collection": {
"id": 1,
"zapiet_id": 1,
"external_id": "",
"account_id": 1,
"handle": "",
"title": "Menu 1",
"image": null,
"config": "{\"status\": true}",
},
"status": {
"store_pickup": true,
"local_delivery": true
}
}
],
"config": {
"tags": {
"store_pickup": [
"Store Pickup"
],
"local_delivery": [
"Local Delivery"
]
},
"pickup_rate": {
"rate_name": {
"en": "Pickup"
},
"max_radius": 0,
"rate_price": 0,
"phone_required": false,
"min_order_value": 0,
"rate_description": {
"en": null
},
"max_radius_enabled": false,
"free_pickup_enabled": false,
"estimated_pickup_time": 15,
"free_pickup_min_order_value": 0
}
}
}
],
"from": 1,
"last_page": 1,
"per_page": 3,
"to": 3,
"total": 3
}
},
"delivery": {
"estimated_delivery_time": 20,
"restaurant": {
"id": 1,
"zapiet_id": 1,
"company_name": "Restaurant",
"address_line_1": "",
"address_line_2": "",
"phone": "",
"phone_formatted": "",
"postal_code": "",
"region": "",
"country_code": "",
"country_name": "",
"latitude": "",
"longitude": "",
"distance": "",
"max_radius": null,
"city": "",
"estimated_pickup_time": "",
"accepting_orders": true,
"status": "open",
"zone": {
"id": 1,
"name": "Zone 1",
"config": {
"rate_name": {
"en": "Delivery"
},
"rate_price": 4.95,
"validation": {
"option": "postcode",
"max_radius": 0,
"eligible_post_codes": "",
"max_driving_distance": 0
},
"phone_required": false,
"min_order_value": 0,
"free_delivery_enabled": false,
"estimated_delivery_time": 20,
"free_delivery_min_order_value": 0
}
},
"menus": [
{
"id": 1,
"name": {
"en": "Menu"
},
"collection": {
"id": 1,
"zapiet_id": 1,
"external_id": "",
"account_id": 1,
"handle": "",
"title": "Menu",
"image": null,
"config": "{\"status\": true}",
},
"status": {
"store_pickup": true,
"local_delivery": true
}
}
],
"config": {
"tags": {
"store_pickup": [
"Store Pickup"
],
"local_delivery": [
"Local Delivery"
]
},
"pickup_rate": {
"rate_name": {
"en": "Pickup"
},
"max_radius": 0,
"rate_price": 0,
"phone_required": false,
"min_order_value": 0,
"rate_description": {
"en": null
},
"max_radius_enabled": false,
"free_pickup_enabled": false,
"estimated_pickup_time": 15,
"free_pickup_min_order_value": 0
}
}
}
}
}
}
```
## Delivery Option
Currently selected delivery option
### Get
```javascript
ZapietEats.getDeliveryOption()
```
#### Response
A string with the value `"pickup"` or `"delivery"`
### Set
#### Example call
```javascript
ZapietEats.setDeliveryOption("pickup")
```
#### Parameters
A string with the value `"pickup"` or `"delivery"`
## Restaurant
Currently selected restaurant
### Get
```javascript
ZapietEats.getRestaurant()
```
#### Example response
```json
{
"id": 1,
"zapiet_id": 1,
"company_name": "Restaurant",
"address_line_1": "",
"address_line_2": "",
"phone": "",
"phone_formatted": "",
"postal_code": "",
"region": "",
"country_code": "",
"country_name": "",
"latitude": "",
"longitude": "",
"distance": "",
"max_radius": "",
"city": "",
"estimated_pickup_time": "",
"accepting_orders": true,
"status": "open",
"menus": [
{
"id": 1,
"name": {
"en": "Menu"
},
"collection": {
"id": 1,
"zapiet_id": 1,
"external_id": "",
"account_id": 1,
"handle": "",
"title": "Menu 1",
"config": "{\"status\": true}"
},
"status": {
"store_pickup": true,
"local_delivery": true
}
}
],
"config": {
"tags": {
"store_pickup": [
"Store Pickup"
],
"local_delivery": [
"Local Delivery"
]
},
"pickup_rate": {
"rate_name": {
"en": "Pickup"
},
"max_radius": 0,
"rate_price": 0,
"phone_required": false,
"min_order_value": 0,
"rate_description": {},
"max_radius_enabled": false,
"free_pickup_enabled": false,
"estimated_pickup_time": 15,
"free_pickup_min_order_value": 0
}
}
}
```
### Set
#### Example call
```javascript
ZapietEats.setRestaurant(1)
```
#### Parameters
An integer with the restaurant's `zapiet_id`
## Menu
Currently selected menu
### Get
```javascript
ZapietEats.getMenu()
```
#### Example response
```json
{
"id": 1,
"name": {
"en": "Daily menu"
},
"collection": {
"id": 1,
"zapiet_id": 1,
"external_id": "1234564789",
"account_id": 1,
"handle": "daily-menu",
"title": "Daily menu",
"image": null,
"config": "{\"status\": true}"
},
"status": {
"store_pickup": true,
"local_delivery": true
}
}
```
### Set
#### Example call
```javascript
ZapietEats.setMenu(1)
```
#### Parameters
An integer with the menu's `zapiet_id`
## Language
Widget's current display language
### Get
```javascript
ZapietEats.getLanguage()
```
#### Response
A string with the widget's current language code
### Set
#### Example call
```javascript
ZapietEats.setLanguage("fr")
```
#### Parameters
An string with the language code
# Settings
Retrieve preferences set in the store admin
## Account
#### Method
```javascript
ZapietEats.getSettings()
```
#### Example response
```json
{
"pickup_enabled": true,
"delivery_enabled": true,
"logo": {
"src": "",
"width": 180,
"position": "center"
},
"animation": {
"enabled": true
},
"advanced": {
"show_closed_restaurants": true,
"show_restaurant_address": false,
"address_format": ""
},
"google": {
"enable_suggestion": false,
"enable_status_map": false
},
"company_name": "Company",
"language": "en",
"currency_code": "EUR",
"translations": {
"en": {...},
"config": []
}
}
```
## Widget
#### Method
```javascript
ZapietEats.getConfig()
```
#### Example Response
```json
{
"products": {
"enable_tag_section_name": false
},
"custom_styles": {
"enabled": false,
"value": ""
},
"selectors": {
"product_quantity": "[name=\"quantity\"]",
"product_add_to_cart": "[name=\"add\"]",
"product_add_to_cart_text": "[data-add-to-cart-text]",
"product_buy_now_button": "[class*=\"payment-button\"]",
"cart_checkout_button": "[name*=\"checkout\"]",
"cart_form": "form[action*=\"/cart\"]",
"cart_update_button": "[name=\"update\"]",
"cart_express_checkout": "[class*=\"payment-button\"]",
"product_plus_button": "[class*=\"js-qty__adjust--plus\"]",
"product_variant_select": "[name=id]",
"cart_quantity_select": "input[name*=\"updates\"]"
},
"google": {
"api_key": "",
"enable_suggestion": false,
"enable_status_map": false
}
}
```
# Last Mile API
Welcome to Zapiet's Last Mile API documentation
Documentation for Last Mile API
# Configuring a test store
In the Test stores section, you can enter a list of stores that can see and use the integration before it goes live for all merchants. This can be helpful for development and beta testing phases, or if you want to have a private integration. Enter URLs with the [myshopify.com](https://support.zapiet.com//myshopify.com) domain, and separate them with a comma without any spaces. For example, *teststore1.myshopify.com,teststore2.myshopify.com*.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543575/856a4c336dd34e660c6fc100/m_ip4CoRj9D55401xETVkU8Na8o0fw0dRQ.PNG-1619877817?expires=1725953400\&signature=7053d6b84f1fa13975c164fa619147c888baa30d3b8bd09a34e089cfed472dcc\&req=cSIiE819mIZaFb4f3HP0gJzG01k1TvWLuDIDsUw2uDGra56os5WfvjCpTSMJ%0AKuJdehwisSZM6fTbDw%3D%3D%0A)
Next up is the app setup overview
# App setup overview
In the App setup section of your integration, you can:
* Set up production and development endpoints
* Choose which endpoint you want to use
* Set up authentication
* Add settings for merchants
* Add packages
* Set up the requests we send to you
* Set up notifications when something goes wrong
To get to the App setup section, go to your integration, and click App Setup.
[](https://downloads.intercomcdn.com/i/o/688861450/4d912114e109b1a55d2f8d27/image.png?expires=1725953400\&signature=ba505f2b3ce93c68917e848871e8596ed2ca722fd4a393c0b9423c01103abcd9\&req=cigvHs9%2FmYRfFb4f3HP0gGMVG4p6BnLCHeTfP%2FvisxvcyvACfanUbnXUxftT%0AsJgWAM%2BDcleeXHZcUg%3D%3D%0A)
Let’s take a look at each section separately. First up, general endpoints.
***
# General endpoints
In the General section you can:
* Set your production and staging endpoints
* Choose which one you want to use now
* Select the content type of our requests
[](https://downloads.intercomcdn.com/i/o/688860235/0d39c3830ba62814c86c187d/image.png?expires=1725953400\&signature=1b06f3b0d710275beb327d0f00b49780b89ee3b8505800728d90d57c2930b9bc\&req=cigvHs9%2Bn4JaFb4f3HP0gKuA6V5b7OWrmmOwZDT4NT9sgpsybB5AXCO%2BPvmo%0AnFBo%2FwgAtPVkAXiExQ%3D%3D%0A)
## Status
You can select which endpoint you want to use: Staging or Production. Setting the status to production does not make your integration live for all merchants—it is merely lets you switch between 2 different endpoints. If you do not have a staging endpoint, you can have the same URL in both endpoint fields.
## Production endpoint
Set the endpoint that you want to use as a base for all requests when the status is set to Production. We recommend putting your merchant-facing endpoint here, for example *lmdprovider.app/api/v1\_0*.
## Staging endpoint
Set the endpoint that you want to use as a base for all requests when the status is set to Staging. We recommend putting your development endpoint here, for example *test.lmdprovider.app/api/v1\_0*.
### Note
You can override the base URL in each request if you need to.
## Content type
We support 2 content types:
* application/json
* application/x-www-form-urlencoded
We will use this content type for all requests, and we do not support different content types depending on the request yet.
Now that you’ve set up your general endpoints, let’s take a look at authentication.
# Authentication
We support four kinds of authentication:
* API key
* Bearer token (no refresh token)
* Basic flow
* OAuth
Merchants enter their authentication key when they first activate your integration.
[](https://downloads.intercomcdn.com/i/o/817684897/e1bbecd0103ab30738cd9c07/Screenshot+2023-08-29+at+9.06.47+AM.png?expires=1725953400\&signature=f283279af7a320b0b3ccb6735e5d0e3b6a97f654e33bc578bcdd48cd03107aaa\&req=fCEgEMF6lYhYFb4f3HP0gHm1WgYHVYKT70jDYDEwdCrxY8zBBFQvy842BcOu%0AI8cU3tGiU4I12%2FsRfw%3D%3D%0A)
***
## API key
You can have the merchant’s API key as a header or a query parameter. You can configure the field name, and add multiple headers if you need them.
[](https://downloads.intercomcdn.com/i/o/817685249/5de325d1864ef75ddfa8e15c/Screenshot+2023-08-29+at+9.07.57+AM.png?expires=1725953400\&signature=7dbb3c2b2897baf8541334b64cd049bb78f5bed58ee9ccb671ab41e528e1a640\&req=fCEgEMF7n4VWFb4f3HP0gGC%2FFcGmmzjD0bAp1TLgn2RR1hGYUhN7Qe7G5RRL%0AUQfa62qYTLnggrPdyg%3D%3D%0A)
If you need merchants to enter an additional authentication parameter like their username and password, you can add those by [creating settings](https://support.zapiet.com/en/articles/6280079-creating-settings) and using the variable as the value.
[](https://downloads.intercomcdn.com/i/o/817880560/533b9fc53c85a82541699383/432c0cd1-4855-425f-8603-1a27eb5ae39b.png?expires=1725953400\&signature=8246bfc1e310908f950040188e9eb5c22b99459b9f618365a92a70f73f640772\&req=fCEgHsF%2BmIdfFb4f3HP0gLRDbR2wMy02sz7P72iIHHnFr4IcuN1FmvQqiSdc%0ApoXiUT9zdojuwF4tDg%3D%3D%0A)
***
## Bearer token
We will automatically attach an Authorization header to your requests. We will add the merchant’s key after “Bearer”. We can only support bearer tokens that don’t expire, and we don’t support refresh tokens yet.
```
Authorization: Bearer YW5keTpjYXJnaW5keTpjYXJnaWxs
```
***
## Basic flow
We will automatically attach an Authorization header to your requests. We will add the merchant’s key after “Basic”.
```
Authorization: Basic YW5keTpjYXJnaWxs
```
***
## OAuth
When OAuth is selected, you need to specify the Authentication end point, the grant type and the scope that your API expects to receive.
[](https://downloads.intercomcdn.com/i/o/817686644/d00a543b6720022be368b97f/0ac03aec-a82c-43b4-9c76-6fdb434b4288.png?expires=1725953400\&signature=5b8cbdd4c897449b60cfa30f4b5488973f2f102c13530e88f8957abfaad67669\&req=fCEgEMF4m4VbFb4f3HP0gFAfyV%2BerdrhlcRSf2gz%2FfF4w21esZa7OEiDeS50%0ARP5lX99sZA%2BhjhwMvg%3D%3D%0A)
When OAuth is configured, customers will be asked to enter their Client ID and Client Secret to activate the integration.
[](https://downloads.intercomcdn.com/i/o/817687392/adffc36386c77e3460aefa8a/Screenshot+2023-08-29+at+9.11.49+AM.png?expires=1725953400\&signature=aa500a54b27793b18248cd48ffc916658ae540413b46e72cf57ada9f74cc0248\&req=fCEgEMF5nohdFb4f3HP0gCPm5z%2FeOs7cfGq8yxtELR%2FETfi%2Frq3uLh65CphF%0AyZDzta9arN2kpQ5chQ%3D%3D%0A)
# Creating settings
Our settings feature lets you create merchant-configurable settings. These settings will show when a merchant activates your integration in Zapiet - Pickup + Delivery.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543624/ca4b83273e6b7cf37b08a8c5/faglALapsdODgire1nSv_24WEzf5z_nWYg.PNG-1619961577?expires=1725953400\&signature=c3d9e4ce101b5af9d47b3bf7f8ea8baea8dc01c304d4227e369d6132e04162b3\&req=cSIiE819m4NbFb4f3HP0gKLwA6MAOYA8JAvOCqElOCgvpNcFcZY2XdZQsB1x%0AUKvReF1B77xE6BVtKw%3D%3D%0A)
You can use values merchants enter as variables in any request or a request header. These settings are often used to ask the merchant questions like:
* Do your orders order contain alcohol?
* Do your orders contain fragile items?
* Should we ask for ID on delivery?
## Creating a setting
You can choose between a few setting types:
* Text field
* Checkbox (True/False)
* Select
* Password
1. Go to the App Setup page.
[](https://downloads.intercomcdn.com/i/o/688861450/4d912114e109b1a55d2f8d27/image.png?expires=1725953400\&signature=ba505f2b3ce93c68917e848871e8596ed2ca722fd4a393c0b9423c01103abcd9\&req=cigvHs9%2FmYRfFb4f3HP0gGMVG4p6BnLCHeTFO%2F3riTGfIXCcSeTy8IWUX%2BiW%0AmII%3D%0A)
2. Click Add Setting.
[](https://downloads.intercomcdn.com/i/o/688898732/2e11930c1d9ad0de0a46193a/image.png?expires=1725953400\&signature=55d646a649a6bb01e8b8104d69cb74f5f2ad8691fb5ab803fa83f75ae645c377\&req=cigvHsB2moJdFb4f3HP0gNtpByyBaJy50SmXgeaZxWftQNgBV%2FKXFuQqcbMj%0AGa4%3D%0A)
3. Choose a setting type.
4. Enter a name and description for your setting.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543628/362e802943cba8075efd3076/lxZiGGwBgc1ZLnHfmrHBA45Fg_6NE5E1Ww.PNG-1619965166?expires=1725953400\&signature=4c6ef172b1d9650a274b1b4c0b4630011d6ebc3d84210d5d0be4514aff10fcb8\&req=cSIiE819m4NXFb4f3HP0gAKS9hxJp6fYiGRF4gtyopQ7fnoEyeYZtnYaCMif%0ApQY%3D%0A)
5. In this example, we are going to ask the merchant to select the type of vehicle they want to deliver their orders. The merchant must select from a pre-defined list of options. Click the "Select" field type and add the available options.\
6. Click Create setting.
7. Save changes at the top of the page.\
## Accessing settings in requests
Each setting will have its unique handle. You will see the handle below the setting name.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543630/fa2454c945e38b51fbff0009/HyVrmzRt0d0Je1VtqGOwZU6qNNhfPhEhYw.png-1619965564?expires=1725953400\&signature=9710ed67036d2cc69ef3c0b702aed7c6e03dd3c740265dee79b32f82d9f73f27\&req=cSIiE819m4JfFb4f3HP0gNmOUAXpXbygSgLs2pOmbG1qOyvWZMElKBADIwds%0Ag5URFnqFIOLBf1fn%2FA%3D%3D%0A)
You can access this value in any request including authentication headers by using the liquid variable:
```
{{ settings.customer_id }}
```
Let’s take a look at packages next.
# Creating packages
If you need to have packages in requests we send to you, you can define them in the Packages section. You can then use packaging variables in the requests to get the package the merchant chooses.
## Create a package
1. Go to the App Setup page
[](https://downloads.intercomcdn.com/i/o/688853206/4a3c7730b2fb8a4a54a2275c/image.png?expires=1725953400\&signature=0e3e2717ac4e7247e38101af67bf7fc2babf516460fd8a8d5fa6c58924001af4\&req=cigvHsx9n4FZFb4f3HP0gMiE4XpBA0D%2FW3TmwlB00W8uU%2FPkxJ7YsGSHrytp%0AVMw%3D%0A)
2. Click Add package\
[](https://downloads.intercomcdn.com/i/o/688853701/aa89c18992d4473e37463973/image.png?expires=1725953400\&signature=196ccd3da4940140a848cfe02b7b64be384a922fbd25e5d3ca3370ded46fcc15\&req=cigvHsx9moFeFb4f3HP0gJA%2Bloz%2Fxq9s5L2REFx3GgEohc3IlnzYX3%2Bixl1e%0AwEA%3D%0A)
3. Enter a package name that the merchants will see in the Name field
4. Enter the internal name for this package in Courier name
5. Enter the length, width, height, and the measurement unit
6. Choose whether you want to set that package as the default
7. Click Add Package\
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543715/95d7c97b285824e8a84ea17a/z4e_1Yda--VmaUKa3rGt9-PKdtBOW-wz2A.PNG-1619967421?expires=1725953400\&signature=ea42885cc114889122690815923aeb1a0a59155f73a5a084b369c02beb6c8998\&req=cSIiE819moBaFb4f3HP0gBxvw%2FOv%2BzIzyq47p0Q9k413hpeMgtIlbibsx1qs%0ALNs%3D%0A)
8. Save changes at the top of the page
## Merchant perspective
When you define packages, a merchant will see them on the integration page. They will be able to
* Select their default package
* Set the weight threshold for each package
[](https://downloads.intercomcdn.com/i/o/688855082/f42b9ac85997bc3d4a6fd894/image.png?expires=1725953400\&signature=fd9e00057e5f6e54f450f6875c0cec51607134ba494ce9549a1369c535e45f9c\&req=cigvHsx7nYldFb4f3HP0gKKkAU%2BCh3mJx%2FevD%2FhlxQw%2F6P%2FZlFgpU%2FMzUNue%0Ax5XyxFPQ183BsCXpxQ%3D%3D%0A)
## Variables
Please take a look at our [packaging variables](https://partners.zapiet.com/docs/last-mile/allowed-variables) in the variable guide. You can then reference them in requests like any other variable. For example, ####{{ package.length }}
Now it’s time to start creating requests—first one is the rate estimate.
# Rate estimate
Rate estimate request lets you show your delivery rates directly to customers.
## Rate request
We send a rate request when a customer goes to the rate page in Shopify checkout. To format the rate request:
1. Go to the App Setup page
[](https://downloads.intercomcdn.com/i/o/688861450/4d912114e109b1a55d2f8d27/image.png?expires=1725953400\&signature=ba505f2b3ce93c68917e848871e8596ed2ca722fd4a393c0b9423c01103abcd9\&req=cigvHs9%2FmYRfFb4f3HP0gGMVG4p6BnLCHeTFO%2F3riTGfIXCcSeTy8IWUX%2BiW%0AmII%3D%0A)
2. Click Rate estimate
[](https://downloads.intercomcdn.com/i/o/688862093/47358120074f928d95036593/image.png?expires=1725953400\&signature=221579bd2d31f73b92c84fc1cea842b85ebb43b9282605fc907adcd6e7eba04b\&req=cigvHs98nYhcFb4f3HP0gBZQbQhkQX5dRnUD7A48I4CCA%2Bem7rwBgzVqoQtP%0Ak1k%3D%0A)
First, choose between 2 rate modes:
* Manual
* Automatic
If you don’t want to offer rate estimates, you can set the rate mode to Manual. Merchants will then need to set up rates on their own. If you set the mode to Automatic, you will need to format the rate estimate request.
## Format the rate API Endpoint
The rate request is a POST to an endpoint of your choice. We will use your Staging/Production endpoint as the base, so you only need to add the missing path to your rate estimate endpoint.
[](https://downloads.intercomcdn.com/i/o/688862710/298bcedede2a7ad82d17ef92/image.png?expires=1725953400\&signature=91b3f848375c62b61842d96aa8436d98944216b027eedc5f37c44a9e5a0b41b1\&req=cigvHs98moBfFb4f3HP0gKAJhgtNIriQ4dGZg7cO5oKaWgbb%2F756eGMHdp0%2F%0Aae5UR%2Fh7jsWA2%2BsHUg%3D%3D%0A)
If your rate estimate endpoint is completely different than the general endpoint you set up earlier, just make sure you include https\:// in the URL.
[](https://downloads.intercomcdn.com/i/o/688863580/6418a7813edbcbcea530fa22/image.png?expires=1725953400\&signature=d241d1f0691ef20f419f8361bbcb9e58186adfa826acdd66b8e920c0951e349f\&req=cigvHs99mIlfFb4f3HP0gN%2BsUk%2BaaR2NxwKJyc22StlNobWco1CqZ5mUd8%2Bc%0AMI%2BfpH%2B0C3rIVjFrtQ%3D%3D%0A)
## Format the rate estimate request
The format of the request body needs to be valid JSON. We support liquid variables that are on our [rate estimate list](https://partners.zapiet.com/docs/last-mile/allowed-variables), and you can use any [liquid filter](https://shopify.dev/docs/themes/liquid/reference/filters). Here’s an example request that will be prefilled automatically for you:
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543687/e491488896efa902c0db28b8/mPNOO99jfApykRak7XeclDJ3jbO5cdYr7A.PNG-1620038518?expires=1725953400\&signature=ac4c36d2df062a4e1ddb830530b3595bd88d72e8bb1a2b765378a962cef8f07d\&req=cSIiE819m4lYFb4f3HP0gGQl5OsZxqBEWsg4IdlSNpAbNP8Idavr%2FqWMhal9%0AHB2VwGVR%2BBXFvtE%2FIQ%3D%3D%0A)
### Line item schema
If you need line items in your request, create the json for one line item in the Line item schema section. You can then pass the array of line items in the request body by using the ####{{ line\_items }} liquid variable.
## Rate response
Please return only 1 rate in your response.
### Rate identifier
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543688/fc7680b06c02de87d0b5b44b/jLJGuGLXu2aUPKdzemfc53lr-Pm081fIIg.png-1620043308?expires=1725953400\&signature=d5a5d659f80c5bddfa7733c79f543a66a048e5e581d30c362ea4f7cc9b0a7991\&req=cSIiE819m4lXFb4f3HP0gLa%2Blz8rSVMmbBWFIdJ3uysQ8a%2FFavA4ruNF8Ube%0AYcPWGSrM26XmKAIPOA%3D%3D%0A)
Enter the field name where you return the rate identifier. If you don’t have a rate identifier, leave the field blank.
### Rate price
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543691/77eca26fd6b59c9ddb944ced/ug5aW2zF_WDD6tOECsQlKAHniTvtYvCNzg.png-1620043460?expires=1725953400\&signature=aa100f69a7ab39bc9cb2dee29c8ffe506afc486ec3f571d0837e54a96d28cf1b\&req=cSIiE819m4heFb4f3HP0gNiVlNvnJq4b1Zg1TedauoxnSBlIXbryqUQNq5n9%0AOgrMlJihDkTuKTGqug%3D%3D%0A)
Select whether you return the price in Cents or Dollars, and enter the field name for the price
### Rate currency
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543693/143b474d0c32d0b0d2013c57/KZzskKQ2b_9qpvLpefpuGi0Pf7aEN5KD4g.png-1620043513?expires=1725953400\&signature=73ec3adaf50ae81d7834a18e8da9a8fe6391def39e535c6830225b606dcfc9fd\&req=cSIiE819m4hcFb4f3HP0gEqJ9WOdnvuzNLU6tXeTebCjtHc4T0nQoQ1hsqzI%0AVXxKqPpAu92kRh99uw%3D%3D%0A)
Enter the field name if you support multiple currencies, or the currency code if you return only one currency.
## Merchant perspective
When a merchant sets up your integration, they can choose:
* Whether they want to use your rates
* To offer free delivery after a certain threshold
* Name the rate however they want
* Adjust the handling fee
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543697/2a04471017e296850fc6eab2/rwq7AzW8IDFuU5hPHDRBUkk1KfDLpbeCRg.png-1620044343?expires=1725953400\&signature=93b76fe0220356e7e3d765b266ed0e1ddc973db7b95ff692eb7bb014d71ec416\&req=cSIiE819m4hYFb4f3HP0gHnb4h4sGxLJ9gM4dJpCpk5NqoSWWhG6OR9Yv1nA%0AS5hbsqHFrFVUKIW4yw%3D%3D%0A)
## Testing rates
The only way to test rates estimate is to go through Shopify checkout while using our app. If you would like us to give you a test environment that’s ready to go, send us an email at ..
# Creating a delivery
Create a delivery request that sends an order to your service.
***
## Create delivery
When an order is completed, our app will process it. As a part of our order processing, we send the order to you. The processing is usually instantaneous, though if the webhook fails we will send the order in up to 10 minutes from order creation. To format the Create delivery request:
1. Go to the App Setup page.
[](https://downloads.intercomcdn.com/i/o/688861450/4d912114e109b1a55d2f8d27/image.png?expires=1725953400\&signature=ba505f2b3ce93c68917e848871e8596ed2ca722fd4a393c0b9423c01103abcd9\&req=cigvHs9%2FmYRfFb4f3HP0gGMVG4p6BnLCHeTFO%2F3riTGfIXCcSeTy8IWUX%2BiW%0AmII%3D%0A)
2. Click Create delivery.
[](https://downloads.intercomcdn.com/i/o/688868426/88e808243966946c159e2473/image.png?expires=1725953400\&signature=bde98eee6a5d7e17e2e747cabe599377f983d1bbd808cceb17ca59b4da757531\&req=cigvHs92mYNZFb4f3HP0gOi7j9oN%2FpXXSBkRoSU5ndbeUMDm03E9oBQTnjtA%0AwzQ%3D%0A)
***
## Format the create delivery API endpoint
Create delivery request is a POST to an endpoint of your choice. We will use your Staging/Production endpoint as the base, so you only need to add the missing path to your Create delivery endpoint.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543639/7e1d667c76e6ab495fdfc010/C_0ohWEkGBtcGJWmKKJCBwrYleO96HaFCw.png-1620050168?expires=1725953400\&signature=a729a0bdb2793d92ff0ab876b9826b89a2c500783d3303665486f0cef56eec52\&req=cSIiE819m4JWFb4f3HP0gFZSYaG2XK35eogZJ%2FZQsLQLxv4QiE3B%2BhAfHT4e%0AWAIw9g%2Bl2y5NYxkoSg%3D%3D%0A)
If your Create delivery endpoint is completely different from the general endpoint, ensure you include https\:// in the URL.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543640/69b9ebd6c43bdb61b0c6b571/KU4wehk5JTV7bnXW083nC2sm-1gqhEhCBg.png-1620050262?expires=1725953400\&signature=a66d3c62185ee6f9360f38de8d23fb5b2a3ef3540268f72f98730898cab06c66\&req=cSIiE819m4VfFb4f3HP0gPDWH9tMdge9cVJzW99IcUoUcX0hdmtxnh5pl9g%2B%0A2YRq6uX6dsEO%2BYkzKQ%3D%3D%0A)
***
## Format the create delivery request
The format of the request body needs to be valid JSON. We support liquid variables that are on our create delivery list, and you can use any [liquid filter](https://shopify.dev/docs/themes/liquid/reference/filters). Here’s an example request that will be prefilled automatically for you:
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543642/3763821b46d86c3496fdfa64/ioRF3QFiy8POxeSyPZ6YYCiFbwcdPfcvIw.png-1620051317?expires=1725953400\&signature=ccdb1abe83fac1b1f6338ab4ac0ea633da52dc45c1ee20fade55af9269e00315\&req=cSIiE819m4VdFb4f3HP0gLsYZ5NiYbUYleJ9Vn1%2FY5Knnv6OB3Ls6Prvptmr%0AZgNsbgCCZsQ0JmNsRA%3D%3D%0A)
### Line item schema
If you need line items in your request, create the JSON for one line item in the Line item schema section. You can then pass the array of line items in the request body by using the ##{{ line\_items }} liquid variable.
***
## Create a delivery response
### Delivery ID
Your Create delivery response should have a "key" : "value" pair containing a unique identifier for a delivery order. Please enter the key from that key-value pair in the Delivery ID field. We will use it when checking order status updates or cancelling an order, and you can access it through the ##{{ courier.delivery.id }} variable.
[](https://downloads.intercomcdn.com/i/o/688871813/12cd8d42aeb341a75117f483/image.png?expires=1725953400\&signature=e1bae738f0fafa2c21e12a169c5030808a2861888cf37cb5ec4a1a4ad8d7d422\&req=cigvHs5%2FlYBcFb4f3HP0gNQasOij%2BIXFMN05Oz3xBzKHGHnRv4%2BMFhEO5hzQ%0AoNItfR17tSk3ao28qg%3D%3D%0A)
### Tracking details
In the Tracking number field, please enter the key from the response that contains your tracking number. In the Tracking URL field, please enter the key that contains your tracking URL. We will attach the tracking number and the URL when we process the order, if the merchant has enabled tracking details.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543646/76cc79443ee49de4ab11aacd/im0oUu2Ly7y14OO3m_hF-5D0QTGdq2hUSw.png-1620053637?expires=1725953400\&signature=96f91239f4c984ecb422270071b720ac3c86598e42f8c32b7f924377c3e55a70\&req=cSIiE819m4VZFb4f3HP0gKsSG712JMPjBAzOqg8aV2x61x8uPu7MrRZS3HJn%0A6sdf%2BCj7yFxDQp47IQ%3D%3D%0A)
If you don’t want to offer tracking details, leave both fields blank.
***
## Merchant perspective
When merchants connect to your service, they can choose:
* Which locations in Zapiet - Pickup + Delivery will use your service
* Whether they want to use tracking details
### Selecting a location
Merchants can have only one LMD provider per Zapiet - Pickup + Delivery location, and they can choose which locations each provider should serve.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543652/40c60801d89f8ca85729f666/MebWPYIL2MRneIxkdF6b7mmkkt-O_WfieQ.png-1620054098?expires=1725953400\&signature=c625495ac6e48d41963e0ed32a340816051f2368ffe4239a691db1b88483d8bf\&req=cSIiE819m4RdFb4f3HP0gPK4lpdVmABySIKfKE6JtDMum1nMaiT1YaVuVRgq%0AlWNRIfgCoajF7d%2FIVA%3D%3D%0A)
If the merchant is already using an LMD provider for a location, the location will be greyed out.
### Selecting tracking details
If you left tracking details in your Create delivery request blank, this section will not show. Merchant can select whether they want to
* Add tracking details
* Send tracking details to the customer
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543653/907aebe5d74760422e6a58dc/hWxPHfpoIYbhTNqRxU2jqmY-03kHcKch-Q.png-1620054310?expires=1725953400\&signature=b88f3e9e8568d8a6632547c11f67c1e5715c736280fcd5a63cd5c434e3677161\&req=cSIiE819m4RcFb4f3HP0gFS2ftj4jobMG275S8MMEnQZbKXF9%2Fa5bKl5K16x%0Av%2BcLzzeepOvMiXoliw%3D%3D%0A)
If Add \[LMD provider name] tracking details to Shopify order is enabled, we will automatically fulfil the order when processing it. This allows us to add the tracking number to the order and then poll your service for the order status. If Send tracking details to customer is enabled, we will send a Shipping confirmation email to the customer when fulfilling the order. That way the customer can get the tracking number and the tracking URL.
***
## Testing create delivery
If you have only one key in the authentication header, you can test the Create delivery request from the comfort of Zapiet Partners.
1. Go to App setup.
2. Click Create delivery.
3. Click Test request.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543655/eca988e79b51a2430b231509/64kANVqhuMegvm-4Q8t8dQCkUvlbaAHtKw.png-1620054921?expires=1725953400\&signature=5b0c1f6fb272b78d216ea68f5c1e10fde4df1ad1cd3954cf361dc3a4c8ca0ad1\&req=cSIiE819m4RaFb4f3HP0gAR0%2FAYJC35JCRPLHA4CCavXmGZaNFW8Kmoksf9h%0Aj9w%3D%0A)
4. Enter your API key in the API key field.
[](https://downloads.intercomcdn.com/i/o/688868988/de71b2e6a7b79b5a5435a65e/image.png?expires=1725953400\&signature=a847f62d480c4c5ab76f8dcb36d7a4d3aa8c240e53d41881a4511e5581f91544\&req=cigvHs92lIlXFb4f3HP0gNQ%2BzevOWBngwhgzLvD82efxKF8lC9ti%2FTB5NkBu%0AkG0%3D%0A)
5. Click Preview request.
You should now see the preview request you formatted earlier, with sample data instead of liquid variables. Click Send request and you’ll see the response from your service.
***
Let’s see how the delivery status works next.
# Delivery status
The delivery status request reflects the order status from your service in both Shopify and Zapiet - Pickup + Delivery.
## Webhook mode
To use webhooks for delivery status updates, you need to select “Webhook from carrier” from the dropdown menu within the Delivery Status endpoint settings.
Next, you need to create the URL that will be used for the webhook.
The base URL is
We recommend using your company name to avoid any issues, for example :\
Next, you need to generate an authentication token that will be sent with the web hook.
Next, you need to enter the key from the response object that contains the order status value.
Next, you need to specify each status value we can expect to receive.
## Polling request Mode
The request is called only if [tracking details](/last-mile-api/creating-a-delivery#h_5797d233e9) are enabled. We will send a request every 10 minutes after the tracking details have been added to the order. To format the Delivery status request:
1. Go to the App Setup page
[](https://downloads.intercomcdn.com/i/o/688861450/4d912114e109b1a55d2f8d27/image.png?expires=1725953400\&signature=ba505f2b3ce93c68917e848871e8596ed2ca722fd4a393c0b9423c01103abcd9\&req=cigvHs9%2FmYRfFb4f3HP0gGMVG4p6BnLCHeTFO%2F3riTGfIXCcSeTy8IWUX%2BiW%0AmII%3D%0A)
2. Click Delivery status
[](https://downloads.intercomcdn.com/i/o/688867222/385d9ef50ef3e8561385595e/image.png?expires=1725953400\&signature=adad2af74a40136d53b700ed47a0b71631c0722dc0e22e8551a7f391a2703b45\&req=cigvHs95n4NdFb4f3HP0gDayxNmK4yMg1R9Zgi2mp4%2BAvOWAbxbg9A3lE96y%0Ae0U%3D%0A)
### Endpoint
We accept GET and POST requests. If you need to, you can use ####{{ courier.delivery.id }} variable that you passed us in the Create delivery request. For the full list of allowed variables, check the Delivery status section of our [Allowed variables ](/last-mile-api/allow-variables-list)list.
Select "pull status every 5 minutes" from the dropdown menu as shown below:
### Response
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543677/d629b95608281392d3826c6d/GQyaw4AUE2mfZQ7A1rOTXUAT-zP7ltcfpQ.png-1621777941?expires=1725953400\&signature=abb4c55238ad6eb53dccaebbc013729751fbdf9a4936a3a1b5a24bc6209d02b8\&req=cSIiE819m4ZYFb4f3HP0gMm5%2FRmDIpthk%2BuS5Lm%2BIO3YLtpCf6eEjKJObix0%0AuIdz67mUsWo%2Bsf0xGA%3D%3D%0A)
For the response, we expect a single "key" : "value" pair. The key should be static, and the value can change depending on the status.
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543678/adefdf577a502097f70acfdc/_qvhILftNReUqXooIV9a9W-Mbai4ne3yuQ.png-1621778171?expires=1725953400\&signature=13cdd32b03537ed2715b4f0a1b01107d60d666dbbc10da4307061637af423858\&req=cSIiE819m4ZXFb4f3HP0gPN7EixA9964UbznNThdxDZoQYp2H9hFriUZvMpa%0A1rsXAWsqRUswXSc0HQ%3D%3D%0A)
Next, you need to specify each status value we can expect to receive.
# Cancel delivery
Our cancel delivery request can be used to cancel deliveries within your system.
You can use the POST or DELETE method to send the request to your cancel endpoint.
If you use the POST method, you can include a request body if it is required by your endpoint, if it is not required you can leave the body empty.
# Creating an integration
To connect your last mile delivery service to Zapiet - Pickup + Delivery, you must first create an integration.
1. Log in to your [Zapiet Partners](https://partners.zapiet.com/) account.
[](https://downloads.intercomcdn.com/i/o/569842143/02b8c64253b02872390b22a4/image.png?expires=1725953400\&signature=cbad0d54dbf1ca9ab6148c44638015a618b3215f2dccd8bc6ef3af7dbecfe97d\&req=cSYuHs18nIVcFb4f3HP0gLf8%2BpXD%2BsV35mGpWnkaKJ8lSoa0NxBEoDpxqFl3%0AshY%3D%0A)
2. Click Apps.
[](https://downloads.intercomcdn.com/i/o/689004390/ba0b640733e310461c838daf/image.png?expires=1725953400\&signature=5ff23e41d8f5c8c99677d5c569c8b83a983f21fc51ec4648bf7f7eab32712e4a\&req=ciguFsl6nohfFb4f3HP0gCDZxinMLk3dGavnrd21OD%2Fgv%2FwWeb7QyltkkryF%0AGhc%3D%0A)
3. Click Create an app.
[](https://downloads.intercomcdn.com/i/o/689004592/2b491c7a81f0df07ded292ab/image.png?expires=1725953400\&signature=f716cf916695e9a20901de4b87206105dc5af26b35d9b85a6ff177958a5c6171\&req=ciguFsl6mIhdFb4f3HP0gIF6KFRXyj4SKB7%2FLzOwrEL%2F%2BTcsfGTRCDQvr8e7%0AzCA%3D%0A)
4. Enter the name of your delivery service and select Last Mile Delivery as the app type.\
[](https://downloads.intercomcdn.com/i/o/689004899/ff4be9f6f456807fd8bdcb18/image.png?expires=1725953400\&signature=ba3b406a827a0e4a3828143b61bcb2d490b9b4674f7f9cc47b6fa42e94753093\&req=ciguFsl6lYhWFb4f3HP0gG3CAcWba0ErvbCNuN%2FV%2FN7cWOy4MNvsEfwhbXBp%0A1V4%3D%0A)
5. Click Create app.
[](https://downloads.intercomcdn.com/i/o/689005010/ff46b0a124833d2e891196cd/image.png?expires=1725953400\&signature=189896f3f7824784ecc43955faa87077bfb553cf584b3b5c92cdcb0794f193fc\&req=ciguFsl7nYBfFb4f3HP0gNUbZbul7GTHB1i3wX9ttnB2z%2BNeI5wUg7HOOAlz%0A6qQ%3D%0A)
The next step is to add basic information about the app on the App listing page.
# Writing app listing
The app listing page lets you:
* Add basic information about your page
* Select which countries your service covers
* Add test stores for development testing and beta testing
## App information
App information and the app icon show in Zapiet - Pickup + Delivery > Settings > Last mile delivery. In the development and beta phases, the integration will only be visible to stores you enter in the Test stores section. When the integration goes public, all merchants will see it.
[](https://downloads.intercomcdn.com/i/o/569773609/73c2b8454eb608d8bd98b5a0/image.png?expires=1725952500\&signature=eb658ce347d4989f09645a89940ae43ef3f2d09d7852f8f501434c78cd2ad103\&req=cSYuEc59m4FWFb4f3HP0gC%2FIaU30ZJgMgQPmZCd0zuCOc3UiiYdM2r7B5MI0%0A%2B4p0bLYsSpEwJ5oWOg%3D%3D%0A)
## Short description
A short description is a hook that helps merchants choose your app. Make it short, and include your unique selling point. For example, *Teleportation delivery within London*.
## Website
The website will show as a *Learn more* link. Merchants that discover your service from our app will most likely click that link, so we recommend creating a special page with clear signup steps.
## Contact email
The contact email is not visible right now, but we plan to make it easier for merchants to contact you when they have questions.
## App icon
App icon helps merchants recognize you on our Last mile delivery page. We recommend a 1200px by 1200px transparent PNG.
## Locations
You can add countries and regions where your service operates. While this is not yet a feature, we plan to show location-specific integrations only to merchants in those locations. If left blank, the integration will be visible to all merchants.
# Order status
The Last Mile API can automatically update an order's delivery status within Shopify. Our system will automatically poll your order status endpoint every 15 minutes to check for any status changes.
1. Edit your app and click Delivery status
[](https://downloads.intercomcdn.com/i/o/688867222/385d9ef50ef3e8561385595e/image.png?expires=1725953400\&signature=adad2af74a40136d53b700ed47a0b71631c0722dc0e22e8551a7f391a2703b45\&req=cigvHs95n4NdFb4f3HP0gDayxNmK4yMg1R9Zgi2mp4%2BAvOWAbxbg9A3lE96y%0Ae0U%3D%0A)
2. Enter your API endpoint for retrieving a delivery status\
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525543677/d629b95608281392d3826c6d/GQyaw4AUE2mfZQ7A1rOTXUAT-zP7ltcfpQ.png-1621777941?expires=1725953400\&signature=abb4c55238ad6eb53dccaebbc013729751fbdf9a4936a3a1b5a24bc6209d02b8\&req=cSIiE819m4ZYFb4f3HP0gMm5%2FRmDIpthk%2BuI4L%2B3Gse3N7tXdPPlOCQzHMEJ%0Aeok%3D%0A)
3. Tell the Last Mile API which field of your response contains the status value\
[](https://downloads.intercomcdn.com/i/o/689006752/cf6e8512bae5bda5ad6bf07e/image.png?expires=1725953400\&signature=8c7c90b7d02eb8e82b05d4d7e47ca38fee20c8ae3ab9c7762c3d46863a160dab\&req=ciguFsl4moRdFb4f3HP0gE%2BDpUO9%2FguuohrRJRUN2A0Jdic0x552YwJE7p6h%0Aw70%3D%0A)
4. Enter the value which should trigger a delivered status within Shopify\
[](https://downloads.intercomcdn.com/i/o/689006988/5b111d594d72890878d121a4/image.png?expires=1725953400\&signature=6276054b5ad543fc50396e12126143dcad6a0d05a3ade50679f7abdbe6ddbc4e\&req=ciguFsl4lIlXFb4f3HP0gDtys3O4IBl1vnH7EXDIeDnM6xv9fMQtyCfPLHet%0ASdU%3D%0A)
5. Enter the value which would trigger a delivery cancellation in Shopify
\
[](https://downloads.intercomcdn.com/i/o/689007097/a6294078a32e7e9faa75b54b/image.png?expires=1725953400\&signature=b5b5c75f11f76ac585360c7f24a16c93e76a9905ddf274b396a2ff4f28acd474\&req=ciguFsl5nYhYFb4f3HP0gK6%2FIBQbvaIuSnkqwV%2FD40oPHiyb3Nie9%2BNIXXc8%0ABGw%3D%0A)
6. Click Save\
[](https://downloads.intercomcdn.com/i/o/689007518/e94c71436f4780f6665f568d/image.png?expires=1725953400\&signature=014a04b6f6a54c5c32673612287cc8c0b188a65e4b1407c1afa6848a915c7f28\&req=ciguFsl5mIBXFb4f3HP0gIgQDsqrEru74rMXKN4636SogQEmGSizgZfB1Tvu%0A8V8%3D%0A)
# Tracking URLs
## Static tracking urls
If you provide a tracking url via your API then you should enter it's JSON key in the Tracking URL field as shown below:
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525530939/308919e192fbac8763aa8e5a/aBgk8HPGJrEjDtMouv2wpBA-guHYNfCLSg.png-1593365155?expires=1725953400\&signature=81abee09f0ff33b896f48318d778dab8a8d99238f0f45d559add001707476a70\&req=cSIiE8p%2BlIJWFb4f3HP0gBryuNqWGqiOJXtqFZLf9jrobq0FYi4JmwKbG1VK%0A5Qpg0eW7FrAy8hlyrw%3D%3D%0A)
In the example above we will automatically fetch the value contained within the "tracking\_url" parameter and attached this to the customer's order within Shopify.
***
## Dynamically generated tracking urls
If you do not include a tracking url via your API you can dynamically construct a url using liquid variables.\
[](https://zapiet-ltd-2e9268abd76f.intercom-attachments-7.com/i/o/525530940/5ec3fa083b8038a41f78c6d0/QV51dELd2HoLMM8hyjgRSqSljKCatyVrtw.png-1593364940?expires=1725953400\&signature=aaf9a895e85f33f6106db61bff18a71dcd26a6a45b78e610e328d375602df804\&req=cSIiE8p%2BlIVfFb4f3HP0gM2k%2FjMNSTTQ6TgGNA4gwXvd59cKbp3pmnbsAHAV%0AErwxIVLWkLEGtdEJpA%3D%3D%0A)
There are currently three variables available:
| Field name | Description | Example |
| ---------------- | ------------------------------------------------------------------------------ | ---------------- |
| id | Shopify's unique identifier for the order | 2206491738155 |
| external\_id | Your unique identifier for the order provided in your Delivery Create response | ABCDEFG12345 |
| tracking\_number | The tracking number provided in your Delivery Create response | RETHNKW354W3H438 |
# Allow variables list
| Field name | Notes | Example |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| id | Shopify internal order ID | 450789469 |
| name | Shopify order name | #10001 |
|
note
| The value of the special instructions / notes field | |
| delivery.customer.name | | Andrew Cargill |
| delivery.customer.first\_name |
The first name of the person associated with the delivery address.
| Andrew |
| delivery.customer.last\_name |
The last name of the person associated with the delivery address.
| Cargill |
| delivery.address.company\_name |
The company of the person associated with the delivery address.
| |
| delivery.address.address\_line\_1 |
The street address of the delivery address.
| |
|
delivery.address.address\_line\_2
|
An optional additional field for the street address of the delivery address.
| |
|
delivery.address.city
|
The city, town, or village of the delivery address.
| |
|
delivery.address.country
|
The name of the country of the delivery address.
| |
|
delivery.address.region
|
The name of the region (province, state, prefecture, …) of the delivery address.
| |
|
delivery.address.postal\_code
|
The postal code (zip, postcode, Eircode, …) of the delivery address.
| |
|
delivery.address.phone
|
The phone number at the delivery address.
| |
|
delivery.address.latitude
|
The latitude of the delivery address.
| |
|
delivery.address.longitude
|
The longitude of the delivery address.
| |
|
delivery.address.country\_code
|
The two-letter code (ISO 3166-1 format) for the country of the delivery address.
| |
|
delivery.address.region\_code
|
The two-letter abbreviation of the region of the delivery address.
| |
| delivery.datetime | The date and time the customer selected to receive their order. ISO 8601 format. | 2020-07-17T12:30:00+00:00 |
| delivery.start\_datetime | The earliest date and time the customer selected to receive their order. ISO 8601 format. |
2020-07-17T12:30:00+00:00
|
|
delivery.end\_datetime
| The latest date and time the customer selected to receive their order. ISO 8601 format. | 2020-07-17T13:00:00+00:00 |
| delivery.note | The variable for our delivery notes feature. | |
### Pickup details
| Field name | Notes |
An optional additional field for the street address of the delivery address.
| |
| pickup.address.city |
The city, town, or village of the delivery address.
| New York |
| pickup.address.country |
The name of the country of the delivery address.
| United States |
|
pickup.address.country\_code
| The two-letter code ([ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format) for the country of the delivery address. | US |
| pickup.address.region |
The name of the region (province, state, prefecture, …) of the delivery address.
|
New York
|
| pickup.address.postal\_code |
The postal code (zip, postcode, Eircode, …) of the delivery address.
|
10153
|
| pickup.address.region\_code |
The two-letter abbreviation of the region of the delivery address.
|
NY
|
| pickup.address.latitude |
Latitude of pickup location
|
53.3736828
|
| pickup.address.longitude |
Longitude of pickup location
|
-0.0160712
|
|
pickup.datetime
|
The date and time the order should be collected from the merchant. ISO 8601 format
| 2020-07-17T12:15:00+00:00 |
|
pickup.date
| YYYY-MM-DD | 2020-06-22 |
| pickup.time | HH:MM | 12:30 |
| pickup.address.custom\_attributes\_1 | | |
| pickup.address.custom\_attributes\_2 | | |
| pickup.address.custom\_attributes\_3 | | |
## Items
| Field name | Notes | Example |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| id | The ID of the item. |
669751112
|
| price |
The price of the item before discounts have been applied in the shop currency.
| 199.99 |
| grams |
The weight of the item in grams.
| 500 |
|
quantity
|
The number of items that were purchased.
| 5 |
| product\_id |
The ID of the product that the line item belongs to. Can be null if the original product associated with the order is deleted at a later date.
| 7513685 |
| sku |
The item's SKU (stock keeping unit).
| IPod-342-n |
| title |
The title of the product.
|
iPod Nano
|
| variant\_id |
The ID of the product variant.
| 4264112 |
| variant\_title |
The title of the product variant.
|
Pink
|
| vendor |
The name of the item's supplier.
| Apple |
|
name
|
The name of the product variant.
| iPod Nano - Pink |
## Settings
| Field name | Notes | Example |
| -------------------------------- | ----------------------------------------------------------------------------------- | ------- |
| settings.signature\_required | | true |
| settings.min\_age | | 21 |
| settings.notifications\_enabled | | false |
| settings.courier\_rates\_enabled | Whether the merchants want to use dynamically generated rates or manually configure | true |
## Courier
| Field name | Notes | Example |
| ------------------------------- | --------------------------------------------------------------------- | ------- |
|
courier.delivery.id
|
The last mile couriers unique identifier for the delivery
| 100001 |
# Phone number formatting
If your phone number validation is particularly sensitive you can use liquid filters to split off the country code from the rest of the number and format as required.
We've included an example below to help you get started:
```
{% assign firstchar = pickup.contact.phone | slice: 0 %}
{% if firstchar == "0" %}
{% assign phone = pickup.contact.phone | remove_first: "0" %}
{% else %}
{% assign phone = pickup.contact.phone | remove_first: "+358" %}
{% endif %}
```
You would then replace:
```
{{ pickup.contact.phone }}
```
with the following in your delivery create request.
```
{{ phone }}
```
If a customer were to now enter either of the following numbers: +358401234567, 0401234567 they would both become 401234567. You can then hardcode the country code in a separate field if your API allows or prepend the country value to the start of the string.
