---
title: "Upload a file"
description: "Upload a file and attach it to a product as a download its buyers get."
---

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

# Upload a file

This guide uploads a PDF workbook and attaches it to a product as a download. It uses the `sherpo` helper from [your first call](/merchant-api/first-call) and a token with `file:write` and `product:write` (attaching to a product needs both; see [scopes](/merchant-api/scopes)), and `file:read` to fetch the file back or read the storage left. [Files](/merchant-api/files) explains each step in full.

1. **Reserve the file.** <a href="/merchant-api/reference/create-upload/">`POST /uploads`</a> takes its name, type and size, and who may reach it: `signed` for a file only buyers may reach. The answer is the file, still `pending`, and where to send its bytes.

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/uploads' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{
     "enforcement": "signed",
     "name": "watercolor-workbook",
     "title": "Workbook",
     "mime": "application/pdf",
     "bytes": 2481152
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/uploads', {
     body: {
       "enforcement": "signed",
       "name": "watercolor-workbook",
       "title": "Workbook",
       "mime": "application/pdf",
       "bytes": 2481152
     },
   });
   ```

   Answers `201`, abridged:

   ```json
   {
     "asset": {
       "id": "d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
       "name": "watercolor-workbook",
       "title": "Workbook",
       "mime": "application/pdf",
       "bytes": 2481152,
       "enforcement": "signed",
       "status": "pending"
     },
     "upload": {
       "method": "PUT",
       "expires_at": "2026-11-03T11:00:00.000Z"
     }
   }
   ```

2. **Send the bytes** to `upload.url` with `upload.method` and `upload.headers`, before `upload.expires_at`. This request goes to the upload URL directly, without your token. Any other header you send is dropped when the upload completes.

3. **Complete it.** <a href="/merchant-api/reference/complete-upload/">`POST /assets/{asset}/complete`</a> marks it `ready`.

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/assets/d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a/complete' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: complete-d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/assets/d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a/complete', {
     key: 'complete-d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a',
   });
   ```

   Answers `200`, abridged:

   ```json
   {
     "id": "d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
     "status": "ready",
     "metadata": {
       "pages": 24
     }
   }
   ```

4. **Attach it.** <a href="/merchant-api/reference/attach-asset/">`POST /{kind}/{id}/attachments`</a> attaches it to the product as a `deliverable`, delivered as a `download`.

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/attachments' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: attach-d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a' \
     -H 'Content-Type: application/json' \
     -d '{
     "asset": {
       "id": "d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a"
     },
     "role": "deliverable",
     "delivery": "download"
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/attachments', {
     body: {
       "asset": {
         "id": "d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a"
       },
       "role": "deliverable",
       "delivery": "download"
     },
     key: 'attach-d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a',
   });
   ```

   Answers `200`, abridged:

   ```json
   {
     "target": {
       "kind": "product",
       "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42"
     },
     "role": "deliverable",
     "delivery": "download",
     "preview_only": false
   }
   ```

All four steps in Node:

```js
import { readFile } from 'node:fs/promises';

const bytes = await readFile('watercolor-workbook.pdf');

// 1. Reserve the file and get where to send its bytes.
const { asset, upload } = await sherpo('POST', '/v1/stores/STORE_ID/uploads', {
  body: {
    enforcement: 'signed',
    name: 'watercolor-workbook',
    title: 'Workbook',
    mime: 'application/pdf',
    bytes: bytes.length,
  },
});

// 2. Send exactly those bytes with the headers the answer gave; fetch sets Content-Length itself.
const headers = Object.fromEntries(
  Object.entries(upload.headers).filter(([name]) => name.toLowerCase() !== 'content-length'),
);
const sent = await fetch(upload.url, { method: upload.method, headers, body: bytes }).catch(
  (error) => error,
);
if (!(sent instanceof Response) || !sent.ok) {
  const reason =
    sent instanceof Response
      ? `it answered ${sent.status}${await sent.text().then((text) => (text ? `: ${text.slice(0, 200)}` : ''), (error) => ` (its body unreadable: ${error.message})`)}`
      : sent.message;
  const cancel = await sherpo('POST', `/v1/stores/STORE_ID/assets/${asset.id}/cancel`).then(
    () => null,
    (error) => error,
  );
  const then = cancel === null ? 'its upload was cancelled' : `cancelling it failed too (${cancel.message})`;
  throw new Error(`Sending the bytes of ${asset.id} failed (${reason}); ${then}.`, {
    cause: cancel === null ? sent : new AggregateError([sent, cancel]),
  });
}

// 3. Complete it, so the file becomes ready.
await sherpo('POST', `/v1/stores/STORE_ID/assets/${asset.id}/complete`, {
  key: `complete-${asset.id}`,
});

// 4. Attach it to a product, as a download its buyers get.
await sherpo('POST', '/v1/stores/STORE_ID/products/PRODUCT_ID/attachments', {
  body: { asset: { id: asset.id }, role: 'deliverable', delivery: 'download' },
  key: `attach-${asset.id}`,
});
```

A file up to 2 MiB can skip the first three steps: <a href="/merchant-api/reference/create-inline-upload/">`POST /uploads/inline`</a> takes its bytes in the request and answers it `ready` (see [files](/merchant-api/files#a-small-file-in-one-call)).

## When it goes wrong

- The bytes request fails, or `upload.expires_at` passes: cancel the reservation with <a href="/merchant-api/reference/cancel-upload/">`POST /assets/{asset}/cancel`</a> and start again.
- Completing answers `409` with `context.current: "pending"`: the bytes aren't in place yet. Send them, then complete again.
- Reserving answers `409` `conflict` on `value`: the file would take the store past its plan's storage allowance. <a href="/merchant-api/reference/get-quota/">`GET /quota`</a> shows what is left.

## Then

Fetch it back with <a href="/merchant-api/reference/get-asset-url/">`POST /assets/{asset}/url`</a>, which answers a URL your token alone can fetch:

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/assets/d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a/url' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "disposition": "attachment",
  "expires_in": 300
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/assets/d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a/url', {
  body: {
    "disposition": "attachment",
    "expires_in": 300
  },
});
```

Answers `200`, abridged:

```json
{
  "url": "https://api.sherpo.io/merchant/v1/stores/STORE_ID/files/CAPABILITY",
  "expires_at": "2026-11-03T10:05:00.000Z"
}
```

```js
const { url } = await sherpo('POST', '/v1/stores/STORE_ID/assets/ASSET_ID/url', {
  body: { disposition: 'attachment' },
});
// A linked file's URL is elsewhere, so only this API's own URLs get the token.
const headers = url.startsWith(`${BASE}/`) ? { Authorization: `Bearer ${TOKEN}` } : {};
const file = await fetch(url, { headers });
if (!file.ok) throw new Error(`The file answered ${file.status}.`);
const bytes = new Uint8Array(await file.arrayBuffer());
```

Source: https://docs.sherpo.io/merchant-api/guides/upload-a-file/index.mdx
