Skip to main content

​
Order Object

When a checkout session is successfully paid, it converts to an Order. Orders track payment status, fulfillment, and provide an immutable record of the transaction.
All monetary amounts are integers in cents (e.g., 4995 = $49.95).

​
The Order Object

{
  "id": "ord_abc123xyz",
  "order_number": "ORD-2025-001234",
  "checkout_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "reference_id": "your-order-123",
  "status": "completed",
  "payment_status": "captured",
  "customer": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1-555-123-4567",
    "shipping_address": {
      "address_line_1": "123 Main St",
      "address_line_2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "billing_address": {
      "address_line_1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  },
  "line_items": [
    {
      "id": "li_123",
      "product_id": "PROD-001",
      "name": "Digital Thermometer",
      "quantity": 1,
      "price": 2995,
      "hsa_fsa_eligible": true
    }
  ],
  "amounts": {
    "subtotal": 2995,
    "hsa_amount": 2995,
    "regular_amount": 0,
    "shipping": 995,
    "tax": 245,
    "discount": 0,
    "total": 4235
  },
  "payment": {
    "payment_id": "pay_xyz789",
    "payment_method": "hsa_fsa_card",
    "last4": "1111",
    "brand": "visa",
    "captured_at": "2026-02-25T15:30:00Z"
  },
  "metadata": {
    "order_number": "ORDER-12345",
    "platform": "CUSTOM"
  },
  "created_at": "2026-02-25T15:00:00Z",
  "completed_at": "2026-02-25T15:30:00Z",
  "status_history": [
    {
      "status": "pending",
      "timestamp": "2026-02-25T15:00:00Z",
      "reason": "Order created"
    },
    {
      "status": "processing",
      "timestamp": "2026-02-25T15:01:00Z",
      "reason": "Payment processing"
    },
    {
      "status": "completed",
      "timestamp": "2026-02-25T15:30:00Z",
      "reason": "Payment captured"
    }
  ]
}

​
Attributes

AttributeTypeDescription
idstringUnique order identifier
order_numberstringHuman-readable order number
checkout_idstringAssociated checkout session ID
reference_idstringYour order/cart ID (passed during checkout creation)
statusenumOrder status (see below)
payment_statusenumPayment status (see below)
customerobjectCustomer information with addresses
line_itemsarrayOrdered items (snapshot from checkout)
amountsobjectOrder totals
paymentobjectPayment information
metadataobjectCustom key-value pairs
created_attimestampWhen order was created
completed_attimestampWhen order was completed (null if pending)
status_historyarrayHistory of status changes

​
Amounts Object

FieldTypeDescription
subtotalintegerSum of all line item totals
hsa_amountintegerAmount payable with HSA/FSA
regular_amountintegerAmount requiring regular payment
shippingintegerShipping cost
taxintegerTax amount
discountintegerDiscount applied
totalintegerFinal total charged

​
Line Item Attributes

AttributeTypeDescription
idstringLine item identifier
product_idstringYour product ID
namestringProduct name
quantityintegerQuantity ordered
priceintegerUnit price in cents
hsa_fsa_eligiblebooleanWhether this item is HSA/FSA eligible

​
Order Status

StatusDescription
pendingOrder created, awaiting payment
processingPayment being processed
completedPayment successful, order complete
failedPayment failed
cancelledOrder cancelled

​
Payment Status

StatusDescription
pendingPayment not yet attempted
authorizedPayment authorized (not captured)
capturedPayment captured successfully
failedPayment failed
refundedPayment refunded (full or partial)
disputedPayment disputed/chargebacked

​
Order Lifecycle

An order moves through these states:
  • pending - Order created, awaiting payment
  • processing - Payment initiated
  • completed - Payment captured successfully
  • failed - Payment declined or failed
  • cancelled - Order cancelled by customer or merchant
  • refunded - Completed order was refunded (full or partial)
  • disputed - Completed order has a chargeback filed

​
Status History

Track all status changes: 
{
  "status_history": [
    {
      "status": "pending",
      "timestamp": "2026-02-25T15:00:00Z",
      "reason": "Order created"
    },
    {
      "status": "processing",
      "timestamp": "2026-02-25T15:01:00Z",
      "reason": "Customer submitted payment"
    },
    {
      "status": "completed",
      "timestamp": "2026-02-25T15:30:00Z",
      "reason": "Payment captured successfully"
    }
  ]
}