Items

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 and fees, which tag an item through itemId.

Creating an item

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:

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:

PATCH /v0/items/{id}
{
  "archived": true
}

The response reflects the retirement timestamp:

{
  "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:

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.

Getting Started

Authentication

Platform

Integrations

Legal

What’s an item?

Creating an item

Tagging metrics and fees with an item

Archiving items

​What’s an item?

​Creating an item

​Tagging metrics and fees with an item

​Archiving items

What’s an item?

Creating an item

Tagging metrics and fees with an item

Archiving items