---
title: "Assign licence keys to an order"
description: "Place a licence key on this order by hand, as the order page's Assign key does: asset_id names the licence-key file, key a specific unassigned key, tag the pool to draw from (default: the file's own pool, as at checkout:"
url: https://docs.filemonk.io/v2/api-reference/orders/assign-licence-keys-to-an-order/
api: "API v2 reference"
method: POST
path: "/orders/{id}/licences/assign"
---

# Assign licence keys to an order

`POST https://app.filemonk.io/api/v2/external/orders/{id}/licences/assign`

Place a licence key on this order by hand, as the order page's Assign key does: asset_id names the licence-key file, key a specific unassigned key, tag the pool to draw from (default: the file's own pool, as at checkout: its licence tag, or untagged keys when the file has no tag). send_email true emails the buyer afterwards.

**Note:** Autogenerated-key files mint a new key. 422 when the key is taken or the pool is empty. send_email charges usage and fulfils in Shopify like any send.

## Path parameters

- `id` (string, required)

## Request body

- `asset_id` (string, required): e.g. `e2b7727e-45ad-42b7-b842-cc4615205b10`
- `key` (any)
- `tag` (string): e.g. `ebook-2026`
- `send_email` (boolean): e.g. `true`

## Returns

- `id` (string, nullable, required): e.g. `3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f`
- `shopify_order_id` (string, nullable, required): e.g. `gid://shopify/Order/7555375595815`
- `name` (string, nullable, required): e.g. `#1077`
- `confirmation_number` (string, nullable, required): e.g. `H5CZG3GZX`
- `ordered_at` (string, nullable, required): e.g. `2026-10-26T14:19:15Z`
- `customer` (object, required)
  - `id` (string, nullable, required): e.g. `b797db3a-cbc3-4643-804f-adf34c7f08d7`
  - `shopify_customer_id` (string, nullable, required): e.g. `gid://shopify/Customer/9026290417959`
  - `email` (string, nullable, required): e.g. `shopper@example.com`
  - `phone` (any, required)
  - `first_name` (string, nullable, required): e.g. `Jane`
  - `last_name` (string, nullable, required): e.g. `Doe`
  - `country_code` (any, required)
  - `locale` (any, required)
  - `unsubscribed` (boolean, nullable, required): e.g. `false`
- `total` (object, required)
  - `amount` (string, nullable, required): e.g. `1142.89`
  - `currency` (string, nullable, required): e.g. `INR`
- `status` (object, required)
  - `financial` (string, nullable, required): e.g. `paid`
  - `fulfillment` (string, nullable, required): e.g. `unfulfilled`
  - `cancelled_at` (any, required)
  - `paid_at` (string, nullable, required): e.g. `2026-10-30T21:48:16Z`
  - `flagged_as_fraud` (boolean, nullable, required): e.g. `false`
  - `fraud_check_completed` (boolean, nullable, required): e.g. `false`
  - `marked_fulfilled_at` (any, required)
  - `delivery_conditions_met` (boolean, nullable, required): e.g. `false`
- `access` (object, required)
  - `state` (string, nullable, required): e.g. `active`
  - `revoked_at` (any, required)
  - `available_until` (any, required)
  - `download_reset_at` (string, nullable, required): e.g. `2026-10-30T22:19:10Z`
  - `downloads_count` (integer, nullable, required): e.g. `0`
- `delivery` (object, required)
  - `email_sent_at` (string, nullable, required): e.g. `2026-10-30T22:34:30Z`
  - `delivery_failed_at` (any, required)
  - `download_page_url` (string, nullable, required): e.g. `https://example-store.myshopify.com/apps/filemonk/orders/…`
  - `source` (string, nullable, required): e.g. `webhook`
