> For the complete documentation index, see [llms.txt](https://docs.startrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/worked-example.md).

# Worked example

End to end with a registered schema — one-time collection, issue, read back, update, transfer, viewer link — with the calls, bodies and what to store.

One client, one registered schema (`ingot-registry-record`), one record from creation to transfer. Every call carries `commerce-api-key`, `issuer-address` and `Content-Type: application/json`; `<base_url>` is the environment's host — see [URL per environment](https://docs.startrail.io/readme/url-per-environment.md). The viewer host is `https://port.startrail.io` in production and `https://port-stg.startbahn.jp` on the test environment.

## The big picture

```mermaid
flowchart TD
    A["0 POST /commerce/collection (once)"] -->|collectionAddress| B["1 GET /schema-registry/name/<name>?version=latest"]
    B -->|cid| C["2 POST /commerce/srrs<br/>$schema = ipfs://cid, collectionAddress"]
    C -->|tokenId, metadataCID| D["3 GET /collection/{collectionAddress}/srr/{tokenId}<br/>poll until metadataDigest = metadataCID"]
    D --> E["4 PATCH /commerce/srrs/{tokenId}/metadata<br/>baseCid = last metadataCID"]
    E -->|new metadataCID| D
    D --> F["5 POST /commerce/srrs/transfers"]
    F --> G["6 poll ownerAddress / transferCommitment"]
    G --> H["Viewer: /srr/{collectionAddress}/{tokenId}"]
```

| # | Step               | Endpoint                                                         | You provide                                                      | You store                                                                    |
| - | ------------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| 0 | Collection, once   | `POST /commerce/collection`                                      | `payload.name`, `payload.symbol`                                 | `collectionAddress` — it goes into every later call and into the viewer link |
| 1 | Resolve the schema | `GET /schema-registry/name/ingot-registry-record?version=latest` | —                                                                | `cid` (optional: issuance resolves a name form itself)                       |
| 2 | Issue              | `POST /commerce/srrs`                                            | `requestId`, one entry with `collectionAddress` and the document | `tokenId`, `metadataCID`, `requestId`                                        |
| 3 | Read back          | `GET /collection/{collectionAddress}/srr/{tokenId}`              | —                                                                | — ; poll until `metadataDigest` = `metadataCID`                              |
| 4 | Update             | `PATCH /commerce/srrs/{tokenId}/metadata`                        | `baseCid` = last `metadataCID`, `collectionAddress`, the change  | new `metadataCID`                                                            |
| 5 | Transfer           | `POST /commerce/srrs/transfers`                                  | `tokenId`, `collectionAddress`, `to`, `transferType`             | `transferMetadataCID`                                                        |
| 6 | Confirm            | step 3 route, or webhooks                                        | —                                                                | —                                                                            |

## 0. Collection (once)

```json
POST <base_url>/port/api/v1/commerce/collection
{ "payload": { "name": "Ingot Registry", "symbol": "INGOT" } }
```

`201` → `result.collectionAddress`, `status: waiting_for_mining`. Usable once mined; confirm with [Get Collection of LUW](https://docs.startrail.io/issue-transfer-api/collection/get-collection-of-luw.md) or the `collection_created` webhook. See [Create Collection](https://docs.startrail.io/issue-transfer-api/collection/create-collection.md).

## 1. Resolve the schema

```
GET <base_url>/port/api/v1/schema-registry/name/ingot-registry-record?version=latest
```

`200` → `cid`, `schemaUri` (`ipfs://<cid>`), `version`. You can skip this and put the name form straight into `$schema`; the pinned document ends up on the latest version either way.

## 2. Issue

```json
POST <base_url>/port/api/v1/commerce/srrs
{
  "requestId": "ingot-2026-10-27-001",
  "payload": [
    {
      "externalId": "ingot-2026-10-27-001-1",
      "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1",
      "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22",
      "isPrimaryIssuer": true,
      "lockExternalTransfer": false,
      "metadata": {
        "$schema": "ipfs://bafkreigxv3lhvqmfz5n6g2xzpt4ql3a4ql7ekg7kza6iz5s4ms2nrv4d4u",
        "name": "Silver bar 1 kg, serial SRF-2025-00412",
        "identifierScheme": "ingot-markings-v1",
        "itemIdentifier": "bab885aba45a1c6b8f58bf53b9510be04925a3e87ae563a2b2bcf8e87e85ca90",
        "imageHash": "0c405ae068a7d62aef5050ab719466dab62a6a4a7458a5e16eb6ff7c30c7888c",
        "hubEventId": "a246877c73b2feec86fc9004e30ef4747fbe214da29ff9049ce4c911569bf3db",
        "markings": {
          "metal": "silver",
          "refiner": "Silver Refiners Federation",
          "serialNumber": "SRF-2025-00412",
          "fineness": 0.999,
          "weight": { "value": 1, "unit": "kg" },
          "form": "bar"
        },
        "custody": {
          "custodian": { "externalId": "CUST-001", "name": { "en": "Northern Vault Services AG" } },
          "facility": "ZRH-V2",
          "country": "CH",
          "status": "in_custody"
        }
      }
    }
  ]
}
```

`201`:

```json
{
  "results": [
    {
      "status": "waiting_for_mining",
      "srr": {
        "tokenId": "561308332886",
        "metadataCID": "bafkreidtb6ta2abip7jhdglevredpdlfmp2764u6bkwhlkjcrpruv46wla",
        "metadataURL": "https://cdn.startrail.io/ipfs/bafkreidtb6ta2abip7jhdglevredpdlfmp2764u6bkwhlkjcrpruv46wla",
        "collectionContractAddress": "0x8B116A8896538377328936279E64B11303cBf7B1"
      },
      "externalId": "ingot-2026-10-27-001-1"
    }
  ]
}
```

| Answer                                                        | What to do                                                                                           |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `201`                                                         | Store `tokenId`, `metadataCID`, `requestId`                                                          |
| `400` with `Details`                                          | The document breaks the schema; fix it and send again with a **new** `requestId`                     |
| `400` `Duplicate Request Error …` / `Request Content Error …` | You already sent this; read the result from step 3 instead                                           |
| `403`                                                         | The wallet is not enabled for registered schemas; [contact Startbahn](https://startbahn.io/contact)  |
| Timeout, no answer                                            | Resend with the **same** `requestId`: a request that went through is refused instead of issued twice |

## 3. Read back

```
GET <base_url>/port/api/v1/collection/0x8B116A8896538377328936279E64B11303cBf7B1/srr/561308332886
```

| Answer                                                                         | Meaning                                      |
| ------------------------------------------------------------------------------ | -------------------------------------------- |
| `404` `SRR not found: 0x8B116A8896538377328936279E64B11303cBf7B1/561308332886` | Not indexed yet — poll every few seconds     |
| `200`, `metadataDigest` ≠ the CID you expect                                   | Indexed, but the last transaction is not yet |
| `200`, `metadataDigest` = `metadataCID`                                        | Done                                         |

The document itself is at `https://cdn.startrail.io/ipfs/<metadataDigest>`; `$schema` in it is the CID form and any storage URL you sent is `ipfs://<cid>`. See [Get SRR by collection and token id](https://docs.startrail.io/get-srr-api/get-srr-by-token-id.md) and [subgraph lag](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md#edge-cases).

## 4. Update

A beneficiary is assigned. The whole change is one `PATCH`; `baseCid` is the `metadataCID` of step 2.

```json
PATCH <base_url>/port/api/v1/commerce/srrs/561308332886/metadata
{
  "requestId": "ingot-first-beneficiary-2026-10-27-001",
  "payload": {
    "set": { "hubEventId": "a29da9b3326f9e7763a7c88cb19ab3762380135ffaa5e0a28dc77a8084c4d475" },
    "prepend": {
      "beneficiaries": [
        {
          "effectiveAt": "2026-10-13T10:00:00+02:00",
          "externalId": "3012f2cf037c5bbd107085a096c4d240b7d34cc9c1ffe1eb5fc767c4e78e820a",
          "hubEventId": "a29da9b3326f9e7763a7c88cb19ab3762380135ffaa5e0a28dc77a8084c4d475",
          "reason": "allocation",
          "reference": "ALLOC-2026-1013-01"
        }
      ]
    },
    "baseCid": "bafkreidtb6ta2abip7jhdglevredpdlfmp2764u6bkwhlkjcrpruv46wla",
    "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1"
  }
}
```

`200`:

```json
{
  "previousMetadataCID": "bafkreidtb6ta2abip7jhdglevredpdlfmp2764u6bkwhlkjcrpruv46wla",
  "tokenId": "561308332886",
  "collectionAddress": "0x8b116a8896538377328936279e64b11303cbf7b1",
  "metadataCID": "bafkreic6dylmir5h25qds7jpqxuai5m556kdzd3jwgcf6m7m65bv32rery",
  "metadataURL": "https://cdn.startrail.io/ipfs/bafkreic6dylmir5h25qds7jpqxuai5m556kdzd3jwgcf6m7m65bv32rery",
  "txReceiptId": "12345"
}
```

| Answer               | What to do                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `200`                | Store `metadataCID`: it is the next `baseCid`. Poll step 3 until `metadataDigest` equals it                              |
| `204`                | Nothing changed; the version stays                                                                                       |
| `400` with `Details` | Invalid change (a required field missing, an enum value); nothing is written                                             |
| `404`                | Unknown token, wrong `collectionAddress`, or a `baseCid` nothing resolves: read `metadataDigest` from step 3 and rebuild |

Later events follow the same pattern: a sale is another `prepend.beneficiaries`; a custodian change is `set.custody`; an assay certificate is `set.assay`. Send one update at a time per record and chain `baseCid` — see [Update metadata](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/update-metadata.md).

## 5. Transfer

The record is reserved for the buyer's email; the certificate moves when the buyer signs in.

```json
POST <base_url>/port/api/v1/commerce/srrs/transfers
{
  "requestId": "ingot-transfer-2026-10-27-001",
  "payload": [
    {
      "tokenId": "561308332886",
      "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1",
      "externalId": "DEAL-2026-1014-04",
      "to": { "email": "buyer@example.com" },
      "transferType": "Primary sale",
      "remarks": { "en": "Sold at the autumn fair" }
    }
  ]
}
```

`201` → `results[0].mode: reserved`, `transferMetadataCID`, `nextStep`. If the buyer never signs in, complete it yourself with `POST /commerce/srrs/561308332886/transfers/claim` and `payload.preimage = "buyer@example.com"`, or cancel it with `DELETE /commerce/srrs/561308332886/transfers/pending?collectionAddress=0x8B11…`. See [Transfers](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/transfers.md).

## 6. Confirm and link

Poll step 3: `transferCommitment` is set once the reservation is mined; `ownerAddress` changes once the transfer executes. The `transferReservationComplete` and `transferExecutionComplete` [webhooks](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/webhook-setup.md) fire at the same points.

The certificate page for the record:

```
https://port.startrail.io/srr/0x8B116A8896538377328936279E64B11303cBf7B1/561308332886
```

## Checklist

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

ONCE:
  0. POST /commerce/collection {payload:{name,symbol}} -> store result.collectionAddress

PER RECORD:
  1. (optional) GET /schema-registry/name/<name>?version=latest -> cid
  2. POST /commerce/srrs {requestId, payload:[{externalId, collectionAddress, artistAddress,
       isPrimaryIssuer, lockExternalTransfer, metadata:{$schema: ipfs://cid, ...}}]}
       -> store tokenId, metadataCID; no attachmentFiles with a registered schema
       -> 403: wallet not enabled (closed release) -> contact Startbahn
  3. GET /collection/{collectionAddress}/srr/{tokenId} until metadataDigest == metadataCID

PER CHANGE (one at a time per record):
  4. PATCH /commerce/srrs/{tokenId}/metadata {requestId, payload:{set|append|prepend|insert,
       baseCid: last metadataCID, collectionAddress}}
       -> 200: store metadataCID (next baseCid); 204: nothing changed
  3. poll until metadataDigest == new metadataCID

TRANSFER:
  5. POST /commerce/srrs/transfers {requestId, payload:[{tokenId, collectionAddress, to:{address|email|revealHash}, transferType}]}
       -> address: owner changes when mined; email/revealHash: reserved, claim or cancel later
  6. poll ownerAddress / transferCommitment; viewer: https://port.startrail.io/srr/{collectionAddress}/{tokenId}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/worked-example.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
