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_settingsobjectSettings controlling the Zebo Checkout experience.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.
customerobjectCustomer who placed this order.Click or tap to expand
- Name
  created_at
  Type
  timestamp
  Description
  When this customer was created.
- Name
  email_address
  Type
  string
  Description
  Email for receipts and updates.
- 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
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.
invoiceobjectInvoice generated for this order.Click or tap to expand
- Name
  deliveries
  Type
  array|null
  Description
  Email/SMS delivery log—null if not yet sent.
- 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
  id
  Type
  string
  Description
  Unique invoice ID.
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
  physical or digital—affects shipping requirements.
  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, like ghs or usd.
  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 like ghs.
  Name
  value
  Type
  integer
  Description
  Amount in smallest unit.
- Name
  balance_transaction
  Type
  object|null
  Description
  Ledger entry created once the payment settles. null until the payment is paid.
  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 like ghs.
  Name
  value
  Type
  integer
  Description
  Amount in smallest unit.
  Name
  available_at
  Type
  timestamp|null
  Description
  When the funds become available for payout. Typically 7 days after payment settlement to account for dispute windows.
  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
  paid_at
  Type
  timestamp|null
  Description
  When the payout was completed.
  Name
  payment_id
  Type
  string
  Description
  Payment this transaction is tied to.
  Name
  payout_configuration
  Type
  object|null
  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|null
  Description
  Payout that will disburse the funds (nullable until scheduled).
- Name
  executed_at
  Type
  timestamp|null
  Description
  When the customer authorized execution (set after we pass OTP or 3DS).
- 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|null
  Description
  Details about the most recent charge attempt—null until we try to collect payment.
  View latest_attempt attributesClick or tap to expand
  Name
  failed_at
  Type
  timestamp|null
  Description
  Set when the attempt fails.
  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|null
  Description
  Set when the attempt succeeds.
- 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|null
  Description
  When funds were fully captured and marked as paid.
- 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
  issuer
  Type
  string
  Description
  Network provider: mtn, vodafone, visa, etc.
  Name
  number
  Type
  string
  Description
  Masked or tokenized account identifier.
  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
  payout_configuration
  Type
  object|null
  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
  What the customer sees on their bank statement.
- Name
  status
  Type
  string
  Description
  Payment state: requires_action, processing, succeeded, failed, etc.
Name
sealed_at
Type
timestamp
Description
When the order was finalized and became immutable—ready for payment or fulfillment.
shippingobjectShipping details—null for digital goods.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
  district
  Type
  string
  Description
  District or locality.
  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
  town
  Type
  string
  Description
  City or town.
Name
statement_descriptor
Type
string
Description
What shows up on the customer's bank or mobile money statement—keep it recognizable.
Name
status
Type
string
Description
Current lifecycle state: requires_payment, paid, completed, etc.

POST/orders/new

Create an order

Create an order and optionally charge it right away. Three common patterns:

New customer, new payment method: Pass customer_data + payment_method_data for first-time checkouts.
Existing customer, new payment method: Use customer_id with fresh payment_method_data when the customer wants to pay with a different instrument.
Order now, pay later: Provide only customer_id or customer_data and skip the payment method—you'll charge it later via /orders/pay.

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 defer payment.

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. Must include type, name, price, and quantity inside this object.
  View product attributesClick or tap to expand
  Name
  id
  Type
  string
  Description
  Optional product ID for reconciliation.
  Name
  type
  Type
  string
  Description
  physical or digital to signal whether shipping is required.
  Name
  name
  Type
  string
  Description
  Customer-facing label for the product.
  Name
  about
  Type
  string
  Description
  Marketing copy or long-form description.
  Name
  reference
  Type
  string
  Description
  Your SKU or internal reference.
  Name
  tax_code
  Type
  string
  Description
  Tax classification code for this item.
  Name
  price
  Type
  object
  Description
  Per-unit price. Required fields align with the Money schema.
  View price attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Lowercase ISO 4217 currency code (e.g., ghs).
  Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit (pesewas, cents, etc.).
  Name
  quantity
  Type
  integer
  Description
  Number of units being purchased (minimum 1).
  Name
  custom_data
  Type
  object
  Description
  Key-value strings for your own custom data. Matches the custom_data object in the spec.
