Ordering Examples

The ordering workflow follows a specific sequence. Each step below is shown in order, from checkout initialization through cancellation.

Best Practices

• Generate a new clientRequestId for each checkout flow.
• Maintain the same clientRequestId across LeaseInventory, PreviewOrder, and CreateOrder.
• Only rotate clientRequestId after reaching a terminal state (order confirmed or failed).
• Set isGuestOrder: true when placing orders on behalf of guest accounts.
• Use associateTags to identify your partner source in every order (e.g., "affiliateName": "fever").
• For QR codes, use vendorQrCodeData from the order summary; fall back to vendorBookingId if unavailable.
• Set paymentProcessor to "PartnerPay" when your platform handles payment collection.
• Poll order status with a reasonable timeout (e.g., 10 seconds) before treating the order as failed.

---

1. Checkout Refresh

Initialize or refresh the checkout session for a showtime. Returns ticket types, pricing, survey details, and fees.

Request

curl -X POST \
  https://api-beta.atomtickets.com/ordering/v2/aggregation/checkout/refresh \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "showtimeId": "ST-20260214-1930-AMC4",
    "promotions": ["PARTNER10OFF"],
    "includeAreaCategory": true
  }'

Response

{
  "surveyDetailResponse": { ... },
  "showtimesResponse": {
    "showtimeId": "ST-20260214-1930-AMC4",
    "movieTitle": "The Last Frontier",
    "venueName": "AMC Loews Broadway 4",
    "startTime": "2026-02-14T19:30:00Z",
    "products": [
      {
        "productId": "PROD-ADULT-001",
        "name": "Adult",
        "price": 14.99,
        "offers": [
          { "offerId": "OFFER-STD-001", "name": "Standard", "price": 14.99 }
        ]
      }
    ]
  },
  "maxTicketQuantity": 10,
  "agePolicyLink": {
    "url": "https://www.atomtickets.com/age-policy",
    "label": "Age Policy"
  }
}

After refreshing checkout, use the showtimeId to discover the auditorium layout for seat selection.

---

2. Get Seat Layout

Retrieve the seating map for a showtime. Use this to display available seats to the user.

Request

curl -X GET \
  'https://api-beta.atomtickets.com/ordering/v1/discovery/auditoriums?showtimeId=ST-20260214-1930-AMC4&tickets=2' \
  -H 'x-api-key: {AtomPartnerApiKey}'

Response

{
  "layoutArea": {
    "rows": [
      {
        "rowLabel": "A",
        "seats": [
          {
            "seatId": "A1",
            "label": "A1",
            "status": "available",
            "seatType": "standard"
          },
          {
            "seatId": "A2",
            "label": "A2",
            "status": "available",
            "seatType": "standard"
          },
          {
            "seatId": "A3",
            "label": "A3",
            "status": "occupied",
            "seatType": "standard"
          }
        ]
      }
    ]
  },
  "legend": [
    { "type": "standard", "label": "Standard", "color": "#4CAF50" },
    { "type": "premium", "label": "Premium", "color": "#FF9800" }
  ],
  "occupiedSeats": {
    "A3": { "firstName": "J", "lastName": "D" }
  },
  "recommendedSeats": ["A1", "A2"],
  "numAvailable": 42
}

With the auditorium layout retrieved, create an account (guest or authenticated) before leasing seats.

---

3. Create Guest Account

Create a guest account for users who do not want to register. The response provides auth credentials for subsequent requests.

Request

curl -X POST \
  https://api-beta.atomtickets.com/ordering/v1/customer/account/guest \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "email": "guest@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "attributionMap": {
      "affiliateName": "fever",
      "campaign": "spring-2026"
    }
  }'

Response

{
  "authToken": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJHVUVTVC01NTAxMiJ9.signature",
  "accountId": "GUEST-55012",
  "identityId": "ID-99201",
  "identityValue": "guest@example.com"
}

---

4. Authenticate Existing User

Authenticate a returning user with existing credentials. Use this instead of guest account creation.

Request

curl -X POST \
  https://api-beta.atomtickets.com/ordering/v1/customer/account/authenticate \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "identityValue": "moviefan@example.com",
    "password": "userpassword123"
  }'

