> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filemonk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach Assets to Order

> Attach one or more assets to an order as custom files.

<Note>
  **Beta.** The order asset management endpoints are in active development. The
  request and response shapes shown here are stable for production use, but we may
  add new fields or capabilities without notice.
  [Contact support](mailto:support@filemonk.io) to be notified of breaking changes.
</Note>

Attach existing assets to a specific order. This creates a custom (order-level)
collection for the order and links the provided assets to it. Assets attached
this way appear on the customer's download page alongside any product-level
assets.

Use this endpoint together with [Create Asset](/api-reference/assets/create-asset)
and [Notify Order](/api-reference/orders/notify-order) to programmatically
deliver files to customers.

## Path parameters

<ParamField path="id" type="string" required>
  The order's unique identifier (UUID).
</ParamField>

## Request body

<ParamField body="asset_ids" type="array" required>
  An array of asset UUIDs to attach to the order. Assets must belong to your
  store. Existing attachments are preserved — duplicates are silently ignored.
</ParamField>

## Response

<ResponseField name="order" type="object" required>
  The order object.
</ResponseField>

<ResponseField name="attached_assets" type="array" required>
  List of assets that were attached (or already attached) to the order.

  <Expandable title="Asset properties">
    <ResponseField name="id" type="string" required>
      Unique asset identifier (UUID).
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Asset type: `internal`, `external`, or `licence`.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      Display name of the asset.
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      Filename of the asset.
    </ResponseField>

    <ResponseField name="content_type" type="string | null">
      MIME type of the asset.
    </ResponseField>

    <ResponseField name="byte_size" type="integer">
      File size in bytes.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://app.filemonk.io/api/v1/external/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890/attach_assets' \
    -H 'X-Auth-Token: fm_api_key_your_key_here' \
    -H 'Content-Type: application/json' \
    -d '{
      "asset_ids": [
        "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
        "a9b8c7d6-e5f4-3210-abcd-ef9876543210"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const orderId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
  const response = await fetch(
    `https://app.filemonk.io/api/v1/external/orders/${orderId}/attach_assets`,
    {
      method: 'POST',
      headers: {
        'X-Auth-Token': 'fm_api_key_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        asset_ids: [
          'f1e2d3c4-b5a6-7890-fedc-ba0987654321',
          'a9b8c7d6-e5f4-3210-abcd-ef9876543210'
        ]
      })
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  order_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  response = requests.post(
      f'https://app.filemonk.io/api/v1/external/orders/{order_id}/attach_assets',
      headers={'X-Auth-Token': 'fm_api_key_your_key_here'},
      json={
          'asset_ids': [
              'f1e2d3c4-b5a6-7890-fedc-ba0987654321',
              'a9b8c7d6-e5f4-3210-abcd-ef9876543210'
          ]
      }
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "order": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "#1042",
      "email": "customer@example.com",
      "phone": "+1234567890",
      "financial_status": "paid",
      "fulfillment_status": null,
      "total_price": "29.99",
      "currency": "USD",
      "created_at": "2026-03-01T14:30:00Z",
      "download_count": 0
    },
    "attached_assets": [
      {
        "id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
        "type": "internal",
        "name": "Custom Song - Order 1042",
        "filename": "custom-song-1042.mp3",
        "content_type": "audio/mpeg",
        "byte_size": 5242880
      }
    ]
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Order not found"
  }
  ```

  ```json 422 theme={null}
  {
    "error": "asset_ids must be a non-empty array"
  }
  ```
</ResponseExample>