- 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
  custom_data
  Type
  object
  Description
  Key-value strings for internal tracking.
- 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.
  Name
  custom_data
  Type
  object
  Description
  Key-value strings so you can annotate the shipping line.
Name
idempotency_key
Type
string
Description
Unique key for this request—prevents duplicate orders if you retry.
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.

Optional attributes

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.
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
  issuer
  Type
  enum
  Description
  Wallet network: mtn, vodafone, or airteltigo.
  Name
  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
send_invoice
Type
boolean
Description
Auto-send the invoice via email/SMS when payment is ready, then send the receipt after payment succeeds.
Name
finalize
Type
boolean
Description
Explicitly finalize the order, making it immutable regardless of payment state. When true, the order is finalized immediately—line items lock, totals freeze, and an invoice generates. When false or omitted, finalization follows default heuristics (finalize only if payment is executable). Use this to create read-only orders that can be shared or reviewed before payment.
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 {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "0f780d10-0a2f-4c29-a2b1-1f566e0b1f80",
    "number": "ORDER-NUMBER-2",
    "statement_descriptor": "STMTDESC",
    "execute_payment": true,
    "send_invoice": true,
    "checkout_settings": {
      "redirect_url": "https://google.com/thank-you",
      "cancel_url": "https://google.com/order-cancelled"
    },
    "customer_data": {
      "name": "Customer Name",
      "email_address": "customer@example.com",
      "phone_number": "+233242058841"
    },
    "payment_method_data": {
      "type": "mobile_money",
      "mobile_money": {
        "issuer": "mtn",
        "number": "0242057831"
      }
    },
    "line_items": [
      {
        "type": "product",
        "product": {
          "type": "physical",
          "name": "Utility Sneakers",
          "quantity": 1,
          "price": { "currency": "ghs", "value": 20000 }
        }
      }
    ],
    "billing_details": {
      "email_address": "customer@example.com",
      "address": {
        "line1": "23 Adenta High Street",
        "town": "Accra",
        "country": "Ghana"
      }
    }
  }'

Response

{
  "order": {
    "id": "or_f8y1p1",
    "number": "ORDER-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",
        "issuer": "mtn",
        "number": "0242057831",
        "created_at": "2025-01-13T10:00:00Z",
        "verified": false
      },
      "amount": { "currency": "ghs", "value": 20500 },
      "next_action": {
        "type": "confirm_payment",
        "confirm_payment": {
          "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": "requires_action",
      "initiated_at": "2025-01-13T10:00:00Z"
    },
    "invoice": {
      "id": "inv_HMpTYm",
      "deliveries": null,
      "format": {
        "web": { "url": "https://checkout.zebo.dev/or_f8y1p1" },
        "pdf": { "url": "https://checkout.zebo.dev/or_f8y1p1/pdf" }
      }
    },
    "customer": {
      "id": "cu_a1b2c3",
      "email_address": "customer@example.com",
      "phone_number": "+233242058841",
      "created_at": "2025-01-13T10:00:00Z",
      "name": "Customer Name"
    },
    "shipping": {
      "address": {
        "line1": "23 Adenta High Street",
        "line2": "Behind Pantang",
        "town": "Accra",
        "region": "Greater Accra",
        "country": "Ghana",
        "district": "Adenta",
        "post_code": "GHA-123-9822"
      }
    }
  }
}

POST/orders/new

For a known customer

For returning customers with saved payment methods, just send customer_id and payment_method_id. This is the fastest path—perfect for subscriptions and repeat purchases where you already have consent to charge.

Request

POST

/orders/new