- `line_items` (array of objects, required)
  - `id` (string, nullable, required): e.g. `5956bb41-dc65-45d5-b7d7-25f570598468`
  - `digital_product_id` (string, nullable, required): e.g. `7ea3c05d-6f29-42b6-b24f-43260caeaa32`
  - `title` (string, nullable, required): e.g. `Watercolour Course`
  - `sku` (string, nullable, required): e.g. `b0f5fbd0-f231-470f-b3d1-a392e3136a50`
  - `quantity` (integer, nullable, required): e.g. `2`
  - `shopify_line_item_id` (string, nullable, required): e.g. `gid://shopify/LineItem/18329329434919`
  - `shopify_product_id` (string, nullable, required): e.g. `gid://shopify/Product/9642107044135`
  - `shopify_variant_id` (string, nullable, required): e.g. `gid://shopify/ProductVariant/49417714893095`
  - `attached_to_this_order_only` (boolean, nullable, required): e.g. `false`
  - `access` (object, required)
    - `revoked` (boolean, nullable, required): e.g. `false`
    - `revoked_at` (any, required)
  - `preorder` (object, required)
    - `enabled` (boolean, nullable, required): e.g. `false`
    - `launch_at` (any, required)
    - `released` (boolean, nullable, required): e.g. `true`
    - `message` (any, required)
  - `files` (array of objects, required)
    - `id` (any, required)
    - `asset` (object, required)
      - `id` (string, nullable, required): e.g. `7ea42f2a-6dbe-459c-b8a4-27b0eb823e52`
      - `name` (string, nullable, required): e.g. `price-list.csv`
      - `type` (string, nullable, required): e.g. `file`
    - `download_count` (integer, nullable, required): e.g. `0`
    - `watermark` (object, required)
      - `enabled` (boolean, nullable, required): e.g. `false`
      - `status` (string, nullable, required): e.g. `not_required`
    - `licence_keys` (array of anys, required)
- `eu_withdrawal` (object, required)
  - `consent_required` (boolean, nullable, required): e.g. `false`
  - `consented_at` (any, required)
  - `consent_text` (any, required)
- `shopify_tags` (array of anys, required)
- `imported_at` (any, required)
- `deleted_at` (any, required)
- `created_at` (string, nullable, required): e.g. `2026-10-26T14:19:29Z`
- `updated_at` (string, nullable, required): e.g. `2026-10-30T22:19:10Z`
- `licence` (object, required)
  - `id` (string, nullable, required): e.g. `bcc87d33-c87e-4f39-9cd2-e43250ebc1ed`
  - `key` (string, nullable, required): e.g. `ABCD-EFGH-0005`
  - `source` (string, nullable, required): e.g. `uploaded`
  - `status` (string, nullable, required): e.g. `assigned`
  - `tags` (array of strings, required)
  - `assigned_at` (string, nullable, required): e.g. `2026-10-30T23:10:00Z`
  - `order` (any, required)
  - `file` (any, required)
  - `created_at` (string, nullable, required): e.g. `2026-10-30T16:48:56Z`

