Assign licence keys to an order

POST/orders/{id}/licences/assign

Costs 2 rate-limit points · Rate limits

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.

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.

Also searched asassign licence keygive this order a keyadd a license key to the ordercustomer needs a keyassign key from tag

Path parameters

idstringRequired

Request body

asset_idstringRequired
Example: e2b7727e-45ad-42b7-b842-cc4615205b10
keyany
tagstring
Example: ebook-2026
send_emailboolean
Example: true

Returns

idstring, nullable
Example: 3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f
shopify_order_idstring, nullable
Example: gid://shopify/Order/7555375595815
namestring, nullable
Example: #1077
confirmation_numberstring, nullable
Example: H5CZG3GZX
ordered_atstring, nullable
Example: 2026-10-26T14:19:15Z
customerobject
Show 9 child attributesHide child attributes
- idstring, nullable
  Example: b797db3a-cbc3-4643-804f-adf34c7f08d7
- shopify_customer_idstring, nullable
  Example: gid://shopify/Customer/9026290417959
- emailstring, nullable
  Example: shopper@example.com
- phoneany
- first_namestring, nullable
  Example: Jane
- last_namestring, nullable
  Example: Doe
- country_codeany
- localeany
- unsubscribedboolean, nullable
  Example: false
totalobject
Show 2 child attributesHide child attributes
- amountstring, nullable
  Example: 1142.89
- currencystring, nullable
  Example: INR
statusobject
Show 8 child attributesHide child attributes
- financialstring, nullable
  Example: paid
- fulfillmentstring, nullable
  Example: unfulfilled
- cancelled_atany
- paid_atstring, nullable
  Example: 2026-10-30T21:48:16Z
- flagged_as_fraudboolean, nullable
  Example: false
- fraud_check_completedboolean, nullable
  Example: false
- marked_fulfilled_atany
- delivery_conditions_metboolean, nullable
  Example: false
accessobject
Show 5 child attributesHide child attributes
- statestring, nullable
  Example: active
- revoked_atany
- available_untilany
- download_reset_atstring, nullable
  Example: 2026-10-30T22:19:10Z
- downloads_countinteger, nullable
  Example: 0
deliveryobject
Show 4 child attributesHide child attributes
- email_sent_atstring, nullable
  Example: 2026-10-30T22:34:30Z
- delivery_failed_atany
- download_page_urlstring, nullable
  Example: https://example-store.myshopify.com/apps/filemonk/orders/…
- sourcestring, nullable
  Example: webhook
line_itemsarray of objects
Show 12 child attributesHide child attributes
- idstring, nullable
  Example: 5956bb41-dc65-45d5-b7d7-25f570598468
- digital_product_idstring, nullable
  Example: 7ea3c05d-6f29-42b6-b24f-43260caeaa32
- titlestring, nullable
  Example: Watercolour Course
- skustring, nullable
  Example: b0f5fbd0-f231-470f-b3d1-a392e3136a50
- quantityinteger, nullable
  Example: 2
- shopify_line_item_idstring, nullable
  Example: gid://shopify/LineItem/18329329434919
- shopify_product_idstring, nullable
  Example: gid://shopify/Product/9642107044135
- shopify_variant_idstring, nullable
  Example: gid://shopify/ProductVariant/49417714893095
- attached_to_this_order_onlyboolean, nullable
  Example: false
- accessobject
  Show 2 child attributesHide child attributes
  - revokedboolean, nullable
    Example: false
  - revoked_atany
- preorderobject
  Show 4 child attributesHide child attributes
  - enabledboolean, nullable
    Example: false
  - launch_atany
  - releasedboolean, nullable
    Example: true
  - messageany
- filesarray of objects
  Show 5 child attributesHide child attributes
  - idany
  - assetobject
    Show 3 child attributesHide child attributes
    idstring, nullable
    Example: 7ea42f2a-6dbe-459c-b8a4-27b0eb823e52
    namestring, nullable
    Example: price-list.csv
    typestring, nullable
    Example: file
  - download_countinteger, nullable
    Example: 0
  - watermarkobject
    Show 2 child attributesHide child attributes
    enabledboolean, nullable
    Example: false
    statusstring, nullable
    Example: not_required
  - licence_keysarray of anys
eu_withdrawalobject
Show 3 child attributesHide child attributes
- consent_requiredboolean, nullable
  Example: false
- consented_atany
- consent_textany
shopify_tagsarray of anys
imported_atany
deleted_atany
created_atstring, nullable
Example: 2026-10-26T14:19:29Z
updated_atstring, nullable
Example: 2026-10-30T22:19:10Z
licenceobject
Show 9 child attributesHide child attributes
- idstring, nullable
  Example: bcc87d33-c87e-4f39-9cd2-e43250ebc1ed
- keystring, nullable
  Example: ABCD-EFGH-0005
- sourcestring, nullable
  Example: uploaded
- statusstring, nullable
  Example: assigned
- tagsarray of strings
- assigned_atstring, nullable
  Example: 2026-10-30T23:10:00Z
- orderany
- fileany
- created_atstring, nullable
  Example: 2026-10-30T16:48:56Z

Errors

401

Missing or invalid API key.

404

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

422

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

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.

Every error has the same shape: see Errors.

POST/orders/{id}/licences/assign

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
  }'

const res = await fetch("https://app.filemonk.io/api/v2/external/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f/licences/assign", {
  method: "POST",
  headers: {
    "X-Auth-Token": process.env.FILEMONK_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "asset_id": "e2b7727e-45ad-42b7-b842-cc4615205b10",
    "tag": "ebook-2026",
    "send_email": true
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://app.filemonk.io/api/v2/external/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f/licences/assign",
    headers={"X-Auth-Token": os.environ["FILEMONK_API_KEY"]},
    json={
        "asset_id": "e2b7727e-45ad-42b7-b842-cc4615205b10",
        "tag": "ebook-2026",
        "send_email": True
    },
)
data = res.json()

require "net/http"
require "json"

uri = URI("https://app.filemonk.io/api/v2/external/orders/3e84eb8d-e1d9-4e92-a4b2-a419c7f1122f/licences/assign")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["FILEMONK_API_KEY"], "Content-Type" => "application/json")
req.body = {
  asset_id: "e2b7727e-45ad-42b7-b842-cc4615205b10",
  tag: "ebook-2026",
  send_email: true
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Response

{
  "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"
  }
}

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

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

{
  "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"
    ]
  }
}

{
  "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)."
}