POSTMethod POST/partner/mint/batch

You send a batch of product rows, and you receive a batch identifier. We answer as soon as we accept the batch, before any processing. You then follow the progress with GET /v1/partner/mint/batch/status/{job_id}. Read the warning below before reading that status.

Full address:

POST https://api.sealtrust.io/v1/partner/mint/batch

The same endpoint also answers without the /v1 prefix, at https://api.sealtrust.io/partner/mint/batch. The two addresses call the same code. Use the /v1 form for a new integration.

#Authorization

Send your API key in the Authorization header, in the Bearer format. The key must carry the mint:batch scope. A key that does not carry this scope receives a 403 whose message names the missing scope.

Three conditions come on top of the scope of the key.

• The plan of the key's brand must include API access. Otherwise you receive a 403 carrying the code FEATURE_NOT_AVAILABLE.
• The plan of the batch's brand must allow identification by QR. That is the method the server sets on every row of this endpoint. A plan that does not allow it receives a 403 carrying the code AUTH_METHOD_NOT_ALLOWED.
• Every row carries the public code of a brand the key serves: its own, or, with a reseller key, a client brand of your contract. A single row carrying another code makes the whole batch refused with a 403. All the rows carry the same brand, otherwise the batch is refused with 422 ONE_BRAND_PER_BATCH. The offer and the allowance applied are that brand's.

#Rate limit

We measure the rate over a fixed 60-second window. We first apply the value set on your account, if we have set one. Otherwise the one of your plan. In the absence of both, the fallback value is 120 calls per window.

Two counters are layered, with the same cap: one per key, one for the sum of all the keys of your brand. Creating additional keys therefore does not increase the total rate allowed.

As soon as we recognize your key, the response carries four headers. They describe the more constraining of the two counters. An authentication refusal comes before the counting and carries none of these headers.

A rate refusal returns 429. It carries these four headers, describing this time the counter that refused, and it adds Retry-After, expressed in seconds remaining in the current window. This value is never lower than 1.

Two other caps can refuse the same call: the daily quota of your key, which is consumed per item, and, on a trial account only, the cap of 10 products per billing period. You will find them in the error table, further down.

#Path and query parameters

This endpoint has no path parameter, and one optional query parameter.

#Headers

#Request body

You send the batch in one of the two formats. The content is the same in both cases.

• JSON: send a list of objects. A lone object, a number or a string at the top level makes the request fail with a 400.
• CSV: send a file as multipart/form-data, under the form field named exactly file. Encode the file in UTF-8. You may leave the byte order mark at the head of the file, we remove it. A file encoded otherwise makes the call fail with a 500. In a spreadsheet, choose the "CSV UTF-8" export. We strip the edge spaces of the cells before validating.

You can compress the CSV file in gzip or in zlib, we decompress it. If the decompressed content exceeds about 20 MiB, you receive a 413.

A batch has at most 500 items. We refuse an empty batch with a 400.

#Fields of a row

A row accepts seven fields, and only seven.

In CSV, the header must contain at least the four required columns. The model_sku and batch_code columns are optional, and an empty cell means "no code". The order of the columns is free.

The server ignores no field. Any field this table does not name makes the row fail, and therefore the batch, with a 400.

#Replaying a call without doubling its effect

You can send an Idempotency-Key header. It is optional. We remember it for 24 hours.

• Replay the same idempotency key with the same batch, and you receive the response of the first call, without a second processing starting.
• Replay the same idempotency key with a different batch, and you receive a
  409. This behavior dates from 08/20/2026. Before that, the second batch was never processed and nothing reported it.
• Replay an idempotency key whose call is still being processed, and you also receive a 409. This lock expires on its own after 60 seconds.

We compare two batches on their content once read and normalized. The order of the rows, the order of the columns, the choice between CSV and JSON and the empty cells make no difference.

#Example request

A batch of two items, in JSON.

curl -i -X POST https://api.sealtrust.io/v1/partner/mint/batch \
  -H "Authorization: Bearer st_live_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-example-0001" \
  -d '[
    {
      "product_name": "Sac Exemple 001",
      "brand_code": "7K3QXW9M2A",
      "category_id": 3,
      "metadata_uri": "ipfs://example-metadonnees-0001",
      "external_ref": "EX-0001"
    },
    {
      "product_name": "Sac Exemple 002",
      "brand_code": "7K3QXW9M2A",
      "category_id": 3,
      "metadata_uri": "ipfs://example-metadonnees-0002",
      "external_ref": "EX-0002"
    }
  ]'

import { SealTrustClient } from "@sealtrust-io/sdk";

const sealtrust = new SealTrustClient({
  apiKey: "st_live_0000000000000000000000000000000000000000000000",
});

