Skip to main content
POST
/
v0
/
plans
Create
curl --request POST \
  --url https://api.paygentic.io/v0/plans \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "<string>",
  "merchantId": "<string>",
  "name": "<string>",
  "billingCadence": "P1M",
  "billingInterval": "monthly",
  "defaultTaxCode": "eservice",
  "defaultTaxRate": 0,
  "description": "<string>",
  "invoiceDisplayName": "<string>",
  "prices": [
    "<string>"
  ],
  "productId": "<string>",
  "taxBehavior": "exclusive",
  "renewalReminderEnabled": true,
  "renewalReminderDays": 3,
  "billingVersion": 0
}
'
{
  "id": "plan_t9u0v1w2x3y4z5a6",
  "object": "plan",
  "billingCadence": "P1M",
  "billingInterval": "monthly",
  "createdAt": "2024-01-12T10:00:00Z",
  "currency": "USD",
  "defaultTaxCode": "eservice",
  "defaultTaxRate": 8.5,
  "description": "Claude API access with 500K tokens monthly allowance",
  "invoiceDisplayName": "LLM API Basic Plan",
  "merchantId": "org_b7c8d9e0f1g2h3i4",
  "name": "Basic Tier",
  "prices": [
    "price_r3s4t5u6v7w8x9y0"
  ],
  "productId": "prod_j5k6l7m8n9o0p1q2",
  "taxBehavior": "exclusive",
  "updatedAt": "2024-01-12T10:00:00Z"
}

Authorizations

​
Authorization
string
header
required

API key authentication

Body

application/json
​
currency
string
required

Three-letter ISO 4217 currency code for plan pricing. Must be one of the merchant's supported currencies. Sample values: 'USD' for US dollars, 'EUR' for euros, 'GBP' for British pounds

Required string length: 3
Pattern: ^[A-Z]{3}$
​
merchantId
string
required

The merchant organization that will own this plan

Pattern: ^org_[a-zA-Z0-9]+$
​
name
string
required

Plan identifier visible to customers. Sample values: 'Basic Tier', 'Business Package', 'Enterprise Solution', 'Metered Billing', 'Free Tier', 'Premium Access'

​
billingCadence
enum<string>

ISO 8601 duration for the billing period. Takes precedence over billingInterval when both are provided.

Available options:
P1M,
P3M,
P1Y
​
billingInterval
enum<string>

Recurring billing period frequency. Sample values: 'monthly' for monthly billing, 'quarterly' for quarterly billing, 'yearly' for annual billing

Available options:
monthly,
quarterly,
yearly,
annual
​
defaultTaxCode
string
default:eservice

Default tax code for plan line items. Common values: 'eservice' (electronically supplied services), 'saas' (software as a service), 'consulting', 'ebook', 'standard', 'reduced', 'exempt'. Full list available via GET /tax/codes endpoint.

​
defaultTaxRate
number
default:0

Fallback tax rate percentage when automatic tax calculation fails. Sample values: 8.5 represents 8.5% tax, 10.0 represents 10% tax, 0 represents no tax

​
description
string

Plan details explaining included features and limits. Sample values: 'Claude API access with 500K tokens monthly allowance', 'Unlimited cloud storage plus real-time analytics tools', 'Complete machine learning infrastructure with GPU access', 'Flexible usage-based pricing with no monthly commitment'

​
invoiceDisplayName
string

Plan name shown on billing statements. Sample values: 'LLM API Basic Plan', 'Data Warehouse Business', 'ML Platform Enterprise', 'Pay-Per-Use Model'

​
prices
string[]

Array of price IDs to associate with this plan

Unique identifier for a price

Pattern: ^price_[a-zA-Z0-9]+$
​
productId
string

The product this plan belongs to

Pattern: ^prod_[a-zA-Z0-9]+$
​
taxBehavior
enum<string>
default:exclusive

Whether tax is added on top of the price (exclusive) or included in the price (inclusive)

Available options:
exclusive,
inclusive
​
renewalReminderEnabled
boolean
default:true

Whether to send renewal reminder emails to customers before their subscription renews

​
renewalReminderDays
integer
default:3

Number of days before renewal to send the reminder email

Required range: 1 <= x <= 30
​
billingVersion
enum<integer>
default:0

Billing engine version. 0 = legacy fee-schedule billing (Legacy), 1 = line-item billing with metered usage support (Standard).

Available options:
0,
1

Response

Plan created successfully

​
id
string
required

Unique identifier for a plan

Pattern: ^plan_[a-zA-Z0-9]+$
​
object
enum<string>
required
Available options:
plan
​
billingCadence
enum<string>
default:P1M
required

ISO 8601 duration for the billing period.

Available options:
P1M,
P3M,
P1Y
​
billingInterval
string
required
deprecated

Deprecated. Human-readable billing period derived from billingCadence. Use billingCadence instead.

​
createdAt
string<date-time>
required
​
currency
string
required
​
merchantId
string
required

The merchant organization that owns this plan

Pattern: ^org_[a-zA-Z0-9]+$
​
name
string
required
​
productId
string
required

The product this plan belongs to

Pattern: ^prod_[a-zA-Z0-9]+$
​
updatedAt
string<date-time>
required
​
defaultTaxCode
string

Default tax code for plan line items. Common values: 'eservice' (electronically supplied services), 'saas' (software as a service), 'consulting', 'ebook', 'standard', 'reduced', 'exempt'. Full list available via GET /tax/codes endpoint.

​
defaultTaxRate
number

Fallback tax rate (as percentage) if automatic tax calculation is unavailable

​
deletedAt
string<date-time>
​
description
string
​
invoiceDisplayName
string
​
paymentTerm
object
​
prices
object[]
​
taxBehavior
enum<string>

Whether tax is added on top of the price (exclusive) or included in the price (inclusive)

Available options:
exclusive,
inclusive
​
walletNamespaceId
string

Unique identifier for a wallet namespace

​
renewalReminderEnabled
boolean

Whether renewal reminder emails are enabled for subscriptions using this plan

​
renewalReminderDays
integer

Number of days before renewal to send the reminder email

​
billingVersion
integer

Billing engine version. Managed by Paygentic support.