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 in following format:
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
Implementation tips
Hosting options
For dynamic providers, we recommend using Cloudflare Workers:
- Fast global response times
- Free tier available
- Easy deployment and maintenance
For static locations (up to 50):
- Create a JSON file with your locations
- Upload it to Shopify CDN via the Content tab
- Use the CDN URL as your endpoint
Note: The CDN URL will change after each file update due to Shopify’s CDN versioning system. Make sure to update the endpoint URL in your settings after uploading a new version.
Troubleshooting
If you receive a CUSTOM_INTEGRATION_INVALID_RESPONSE
error:
- Open your browser’s Developer Tools
- Go to the Network tab
- Find the request to
/locations
endpoint - Inspect the response to see detailed error information
While we don’t assist with implementation, our support team is happy to help with debugging issues.
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.