---
title: "Create order"
method: POST
path: "/orders"
tags: ["Orders"]
---

# Create order

`POST /orders`

Creates a new escrow payment order.
`buyer_id` and `seller_id` are required (both customers must exist).
Once created, the order has a `buyer_link` and `seller_link` for the payment flow.

## Request body

- object
  - `buyer_id` integer — Customer ID of the buyer. Required unless `auto_settle` is `1` or `trustee_type` is `account`.
  - `seller_id` integer — Customer ID of the seller. Required unless `auto_settle` is `1`.
  - `trustee_type` 'account' — Pass `account` to use the authenticated account itself as the buyer (the `buyer_id` is then set automatically).
  - `name` string, required — Order description or product name.
  - `value` number, float, required — Order amount in the account's base currency.
  - `fee_value` number, float — Fixed platform fee amount. Cannot exceed `value`.
  - `fee_percent` number, float — Platform fee as a percentage. Min 0, max 100.
  - `tag` string — Custom reference tag.
  - `auto_settle` 0 | 1 — Set to `1` if there is no seller (e-commerce model). Auto-settles after payment.
  - `metadata` object — Arbitrary key-value metadata stored on the order.
  - `template` object — Custom template data for the checkout page.
    - `btn_submit_text` string — Custom text for the submit button.
    - `iframe_title` string — Title displayed in the payment iframe.
    - `expires_in` integer — Session expiration time in seconds.
    - `hide_cardholder` boolean — Whether to hide the cardholder name field. Default `false`.
    - `password_cvv` boolean — Whether to require CVV. Default `true`.
  - `images` string[] — Array of image URLs for the order.
  - `buyer_confirmed_url` string, uri — Redirect URL after buyer confirms payment.
  - `buyer_denied_url` string, uri — Redirect URL if buyer cancels payment.
  - `seller_confirmed_url` string, uri — Redirect URL after seller accepts the order.
  - `seller_denied_url` string, uri — Redirect URL if seller rejects the order.
  - `payin_intents` integer — Maximum number of payin attempts allowed.
  - `payin_method_types` string[] — Allowed payment method types for this order (e.g. `["CARD","BANKWIRE"]`).
  - `payin_method_fallback` string[] — Fallback payment methods if primary types fail.
  - `buyer_billing_id` integer — Address ID to use as the buyer's billing address.
  - `buyer_shipping_id` integer — Address ID to use as the buyer's shipping address.
  - `subscription_id` integer — Associate this order with an existing ACTIVE subscription. The subscription must belong to the `buyer_id` customer.
  - `discount_amount` number — Discount amount to apply to the order value.
  - `discount_coupon_id` integer — Coupon ID to apply as a discount.
  - `discount_wallet_id` integer — Wallet ID to fund a discount credit.
  - `bundle` integer — Bundle ID to associate with this order.

## Response `200`

Order created

- OrderResponse
  - `id` integer
  - `self` string
  - `public_id` string, nullable
  - `name` string
  - `description` string, nullable
  - `value` number — Order amount.
  - `fee_value` number, nullable
  - `fee_percent` number, nullable
  - `currency` string
  - `amount` string — Formatted amount with currency symbol.
  - `payin_amount` string, nullable
  - `payout_amount` string, nullable
  - `fee_amount` string, nullable
  - `shipping_amount` string, nullable
  - `buyer_link` string, uri — Payment URL to share with the buyer.
  - `seller_link` string, uri — Acceptance URL to share with the seller.
  - `qr_link` string, uri — QR code image URL for the order.
  - `status` 'DRAFT' | 'PENDING_DETAILS' | 'PENDING_PUBLISH' | 'PUBLISHED' | 'ACCEPTED' | 'REJECTED' | 'CANCELLED' | 'RELEASED'
  - `sandbox` boolean
  - `status_nicename` string — Human-readable status label.
  - `images` string[]
  - `tag` string, nullable
  - `payin_intents` integer, nullable
  - `payin_types` string[], nullable
  - `payin_fallback` string[], nullable
  - `metadata` object, nullable
  - `template` object, nullable
  - `published_units` integer, nullable
  - `refund` object
    - `status` string, nullable
    - `reference_id` string, nullable
  - `created_at` string, date-time, nullable
  - `published_at` string, date-time, nullable — When the order was paid.
  - `accepted_at` string, date-time, nullable
  - `shipping_at` string, date-time, nullable
  - `cancelled_at` string, date-time, nullable
  - `validated_at` string, date-time, nullable
  - `released_at` string, date-time, nullable
  - `connections` Connections — Hypermedia links to related resources.

## Other responses

- `422` — Validation error

## Changes

- **2026-03-24** `33c8b5a6215c` — 7 info
  - added the new optional request property `discount_amount`
  - added the new optional request property `discount_coupon_id`
  - added the new optional request property `discount_wallet_id`
  - added the new optional request property `subscription_id`
  - …3 more
- **2026-03-11** `ff825f6602c8` — 4 breaking, 8 info
  - request property `auto_settle` was restricted to a list of enum values
  - the request property `buyer_id` became required
  - the request property `seller_id` became required
  - the `auto_settle` request property type/format changed from `boolean`/`` to `integer`/``
  - …8 more

[Change history](https://skmtc.dev/truust-io/apis/truust-api/changes/orders/post.md)

---

[API](https://skmtc.dev/truust-io/apis/truust-api.md) · [All operations](https://skmtc.dev/truust-io/apis/truust-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/truust-io/truust-api/revisions/cc81e28726b9/schema)