Products tools

• products_archive: Archive a product
• products_create: Create a product
• products_get: Get a product
• products_list: List products
• products_pricing_table: Get the pricing table
• products_update: Update a product

products_archive#

Archive a product. Operation products.archive · Brand level · permission catalog:write · risk tier write · since M4

Archives a product: it leaves the pricing table, can't be sold and can't get new prices. Existing subscriptions, invoices and the product's prices stay as they are. Archiving an archived product changes nothing. Reactivate it with products.update and active: true.

reason is recorded in the audit log.

Annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: true · openWorldHint: false

Arguments#

• Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
• Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
• Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors#

• resource_not_found: No product with this ID is visible to the request.
• version_conflict: The product changed at the same time; retry.
• permission_denied: You can't change this brand's catalog.

Example#

Retire a plan

Arguments:

{
  "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "reason": "Replaced by the 2027 plans",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

{
  "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "object": "product",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "name": "Pro",
  "description": "For growing teams.",
  "taxCategoryId": "saas",
  "kind": "plan",
  "entitlements": [
    {
      "featureKey": "seats.max",
      "value": 10
    },
    {
      "featureKey": "feature.export",
      "value": true
    }
  ],
  "lifetimeEntitlements": false,
  "displayOrder": 2,
  "highlighted": true,
  "active": false,
  "images": [],
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

products_create#

Create a product. Operation products.create · Brand level · permission catalog:write · risk tier write · since M4

Creates a product in the brand's catalog, in the request's mode (test and live mode have separate catalogs).

taxCategoryId is required: it decides which tax rates apply to the product in every jurisdiction (for example saas, ebook or electronically_supplied_service). Products of kind: plan appear on the brand's public pricing table. entitlements grant values of the brand's features (features.create), such as seats.max = 10; each value must fit its feature's type. Subscriptions grant them while they're active; with lifetimeEntitlements: true, a one-time purchase grants them for good.

Add prices with prices.create. Images are https URLs.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Arguments#

• Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
• Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
• Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors#

• org_restricted: Live mode, while the organization's Ownrecord subscription is unpaid (§37.5).
• validation_failed: A field is missing or malformed, e.g. an unknown tax category.
• feature_not_found: An entitlement names a feature the brand doesn't have in this mode.
• entitlement_value_invalid: An entitlement value doesn't fit its feature's type.
• permission_denied: You can't change this brand's catalog.

Example#

A plan with seats and export

Arguments:

{
  "name": "Pro",
  "description": "For growing teams.",
  "taxCategoryId": "saas",
  "kind": "plan",
  "entitlements": [
    {
      "featureKey": "seats.max",
      "value": 10
    },
    {
      "featureKey": "feature.export",
      "value": true
    }
  ],
  "displayOrder": 2,
  "highlighted": true,
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

{
  "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "object": "product",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "name": "Pro",
  "description": "For growing teams.",
  "taxCategoryId": "saas",
  "kind": "plan",
  "entitlements": [
    {
      "featureKey": "seats.max",
      "value": 10
    },
    {
      "featureKey": "feature.export",
      "value": true
    }
  ],
  "lifetimeEntitlements": false,
  "displayOrder": 2,
  "highlighted": true,
  "active": true,
  "images": [],
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}

products_get#

Get a product. Operation products.get · Brand level · permission catalog:read · risk tier read · since M4

Returns one product of the brand's catalog in the request's mode, archived or not: its kind, whether it is active, its entitlements and its pricing-table hints (displayOrder, highlighted). The brand's pricing table shows its active products of kind plan.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments#

• Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
• Read-only: changes nothing; idempotency_key is ignored.

Errors#

• resource_not_found: No product with this ID is visible to the request.
• permission_denied: You can't see this brand's catalog.

Example#

A plan

Arguments:

{
  "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}

Result output:

{
  "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "object": "product",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "name": "Pro",
  "description": "For growing teams.",
  "taxCategoryId": "saas",
  "kind": "plan",
  "entitlements": [
    {
      "featureKey": "seats.max",
      "value": 10
    },
    {
      "featureKey": "feature.export",
      "value": true
    }
  ],
  "lifetimeEntitlements": false,
  "displayOrder": 2,
  "highlighted": true,
  "active": true,
  "images": [],
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}

products_list#

List products. Operation products.list · Brand level · permission catalog:read · risk tier read · since M4

Lists the brand's products in the request's mode, newest first. Filter with active (true or false) and kind (plan or standard).

Paginate with limit (1–100, default 10) and starting_after (the next_cursor of the previous page).

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments#

• Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
• Read-only: changes nothing; idempotency_key is ignored.

Errors#

• validation_failed: A filter or pagination value is malformed.
• permission_denied: You can't see this brand's catalog.

Example#

Active plans

Arguments:

{
  "active": "true",
  "kind": "plan",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}

Result output:

{
  "object": "list",
  "data": [
    {
      "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
      "object": "product",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "name": "Pro",
      "description": "For growing teams.",
      "taxCategoryId": "saas",
      "kind": "plan",
      "entitlements": [
        {
          "featureKey": "seats.max",
          "value": 10
        },
        {
          "featureKey": "feature.export",
          "value": true
        }
      ],
      "lifetimeEntitlements": false,
      "displayOrder": 2,
      "highlighted": true,
      "active": true,
      "images": [],
      "metadata": {},
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

products_pricing_table#

Get the pricing table. Operation products.pricing_table · Brand level · permission catalog:read · risk tier read · since M4

Returns the brand's pricing table: its active products of kind: plan, in display order, with their active prices and the features each plan grants (by name). Use it to render plans on your own site; it needs no API key and is rate-limited per IP address.

Only what customers may see is included: no nicknames, metadata or internal fields. Archived products and prices are left out.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments#

• Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
• Read-only: changes nothing; idempotency_key is ignored.

Errors#

• resource_not_found: No brand with this slug is visible to the request.

Example#

Acme App's plans

Arguments:

{
  "brandSlug": "acme-app",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}

Result output:

{
  "object": "pricing_table",
  "brand": {
    "id": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
    "slug": "acme-app",
    "name": "Acme App"
  },
  "livemode": true,
  "products": [
    {
      "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
      "name": "Pro",
      "description": "For growing teams.",
      "images": [],
      "highlighted": true,
      "displayOrder": 2,
      "features": [
        {
          "key": "seats.max",
          "name": "Seats",
          "type": "limit",
          "value": 10
        },
        {
          "key": "feature.export",
          "name": "Export",
          "type": "boolean",
          "value": true
        }
      ],
      "prices": [
        {
          "id": "price_01m4tx5nj8emwbyf7y9vcf47y2",
          "lookupKey": "pro_monthly",
          "type": "recurring",
          "currency": "EUR",
          "taxBehavior": "inclusive",
          "amount": null,
          "customAmount": null,
          "creditPack": null,
          "recurring": {
            "interval": "month",
            "intervalCount": 1,
            "usageType": "licensed",
            "billingScheme": "tiered",
            "unitAmount": null,
            "tiersMode": "graduated",
            "tiers": [
              {
                "upTo": 10,
                "unitAmountMicros": "12000000",
                "flatAmount": null
              },
              {
                "upTo": "inf",
                "unitAmountMicros": "9000000",
                "flatAmount": null
              }
            ],
            "trialDays": 14,
            "includedCredits": null,
            "metered": null
          }
        }
      ]
    }
  ]
}

products_update#

Update a product. Operation products.update · Brand level · permission catalog:write · risk tier write · since M4

Changes a product's name, description, tax category, kind, entitlements, lifetimeEntitlements, pricing-table hints, images or metadata. Send only the fields to change; null clears an optional value. entitlements, images and metadata replace the whole list or map. Customers' entitlements are recomputed after a change of entitlements or lifetimeEntitlements.

A new tax category applies to future sales; issued invoices keep theirs. active: false archives the product (as products.archive) and active: true reactivates it.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments#

• Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
• Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
• Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors#

• validation_failed: No field to change was sent, or one is malformed.
• feature_not_found: An entitlement names a feature the brand doesn't have in this mode.
• entitlement_value_invalid: An entitlement value doesn't fit its feature's type.
• resource_not_found: No product with this ID is visible to the request.
• version_conflict: The product changed at the same time; retry.
• permission_denied: You can't change this brand's catalog.

Example#

Raise the seat limit

Arguments:

{
  "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "entitlements": [
    {
      "featureKey": "seats.max",
      "value": 25
    },
    {
      "featureKey": "feature.export",
      "value": true
    }
  ],
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

{
  "id": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
  "object": "product",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "name": "Pro",
  "description": "For growing teams.",
  "taxCategoryId": "saas",
  "kind": "plan",
  "entitlements": [
    {
      "featureKey": "seats.max",
      "value": 25
    },
    {
      "featureKey": "feature.export",
      "value": true
    }
  ],
  "lifetimeEntitlements": false,
  "displayOrder": 2,
  "highlighted": true,
  "active": true,
  "images": [],
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}