Logo GenukaGenuka Pay
API ReferenceSubscriptions

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 price object) 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/products
  • POST /api/v1/products
  • PATCH /api/v1/products/{id}
  • GET /api/v1/prices
  • POST /api/v1/prices
  • POST /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
ParameterTypeRequiredDescription
namestringYesProduct name, 255 characters at most
descriptionstringNo5,000 characters at most
activebooleanNotrue by default
metadataobjectNoFree-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
ParameterDescription
filter[active]true or false
includeprices to include each product's prices, archived ones included
sortcreated_at or name, prefix with - for descending order. -created_at by default.
page, per_pagePagination, see the overview

The prices key appears in the response only with include=prices.

Prices

Create a price

POST /api/v1/prices
ParameterTypeRequiredDescription
product_idstringYesProduct from the same application
amountintegerYesAmount per period, in the minor unit. In XAF and XOF, 15000 means 15,000 FCFA.
currencystringYesXAF or XOF
intervalstringYesweek, month, quarter, or year
interval_countintegerNoNumber of intervals per period, from 1 to 100. 1 by default. "interval": "month", "interval_count": 3 bills every 3 months.
cyclesintegerNoNumber of paid periods before the subscription ends, from 1 to 1,000. Empty: no end, the subscription runs until it is cancelled.
trial_daysintegerNoFree trial days, from 0 to 365. 0 by default.
grace_daysintegerNoDays during which access is kept after an unpaid due date. 7 by default. See below for the limit.
renewal_rulestringNofixed_anchor (default) or from_payment. See the renewal rule.
nicknamestringNoPrice name, for example "Monthly"
metadataobjectNoFree-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.

PriceMaximum grace_days
Weekly7
Monthly30
Quarterly90
Yearly365
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}/archive

No 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
ParameterDescription
filter[product_id]Prices of one or more products, separated by commas
filter[archived]true: archived prices only. false: active prices only. Omitted: both.
sortcreated_at or amount, prefix with - for descending order. -created_at by default.
page, per_pagePagination

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:

RulePayment on November 15Next due date
fixed_anchorThe period stays November 10 to December 10: the days of delay are lost.December 10
from_paymentThe 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 statusCause
404Product or price unknown, from another business, or from the other environment
422Invalid field: unknown product, zero or decimal amount, unsupported currency, unknown interval, grace_days beyond one period, and so on
400Filter, sort, or include not allowed

How is this guide?

Last updated on