> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://tieback.io/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tieback.io/docs/_mcp/server.

# Minting Lifecycle

> Follow a mint request from submission through to completion, covering job states, batch states, processing cycles, retries and idempotent resubmission.

## Overview

Every mint request follows a deterministic lifecycle from submission through to completion. This page describes each stage, the state transitions involved, and what happens when something fails.

## Mint request submission

A mint request begins when someone submits it through the Minting Wizard or programmatically through the API.

Submission performs the following atomically:

#### Preflight validation

Confirms the product is mint ready: active commercial status and all required DPP fields
populated.

#### ERP enforcement

If a production batch is linked, confirms it exists, belongs to the brand and product, carries
`READY` status, and that the requested quantity fits within the batch quantity.

#### Job creation

Creates a mint job in `QUEUED` status.

#### Batch creation

Creates a mint batch linked one to one with the job.

If a preflight check fails, the request returns a structured list of blocking reasons and creates no records.

## Job state transitions

```
QUEUED → RESERVED → PROCESSING → COMPLETED
                                → FAILED
```

| State          | Description                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| **QUEUED**     | Job is waiting to be claimed by a background worker.                           |
| **RESERVED**   | A worker has claimed the job and is preparing to process it.                   |
| **PROCESSING** | Token generation is in progress. Units are being created in processing cycles. |
| **COMPLETED**  | All requested units have been generated successfully.                          |
| **FAILED**     | The job has exhausted its retry attempts and is a terminal failure.            |

## Batch status transitions

```
queued → processing → minted
                    → failed
```

The mint batch status mirrors the job lifecycle. When the job reaches `COMPLETED`, the batch becomes `minted` and records the final `minted_quantity`.

## Processing cycles

During the `PROCESSING` phase:

* Units are generated in high throughput cycles.
* Each cycle inserts units with resolver URLs, serial numbers for serial mode jobs, and the appropriate status.
* The worker continues until the requested quantity is reached or an error occurs.
* Large jobs continue automatically across multiple worker invocations until the job is complete.

## Failure and retry semantics

* If a processing cycle hits an error, the error is recorded and the job's error count increases.
* The job stays eligible for retry until it exhausts its allowed attempts.
* After that, the job moves to `FAILED` with the last error message preserved.
* Partial progress is preserved. Units generated before the failure remain in place.

## Idempotency

Mint requests support client provided idempotency keys. When a duplicate request arrives with the same key:

* The existing job and batch are returned.
* No new records are created.
* The response includes `is_duplicate: true` to flag the idempotent match.

> **Tip**
>
> Idempotency keys make it safe to retry a mint submission after a network failure or timeout,
> without any risk of issuing a second batch.

## Background continuation

Large jobs are designed to complete without user intervention:

* The background worker picks up queued and in progress jobs.
* Jobs are processed oldest first.
* A soft lock ensures only one worker processes a given job at a time, preventing duplicate units.

## Token lifecycle

| State       | Description                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------- |
| **minted**  | The token exists and the passport is not yet live, awaiting manual activation by the brand. |
| **active**  | The token is live and resolving. Tokens activated at mint enter this state immediately.     |
| **revoked** | The token has been permanently deactivated.                                                 |

Activation has two modes chosen on the mint request. **Activated at mint** makes the passport live the moment it is issued. **Manual activation** issues the token inactive so the brand can make it live later, for example when the unit is packed, shipped or sold.

## Related Docs

* [Minting Overview](/minting/overview)
* [Minting Architecture](/minting/architecture)
* [Minting Security](/minting/security)
* [Exports and Print Jobs](/minting/exports-print-jobs)