Rate limit: this call costs 2 points ([rate limits](https://docs.filemonk.io/v2/errors-and-rate-limits/)).

## Example request

```sh
curl -X POST "https://app.filemonk.io/api/v2/external/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f/licences/assign" \
  -H "X-Auth-Token: $FILEMONK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "e2b7727e-45ad-42b7-b842-cc4615205b10",
    "tag": "ebook-2026",
    "send_email": true
  }'
```

## 200

Success: the write completed; the body is the updated resource.

```json
{
  "id": "3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f",
  "shopify_order_id": "gid://shopify/Order/7555375595815",
  "name": "#1077",
  "confirmation_number": "H5CZG3GZX",
  "ordered_at": "2026-10-26T14:19:15Z",
  "customer": {
    "id": "b797db3a-cbc3-4643-804f-adf34c7f08d7",
    "shopify_customer_id": "gid://shopify/Customer/9026290417959",
    "email": "shopper@example.com",
    "phone": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "country_code": null,
    "locale": null,
    "unsubscribed": false
  },
  "total": {
    "amount": "1142.89",
    "currency": "INR"
  },
  "status": {
    "financial": "paid",
    "fulfillment": "unfulfilled",
    "cancelled_at": null,
    "paid_at": "2026-10-30T21:48:16Z",
    "flagged_as_fraud": false,
    "fraud_check_completed": false,
    "marked_fulfilled_at": null,
    "delivery_conditions_met": false
  },
  "access": {
    "state": "active",
    "revoked_at": null,
    "available_until": null,
    "download_reset_at": "2026-10-30T22:19:10Z",
    "downloads_count": 0
  },
  "delivery": {
    "email_sent_at": "2026-10-30T22:34:30Z",
    "delivery_failed_at": null,
    "download_page_url": "https://example-store.myshopify.com/apps/filemonk/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f",
    "source": "webhook"
  },
  "line_items": [
    {
      "id": "5956bb41-dc65-45d5-b7d7-25f570598468",
      "digital_product_id": "7ea3c05d-6f29-42b6-b24f-43260caeaa32",
      "title": "Watercolour Course",
      "sku": "b0f5fbd0-f231-470f-b3d1-a392e3136a50",
      "quantity": 2,
      "shopify_line_item_id": "gid://shopify/LineItem/18329329434919",
      "shopify_product_id": "gid://shopify/Product/9642107044135",
      "shopify_variant_id": "gid://shopify/ProductVariant/49417714893095",
      "attached_to_this_order_only": false,
      "access": {
        "revoked": false,
        "revoked_at": null
      },
      "preorder": {
        "enabled": false,
        "launch_at": null,
        "released": true,
        "message": null
      },
      "files": [
        {
          "id": null,
          "asset": {
            "id": "7ea42f2a-6dbe-459c-b8a4-27b0eb823e52",
            "name": "price-list.csv",
            "type": "file"
          },
          "download_count": 0,
          "watermark": {
            "enabled": false,
            "status": "not_required"
          },
          "licence_keys": []
        },
        {
          "id": "66e2751c-9812-422c-864d-f8ce6a95c605",
          "asset": {
            "id": "96fbe30b-c819-4cb8-9666-814c0c8853f1",
            "name": "Beginner's Guide.pdf",
            "type": "file"
          },
          "download_count": 0,
          "watermark": {
            "enabled": true,
            "status": "ready"
          },
          "licence_keys": []
        }
      ]
    }
  ],
  "eu_withdrawal": {
    "consent_required": false,
    "consented_at": null,
    "consent_text": null
  },
  "shopify_tags": [],
  "imported_at": null,
  "deleted_at": null,
  "created_at": "2026-10-26T14:19:29Z",
  "updated_at": "2026-10-30T22:19:10Z",
  "licence": {
    "id": "bcc87d33-c87e-4f39-9cd2-e43250ebc1ed",
    "key": "ABCD-EFGH-0005",
    "source": "uploaded",
    "status": "assigned",
    "tags": [
      "ebook-2026"
    ],
    "assigned_at": "2026-10-30T23:10:00Z",
    "order": null,
    "file": null,
    "created_at": "2026-10-30T16:48:56Z"
  }
}
```

## 401

Missing or invalid API key.

```json
{
  "errors": [
    "Invalid API key"
  ]
}
```

## 404

The resource does not exist for this shop, or the action path is not registered.

```json
{
  "errors": [
    "Order not found: c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
  ]
}
```

## 422

The request failed validation, or sent a key the action does not take (`code: "unknown_parameters"` with `unknown` and `accepted`). Nothing was saved.

```json
{
  "errors": [
    "access.download_limit_count must be an integer of at least 0"
  ],
  "field_errors": {
    "access.download_limit_count": [
      "must be an integer of at least 0"
    ]
  }
}
```

## 429

Rate limited. Cost-weighted per API key, shared with API v1: a read costs 1 point, a write 2, 40 points per fixed 60-second window. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix time the window ends); a 429 adds `Retry-After` (seconds), `retry_after`, `retryable: true` and a `next_step` in the body. A 429 did nothing: wait `retry_after` seconds, then send the same request again. The budget is per key, so every tool or script using the key shares it; prefer one list call with `per_page` over many single reads.

```json
{
  "errors": [
    "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 12 second(s)."
  ],
  "code": "rate_limited",
  "retry_after": 12,
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 12 second(s)."
}
```