Skip to content

Accessing pickup point details

Atlas Pickup Points saves pickup point details to the Shopify order metafield. We recommend treating our metafield as the source of truth for pickup point details.

In this guide we’ll cover how to access pickup point details via Shopify API.

How to access pickup point details via Shopify API?

Depending on your integration method, you can access pickup point details via webhooks or ShopifyGraphQL Admin API.

Webhooks

If you are receiving orders information trough webhooks, we recommend updating the webhook with our metafield namespace.

For example:

mutation WebhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) {
webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) {
userErrors {
field
message
}
webhookSubscription {
id
topic
endpoint {
__typename
... on WebhookHttpEndpoint {
callbackUrl
}
}
}
}
}
{
"id": "gid://shopify/WebhookSubscription/1234567890",
"webhookSubscription": {
"metafieldNamespaces": ["atlas_pickup_points"]
}
}

Then, your webhook payload with include metafields array, containing objects with namespace and key attributes set to atlas_pickup_points and point respectively. The value attribute will be a JSON string with pickup point details of the shape described below. See Shopify documentation for more information about webhook subscriptions.

GraphQL Admin API

To fetch order details with pickup point details, you can use the following query:

query GetOrder($orderId: ID!) {
order(id: $orderId) {
id
pickupPoint: metafield(namespace: "atlas_pickup_points", key: "point") {
jsonValue
}
}
}
{
"id": "gid://shopify/Order/1234567890"
}

Then, your response will include data object with order object. The order object will include pickupPoint object with jsonValue object containing the pickup point details in the shape described below. See Shopify documentation for more information about the Order object.

Example response

{
"data": {
"order": {
"id": "gid://shopify/Order/1234567890",
"pickupPoint": {
"jsonValue": {
"provider": "DPD",
"code": "GB12345",
"details": {
"name": "DPD Pickup Point",
"description1": "12 Grimmauld Place",
"description2": "next to the Order of the Phoenix headquarters"
},
"address": {
"address1": "12 Grimmauld Place",
"address2": null,
"city": "London",
"zip": "W1U 1DS",
"province": null,
"provinceCode": null,
"countryCode": "GB",
"latitude": 51.5194,
"longitude": -0.1268
},
"attributes": [
{
"key": "visible_for_muggles",
"value": false
},
{
"key": "secret_phrase",
"value": "the owl flies at midnight"
}
]
}
}
}
}
}

Structure of the pickup point metafield

The structure of the JSON object is as follows:

AttributeTypeDescription
providerStringPoints provider, typically carrier name
codeStringCarrier given identifier
detailsDetails objectPickup point details
addressAddress objectPickup point address
attributesAttributes object[]List of pickup point attributes - varies by carrier

Details object

AttributeTypeDescription
nameStringName of the pickup point
description1StringDescription
description2Nullable StringSecond line of the description

Address object

AttributeTypeDescription
address1StringFirst line of the address
address2Nullable StringSecond line of the address
cityStringCity
zipStringPostal code
provinceNullable StringProvince name
provinceCodeNullable StringProvince code
countryCodeStringCountry code ISO 3166-1 alpha-2
latitudeFloatLatitude
longitudeFloatLongitude

Attributes object

Attributes are carrier specific and are used to pass additional information about the pickup point.

AttributeTypeDescription
keyStringKey of the attribute
valueString / Boolean / NumberValue of the attribute