Orders

Every order is a complete record of a transaction, from line items and customer data to payment state and fulfillment information. The APIs below give you precise control over the full order lifecycle, whether you're charging immediately or deferring payment until later.

The order object

An order object holds everything—the cart, payment intent, customer profile, and current state. You can create orders with inline customer data for one-time checkouts or reference saved customers and payment methods for frictionless repeat purchases.

Properties

checkout_settingsobjectOptional hosted-checkout redirects. Omitted when not configured.Click or tap to expand
- Name
  cancel_url
  Type
  string
  Description
  URL to redirect customers who cancel or abandon payment. Strongly recommended to handle cancellations gracefully.
- Name
  redirect_url
  Type
  string
  Description
  URL to redirect customers after successful payment. Strongly recommended for a seamless customer experience.
Name
canceled_at
Type
timestamp
Description
When the order was canceled. Omitted until cancellation.
Name
completed_at
Type
timestamp
Description
When the order was completed. Omitted until completion.
Name
custom_data
Type
object
Description
Your string key-value data. Omitted when empty.
customerobjectCustomer who placed this order.Click or tap to expand
- Name
  email_address
  Type
  string
  Description
  Email for receipts and updates.
- Name
  guest
  Type
  boolean
  Description
  Whether the customer was created as a guest during checkout.
- Name
  id
  Type
  string
  Description
  Customer ID.
- Name
  name
  Type
  string
  Description
  Full name for billing and communication.
- Name
  phone_number
  Type
  string
  Description
  Phone number for OTP and notifications.
Name
expires_at
Type
timestamp
Description
When the order expires. Omitted when no expiry applies.
Name
id
Type
string
Description
Unique identifier for this order—use it for lookups, updates, and payment operations.
Name
initiated_at
Type
timestamp
Description
When we started processing this order.
invoiceobjectHosted invoice links. Omitted while the order is a draft.Click or tap to expand
- Name
  format
  Type
  object
  Description
  Invoice viewing links.
  View format attributesClick or tap to expand
  Name
  pdf
  Type
  object
  Description
  PDF download.
  View pdf attributesClick or tap to expand
  Name
  url
  Type
  string
  Description
  Direct PDF link.
  Name
  web
  Type
  object
  Description
  Hosted page.
  View web attributesClick or tap to expand
  Name
  url
  Type
  string
  Description
  Web URL for viewing the invoice.
- Name
  number
  Type
  string
  Description
  Invoice number. Omitted when unset.
invoice_settingsobjectCustomer-facing invoice content. Omitted when not configured.Click or tap to expand
- Name
  custom_data
  Type
  object
  Description
  String key-value data. Omitted when empty.
- Name
  footer
  Type
  string
  Description
  Invoice footer. Omitted when unset.
- Name
  memo
  Type
  string
  Description
  Invoice memo. Omitted when unset.
- Name
  number
  Type
  string
  Description
  Invoice number. Omitted when unset.
line_item_groupobjectCart contents and totals.Click or tap to expand
- Name
  line_items
  Type
  array
  Description
  Array of products, fees, and shipping charges—each with a type discriminator.
  View line_items attributesClick or tap to expand
  Name
  fee
  Type
  object
  Description
  Fee details when type is fee—covers service charges, convenience fees, etc.
  View fee attributesClick or tap to expand
  Name
  amount
  Type
  object
  Description
  Fee amount.
  View amount attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Currency code.
  Name
  value
  Type
  integer
  Description
  Amount in smallest currency unit.
  Name
  description
  Type
  string
  Description
  Internal note about what this fee covers.
  Name
  id
  Type
  string
  Description
  Fee identifier.
  Name
  label
  Type
  string
  Description
  Customer-facing label for this fee.
  Name
  product
  Type
  object
  Description
  Product details when type is product.
  View product attributesClick or tap to expand
  Name
  about
  Type
  string
  Description
  Long-form description or marketing copy.
  Name
  custom_data
  Type
  object
  Description
  Your own key-value string pairs—exactly the same shape as the custom_data field in the API.
  Name
  id
  Type
  string
  Description
  Internal product ID for reconciliation and reporting.
  Name
  name
  Type
  string
  Description
  Product name shown to the customer.
  Name
  price
  Type
  object
  Description
  Per-unit price.
  View price attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Currency code.
  Name
  value
  Type
  integer
  Description
  Price in smallest currency unit.
  Name
  quantity
  Type
  integer
  Description
  How many units the customer is purchasing.
  Name
  reference
  Type
  string
  Description
  Your SKU or internal product reference.
  Name
  tax_code
  Type
  string
  Description
  Tax classification code for this item.
  Name
  type
  Type
  string
  Description
  Product type: cause, custom, digital, physical, service, or voucher.
  Name
  shipping
  Type
  object
  Description
  Shipping details when type is shipping.
  View shipping attributesClick or tap to expand
  Name
  fee
  Type
  object
  Description
  Shipping cost.
  View fee attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Currency code.
  Name
  value
  Type
  integer
  Description
  Amount in smallest currency unit.
  Name
  id
  Type
  string
  Description
  Unique ID for this shipping charge.
  Name
  type
  Type
  string
  Description
  Line item type: product, fee, or shipping.
- Name
  total
  Type
  object
  Description
  Sum of all line items after any adjustments.
  View total attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  ISO currency code. Supported values for order creation are ghs, usd, gbp, eur, and cny.
  Name
  value
  Type
  integer
  Description
  Amount in smallest unit (cents, pesewas, etc.).
Name
number
Type
string
Description
Human-friendly reference like ORDER-1234 for your internal systems and customer communication.
paymentobjectPayment intent tied to this order.Click or tap to expand
- Name
  amount
  Type
  object
  Description
  Total amount being charged.
  View amount attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Currency code. Supported values for order creation are ghs, usd, gbp, eur, and cny.
  Name
  value
  Type
  integer
  Description
  Amount in smallest unit.
- Name
  balance_transaction
  Type
  object
  Description
  Ledger entry created once the payment settles. Omitted until available.
  View balance_transaction attributesClick or tap to expand
  Name
  amount
  Type
  object
  Description
  Net funds that hit your balance for this payment.
  View amount attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Currency code. Supported values for order creation are ghs, usd, gbp, eur, and cny.
  Name
  value
  Type
  integer
  Description
  Amount in smallest unit.
  Name
  available_at
  Type
  timestamp
  Description
  When the funds become available for payout. Omitted until known.
  Name
  created_at
  Type
  timestamp
  Description
  When the balance transaction was created.
  Name
  id
  Type
  string
  Description
  Balance transaction ID.
  Name
  order_id
  Type
  string
  Description
  Order that created this balance transaction.
  Name
  claimed_at
  Type
  timestamp
  Description
  When the funds were claimed for payout. Omitted until claimed.
  Name
  paid_at
  Type
  timestamp
  Description
  When the payout was completed. Omitted until paid.
  Name
  payment_id
  Type
  string
  Description
  Payment this transaction is tied to.
  Name
  payout_configuration
  Type
  object
  Description
  Payout routing instructions for this transaction. Present only when order-level payout_settings was specified during order creation.
  View payout_configuration attributesClick or tap to expand
  Name
  destination
  Type
  object
  Description
  Where funds will be paid out.
  View destination attributesClick or tap to expand
  Name
  financial_account_id
  Type
  string
  Description
  Financial account that will receive the payout.
  Name
  enable_fx
  Type
  boolean
  Description
  Whether foreign exchange conversion is enabled for this payout.
  Name
  payout_id
  Type
  string
  Description
  Payout that will disburse the funds. Omitted until scheduled.
