How to

Build guest order tracking

Let guests track their order status using the public order ID—without an account.

Build a guest order tracking page that resolves an order by its public ID and shows item, status, and delivery details—no login required. Useful for guest checkout and support deflection.

Prerequisites

Merchant API key
Public order IDs available from confirmation emails or receipts

Goal

Allow guests to retrieve order details by public ID
Show item list, totals, and lifecycle statuses safely

Architecture at a glance

UI form (enter public ID) → GraphQL getOrderPublic → render order summary and statuses
Handle not found/expired IDs; avoid leaking PII beyond order context

APIs used

Merchant API: https://merchantapi.geins.io/graphql

Step-by-step

Add input UI for public order ID

Create a simple form with a single input for the publicOrderId (GUID). Validate format client-side.

Request example

query getOrderPublic(
  $publicOrderId: Guid!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  getOrderPublic(
    publicOrderId: $publicOrderId
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  ) {
    orderId
    publicOrderId
    status
    created
    totals { grandTotal currency }
    customer { email }
    deliveryAddress { firstName lastName address1 zip city country }
    items {
      productId
      skuId
      name
      quantity
      price { unit total currency }
      status
    }
    shipments {
      carrier 
      method 
      trackingNumber 
      trackingUrl
      status
    }
  }
}

{
    "Accept": "application/json",
    "X-ApiKey": "{MERCHANT_API_KEY}"
}

{
  "publicOrderId": "{PUBLIC_ORDER_ID}",
  "channelId": "{CHANNEL_ID}",
  "languageId": "{LANGUAGE_ID}",
  "marketId": "{MARKET_ID}"
}

curl -X POST https://merchantapi.geins.io/graphql \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-ApiKey: {MERCHANT_API_KEY}" \
  -d '{"query":"query getOrderPublic($publicOrderId: Guid!, $channelId: String, $languageId: String, $marketId: String) { getOrderPublic(publicOrderId: $publicOrderId, channelId: $channelId, languageId: $languageId, marketId: $marketId) { orderId publicOrderId status created totals { grandTotal currency } customer { email } deliveryAddress { firstName lastName address1 zip city country } items { productId skuId name quantity price { unit total currency } status } shipments { carrier method trackingNumber trackingUrl status } } }","variables":{"publicOrderId":"{PUBLIC_ORDER_ID}","channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

The channelId, languageId, and marketId arguments are optional and can be left out to use default values.

Response example

200 OK

response.json

{ "data": 
  { "getOrderPublic": 
    { "publicOrderId": "...", 
      "status": "...", 
      "items": [ ... ] 
    }
  }
}

Render statuses and tracking

Map order status and item statuses to user-friendly labels.
If shipments[].trackingUrl exists, render a track button; else show method/carrier.
Mask sensitive data if needed (e.g., email partial).

Validation

Enter a known publicOrderId from a confirmation; verify order summary matches the confirmation.
Try an invalid/unknown GUID and show a clear, non-revealing error.

Related

Use multi-market support GetOrderPublic

Get user orders

Retrieve order history and details for authenticated users using Geins Merchant API

Handle canonical URLs

Learn how to handle canonical URLs and redirects in Geins Merchant API and Management API.