curl https://api.zebo.dev/orders/new \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cu_dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
    "payment_method_id": "pm_OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa",
    "execute_payment": true,
    "idempotency_key": "1577b509-52b2-4d5a-a1b6-fa0f6d574f75",
    "line_items": [
      {
        "type": "product",
        "product": {
          "type": "digital",
          "name": "Streaming Pack",
          "quantity": 1,
          "price": { "currency": "ghs", "value": 200 }
        }
      }
    ]
  }'

Response

{
  "order": {
    "id": "or_6q8wxs",
    "number": "ORDER-NUMBER",
    "customer_id": "cu_dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
    "payment_method_id": "pm_OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa",
    "status": "requires_payment",
    "initiated_at": "2025-01-13T11:00:00Z",
    "sealed_at": "2025-01-13T11:00:01Z",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "prod_stream_single",
            "about": "Digital streaming pack (single license).",
            "tax_code": "media",
            "name": "Streaming Pack",
            "type": "digital",
            "price": { "currency": "ghs", "value": 200 },
            "quantity": 1,
            "reference": "stream-pack-1"
          }
        },
        {
          "type": "product",
          "product": {
            "id": "prod_stream_bundle",
            "about": "Digital streaming pack bundle.",
            "tax_code": "media",
            "name": "Streaming Pack (bundle)",
            "type": "digital",
            "price": { "currency": "ghs", "value": 100 },
            "quantity": 2,
            "reference": "stream-pack-2"
          }
        }
      ],
      "total": { "currency": "ghs", "value": 400 }
    },
    "payment": {
      "id": "py_6q8wxs",
      "statement_descriptor": "STATEMENT",
      "payment_method": {
        "id": "pm_OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa",
        "customer_id": "cu_dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
        "type": "mobile_money",
        "issuer": "mtn",
        "number": "0242057831",
        "created_at": "2025-01-13T11:00:00Z",
        "verified": false
      },
      "amount": { "currency": "ghs", "value": 400 },
      "next_action": {
        "type": "confirm_payment",
        "confirm_payment": {
          "expires_at": "2025-01-13T11:08:00Z",
          "scheme": "zcommerce_defined_auth",
          "request": {
            "id": "token_req_2",
            "recipient": "0242057831",
            "sent_via": "sms",
            "token_size": 6,
            "sender_id": "zverify"
          }
        }
      },
      "status": "requires_action",
      "initiated_at": "2025-01-13T11:00:00Z"
    },
    "invoice": {
      "id": "inv_6q8wxs",
      "deliveries": null,
      "format": {
        "web": { "url": "https://checkout.zebo.dev/or_6q8wxs" },
        "pdf": { "url": "https://checkout.zebo.dev/or_6q8wxs/pdf" }
      }
    },
    "customer": {
      "id": "cu_dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
      "email_address": "customer@example.com",
      "phone_number": "+244242057831",
      "created_at": "2025-01-13T11:00:00Z",
      "name": "Customer Name"
    },
    "shipping": null
  }
}

POST/orders/new

Create with payment method

When the customer has a saved payment method, reference it by ID to charge immediately. You'll need both customer_id and payment_method_id.

Required attributes

Name
payment_method_id
Type
string
Description
ID of the saved payment method to charge.
line_itemsarrayCart contents. Matches the same schema shown in the first create example.Click or tap to expand
- Name
  type
  Type
  string
  Description
  Discriminator for the entry (product, fee, or shipping).
- Name
  product
  Type
  object
  Description
  Required when type is product. Includes product details, price, and quantity.
  View product attributesClick or tap to expand
  Name
  type
  Type
  string
  Description
  physical or digital.
  Name
  name
  Type
  string
  Description
  Customer-facing label.
  Name
  quantity
  Type
  integer
  Description
  Number of units.
  Name
  price
  Type
  object
  Description
  Money object with currency + value.
  View price attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Lowercase ISO 4217 code (e.g., ghs).
  Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit.
