Skip to main content
POST
Create

Authorizations

Authorization
string
header
required

API key authentication

Body

application/json
name
string
required

Subscription identifier combining customer and service details. Sample values: 'TechCorp - LLM API Access', 'Analytics Co - Data Platform Enterprise', 'StartupXYZ - Image Generation Service', 'Enterprise Inc - ML Training Platform'

planId
string
required

Unique identifier for a plan

Pattern: ^plan_[a-zA-Z0-9]+$
startedAt
string<date-time>
required

Subscription activation timestamp in ISO 8601 format. Sample values: '2024-01-15T10:30:00Z', '2024-02-01T00:00:00Z'

autoCharge
boolean
default:false

Enable automatic charging of invoices using stored payment methods. When true, invoices will be automatically paid using off-session payment. Defaults to false.

taxExempt
boolean
default:false

When true, forces tax rate to 0%. Use for customers with verified tax-exempt status.

customer
object

Fields to create a new customer and consumer. Will use an existing consumer if one exists with the same email address. Required if customerId is not provided. Address with complete tax information (country, state, zipCode) is required for tax calculation when using Paygentic Tax.

customerId
string

Unique identifier for a customer

Pattern: ^cus_[a-zA-Z0-9]+$
endingAt
string<date-time>

Subscription expiration timestamp in ISO 8601 format. Sample values: '2024-12-31T23:59:59Z', '2025-01-15T10:30:00Z'. Omit for indefinite subscriptions. Must be after startedAt: a value at or before it is rejected with 400.

prefundAmount
string
deprecated

Deprecated. This field is ignored and has no effect.

minimumAccountBalance
string
deprecated

Deprecated. This field is ignored and has no effect.

redirectUrls
object

Optional redirect URLs after payment completion or failure. If not provided, uses default platform behavior.

elapsedPeriodBilling
enum<string>
default:none

Whether a backdated start bills its elapsed periods. A start is backdated when startedAt is more than 24 hours before the subscription is created. none bills only charges that fall due from the moment of creation, for a customer whose earlier periods another system already billed. per_period bills every charge that fell due from startedAt, on one first invoice; it refuses a startedAt more than 12 months back, with the code PER_PERIOD_LOOKBACK_EXCEEDED. Has no effect on a start that is not backdated. Defaults to none.

Available options:
none,
per_period
billingAnchor
string<date-time>

A billing anchor for this subscription, in place of the plan's. Any instant, past or future. The subscription's billing anchor is its first recurrence on or after startedAt, stepping back or forward by whole billing cadences. Example: on a monthly plan, an anchor of '2027-01-31T00:00:00Z' with a start of '2026-10-10T00:00:00Z' gives '2026-10-31T00:00:00Z'. A create is refused with 400 when the resolved anchor does not line up with the usage period anchor of a feature that credits unused balance. Omit it to use the plan's billing anchor. A repeated create that names an anchor resolving to a different instant than the existing subscription's gets 409.

testClockId
string

Test clock identifier for simulating time-based billing scenarios. Sample values: 'tc_abc123xyz', 'tc_789def456'. Restricted to non-production environments (local, dev, sandbox). Must belong to the same merchant organization.

renewalReminderEnabled
boolean | null

Override plan setting for renewal reminder emails. When set, this subscription's setting takes precedence over the plan default. Set to true to enable reminders, false to disable, or null/omit to use plan default.

renewalReminderDays
integer | null

Override plan setting for number of days before renewal to send the reminder. Only used if renewalReminderEnabled is true (or inherited from plan). Set to null to use plan default.

Required range: 1 <= x <= 30
paymentTermDays
integer

Payment term in days ("Net X") applied to every invoice the subscription generates: invoice dueAt = invoice issue date + paymentTermDays. Defaults to 0 ("due on issue"). Valid on any subscription, whatever its payment method. With a non-zero value Invoice 0's payment session expires at its due date, and sending sessionExpiryMinutes with it answers 400 SESSION_EXPIRY_NOT_ALLOWED_WITH_PAYMENT_TERM.

Required range: 0 <= x <= 365
sessionExpiryMinutes
number

Number of minutes until the payment session expires. Defaults to 240 minutes (4 hours) if not provided. Not accepted with a non-zero paymentTermDays: the session then expires at the invoice due date.

Required range: x >= 1
versionPolicy
enum<string>

How the subscription follows new versions of its plan. floating follows the plan's default version: when the default changes, the subscription bills from the new default from its next billing period. pinned keeps the plan version that the subscription holds. A subscription created without a value is floating. A change to this value does not change a billing period that has already started.

Available options:
floating,
pinned
metadata
object

Free-form merchant metadata to attach to the subscription. Values must be strings, numbers, or booleans.

