Catalog
Create the products you sell and the prices your customers subscribe to.
The catalog has two levels:
- a product describes what you sell, for example "Gym, unlimited access";
- a price (the
priceobject) sets a product's amount, currency, and billing interval. A product can have several prices: monthly, quarterly, yearly with a trial, and so on.
A subscription is always created on a price, never directly on a product.
Find an ID
In the dashboard, the Subscriptions → Catalog page shows the product_id and price_id of every product and price, with a copy button.
Endpoints
GET /api/v1/productsPOST /api/v1/productsPATCH /api/v1/products/{id}GET /api/v1/pricesPOST /api/v1/pricesPOST /api/v1/prices/{id}/archive
The catalog emits no webhooks. There is no route to retrieve a single product, and no deletion: deactivate a product or archive a price instead.
Products
Create a product
POST /api/v1/products| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Product name, 255 characters at most |
| description | string | No | 5,000 characters at most |
| active | boolean | No | true by default |
| metadata | object | No | Free-form data, returned as is |
curl -X POST "https://api-pay.genuka.com/api/v1/products" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Idempotency-Key: product-gym-unlimited" \
-H "Content-Type: application/json" \
-d '{
"name": "Gym, unlimited access",
"description": "7 days a week",
"metadata": { "sku": "GYM-1" }
}'Response 201:
{
"data": {
"id": "01k79y7a2b4c6d8e0f2g4h6j8k",
"object": "product",
"name": "Gym, unlimited access",
"description": "7 days a week",
"active": true,
"metadata": { "sku": "GYM-1" },
"created_at": "2026-10-01T07:00:00.000000Z"
}
}Update a product
PATCH /api/v1/products/{id}Send only the fields you want to change: name, description, active, metadata. null clears description or metadata. metadata is replaced, not merged.
Deactivating a product ("active": false) blocks any new subscription on its prices. Existing subscriptions keep being billed.
List products
GET /api/v1/products| Parameter | Description |
|---|---|
| filter[active] | true or false |
| include | prices to include each product's prices, archived ones included |
| sort | created_at or name, prefix with - for descending order. -created_at by default. |
| page, per_page | Pagination, see the overview |
The prices key appears in the response only with include=prices.
Prices
Create a price
POST /api/v1/prices| Parameter | Type | Required | Description |
|---|---|---|---|
| product_id | string | Yes | Product from the same application |
| amount | integer | Yes | Amount per period, in the minor unit. In XAF and XOF, 15000 means 15,000 FCFA. |
| currency | string | Yes | XAF or XOF |
| interval | string | Yes | week, month, quarter, or year |
| interval_count | integer | No | Number of intervals per period, from 1 to 100. 1 by default. "interval": "month", "interval_count": 3 bills every 3 months. |
| cycles | integer | No | Number of paid periods before the subscription ends, from 1 to 1,000. Empty: no end, the subscription runs until it is cancelled. |
| trial_days | integer | No | Free trial days, from 0 to 365. 0 by default. |
| grace_days | integer | No | Days during which access is kept after an unpaid due date. 7 by default. See below for the limit. |
| renewal_rule | string | No | fixed_anchor (default) or from_payment. See the renewal rule. |
| nickname | string | No | Price name, for example "Monthly" |
| metadata | object | No | Free-form data |
Grace period limit. grace_days cannot exceed one period of the price, nor 365 days. A period counts as 7 days for week, 30 for month, 90 for quarter, and 365 for year, multiplied by interval_count.
| Price | Maximum grace_days |
|---|---|
| Weekly | 7 |
| Monthly | 30 |
| Quarterly | 90 |
| Yearly | 365 |
curl -X POST "https://api-pay.genuka.com/api/v1/prices" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Idempotency-Key: price-gym-yearly" \
-H "Content-Type: application/json" \
-d '{
"product_id": "01k79y7a2b4c6d8e0f2g4h6j8k",
"nickname": "Yearly",
"amount": 100000,
"currency": "XAF",
"interval": "year",
"trial_days": 7,
"grace_days": 30
}'Response 201:
{
"data": {
"id": "01k79y8m0n2p4q6r8s0t2v4w6x",
"object": "price",
"product_id": "01k79y7a2b4c6d8e0f2g4h6j8k",
"nickname": "Yearly",
"amount": 100000,
"currency": "XAF",
"interval": "year",
"interval_count": 1,
"cycles": null,
"trial_days": 7,
"grace_days": 30,
"renewal_rule": "fixed_anchor",
"archived": false,
"metadata": null,
"created_at": "2026-10-01T07:00:00.000000Z"
}
}A price cannot be changed
A price's amount, currency, and billing interval are fixed when it is created: there is no update route. To change your pricing, archive the price and create a new one. Existing subscriptions stay on the old price.
Archive a price
POST /api/v1/prices/{id}/archiveNo request body. An archived price ("archived": true) no longer accepts new subscriptions; existing ones keep being billed at its amount. Archiving it again changes nothing. A price cannot be unarchived.
List prices
GET /api/v1/prices| Parameter | Description |
|---|---|
| filter[product_id] | Prices of one or more products, separated by commas |
| filter[archived] | true: archived prices only. false: active prices only. Omitted: both. |
| sort | created_at or amount, prefix with - for descending order. -created_at by default. |
| page, per_page | Pagination |
Renewal rule
renewal_rule decides when the new period starts when the customer pays late. Example with a monthly price, a current period from October 10 to November 10, and the next due date on November 10:
| Rule | Payment on November 15 | Next due date |
|---|---|---|
fixed_anchor | The period stays November 10 to December 10: the days of delay are lost. | December 10 |
from_payment | The period becomes November 15 to December 15, and the due day moves to the 15th. | December 15 |
An early payment never moves the period. fixed_anchor suits schools and software, from_payment suits gyms and services used from the moment they are paid for.
For monthly, quarterly, and yearly prices, the due day is kept from one month to the next and moved to the last day of shorter months: January 31, February 28 or 29, March 31.
Errors
| HTTP status | Cause |
|---|---|
404 | Product or price unknown, from another business, or from the other environment |
422 | Invalid field: unknown product, zero or decimal amount, unsupported currency, unknown interval, grace_days beyond one period, and so on |
400 | Filter, sort, or include not allowed |
How is this guide?
Last updated on