Response

{
  "token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJVU1ItODgyMzQifQ.signature",
  "accountId": "USR-88234",
  "identities": [
    {
      "identityId": "ID-44102",
      "identityValue": "moviefan@example.com",
      "type": "email"
    }
  ],
  "customer": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "atomToken": "atom-token-value",
  "privateKey": "private-key-value",
  "signupPromoId": "PROMO-SIGNUP-001"
}

From this point forward, all requests require authentication headers. Use the authToken/token, and generate the required signatures.

---

5. Lease Inventory (Reserve Seats)

Temporarily reserve selected seats. The lease locks the seats for a limited time while the user completes checkout. Use the same clientRequestId for this call, PreviewOrder, and CreateOrder.

Request

curl -X POST \
  https://api-beta.atomtickets.com/ordering/v1/inventory/lease \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -H 'X-Atom-Timestamp: 2026-02-13T12:00:00Z' \
  -H 'X-Atom-AuthToken: {authToken}' \
  -H 'X-Atom-DeviceSignature: {deviceSignature}' \
  -H 'X-Atom-Signature: {signature}' \
  -H 'X-Atom-DeviceId: partner-device-001' \
  -H 'X-Atom-AdId: partner-ad-001' \
  -d '{
    "clientRequestId": "req-a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
    "leaseItems": [
      {
        "productId": "PROD-ADULT-001",
        "offerId": "OFFER-STD-001",
        "seatIds": ["A1", "A2"]
      }
    ]
  }'

Response

{
  "leaseDurationSeconds": 600
}

Seats are held for leaseDurationSeconds (10 minutes). Proceed to preview and create the order before the lease expires.

---

6. Preview Order

Preview the full order with final pricing before committing. This step validates the order without charging.

Request

curl -X POST \
  https://api-beta.atomtickets.com/ordering/v2/customer/orders/preview \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -H 'X-Atom-Timestamp: 2026-02-13T12:00:00Z' \
  -H 'X-Atom-AuthToken: {authToken}' \
  -H 'X-Atom-DeviceSignature: {deviceSignature}' \
  -H 'X-Atom-Signature: {signature}' \
  -H 'X-Atom-DeviceId: partner-device-001' \
  -H 'X-Atom-AdId: partner-ad-001' \
  -d '{
    "orderParameters": {
      "lineItems": [
        { "productId": "PROD-ADULT-001", "offerId": "OFFER-STD-001", "quantity": 2 }
      ],
      "channel": "Partner",
      "clientVersion": "1.0.0",
      "clientRequestId": "req-a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
      "isGuestOrder": true,
      "paymentProcessor": "PartnerPay",
      "associateTags": {
        "affiliateName": "fever"
      }
    }
  }'

Response

{
  "receipt": {
    "subtotal": 29.98,
    "serviceFee": 3.5,
    "tax": 2.7,
    "totalAmount": 36.18,
    "currency": "USD",
    "lineItems": [
      {
        "productName": "Adult",
        "quantity": 2,
        "unitPrice": 14.99,
        "subtotal": 29.98
      }
    ]
  },
  "autoAddedItems": []
}

Review the receipt.totalAmount before creating the order.

---

7. Create Order

Commit the order. The payment is captured and tickets are issued.

Request

curl -X POST \
  https://api-beta.atomtickets.com/ordering/v1/customer/orders \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -H 'X-Atom-Timestamp: 2026-02-13T12:00:00Z' \
  -H 'X-Atom-AuthToken: {authToken}' \
  -H 'X-Atom-DeviceSignature: {deviceSignature}' \
  -H 'X-Atom-Signature: {signature}' \
  -H 'X-Atom-DeviceId: partner-device-001' \
  -H 'X-Atom-AdId: partner-ad-001' \
  -d '{
    "orderParameters": {
      "lineItems": [
        { "productId": "PROD-ADULT-001", "offerId": "OFFER-STD-001", "quantity": 2 }
      ],
      "channel": "Partner",
      "clientVersion": "1.0.0",
      "clientRequestId": "req-a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
      "isGuestOrder": true,
      "paymentProcessor": "PartnerPay",
      "associateTags": {
        "affiliateName": "fever"
      }
    }
  }'