- Name
  canceled_at
  Type
  timestamp
  Description
  When payment was canceled. Omitted until canceled.
- Name
  due_at
  Type
  timestamp
  Description
  When payment is due. Omitted when unset.
- Name
  executed_at
  Type
  timestamp
  Description
  When payment execution began. Omitted until execution.
- Name
  expired_at
  Type
  timestamp
  Description
  When payment expired. Omitted until expired.
- Name
  failed_at
  Type
  timestamp
  Description
  When payment failed. Omitted until failed.
- Name
  id
  Type
  string
  Description
  Payment intent ID—use this to track and update payment state.
- Name
  initiated_at
  Type
  timestamp
  Description
  When we kicked off the payment intent.
- Name
  latest_attempt
  Type
  object
  Description
  Details about the most recent charge attempt. Omitted before the first attempt.
  View latest_attempt attributesClick or tap to expand
  Name
  error
  Type
  object
  Description
  Attempt error details. Omitted when no error is available.
  Name
  initiated_at
  Type
  timestamp
  Description
  When this attempt started.
  Name
  payment_method_id
  Type
  string
  Description
  Payment method that was charged.
  Name
  payment_method_type
  Type
  string
  Description
  Payment rail used for this attempt.
  Name
  reference
  Type
  string
  Description
  Gateway reference or transaction ID.
  Name
  status
  Type
  string
  Description
  Attempt status: pending, succeeded, failed, etc.
  Name
  succeeded_at
  Type
  timestamp
  Description
  Set when the attempt succeeds. Omitted otherwise.
- Name
  next_action
  Type
  object
  Description
  What needs to happen next to complete the payment.
  View next_action attributesClick or tap to expand
  Name
  confirm_payment
  Type
  object
  Description
  OTP confirmation flow details.
  View confirm_payment attributesClick or tap to expand
  Name
  expires_at
  Type
  timestamp
  Description
  When this OTP token expires.
  Name
  request
  Type
  object
  Description
  Details about the OTP we sent.
  View request attributesClick or tap to expand
  Name
  id
  Type
  string
  Description
  Unique ID for this OTP delivery.
  Name
  recipient
  Type
  string
  Description
  Phone number or email that received the token.
  Name
  sender_id
  Type
  string
  Description
  Sender name shown to the customer (e.g., zverify).
  Name
  sent_via
  Type
  string
  Description
  Delivery channel: sms or email.
  Name
  token_size
  Type
  integer
  Description
  Length of the OTP code (usually 6).
  Name
  scheme
  Type
  string
  Description
  Auth scheme: typically zcommerce_defined_auth.
  Name
  type
  Type
  string
  Description
  Action required: confirm_payment, authorize_payment, etc.
- Name
  paid_at
  Type
  timestamp
  Description
  When funds were fully captured and marked as paid. Omitted until paid.
- Name
  paid_offline
  Type
  boolean
  Description
  Whether payment was recorded out of band. Omitted when unavailable.
- Name
  payment_method
  Type
  object
  Description
  The payment method being charged.
  View payment_method attributesClick or tap to expand
  Name
  created_at
  Type
  timestamp
  Description
  When this method was added.
  Name
  customer_id
  Type
  string
  Description
  Which customer owns this payment method.
  Name
  id
  Type
  string
  Description
  Saved payment method ID.
  Name
  mobile_money
  Type
  object
  Description
  Mobile money details. Present when type is mobile_money.
  View mobile_money attributesClick or tap to expand
  Name
  account_number
  Type
  string
  Description
  Masked account number.
  Name
  network
  Type
  string
  Description
  Wallet network: airtel, mtn, telecel, or vodafone.
  Name
  type
  Type
  string
  Description
  Payment rail: mobile_money, card, bank_account, etc.
  Name
  verified
  Type
  boolean
  Description
  Whether the payment method passed verification.
  Name
  verified_at
  Type
  timestamp
  Description
  When verification completed. Omitted if not verified.
- Name
  payout_configuration
  Type
  object
  Description
  Payout routing instructions for this payment. Present only when order-level payout_settings was specified during order creation.
  View payout_configuration attributesClick or tap to expand
  Name
  destination
  Type
  object
  Description
  Where funds will be paid out.
  View destination attributesClick or tap to expand
  Name
  financial_account_id
  Type
  string
  Description
  Financial account that will receive the payout.
  Name
  enable_fx
  Type
  boolean
  Description
  Whether foreign exchange conversion is enabled for this payout.
- Name
  statement_descriptor
  Type
  string
  Description
  Optional statement descriptor shown on the customer's bank statement.
- Name
  status
  Type
  string
  Description
  Payment state: requires_action, processing, succeeded, failed, etc.
Name
receipt_number
Type
string
Description
Merchant-supplied receipt reference for reconciliation. Omitted when unset; Commerce does not enforce uniqueness.
Name
paid_at
Type
timestamp
Description
When the order was paid. Omitted until paid.
Name
payment_due_at
Type
timestamp
Description
When payment is due. Omitted when no due time was supplied.
payout_settingsobjectOrder-specific payout settings. Omitted when not configured.Click or tap to expand
Name
reference
Type
string
Description
Public order reference. Omitted when unset.
Name
sealed_at
Type
timestamp
Description
When the order was finalized and became immutable—ready for payment or fulfillment.
shippingobjectShipping details. Omitted when unavailable.Click or tap to expand
- Name
  address
  Type
  object
  Description
  Where to send the package.
  View address attributesClick or tap to expand
  Name
  country
  Type
  string
  Description
  Country.
  Name
  city
  Type
  string
  Description
  City or town.
  Name
  line1
  Type
  string
  Description
  Street address line 1.
  Name
  line2
  Type
  string
  Description
  Street address line 2 (optional).
  Name
  name
  Type
  string
  Description
  Recipient name.
  Name
  phone_number
  Type
  string
  Description
  Contact number for delivery.
  Name
  post_code
  Type
  string
  Description
  Postal/ZIP code.
  Name
  region
  Type
  string
  Description
  State, province, or region.
Name
status
Type
string
Description
Current lifecycle state: requires_payment, paid, completed, etc.

Create an order

Create a new order for a first-time or returning customer, and decide whether to charge it now or later. Product line items can be fully inline, or they can reuse products and prices you already keep in your catalog.

Clients should treat the published route in this reference as authoritative and should not construct alternative order-creation paths.

Rules

Exactly one of customer_id or customer_data is required.
Set execute_payment to true only when a payment method is attached (payment_method_id or payment_method_data). Omit it or pass false to create the order first and charge it later.
Every line item in the request must use the same currency.
Product line items support three valid shapes: inline product data, product_id plus explicit price, or product_id plus price_id.
When you send product_id, Commerce snapshots the current catalog product onto the order. Do not combine product_id with inline product fields such as name, type, about, reference, tax_code, or custom_data.
When you send product_id, you must also send either price or price_id. Do not send both. Commerce does not infer the amount from the product's default unit price.
When provided, receipt_number is trimmed, must satisfy the same configured length limits as number, and does not need to be unique.
To make retries safe, send a stable request_meta.idempotency_key or the Idempotency-Key header. Same-key retries with the same operation payload replay the original success; same-key retries with a different operation payload return idempotency_key_conflict.

