> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Items

> Optional SKU tags that map your charges to external accounting systems

An item is a name for something you sell — "Neural Network Training -
Standard Seat," for example. You tag your billable metrics and fees with an
item so that every invoice line they produce can be translated into the SKU,
GL, or tax code your accounting system expects.

## What's an item?

Items are **optional**. Nothing requires one: a billable metric or fee filed
directly into a product bills exactly as it always has. Paygentic doesn't
create items for you — you create them when you have something to map.

Items are also deliberately thin. An item has:

* A **name** - the canonical, customer-facing SKU name
* A **catalog ID** - the product it belongs to, if you've filed it into one
* **Metadata** - optional key-value pairs for internal tracking
* **External references** - links to your CRM, ERP, or tax provider

An item never carries a price, currency, plan, or metering configuration.
Those live on [billable metrics](/platform/pricing/billable-metrics) and
[fees](/platform/pricing/fees), which tag an item through `itemId`.

## Creating an item

```json theme={null}
POST /v0/items
{
  "merchantId": "org_abc123",
  "name": "Neural Network Training - Standard Seat",
  "catalogId": "prod_xyz789"
}
```

`catalogId` is optional at creation time — you can file an item into a
product later by updating it, and you can move a filed item to a different
product at any time. Re-filing carries the item's tagged billable metrics
and fees to the new product with it, in one transaction.

You cannot, however, un-file an item (set `catalogId` back to `null`) while
billable metrics or fees are still tagged with it — untag them first.

## Tagging metrics and fees with an item

Billable metrics and fees accept an `itemId` that points at the item they
bill for:

```json theme={null}
POST /v0/billableMetrics
{
  "merchantId": "org_abc123",
  "name": "Tokens processed",
  "description": "Tokens processed by the model",
  "unit": "token",
  "aggregation": "sum",
  "itemId": "itm_abc123"
}
```

Supply either `productId` or `itemId` — at least one is required. Set
`itemId` and the product is resolved from the item's `catalogId` for you; set
`productId` and the metric or fee is filed directly, with no item tag. If you
pass both, they must resolve to the same product. `productId` is always
populated on the response either way.

## Archiving items

Archiving retires an item from your catalog so it can no longer be attached
to new pricing, while keeping it readable so historical invoices and line
items still resolve to it.

|                                   | Archived | Deleted |
| --------------------------------- | -------- | ------- |
| Visible in default list results   | No       | No      |
| Readable directly by ID           | Yes      | No      |
| Can be tagged by new metrics/fees | No       | No      |
| Restorable                        | Yes      | No      |

To archive an item, set `archived: true` on an update:

```json theme={null}
PATCH /v0/items/{id}
{
  "archived": true
}
```

The response reflects the retirement timestamp:

```json theme={null}
{
  "id": "itm_abc123",
  "object": "item",
  "archivedAt": "2026-07-25T00:00:00.000Z",
  "...": "..."
}
```

To restore an archived item, set `archived: false`.

By default, a `GET /v0/items` list omits archived items. Pass
`includeArchived=true` to include them:

```bash theme={null}
curl "https://api.paygentic.io/v0/items?merchantId=org_abc123&includeArchived=true"
```

Resolution queries are the exception: a lookup by `provider` and `externalId`
always returns its match, archived or not, so an external code never silently
resolves to nothing.