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.
-
Reserve the file.
POST /uploadstakes its name, type and size, and who may reach it:signedfor a file only buyers may reach. The answer is the file, stillpending, 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" } } -
Send the bytes to
upload.urlwithupload.methodandupload.headers, beforeupload.expires_at. This request goes to the upload URL directly, without your token. Any other header you send is dropped when the upload completes. -
Complete it.
POST /assets/{asset}/completemarks itready.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 } } -
Attach it.
POST /{kind}/{id}/attachmentsattaches it to the product as adeliverable, delivered as adownload.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_atpasses: cancel the reservation withPOST /assets/{asset}/canceland start again. - Completing answers
409withcontext.current: "pending": the bytes aren’t in place yet. Send them, then complete again. - Reserving answers
409conflictonvalue: the file would take the store past its plan’s storage allowance.GET /quotashows 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());