Required attributes

line_itemsarrayCart contents. Provide at least one line item per order.Click or tap to expand
- Name
  type
  Type
  string
  Description
  Discriminator for each entry: product, fee, or shipping. Matches the schemas in our OpenAPI spec.
- Name
  product
  Type
  object
  Description
  Required when type is product. Use one of three shapes: inline product data, product_id with explicit price, or product_id with price_id.
  View product attributesClick or tap to expand
  Name
  about
  Type
  string
  Description
  Marketing copy or long-form description. Only used for inline product data.
  Name
  custom_data
  Type
  object
  Description
  Key-value strings for your own custom data. Only used for inline product data.
  Name
  name
  Type
  string
  Description
  Customer-facing label for the product. Only used for inline product data.
  Name
  price
  Type
  object
  Description
  Per-unit price. Use this for inline product data or when overriding the amount for a catalog-backed product line item.
  View price attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Lowercase ISO 4217 currency code. Supported values for order creation are ghs, usd, gbp, eur, and cny.
  Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit (pesewas, cents, etc.).
  Name
  price_id
  Type
  string
  Description
  Existing catalog price to use for this line item. It must belong to the same product referenced by product_id. Do not combine this with price.
  Name
  product_id
  Type
  string
  Description
  Existing catalog product to snapshot onto the order line item.
  Name
  quantity
  Type
  integer
  Description
  Number of units being purchased (minimum 1). Required for every product line item shape.
  Name
  reference
  Type
  string
  Description
  Your SKU or internal reference. Only used for inline product data.
  Name
  tax_code
  Type
  string
  Description
  Tax classification code for this item. Only used for inline product data.
  Name
  type
  Type
  string
  Description
  cause, custom, digital, physical, service, or voucher. Only used for inline product data.
- Name
  fee
  Type
  object
  Description
  Required when type is fee. Use this for service or technology charges.
  View fee attributesClick or tap to expand
  Name
  id
  Type
  string
  Description
  Fee identifier.
  Name
  label
  Type
  string
  Description
  Customer-facing label, e.g., "Service Fee".
  Name
  tax_code
  Type
  string
  Description
  Tax classification code for this fee.
  Name
  description
  Type
  string
  Description
  Explain why the fee is being charged.
  Name
  amount
  Type
  object
  Description
  Fee amount (uses the same Money schema).
  View amount attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Lowercase ISO 4217 currency code.
  Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit.
- Name
  shipping
  Type
  object
  Description
  Required when type is shipping. Captures fulfillment charges.
  View shipping attributesClick or tap to expand
  Name
  id
  Type
  string
  Description
  Unique ID for this shipping charge.
  Name
  tax_code
  Type
  string
  Description
  Tax classification code for the shipping fee.
  Name
  fee
  Type
  object
  Description
  Shipping cost (Money schema).
  View fee attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Lowercase ISO 4217 currency code.
  Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit.
customer_dataobjectInline customer profile for first-time buyers. Mutually exclusive with customer_id.Click or tap to expand
- Name
  name
  Type
  string
  Description
  Full customer name exactly as it should appear on invoices and receipts.
- Name
  email_address
  Type
  string
  Description
  Primary email—used for invoices, receipts, and payment notifications.
- Name
  phone_number
  Type
  string
  Description
  Phone number in international format so we can deliver OTPs or status updates.
- Name
  reference
  Type
  string
  Description
  Optional internal reference or CRM ID for this customer.
- Name
  custom_data
  Type
  object
  Description
  Free-form key/value strings for attaching custom attributes (e.g., customer segment).
Name
customer_id
Type
string
Description
Reference an existing customer. Mutually exclusive with customer_data.

Product line item shapes

Use the shape that matches how you manage your catalog and pricing:

Inline product data

{
  "type": "product",
  "product": {
    "name": "Utility Sneakers",
    "type": "physical",
    "quantity": 1,
    "price": { "currency": "ghs", "value": 20000 }
  }
}

Catalog product with explicit price

{
  "type": "product",
  "product": {
    "product_id": "prod_abc123xyz",
    "quantity": 2,
    "price": { "currency": "usd", "value": 4100 }
  }
}

Catalog product with saved catalog price

{
  "type": "product",
  "product": {
    "product_id": "prod_abc123xyz",
    "price_id": "pr_xyz789",
    "quantity": 2
  }
}

When you reference product_id, Commerce snapshots the product data onto the order at creation time. Later edits to the catalog product or price do not rewrite an order that already exists. You can also mix catalog-backed and inline product line items in the same order, as long as every line item uses the same currency.

The full request examples below use inline product data for broad SDK compatibility. If you already keep products and prices in your catalog, replace the product payload with either catalog-backed shape shown above.

Optional attributes

request_metaobjectRequest-specific controls that do not change the order being created.Click or tap to expand
- Name
  idempotency_key
  Type
  string
  Description
  Stable key for this logical order creation. Use the same key when retrying after a timeout or network failure.
Name
payment_method_id
Type
string
Description
ID of a saved payment method to charge. Only works with customer_id—the method must belong to that customer.
Name
receipt_number
Type
string
Description
Optional merchant-supplied receipt reference for reconciliation. Commerce trims whitespace, applies the same configured length validation used for number, and does not enforce uniqueness.
Name
statement_descriptor
Type
string
Description
Exact descriptor shown on the customer's bank or mobile money statement. Mutually exclusive with statement_descriptor_prefix.
Name
statement_descriptor_prefix
Type
string
Description
Static prefix, between 2 and 10 characters, used to build the descriptor as prefix*order_id. Commerce appends enough characters from the generated order ID to fit the final descriptor limit.
payment_method_dataobjectInline payment details for new payment instruments.Click or tap to expand
- Name
  type
  Type
  enum
  Description
  Currently only mobile_money is supported for inline collection.
- Name
  mobile_money
  Type
  object
  Description
  Required when type is mobile_money. Provides wallet details.
  View mobile_money attributesClick or tap to expand
  Name
  network
  Type
  enum
  Description
  Wallet network: airtel, mtn, telecel, or vodafone.
  Name
  account_number
  Type
  string
  Description
  Subscriber MSISDN in international format (e.g., +23354...).
Name
execute_payment
Type
boolean
Description
Whether to charge the order immediately. Defaults to false—you'll call /orders/pay later.
Name
finalize
Type
boolean
Description
Set to true to seal the order and generate its hosted invoice. When omitted or false, an order without executable payment details remains a draft and its response omits invoice.
invoice_settingsobjectOptional customer-facing invoice content.Click or tap to expand
- Name
  custom_data
  Type
  object
  Description
  String key-value data attached to the invoice.
- Name
  footer
  Type
  string
  Description
  Text shown at the bottom of the invoice.
- Name
  memo
  Type
  string
  Description
  Customer-facing invoice note.
- Name
  number
  Type
  string
  Description
  Invoice number.