- Name
  fee
  Type
  object
  Description
  Required when type is fee. Captures service or convenience charges.
  View fee attributesClick or tap to expand
  Name
  label
  Type
  string
  Description
  Customer-facing description for the fee.
  Name
  description
  Type
  string
  Description
  Internal note about what this fee covers.
  Name
  amount
  Type
  object
  Description
  Money object describing the fee amount.
  View amount attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Currency code.
  Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit.
- Name
  shipping
  Type
  object
  Description
  Required when type is shipping. Defines fulfillment costs.
  View shipping attributesClick or tap to expand
  Name
  fee
  Type
  object
  Description
  Money object with currency + value for the shipping charge.
  View fee attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Currency code.
  Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit.

Request

POST

/orders/new

curl https://api.zebo.dev/orders/new \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cu_dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
    "payment_method_id": "pm_OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa",
    "execute_payment": true,
    "line_items": [
      {
        "type": "product",
        "product": {
          "type": "digital",
          "name": "Software License",
          "quantity": 1,
          "price": { "currency": "ghs", "value": 1200 }
        }
      }
    ]
  }'

Response

{
  "order": {
    "id": "or_yj0snl",
    "number": "ORDER-NUMBER",
    "customer_id": "cu_dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
    "payment_method_id": "pm_OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa",
    "status": "requires_payment",
    "initiated_at": "2025-01-13T11:30:00Z",
    "sealed_at": "2025-01-13T11:30:01Z",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "prod_software",
            "about": "Annual software license",
            "tax_code": "software",
            "name": "Software License",
            "type": "digital",
            "price": { "currency": "ghs", "value": 1200 },
            "quantity": 1,
            "reference": "software-license-annual"
          }
        }
      ],
      "total": { "currency": "ghs", "value": 1200 }
    },
    "payment": {
      "id": "py_yj0snl",
      "statement_descriptor": "STATEMENT",
      "payment_method": {
        "id": "pm_OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa",
        "customer_id": "cu_dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
        "type": "mobile_money",
        "issuer": "mtn",
        "number": "0242057831",
        "created_at": "2025-01-13T11:30:00Z",
        "verified": false
      },
      "amount": { "currency": "ghs", "value": 1200 },
      "next_action": {
        "type": "confirm_payment",
        "confirm_payment": {
          "expires_at": "2025-01-13T11:38:00Z",
          "scheme": "zcommerce_defined_auth",
          "request": {
            "id": "token_req_3",
            "recipient": "0242057831",
            "sent_via": "sms",
            "token_size": 6,
            "sender_id": "zverify"
          }
        }
      },
      "status": "requires_action",
      "initiated_at": "2025-01-13T11:30:00Z"
    },
    "invoice": {
      "id": "inv_yj0snl",
      "deliveries": null,
      "format": {
        "web": { "url": "https://checkout.zebo.dev/or_yj0snl" },
        "pdf": { "url": "https://checkout.zebo.dev/or_yj0snl/pdf" }
      }
    },
    "customer": {
      "id": "cu_dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
      "email_address": "customer@example.com",
      "phone_number": "+244242057831",
      "created_at": "2025-01-13T11:00:00Z",
      "name": "Customer Name"
    },
    "shipping": null
  }
}

POST/orders/new

Create and finalize

Use the finalize parameter to explicitly lock an order before payment. This creates an immutable order with a generated invoice—perfect for quote workflows, approval processes, or when you want customers to review the final order before paying.

When finalize: true, the order is finalized immediately regardless of whether payment will be executed. The order becomes read-only, and the sealed_at timestamp is set.

Request

POST

/orders/new

curl https://api.zebo.dev/orders/new \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cu_abc123",
    "finalize": true,
    "line_items": [
      {
        "type": "product",
        "product": {
          "type": "physical",
          "name": "Enterprise Plan (Annual)",
          "quantity": 1,
          "price": {"currency": "ghs", "value": 120000}
        }
      }
    ]
  }'

Response