changeReason
enum<string>

Why a change was made. correction repairs data that was entered wrong; migration moves a contract from another system; commercial is a real change to the deal; contractual applies a step the original contract scheduled, such as an annual uplift. Defaults to unspecified.

Available options:
commercial,
correction,
migration,
unspecified,
contractual
changeDescription
string

A free-text note on why these intervals are changing.

Maximum string length: 1000
changeMetadata
object

Your own key-value data about the change, such as a CRM deal ID.

addPrices
object[]

Catalog prices to bill on this subscription that its plan version does not carry. Each must be owned by the same merchant and use the standard price model.

Maximum array length: 25
overridePrices
object[]

Rate or quantity overrides for prices the plan version does carry.

Maximum array length: 25
removePrices
object[]

Plan prices this subscription does not bill.

Maximum array length: 25

Response

Subscription already exists

id
string
required
object
enum<string>
required
Available options:
subscription
merchantId
string
required

The merchant organization that owns this subscription, equal to the customer's merchant.

Pattern: ^org_[a-zA-Z0-9]+$
createdAt
string<date-time>
required
customerId
string
required
name
string
required
planId
string
required
versionPolicy
enum<string>
required

How the subscription follows new versions of its plan. floating follows the plan's default version: when the default changes, the subscription bills from the new default from its next billing period. pinned keeps the plan version that the subscription holds. A subscription created without a value is floating. A change to this value does not change a billing period that has already started.

Available options:
floating,
pinned
startedAt
string<date-time>
required
elapsedPeriodBilling
enum<string> | null
required

Whether this subscription's backdated start bills its elapsed periods, as chosen at creation. null for a subscription created before the choice existed. null is listed in the enum as well as via nullable because the response validator checks the enum independently.

Available options:
none,
per_period,
null
billingStartsAt
string<date-time> | null
required

The billing start: a charge is billed only if it falls due at or after this moment. Fixed at creation and never changed. It is startedAt, unless the start was backdated with elapsedPeriodBilling of none, in which case it is the moment of creation.

billingAnchor
string<date-time>
required

The instant the subscription's billing periods are anchored on: its billing anchor, else its start. Every recurring period boundary is this instant plus a whole number of cadences.

billingCadence
string
required

The ISO-8601 duration the subscription's billing periods step by where no price sets its own: the subscription's cadence, else its plan's.

Example:

"P1M"

status
enum<string>
required
Available options:
pending_payment,
active,
terminated
updatedAt
string<date-time>
required
paymentTermDays
integer
required

Payment term in days ("Net X") snapshotted onto every invoice the subscription generates (invoice dueAt = invoice issue date + paymentTermDays). Defaults to 0 ("due on issue"); a non-zero value is valid on any subscription, whatever its payment method.

Required range: 0 <= x <= 365
autoCharge
boolean
default:false

Whether automatic charging is enabled for this subscription. When true, invoices will be automatically paid using stored payment methods.

endingAt
string<date-time>
estimatedTaxRate
number

Projected tax percentage rate. Sample values: 8.875 indicates 8.875% tax rate, 10.0 indicates 10% tax rate, 0 indicates no tax applied

taxExempt
boolean
default:false

When true, tax rate is forced to 0%.

payment
object

Payment session details when upfront payment is required, or confirmation of a zero-amount paid invoice

planVersionId
string

The plan version pinned to this subscription at creation.

versionNumber
integer

The version number of the plan version referenced by planVersionId, as of subscription creation.

Required range: x >= 1
prefundAmount
string
deprecated

Deprecated. Legacy-only, not populated for new subscriptions.

minimumAccountBalance
string
deprecated

Deprecated. Legacy-only, not populated for new subscriptions.

terminatedAt
string<date-time>
terminatedBy
string

ID of who terminated the subscription (customer ID or merchant ID)

terminationReason
string

Reason for termination

terminationChangeReason
enum<string> | null

Why the subscription was terminated. Null while it is not terminated.

Available options:
commercial,
correction,
migration,
unspecified,
contractual,
null
testClockId
string

Test clock ID if this subscription is attached to a test clock. Only present in non-production environments.

walletId
string
deprecated

Deprecated. Legacy-only, not populated for new subscriptions.

renewalReminderEnabled
boolean | null

Whether renewal reminder emails are enabled for this subscription. Null means use plan default.

renewalReminderDays
integer | null

Number of days before renewal to send the reminder. Null means use plan default.

autoApprove
boolean | null

Subscription-level auto-approval override. Null means plan default is used.

metadata
object

Free-form merchant metadata to attach to the subscription. Values must be strings, numbers, or booleans.

customer
object

Customer details with merchant and consumer information. Only included when include=customer is specified in the list query.