Name
payment_due_after
Type
timestamp
Description
RFC 3339 timestamp for when payment is due. The order response exposes it as payment_due_at when set.
Name
custom_data
Type
object
Description
Arbitrary string key-value pairs for application-specific needs. Attach internal order IDs, fulfillment workflows, tracking identifiers, or any metadata your system requires. Maximum size when serialized: 25 KB. See the Custom Data guide for best practices.
checkout_settingsobjectCheckout configuration for this order. Strongly recommended to provide both redirect_url and cancel_url for a delightful customer experience.Click or tap to expand
- Name
  redirect_url
  Type
  string
  Description
  URL where customers land after completing payment. Include order tracking parameters to show order status and next steps.
- Name
  cancel_url
  Type
  string
  Description
  URL where customers land if they abandon checkout without paying. Use this to show incomplete order details or offer alternative payment methods.
billing_detailsobjectContact info for invoicing and receipt delivery.Click or tap to expand
- Name
  name
  Type
  string
  Description
  Billing contact name.
- Name
  email_address
  Type
  string
  Description
  Billing email address.
- Name
  phone_number
  Type
  string
  Description
  Billing phone number.
- Name
  address
  Type
  object
  Description
  Optional postal address for invoices.
  View address attributesClick or tap to expand
  Name
  name
  Type
  string
  Description
  Recipient name if different from customer.
  Name
  phone_number
  Type
  string
  Description
  Contact phone for delivery or verification.
  Name
  line1
  Type
  string
  Description
  Street address line 1.
  Name
  line2
  Type
  string
  Description
  Street address line 2 (optional).
  Name
  town
  Type
  string
  Description
  City or town.
  Name
  region
  Type
  string
  Description
  State, province, or region.
  Name
  district
  Type
  string
  Description
  District or locality.
  Name
  country
  Type
  string
  Description
  Country name.
  Name
  post_code
  Type
  string
  Description
  Postal or ZIP code.
shippingobjectShipping destination, required for physical fulfillment.Click or tap to expand
- Name
  address
  Type
  object
  Description
  Where the package should go. Same schema as Address in the API.
  View address attributesClick or tap to expand
  Name
  name
  Type
  string
  Description
  Recipient name.
  Name
  phone_number
  Type
  string
  Description
  Phone number for delivery coordination.
  Name
  line1
  Type
  string
  Description
  Street address line 1.
  Name
  line2
  Type
  string
  Description
  Street address line 2 (optional).
  Name
  town
  Type
  string
  Description
  City or town.
  Name
  region
  Type
  string
  Description
  State, province, or region.
  Name
  district
  Type
  string
  Description
  District or locality.
  Name
  country
  Type
  string
  Description
  Country name.
  Name
  post_code
  Type
  string
  Description
  Postal or ZIP code.
payout_settingsobjectOrder-specific payout configuration. Overrides your application-level payout settings for this order—useful for marketplace scenarios where different orders route to different sellers.Click or tap to expand
- Name
  destination
  Type
  object
  Description
  Where funds from this order should be paid out.
  View destination attributesClick or tap to expand
  Name
  financial_account_id
  Type
  string
  Description
  ID of an existing financial account to receive the payout. The account must exist and have push capability enabled. Create financial accounts via the dashboard or [Financial Accounts API](/financial-accounts).
- Name
  enable_fx
  Type
  boolean
  Description
  Whether to enable foreign exchange conversion for this order's payout. When true, Commerce can convert the payout currency to match the destination account. Defaults to false.

Request

POST

/orders/new

curl https://api.zebo.dev/orders/new \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request_meta": {
    "idempotency_key": "order_checkout_ORDER-NUMBER-2"
  },
  "number": "ORDER-NUMBER-2",
  "receipt_number": "RCPT-NUMBER-2",
  "statement_descriptor": "STMTDESC",
  "execute_payment": true,
  "finalize": true,
  "checkout_settings": {
    "redirect_url": "https://google.com/thank-you",
    "cancel_url": "https://google.com/order-cancelled"
  },
  "customer_data": {
    "name": "Customer Name",
    "email_address": "[email protected]",
    "phone_number": "+233242058841"
  },
  "payment_method_data": {
    "type": "mobile_money",
    "mobile_money": {
      "network": "mtn",
      "account_number": "0242057831"
    }
  },
  "line_items": [
    {
      "type": "product",
      "product": {
        "type": "physical",
        "name": "Utility Sneakers",
        "quantity": 1,
        "price": {
          "currency": "ghs",
          "value": 20000
        }
      }
    }
  ],
  "billing_details": {
    "name": "Customer Name",
    "email_address": "[email protected]",
    "address": {
      "line1": "23 Adenta High Street",
      "city": "Accra",
      "country": "GH"
    }
  }
}'

{
  "order": {
    "id": "or_f8y1p1",
    "number": "ORDER-NUMBER-2",
    "receipt_number": "RCPT-NUMBER-2",
    "status": "requires_payment",
    "statement_descriptor": "STMTDESC",
    "initiated_at": "2025-01-13T10:00:00Z",
    "sealed_at": "2025-01-13T10:00:01Z",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "prod_utility",
            "type": "physical",
            "tax_code": "apparel",
            "name": "Utility Sneakers",
            "price": { "currency": "ghs", "value": 20000 },
            "quantity": 1,
            "reference": "utility-sneakers"
          }
        }
      ],
      "total": { "currency": "ghs", "value": 20500 }
    },
    "payment": {
      "id": "py_3deNYy",
      "statement_descriptor": "STMTDESC",
      "payment_method": {
        "id": "pm_wveyHj",
        "customer_id": "cu_a1b2c3",
        "type": "mobile_money",
        "mobile_money": {
          "network": "mtn",
          "account_number": "0242057831"
        },
        "created_at": "2025-01-13T10:00:00Z",
        "verified": false
      },
      "amount": { "currency": "ghs", "value": 20500 },
      "next_action": {
        "type": "confirm_payment",
        "confirm_payment": {
          "confirmed": false,
          "expires_at": "2025-01-13T10:08:00Z",
          "scheme": "zcommerce_defined_auth",
          "request": {
            "id": "token_req_1",
            "recipient": "0242057831",
            "sent_via": "sms",
            "token_size": 6,
            "sender_id": "zverify"
          },
          "status": "pending"
        }
      },
      "status": "requires_action",
      "initiated_at": "2025-01-13T10:00:00Z"
    },
    "invoice": {
      "format": {
        "web": { "url": "https://pages.zebo.dev/invoices/or_f8y1p1" },
        "pdf": { "url": "https://pages.zebo.dev/invoices/or_f8y1p1/pdf" }
      }
    },
    "customer": {
      "id": "cu_a1b2c3",
      "email_address": "[email protected]",
      "phone_number": "+233242058841",
      "guest": false,
      "name": "Customer Name"
    }
  }
}

Pay for an order

Charge an existing order without recreating it. Four ways to use this:

Already has a payment method: Just send order_id—we'll charge the attached method.
Swap to a different saved method: Send order_id + payment_method_id.
Use a new payment method once: Send order_id + payment_method_data.
Use and save a new method: Add save_payment_method: true and include payment_method_data.billing_details.
Offline payment: Send order_id + paid_out_of_band: true—marks the payment as received outside Commerce (cash, bank transfer, check).

Rules

Pass either payment_method_id, payment_method_data, or paid_out_of_band, never multiple.
paid_out_of_band is mutually exclusive with payment method parameters.
Any payment_method_id must belong to the order's customer.
save_payment_method affects only inline payment_method_data; it defaults to false.

