API: Batches

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

1
{
2
  "_brand_id": "uuid",
3
  "_product_id": "uuid",
4
  "_batch_number": "BATCH-2026-001",
5
  "_production_date": "2026-01-15",
6
  "_quantity": 500,
7
  "_facility_ref": "FAC-EU-01",
8
  "_attributes": {}
9
}

Response

1
{
2
  "id": "uuid",
3
  "product_id": "uuid",
4
  "batch_number": "BATCH-2026-001",
5
  "status": "active",
6
  "production_date": "2026-01-15",
7
  "quantity": 500,
8
  "facility_ref": "FAC-EU-01",
9
  "created_at": "2026-01-15T12:00:00Z"
10
}

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

1
{
2
  "_brand_id": "uuid",
3
  "_product_id": "uuid"
4
}

Response

1
[
2
  {
3
    "id": "uuid",
4
    "batch_number": "BATCH-2026-001",
5
    "status": "active",
6
    "production_date": "2026-01-15",
7
    "quantity": 500,
8
    "facility_ref": "FAC-EU-01",
9
    "attributes": {},
10
    "created_at": "2026-01-15T12:00:00Z",
11
    "updated_at": "2026-01-15T12:00:00Z"
12
  }
13
]

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

1
{
2
  "_brand_id": "uuid",
3
  "_batch_id": "uuid",
4
  "_patch": {
5
    "quantity": 600,
6
    "facility_ref": "FAC-EU-02"
7
  }
8
}

Response

1
{
2
  "id": "uuid",
3
  "batch_number": "BATCH-2026-001",
4
  "status": "active",
5
  "quantity": 600,
6
  "facility_ref": "FAC-EU-02",
7
  "updated_at": "2026-01-15T13:00:00Z"
8
}

Errors

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