const batch = await sealtrust.products.mint(
  [
    {
      product_name: "Sac Exemple 001",
      brand_code: "7K3QXW9M2A",
      category_id: 3,
      metadata_uri: "ipfs://example-metadonnees-0001",
      external_ref: "EX-0001",
    },
    {
      product_name: "Sac Exemple 002",
      brand_code: "7K3QXW9M2A",
      category_id: 3,
      metadata_uri: "ipfs://example-metadonnees-0002",
      external_ref: "EX-0002",
    },
  ],
  "batch-example-0001",
);

console.log(batch.job_id, batch.status, batch.items_count, batch.brand_code);

import requests

batch = [
    {
        "product_name": "Sac Exemple 001",
        "brand_code": "7K3QXW9M2A",
        "category_id": 3,
        "metadata_uri": "ipfs://example-metadonnees-0001",
        "external_ref": "EX-0001",
    },
    {
        "product_name": "Sac Exemple 002",
        "brand_code": "7K3QXW9M2A",
        "category_id": 3,
        "metadata_uri": "ipfs://example-metadonnees-0002",
        "external_ref": "EX-0002",
    },
]

response = requests.post(
    "https://api.sealtrust.io/v1/partner/mint/batch",
    headers={
        "Authorization": "Bearer st_live_0000000000000000000000000000000000000000000000",
        "Idempotency-Key": "batch-example-0001",
    },
    json=batch,
    timeout=30,
)

print(response.status_code)
print(response.headers["X-RateLimit-Remaining"])
print(response.json())

The same batch in CSV, sent as multipart/form-data. The batch.csv file contains:

product_name,brand_code,category_id,metadata_uri,external_ref
Sac Exemple 001,7K3QXW9M2A,3,ipfs://example-metadonnees-0001,EX-0001
Sac Exemple 002,7K3QXW9M2A,3,ipfs://example-metadonnees-0002,EX-0002

The TypeScript SDK does not expose CSV submission. The TypeScript tab below therefore calls the endpoint directly.

curl -i -X POST https://api.sealtrust.io/v1/partner/mint/batch \
  -H "Authorization: Bearer st_live_0000000000000000000000000000000000000000000000" \
  -H "Idempotency-Key: batch-example-0001" \
  -F "file=@batch.csv;type=text/csv"

import { readFile } from "node:fs/promises";

const contenu = await readFile("batch.csv");

const formulaire = new FormData();
formulaire.append("file", new Blob([contenu], { type: "text/csv" }), "batch.csv");

const response = await fetch("https://api.sealtrust.io/v1/partner/mint/batch", {
  method: "POST",
  headers: {
    Authorization:
      "Bearer st_live_0000000000000000000000000000000000000000000000",
    "Idempotency-Key": "batch-example-0001",
  },
  body: formulaire,
});

console.log(response.status);
console.log(response.headers.get("X-RateLimit-Remaining"));
console.log(await response.json());

import requests

with open("batch.csv", "rb") as file:
    response = requests.post(
        "https://api.sealtrust.io/v1/partner/mint/batch",
        headers={
            "Authorization": "Bearer st_live_0000000000000000000000000000000000000000000000",
            "Idempotency-Key": "batch-example-0001",
        },
        files={"file": ("batch.csv", file, "text/csv")},
        timeout=30,
    )

print(response.status_code)
print(response.headers["X-RateLimit-Remaining"])
print(response.json())

#Example response

HTTP code 200.

{
  "job_id": "0000a1b2c3d4e5f6",
  "status": "queued",
  "items_count": 2,
  "brand_code": "7K3QXW9M2A",
  "brand_id": 12,
  "issue_purchase_codes": false
}

The response has six fields and nothing else.

status: "queued" means that we have accepted the batch and that it is waiting for its processing. We have processed nothing at that moment. Follow what comes next with GET /v1/partner/mint/batch/status/{job_id}.

#Errors

The body of an error response carries a detail field. Depending on the case, this field contains a sentence or an object.

A refusal that carries a sentence, here the empty batch, HTTP code 400:

{
  "detail": "Batch vide (aucun item)"
}

A refusal that carries an object, here an incomplete CSV header, HTTP code 400:

{
  "detail": {
    "error": "Colonnes manquantes",
    "missing": ["category_id", "metadata_uri"]
  }
}

#See also

• GET /partner/mint/batch/status/{job_id}, follow the progress of a batch sent to minting.
• Create products, one at a time and in batches, create a product, create a whole run, import a file.
• Partner API, overview, base address, keys, scopes, call caps and pagination.
• Issue purchase codes, one code per piece, shown once, at mint time or later.
• API errors, recognize an error code and decide whether to correct or replay.