Optional attributes

Name
payment_method_id
Type
string
Description
ID of a saved payment method belonging to this order's customer.
payment_method_dataobjectNew payment method details to charge.Click or tap to expand
- Name
  type
  Type
  enum
  Description
  Currently only mobile_money is accepted when supplying inline details.
- Name
  mobile_money
  Type
  object
  Description
  Required when type is mobile_money. Mirrors the MobileMoney schema.
  View mobile_money attributesClick or tap to expand
  Name
  network
  Type
  enum
  Description
  Wallet network: airtel, mtn, telecel, or vodafone.
  Name
  account_number
  Type
  string
  Description
  Wallet MSISDN in international or local format (we normalize it).
Name
paid_out_of_band
Type
boolean
Description
Set to true when payment was received outside Commerce (cash, bank transfer, check). Marks the payment as paid offline and completes the payment immediately. Mutually exclusive with payment_method_id and payment_method_data. Defaults to false.
Name
payment_method_types
Type
array
Description
Allowed payment-method types for this attempt. Each value must be supported for the application.
Name
save_payment_method
Type
boolean
Description
Save inline payment details for future use. When true, payment_method_data.billing_details is required and must include name and address.country.

Request

POST

/orders/pay

curl https://api.zebo.dev/orders/pay \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
  "payment_method_data": {
    "type": "mobile_money",
    "mobile_money": {
      "network": "mtn",
      "account_number": "0544998605"
    }
  }
}'

{
  "order": {
    "id": "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
    "initiated_at": "2026-08-28T09:30:00Z",
    "status": "requires_payment",
    "customer": {
      "guest": true,
      "id": "cu_4pL8rN",
      "name": "Gloria Kesewaa"
    },
    "payment": {
      "amount": { "currency": "ghs", "value": 20000 },
      "id": "py_3deNYy",
      "initiated_at": "2026-08-28T09:30:01Z",
      "statement_descriptor": "ZEBO",
      "status": "requires_action"
    }
  }
}

Confirm a payment

Submit the confirmation token for a specific payment and confirmation request. Read payment_id from order.payment.id and confirmation_id from order.payment.next_action.confirm_payment.request.id in the preceding create, pay, or request-confirmation response. The response always uses the { "order": ... } envelope; an actionable error can include both order and error.

Required attributes

Name
confirmation_id
Type
string
Description
ID of the confirmation request that issued the token.
Name
order_id
Type
string
Description
ID of the order being paid.
Name
payment_id
Type
string
Description
ID of the payment attached to the order.
Name
token
Type
string
Description
Confirmation token supplied by the customer.

Request

POST

/orders/confirm_payment

curl https://api.zebo.dev/orders/confirm_payment \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmation_id": "otc_req_8Ks2Vn",
    "order_id": "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
    "payment_id": "py_3deNYy",
    "token": "302673"
  }'

{
  "order": {
    "customer": {
      "guest": true,
      "id": "cu_4pL8rN",
      "name": "Gloria Kesewaa"
    },
    "id": "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
    "initiated_at": "2026-08-28T09:30:00Z",
    "status": "paid"
  }
}

Request confirmation

Some payment methods—especially mobile money—require the customer to confirm with an OTP. Call this to send (or resend) the confirmation token.

Request

POST

/orders/request_confirmation

curl https://api.zebo.dev/orders/request_confirmation \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi"
}'

{
  "order": {
    "id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
    "status": "requires_payment",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "pm_fNa3i3QPkt4yU5FQHoM042tRFAdthCbcRZJdZnrl",
            "reference": "pm_fNa3i3QPkt4yU5FQHoM042tRFAdthCbcRZJdZnrl",
            "about": "Tollo victoria advenio crudelis facere crudelis. Aequitas voco correptius suspendo fuga demergo. Angelus texo pecto.",
            "custom_data": {
              "size": "56",
              "color": "blue"
            },
            "tax_code": "gold",
            "name": "Awesome Fresh Gloves",
            "type": "digital",
            "price": {
              "currency": "ghs",
              "value": 20
            },
            "quantity": 1
          }
        },
        {
          "type": "product",
          "product": {
            "id": "cu_deeYHxzydDJWU1w9YCjOvgDirYv37WyYmI9MhdEA",
            "reference": "cu_deeYHxzydDJWU1w9YCjOvgDirYv37WyYmI9MhdEA",
            "about": "Sunt astrum verecundia cenaculum. Asporto voluptas mollitia voluptate vaco concedo bellum clam aufero taedium. Admiratio cohibeo ullus comis alter.",
            "custom_data": {
              "size": "56",
              "color": "blue"
            },
            "tax_code": "black",
            "name": "Awesome Fresh Table",
            "type": "digital",
            "price": {
              "currency": "ghs",
              "value": 100
            },
            "quantity": 2
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 220
      }
    },
    "initiated_at": "2025-04-09T00:11:47.74569+01:00",
    "sealed_at": "2025-04-09T00:11:48.374979+01:00",
    "payment": {
      "id": "py_8QNM4ujclxXUDZBnL9ujyPfMG4Bk6ZRMBeRtc99l",
      "statement_descriptor": "STATEMENT",
      "payment_method": {
        "id": "pm_acA9cJRhjZHw1Gs4p39fKTbp1AgsFjhBk1AwIuVf",
        "customer_id": "cu_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
        "type": "mobile_money",
        "mobile_money": {
          "network": "mtn",
          "account_number": "024******31",
          "last4": "7831"
        },
        "created_at": "2025-04-09T00:11:47.873476+01:00",
        "verified": false
      },
      "amount": {
        "currency": "ghs",
        "value": 220
      },
      "next_action": {
        "type": "confirm_payment",
        "confirm_payment": {
          "expires_at": "0001-01-01T00:00:00Z",
          "scheme": "zcommerce_defined_auth",
          "request": {
            "recipient": "0242057831",
            "sent_via": "sms",
            "token_size": 6,
            "sender_id": "zverify"
          },
          "confirmed": false,
          "status": "pending_verification"
        }
      },
      "status": "requires_action",
      "initiated_at": "2025-04-09T00:11:47.995076+01:00"
    },
    "customer": {
      "id": "cu_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
      "email_address": "[email protected]",
      "phone_number": "+233544998605",
      "name": "Gloria Kesewaa"
    }
  }
}

Update an order

Update mutable fields on an existing order and get back the same response shape as Lookup an order. Use this endpoint for three distinct cases: revising an open draft, reopening a sealed order so it becomes editable again, or applying changes and resealing in the same request.

What you can change

Replace the full line_items collection
Change the order number
Set or change the order receipt_number
Change the payment statement_descriptor
Attach a different saved payment_method_id
Tokenize and attach new inline payment_method_data
Remove the attached payment method with clear_payment_method
Replace order-level custom_data
Replace or clear customer-facing invoice_settings
Explicitly open, seal, or reseal the order with finalize

Rules