{
  "order": {
    "id": "or_xyz789",
    "number": "ORD-2025-001",
    "status": "requires_payment",
    "customer_id": "cu_abc123",
    "initiated_at": "2025-01-27T00:35:00Z",
    "sealed_at": "2025-01-27T00:35:01Z",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "prod_enterprise",
            "name": "Enterprise Plan (Annual)",
            "type": "physical",
            "quantity": 1,
            "price": {
              "currency": "ghs",
              "value": 120000
            }
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 120000
      }
    },
    "invoice": {
      "id": "inv_xyz789",
      "format": {
        "web": {
          "url": "https://checkout.zebo.dev/or_xyz789"
        },
        "pdf": {
          "url": "https://checkout.zebo.dev/or_xyz789/pdf"
        }
      }
    },
    "customer": {
      "id": "cu_abc123",
      "name": "Acme Corporation",
      "email_address": "billing@acme.com"
    }
  }
}

POST/orders/pay

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: Send order_id + payment_method_data—we'll save it to the order for future retries.
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.

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
  issuer
  Type
  enum
  Description
  Wallet network: mtn, vodafone, or airteltigo.
  Name
  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.

Request

POST

/orders/pay

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

Response

{}

POST/orders/confirm_payment

Confirm a payment

Submit the OTP your customer received to complete the payment. On success, the order moves to paid. Some providers require an additional authorization step—if so, the order goes to authorize_payment and you can prompt the customer to approve it in their provider app.

Request

POST

/orders/confirm_payment

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

Response

{}

POST/orders/request_confirmation

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 {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi"
  }'

Response

{
  "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",
        "issuer": "mtn",
        "number": "0242057831",
        "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": "gloria@kesewaa.co",
      "phone_number": "+233544998605",
      "name": "Gloria Kesewaa"
    }
  }
}

POST/orders/finalize

Finalize an order

Finalize an order to lock it for payment. Once finalized, the order becomes immutable—line items, totals, and customer data can no longer be changed. 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
Totals lock: The amount due becomes fixed
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 {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
  }'

Response

{
  "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"
    }
  }
}

POST/orders/complete

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 {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
  }'

Response

{
  "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
      }
    }
  }
}

POST/orders/lookup

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 {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
  }'

Response

{
  "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",
        "issuer": "mtn",
        "number": "0594870087",
        "created_at": "2025-09-14T16:24:41.171905592Z",
        "verified": true
      },
      "latest_attempt": {
        "payment_method_type": "mobile_money",
        "payment_method_id": "pm_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://checkout.zebo.dev/48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
        },
        "pdf": {
          "url": "https://checkout.zebo.dev/48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt/pdf"
        }
      }
    },
    "customer": {
      "id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
      "email_address": "yaw@konadu.ie",
      "phone_number": "+233559714200",
      "name": "Anita Segnom"
    },
    "status": "completed",
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
  }
}

POST/orders/page

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 1 always contains the freshest activity and subsequent pages step back in time.

Optional attributes

Name
page_number
Type
integer
Description
1-based page index to fetch. Must be between 1 and 10 inclusive—use the default (1) to start from the latest orders.
Name
page_size
Type
integer
Description
Number of orders per page (1–256). The response echoes the count we actually returned, so the last page can be smaller than what you requested.

Response shape

Top level page object includes number, size, and an orders array.
Every order summary contains status + timestamps (initiated_at, sealed_at, completed_at when present) and a condensed line_item_group with products_count and computed total.
customer is included when the order is tied to a buyer and surfaces id, name, and any known email, phone_number, suffix, or title.

Request

POST

/orders/page

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

Response

{
  "page": {
    "number": 1,
    "size": 2,
    "orders": [
      {
        "id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
        "line_item_group": {
          "products_count": 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",
        "status": "requires_payment",
        "customer": {
          "id": "py_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
          "name": "Gloria Kesewaa",
          "email": "gloria@kesewaa.co",
          "phone_number": "+233544998605"
        }
      },
      {
        "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
        "line_item_group": {
          "products_count": 1,
          "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",
          "name": "Anita Segnom",
          "email": "yaw@konadu.ie",
          "phone_number": "+233559714200"
        }
      }
    ]
  }
}