Response

{
  "orderId": "ORD-12345",
  "eventId": "EVT-67890"
}

The order is now processing. Poll the order status endpoint to confirm fulfillment.

---

8. Poll Order Status

Poll this endpoint to check whether the order has been fulfilled by the vendor. Recommended polling interval is 2 seconds with a 10-second timeout.

Request

curl -X GET \
  https://api-beta.atomtickets.com/ordering/v1/customer/orders/ORD-12345/status \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -H 'X-Atom-Timestamp: 2026-02-13T12:00:00Z' \
  -H 'X-Atom-AuthToken: {authToken}' \
  -H 'X-Atom-DeviceSignature: {deviceSignature}' \
  -H 'X-Atom-Signature: {signature}' \
  -H 'X-Atom-DeviceId: partner-device-001' \
  -H 'X-Atom-AdId: partner-ad-001'

Response

{
  "orderStatus": "fulfilled",
  "orderStatusReason": null,
  "orderStatusReasonCode": null
}

Once the status is fulfilled, retrieve the full order summary for ticket details and QR codes.

---

9. Get Order Summary

Retrieve the complete order details including ticket barcodes and QR code data for theater entry.

Request

curl -X GET \
  https://api-beta.atomtickets.com/ordering/v2/customer/orders/ORD-12345/summary \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -H 'X-Atom-Timestamp: 2026-02-13T12:00:00Z' \
  -H 'X-Atom-AuthToken: {authToken}' \
  -H 'X-Atom-DeviceSignature: {deviceSignature}' \
  -H 'X-Atom-Signature: {signature}' \
  -H 'X-Atom-DeviceId: partner-device-001' \
  -H 'X-Atom-AdId: partner-ad-001'

Response

{
  "orderId": "ORD-12345",
  "eventId": "EVT-67890",
  "orderStatus": "fulfilled",
  "receipt": {
    "subtotal": 29.98,
    "serviceFee": 3.5,
    "tax": 2.7,
    "totalAmount": 36.18,
    "currency": "USD"
  },
  "venueInfo": {
    "name": "AMC Loews Broadway 4",
    "address": "1441 Third Street Promenade, Santa Monica, CA 90401"
  },
  "showtime": {
    "startTime": "2026-02-14T19:30:00Z",
    "auditorium": "Auditorium 7",
    "screenType": "IMAX"
  },
  "tickets": [
    {
      "seatLabel": "A1",
      "ticketType": "Adult",
      "price": 14.99,
      "vendorQrCodeData": "VNDR-QR-A1-ENC-7f8g9h0i1j2k3l4m5n6o",
      "vendorBookingId": "VNDR-BK-90210"
    },
    {
      "seatLabel": "A2",
      "ticketType": "Adult",
      "price": 14.99,
      "vendorQrCodeData": "VNDR-QR-A2-ENC-9k0l1m2n3o4p5q6r7s8t",
      "vendorBookingId": "VNDR-BK-90210"
    }
  ],
  "concessions": []
}

QR Code Handling

Use the vendorQrCodeData field from each ticket to generate QR codes for theater entry. If vendorQrCodeData is not present, fall back to the vendorBookingId at the order level.

---

10. Cancel Order

Cancel a confirmed order. Cancellation is only available if the showtime hasn’t passed.

Request

curl -X DELETE \
  https://api-beta.atomtickets.com/v1/customer/orders/ORD-12345 \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -H 'X-Atom-Timestamp: 2026-02-13T12:00:00Z' \
  -H 'X-Atom-AuthToken: {authToken}' \
  -H 'X-Atom-DeviceSignature: {deviceSignature}' \
  -H 'X-Atom-Signature: {signature}' \
  -H 'X-Atom-DeviceId: partner-device-001' \
  -H 'X-Atom-AdId: partner-ad-001'

Response

{
  "orderId": "ORD-12345",
  "cancellationStatus": "cancelled",
  "refundAmount": 36.18,
  "cancellationReason": "Customer requested cancellation"
}