Custom endpoint
You can use a custom endpoint if you would like to offer pickup points that are not provided by our app. To get this to work, you will need the help of a developer. This guide is meant for developers.
How does it work?
When creating a pickup point rate, once you select Custom endpoint, you will be able to paste your endpoint URL. Each time pickup points are displayed, we will be making a GET request to that endpoint. Each request will be made with the following query parameters:
Parameter | Name | Description |
---|---|---|
lat | Latitude | Latitude of user shipping address or his position on the map |
lng | Longitude | Longitude of user shipping address or his position on the map |
country_code | Country code | Country code (ISO 3166-1 alpha-2) of user shipping address. It won’t change if user moves map to different country. |
q | Search query | Optional: search query on the list view, search can be enabled in Custom endpoint settings |
If your endpoint requires options, you can pass them as query parameters as well and they will be merged with above.
Your endpoint is expected to respond with JSON body, for example:
Response
Response object
Key | Required | Type | Description |
---|---|---|---|
locations | true | Location[] | Contains data of all available locations for requested lng/lat |
error_message | false | String | Error shown to the end user. Currently not surfaced in UI, but visible in network request response |
Location object
Key | Required | Type | Description |
---|---|---|---|
code | true | String | Carrier given identifier |
address | true | Address | |
details | true | Details | |
attributes | false | Attributes[] | List of additional attributes that will be passed to the order |
icon_url | false | String | URL to the icon that will be displayed on the map - should be PNG hosted on Shopify CDN |
Address object
Key | Required | Type | Description |
---|---|---|---|
address1 | true | String | The first line of the address: street and number |
address2 | false | String | Second line of the address |
city | true | String | City |
zip | true | String | Postal code |
country_code | true | String | Country code ISO 3166-1 alpha-2 |
latitude | true | Float | Latitude |
longitude | true | Float | Longitude |
Details object
Key | Required | Type | Description |
---|---|---|---|
name | true | String | Location name, displayed to end user |
description | false | String | Description of the location, displayed to end user |
business_hours | false | BusinessHour[] | List of opening hours, if unknown or 24/7 send empty array |
open_24_hours | false | Boolean | Is the location open 24/7? If unknown: send false |
BusinessHour object
Key | Required | Type | Description |
---|---|---|---|
day | true | Enum: MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY SUNDAY | Day of the week |
opening_time | true | String | Time in 24h format, for example: 1:00 or 23:49 |
closing_time | true | String | As above |
Attributes object
Key | Required | Type | Description |
---|---|---|---|
key | true | String | Key of the attribute |
value | true | String / Boolean / Number | Value of the attribute |
TypeScript type
Tips
We suggest using Cloudflare Workers for creating custom providers. If you need any guidance, feel free to reach out.
Changelog
20 Aug, 2024
- Added
country_code
query parameter
11 Jul, 2024
- We removed
features
property. Instead you can manage features within the pickup point rate settings.
12 Mar, 2024
- We removed
distance_meters
property. Instead we will calculate distance based on location lng / lat. If you respond withdistance_meters
- it will be ignored, you can remove it from your API.