Skip to main content
Use this endpoint to create a payment plan and attach it to a service. A plan defines how your service charges subscribers — whether that is a fixed recurring fee, a usage-based charge, or a one-time payment — along with the amount in USDC and the billing cadence. Once created, a plan can be referenced in checkout sessions to start collecting payments. 
POST https://api.retempo.xyz/api/v1/services/:serviceId/plans

​
Path Parameters

​
serviceId
string
required
The unique identifier of the service you want to attach this plan to. The service must exist; passing an invalid ID returns a 404.

​
Request Body

​
name
string
required
The display name for the plan. This name appears on invoices and in the checkout flow presented to the payer.
​
pricingType
string
required
The pricing model for the plan. Accepted values are:
  • FIXED_RECURRING — charges the subscriber the same amount on every billing cycle (e.g. monthly SaaS).
  • USAGE_BASED — charges based on reported usage events. The amount field represents the per-unit price.
  • ONE_TIME — charges the subscriber once at checkout with no renewal.
​
amount
string | number
required
The charge amount in USDC. You can pass this as a decimal string (e.g. "49.00") or a number (e.g. 49). The value is stored with six decimal places of precision (e.g. "49.000000"). Must be a non-negative value.
​
description
string
A human-readable description of what the plan includes. This appears in checkout sessions and on invoices.
​
billingInterval
string
default:"NONE"
How often the subscriber is billed. Accepted values are MONTH, WEEK, DAY, and NONE. Defaults to NONE if omitted.
  • MONTH — billed once per calendar month.
  • WEEK — billed once per week.
  • DAY — billed daily.
  • NONE — no automatic recurring billing (use with ONE_TIME or USAGE_BASED plans).
​
currency
string
default:"USDC"
The settlement currency for the plan. Defaults to USDC if omitted. Currently only USDC is supported.
For FIXED_RECURRING plans, set billingInterval to MONTH, WEEK, or DAY to enable automatic recurring settlement. Leaving it as NONE on a recurring plan will prevent automatic renewals.

​
Response

A successful request returns HTTP 201 Created with the new plan object. 
{
  "plan": {
    "id": "clz1plan567",
    "serviceId": "clz1abc2def3ghi4",
    "name": "Pro Monthly",
    "description": "Full access, billed monthly",
    "pricingType": "FIXED_RECURRING",
    "billingInterval": "MONTH",
    "amount": "49.000000",
    "currency": "USDC",
    "createdAt": "2025-06-01T10:05:00.000Z",
    "updatedAt": "2025-06-01T10:05:00.000Z"
  }
}
​
plan
object
The newly created payment plan object.

​
Error Responses

StatusMessageCondition
400 Bad Requestname is required.name was omitted.
400 Bad Requestamount is required.amount was omitted.
400 Bad RequestpricingType must be one of: FIXED_RECURRING, USAGE_BASED, ONE_TIME.An invalid pricingType value was provided.
400 Bad RequestbillingInterval must be one of: MONTH, WEEK, DAY, NONE.An invalid billingInterval value was provided.
404 Not FoundReferenced database record was not found.No service exists for the provided serviceId.

​
Examples

Create a fixed recurring monthly plan: 
curl -X POST https://api.retempo.xyz/api/v1/services/clz1abc2def3ghi4/plans \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Monthly",
    "description": "Full access, billed monthly",
    "pricingType": "FIXED_RECURRING",
    "billingInterval": "MONTH",
    "amount": "49.00"
  }'
Create a usage-based plan with a per-unit price: 
curl -X POST https://api.retempo.xyz/api/v1/services/clz1abc2def3ghi4/plans \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pay-Per-Call",
    "description": "Charged per API call",
    "pricingType": "USAGE_BASED",
    "amount": "0.001"
  }'
For usage-based plans, pair the plan with the /api/v1/usage-events endpoint to report consumption and drive accurate invoice generation at the end of each billing period.