Skip to main content
POST
Create a subscription plan

Authorizations

x-api-key
string
header
required

API key for authentication (required)

x-merchant-id
string
header
required

Merchant ID for identifying the merchant (required)

Body

application/json
name
string
required

Plan name

Required string length: 1 - 255
Example:

"Monthly Premium Plan"

amount
integer
required

Amount in smallest currency unit (e.g., cents)

Required range: x >= 1
Example:

9900

currency
enum<string>
required

Currency code (ISO 4217)

Available options:
MXN,
USD
Example:

"MXN"

interval
enum<string>
required

Billing interval

Available options:
DAY,
WEEK,
MONTH,
YEAR
Example:

"MONTH"

externalId
string

External plan ID from merchant system

Maximum string length: 255
Example:

"PLAN-MONTHLY-001"

description
string

Plan description

Maximum string length: 1000
Example:

"Premium subscription with all features included"

intervalCount
integer
default:1

Number of intervals between billings

Required range: 1 <= x <= 12
Example:

1

trialDays
integer

Number of trial days before first billing

Required range: 1 <= x <= 365
Example:

14

metadata
object

Additional metadata for the plan

Example:

Response

Subscription plan created successfully

id
string<uuid>
required

Unique plan identifier

Example:

"123e4567-e89b-12d3-a456-426614174000"

merchantId
string
required

Merchant identifier

Example:

"merchant_123"

name
string
required

Plan name

Example:

"Monthly Premium Plan"

amount
string
required

Amount in smallest currency unit (string representation of BigInt)

Example:

"9900"

currency
string
required

Currency code

Example:

"MXN"

interval
enum<string>
required

Billing interval

Available options:
DAY,
WEEK,
MONTH,
YEAR
Example:

"MONTH"

intervalCount
integer
required

Number of intervals between billings

Example:

1

active
boolean
required

Whether the plan is active

Example:

true

createdAt
string<date-time>
required

Creation timestamp

Example:

"2025-01-15T10:00:00.000Z"

updatedAt
string<date-time>
required

Last update timestamp

Example:

"2025-01-15T10:00:00.000Z"

externalId
string | null

External plan ID from merchant system

Example:

"PLAN-MONTHLY-001"

description
string | null

Plan description

Example:

"Premium subscription with all features included"

trialDays
integer | null

Number of trial days

Example:

14

metadata
object | null

Additional metadata