> 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.

# API: Batches

> Manage production batches programmatically, covering creation, status transitions, quantity rules and how batches link to minting requests and units.

> **Programmatic access — early access**
>
> The
>
> **tie*back***
>
> API is available to selected workspaces during early access. Endpoints in production today are
> authenticated with an authenticated session. Standalone API-key access is being onboarded per
> workspace. Contact
>
> **tie*back***
>
> to enable API credentials for your workspace.

## What It Does

The Batches API lets you create and manage production batches for products. Each batch represents a specific production run and can be independently tracked, updated, and used as the scope for minting a Digital Product Passport.

## Authentication & Permissions

All RPCs require an authenticated session. Mutations require a role with sufficient permissions for the target brand.

## RPCs

### create\_product\_batch

Creates a new production batch for a product.

**Request**

```json
{
  "_brand_id": "uuid",
  "_product_id": "uuid",
  "_batch_number": "BATCH-2026-001",
  "_production_date": "2026-01-15",
  "_quantity": 500,
  "_facility_ref": "FAC-EU-01",
  "_attributes": {}
}
```

**Response**

```json
{
  "id": "uuid",
  "product_id": "uuid",
  "batch_number": "BATCH-2026-001",
  "status": "active",
  "production_date": "2026-01-15",
  "quantity": 500,
  "facility_ref": "FAC-EU-01",
  "created_at": "2026-01-15T12:00:00Z"
}
```

**Errors**

* Not authenticated, request has no valid JWT.
* Forbidden, caller does not have sufficient access.
* Invalid input, request is malformed or cannot be processed.

**Notes**

* `_production_date`, `_quantity`, `_facility_ref`, and `_attributes` are optional.
* `_batch_number` must be unique within the product.

---

### list\_product\_batches

Returns all batches for a given product.

**Request**

```json
{
  "_brand_id": "uuid",
  "_product_id": "uuid"
}
```

**Response**

```json
[
  {
    "id": "uuid",
    "batch_number": "BATCH-2026-001",
    "status": "active",
    "production_date": "2026-01-15",
    "quantity": 500,
    "facility_ref": "FAC-EU-01",
    "attributes": {},
    "created_at": "2026-01-15T12:00:00Z",
    "updated_at": "2026-01-15T12:00:00Z"
  }
]
```

**Errors**

* Not authenticated, request has no valid JWT.
* Forbidden, caller does not have sufficient access.
* Invalid input, request is malformed or cannot be processed.

---

### update\_product\_batch

Updates an existing batch's metadata.

**Request**

```json
{
  "_brand_id": "uuid",
  "_batch_id": "uuid",
  "_patch": {
    "quantity": 600,
    "facility_ref": "FAC-EU-02"
  }
}
```

**Response**

```json
{
  "id": "uuid",
  "batch_number": "BATCH-2026-001",
  "status": "active",
  "quantity": 600,
  "facility_ref": "FAC-EU-02",
  "updated_at": "2026-01-15T13:00:00Z"
}
```

**Errors**

* Not authenticated, request has no valid JWT.
* Forbidden, caller does not have sufficient access.
* Invalid input, request is malformed or cannot be processed.

## Related Docs

* [API: Products](/api-reference/api-products)
* [Minting Overview](/minting/overview)
* [API: Minting](/api-reference/api-minting)
* [API: Credentials](/api-reference/api-credentials)