An order represents a customer's intent to pay for something. It captures the amount, currency, and customer reference before any payment attempt begins. Every payment in Nimbbl is linked to an order — you create the order first, then the customer makes one or more payment attempts against it.

What is an Order?

Order Definition

An order is the starting point for every transaction in Nimbbl. When a customer initiates a purchase on your platform, your server creates an order through the Create Order API. The order captures:

• Amount — the total amount to be collected
• Currency — the transaction currency (e.g., INR, USD)
• Invoice ID — your internal reference ID for tracking
• Customer details — mobile number, email, and name (when available)
• Custom attributes — additional metadata you want to associate with the order

The order receives a unique order_id from Nimbbl (e.g., o_Rk7mNpQ3xW9vLa2B) that you use to track it throughout its lifecycle.

Order Lifecycle and States

An order moves through defined states as payment attempts are made:

State	Description	Why It Moves	Possible Next States
New	Order created, awaiting first payment attempt.	Your server called the Create Order API and Nimbbl created the order record.	Pending
Pending	Order is active, no successful payment yet. The customer can still attempt payment.	A payment attempt was initiated against this order. The order stays in Pending as long as payment attempts are being made and none have succeeded.	Completed, Lapsed
Completed	A payment attempt succeeded. The order amount has been collected.	A payment linked to this order moved to Succeeded. This is a terminal state -- no further payment attempts are accepted.	—
Lapsed	All payment attempts failed or the order expired without a successful payment. Orders are automatically lapsed after 24 hours by default. Merchants can configure a different validity period.	The maximum number of payment attempts was reached, the order validity period expired, or a payment was reversed.	Completed (rare)

info

An order can have multiple payment attempts. If a payment fails, the order remains in Pending and the customer can retry with the same or a different payment mode -- up to the configured payment attempt limit.

Why Lapsed can move to Completed

In rare cases, a payment that was initially reported as failed may later be confirmed as successful through a delayed notification from the payment partner. If this happens while the order is in Lapsed state, the order moves to Completed. Always use webhooks to stay updated on order state changes.

Order Attributes

Key attributes of an order:

Attribute	Description
order_id	Nimbbl's unique order identifier (e.g., o_Rk7mNpQ3xW9vLa2B)
invoice_id	Your internal reference ID for tracking this order
amount_before_tax	Cart amount before tax
tax	Total tax amount
total_amount	Total payable amount including tax
currency	Order currency code (e.g., INR)
quantity	Total item count across all line items
status	Current order state (New, Pending, Completed, or Lapsed)
user	Customer details (mobile number, email)
shipping_address	Customer's delivery address
billing_address	Customer's billing address
line_items	Array of items in the order (see below)
additional_charges	Convenience fees or surcharges applied to the order
shipping_charges	Delivery charges
cod_charges	Cash on Delivery charges, if applicable
description	Order description
custom_attributes	Additional metadata associated with the order

Line item attributes (each item in the line_items array):

Attribute	Description
sku_id	Your internal SKU identifier
name	Item name
description	Item description
amount_before_tax	Item amount before tax
tax	Tax amount for this item
rate	Unit rate for the item
quantity	Number of units
image_url	URL to the item image

Relationship to Payments

Each order can have multiple payment attempts, but only one payment can succeed. Once a payment succeeds, the order moves to Completed and no further payment attempts are accepted.

• A Pending order has zero successful payments. It may have failed payment attempts.
• A Completed order has exactly one successful payment.
• A Lapsed order has zero successful payments and can no longer accept new attempts.

Once an order is completed, the successful payment can be referenced for refund processing.

Working with Orders

Creating Orders

Orders are created through a server-to-server API call. Your backend sends the order details to Nimbbl and receives an order_id in response:

1. Customer initiates purchase on your platform
2. Your server calls the Create Order API with the amount, currency, and customer details
3. Nimbbl returns an order_id
4. You pass the order_id to the checkout (Sonic, SDK, or API) to start the payment flow

tip

Always create orders from your server, never from the client side. This ensures order integrity and prevents tampering with amounts or currency.

Handling Order States

Your integration should handle order state changes through one of these mechanisms:

• Webhooks (recommended) — receive real-time notifications when order state changes. See Webhooks and Transaction Enquiry.
• Transaction Enquiry API — poll Nimbbl to check order state. Useful as a fallback when webhooks are delayed.
• Callback response — for SDK integrations, the checkout callback returns the final order state.

Always validate the response signature before trusting the order state received from callbacks.

Updating Orders

Orders can be updated while they are in Pending state (before a successful payment). Once an order is Completed or Lapsed, it cannot be modified.

Related Reading

Standard Checkout Server SetupCreating orders through the server integrationCommand Center Search OrdersViewing and managing orders in Command Center