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

# Create order

`POST /orders`

Creates a new escrow payment order. An order requires a buyer (`buyer_id`), optional seller (`seller_id`),
a `name`, and a `value`. Once created, the order has a `buyer_link` and `seller_link` for the payment flow.

## Request body

- object
  - `name` string, required — Order description or product name.
  - `value` number, float, required — Order amount in the account's base currency.
  - `buyer_id` integer — Customer ID of the buyer. Required unless `trustee_type` is `account`.
  - `seller_id` integer — Customer ID of the seller. Required unless `auto_settle` is true.
  - `fee_value` number, float — Fixed platform fee amount. Cannot exceed `value`.
  - `fee_percent` number, float — Platform fee as a percentage.
  - `tag` string — Custom reference tag.
  - `metadata` object — Arbitrary key-value metadata stored on the order.
  - `template` object — Custom template data for the checkout page.
  - `images` string[] — Array of image URLs for the order.
  - `auto_settle` boolean — If true, the order is automatically settled after payment without seller confirmation.
  - `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.

## 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

---

[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/7266c24b4325/schema)