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>",
  "billingInterval": "<string>",
  "defaultTaxCode": "eservice",
  "defaultTaxRate": 0,
  "description": "<string>",
  "invoiceDisplayName": "<string>",
  "prices": [
    "<string>"
  ],
  "productId": "<string>",
  "taxBehavior": "exclusive",
  "renewalReminderEnabled": true,
  "renewalReminderDays": 3
}
'
{
  "id": "plan_t9u0v1w2x3y4z5a6",
  "object": "plan",
  "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
​
merchantId
string
required

The merchant organization that will own this plan

​
name
string
required

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

​
billingInterval
string

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

​
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

​
productId
string

The product this plan belongs to

​
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

Response

Plan created successfully

​
id
string
required

Unique identifier for a plan

​
object
enum<string>
required
Available options:
plan
​
billingInterval
string
required
​
createdAt
string<date-time>
required
​
currency
string
required
​
merchantId
string
required

The merchant organization that owns this plan

​
name
string
required
​
productId
string
required

The product this plan belongs to

​
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.