Include at least one mutable field besides order_id.
line_items is a full replacement field, not a sparse merge, and it cannot be empty when provided.
payment_method_id, payment_method_data, and clear_payment_method are mutually exclusive.
payment_method_data currently supports only mobile_money for order updates.
Completed, paid, canceled, and expired orders cannot be updated.
custom_data is metadata-only. Updating it does not require reopen / reseal by itself.
Omit receipt_number to leave it unchanged. When provided, Commerce trims it and requires a different non-empty value within the same configured length limits as number. It cannot be cleared once set, and receipt numbers are not unique.
If payment confirmation or execution has already started, Commerce rejects edits that change economics, payment configuration, or require reopening the order.
When mutating seal-sensitive fields on a sealed order, you must provide finalize explicitly:
- finalize: false reopens the order and leaves it editable.
- finalize: true applies the changes and seals the order again in the same request.

Required attributes

Name
order_id
Type
string
Description
The unique identifier of the order to update.

Optional attributes

Name
clear_payment_method
Type
boolean
Description
Clears the currently attached payment method. Mutually exclusive with payment_method_id and payment_method_data.
Name
custom_data
Type
object
Description
Replacement order-level custom data. Provide an empty object to clear the current value.
Name
finalize
Type
boolean
Description
Explicit seal decision. Use false to reopen a sealed order and leave it editable, or true to seal or reseal the order after applying the requested changes.
invoice_settingsobjectFull replacement for customer-facing invoice content. Send an empty object to clear the current settings.Click or tap to expand
- Name
  custom_data
  Type
  object
  Description
  String key-value data attached to the invoice.
- Name
  footer
  Type
  string
  Description
  Text shown at the bottom of the invoice.
- Name
  memo
  Type
  string
  Description
  Customer-facing invoice note.
- Name
  number
  Type
  string
  Description
  Invoice number.
Name
line_items
Type
array
Description
Full replacement for the order's current line items. Use the same line-item schema as Create an order.
Name
number
Type
string
Description
Replacement order number.
payment_method_dataobjectNew payment method details to tokenize and attach to the order.Click or tap to expand
- Name
  billing_details
  Type
  object
  Description
  Required when providing inline payment method details. Must include name and address.country.
- Name
  mobile_money
  Type
  object
  Description
  Required when type is mobile_money. Provide network and account_number.
- Name
  type
  Type
  string
  Description
  Currently only mobile_money is supported for order updates.
Name
payment_method_id
Type
string
Description
ID of a saved payment method to attach to the order.
Name
receipt_number
Type
string
Description
Replacement receipt reference. Must be a different non-empty value when provided.
Name
statement_descriptor
Type
string
Description
Replacement payment statement descriptor for the order's payment.
Name
statement_descriptor_prefix
Type
string
Description
Static prefix, between 2 and 10 characters, used to build the replacement descriptor as prefix*order_id. Mutually exclusive with statement_descriptor.

Response shape

Returns the same order object as Lookup an order.
If finalize: false reopens a sealed order, sealed_at and invoice are cleared until the order is sealed again.
If finalize: true seals or reseals the order, Commerce returns the regenerated invoice and the updated payment amount.
The returned order object includes top-level custom_data when present.
The returned order object includes top-level receipt_number when set.

Request

POST

/orders/update

curl https://api.zebo.dev/orders/update \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
  "receipt_number": "RCPT-2025-041-REV1",
  "line_items": [
    {
      "type": "product",
      "product": {
        "name": "Quarterly support retainer",
        "type": "digital",
        "price": {
          "currency": "ghs",
          "value": 15000
        },
        "quantity": 1
      }
    },
    {
      "type": "fee",
      "fee": {
        "label": "Service fee",
        "amount": {
          "currency": "ghs",
          "value": 500
        }
      }
    }
  ],
  "statement_descriptor": "ORDER REVISION",
  "custom_data": {
    "channel": "dashboard",
    "edited_by": "ops"
  },
  "finalize": true
}'

{
  "order": {
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "number": "ORDER-2025-REV2",
    "receipt_number": "RCPT-2025-041-REV1",
    "status": "requires_payment",
    "initiated_at": "2025-05-01T10:00:00Z",
    "sealed_at": "2025-05-01T10:04:00Z",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "li_VNojv2eX7F9H3mQ5pZr2Ld8",
            "name": "Quarterly support retainer",
            "type": "digital",
            "price": {
              "currency": "ghs",
              "value": 15000
            },
            "quantity": 1
          }
        },
        {
          "type": "fee",
          "fee": {
            "id": "li_7Nf0wP4sT8kJ2qM6xCz9Rb1",
            "label": "Service fee",
            "amount": {
              "currency": "ghs",
              "value": 500
            }
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 15500
      }
    },
    "payment": {
      "id": "py_3PjQ7mVn2cX5kL8rT1sW4yH6uB9dF0gN",
      "statement_descriptor": "ORDER REVISION",
      "payment_method": {
        "id": "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
        "customer_id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
        "type": "mobile_money",
        "mobile_money": {
          "network": "mtn",
          "account_number": "0594870087"
        },
        "created_at": "2025-05-01T10:00:00Z",
        "verified": true,
        "verified_at": "2025-05-01T10:00:15Z"
      },
      "amount": {
        "currency": "ghs",
        "value": 15500
      },
      "status": "requires_action",
      "initiated_at": "2025-05-01T10:00:00Z"
    },
    "invoice": {
      "id": "in_bRSGJcH7v4oLIAa3KlBmB9K6ZoRUucJXAJMWxl1KQq0JCZs0oOEG8ibCeGn1",
      "format": {
        "web": {
          "url": "https://pages.zebo.dev/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
        },
        "pdf": {
          "url": "https://pages.zebo.dev/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt/pdf"
        }
      }
    },
    "customer": {
      "id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
      "email_address": "[email protected]",
      "phone_number": "+233559714200",
      "name": "Anita Segnom"
    },
    "custom_data": {
      "channel": "dashboard",
      "edited_by": "ops"
    }
  }
}

Finalize an order

Finalize an order to seal it for payment. This endpoint generates an invoice and hosted checkout page that you can share with customers.

What finalization means

Finalizing an order is the transition from draft to ready-for-payment. Before finalization, orders are flexible—you can add products, adjust quantities, or update customer details. After finalization:

Line items freeze: No additions, removals, or quantity changes unless you later reopen the order with Update an order
Totals lock: The amount due becomes fixed until the order is reopened
Invoice generates: A viewable invoice with web and PDF formats
Checkout activates: The hosted payment page becomes accessible
Payment readiness: The order can accept payment attempts

Use this endpoint when you've finished building the cart and want to present it to the customer for payment. The response includes invoice URLs and the sealed_at timestamp marking when the order was finalized.

Required attributes

Name
order_id
Type
string
Description
The unique identifier of the order to finalize.

Request

POST

/orders/finalize

curl https://api.zebo.dev/orders/finalize \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'

{
  "order": {
    "number": "ORDER-12345",
    "status": "requires_payment",
    "payment_id": "py_xyz123abc456",
    "customer_id": "cu_abc123def456",
    "sealed_at": "2025-01-25T10:30:00Z",
    "initiated_at": "2025-01-25T10:25:00Z",
    "expires_at": "2025-02-01T10:25:00Z",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "prod_123",
            "name": "Premium Widget",
            "quantity": 2,
            "price": {
              "currency": "ghs",
              "value": 5000
            }
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 10000
      }
    },
    "invoice": {
      "number": "ORDER-12345",
      "due_at": "2025-01-25T10:30:00Z"
    }
  }
}

