# 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="webhooks">webhooks</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 %}