Billing
Products & Prices
Model your catalog with products, then attach one-time or recurring prices to power checkout and subscriptions.
Overview
A product represents what you sell — a plan, service, or good. A price defines how much and how often you charge for it. One product can have multiple prices (e.g., monthly and yearly), and subscriptions reference a priceId when billing customers.
Products
What you sell — plans, services, goods
Prices
One-time or recurring, per product
Subscriptions
Bill a customer on a price
Create a product
Create a product first, then attach prices to it. The API returns the new product with status active and dispatches a product.created webhook.
curl https://paymenthooks.com/api/v1/products \
-X POST \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Pro Plan",
"description": "Full access to the Pro feature set",
"type": "service",
"metadata": { "tier": "pro" }
}'Required field: name. Optional: description, type, status (defaults to active), images, and arbitrary metadata. Returns 201 on success, 400 if name is missing, or 500 on a server error.
Create a price
Attach a price to a product. Use type: "one_time" for single charges or type: "recurring" with an interval for subscriptions. The API dispatches a price.created webhook.
curl https://paymenthooks.com/api/v1/prices \
-X POST \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"productId": "prod_abc123",
"amount": 2900,
"currency": "USD",
"type": "recurring",
"interval": "month",
"trialDays": 14
}'Required fields: productId, amount (integer, in the smallest unit of currency — e.g., cents or paise), and currency. Optional: type, interval (day | week | month | year), intervalCount, trialDays, nickname, isDefault, and metadata. Returns 201 on success or 400 if required fields are missing.
Product endpoints
Complete payload and response for every product endpoint. Click copy on any block.
/v1/productsCreate a product{
"name": "Pro Plan",
"description": "Full access to the Pro feature set",
"type": "service",
"status": "active",
"metadata": { "tier": "pro" }
}{
"data": {
"id": "prod_abc123",
"merchantId": "mer_abc123",
"name": "Pro Plan",
"description": "Full access to the Pro feature set",
"type": "service",
"status": "active",
"prices": [],
"metadata": { "tier": "pro" },
"createdAt": "2026-05-01T00:00:00.000Z",
"updatedAt": "2026-05-01T00:00:00.000Z"
},
"error": null
}/v1/products?page=1&pageSize=10&status=activeList products{
"data": [
{
"id": "prod_abc123",
"name": "Pro Plan",
"type": "service",
"status": "active",
"pricesCount": 2,
"metadata": { "tier": "pro" },
"createdAt": "2026-05-01T00:00:00.000Z"
}
],
"meta": { "total": 8, "page": 1, "pageSize": 10 },
"error": null
}/v1/products/:idRetrieve a product{
"data": {
"id": "prod_abc123",
"merchantId": "mer_abc123",
"name": "Pro Plan",
"description": "Full access to the Pro feature set",
"type": "service",
"status": "active",
"prices": [
{ "id": "price_monthly_pro", "amount": 2900, "currency": "USD", "type": "recurring", "interval": "month" }
],
"metadata": { "tier": "pro" },
"createdAt": "2026-05-01T00:00:00.000Z",
"updatedAt": "2026-05-01T00:00:00.000Z"
},
"error": null
}/v1/products/:idUpdate a product{
"name": "Pro Plan (2026)",
"status": "active",
"metadata": { "tier": "pro", "year": "2026" }
}{
"data": {
"id": "prod_abc123",
"name": "Pro Plan (2026)",
"status": "active",
"metadata": { "tier": "pro", "year": "2026" },
"updatedAt": "2026-05-16T10:30:00.000Z"
},
"error": null
}/v1/products/:idDelete a product{
"data": null,
"error": null
}Price endpoints
Complete payload and response for every price endpoint.
/v1/pricesCreate a price{
"productId": "prod_abc123",
"amount": 2900,
"currency": "USD",
"type": "recurring",
"interval": "month",
"intervalCount": 1,
"trialDays": 14,
"nickname": "Monthly Pro",
"metadata": { "plan": "pro" }
}{
"data": {
"id": "price_monthly_pro",
"productId": "prod_abc123",
"amount": 2900,
"currency": "USD",
"originalAmount": 2900,
"originalCurrency": "USD",
"type": "recurring",
"interval": "month",
"intervalCount": 1,
"trialDays": 14,
"nickname": "Monthly Pro",
"billingScheme": "per_unit",
"isDefault": false,
"status": "active",
"metadata": { "plan": "pro" },
"createdAt": "2026-05-01T00:00:00.000Z"
},
"error": null
}/v1/prices?productId=prod_abc123&status=activeList prices (filter by product){
"data": [
{
"id": "price_monthly_pro",
"productId": "prod_abc123",
"amount": 2900,
"currency": "USD",
"type": "recurring",
"interval": "month",
"status": "active",
"createdAt": "2026-05-01T00:00:00.000Z"
}
],
"meta": { "total": 2, "page": 1, "pageSize": 25 },
"error": null
}/v1/prices/:idRetrieve a price{
"data": {
"id": "price_monthly_pro",
"productId": "prod_abc123",
"amount": 2900,
"currency": "USD",
"type": "recurring",
"interval": "month",
"intervalCount": 1,
"trialDays": 14,
"billingScheme": "per_unit",
"status": "active",
"metadata": { "plan": "pro" },
"createdAt": "2026-05-01T00:00:00.000Z"
},
"error": null
}/v1/prices/:idUpdate a price{
"nickname": "Monthly Pro (legacy)",
"status": "archived",
"metadata": { "plan": "pro", "deprecated": "true" }
}{
"data": {
"id": "price_monthly_pro",
"productId": "prod_abc123",
"nickname": "Monthly Pro (legacy)",
"status": "archived",
"metadata": { "plan": "pro", "deprecated": "true" },
"updatedAt": "2026-05-16T10:30:00.000Z"
},
"error": null
}/v1/prices/:idDelete a price{
"data": null,
"error": null
}Currency handling
Send amount in the smallest unit of the currency you price in (e.g., 39900 paise for INR 399.00). PaymentHooks converts it to USD cents at the live exchange rate for storage and gateway routing, and keeps your original amount and currency on the price as originalAmount / originalCurrency for display.