See also the Subscription response object.

A subscription can be created using either a payment method token or – under certain conditions – a payment method nonce.

The payment method must be vaulted before you can associate it with a subscription, so it's usually simplest to refer to the payment method using its PaymentMethodToken. Here's an example:

C♯ 
var request = new SubscriptionRequest
{
    PaymentMethodToken = "the_token",
    PlanId = "the_plan_id"
};

Result<Subscription> result = gateway.Subscription.Create(request);

However, payment method tokens do not carry any 3D Secure data. If you use 3D Secure and need to apply 3DS to the first transaction of a new subscription, you must create the subscription using a 3DS-enriched payment method nonce.

Parameters
AddOns

The collection of add-ons associated with a subscription. Add-on details can only be managed within the Control Panel.

Add Array

Array of add-ons to add to the subscription.
Each element contains:
Amount Decimal

Price of the add-on. This will override the inherited add-on amount.
InheritedFromId required, string

Specify an add-on ID to apply to the subscription. You can't duplicate an add-on that is inherited from the plan, but you can update the quantity.
NeverExpires bool

Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.
NumberOfBillingCycles string

Number of billing cycles to apply the add-on. Must be greater than 0.
Quantity int

How many of this add-on to apply to the subscription. The default is 1.
Remove Array

Array of add-on IDs that are inherited from the plan. IDs specified will be removed from the subscription.
Update Array

Array of add-ons that are inherited from the plan.
Each element contains:
Amount Decimal

Price of the add-on. This will override the existing add-on amount.
ExistingId required, string

Update a particular add-on by specifying the add-on ID.
NeverExpires bool

Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles. This will override inherited plan details.
NumberOfBillingCycles int

Number of billing cycles to apply the add-on. This will override inherited plan details. Must be greater than 0.
Quantity int

How many of this add-on to apply to the subscription. The default is 1.
BillingDayOfMonth int

The value that specifies the day of the month that the gateway will charge the subscription on every billing cycle. The value of this field must be 1-28 or 31. A value of 31 tells the recurring billing engine to charge the subscription on the last day of the month, regardless of how many days are in the month. Passing a value with this field will override the plan's default settings.
Descriptor

Dynamic descriptors are not enabled on all accounts by default. If you receive a validation error of 92203 or if your dynamic descriptors are not displaying as expected, please contact us.

Dynamic descriptors are sent on a per-transaction basis and define what will appear on your customers' credit card statements for a specific purchase. The clearer the description of your product, the less likely customers will issue chargebacks due to confusion or non-recognition.

See the dynamic descriptor example for additional information.
Name string

The value in the business name field of a customer's statement. The specific length/character requirements for this value depend on your processor. Contact us for assistance.
Phone string

The value in the phone number field of a customer's statement. Phone must be 10-14 characters and can only contain numbers, dashes, parentheses and periods.
Url string

The value in the URL/web address field of a customer's statement. The URL must be 13 characters or shorter.
Discounts

A collection of discounts associated with this subscription. Discount details can only be managed within the Control Panel.

Add Array

Array of discounts to add to the subscription.
Each element contains:
Amount Decimal

Price of the discount. This will override the inherited discount amount.
InheritedFromId required, string

Specify a discount ID to apply to the subscription. You can't duplicate a discount that is inherited from the plan, but you can update the quantity.
NeverExpires bool

Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.
NumberOfBillingCycles string

Number of billing cycles to apply the discount. Must be greater than 0.
Quantity int

How many of this discount to apply to the subscription. The default is 1.
Remove Array

Array of discount IDs that are inherited from the plan. IDs specified will be removed from the subscription.
Update Array

Array of discounts that are inherited from the plan.
Each element contains:
Amount Decimal

Price of the discount. This will override the existing discount amount.
ExistingId required, string

Update a particular discount by specifying the discount ID.
NeverExpires bool

Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles. This will override inherited plan details.
NumberOfBillingCycles int

Number of billing cycles to apply the discount. This will override inherited plan details. Must be greater than 0.
Quantity int

How many of this discount to apply to the subscription. The default is 1.
FirstBillingDate DateTime

The day the subscription starts billing. The field can accept date objects and must be a future date. This will override default plan details. Dates will be interpreted as UTC dates.
Id string

A string value representing a specific subscription in the Vault. Max 36 characters; must be unique within a merchant's Vault; valid characters are letters, numbers, - and _. If not specified on creation, the gateway will generate an alphanumeric ID that can be accessed on the result. The generated IDs will never start with a leading 0 and are case insensitive.
MerchantAccountId string

The merchant account ID used to create the subscription's transactions. Currency is also determined by merchant account ID and it must match the Plan's currency. See the Transaction MerchantAccountId parameter for more information.
NeverExpires bool

