Integration and metafield specification
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.
How to access pickup point details via Shopify API?
Depending on your integration method, you can access pickup point details via webhooks or GraphQL 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", "topic": "ORDERS_CREATE", "endpoint": { "callbackUrl": "https://your-webhook-endpoint.com/webhook" }, "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 details.
Shopify 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.
Parsed example:
{ "data": { "order": { "id": "gid://shopify/Order/1234567890", "pickupPoint": { "jsonValue": { "provider": "INPOST", "code": "WAW29HP", "details": { "name": "Paczkomat WAW29HP", "description1": "al. Jerozolimskie 31, Warszawa", "description2": "w sklepie Duży Ben", "distance": "0.14 km" }, "address": { "address1": "al. Jerozolimskie 31", "address2": null, "city": "Warszawa", "zip": "00-508", "province": null, "provinceCode": null, "countryCode": "PL" } } } } }}
Structure of the pickup point metafield
The structure of the JSON object is as follows:
Attribute | Type | Description |
---|---|---|
provider | String | Points provider, typically carrier name |
code | String | Carrier given identifier |
details | Details object | Pickup point details |
address | Address object | Pickup point address |
attributes | Attributes object[] | List of pickup point attributes - varies by carrier |
Details object
Attribute | Type | Description |
---|---|---|
name | String | Name of the pickup point |
description1 | String | Description |
description2 | Nullable String | Second line of the description |
distance | String | Human readable distance in local format |
Address object
Attribute | Type | Description |
---|---|---|
address1 | String | First line of the address |
address2 | Nullable String | Second line of the address |
city | String | City |
zip | String | Postal code |
province | Nullable String | Province name |
provinceCode | Nullable String | Province code |
countryCode | String | Country code ISO 3166-1 alpha-2 |
Attributes object
Attribute | Type | Description |
---|---|---|
key | String | Key of the attribute |
value | String / Boolean / Number | Value of the attribute |