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

# Async

> Making your first API order in asynchronous mode

## The URL

As we are using the playground, the base URL is `https://playground.runa.io/v2`, we will be making a call to the `POST /order` endpoint. The full path therefore is `https://playground.runa.io/v2/order`.

## What headers do I need to send?

To successfully place an order, you need to include the following headers in your API request:

<ParamField header="X-Api-Key" type="string" required>
  The API key you created in the previous step.
</ParamField>

<ParamField header="X-Idempotency-Key" type="string" required>
  A unique value that we use to prevent duplicate purchases. If a network error
  occurs, you can retry the request with the same idempotency key and we will
  return the original order without any danger of creating a new one. You can
  read more about how we handle this field in the [idempotency
  guide](/best-practices/idempotency).

  For testing you can just make one up, but you **must** generate a unique value for each order you intend to make. We suggest using a V4 UUID for this field.
</ParamField>

<ParamField header="X-Api-Version" type="string">
  The API version you want to use. This header is optional but we highly
  recommend you to set it. For this guide, we will use the latest version
  `2024-02-05`
</ParamField>

<ParamField header="X-Execution-Mode" type="string" default="async">
  Set the value of this header to `async` as we are using the synchronous
  execution mode for this guide. If omitted, the default value is `async` but we
  still recommend you set it for explicitness.
</ParamField>

Putting this all together the full headers we need to send are:

```http theme={null}
X-Api-Key: <your-api-key>
X-Idempotency-Key: <your-idempotency-key>
X-Api-Version: 2024-02-05
X-Execution-Mode: async
```

## The request body

The request body is a JSON object that defines the order we are about to place. We need to define the **payment method** and the **items we want to order**, and how we want to **distribute** the payout link to the end users.

Here's the outline of the request body we will be constructing, read on to see how to fill in the details.

```json [expandable] theme={null}
{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "USD"
  },
  "items": [
    {
      "face_value": 10,
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    },
    {
      "face_value": 20,
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    }
  ]
}
```

### The payment method

The payment method is the balance you want to use to pay for the order. For simplicity we will match the currency of the payout link we are about to order. The following fields are set on the `payment_method` object:

<Columns cols={2}>
  <div>
    <ParamField body="type" children="payment_method" type="string" required>
      Set the payment method type as `ACCOUNT_BALANCE`
    </ParamField>

    <ParamField body="currency" type="string" required>
      For this example, we will use the currency `USD`
    </ParamField>
  </div>

  <div>
    ```json theme={null}
    "payment_method": {
      "type": "ACCOUNT_BALANCE",
      "currency": "USD"
    }
    ```
  </div>
</Columns>

### The order items

As we are using the asynchronous execution mode, we can order multiple payout links at a time. You can order up to 200 items in a single order. If you need to order more than 200 items, you can create multiple orders.

The following fields are set on the items within the `items` array:

<Columns cols={2}>
  <div>
    <ParamField body="face_value" type="number" required>
      Indicate the face value of the payout link you wish to order. The currency will be based on the selected product. As the product is in USD this will be \$10.
    </ParamField>

    <ParamField body="distribution_method" type="object" required>
      We have a choice here between `EMAIL` and `PAYOUT_LINK`. Read on to see how to
      set these fields.
    </ParamField>

    <ParamField body="products" type="object" required>
      We have a choice here between `SINGLE` and `MULTIPLE` and `TEMPLATE`. Read on to see how to set these fields.
    </ParamField>
  </div>

  <div>
    ```json theme={null}
    {
      "face_value": 10,
      "distribution_method": {
        ...
      },
      "products": {
        ...
      }
    }
    ```
  </div>
</Columns>

#### The distribution method

As mentioned we have two options here, `EMAIL` and `PAYOUT_LINK`.

* `EMAIL`: This will send the payout link directly to the end user's email inbox.
* `PAYOUT_LINK`: This will return the payout link in the response body.
* `RECIPIENT`: This is used for payment type products, we won't be using this in this guide.

##### To distribute via `EMAIL`

<Columns cols={2}>
  <div>
    <ParamField body="type" children="distribution_method" type="string" required>
      Set the distribution method type as `EMAIL`
    </ParamField>

    <ParamField body="email_address" children="distribution_method" type="string" required>
      Set the email address you want to send this payout link to.
    </ParamField>
  </div>

  <div>
    ```json theme={null}
    "distribution_method": {
      "type": "EMAIL",
      "email_address": "recipient@example.com"
    }
    ```
  </div>
</Columns>

