Orders
Every order is a complete record of a transaction, from line items and customer data to payment state and fulfillment metadata. 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
- Name
id- Type
- string
- Description
Unique identifier for this order—use it for lookups, updates, and payment operations.
- Name
number- Type
- string
- Description
Human-friendly reference like
ORDER-1234for your internal systems and customer communication.
- Name
status- Type
- string
- Description
Current lifecycle state:
requires_payment,paid,completed, etc.
- Name
statement_descriptor- Type
- string
- Description
What shows up on the customer's bank or mobile money statement—keep it recognizable.
- Name
initiated_at- Type
- timestamp
- Description
When we started processing this order.
- Name
sealed_at- Type
- timestamp
- Description
When the order was finalized and became immutable—ready for payment or fulfillment.
line_item_groupobjectCart contents and totals.Click or tap to expand- 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
ghsorusd.
- Name
value- Type
- integer
- Description
- Amount in smallest unit (cents, pesewas, etc.).
- Name
line_items- Type
- array
- Description
- Array of products, fees, and shipping charges—each with a
typediscriminator.
View line_items attributesClick or tap to expand
- Name
type- Type
- string
- Description
- Line item type:
product,fee, orshipping.
- Name
product- Type
- object
- Description
- Product details when
typeisproduct.
View product attributesClick or tap to expand
- Name
id- Type
- string
- Description
- Internal product ID for reconciliation and reporting.
- 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_datafield in the API.
- Name
tax_code- Type
- string
- Description
- Tax classification code for this item.
- Name
name- Type
- string
- Description
- Product name shown to the customer.
- Name
type- Type
- string
- Description
physicalordigital—affects shipping requirements.
- Name
reference- Type
- string
- Description
- Your SKU or internal product reference.
- 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
fee- Type
- object
- Description
- Fee details when
typeisfee—covers service charges, convenience fees, etc.
View fee attributesClick or tap to expand
- Name
id- Type
- string
- Description
- Fee identifier.
- Name
description- Type
- string
- Description
- Internal note about what this fee covers.
- Name
label- Type
- string
- Description
- Customer-facing label for this fee.
- 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
shipping- Type
- object
- Description
- Shipping details when
typeisshipping.
View shipping attributesClick or tap to expand
- Name
id- Type
- string
- Description
- Unique ID for this shipping charge.
- 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.
paymentobjectPayment intent tied to this order.Click or tap to expand- Name
id- Type
- string
- Description
- Payment intent ID—use this to track and update payment state.
- Name
statement_descriptor- Type
- string
- Description
- What the customer sees on their bank statement.
- 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
payment_method- Type
- object
- Description
- The payment method being charged.
View payment_method attributesClick or tap to expand
- Name
id- Type
- string
- Description
- Saved payment method ID.
- Name
customer_id- Type
- string
- Description
- Which customer owns this payment method.
- Name
type- Type
- string
- Description
- Payment rail:
mobile_money,card,bank, etc.
- Name
issuer- Type
- string
- Description
- Network provider:
mtn,vodafone,visa, etc.
- Name
number- Type
- string
- Description
- Masked or tokenized account identifier.
- Name
created_at- Type
- timestamp
- Description
- When this method was added.
- Name
verified- Type
- boolean
- Description
- Whether the payment method passed verification.
- Name
next_action- Type
- object
- Description
- What needs to happen next to complete the payment.
View next_action attributesClick or tap to expand
- Name
type- Type
- string
- Description
- Action required:
confirm_payment,authorize_payment, etc.
- Name
confirm_payment- Type
- object
- Description
- OTP confirmation flow metadata.
View confirm_payment attributesClick or tap to expand
- Name
expires_at- Type
- timestamp
- Description
- When this OTP token expires.
- Name
scheme- Type
- string
- Description
- Auth scheme: typically
zcommerce_defined_auth.
- 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
sent_via- Type
- string
- Description
- Delivery channel:
smsoremail.
- Name
token_size- Type
- integer
- Description
- Length of the OTP code (usually 6).
- Name
sender_id- Type
- string
- Description
- Sender name shown to the customer (e.g.,
zverify).
- Name
latest_attempt- Type
- object|null
- Description
- Details about the most recent charge attempt—
nulluntil we try to collect payment.
View latest_attempt attributesClick or tap to expand
- Name
payment_method_type- Type
- string
- Description
- Payment rail used for this attempt.
- Name
payment_method_id- Type
- string
- Description
- Payment method that was charged.
- Name
reference- Type
- string
- Description
- Gateway reference or transaction ID.
- Name
status- Type
- string
- Description
- Attempt status:
pending,succeeded,failed, etc.
- Name
initiated_at- Type
- timestamp
- Description
- When this attempt started.
- Name
succeeded_at- Type
- timestamp|null
- Description
- Set when the attempt succeeds.
- Name
failed_at- Type
- timestamp|null
- Description
- Set when the attempt fails.
- Name
status- Type
- string
- Description
- Payment state:
requires_action,processing,succeeded,failed, etc.
- Name
initiated_at- Type
- timestamp
- Description
- When we kicked off the payment intent.
- Name
executed_at- Type
- timestamp|null
- Description
- When the customer authorized execution (set after we pass OTP or 3DS).
- Name
paid_at- Type
- timestamp|null
- Description
- When funds were fully captured and marked as paid.
- Name
balance_transaction- Type
- object|null
- Description
- Ledger entry created once the payment settles.
nulluntil the payment is paid.
View balance_transaction attributesClick or tap to expand
- Name
id- Type
- string
- Description
- Balance transaction ID.
- Name
payout_id- Type
- string|null
- Description
- Payout that will disburse the funds (nullable until scheduled).
- Name
payment_id- Type
- string
- Description
- Payment this transaction is tied to.
- Name
created_at- Type
- timestamp
- Description
- When the balance transaction was created.
- Name
paid_at- Type
- timestamp|null
- Description
- When the payout was completed.
- 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.
invoiceobjectInvoice generated for this order.Click or tap to expand- Name
id- Type
- string
- Description
- Unique invoice ID.
- Name
deliveries- Type
- array|null
- Description
- Email/SMS delivery log—
nullif not yet sent.
- Name
format- Type
- object
- Description
- Invoice viewing links.
View format attributesClick or tap to expand
- 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
pdf- Type
- object
- Description
- PDF download.
View pdf attributesClick or tap to expand
- Name
url- Type
- string
- Description
- Direct PDF link.
customerobjectCustomer who placed this order.Click or tap to expand- Name
id- Type
- string
- Description
- Customer ID.
- Name
name- Type
- string
- Description
- Full name for billing and communication.
- Name
email_address- Type
- string
- Description
- Email for receipts and updates.
- Name
phone_number- Type
- string
- Description
- Phone number for OTP and notifications.
- Name
created_at- Type
- timestamp
- Description
- When this customer was created.
shippingobjectShipping details—nullfor 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
name- Type
- string
- Description
- Recipient name.
- Name
phone_number- Type
- string
- Description
- Contact number for delivery.
- 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
country- Type
- string
- Description
- Country.
- Name
district- Type
- string
- Description
- District or locality.
- Name
post_code- Type
- string
- Description
- Postal/ZIP code.
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_datafor first-time checkouts. - Existing customer, new payment method: Use
customer_idwith freshpayment_method_datawhen the customer wants to pay with a different instrument. - Order now, pay later: Provide only
customer_idorcustomer_dataand skip the payment method—you'll charge it later via/orders/pay.
Rules
- Exactly one of
customer_idorcustomer_datais required. - Set
execute_paymenttotrueonly when a payment method is attached (payment_method_idorpayment_method_data). Omit it or passfalseto 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, orshipping. Matches the schemas in our OpenAPI spec.
- Name
product- Type
- object
- Description
- Required when
typeisproduct. Must includetype,name,price, andquantityinside this object.
View product attributesClick or tap to expand
- Name
id- Type
- string
- Description
- Optional product ID for reconciliation.
- Name
type- Type
- string
- Description
physicalordigitalto 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
Moneyschema.
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 metadata. Matches the
custom_dataobject in the spec.
- Name
fee- Type
- object
- Description
- Required when
typeisfee. 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
Moneyschema).
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
typeisshipping. 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 withcustomer_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
metadata- 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_moneyis supported for inline collection.
- Name
mobile_money- Type
- object
- Description
- Required when
typeismobile_money. Provides wallet metadata.
View mobile_money attributesClick or tap to expand
- Name
issuer- Type
- enum
- Description
- Wallet network:
mtn,vodafone, orairteltigo.
- 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/paylater.
- 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. Whenfalseor 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.
- Name
redirect_url- Type
- string
- Description
Where to redirect the customer after completing a hosted checkout session.
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
Addressin 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.
Request
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,
"redirect_url": "https://google.com/thank-you",
"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": "ord_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": "pay_3deNYy",
"statement_descriptor": "STMTDESC",
"payment_method": {
"id": "pm_wveyHj",
"customer_id": "cus_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://pages.zebo.dev/invoices/ord_f8y1p1" },
"pdf": { "url": "https://pages.zebo.dev/invoices/ord_f8y1p1/pdf" }
}
},
"customer": {
"id": "cus_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"
}
}
}
}
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
curl https://api.zebo.dev/orders/new \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
"payment_method_id": "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": "ord_6q8wxs",
"number": "ORDER-NUMBER",
"customer_id": "dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
"payment_method_id": "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": "pay_6q8wxs",
"statement_descriptor": "STATEMENT",
"payment_method": {
"id": "OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa",
"customer_id": "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://pages.zebo.dev/invoices/ord_6q8wxs" },
"pdf": { "url": "https://pages.zebo.dev/invoices/ord_6q8wxs/pdf" }
}
},
"customer": {
"id": "dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
"email_address": "customer@example.com",
"phone_number": "+244242057831",
"created_at": "2025-01-13T11:00:00Z",
"name": "Customer Name"
},
"shipping": null
}
}
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, orshipping).
- Name
product- Type
- object
- Description
- Required when
typeisproduct. Includes product metadata, price, and quantity.
View product attributesClick or tap to expand
- Name
type- Type
- string
- Description
physicalordigital.
- 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
typeisfee. 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
typeisshipping. Defines fulfillment costs.
View shipping attributesClick or tap to expand
- Name
fee- Type
- object
- Description
- Money object with
currency+valuefor 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
curl https://api.zebo.dev/orders/new \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
"payment_method_id": "OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa",
"execute_payment": true,
"line_items": [
{
"type": "product",
"product": {
"type": "digital",
"name": "Software License",
"quantity": 1,
"price": { "currency": "ghs", "value": 1200 }
}
}
]
}'
Response
{
"order": {
"id": "ord_yj0snl",
"number": "ORDER-NUMBER",
"customer_id": "dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
"payment_method_id": "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": "pay_yj0snl",
"statement_descriptor": "STATEMENT",
"payment_method": {
"id": "OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa",
"customer_id": "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://pages.zebo.dev/invoices/ord_yj0snl" },
"pdf": { "url": "https://pages.zebo.dev/invoices/ord_yj0snl/pdf" }
}
},
"customer": {
"id": "dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ",
"email_address": "customer@example.com",
"phone_number": "+244242057831",
"created_at": "2025-01-13T11:00:00Z",
"name": "Customer Name"
},
"shipping": null
}
}
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
curl https://api.zebo.dev/orders/new \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_abc123",
"finalize": true,
"line_items": [
{
"type": "product",
"product": {
"type": "physical",
"name": "Enterprise Plan (Annual)",
"quantity": 1,
"price": {"currency": "ghs", "value": 120000}
}
}
]
}'
Response
{
"order": {
"id": "ord_xyz789",
"number": "ORD-2025-001",
"status": "requires_payment",
"customer_id": "cus_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://pages.zebo.dev/invoices/ord_xyz789"
},
"pdf": {
"url": "https://pages.zebo.dev/invoices/ord_xyz789/pdf"
}
}
},
"customer": {
"id": "cus_abc123",
"name": "Acme Corporation",
"email_address": "billing@acme.com"
}
}
}
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, orpaid_out_of_band, never multiple. paid_out_of_bandis mutually exclusive with payment method parameters.- Any
payment_method_idmust 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_moneyis accepted when supplying inline details.
- Name
mobile_money- Type
- object
- Description
- Required when
typeismobile_money. Mirrors theMobileMoneyschema.
View mobile_money attributesClick or tap to expand
- Name
issuer- Type
- enum
- Description
- Wallet network:
mtn,vodafone, orairteltigo.
- 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
truewhen payment was received outside Commerce (cash, bank transfer, check). Marks the payment as paid offline and completes the payment immediately. Mutually exclusive withpayment_method_idandpayment_method_data. Defaults tofalse.
Request
curl https://api.zebo.dev/orders/pay \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"order_id": "JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
"payment_method_data": {
"type": "mobile_money",
"mobile_money": {
"issuer": "mtn",
"number": "0544998605"
}
}
}'
Response
{}
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
curl https://api.zebo.dev/orders/confirm_payment \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"order_id": "JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
"token": "302673"
}'
Response
{}
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
curl https://api.zebo.dev/orders/request_confirmation \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"order_id": "kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi"
}'
Response
{
"order": {
"id": "kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
"status": "requires_payment",
"line_item_group": {
"line_items": [
{
"type": "product",
"product": {
"id": "fNa3i3QPkt4yU5FQHoM042tRFAdthCbcRZJdZnrl",
"reference": "fNa3i3QPkt4yU5FQHoM042tRFAdthCbcRZJdZnrl",
"about": "Tollo victoria advenio crudelis facere crudelis. Aequitas voco correptius suspendo fuga demergo. Angelus texo pecto.",
"metadata": {
"size": "56",
"some": "metadata"
},
"tax_code": "gold",
"name": "Awesome Fresh Gloves",
"type": "digital",
"price": {
"currency": "ghs",
"value": 20
},
"quantity": 1
}
},
{
"type": "product",
"product": {
"id": "deeYHxzydDJWU1w9YCjOvgDirYv37WyYmI9MhdEA",
"reference": "deeYHxzydDJWU1w9YCjOvgDirYv37WyYmI9MhdEA",
"about": "Sunt astrum verecundia cenaculum. Asporto voluptas mollitia voluptate vaco concedo bellum clam aufero taedium. Admiratio cohibeo ullus comis alter.",
"metadata": {
"size": "56",
"some": "metadata"
},
"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": "8QNM4ujclxXUDZBnL9ujyPfMG4Bk6ZRMBeRtc99l",
"statement_descriptor": "STATEMENT",
"payment_method": {
"id": "acA9cJRhjZHw1Gs4p39fKTbp1AgsFjhBk1AwIuVf",
"customer_id": "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": "N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
"email_address": "gloria@kesewaa.co",
"phone_number": "+233544998605",
"name": "Gloria Kesewaa"
}
}
}
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
curl https://api.zebo.dev/orders/finalize \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"order_id": "48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'
Response
{
"order": {
"number": "ORDER-12345",
"status": "requires_payment",
"payment_id": "pay_xyz123abc456",
"customer_id": "cus_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"
}
}
}
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
trueif payment was received outside Commerce (cash, bank transfer, check). When true, the payment is marked as paid offline before completing the order. Defaults tofalse, which requires the payment to already be inpaidstatus.
Request
curl https://api.zebo.dev/orders/complete \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"order_id": "48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'
Response
{
"order": {
"number": "ORDER-12345",
"status": "completed",
"payment_id": "pay_xyz123abc456",
"customer_id": "cus_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
curl https://api.zebo.dev/orders/lookup \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"order_id": "48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'
Response
{
"order": {
"line_item_group": {
"line_items": [
{
"product": {
"id": "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": "OHFv6I3OZBvB1R46TQQGNxPPtgbPR6CXpQ8En9wl",
"statement_descriptor": "STATEMENT",
"payment_method": {
"id": "hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
"customer_id": "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": "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": "OHFv6I3OZBvB1R46TQQGNxPPtgbPR6CXpQ8En9wl",
"created_at": "2025-09-14T16:29:45Z",
"paid_at": "2025-09-15T08:00:00Z",
"amount": {
"currency": "ghs",
"value": 200
}
}
},
"invoice": {
"id": "bRSGJcH7v4oLIAa3KlBmB9K6ZoRUucJXAJMWxl1KQq0JCZs0oOEG8ibCeGn1",
"format": {
"web": {
"url": "https://pages.zebo.dev/invoices/48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
},
"pdf": {
"url": "https://pages.zebo.dev/invoices/48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt/pdf"
}
}
},
"customer": {
"id": "ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
"email_address": "yaw@konadu.ie",
"phone_number": "+233559714200",
"name": "Anita Segnom"
},
"status": "completed",
"id": "48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}
}
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
pageobject includespage_number,page_size, and anordersarray. - Every order summary contains status + timestamps (
initiated_at,sealed_at,completed_atwhen present) and a condensedline_item_groupwithproducts_countand computedtotal. customeris included when the order is tied to a buyer and surfacesid,name, and any knownemail,phone_number,suffix, ortitle.
Request
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": {
"page_number": 1,
"page_size": 2,
"orders": [
{
"id": "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": "N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
"name": "Gloria Kesewaa",
"email": "gloria@kesewaa.co",
"phone_number": "+233544998605"
}
},
{
"id": "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": "ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
"name": "Anita Segnom",
"email": "yaw@konadu.ie",
"phone_number": "+233559714200"
}
}
]
}
}