Products & Prices

Public API v1 · Catalog for one-time and recurring billing

Summary

Products describe what you sell. Prices attach an amount (and optional recurring cadence) to a product. Subscriptions reference a price id — amounts live on prices, not products.

💡

Typical flow: create a product → create one or more prices on that product → create a subscription with a price (and customer / payment method). See Recurring Payments.

Authentication

Server-to-server. Authenticate with a RapidCents rc_sk_ secret key.

Authorization: Bearer {rc_sk_secret_key}
Content-Type: application/json
Accept: application/json

Base URL patterns: /api/v1/products and /api/v1/prices. Business is resolved from the secret key. Currency on prices comes from the authenticated business and is not accepted in the request body.

Catalog Model

Product — name, description, active flag, metadata. Nested prices are returned when loaded.
Price — belongs to a product; unit_amount in the smallest currency unit (e.g. cents); optional recurring for subscriptions; omit recurring for a one-time price.
Immutability — after create, unit_amount, currency, and recurring cadence cannot change. Update only nickname, active, and metadata.

Product Object

Response shape

{
  "id": "product-uuid",
  "object": "product",
  "name": "Pro Plan",
  "description": "Monthly subscription",
  "active": true,
  "prices": [ { /* price objects */ } ],
  "metadata": {},
  "created": 1710000000
}

Create Product

POST /api/v1/products

Request Body

Field	Type	Required	Description
`name`	string	Yes	Product name (max 255)
`description`	string	No	Longer description (max 2000)
`active`	boolean	No	Default `true`
`metadata`	object	No	Arbitrary key/value metadata

Request

POST /api/v1/products
Authorization: Bearer {rc_sk_...}

{
  "name": "Pro Plan",
  "description": "Monthly subscription"
}

Response — 201 Created

{
  "id": "product-uuid",
  "object": "product",
  "name": "Pro Plan",
  "description": "Monthly subscription",
  "active": true,
  "prices": [],
  "metadata": {},
  "created": 1710000000
}

List Products

GET /api/v1/products

Query Parameters

Param	Type	Description
`active`	boolean	Filter by active state
`limit`	integer	Page size (1–100, default 10)
`starting_after`	string	Cursor: return records after this id
`ending_before`	string	Cursor: return records before this id

Response — 200 OK

{
  "object": "list",
  "data": [ { /* product with prices */ } ],
  "has_more": false
}

Get Product

GET /api/v1/products/{product}

Returns the product and its related prices.

Update Product

PATCH /api/v1/products/{product}

Request Body

Field	Type	Required	Description
`name`	string	No	Update name
`description`	string \| null	No	Update description
`active`	boolean	No	Archive or reactivate
`metadata`	object \| null	No	Replace metadata

Request

PATCH /api/v1/products/{product}

{
  "name": "Pro Plan Updated",
  "description": "Updated description",
  "active": true
}

Price Object

Response shape

{
  "id": "price-uuid",
  "object": "price",
  "product": "product-uuid",
  "unit_amount": 2999,
  "currency": "usd",
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "nickname": "Pro monthly",
  "active": true,
  "metadata": {},
  "created": 1710000000
}

When recurring is omitted at create time, the response recurring field is null (one-time price).

Create Price

POST /api/v1/prices

Request Body

Field	Type	Required	Description
`product`	string (UUID)	Yes	Product this price belongs to
`unit_amount`	integer	Yes	Amount in smallest currency unit (min 1)
`recurring`	object	No	Billing cadence for subscriptions; omit for one-time
`recurring.interval`	string	With recurring	`day`, `week`, `month`, or `year`
`recurring.interval_count`	integer	No	Default `1`; must be a supported cadence
`nickname`	string	No	Display label (max 255)
`active`	boolean	No	Default `true`
`metadata`	object	No	Arbitrary key/value metadata

Request — recurring monthly

POST /api/v1/prices
Authorization: Bearer {rc_sk_...}

{
  "product": "product-uuid",
  "unit_amount": 2999,
  "recurring": {
    "interval": "month",
    "interval_count": 1
  }
}

Response — 201 Created

{
  "id": "price-uuid",
  "object": "price",
  "product": "product-uuid",
  "unit_amount": 2999,
  "currency": "usd",
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "nickname": null,
  "active": true,
  "metadata": {},
  "created": 1710000000
}

Supported Recurring Cadences

Only these interval + interval_count pairs map to RapidCents billing sequences and are accepted:

interval	interval_count	Billing
`day`	`1`	Daily
`week`	`1`	Weekly
`week`	`2`	Bi-weekly
`month`	`1`	Monthly
`month`	`3`	Quarterly
`month`	`6`	Twice a year
`year`	`1`	Annually

⚠

Other combinations (for example month + 2) are rejected with a validation error on recurring.interval_count.

List Prices

GET /api/v1/prices

Query Parameters

Param	Type	Description
`product`	string	Filter to prices for this product id
`active`	boolean	Filter by active state
`limit`	integer	Page size (1–100, default 10)
`starting_after`	string	Cursor: return records after this id
`ending_before`	string	Cursor: return records before this id

Example

GET /api/v1/prices?product={product_id}&limit=10

Get Price

GET /api/v1/prices/{price}

Update Price

PATCH /api/v1/prices/{price}

Only presentation and state fields may change. You cannot change unit_amount, currency, or recurring after creation — create a new price instead.

Request Body

Field	Type	Required	Description
`nickname`	string \| null	No	Display label
`active`	boolean	No	Archive or reactivate
`metadata`	object \| null	No	Replace metadata

Request

PATCH /api/v1/prices/{price}

{
  "nickname": "Pro monthly",
  "active": true
}

All Endpoints

Products

Method	Endpoint	Description
POST	`/api/v1/products`	Create product
GET	`/api/v1/products`	List products
GET	`/api/v1/products/{id}`	Get product
PATCH	`/api/v1/products/{id}`	Update product

Prices

Method	Endpoint	Description
POST	`/api/v1/prices`	Create price
GET	`/api/v1/prices`	List prices
GET	`/api/v1/prices/{id}`	Get price
PATCH	`/api/v1/prices/{id}`	Update nickname / active / metadata

Error Handling

HTTP Code	Scenario	Description
`422`	Validation error	Missing required fields or unsupported recurring cadence
`404`	Not found	Product or price does not exist for this business
`401`	Unauthorized	Missing or invalid secret key

Products & Prices

Summary

Authentication

Catalog Model

Product Object

Create Product

Request Body

List Products

Query Parameters

Get Product

Update Product

Request Body

Price Object

Create Price

Request Body

Supported Recurring Cadences

List Prices

Query Parameters

Get Price

Update Price

Request Body

All Endpoints

Products

Prices

Error Handling

Related Docs