When true, the subscription never expires.
NumberOfBillingCycles int

Number of billing cycles the subscription should last.
Options

Optional values that can be passed with a request.
DoNotInheritAddOnsOrDiscounts bool

When true, the plan's add-ons and discounts are ignored for this subscription.
Paypal

PayPal-specific options.
Description string

The description of the transaction that is displayed to customers in email receipts from PayPal. 127 character maximum.
StartImmediately bool

This option overrides a plan's details and starts the subscription immediately.
PaymentMethodNonce string

One-time-use reference to a payment method provided by your customer, such as a credit card or PayPal account.

A payment method must be vaulted before you can associate it with a subscription, so it's usually simplest to refer to the payment method using its PaymentMethodToken. However, there are 2 cases where you can pass a payment method nonce instead of a payment method token:

  • If the nonce was generated by our Drop-in UI and you passed a CustomerId when generating the client token, or
  • If the nonce was generated from a vaulted payment method belonging to the customer that will own the subscription
PaymentMethodToken required, string

An alphanumeric value that references a specific payment method stored in your Vault. It is required when creating a subscription unless you pass a PaymentMethodNonce instead, which can be done under certain circumstances.
PlanId required, string

The plan identifier. Values can use only letters, numbers, -, and _. Plans must be created in the Control Panel.

Price Decimal

The price specified for a subscription. Billing price must be formatted like 10 or 10.00. If you provide a price, it can't be an empty string and can't be greater than the maximum allowed by the processor (contact us for your specific limit). If you omit the price, the subscription will inherit the price from the plan.
TrialDuration int

The trial timeframe specified in a plan. Specifying a trial duration via the API will override the subscription's plan details. It is required if trial period is set to true and must be 1-3 digits. If you specify a trial duration of 0, the gateway will start the subscription immediately and not consider it to include a trial period.
TrialDurationUnit string

The trial unit specified in a plan. Specify day or month. Specifying a trial duration unit via the API will override the subscription's plan details.
HasTrialPeriod bool

A value indicating whether a subscription should begin with a trial period. Specifying a trial period via the API will override the subscription's plan details.

Examples

Specify merchant account

If you have multiple merchant accounts, you can pass the merchant account ID to specify which merchant account to use to process transactions for the subscription. If a merchant account ID is not passed, we'll use your default merchant account. If you would like to change which merchant account is default, contact us.

important

The specified merchant account must be in the same currency as the subscription plan, or any attempted subscription transactions will trigger a validation error. If you want to use a merchant account with a different currency, you must create a new plan in the Control Panel with the indicated currency.

C♯ 
var request = new SubscriptionRequest
{
    PaymentMethodToken = "the_token",
    PlanId = "silver_plan_gbp",
    MerchantAccountId = "gbp_account"
};

Result<Subscription> result = gateway.Subscription.Create(request);

Create with 3D Secure enriched payment method nonce

If you use 3D Secure and need to apply 3DS to the first transaction of a new subscription, you must create the subscription using a 3DS-enriched nonce. See 3D Secure for Recurring Transactions for details on how to properly obtain and use a 3DS-enriched nonce for subscription transactions.

Once you've obtained a 3DS-enriched nonce, provide it on the subscription create call:

C♯ 
var request = new SubscriptionRequest
{
    PaymentMethodNonce = "nonce_from_the_client",
    PlanId = "the_plan_id"
};

Result<Subscription> result = gateway.Subscription.Create(request);

Override plan details

When creating the subscription, you can modify the default behavior in three ways:

  • New add-ons/discounts can be added to the subscription.
  • Add-ons/discounts that would be inherited from the plan can be updated on the subscription.
  • Add-ons/discounts that would be inherited from the plan can be removed from the subscription.
C♯ 
var request = new SubscriptionRequest
{
    PaymentMethodToken = "the_token",
    PlanId = "the_plan_id",
    AddOns = new AddOnsRequest
    {
        Add = new AddAddOnRequest[]
        {
            new AddAddOnRequest
            {
                InheritedFromId = "add_on_id_1",
                Amount = 20.00M
            },
            new AddAddOnRequest
            {
                InheritedFromId = "add_on_id_2",
                Amount = 30.00M
            }
        },
        Update = new UpdateAddOnRequest[]
        {
            new UpdateAddOnRequest
            {
                ExistingId = "add_on_id_3",
                Quantity = 2
            },
            new UpdateAddOnRequest
            {
                ExistingId = "add_on_id_4",
                Quantity = 3
            }
        },
        Remove = new String[] { "add_on_id_5", "add_on_id_6" }
    },
    Discounts = new DiscountsRequest
    {
        Add = new AddDiscountRequest[]
        {
            new AddDiscountRequest
            {
                InheritedFromId = "discount_id_1",
                Amount = 7.00M
            }
        },
        Update = new UpdateDiscountRequest[]
        {
            new UpdateDiscountRequest
            {
                ExistingId = "discount_id_2",
                Amount = 15.00M
            }
        },
        Remove = new String[] { "discount_id_3" }
    }
};

