Pricing (Prices)

What is a Price?

A Price defines how a product is billed. It can be a one-time payment or a recurring subscription with different billing frequencies.

Identifier format: price_ followed by 36 alphanumeric characters.Example: price_abc123def456ghi789jkl012mno345

Product → Price Relationship

A price is attached to a product through productId, and a product can carry several prices for different pricing strategies:

Product "Pro Course"
├── Price 25,000 XAF one-time
├── Price 5,000 XAF/month (monthly subscription)
├── Price 50,000 XAF/year (annual subscription with savings)
└── Price 39 EUR one-time (European market)

This flexibility lets you offer multiple payment options for the same product and support multiple currencies.

Price Attributes

Main Attributes

Attribute	Type	Description
`id`	string	Unique price identifier
`productId`	string	Reference to the parent product
`skuId`	string \| null	Inherited. Link to a legacy variant. `null` for any price created at the product level — no longer a way to create a price, see the note below
`amount`	string	Amount in the currency’s main unit, returned as a decimal string (`"25000.00"`)
`currency`	string	Currency code, returned lowercase (`"xaf"`)
`type`	enum	`one_time` or `recurring`
`active`	boolean	Whether the price is active and usable

Recurring Attributes (Subscriptions)

Attribute	Type	Description
`billingInterval`	enum	`day`, `week`, `month`, `year`
`billingIntervalCount`	number	Number of intervals (e.g. 3 = every 3 months)
`trialPeriodDays`	number \| null	Free trial days

Create a Price

A first price is posed at product creation with defaultPriceData (see Products). POST /v1/prices is the door for the second price — an annual tier next to the monthly one, or a second currency — by indicating in the body the product it attaches to.

Request Body

string

Identifier of the product this price attaches to. Either productId or skuId is required — neither is individually mandatory at the validator level, but the request is rejected if both are absent. skuId is a legacy form, kept for compatibility; productId remains the normal path.

number

required

Amount in the currency’s main unit. Strictly positive, up to 99999999.99.

string

required

Currency code, stored and returned lowercase. Required — there is no default currency. Limited to xaf and eur, see the Supported Currencies section further down.

enum

default:"one_time"

one_time or recurring.

enum

day, week, month, or year. Recurring prices only.

number

Number of intervals per billing cycle. Strictly positive.

number

Free trial days, 0 or more.

boolean

default:"true"

Pass false to create the price already deactivated.

A price is immutable. PUT /v1/prices/{id} only updates the active field — no other field is read, even if present in the body. To change an amount, currency, or billing cadence, create a new price: at matching dimensions (product × currency × type × cadence), the previously active price is automatically deactivated. Details of this replacement rule further down, in the API Response section.

Pricing Types

One-time Payment
Recurring Subscription

One-Time (`one_time`)

The customer pays once to access the product.Use cases:

One-off purchases
Physical products
Digital downloads
Lifetime access

curl -X POST https://buy.api.yabetoopay.com/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123",
    "amount": 25000,
    "currency": "xaf",
    "type": "one_time"
  }'

Recurring (`recurring`)

The customer is billed automatically at regular intervals.Use cases:

SaaS subscriptions
Ongoing services
Premium access
Maintenance

curl -X POST https://buy.api.yabetoopay.com/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123",
    "amount": 5000,
    "currency": "xaf",
    "type": "recurring",
    "billingInterval": "month",
    "billingIntervalCount": 1,
    "trialPeriodDays": 14
  }'

Billing Intervals

For recurring prices, define the billing frequency:

Interval	Count	Description	Example
`day`	1	Daily	Billed every day
`week`	1	Weekly	Billed every week
`week`	2	Bi-weekly	Billed every 2 weeks
`month`	1	Monthly	Billed every month
`month`	3	Quarterly	Billed every 3 months
`month`	6	Semi-annual	Billed every 6 months
`year`	1	Annual	Billed every year

// Quarterly billing
{
  "productId": "prod_abc123",
  "type": "recurring",
  "billingInterval": "month",
  "billingIntervalCount": 3,
  "amount": 15000,
  "currency": "xaf"
}

