What is an Order?

An Order is the central transactional entity generated when a customer completes checkout.

It represents a legally binding purchase contract between buyer and merchant, capturing line item quantities, captured payments, applied discount codes, shipping/billing addresses, and tax assessments.

The Order Lifecycle & Statuses

An order tracks two independent status dimensions:

1. Financial Status

  • pending: Payment authorization created, awaiting capture.
  • paid: Funds successfully captured from gateway.
  • refunded: Captured funds returned to customer.
  • voided: Authorization cancelled before capture.

2. Fulfillment Status

  • unfulfilled: Stock assigned, awaiting picking/packing in warehouse.
  • partially_fulfilled: Portion of line items shipped in split packages.
  • fulfilled: Carrier tracking label generated and dispatched.

Line Item Immutability

Developer Takeaway

Idempotent Order Creation: Always pass an idempotency_key (such as cart ID or payment intent ID) when creating orders via API to prevent duplicate order generation if a network timeout occurs during checkout submit.