Send an invoice

Send the hosted invoice link for an existing order. Commerce uses the order customer's contact details: if the customer has both phone and email, it sends SMS and email; otherwise it sends to whichever contact method exists.

This endpoint is idempotent. Send a stable idempotency key when retrying so Commerce can replay the original delivery result instead of creating duplicate messages.

The order must have a hosted invoice before delivery. Finalize draft orders first with Finalize an order. If a sealed order is missing its invoice, Commerce may generate the invoice before sending.

Request body

Name
order_id
Type
string
Description
The order whose hosted invoice link should be sent.

Response

Returns the current order plus a delivery object. If one channel succeeds and another fails, the endpoint may return HTTP 207 with both sent_channels and failed_channels.

deliveryobjectDelivery result for the hosted invoice link.Click or tap to expand
- Name
  deliveries
  Type
  array
  Description
  Accepted message sends.
  View deliveries attributesClick or tap to expand
  Name
  channel
  Type
  string
  Description
  sms or email.
  Name
  chime_id
  Type
  string
  Description
  Created delivery ID.
- Name
  document_kind
  Type
  string
  Description
  invoice.
- Name
  document_url
  Type
  string
  Description
  Hosted invoice URL sent to the customer.
- Name
  failed_channels
  Type
  array
  Description
  Channels that failed to send.
- Name
  failures
  Type
  array
  Description
  Failed channel details.
  View failures attributesClick or tap to expand
  Name
  channel
  Type
  string
  Description
  sms or email.
  Name
  error
  Type
  string
  Description
  Delivery error.
- Name
  sent_channels
  Type
  array
  Description
  Channels accepted for delivery.

Invoice delivery can return draft_mode_order_has_no_invoice, order_delivery_auth_failed, order_delivery_contact_missing, order_delivery_failed, or order_not_found.

Request

POST

/orders/send_invoice

curl https://api.zebo.dev/orders/send_invoice \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-invoice-or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'

{
  "order": {
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "status": "requires_payment"
  },
  "delivery": {
    "document_kind": "invoice",
    "document_url": "https://pages.zebo.dev/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "sent_channels": ["sms", "email"],
    "deliveries": [
      {
        "channel": "sms",
        "chime_id": "chm_sms_123"
      },
      {
        "channel": "email",
        "chime_id": "chm_email_456"
      }
    ]
  }
}

Send a receipt

Send the hosted receipt link for an existing paid order. Commerce uses the same fan-out rules as invoice delivery: SMS and email when both customer contacts exist, otherwise whichever contact method is available.

Receipt delivery is available only after the order is paid. The link points to the hosted receipt path, such as /invoices/{order_id}/receipt; do not use the invoice PDF path for receipt delivery.

This endpoint is idempotent. Send a stable idempotency key when retrying.

Request body

Name
order_id
Type
string
Description
The paid order whose hosted receipt link should be sent.

Response

Returns the current order plus a delivery object. If one channel succeeds and another fails, the endpoint may return HTTP 207 with both sent_channels and failed_channels.

deliveryobjectDelivery result for the hosted receipt link.Click or tap to expand
- Name
  deliveries
  Type
  array
  Description
  Accepted message sends.
  View deliveries attributesClick or tap to expand
  Name
  channel
  Type
  string
  Description
  sms or email.
  Name
  chime_id
  Type
  string
  Description
  Created delivery ID.
- Name
  document_kind
  Type
  string
  Description
  receipt.
- Name
  document_url
  Type
  string
  Description
  Hosted receipt URL sent to the customer.
- Name
  failed_channels
  Type
  array
  Description
  Channels that failed to send.
- Name
  failures
  Type
  array
  Description
  Failed channel details.
  View failures attributesClick or tap to expand
  Name
  channel
  Type
  string
  Description
  sms or email.
  Name
  error
  Type
  string
  Description
  Delivery error.
- Name
  sent_channels
  Type
  array
  Description
  Channels accepted for delivery.

Receipt delivery can return order_delivery_auth_failed, order_delivery_contact_missing, order_delivery_failed, order_not_found, or order_receipt_missing.

Request

POST

/orders/send_receipt

curl https://api.zebo.dev/orders/send_receipt \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-receipt-or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'

{
  "order": {
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "status": "paid"
  },
  "delivery": {
    "document_kind": "receipt",
    "document_url": "https://pages.zebo.dev/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt/receipt",
    "sent_channels": ["sms"],
    "deliveries": [
      {
        "channel": "sms",
        "chime_id": "chm_sms_789"
      }
    ]
  }
}

Complete an order

Mark an order as completed when the customer has received their items or you've fulfilled the service. This transitions the order to the completed state, indicating the transaction is fully satisfied.

When to complete orders

Complete an order when:

Physical goods: Items have been delivered or picked up
Digital products: Files have been downloaded or access granted
Services: Work has been performed and accepted
Out-of-band payments: Cash, check, or bank transfer received offline

The order must have a successful payment before completion, unless you're marking an offline payment with paid_out_of_band: true.

Out-of-band payments

If the customer paid outside Commerce (cash, bank transfer, check), set paid_out_of_band: true. This marks both the payment and order as complete in a single operation. The payment gets marked as paid offline before the order is completed.

Use this for:

Cash on delivery scenarios
Bank transfer confirmations
Check payments that cleared
Any payment method outside the Commerce platform

Required attributes

Name
order_id
Type
string
Description
The unique identifier of the order to complete.

Optional attributes

Name
paid_out_of_band
Type
boolean
Description
Set to true if payment was received outside Commerce (cash, bank transfer, check). When true, the payment is marked as paid offline before completing the order. Defaults to false, which requires the payment to already be in paid status.

Request

POST

/orders/complete

curl https://api.zebo.dev/orders/complete \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'

{
  "order": {
    "number": "ORDER-12345",
    "status": "completed",
    "payment_id": "py_xyz123abc456",
    "customer_id": "cu_abc123def456",
    "completed_at": "2025-01-27T11:00:00Z",
    "sealed_at": "2025-01-25T10:30:00Z",
    "initiated_at": "2025-01-25T10:25:00Z",
    "expires_at": "2025-02-01T10:25:00Z",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "prod_123",
            "name": "Premium Widget",
            "quantity": 2,
            "price": {
              "currency": "ghs",
              "value": 5000
            }
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 10000
      }
    }
  }
}

Lookup an order

Fetch the current state of an order by ID. Returns the full order object or a 404 if it doesn't exist.

Required attributes

Name
order_id
Type
string
Description
Order ID from the creation response.

Request

POST

/orders/lookup

curl https://api.zebo.dev/orders/lookup \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'