Result<Subscription> result = gateway.Subscription.Create(request);

When adding add-ons/discounts to a subscription, all details will be inherited from the add-on/discount specified by the InheritedFromId. When updating add-ons/discounts, all details will be inherited from the add-on/discount specified by the ExistingId. You can override any of the following:

  • Amount
  • NumberOfBillingCycles or NeverExpires
  • Quantity
C♯ 
var request = new SubscriptionRequest
{
    PaymentMethodToken = "the_token",
    PlanId = "the_plan_id",
    AddOns = new AddOnsRequest
    {
        Add = new AddAddOnRequest[]
        {
            new AddAddOnRequest
            {
                InheritedFromId = "add_on_id_1",
                Amount = 20.00M,
                NumberOfBillingCycles = 2,
                Quantity = 4
            }
        },
        Update = new UpdateAddOnRequest[]
        {
            new UpdateAddOnRequest
            {
                ExistingId = "add_on_id_2",
                Amount = 15.00M,
                NeverExpires = true,
                Quantity = 2
            }
        }
    },
    Discounts = new DisccountsRequest
    {
        Add = new AddDiscountRequest[]
        {
            new AddDiscountRequest
            {
                InheritedFromId = "discount_id_1",
                Amount = 20.00M,
                NumberOfBillingCycles = 2,
                Quantity = 4
            }
        },
        Update = new UpdateDscountRequest[]
        {
            new UpdateDscountRequest
            {
                ExistingId = "discount_id_2",
                Amount = 15.00M,
                NeverExpires = true,
                Quantity = 2
            }
        }
    }
};

Result<Subscription> result = gateway.Subscription.Create(request);

note

You can only add an add-on or discount to a subscription once. If you'd like to apply an add-on or discount to a subscription several times, you can pass Quantity when creating or updating the add-on/discount.

Override trial details

C♯ 
var request = new SubscriptionRequest
{
    PaymentMethodToken = "the_token",
    PlanId = "silver_plan",
    HasTrialPeriod = false,
    TrialDuration = 3,
    TrialDurationUnit = SubscriptionDurationUnit.MONTH
};

Result<Subscription> result = gateway.Subscription.Create(request);
  • If you specify a TrialDuration of 0, we will start the subscription immediately and not consider it in a trial period.
  • Valid values for TrialDurationUnit are day and month.
  • You can disable the trial period (if the plan has one) by passing HasTrialPeriod as false.

    Set start date

    You can override the start date from the plan in three different ways:
    • Set FirstBillingDate to a specific date.
  • Set BillingDayOfMonth.
  • Set the option StartImmediately, which overrides any plan start date and starts the subscription immediately.

important

Passing in more than one of these fields will result in a validation error.

C♯ 
var request = new SubscriptionRequest
{
    PaymentMethodToken = "the_token",
    PlanId = "silver_plan",
    FirstBillingDate = DateTime.Now.AddDays(3)
};

Result<Subscription> result = gateway.Subscription.Create(request);

result.Target.Status;
// Pending
C♯ 
var request = new SubscriptionRequest
{
    PaymentMethodToken = "the_token",
    PlanId = "silver_plan",
    BillingDayOfMonth = 15
};

Result<Subscription> result = gateway.Subscription.Create(request);

result.Target.Status;
// Pending

result.Target.BillingDayOfMonth;
// 15
C♯ 
var request = new SubscriptionRequest
{
    PaymentMethodToken = "the_token",
    PlanId = "silver_plan",
    Options = new SubscriptionOptionsRequest
    {
        StartImmediately = true
    }
};

var result = gateway.Subscription.Create(request);

result.Target.Status;
// Active

result.Target.Transactions.Count;
// 1

Dynamic descriptors

C♯ 
SubscriptionRequest request = new SubscriptionRequest
{
    PaymentMethodToken = "the_token",
    PlanId = "plan_without_trial",
    Descriptor = new DescriptorRequest
    {
      Name = "company*my product",
      Phone = "3125551212",
      Url = "company.com"
    }
};

Result<Subscription> result = gateway.Subscription.Create(request);

Subscription subscription = result.Target;
subscription.Descriptor.Name;
// "company*my product"

subscription.Descriptor.Phone;
// "3125551212"

Transaction transaction = subscription.Transactions[0];
transaction.Descriptor.Name;
// "company*my product"

transaction.Descriptor.Phone;
// "3125551212"

See also