# Create a Collection Order

{% hint style="info" %}
You need an API KEY to create collection orders. You can reach out to us via [discord](https://discord.ordinalsbot.com) to get one.

API KEYs are separate for testnet and mainnet.
{% endhint %}

{% hint style="warning" %}

* The /collectionorder endpoint has a rate limit of maximum 2 requests every 10 seconds.
* If pricing of the collection is in runes then `charge` will be null. Instead, `tokenPayCharge` will be available. User needs to send `tokenPayCharge.feeCharge.amount` of BTC to `tokenPayCharge.feeCharge.address` and `tokenPayCharge.tokenCharge.amount` of  tokens to `tokenPayCharge.tokenCharge.address`
  {% endhint %}

## Create Collection Order

<mark style="color:green;">`POST`</mark> `https://api.ordinalsbot.com/collectionorder`

#### Headers

| Name                                        | Type   | Description                                                     |
| ------------------------------------------- | ------ | --------------------------------------------------------------- |
| x-api-key<mark style="color:red;">\*</mark> | String | <p>API Key</p><p>Required if no turnstile token is present.</p> |

#### Request Body

| Name                                         | Type   | Description                                                                                                                                                                                                                                                                                                                                                         |         |       |          |       |         |                                                                                                                       |
| -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | -------- | ----- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| collection<mark style="color:red;">\*</mark> | Object | <p>Object including</p><p>id: Collection slug to be inscribed</p><p>count: number of inscriptions being ordered.</p>                                                                                                                                                                                                                                                |         |       |          |       |         |                                                                                                                       |
| receiveAddress                               | String | Bitcoin address to receive the inscriptions for the whole order                                                                                                                                                                                                                                                                                                     |         |       |          |       |         |                                                                                                                       |
| token<mark style="color:red;">\*</mark>      | String | <p>Cloudflare turnstile token</p><p>Required if no x-api-key header is present.</p>                                                                                                                                                                                                                                                                                 |         |       |          |       |         |                                                                                                                       |
| rareSats                                     | String | <p>One of following options: </p><p>block9                                                                                                                                                                                                                                                                                                                          | block78 | pizza | uncommon | black | vintage | random<br></p><p>Check <code>/inventory</code> endpoint for all available options and their current availability.</p> |
| fee<mark style="color:red;">\*</mark>        | Number | Mining fee to be paid for this collection inscription (sats/vB)                                                                                                                                                                                                                                                                                                     |         |       |          |       |         |                                                                                                                       |
| additionalFee                                | Number | <p>Amount of satoshis to charge extra for this order that will be added to "referral" account.</p><p>Needs to be used together with "referral" parameter.</p><p></p><p><mark style="color:red;"><strong>Note: additionalFee is added PER FILE!</strong></mark></p>                                                                                                  |         |       |          |       |         |                                                                                                                       |
| referral                                     | String | Referral code to earn up to %15 of the order service fee.                                                                                                                                                                                                                                                                                                           |         |       |          |       |         |                                                                                                                       |
| timeout                                      | Number | <p>Order timeout in minutes. Must be a multiple of 10. </p><p></p><p>Generated payment invoice will be valid for this duration only. Payments that are sent after this will not be processed.</p><p></p><p>Refrain from using too short timeout values and instead use <a data-mention href="#cancel-an-order">#cancel-an-order</a></p><p></p><p>(default=4320)</p> |         |       |          |       |         |                                                                                                                       |
| webhookUrl                                   | String | <p>webhook url to receive a POST payload for order updates</p><p></p><p>Refer to <a data-mention href="/pages/JTttvvY9TijDbZ3AzmDH">/pages/JTttvvY9TijDbZ3AzmDH</a> for format of the webhook payload</p>                                                                                                                                                           |         |       |          |       |         |                                                                                                                       |

{% tabs %}
{% tab title="200: OK " %}

<pre class="language-json"><code class="lang-json">{
    status: 'ok',
    ..., // input parameters
<strong>    charge: {
</strong>        ...
        "id": "815xxx-xxx-xxx-xxx79",
        "address": "3P...Vu",
        "amount": 1218725,
        "lightning_invoice": {
            "expires_at": 1675786558,
            "payreq": "lnbc1218...7qz9v"
        },
        "created_at": 1677176476,
    },
    paylink: {
        "id": "66xxx16", // visit https://app.hel.io/pay/66xxx16 to pay
    },
    chainFee: 718725 // in satoshis
    serviceFee: 100000, // in satoshis
    orderType: 'bulk',
    createdAt: 1675785959855, // timestamp in ms,
}
</code></pre>

{% endtab %}

{% tab title="500: Internal Server Error " %}

```
{
    status: 'error',
    error: 'error reason'
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ordinalsbot.com/api/create-a-collection-order.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.