Skip to main content

Represents a recurring billing agreement that collects payments from a customer on a defined schedule.

​
id
string
required

The unique identifier for the subscription.

Example:

"sub_kfAWZgfQIoeG0q"

​
customer_id
string
required

The unique identifier of the customer associated with the subscription.

Example:

"cus_AvCu2y217JqBKxQQOgvcz"

​
customer_payment_method_id
string
required

The unique identifier of the payment method used for recurring charges.

Example:

"cpm_KvXVM4IJVhan36TN6Srrz"

​
description
string
required

A human-readable description of the subscription.

Example:

"Monthly premium plan"

​
amount
integer
required

The amount to be charged in the smallest currency unit. For example, 20.00 ZAR is represented as 2000 cents. Learn more about minor units.

Example:

1000

​
currency
string
required

The ISO 4217 currency code for the payment.

Example:

"ZAR"

​
country
string
required

The ISO 3166-1 alpha-2 country code of the subscription.

Example:

"ZA"

​
mode
enum<string>
required

Indicates whether the subscription is in live or test mode:

  • live: Used in production to process real payments.
  • test: Used for testing and development. Payments are simulated and no real transactions are processed.
Available options:
live,
test
​
recurrence
Monthly Recurrence · object
required

Schedules payments every N months.

Example:
​
start_date
string<date>
required

The date on which the subscription starts and the first payment is scheduled.

Example:

"2024-01-01"

​
end_date
null | string<date>
required

The date on which the subscription ends. If null, the subscription runs indefinitely.

Example:

"2024-12-31"

​
status
enum<string>
required

The current status of the subscription:

  • active: The subscription is active and payments will be collected on the scheduled dates.
  • paused: The subscription is temporarily paused and no payments will be collected.
  • cancelled: The subscription has been cancelled and will not collect any further payments.
  • expired: The subscription has passed its end date without completing all scheduled payments.
  • completed: The subscription has reached its end date and all scheduled payments have been collected.
Available options:
active,
paused,
cancelled,
expired,
completed
Example:

"cancelled"

​
next_payment_date
null | string<date>
required

The next date on which a payment will be attempted. Null if the subscription has no upcoming payments.

Example:

"2024-02-01"

​
latest_payment_attempt
null | Latest Payment Attempt · object
required

Details about the most recent payment attempt. Null if no payment has been attempted yet.

​
cancelled_at
null | string<date-time>
required

The timestamp at which the subscription was cancelled. Null if the subscription has not been cancelled.

Example:

"2024-06-15T10:30:00Z"

​
created_at
string<date-time>
required

ISO 8601 timestamp when the resource was created

Example:

"2025-06-16T10:30:00Z"

​
updated_at
string<date-time>
required

ISO 8601 timestamp when the resource was last updated

Example:

"2025-06-16T10:30:00Z"

​
scheduled_time
null | string

The time of day at which payments are scheduled, in HH:MM format. UTC time is used.

Example:

"09:00"

​
external_reference
string

External reference for reconciliation or tracking purposes. Must be unique within your merchant account.

Maximum string length: 255
Pattern: ^[a-zA-Z0-9_-]+$
Example:

"INV-2024-001"