Products

A product is a record in the object picked as Products in Settings → Payments. Creating or changing one through these endpoints is the same as editing that record: the fields are written through the object’s own mapping, and Custral pushes the price to the workspace’s Stripe account. Prices are in major units (49.5 is $49.50). unitAmount beside them is the same price in minor units, the way Stripe stores it.

Endpoint	Scope	Does
`GET /v1/products`	`billing:read`	Lists the catalog
`GET /v1/products/{product}`	`billing:read`	One product
`POST /v1/products`	`billing:admin`	Creates a product
`PATCH /v1/products/{product}`	`billing:admin`	Changes the named fields
`POST /v1/products/{product}/archive`	`billing:admin`	Takes a product off the catalog

{product} is the product’s id or its exact name. Writes need a key whose creator is a workspace admin. Creating a product charges nobody.

The Product object

{
  "id": "rec_…",
  "name": "Pro seat",
  "description": "One seat on the Pro plan",
  "price": 49,
  "unitAmount": 4900,
  "currency": "usd",
  "interval": "month",
  "usageEvent": null,
  "stripe": "synced",
  "stripeAmount": 4900
}

string

month, year or one_time.

string | null

The usage event a metered product bills by.

string

Whether Stripe has the price the catalog shows: synced, pending (the push hasn’t finished), out_of_sync (Stripe charges a different amount) or unknown (Stripe couldn’t be read).

integer | null

What Stripe charges, in minor units, when it differs or is known.

Create a product

POST /v1/products

const seat = await custral.products.create({
  name: "Pro seat",
  price: 49,
  currency: "usd",
  interval: "month",
});

string

required

Up to 200 characters.

string

Up to 2,000 characters.

number

Per unit, in major units.

string

An ISO code such as usd.

string

month, year or one_time. Matched against the options on your Products object.

string

For a metered product: the usage event it bills by.

Change a product

PATCH /v1/products/{product} takes the same fields, all optional. Omitted fields stay as they are.

await custral.products.update({product: "Pro seat", price: 59});

Stripe prices can’t be edited, so a new price is pushed as a new Stripe price and the old one is deactivated. Existing subscriptions keep the price they were sold until they change plan.

Archive a product

POST /v1/products/{product}/archive takes the product off the catalog and returns {archived: true}. Quotes already made and Stripe subscriptions already running keep what they had.

Errors

Code	When
`products_object_not_mapped`	No Products object is picked in Settings → Payments.
`product_field_not_mapped`	The Products object has no field mapped for one you sent. Map it in Settings → Payments.
`product_option_not_found`	`interval` or `currency` has no matching option on that field. The message lists the options.
`product_not_found`	No product has that id or name.
`product_ambiguous`	More than one product has that name. Use its id.
`insufficient_permissions`	A write, and the key’s creator is not a workspace admin.

See Errors for the HTTP status each code maps to.

Introduction

Endpoints

Embeds & real-time

The Product object

Create a product

Change a product

Archive a product

Errors

​The Product object

​Create a product

​Change a product

​Archive a product

​Errors

The Product object

Create a product

Change a product

Archive a product

Errors