<Info>
  The playground environment by default does not send emails. To enable this, you need to set the `X-Send-Email: true` header.

  Ensure you refer to the [playground reference](/reference/2024-02-05/playground#sending-emails) for more details.
</Info>

##### To distribute via `PAYOUT_LINK`

<Columns cols={2}>
  <div>
    <ParamField body="type" children="distribution_method" type="string" required>
      Set the distribution method type as `PAYOUT_LINK`
    </ParamField>
  </div>

  <div>
    ```json theme={null}
    "distribution_method": {
      "type": "PAYOUT_LINK"
    }
    ```
  </div>
</Columns>

#### The product selection

There are three options here, `SINGLE`, `MULTIPLE` and `TEMPLATE`.

* `SINGLE`: This will create a payout link for the selected product, the end user will receive a link for the chosen value exactly.
* `MULTIPLE`: This will create payout link where the end user can choose to split the value between multiple products.
* `TEMPLATE`: This will create a payout link as defined by a [pre-built template](/features/merchant-selection-template).

As we've not pulled the [product catalog](/features/product-catalog) we'll use `TEMPLATE` for this example. In the playground environment we have a [pre-defined template](/reference/2024-02-05/playground#default-product-selection-templates) we can use for USD that will give us a payout link with 10 randomized products.

On the `products` object we will set the `type` to `TEMPLATE` and the `template_id` to `PT-01HQ12PV4B8XMBRTK281JM54KK`. The `template_id` is the ID of the template we want to use.

<ParamField body="type" children="products" type="string" required>
  Set the product selection type to `TEMPLATE`
</ParamField>

<ParamField body="template_id" children="products" type="string" required>
  Set the template ID to `PT-01HQ12PV4B8XMBRTK281JM54KK`, a [pre-defined
  playground
  template](/reference/2024-02-05/playground#default-product-selection-templates)
  for USD.
</ParamField>

## Putting it all together

### The request

Here's the complete request we'll be sending to the API.

```http The Request Headers theme={null}
POST https://playground.runa.io/v2/order
X-Api-Key: <your-api-key>
X-Idempotency-Key: <your-idempotency-key>
X-Api-Version: 2024-02-05
X-Execution-Mode: sync
Content-Type: application/json
```

```json The Request Body theme={null}
{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "USD"
  },
  "items": [
    {
      "face_value": 10,
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    },
    {
      "face_value": 20,
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    }
  ]
}
```

### The initial response

For async orders the response to the request will only contain the order ID and the status of the order. This is because the order is processing in the background.

```json The Intermediate Response theme={null}
{
  "id": "O-01234567890ABCDEFGHIJK",
  "status": "PROCESSING"
}
```

You should take note of the order ID as you will need it to fetch the order details later.

### Getting the order details

If you wait a short period and then fetch the order details using the [get order details](/reference/2024-02-05/endpoint/orders/get) endpoint you're able to fetch the same details available when using the synchronous ordering mode.

<Info>
  The order status will be `PROCESSING` for a short period of time after it is
  accepted. On the playground environment this is simulated by a 1 second delay.
</Info>

The URL to fetch the order details is:

```
https://playground.runa.io/v2/order/{order-id}
```

The response will be a `200 OK` with the order details in the body. You can retrieve the payout links from the `payout.url` fields from the `items` array.

```json The Response {25,42} theme={null}
{
  "id": "O-01234567890ABCDEFGHIJK",
  "status": "COMPLETED",
  "created_at": "2025-01-01T12:00:00+00:00",
  "completed_at": "2025-01-01T12:00:01+00:00",
  "description": null,
  "payment_method": {
    "type": "ACCOUNT_BALANCE"
  },
  "currency": "USD",
  "items": [
    {
      "id": "E-01234567890ABCDEFGHIJK",
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK",
        "values": [ ... ]
      },
      "face_value": "10.00",
      "price": "10.00",
      "payout": {
        "status": "ACTIVE",
        "status_updated_at": "2025-01-01T12:00:01+00:00",
        "url": "https://spend.playground.runa.io/01234567-0000-4000-abcd-012345678900",
      },
      "currency": "USD"
    },
    {
      "id": "E-11234567890ABCDEFGHIJK",
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK",
        "values": [ ... ]
      },
      "face_value": "20.00",
      "price": "20.00",
      "payout": {
        "status": "ACTIVE",
        "status_updated_at": "2025-01-01T12:00:01+00:00",
        "url": "https://spend.playground.runa.io/11234567-0000-4000-abcd-012345678900",
      },
      "currency": "USD"
    }
  ],
}
```

Pop the `url` field into your browser to see the payout link. Congratulations, you've just made your first order with Runa.

### Webhooks

While you can fetch the order details after a short delay, in reality this would require you to poll the endpoint until the order is completed. This is not ideal and may lead to rate limiting issues. Instead we have the [order completion webhook](/reference/2024-02-05/webhook/order.completion) available for you to use.

If you intend to use the async ordering mode you should take a look at the [webhooks](/reference/webhooks) section to see how to set one up. Unfortunately the playground environment does not support webhooks so you will need to use a real environment to test this out.

<Card title="Webhooks" horizontal icon="webhook" href="/reference/webhooks" arrow>
  Get real-time updates for the product catalog and your orders.
</Card>

## Next steps

You can now explore the following features to take your first order to the next level.

<Columns cols={3}>
  <Card title="Fetch the product catalog" href="/features/product-catalog" icon="grid" arrow>
    To make orders for specific products you'll need to fetch the product
    catalog first.
  </Card>

  <Card title="Customizing the payout link" href="/features/user-redemption-templates" icon="gift" arrow>
    Add your own branding and customize the redemption experience for your
    recipients.
  </Card>

  <Card title="Pay using a different currency" href="/features/embedded-fx" icon="money-bill-transfer" arrow>
    Use Runa Embedded FX to pay for an order using your funds in another
    currency
  </Card>
</Columns>

Alternatively, you can explore the steps needed to make real orders in the production environment.

<Card title="Moving to production" href="/getting-started/production" icon="hexagon-check" horizontal arrow>
  Once you're ready to go live have a look at the production checklist.
</Card>