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, 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
q	Search query	Search query on the list view

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:

{
  "error_message": null,
  "features": [],
  "locations": [
    {
      "code": "cp_napostu73572",
      "address": {
        "address1": "č.p. 374",
        "city": "Petrovice u Karviné",
        "zip": "73572",
        "country_code": "CZ",
        "latitude": 49.893486,
        "longitude": 18.54901
      },
      "details": { "description": null, "name": "Petrovice u Karviné" }
    },
    {
      "code": "cp_napostu73506",
      "address": {
        "address1": "nám. Budovatelů 1402/18",
        "city": "Karviná",
        "zip": "73506",
        "country_code": "CZ",
        "latitude": 49.866799,
        "longitude": 18.534439
      },
      "details": { "description": null, "name": "Karviná 6" }
    },
    {
      "code": "cp_napostu73401",
      "address": {
        "address1": "tř. Těreškovové 2233/28",
        "city": "Karviná",
        "zip": "73401",
        "country_code": "CZ",
        "latitude": 49.85728,
        "longitude": 18.557595
      },
      "details": { "description": null, "name": "Karviná 4" }
    }
  ]
}

Response

Response object

Key	Required	Type	Description
locations	true	Location[]	Contains data of all available locations for requested lng/lat
error_message	false	String	(not yet supported) Error shown to the end user
features	false	String[]	(not yet supported) If you don’t support map or list search, you can disable them by passing `MAP_UNAVAILABLE` or `SEARCH_UNAVAILABLE`

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 SVG 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: skip or send empty array
open_24_hours	false	Boolean	Is the location open 24/7? If unknown: skip

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

type CustomIntegrationResponse = {
  locations: {
    code: string;
    address: {
      address1: string;
      address2?: string | null | undefined;
      city: string;
      zip: string;
      longitude: number;
      latitude: number;
      province?: string | null | undefined;
      province_code?: string | null | undefined;
      country_code: string;
    };
    details: {
      name: string;
      description?: string | null | undefined;
      business_hours?:
        | {
            day: "MONDAY" | "TUESDAY" | "WEDNESDAY" | "THURSDAY" | "FRIDAY" | "SATURDAY" | "SUNDAY";
            opening_time: string;
            closing_time: string;
          }[]
        | null
        | undefined;
      open_24_hours?: boolean | null | undefined;
    };
    attributes?:
      | {
          [key: string]: string | number | boolean;
        }[]
      | null
      | undefined;
    icon_url?: string | null | undefined;
  }[];
  error_message?: string | null | undefined;
  features?: string[] | undefined;
};

Tips

We suggest using Cloudflare Workers for creating custom providers. If you need any guidance, feel free to reach out.

Changlog

12 Mar, 2024

We removed distance_meters property. Instead we will calculate distance based on location lng / lat. If you respond with distance_meters - it will be ignored, you can remove it from your API.