# Create a new order

Create an order for checkout in one of two ways:
- **Order without quote** - specify the amount, currency and payment methods inline
(`Orders`).
- **Order with quote** - pass a `quote_id` from `POST /quotes` (with `resource: payin`) to bind
the order to a quote. When supplied, the quote is the single source of truth for amount,
currency, payment method, expiry and fee splits; the locked fields (`amount`, `currency`,
`price_id`, `payment_methods`, `split_ids`) must not be sent (`CreateOrderWithQuoteRequest`).
**When a `quote_id` is supplied, the order's expiry is set to the quote's expiry.**

The request variant is selected by the presence of `quote_id`.
An **account funding** order is bound to a quote with `resource_type: account_funding` and also requires `beneficiary_id`. A declined order answers `422` with a `code`.
Pass `split_ids` to declare your share of a dynamic pricing rule's fee for this order. See [Dynamic Fee Split](#tag/pricing_split). If a split on the order later stops resolving (Glomo deleted the underlying rule, or the rule is no longer dynamic) opening the checkout returns a `400 Bad Request`, the order is expired, and you must issue a new one.
To check complete list of API validations, click [here](/platform/validations#validations-for-creating-orders).

Endpoint: POST /orders
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `customer_id` (string)
    The unique identifier of customer linked to order.
    Example: cust_E602dMzgjpDC

  - `document_id` (string)
    The unique identifier of document linked to order. This document entity should contain the required documents to process incoming payments. Refer this [Document](#tag/Document) entity for more details.
    Example: doc_nYUqLpuYQ0M8

  - `currency` (string)
    The currency the order is collected in, as an uppercase [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. Must be one of the listed values; the match is case-sensitive. `INR` is not accepted.
    Enum: "USD", "EUR", "GBP", "AED", "SGD", "AUD"

  - `amount` (number)
    The amount you want to receive, a positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.
    Example: 1000

  - `purpose_code` (string)
    Why you are receiving this payment, as a code from a fixed set: see [Payin purpose codes](/payin/purpose-codes). This is not free text. Pass a listed code exactly, for example `P1401`; matching is exact and case-sensitive. Payins and payouts use different sets, so a payout code such as `S1401` is rejected here. An unrecognised code is rejected with `400 Bad Request`.
Optional on orders. When omitted, Glomo applies your account's default payin purpose code if one has been configured.
    Example: P1401

  - `invoice_number` (string)
    Number/Id of the invoice submitted with order. LRS orders (sent with `lrs`) don't store this field and return it as `null`, but a value you send is still validated.
    Example: RG12FF590

  - `invoice_description` (string)
    Description about the invoice submitted with order
    Example: Payment requested for services provided

  - `invoice_amount` (number)
    The amount on the invoice, in the smallest unit of the order's `currency`, the same unit as `amount` (cents for USD). `1000` is $10.00 when `currency` is USD. Must be greater than or equal to `amount`.
    Example: 1000

  - `reference_number` (string)
    optional identifier to be sent for reconciliations
    Example: R0001

  - `price_id` (string)
    The unique identifier of 'Price' entity linked to the order. This is the referral fee for this order. Note: price_id is only applicable for platform businesses.
    Example: price_E602dMzgjpDC

  - `split_ids` (array)
    The pricing splits to apply, each entry an `id` returned by [Create a pricing split](#tag/pricing_split). A split fixes your share of a dynamic rule's fee and the customer bears the remainder. Omit `split_ids` and no dynamic rule is applied — pricing falls back to your normal (non-dynamic) rules.
`split_ids` and `payment_methods` are independent. `payment_methods` restricts which methods the checkout offers. `split_ids` only changes how the fee for a method is priced: a split applies to its own payment method whether or not that method appears in `payment_methods`, and a split never adds a method to the checkout or removes one from it. One checkout can therefore price one method from a dynamic split and another method from your normal rules.
Every id must exist, must belong to your business, and must still point at a live dynamic rule. When two dynamic rules share a dimension — the same payment method, subtype, rail, currency and fee type — declare a split for every one of them or the request is rejected. On payment links and orders, a split whose payment method is not enabled for your business is also rejected.
A subscription only ever charges `card`, or `pay_via_bank` when SEPA-eligible, so a split declared for any other payment method is rejected at subscription creation and on an auto debit. An auto-debit override must be declared for the method the subscription actually charges.
Glomo can configure your account to require a declaration. On such an account, a payment link, an order, a payin quote or an `as_presented` subscription that omits `split_ids` is rejected.
    Example: ["psplit_7Kq2mXbTdLp9"]

  - `product` (object)
    Details of the product that the payment is related to.
    Example: {"name":"ShieldGuard Insurance","description":"Flexible insurance for belongings travel and digital assets easy to manage"}

  - `product.name` (string, required)
    Name of the product

  - `product.description` (string)
    Description of the product

  - `notes` (object | null)
    Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. Your account may require some `notes` fields: Glomo configures custom field rules per account, and for beneficiaries they are checked when the beneficiary is created. Some fields are also validated by the beneficiary's country (for example, a PAN format for Indian beneficiaries). A missing required field returns `422` with `Validation failed: Notes <field> is required`, and type and validation errors (such as enum constraints) are returned the same way. The rule is set on your account, not by currency or rail. No API lists the fields, but the `422` names each missing one: add that key to `notes` with the value your account expects, and ask your Glomo account manager if you don't know what the field should hold. See [Custom fields](/payin/custom-fields). Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
    Example: {"invoice_ref":"INV-2026-001","project":"Alpha"}

  - `bank_account_details` (object)
    Optional bank account details to associate with the customer for this order. When provided, the bank account will be linked to the customer and associated with this order. Either bic_primary or bic_secondary must be provided when including this field.
    Example: {"account_number":"1234567890","bic_primary":"HDFCINBBDEL","bank_customer_id":"7189204715"}

  - `bank_account_details.account_number` (string, required)
    The bank account number
    Example: 1234567890

  - `bank_account_details.bic_primary` (string)
    SWIFT code for the bank account. Will be null if not provided in the request.
    Example: HDFCINBBDEL

  - `bank_account_details.bic_secondary` (string)
    Local routing code for the bank account like IFSC. Will be null if not provided in the request.
    Example: HDFC0001097

  - `bank_account_details.bank_customer_id` (string)
    Optional bank customer identifier provided by the bank
    Example: 7189204715

  - `lrs` (object)
    Send this object to create an LRS order: a remittance from a customer resident in India, funded
from their Indian bank account. If you send `lrs`, `lrs_quote_id` and `remittance_information` are
required.
- Create the quote first with `POST /lrs/quotes`. The order's `amount` must equal the `USD` side of
the quote (`from.amount` for a `USD` source quote, `to.amount` for an `INR` source quote), and
`currency` must be `USD`. Otherwise the order is rejected with `400`.
- The quote must not have expired. The order expires when the quote does.
- The customer's country must be India, otherwise the order is rejected with `400`.
- An LRS order doesn't store `invoice_number`, `invoice_description`, `invoice_amount`,
`reference_number`, `document_id` or `product`; they come back as `null` or are left out. A value
you send is still validated, so leave these fields out.

Returned on the order when it was created as an LRS order.

  - `lrs.lrs_quote_id` (string, required)
    The `id` of a quote from `POST /lrs/quotes`, created by your account.
    Example: quote_6ab60de4Kx7Pq

  - `lrs.remittance_information` (string, required)
    Your reference for the remittance. Up to 20 characters, using only letters, digits and hyphens; spaces and other characters are rejected with `400`.
    Example: REF12345

  - `lrs.bank_account_id` (string)
    The `id` of the customer's LRS bank account, from `POST /customer/{id}/bank_account`. Optional. It must belong to this customer and be at the same bank as the quote's `bank_code`. A bank account from `POST /customer/{id}/bank-accounts` is not accepted here.
    Example: acclrs_68468c03g9xt7

  - `lrs.beneficiary_id` (string)
    The `id` of a beneficiary created with `category: lrs` through `POST /v2/beneficiaries`, to receive the remittance. Optional.
    Example: bene_68468c03g9xua

  - `payment_methods` (array)
    Array of payment methods that should be available for the customer on the checkout page. This field allows you to control which payment options your customers can use to complete the payment. You can specify one or multiple payment methods in the array. Each value must be a payment method enabled on your account; any other value is rejected with a `400`. Omit the field to offer every payment method enabled on your account.
    Example: ["card"]

  - `request_id` (string | null)
    Your unique identifier for this order, used to reject duplicates. If an order with the same `request_id` already exists on your account, the request is rejected with `400` and the message `Order already exists for this request_id`; the existing order is not returned. Look it up with `GET /v1/orders?request_id=<your_request_id>`. Returned on the order and its webhooks; `null` if you sent none.
    Example: unique_order_request_id_123

  - `quote_id` (string)
    ID of a quote (from `POST /api/v1/quotes` with `resource: "payin"`) to bind this order to. When supplied, the quote is the single source of truth for amount, currency, payment method, and expiry.
    Example: quote_3m4n5o6p7q

  - `beneficiary_id` (string)
    The account the funds land in, as a beneficiary created through [`POST /v2/beneficiaries`](#tag/beneficiary_v2/operation/createBeneficiaryV2).
Required for account funding orders, where it is the customer's own account. Not used by other payin orders.
    Example: bene_5JU9yv0lGSUP

  - `invoice_number` (string)
    Number/Id of the invoice submitted with order.
    Example: RG12FF590

  - `invoice_description` (string)
    Description about the invoice submitted with order.
    Example: Payment requested for services provided

  - `invoice_amount` (number)
    The amount on the invoice, in the smallest unit of the quote's `destination_currency`, which is the currency the order is created in (cents for USD). `1000` is $10.00 when that currency is USD. Must be greater than or equal to the quote's `destination_amount`.
    Example: 1000

  - `reference_number` (string)
    optional identifier to be sent for reconciliations.
    Example: R0001

  - `request_id` (string)
    Your unique identifier for this order, used to reject duplicates. If an order with the same `request_id` already exists on your account, the request is rejected with `400` and the message `Order already exists for this request_id`; the existing order is not returned. Look it up with `GET /v1/orders?request_id=<your_request_id>`. Resending with the same `quote_id` fails first with `400`, because the quote has already been used.
    Example: unique_order_request_id_123

## Response 201:

  - `201` (unknown)
    Order created successfully

## Response 201 fields (application/json):

  - `id` (string)
    The unique identifier for the order.
    Example: order_678a4c88hpAjf

  - `customer_id` (string)
    The unique identifier of customer linked to order.
    Example: cust_E602dMzgjpDC

  - `document_id` (string)
    The unique identifier of document linked to order. This document entity should contain the required documents to process incoming payments. Refer this [Document](#tag/Document) entity for more details.
    Example: doc_nYUqLpuYQ0M8

  - `status` (string)
    The status of the order.
- `active` - the order has been created and can be paid.
- `action_required` - Glomo needs more information before the order can be paid. Respond to the
open RFI to continue.
- `under_review` - the information you submitted is being reviewed. The order returns to `active` if
the review passes.
- `paid` - the order has been paid in full. Terminal. This is the success value, not `success`.
- `failed` - the order could not be accepted, for example because the review did not pass. Terminal.
- `cancelled` - the order was cancelled before it was paid. Terminal.
- `expired` - the order passed its expiry time without being paid. Not always final: a payment that
was already under way when the order expired can still complete it, moving it to `paid`.
    Enum: "active", "action_required", "under_review", "paid", "failed", "cancelled", "expired"

  - `currency` (string)
    The currency the order is collected in, as an uppercase [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. Must be one of the listed values; the match is case-sensitive. `INR` is not accepted.
    Enum: "USD", "EUR", "GBP", "AED", "SGD", "AUD"

  - `amount` (number)
    The amount you want to receive, a positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.
    Example: 1000

  - `purpose_code` (string)
    Why you are receiving this payment, as a code from a fixed set: see [Payin purpose codes](/payin/purpose-codes). This is not free text. Pass a listed code exactly, for example `P1401`; matching is exact and case-sensitive. Payins and payouts use different sets, so a payout code such as `S1401` is rejected here. An unrecognised code is rejected with `400 Bad Request`.
Optional on orders. When omitted, Glomo applies your account's default payin purpose code if one has been configured.
    Example: P1401

  - `invoice_number` (string)
    Number/Id of the invoice submitted with order. LRS orders (sent with `lrs`) don't store this field and return it as `null`, but a value you send is still validated.
    Example: RG12FF590

  - `invoice_description` (string)
    Description about the invoice submitted with order
    Example: Payment requested for services provided

  - `invoice_amount` (number)
    The amount on the invoice, in the smallest unit of the order's `currency`, the same unit as `amount` (cents for USD). `1000` is $10.00 when `currency` is USD. Must be greater than or equal to `amount`.
    Example: 1000

  - `reference_number` (string)
    optional identifier to be sent for reconciliations
    Example: R0001

  - `price_id` (string)
    The unique identifier of 'Price' entity linked to the order. This is the referral fee for this order. Note: price_id is only applicable for platform businesses.
    Example: price_E602dMzgjpDC

  - `split_ids` (array)
    The pricing splits to apply, each entry an `id` returned by [Create a pricing split](#tag/pricing_split). A split fixes your share of a dynamic rule's fee and the customer bears the remainder. Omit `split_ids` and no dynamic rule is applied — pricing falls back to your normal (non-dynamic) rules.
`split_ids` and `payment_methods` are independent. `payment_methods` restricts which methods the checkout offers. `split_ids` only changes how the fee for a method is priced: a split applies to its own payment method whether or not that method appears in `payment_methods`, and a split never adds a method to the checkout or removes one from it. One checkout can therefore price one method from a dynamic split and another method from your normal rules.
Every id must exist, must belong to your business, and must still point at a live dynamic rule. When two dynamic rules share a dimension — the same payment method, subtype, rail, currency and fee type — declare a split for every one of them or the request is rejected. On payment links and orders, a split whose payment method is not enabled for your business is also rejected.
A subscription only ever charges `card`, or `pay_via_bank` when SEPA-eligible, so a split declared for any other payment method is rejected at subscription creation and on an auto debit. An auto-debit override must be declared for the method the subscription actually charges.
Glomo can configure your account to require a declaration. On such an account, a payment link, an order, a payin quote or an `as_presented` subscription that omits `split_ids` is rejected.
    Example: ["psplit_7Kq2mXbTdLp9"]

  - `product` (object)
    Details of the product that the payment is related to.
    Example: {"name":"ShieldGuard Insurance","description":"Flexible insurance for belongings travel and digital assets easy to manage"}

  - `product.name` (string, required)
    Name of the product

  - `product.description` (string)
    Description of the product

  - `notes` (object | null)
    Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. Your account may require some `notes` fields: Glomo configures custom field rules per account, and for beneficiaries they are checked when the beneficiary is created. Some fields are also validated by the beneficiary's country (for example, a PAN format for Indian beneficiaries). A missing required field returns `422` with `Validation failed: Notes <field> is required`, and type and validation errors (such as enum constraints) are returned the same way. The rule is set on your account, not by currency or rail. No API lists the fields, but the `422` names each missing one: add that key to `notes` with the value your account expects, and ask your Glomo account manager if you don't know what the field should hold. See [Custom fields](/payin/custom-fields). Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
    Example: {"invoice_ref":"INV-2026-001","project":"Alpha"}

  - `bank_account_details` (object)
    Bank account details associated with the customer for this order. If provided in the request, all fields will be returned. If bic_primary or bic_secondary was not provided in the request, they will be null in the response.
    Example: {"account_number":"1234567890","bic_primary":"HDFCINBBDEL","bic_secondary":null,"bank_customer_id":"7189204715"}

  - `bank_account_details.account_number` (string)
    The bank account number
    Example: 1234567890

  - `bank_account_details.bic_primary` (string | null)
    SWIFT code for the bank account. Will be null if not provided in the request.
    Example: HDFCINBBDEL

  - `bank_account_details.bic_secondary` (string | null)
    Local routing code for the bank account like IFSC. Will be null if not provided in the request.
    Example: HDFC0001097

  - `bank_account_details.bank_customer_id` (string | null)
    Bank customer identifier provided by the bank. Will be null if not provided in the request.
    Example: 7189204715

  - `lrs` (object)
    Send this object to create an LRS order: a remittance from a customer resident in India, funded
from their Indian bank account. If you send `lrs`, `lrs_quote_id` and `remittance_information` are
required.
- Create the quote first with `POST /lrs/quotes`. The order's `amount` must equal the `USD` side of
the quote (`from.amount` for a `USD` source quote, `to.amount` for an `INR` source quote), and
`currency` must be `USD`. Otherwise the order is rejected with `400`.
- The quote must not have expired. The order expires when the quote does.
- The customer's country must be India, otherwise the order is rejected with `400`.
- An LRS order doesn't store `invoice_number`, `invoice_description`, `invoice_amount`,
`reference_number`, `document_id` or `product`; they come back as `null` or are left out. A value
you send is still validated, so leave these fields out.

Returned on the order when it was created as an LRS order.

  - `lrs.lrs_quote_id` (string, required)
    The `id` of a quote from `POST /lrs/quotes`, created by your account.
    Example: quote_6ab60de4Kx7Pq

  - `lrs.remittance_information` (string, required)
    Your reference for the remittance. Up to 20 characters, using only letters, digits and hyphens; spaces and other characters are rejected with `400`.
    Example: REF12345

  - `lrs.bank_account_id` (string)
    The `id` of the customer's LRS bank account, from `POST /customer/{id}/bank_account`. Optional. It must belong to this customer and be at the same bank as the quote's `bank_code`. A bank account from `POST /customer/{id}/bank-accounts` is not accepted here.
    Example: acclrs_68468c03g9xt7

  - `lrs.beneficiary_id` (string)
    The `id` of a beneficiary created with `category: lrs` through `POST /v2/beneficiaries`, to receive the remittance. Optional.
    Example: bene_68468c03g9xua

  - `payment_methods` (array)
    Array of payment methods that should be available for the customer on the checkout page. This field allows you to control which payment options your customers can use to complete the payment. You can specify one or multiple payment methods in the array.
    Example: ["card"]

  - `created_at` (string)
    When the order was created, as an ISO 8601 date-time in UTC.
    Example: 2021-06-01T12:00:00Z

  - `updated_at` (string)
    When the order was last updated, as an ISO 8601 date-time in UTC.
    Example: 2021-06-01T12:00:00Z

  - `request_id` (string | null)
    Your unique identifier for this order, used to reject duplicates. If an order with the same `request_id` already exists on your account, the request is rejected with `400` and the message `Order already exists for this request_id`; the existing order is not returned. Look it up with `GET /v1/orders?request_id=<your_request_id>`. Returned on the order and its webhooks; `null` if you sent none.
    Example: unique_order_request_id_123

  - `rfi_documents` (array)
    List of required documents for RFI (Request for Information). This field is only present when the order status is 'action_required', indicating that sanction screening has been triggered and additional documents are required to proceed with the payment.
    Example: [{"rfi_doc_id":"rfidoc_123","name":"Passport"},{"rfi_doc_id":"rfidoc_456","name":"Proof of Address"}]

  - `rfi_documents.rfi_doc_id` (string, required)
    Unique identifier for the required RFI document
    Example: rfidoc_123

  - `rfi_documents.name` (string, required)
    Name/type of the required document
    Example: Passport

  - `expires_at` (string)
    When the order expires, as an ISO 8601 date-time in UTC. An order created from a quote inherits the quote's expiry.
    Example: 2026-09-24T22:15:18Z

## Response 400:

  - `400` (unknown)
    Bad Request — validation error. For quote-based orders, possible messages include `quote_id not found`, `quote_id is not a payin quote`, `quote_id has expired`, `quote_id has already been used`, and `amount cannot be specified when quote_id is present` (likewise for any other locked field: `currency`, `price_id`, `payment_methods`, `split_ids`).
For `split_ids`, every id must resolve to a live dynamic rule declared by your business, every dynamic rule on the same dimension must be declared, and every declared payment method must be enabled for your business.

## Response 400 fields (application/json):

  - `error` (string)
    Enum: "Bad Request"

  - `message` (string)
    Error message.
    Example: Currency not supported

## Response 422:

  - `422` (unknown)
    Unprocessable Entity - the request was well formed but the order was declined. Returned for account funding orders, which carry a machine-readable `code` beside the message.
`order_cap_unavailable` and `payment_method_unavailable` share the same customer-safe message, so branch on `code`, never on `message`. The cap applies to the **destination** currency - the amount credited, not the amount charged to the card.

## Response 422 fields (application/json):

  - `error` (string)
    Enum: "Unprocessable Entity"

  - `message` (string)
    A customer-safe description of the decline.
    Example: The order amount is above the limit for this programme

  - `code` (string)
    Why the order was declined.
- `quote_not_found` - no quote with that id.
- `quote_not_owned` - the quote belongs to another business.
- `quote_expired` - the quote lapsed. Create a new one.
- `quote_resource_type_missing` - the quote did not declare `account_funding`.
- `beneficiary_missing` - no `beneficiary_id` named, or it does not resolve.
- `order_amount_above_cap` - above the configured cap for that currency.
- `order_cap_unavailable` - no cap is configured for that currency. Not the same as
the amount being too large.
- `payment_method_unavailable` - your account has no active card payment method.
    Enum: "quote_not_found", "quote_not_owned", "quote_expired", "quote_resource_type_missing", "beneficiary_missing", "order_amount_above_cap", "order_cap_unavailable", "payment_method_unavailable"

## Response 400 examples:

  - `Currency not supported` (unknown)

  - `Duplicate request_id` (unknown)

  - `quote_id not found` (unknown)

  - `quote_id is not a payin quote` (unknown)

  - `quote_id has expired` (unknown)

  - `quote_id has already been used` (unknown)

  - `Locked field sent with quote_id` (unknown)

  - `split_ids sent with quote_id` (unknown)

  - `A split id does not resolve to a live dynamic rule` (unknown)

  - `Another dynamic rule on the same dimension is not declared` (unknown)

  - `A declared payment method is not enabled for your business` (unknown)

  - `split_ids omitted on an account where a declaration is required` (unknown)

## Response 422 examples:

  - `Above the configured cap` (unknown)

  - `No cap configured for the destination currency` (unknown)

  - `beneficiary_id missing or unresolvable` (unknown)

  - `The quote was not created for account funding` (unknown)