🗺️Issuance Flow (End-to-End)

End-to-end recommended flow for issuing SRRs — single and bulk, with new files or reusing previously uploaded files. Flowcharts + step tables.

This page shows the recommended order of API calls to issue SRRs, from file upload to mining confirmation. For payload bodies see Request Payloads & Recipes; for failures see Errors & Troubleshooting.

The one rule that shapes the whole flow: every file an SRR references (thumbnailURL, image, contractTerms.fileURL, attachmentFiles[*].url) must be uploaded via /commerce/signedUrls and referenced by the returned finalUrl — see File URLs. The finalUrl is in the signed-URL response immediately, so you can build your issuance payload right away; you only wait (poll /fileMetadata) for the file's hash + cid before actually calling the issue endpoint.

The big picture

The same six steps apply to single and bulk — bulk just carries more entries in the same two arrays (signedUrls.payload[] for files, srrs.payload[] for SRRs).

Flow A — single SRR with a new file

#	Step	Endpoint	You provide	You get / wait for
1	Request signed URL	POST /commerce/signedUrls	filename (unique per issuer, no spaces, with extension) + category (see the category table) + action: "write"	url (upload target), finalUrl (store it!), contentType
2	Upload	HTTP PUT to url	the file bytes, Content-Type from step 1	200
3	Wait for readiness	POST /commerce/fileMetadata	same filename + category	poll until hash and cid are present (usually a few minutes)
4	Issue	POST /commerce/srrs	requestId (fresh UUID) + payload[0] with metadata.thumbnailURL / image (= finalUrl), optional attachmentFiles	201 with tokenId, metadataCID, status: waiting_for_mining
5	Confirm	Webhook / subgraph	—	mining outcome; full SRR data

Use the public non_attachment_file category for files going into thumbnailURL / image / contractTerms.fileURL — private categories are rejected for those fields. One file can serve several roles (e.g. the same finalUrl as thumbnailURL and image).

Flow B — bulk issuance (many SRRs, many files)

Bulk is the same flow with batched arrays — do not loop the single flow per SRR.

Key differences from single:

Concern	Rule
Files per signedUrls / fileMetadata call	Any number (payload[] array) — batch them, upload in parallel
SRRs per srrs call	1..n in payload[]; ≤ 250 recommended (no hard cap)
Atomicity	All-or-nothing: one failed entry cancels the whole batch — fix the entry named in results[] and resubmit everything
Readiness	Wait until every referenced file has hash + cid before issuing — one not-ready file fails the whole batch
NFC tags	The chip sum across all entries must fit the LUW's NFC allowance — see NFC errors
Idempotency	One requestId for the whole batch; reuse is rejected (Duplicate Request Error)

Flow C — reusing previously uploaded files

Files stay in storage and keep their finalUrl, hash and cid forever — upload once, reference many times.

• Store finalUrls alongside your own records at upload time — that makes reuse a zero-step operation.

• A reused file needs no re-upload and no polling: its hash/cid were computed after the original upload.

• Reuse is natural when: many editions share one artwork image, a shared contract-terms PDF, or re-issuing after a failed batch.

• Filenames are unique per issuer-address — you cannot re-upload a new file under a used name; pick a new name for new content. Identical content under a different name resolves to the same CID on IPFS, so duplicates are harmless.

Checklist (for humans and LLMs)

RECOMMENDED ISSUANCE FLOW (commerce API, base: <base_url>/port/api/v1)
Headers on every call: commerce-api-key, issuer-address, Content-Type: application/json

FOR EACH NEW FILE (batchable):
  1. POST /commerce/signedUrls   body: {payload:[{filename,category}], action:"write"}
     -> save results[i].finalUrl               (available immediately)
     -> category: non_attachment_file for thumbnail/image/contract-terms files,
        artwork for digital-artwork files, private categories for confidential attachments
  2. PUT <results[i].url>        body: file bytes, Content-Type: results[i].contentType
  3. POST /commerce/fileMetadata body: {payload:[{filename,category}]}
     -> repeat until every file returns hash AND cid   (do not issue before this)

FOR REUSED FILES: skip 1-3, use the stored finalUrl
  (lost it? POST /commerce/signedUrls with action:"read" returns it again)

ISSUE (single or bulk, same endpoint):
  4. POST /commerce/srrs body: {requestId:<fresh UUID>, payload:[1..n SRR entries]}
     -> every thumbnailURL / image / contractTerms.fileURL / attachmentFiles[].url
        MUST be a finalUrl; external URLs are rejected (400)
     -> batch is atomic; <=250 entries recommended
     -> response 201: results[i].srr.tokenId + metadataCID, status waiting_for_mining

CONFIRM:
  5. Webhook notifies mining success/failure; read full SRR data from the subgraph.

Common pitfalls

Pitfall	What happens	Avoid by
Issuing before cid is ready	400 … not ready for IPFS publication … / Attachment hash not ready …	Step 3 — poll /fileMetadata first
External file URL (your own CDN, Shopify, …)	400 File URLs must be Startbahn storage URLs …	Always use the finalUrl
Private category for a thumbnail/image	400 … must be publicly accessible …	Upload with non_attachment_file
Reusing a requestId	400 Duplicate Request Error	Fresh UUID per request; reuse only intended as a retry-guard
Retrying a failed bulk with the same body	400 Request Content Error: … already logged	Fix the failing entry, keep a new requestId
Assuming 201 = minted	SRR may still fail at mining	Wait for the webhook; verify via the subgraph

🧩Request Payloads & Recipes🚨Errors & Troubleshooting