Skip to main content

​
Order Object

When a payment is successfully processed — via checkout session or payment link — an Order is created. 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_01ABC...",
  "checkout_id": "cs_abc123",
  "reference_id": "your-order-123",
  "payment_link_id": null,
  "client_reference_id": null,
  "status": "completed",
  "is_recurring": false,
  "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,
      "is_recurring": false
    }
  ],
  "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 (ord_xxx)
checkout_idstringCheckout session ID (cs_xxx)
reference_idstringYour order/cart reference — set for checkout session orders, null for payment link orders
payment_link_idstringPayment link ID — set for payment link orders, null for checkout session orders
client_reference_idstringYour reference passed via payment link — set for payment link orders, null for checkout session orders
statusenumFulfillment status (see below)
is_recurringbooleantrue if this is a subscription/recurring order, false for one-time purchases
payment_statusenumPayment state (see below)
amountintegerOrder total in cents
currencystringLowercase ISO currency code (e.g. usd)
customerobjectCustomer name and email
line_itemsarrayOrdered items (snapshot at time of purchase)
created_attimestampWhen order was created

​
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
is_recurringbooleanWhether this line item is a recurring/subscription item

​
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"
    }
  ]
}