{
  "order": {
    "line_item_group": {
      "line_items": [
        {
          "product": {
            "id": "pm_BydaofEe1IdJro0BVjlm89PxeENo8GsqX09yVtBL",
            "about": "Accedo turba doloremque brevis. Despecto administratio vorax verus odit vinculum. Advoco conforto spiritus debeo careo.",
            "custom_data": {
              "size": "56",
              "some": "custom_data"
            },
            "tax_code": "pink",
            "name": "Gorgeous Granite Salad",
            "type": "physical",
            "price": {
              "currency": "ghs",
              "value": 100
            },
            "quantity": 1
          },
          "type": "product"
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 200
      }
    },
    "initiated_at": "2025-09-14T16:24:41.137708909Z",
    "completed_at": "2025-09-14T16:29:45Z",
    "sealed_at": "2025-09-14T16:24:41.312701813Z",
    "payment": {
      "id": "py_OHFv6I3OZBvB1R46TQQGNxPPtgbPR6CXpQ8En9wl",
      "statement_descriptor": "STATEMENT",
      "payment_method": {
        "id": "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
        "customer_id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
        "type": "mobile_money",
        "mobile_money": {
          "network": "mtn",
          "account_number": "0594870087"
        },
        "created_at": "2025-09-14T16:24:41.171905592Z",
        "verified": true,
        "verified_at": "2025-09-14T16:24:51.171905592Z"
      },
      "latest_attempt": {
        "payment_method_type": "mobile_money",
        "payment_method_id": "hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
        "reference": "68c6ecbc3bf0a6548973b598",
        "status": "succeeded",
        "initiated_at": "2025-09-14T16:26:36.627271781Z",
        "succeeded_at": "2025-09-14T16:29:45Z"
      },
      "amount": {
        "currency": "ghs",
        "value": 200
      },
      "status": "paid",
      "initiated_at": "2025-09-14T16:24:41.240462376Z",
      "executed_at": "2025-09-14T16:26:36.626961042Z",
      "paid_at": "2025-09-14T16:29:45Z",
      "balance_transaction": {
        "id": "bt_EWOA27qe7aO4GZouasUSmVXILsmxjR0H",
        "payout_id": "po_68c6ecbc3bf0a6548973b598",
        "payment_id": "py_OHFv6I3OZBvB1R46TQQGNxPPtgbPR6CXpQ8En9wl",
        "created_at": "2025-09-14T16:29:45Z",
        "paid_at": "2025-09-15T08:00:00Z",
        "amount": {
          "currency": "ghs",
          "value": 200
        }
      }
    },
    "invoice": {
      "id": "in_bRSGJcH7v4oLIAa3KlBmB9K6ZoRUucJXAJMWxl1KQq0JCZs0oOEG8ibCeGn1",
      "format": {
        "web": {
          "url": "https://pages.zebo.dev/invoices/48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
        },
        "pdf": {
          "url": "https://pages.zebo.dev/invoices/48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt/pdf"
        }
      }
    },
    "customer": {
      "id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
      "email_address": "[email protected]",
      "phone_number": "+233559714200",
      "name": "Anita Segnom"
    },
    "status": "completed",
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
  }
}

Cancel an order

Cancel an order that has not yet been completed. Cancellation marks the order as canceled and records the reason and timestamp. If the order has an associated payment that has already been processed, pass execute_refund: true to trigger a refund at the same time.

You cannot cancel an order that has already reached completed status—use a refund flow for post-completion reversals. Orders in requires_payment status (mid-payment-flow) can be canceled; the associated payment will be voided.

Request attributes

Name
execute_refund
Type
boolean
Description
When true, Commerce initiates a refund for any captured funds on the associated payment before marking the order canceled. Defaults to false—omit or set to false if no payment has been captured or you prefer to handle refunds separately.
Name
order_id
Type
string
Description
The typed ID of the order to cancel (e.g. or_abc123). Must belong to the authenticated application.
Name
reason
Type
string
Description
Optional free-text explanation for the cancellation. Recorded on the order for audit purposes. Defaults to "unknown" if not provided. Common values: "customer_request", "fraud", "inventory_unavailable", "duplicate".

Request

POST

/orders/cancel

curl https://api.zebo.dev/orders/cancel \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
  "reason": "customer_request",
  "execute_refund": false
}'

{
  "order": {
    "id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
    "status": "canceled",
    "initiated_at": "2025-04-09T00:11:47.74569+01:00",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "pr_ZLxM9pQ4wRsN7jKv2cY1tD8hBgFnAo3i",
            "name": "Tailoring Service",
            "price": {
              "currency": "ghs",
              "value": 200
            },
            "quantity": 1
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 200
      }
    },
    "payment": {
      "id": "py_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
      "status": "canceled",
      "amount": {
        "currency": "ghs",
        "value": 200
      },
      "canceled_at": "2025-04-09T01:05:12Z",
      "initiated_at": "2025-04-09T00:11:48Z"
    }
  }
}

Page through orders

Retrieve a paginated list of the most recent orders for the authenticated application. Orders are sorted by initiated_at in descending order, so page 0 contains the freshest activity and subsequent pages step back in time.

Provide customer_id to scope the page to a single customer. Omit customer_id to browse all recent orders across the application.

Required attributes

Name
page_size
Type
integer
Description
Number of orders requested per page. Must be between 1 and 256.

Optional attributes

Name
customer_id
Type
string
Description
Optional customer ID to scope the page to one buyer's orders only.
Name
page_number
Type
integer
Description
Zero-based page index from 0 through 10. Defaults to 0 when omitted.

Response shape

Top level page object includes number, size, and an orders array.
Each array entry uses the complete shared order object, not a condensed summary.
Optional fields are omitted when unavailable. The API does not add payment.receipt or line_item_group.products_count summary fields.
When you filter by customer_id, every returned order belongs to that customer.

Request

POST

/orders/page

curl https://api.zebo.dev/orders/page \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "page_number": 0,
  "page_size": 25
}'

{
  "page": {
    "number": 0,
    "size": 2,
    "orders": [
      {
        "id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
        "line_item_group": {
          "line_items": [],
          "total": {
            "currency": "ghs",
            "value": 220
          }
        },
        "initiated_at": "2025-04-09T00:11:47.74569+01:00",
        "sealed_at": "2025-04-09T00:11:48.374979+01:00",
        "status": "requires_payment",
        "customer": {
          "id": "cu_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
          "guest": false,
          "name": "Gloria Kesewaa",
          "email_address": "[email protected]",
          "phone_number": "+233544998605"
        },
        "payment": {
          "id": "py_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
          "amount": { "currency": "ghs", "value": 220 },
          "initiated_at": "2025-04-09T00:11:47.842341+01:00",
          "statement_descriptor": "ZEBO",
          "status": "requires_action",
          "payment_method": {
            "id": "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
            "customer_id": "cu_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
            "created_at": "2025-04-09T00:11:47.842341+01:00",
            "verified": true,
            "type": "mobile_money",
            "mobile_money": {
              "network": "mtn",
              "account_number": "+233******8605",
              "last4": "8605"
            }
          },
          "latest_attempt": {
            "payment_method_type": "mobile_money",
            "payment_method_id": "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
            "reference": "nsn_57d91e4fd4b8",
            "status": "executed",
            "initiated_at": "2025-04-09T00:11:48.391412+01:00"
          }
        }
      },
      {
        "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
        "line_item_group": {
          "line_items": [],
          "total": {
            "currency": "ghs",
            "value": 200
          }
        },
        "initiated_at": "2025-09-14T16:24:41.137708909Z",
        "completed_at": "2025-09-14T16:29:45Z",
        "sealed_at": "2025-09-14T16:24:41.312701813Z",
        "status": "completed",
        "customer": {
          "id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
          "guest": false,
          "name": "Anita Segnom",
          "email_address": "[email protected]",
          "phone_number": "+233559714200"
        }
      }
    ]
  }
}