Skip to main content

​
Order Object

When a cart is successfully paid, it converts to an Order. Orders track payment status, fulfillment, and provide an immutable record of the transaction.

​
The Order Object

{
  "id": "ord_abc123xyz",
  "order_number": "ORD-2025-001234",
  "cart_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": "completed",
  "payment_status": "captured",
  "merchant_id": "mch_xyz789",
  "merchant_site_id": "site_abc123",
  "test_mode": false,
  "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",
      "zip": "10001",
      "country": "US"
    },
    "billing_address": {
      "address_line_1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    }
  },
  "line_items": [
    {
      "id": "li_123",
      "product_id": 12345,
      "merchant_product_id": "PROD-001",
      "name": "Digital Thermometer",
      "quantity": 1,
      "price_cents": 2995,
      "is_hsa_eligible": true,
      "eligibility_type": "auto_substantiation"
    }
  ],
  "amounts": {
    "subtotal_cents": 2995,
    "hsa_fsa_amount_cents": 2995,
    "regular_amount_cents": 0,
    "shipping_cents": 995,
    "tax_cents": 245,
    "discount_cents": 0,
    "total_cents": 4235
  },
  "payment": {
    "payment_id": "pay_xyz789",
    "payment_method": "hsa_fsa_card",
    "last4": "1111",
    "brand": "visa",
    "captured_at": "2025-10-18T15:30:00Z"
  },
  "metadata": {
    "order_number": "ORDER-12345",
    "platform": "SHOPIFY"
  },
  "created_at": "2025-10-18T15:00:00Z",
  "completed_at": "2025-10-18T15:30:00Z",
  "status_history": [
    {
      "status": "pending",
      "timestamp": "2025-10-18T15:00:00Z",
      "reason": "Order created"
    },
    {
      "status": "processing",
      "timestamp": "2025-10-18T15:01:00Z",
      "reason": "Payment processing"
    },
    {
      "status": "completed",
      "timestamp": "2025-10-18T15:30:00Z",
      "reason": "Payment captured"
    }
  ]
}

​
Attributes

AttributeTypeDescription
idstringUnique order identifier
order_numberstringHuman-readable order number
cart_idstringAssociated cart ID
statusenumOrder status (see below)
payment_statusenumPayment status (see below)
merchant_idstringYour merchant ID
merchant_site_idstringYour site ID
test_modebooleanWhether this is a test order
customerobjectCustomer information with addresses
line_itemsarrayOrdered items (snapshot from cart)
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

​
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 from cart, 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": "2025-10-18T15:00:00Z",
      "reason": "Order created from cart"
    },
    {
      "status": "processing",
      "timestamp": "2025-10-18T15:01:00Z",
      "reason": "Customer submitted payment"
    },
    {
      "status": "completed",
      "timestamp": "2025-10-18T15:30:00Z",
      "reason": "Payment captured successfully"
    }
  ]
}