Skip to content

Upload a file

Upload a file and attach it to a product as a download its buyers get.

Updated

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

  1. Reserve the file. POST /uploads 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.

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

    {
      "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. POST /assets/{asset}/complete marks it ready.

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

    {
      "id": "d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
      "status": "ready",
      "metadata": {
        "pages": 24
      }
    }
  4. Attach it. POST /{kind}/{id}/attachments attaches it to the product as a deliverable, delivered as a download.

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

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

All four steps in Node:

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: POST /uploads/inline takes its bytes in the request and answers it ready (see files).

When it goes wrong

  • The bytes request fails, or upload.expires_at passes: cancel the reservation with POST /assets/{asset}/cancel 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. GET /quota shows what is left.

Then

Fetch it back with POST /assets/{asset}/url, which answers a URL your token alone can fetch:

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

{
  "url": "https://api.sherpo.io/merchant/v1/stores/STORE_ID/files/CAPABILITY",
  "expires_at": "2026-11-03T10:05:00.000Z"
}
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());

Type to search…

↑↓ navigate↵ selectEsc close