Subscriptions

subscription objects create ACH debits according to a schedule. The API allows you to retrieve your subscriptions. You can retrieve individual subscriptions as well as a list of all of your subscriptions.

If the NACH profile of the specified mandate has no creditor bank account, subscription cannot be created.

The following rules apply when specifying recurrence:

  • The first ACH debit must be charged within 1 year.

  • If neither month nor day_of_month are present, the subscription will recur from the start_date based on the interval.

  • If month or day_of_month are present, the recurrence rules will be applied from the start_date, and the following validations apply:

  1. If interval is year, then month and day_of_month are optional, although both are required if one is provided.

  2. If interval is month, then month is invalid and day_of_month is valid.

  3. If interval is week, then both month and day_of_month are invalid.

When a charge date falls on a non-business day, one of two things will happen:

  • If the recurrence rule specified -1 as the day_of_month, the charge date will be rolled backwards to the previous business day (i.e., the last working day of the month).

  • Otherwise the charge date will be rolled forwards to the next business day.

Subscription statuses follow these rules:

  1. The subscription will begin in active status. The statuses pending_customer_approval and customer_approval_denied are currently not in use.

  2. An active subscription will automatically move to cancelled status if its active mandate moves to failed, cancelled or expired status.

  3. An active subscription will automatically move to finished status once its last charge date (if any) has passed.

  4. Cancelling an active subscription has no effect on its mandate.

The subscription object

ATTRIBUTES

Scroll inside to view more
Attribute
Description
id string
Unique identifier for the object.
object string, value is "subscription"
String representing the object's type. Objects of the same type share the same value.
created timestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
livemode boolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
amount integer
The amount to charge on a recurring basis. A positive integer in paisa (one hundredth of a Rupee). e.g. 100 means Rs 1.
count positive integer
The total number of ACH debits scheduled in this subscription. If not specified, the subscription will continue until cancelled.
day_of_month integer
As per RFC 2445. The day of the month to charge customers on. 1 to 28 or -1 to indicate the last day of the month.
interval string
The unit of time between charge dates. One of week, month or year.
interval_count positive integer
The number of intervals (specified in the interval property) between charge dates. For example, interval=month and interval_count=3 bills every three months.
month string
The name of the month on which to charge a customer.
name string
The name of the subscription.
start_date date
The date on which the first ACH debit should be charged. Must be within one year of creation and on or after the mandate's first_collection_date and on or before its final_collection_date (if any).
status string
The status of the subscription. One of pending_customer_approval, customer_approval_denied, active, finished and cancelled.
customer string
The identifier of the customer who owns the subscription.
mandate string
The identifier of the mandate on which the subscription is creating ACH debits.
plan string
The identifier of the subscription's plan, if any.
Last updated 1 year ago