Trial Periods

Offer a free trial period to attract new customers:

{
  "productId": "prod_abc123",
  "type": "recurring",
  "billingInterval": "month",
  "billingIntervalCount": 1,
  "amount": 9000,
  "currency": "xaf",
  "trialPeriodDays": 14
}

Subscription starts

The customer signs up and starts their free trial period

Trial period

For 14 days, the customer has full access without being billed

Trial ends

At the end of the trial, the first payment is automatically charged

Recurring cycle

Subsequent payments are charged according to the defined interval

Make sure to clearly inform your customers of the trial duration and the amount that will be billed afterward.

Multi-currency Management

Create one price per currency for the same product. Each price corresponds to a separate POST /v1/prices call:

curl -X POST https://buy.api.yabetoopay.com/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123",
    "amount": 39,
    "currency": "eur",
    "type": "one_time"
  }'

Supported Currencies

The list is closed, not indicative. currency is validated against an enumeration — any other value, including a real ISO 4217 code like XOF or USD, is refused with 422. Only two currencies are accepted today.

Code	Currency	Country/Region
`XAF`	Central African CFA Franc	Central Africa
`EUR`	Euro	Europe

All amounts are expressed in the currency’s main unit, never in cents. For example: 25000 XAF = 25,000 XAF, 39 EUR = €39.

API Response

GET /v1/prices/{id} exposes product and sku at the root of the object.

string

Identifier of the parent product.

object

The parent product, always present.

string | null

Inherited. null for a price created at the product level — the normal path today.

object | null

Inherited. The variant the price comes from, for prices created before the SKU left the creation contract. null otherwise.

price.sku can hold a non-null object. A price created through the legacy path (attached to a variant) still carries it, and will keep carrying it until it’s replaced by a new price. Any integration that dereferences price.sku — for example price.sku.product — must guard against null in both directions: don’t crash when it’s absent, and don’t assume it always is.

{
  "id": "price_abc123def456ghi789",
  "productId": "prod_xyz789abc123def456",
  "product": {
    "id": "prod_xyz789abc123def456",
    "name": "Pro Course"
  },
  "skuId": null,
  "sku": null,
  "amount": "25000.00",
  "currency": "xaf",
  "type": "one_time",
  "billingInterval": null,
  "billingIntervalCount": null,
  "trialPeriodDays": null,
  "active": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Replacement rule. Creating a price automatically deactivates the price that was active for the same product, the same currency, the same type and the same cadence (billingInterval + billingIntervalCount). This is what makes a price immutable: instead of editing an existing price, you create a new one, and the replacement happens on its own.A consequence worth knowing: a monthly price and an annual price share the same type (recurring) but a different cadence, so they coexist without replacing each other — this is how you offer both options on the same product.

Common Operations

Create a Price

curl -X POST https://buy.api.yabetoopay.com/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123",
    "amount": 9000,
    "currency": "xaf",
    "type": "recurring",
    "billingInterval": "month",
    "billingIntervalCount": 1
  }'

Retrieve a Price

curl https://buy.api.yabetoopay.com/v1/prices/price_abc123 \
  -H "Authorization: Bearer sk_live_..."

List a Product’s Prices

curl "https://buy.api.yabetoopay.com/v1/prices?productId=prod_abc123" \
  -H "Authorization: Bearer sk_live_..."

GET /v1/prices accepts the following filters, which can be combined:

Filter	Description
`productId`	Only prices for this product
`skuId`	Inherited. Only prices attached to this legacy variant
`type`	`one_time` or `recurring`
`active`	`true` or `false`

Deactivate a Price

🛑 This page long claimed that “prices cannot be deleted if they are associated with active subscriptions” — that’s false, and not just nuanced: there is no condition at all. DELETE /v1/prices/{id} doesn’t delete anything and never checks any subscription — it unconditionally deactivates the price (active: false) and returns {"message": "Price deactivated"}. PUT produces the same effect, and it’s the only change it accepts.

curl -X PUT https://buy.api.yabetoopay.com/v1/prices/price_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

Pricing Strategies

