> ## Documentation Index > Fetch the complete documentation index at: https://developer.runa.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a new order > Creates a new order, supports both sync and async execution modes We have a guide to help you get started with your first order including which execution mode to use. ## OpenAPI ````yaml reference/2024-02-05/openapi.json POST /order openapi: 3.1.1 info: title: Runa version: '2.0' description: The public Runa API license: name: Ⓒ Runa url: https://runa.io/terms-of-use contact: name: Runa url: https://runa.io email: info@runa.io servers: - url: https://playground.runa.io/v2 description: Playground - url: https://api.runa.io/v2 description: Production security: - ApiKeyAuth: [] tags: - name: utility description: Utility endpoints. - name: balance description: Operations related to account balance. - name: products description: Operations related to products. - name: orders description: Operations related to ordering and orders. externalDocs: url: https://developer.runa.com/reference description: Runa API Reference paths: /order: post: tags: - orders summary: Create a new order. description: Creates a new order. operationId: createOrder parameters: - $ref: '#/components/parameters/X-Api-Version' - required: true name: X-Idempotency-Key schema: type: string in: header description: >- A unique string that prevents order duplication. See [Idempotency](/best-practices/idempotency) for more information. - name: X-Execution-Mode schema: type: string enum: - async - sync default: async in: header description: >- Whether to process the order synchronously or asynchronously. If this header is omitted we default to async. See [which mode to use](/getting-started/first-order/which-mode) to help you decide which execution mode is right for your use case. Sync orders are limited to a single order item. example: async requestBody: required: true description: The details of the order to create. content: application/json: schema: $ref: '#/components/schemas/NewOrderDetails' responses: '200': description: >- Response that will be returned in sync execution mode. Order has successfully been completed. content: application/json: schema: $ref: '#/components/schemas/SyncCompletedOrder' '202': description: >- Response that will be returned in async execution mode. Order has successfully been accepted. content: application/json: schema: $ref: '#/components/schemas/AsyncAcceptedOrder' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateExceeded' '500': $ref: '#/components/responses/InternalServerError' components: parameters: X-Api-Version: name: X-Api-Version description: >- The dated version of the API, if not specified a default is used. See [API versioning](/best-practices/api-versioning) for more information. in: header required: false schema: type: string schemas: NewOrderDetails: title: NewOrderDetails required: - payment_method - items type: object properties: payment_method: title: Payment Method description: >- Payment method for the order. Select the `ACCOUNT_BALANCE` you want to pay for the order from allOf: - $ref: '#/components/schemas/NewAccountPayment' items: title: Items description: >- The list of items to be included in the order. Each item ordered results in a single payout link. The maximum number of items per order is 200. minItems: 1 maxItems: 200 type: array items: $ref: '#/components/schemas/NewOrderItemDetails' description: $ref: '#/components/schemas/OrderDescription' metadata: $ref: '#/components/schemas/OrderMetadata' SyncCompletedOrder: title: CompletedOrderWithFullDetails allOf: - $ref: '#/components/schemas/CompletedOrderWithFullDetails' - properties: status: enum: - COMPLETED AsyncAcceptedOrder: title: Async Order Accepted required: - id - status type: object properties: id: $ref: '#/components/schemas/OrderId' status: $ref: '#/components/schemas/OrderStatus' NewAccountPayment: title: NewAccountPayment required: - type - currency type: object properties: type: description: Account balance payment method. allOf: - $ref: '#/components/schemas/AccountPaymentType' currency: $ref: '#/components/schemas/CurrencyForAccount' description: Pay using your account balance. NewOrderItemDetails: title: NewOrderItemDetails required: - face_value - distribution_method - products type: object properties: face_value: title: Face Value description: >- Face value of the payout link. The currency of the face value is inferred from the product selection. What value is allowed depends on the product mode: - When ordering a `SINGLE` product this field follows the allowed values from the selected product. - If using `MULTIPLE` or `TEMPLATE` this value must be: equal or greater than the minimum face value of the products selected and be a whole number. minimum: 0.01 example: 10 type: number distribution_method: title: Distribution Method description: >- Distribution method to send end users the payout link. Choose `EMAIL` if you want Runa to send the payout link to the end user directly. Choose `PAYOUT_LINK` if you want to send the payout link to the end user yourself. oneOf: - $ref: '#/components/schemas/EmailDistribution' - $ref: '#/components/schemas/LinkDistribution' - $ref: '#/components/schemas/RecipientDistribution' products: title: Products description: >- Choose `SINGLE` if you want the end user to redeem the face value on a single specific product. Choose `MULTIPLE` if the end user can choose to spend the face value across multiple products. oneOf: - $ref: '#/components/schemas/SingleProductWithUsageConfig' - $ref: '#/components/schemas/MultipleProduct' - $ref: '#/components/schemas/PayoutSelectionTemplate' OrderDescription: title: Description description: >- Free format text reference for the order. The order description will not be visible to the end user. You will see this description in the Runa web portal. This field is optional and can be omitted if not needed. If not provided, the field will be set to `null` in the response. type: string nullable: true maxLength: 128 example: Your own reference text OrderMetadata: title: Metadata description: >- A flexible field for you to attach additional, customer-specific data to the order. This is for your internal use, the information stored here will not be exposed to the end user. - All keys and their corresponding values must be strings - Each order supports up to 20 key-value pairs - Keys have a maximum length of 40 characters - Values can be up to 200 characters long. This field is optional and can be omitted if not needed. If not provided, the field will be set to `null` in the response. type: object nullable: true maxProperties: 20 propertyNames: type: string maxLength: 40 additionalProperties: type: string maxLength: 200 example: internal_id: '12345' department: marketing campaign: summer_2024 CompletedOrderWithFullDetails: title: Completed order description: >- Used for an order that has completed. This class is typically used when returning a *single order* to the client. type: object allOf: - $ref: '#/components/schemas/CompletedOrderWithBasicDetails' - required: - id - status - created_at - payment_method - currency - total_price - total_discount - items properties: items: title: Items description: >- The list of items that were included in the order. Each _item_ represents a single payout link. type: array items: $ref: '#/components/schemas/CompletedOrderItem' transaction_detail: $ref: '#/components/schemas/TransactionDetail' metadata: $ref: '#/components/schemas/OrderMetadata' OrderId: title: Order ID description: The ID of the order. type: string example: O-01H5WQGHKCBB85MQFM68S9KJ5Q OrderStatus: title: Order Status description: Status of the order. allOf: - $ref: '#/components/schemas/OrderStatusEnum' example: PROCESSING APIErrorResponse: title: APIErrorResponse required: - type - message type: object properties: type: title: Type description: An error code or type. type: string example: not-found message: title: Message description: A human readable summary of the error. type: string example: The requested resource was not found help: title: Help description: Additional information that pertains to the error. type: string example: Please check the resource ID and try again. description: Generic Runa API error response. ValidationErrorResponse: title: ValidationErrorResponse required: - type - message - details type: object properties: type: title: Type description: An error code or type. type: string example: validation_error message: title: Message description: A human readable summary of the error. type: string example: >- There were one or more problems processing your request, see details key. help: title: Help description: Additional information that pertains to the error. type: string example: null details: title: Details description: Additional details regarding the error. type: array items: $ref: '#/components/schemas/ValidationErrorItem' description: >- A validation error response. Returned when the request failed validation. This response can contain multiple validation errors, see the details key for each. RateExceededResponse: title: RateExceededResponse required: - error type: object properties: error: title: Error description: A human readable error message describing the error. type: string example: rate exceeded description: API rate limited error response. AccountPaymentType: title: AccountPaymentType type: string enum: - ACCOUNT_BALANCE description: Account balance payment. CurrencyForAccount: type: string pattern: ^[A-Z]{3}$ description: >- The currency of the account, represented by ISO 4217 currency codes. Check the [currencies](/reference/currencies) for a listing of supported currencies. example: USD EmailDistribution: title: Email required: - type - email_address type: object properties: type: $ref: '#/components/schemas/EmailDistributionType' email_address: $ref: '#/components/schemas/DistributionEmailAddress' template_id: $ref: '#/components/schemas/RedemptionTemplateId' description: >- Email distribution. Send the payout link to the end user directly via email. LinkDistribution: title: Link required: - type type: object properties: type: $ref: '#/components/schemas/LinkDistributionType' template_id: $ref: '#/components/schemas/RedemptionTemplateId' description: Link distribution. Send the payout link to the end user yourself. RecipientDistribution: title: Recipient description: >- Recipient distribution. Currently this method is only supported for distributing payment type products. For subsequent orders to known recipients we will attempt to make a repeat payout. summary: Send the payout link to a known recipient required: - type - recipient_reference - email_address type: object properties: type: $ref: '#/components/schemas/RecipientDistributionType' recipient_reference: title: Recipient Reference description: >- A customer provided reference to identify an individual recipient. It must be unique per recipient. When the same reference is used for a second order this will trigger a repeat payout. This is a free-form string limited to 255 characters. It can only contain alphanumeric characters, dashes, underscores, dots, and at-signs. example: abc123 type: string maxLength: 255 pattern: ^[A-Za-z0-9-_@.]+$ email_address: $ref: '#/components/schemas/DistributionEmailAddress' template_id: $ref: '#/components/schemas/RedemptionTemplateId' SingleProductWithUsageConfig: title: Single required: - type - value type: object example: type: SINGLE value: AMZ-US properties: type: $ref: '#/components/schemas/SingleProductType' value: title: Value description: >- The code for the product the end user will get when redeeming their payout link. minLength: 1 example: AMZ-US type: string usage_config: description: >- Optional. **Only applicable to prepaid Visa cards.** Attaches an MCC-rules template to the issued card. Ignored for all other products. See [Card spend controls](/features/prepaid-visa/spend-controls) for a worked example. When set on a prepaid Visa card order, it is returned in the order details. allOf: - $ref: '#/components/schemas/UsageConfig' description: >- Single product. The end user will be able to redeem the payout link for this specific product. MultipleProduct: title: Multiple required: - type - values type: object properties: type: $ref: '#/components/schemas/MultipleProductType' values: title: Values description: >- The codes for the products the end user can choose from when redeeming their payout link. All products _must_ use the same currency. example: - AMZ-US - AIRBNB-US minItems: 2 type: array items: type: string uniqueItems: true description: >- Multiple products. The end user will be able to split the payout link's value between these products. PayoutSelectionTemplate: title: Template required: - type - template_id type: object properties: type: $ref: '#/components/schemas/PayoutSelectionTemplateType' template_id: $ref: '#/components/schemas/PayoutSelectionTemplateId' description: Payout selection template. Template having predefined set of products. CompletedOrderWithBasicDetails: title: Completed order description: >- Used for orders that have completed. This class is typically used when returning a *list* of orders to the client. required: - id - status - created_at - payment_method - currency - total_price - total_discount type: object properties: id: $ref: '#/components/schemas/OrderId' status: $ref: '#/components/schemas/OrderStatus' created_at: title: Created At description: UTC timestamp, in ISO 8601 format, when the order was submitted. type: string format: date-time completed_at: title: Completed At description: UTC timestamp, in ISO 8601 format, when the order was completed. type: string format: date-time description: $ref: '#/components/schemas/OrderDescription' payment_method: title: Payment Method description: The payment method used for the order. allOf: - $ref: '#/components/schemas/AccountPayment' currency: title: Currency example: USD type: string pattern: ^[A-Z]{3}$ description: >- The currency of the order, represented by ISO 4217 currency codes. Please check the currency section in the guidelines for how to use this field. total_price: title: Total Price description: The total price of the order. This _includes_ any applicable fees. example: '10' type: string total_discount: title: Total Discount description: The total discount of the order. type: string example: '1' CompletedOrderItem: title: CompletedOrderItem type: object properties: id: title: ID description: The ID of the order item. example: E-NWPEKW4VL type: string distribution_method: title: Distribution Method description: The distribution method used for the payout link. oneOf: - $ref: '#/components/schemas/EmailDistribution' - $ref: '#/components/schemas/LinkDistribution' - $ref: '#/components/schemas/RecipientDistribution' products: title: Products description: The product(s) the end user can redeem the payout link on. oneOf: - $ref: '#/components/schemas/MultipleProduct' - $ref: '#/components/schemas/SingleProductWithUsageConfig' - $ref: '#/components/schemas/PayoutSelectionTemplateDetailed' - $ref: '#/components/schemas/UnknownProduct' face_value: title: Face Value description: The face value of the payout link. example: '10' type: string price: title: Price description: The price paid for the payout link. example: '10' type: string payout: title: Payout description: Payout link details allOf: - $ref: '#/components/schemas/PayoutDetails' currency: title: Currency description: >- The currency of the payout link, represented by ISO 4217 currency codes. type: string pattern: ^[A-Z]{3}$ example: USD required: - id - distribution_method - products - face_value - price - payout TransactionDetail: title: TransactionDetail description: >- A mapping of the subtotal of the order using the payout currency as a key. type: object example: USD: value: '10.00' fx: null additionalProperties: $ref: '#/components/schemas/TransactionDetailEntry' OrderStatusEnum: title: OrderStatusEnum type: string enum: - COMPLETED - FAILED - PROCESSING description: The status of the order. ValidationErrorItem: title: ValidationErrorItem required: - type - message - location type: object properties: type: title: Type description: The type of error encountered. type: string example: value_error.number.not_ge message: title: Message description: A human readable summary of the error. type: string example: ensure this value is greater than or equal to 1 location: title: Location description: The location of the error in the submitted entity. type: array items: type: string example: - items - '0' - face_value description: >- A single validation error. The type indicates the error type and the message provides a human readable summary of the error. The location provides a path to the key in the request body. EmailDistributionType: title: EmailDistributionType type: string enum: - EMAIL description: Supported email distribution types. DistributionEmailAddress: title: Email Address description: The email address of the end user to send the payout link to. example: fred@example.com type: string format: email RedemptionTemplateId: title: Template ID description: The template ID for a User Redemption Template. example: DT-01HPSF51G0ZWHJ3JTNWRH0WDYK type: string LinkDistributionType: title: LinkDistributionType type: string enum: - PAYOUT_LINK description: Supported link distribution types. RecipientDistributionType: title: RecipientDistributionType type: string enum: - RECIPIENT description: Supported recipient distribution types. SingleProductType: title: SingleProductType type: string enum: - SINGLE description: Single product. When only one product code is provided. UsageConfig: title: UsageConfig type: object description: >- Additional configuration applied to the issued product. Only applicable to prepaid Visa cards. properties: spend_rules_template_id: title: MCC rules template ID description: >- Identifier of a Runa-authored MCC-rules template applied to the issued card. Only applicable to prepaid Visa cards. A single template is applied per card, with multiple rules that either allows or blocks transactions for a given merchant category bundled inside that one template. type: string pattern: ^PSR-[0-9A-HJKMNP-TV-Z]{26}$ example: PSR-XXXXXXXXXXXXXXXXXXXXXXXXXX MultipleProductType: title: MultipleProductType type: string enum: - MULTIPLE description: Multiple products. When more than one product code is provided. PayoutSelectionTemplateType: title: PayoutSelectionTemplateType type: string enum: - TEMPLATE description: Payout Selection Template PayoutSelectionTemplateId: title: Template ID description: The template ID for a Payout Selection Template. example: PT-01HPSF51G0ZWHJ3JTNWRH0WDYK type: string AccountPayment: title: AccountPayment required: - type type: object properties: type: description: Account balance payment. allOf: - $ref: '#/components/schemas/AccountPaymentType' currency: $ref: '#/components/schemas/CurrencyForAccount' description: Account balance payment. PayoutSelectionTemplateDetailed: title: Template required: - type - template_id type: object properties: type: $ref: '#/components/schemas/PayoutSelectionTemplateType' template_id: $ref: '#/components/schemas/PayoutSelectionTemplateId' values: title: Values description: The codes for products selected for Payout Selection Template. example: - AMZ-US - AIRBNB-US minItems: 2 type: array items: type: string uniqueItems: true description: Payout selection template. Template having predefined set of products. UnknownProduct: title: Unknown type: object description: >- Product(s) unknown. It was not possible to determine which products were included in the order. required: - type properties: type: title: Type description: >- It is not currently possible to determine which products were selected when this item was ordered. default: UNKNOWN type: string enum: - UNKNOWN PayoutDetails: title: PayoutDetails type: object properties: status: $ref: '#/components/schemas/PayoutStatus' status_updated_at: title: Status Updated At description: Time that the payout link status was last updated type: string format: date-time url: title: Url description: The URL (payout link) the end user uses to redeem. type: string expiry_date: title: Expiry Date description: >- When the payout link expires. This is the expiry of the payout link itself, not the underlying gift card or product. If your account does not have expiry of links enabled this field will be set to `null`, the link does not expire. type: string format: date-time required: - status - status_updated_at - url TransactionDetailEntry: type: object title: TransactionDetailEntry description: >- A subtotal of the value purchased and associated fees and data about the transaction. properties: value: title: Value description: The total value purchased of a payout link currency. type: string example: '10.00' fx: $ref: '#/components/schemas/TransactionDetailFXDetails' required: - value PayoutStatus: title: Payout status description: >- Current status of the payout link. An `ACTIVE` link is live but has not been claimed yet, it will change to `CLAIMED` once that has happened. If you request a cancellation the status will reflect this as `CANCELLED`. Finally, if your account is configured with link expiry, when the link itself expires it will be marked as `EXPIRED` — this is independent of the underlying product's own expiry policy. enum: - ACTIVE - CLAIMED - CANCELLED - EXPIRED TransactionDetailFXDetails: type: object title: TransactionDetailFxDetails description: >- Provides details on fx conversion for an order transaction detail. Present when the payment method currency is different from the transaction detail currency. properties: rate: title: FX Rate description: >- The FX rate received for the transaction between the payout currency and payment currency. type: string example: '1.234' rate_symbol: title: FX Rate symbol description: The currency pair associated with the FX transaction. type: string example: GBPUSD fee: title: Fee description: The fee charged for making this transaction. type: object properties: value: title: Value description: The value of the fee. type: string example: '0.00' currency: title: Currency description: The currency of the fee. type: string example: USD required: - value - currency required: - rate - rate_symbol - fee responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' ValidationError: description: Request failed validation content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' RateExceeded: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/RateExceededResponse' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: >- Your API key. See the [API key](/getting-started/api-key) page on details of how to generate and store your keys. ````