Upload File to Order

Note

Beta. The order asset management and notification 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 to be notified of breaking changes.

Overview

A common workflow for custom/made-to-order products is:

1. Upload a file via the Upload Asset flow
2. Attach it to a specific order
3. Notify the customer so they receive the download email

This guide walks through all three steps.

1. Upload the file

Create an internal asset and upload the file body. See Upload Asset for the full reference.

# Step 1a: Create the asset and get the presigned upload URL
RESPONSE=$(curl -s -X POST 'https://app.filemonk.io/api/v1/external/assets' \
  -H 'X-Auth-Token: fm_api_key_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "asset": {
      "type": "internal",
      "filename": "custom-song.mp3",
      "byte_size": 5242880,
      "content_type": "audio/mpeg"
    }
  }')

ASSET_ID=$(echo $RESPONSE | jq -r '.asset.id')
UPLOAD_URL=$(echo $RESPONSE | jq -r '.upload.url')

# Step 1b: Upload the file body
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/mpeg" \
  -H "Content-Disposition: inline; filename=\"custom-song.mp3\"" \
  --upload-file ./custom-song.mp3

const API_KEY = 'fm_api_key_your_key_here';
const BASE = 'https://app.filemonk.io/api/v1/external';

// Step 1a: Create the asset
const filePath = './custom-song.mp3';
const stats = await stat(filePath);

const create = await fetch(`${BASE}/assets`, {
  method: 'POST',
  headers: {
    'X-Auth-Token': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    asset: {
      type: 'internal',
      filename: 'custom-song.mp3',
      byte_size: stats.size,
      content_type: 'audio/mpeg'
    }
  })
}).then(r => r.json());

// Step 1b: Upload the file body
const body = await readFile(filePath);
await fetch(create.upload.url, {
  method: 'PUT',
  headers: create.upload.headers,
  body
});

const assetId = create.asset.id;

API_KEY = 'fm_api_key_your_key_here'
BASE = 'https://app.filemonk.io/api/v1/external'

# Step 1a: Create the asset
file_path = './custom-song.mp3'
byte_size = os.path.getsize(file_path)

create = requests.post(
    f'{BASE}/assets',
    headers={'X-Auth-Token': API_KEY},
    json={
        'asset': {
            'type': 'internal',
            'filename': 'custom-song.mp3',
            'byte_size': byte_size,
            'content_type': 'audio/mpeg'
        }
    }
).json()

# Step 1b: Upload the file body
with open(file_path, 'rb') as f:
    requests.put(create['upload']['url'], headers=create['upload']['headers'], data=f).raise_for_status()

asset_id = create['asset']['id']

2. Attach the asset to the order

curl -X POST "https://app.filemonk.io/api/v1/external/orders/$ORDER_ID/attach_assets" \
  -H 'X-Auth-Token: fm_api_key_your_key_here' \
  -H 'Content-Type: application/json' \
  -d "{\"asset_ids\": [\"$ASSET_ID\"]}"

const orderId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

await fetch(`${BASE}/orders/${orderId}/attach_assets`, {
  method: 'POST',
  headers: {
    'X-Auth-Token': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ asset_ids: [assetId] })
});

order_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'

requests.post(
    f'{BASE}/orders/{order_id}/attach_assets',
    headers={'X-Auth-Token': API_KEY},
    json={'asset_ids': [asset_id]}
).raise_for_status()

3. Notify the customer

curl -X POST "https://app.filemonk.io/api/v1/external/orders/$ORDER_ID/notify" \
  -H 'X-Auth-Token: fm_api_key_your_key_here' \
  -H 'Content-Type: application/json'

const notify = await fetch(`${BASE}/orders/${orderId}/notify`, {
  method: 'POST',
  headers: {
    'X-Auth-Token': API_KEY,
    'Content-Type': 'application/json'
  }
}).then(r => r.json());

console.log('Notified at:', notify.notified_at);

notify = requests.post(
    f'{BASE}/orders/{order_id}/notify',
    headers={'X-Auth-Token': API_KEY}
).json()

print('Notified at:', notify['notified_at'])

That’s it — the customer will receive a download email with a link to their custom file.

Tip

You can also use an external URL asset instead of uploading a file. Create the asset with type: "external" and external_url pointing to your hosted file, then follow steps 2 and 3 above.

Using an external URL instead

If your file is already hosted elsewhere, skip the upload and create an external asset instead:

curl -X POST 'https://app.filemonk.io/api/v1/external/assets' \
  -H 'X-Auth-Token: fm_api_key_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "asset": {
      "type": "external",
      "external_url": "https://cdn.example.com/songs/custom-song-1042.mp3",
      "name": "Custom Song"
    }
  }'

Then attach and notify as above.