Monthly vs. Annual Pricing

Offer a discount for the annual subscription — two POST /v1/prices calls on the same product, with two different cadences:

// Monthly price
{
  "productId": "prod_saas_pro",
  "amount": 9000,
  "currency": "xaf",
  "type": "recurring",
  "billingInterval": "month",
  "billingIntervalCount": 1
}

// Annual price — same product, different cadence: both coexist
{
  "productId": "prod_saas_pro",
  "amount": 90000,
  "currency": "xaf",
  "type": "recurring",
  "billingInterval": "year",
  "billingIntervalCount": 1
}

9,000 XAF/month vs. 90,000 XAF/year works out to about 2 free months, which encourages customers to commit for the year.

Tiered Pricing

Create one product per service tier, each with its own price:

Product "Cloud App — Starter"     → Price 5,000 XAF/month
Product "Cloud App — Pro"         → Price 15,000 XAF/month
Product "Cloud App — Enterprise"  → Price 50,000 XAF/month

Useful Getters

The Price model provides getters to simplify checks:

// Check the price type
price.isRecurring  // true if type === 'recurring'
price.isOneTime    // true if type === 'one_time'

Best Practices

Amount Format

Amounts are expressed in the currency’s main unit, never in cents:

XAF: 25000 = 25,000 XAF
EUR: 39 = €39

Decimals are accepted and the amount cannot exceed 99999999.99. The API returns it as a decimal string ("25000.00").

Repricing a Product

A price is immutable: never rely on PUT to change an amount, currency, or cadence — it only touches active
Create a new price; the previously active price of matching dimensions deactivates on its own
Read the product from price.product

Active/Inactive Prices

Deactivate old prices rather than deleting them
Keep the number of active prices to the minimum necessary
Keep in mind that a new price deactivates the active price of the same product, currency, type, and cadence

Trial Periods

7 to 14 days is generally optimal
Too short: not enough time to evaluate
Too long: potential loss of revenue

Multi-currency

Adjust prices for each market (not a straight conversion)
Account for local purchasing power
Use psychological pricing (9,000 XAF rather than 8,750 XAF)

Next Steps

Create Promotions

Apply discounts with coupons and promo codes

Manage Subscriptions

Understand the subscription lifecycle

Get started

Setup account

Key concepts

Product Catalog

Resources

What is a Price?

Product → Price Relationship

Price Attributes

Main Attributes

Recurring Attributes (Subscriptions)

Create a Price

Request Body

Pricing Types

One-Time (`one_time`)

Recurring (`recurring`)

Billing Intervals

Trial Periods

Multi-currency Management

Supported Currencies

API Response

Common Operations

Create a Price

Retrieve a Price

List a Product’s Prices

Deactivate a Price

Pricing Strategies

Monthly vs. Annual Pricing

Tiered Pricing

Useful Getters

Best Practices

Next Steps

Create Promotions

Manage Subscriptions

​What is a Price?

​Product → Price Relationship

​Price Attributes

​Main Attributes

​Recurring Attributes (Subscriptions)

​Create a Price

​Request Body

​Pricing Types

​One-Time (one_time)

​Recurring (recurring)

​Billing Intervals

​Trial Periods

​Multi-currency Management

​Supported Currencies

​API Response

​Common Operations

​Create a Price

​Retrieve a Price

​List a Product’s Prices

​Deactivate a Price

​Pricing Strategies

​Monthly vs. Annual Pricing

​Tiered Pricing

​Useful Getters

​Best Practices

​Next Steps

Create Promotions

Manage Subscriptions

What is a Price?

Product → Price Relationship

Price Attributes

Main Attributes

Recurring Attributes (Subscriptions)

Create a Price

Request Body

Pricing Types

One-Time (`one_time`)

Recurring (`recurring`)

Billing Intervals

Trial Periods

Multi-currency Management

Supported Currencies

API Response

Common Operations

Create a Price

Retrieve a Price

List a Product’s Prices

Deactivate a Price

Pricing Strategies

Monthly vs. Annual Pricing

Tiered Pricing

Useful Getters

Best Practices

Next Steps