Accessing pickup point details

When a buyer selects a pickup point, Atlas saves the details to an order metafield. This metafield is always active and requires no configuration. We recommend treating it as the source of truth for pickup point details.

• Metafield namespace: atlas_pickup_points
• Metafield key: point

If you need to pass pickup point data to third-party systems in other formats (order custom attributes, shipping address, or custom metafields), see How to get pickup point data into my fulfillment software. For a list of pre-integrated apps, see the Integrations page.

#Structure of the pickup point metafield

The metafield value is a JSON object with the following structure:

#Details object

#Address object

#Attributes object

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

#Provider enum

Possible values for the provider field:

AN_POST BOX_NOW BPOST BRING BUDBEE CESKA_POSTA CHRONOPOST COLIS_PRIVE COLISSIMO CORREOS CTT CUSTOM DAO DHL DHL_GLOBAL DPD DPD_BULGARIA DPD_FRANCE DPD_NETHERLANDS DROPP ECONT EVRI FAN_COURIER FEDEX FOXPOST GLS GLS_HUNGARY GLS_SPAIN HELTHJEM HRVATSKA_POSTA INPOST INSTABOX LATVIJAS_PASTS LIETUVOS_PASTAS MAGYAR_POSTA MATKAHUOLTO MEEST MONDIAL_RELAY OMNIVA ONE_BY_ALLEGRO ORLEN OVERSEAS_EXPRESS PACKETA PAXY POCZTA_POLSKA POST_AG POSTA_SLOVENIJE POSTE_ITALIANE POSTI POSTNL POSTNORD PPL RELAIS_COLIS ROYAL_MAIL SAMEDAY SENDCLOUD SEUR SEVEN_SENDERS SHIPPYPRO SLOVAK_PARCEL_SERVICE SLOVENSKA_POSTA SPEEDEX SPRING TNT UNISEND UPS VENIPAK

#Shopify API

You can access pickup point details via Shopify webhooks and the Shopify GraphQL Admin API.

#Webhooks

If you receive order data through webhooks, update the webhook subscription to include the Atlas metafield namespace. Subscribe to orders/create and orders/updated webhook topics.

For example:

mutation WebhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) {
  webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) {
    userErrors {
      field
      message
    }
    webhookSubscription {
      id
      topic
      uri
    }
  }
}

{
  "id": "gid://shopify/WebhookSubscription/1234567890",
  "webhookSubscription": {
    "metafieldNamespaces": ["atlas_pickup_points"]
  }
}

Your webhook payload will then include a metafields array containing an object with namespace set to atlas_pickup_points and key set to point. The value attribute is a JSON string with pickup point details in the structure described above. See Shopify documentation for more information about webhook subscriptions.

#GraphQL Admin API

To fetch an order 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"
}

The response will include a pickupPoint object with jsonValue containing the pickup point details in the structure described above. See Shopify documentation for more information about the Order object.

#Example response

{
  "data": {
    "order": {
      "id": "gid://shopify/Order/1234567890",
      "pickupPoint": {
        "jsonValue": {
          "provider": "CHRONOPOST",
          "code": "8912U",
          "details": {
            "name": "LIBRAIRIE PAPETERIE HENRI IV",
            "description1": "15 BOULEVARD HENRI IV, PARIS",
            "description2": null
          },
          "address": {
            "address1": "15 BOULEVARD HENRI IV",
            "address2": null,
            "city": "PARIS",
            "zip": "75004",
            "province": null,
            "provinceCode": null,
            "countryCode": "FR",
            "latitude": 48.851521,
            "longitude": 2.363166
          },
          "attributes": [
            {
              "key": "typeDePoint",
              "value": "P"
            }
          ]
        }
      }
    }
  }
}

#When Atlas writes data to the order

If your system imports orders as soon as they are created or paid, the timing below determines which pickup point data is available at each moment.

#The pickup point metafield

The timing depends on where the buyer selects the pickup point:

• Selection during checkout (Shopify Plus): Atlas saves the atlas_pickup_points.point metafield when the order is created. It is present in the orders/create webhook if your subscription includes the metafield namespace.
• Selection on the Thank you page: the order is created first, and Atlas saves the metafield when the buyer selects a pickup point. The metafield is empty in the orders/create webhook.
• Automatic selection: Atlas saves the metafield when it assigns the nearest pickup point, after the selection delay you configured.

#Order attributes, shipping address, and custom metafields

The optional outputs configured in the pickup point configuration (order custom attributes, the shipping address update, and custom metafields) are not part of the initial order. When the pickup point is selected during checkout, Atlas applies them within seconds after the order is created. When the pickup point is selected on the Thank you page or assigned by automatic selection, Atlas applies them at the same time as the metafield. In both cases Shopify sends an orders/updated webhook when they are applied. There is no configurable delay.

#Changes after order creation

• The pickup point may be changed by shop staff after the order is created. Shopify sends an orders/updated webhook when the pickup point is changed.
• A pickup point cannot be removed from an order once one is set. It can only be changed to another pickup point.
• If the buyer selects a pickup point but switches to a home delivery shipping option before completing checkout, the order is created without the metafield. If pickup point data still ends up on such an order, Atlas removes it within seconds after the order is created.