Plan basics
Learn more about the plans resource.
Last updated
Learn more about the plans resource.
Last updated
On this page, you'll find information on:
Plans define the recurring billing behavior of a group of subscriptions. Since plans can be used to perform reporting and bulk operations, you should be careful when adding different subscription products to the same plan.
For complete specifications, refer to the Plans API reference documentation.
When creating a plan, you can specify its id . The value cannot contain whitespaces. If you don't provide an id, Digital River generates a UUID.
A plan's name should describe the subscription products that belong to it. We recommend that you select a name specific enough for inclusion in . When Digital River creates a draft invoice at the start of each billing cycle, we use the plan's name to set the invoice's description . We then add invoice.description to the of events with the of , , and .
A plan's terms should contain the contractual agreement displayed to customers during the acquisition process. These terms define the subscription, provide links to Digital River's terms of sale and privacy policy, and stipulate that customers agree to store their payment information for use in renewals.
These should be the same during the acquisition process.
The optional contractBindingDays indicates the agreed-upon length of the contract. For example, an annual subscription should have a value of 365.
The billing interval is used in combination with the intervalCount. You can set up plans with intervals of day, week, month or year. The intervalCount is how often the customer is billed per the unit of time specified by interval. The intervalCount must be 1 or greater and cannot exceed 1000.
The following examples demonstrate the relationship between these variables:
This defines a subscription with a binding length of one year. The customer is billed annually.
The billingOffsetDays represents how many days before the end of the billing period that Digital River opens an invoice. For example, if you want Digital River to start attempting to capture payment ten days before the billing period ends, set this parameter to 10.
The billingOffsetDays cannot be greater than the collectionPeriodDays. Such a configuration could result in the billing process concluding without a successful payment capture but with time remaining in the current cycle.
For example, if you want to set up your system to email a customer one week before Digital River opens an invoice, set reminderOffsetDays to 7.
The reminderOffsetDays cannot be greater than the contractBindingDays.
The collectionPeriodDays represents the number of days that Digital River attempts to collect payment. If you set this parameter to 0 or 1 , we make a single attempt to bill the customer. But if you provide a value greater than 1, and the first billing attempt fails, our smart autorenewal service continues making collection attempts for the number of days you specify.
Once a plan is created, billingOptimization indicates whether our smart autorenewal service is activated for that plan's subscriptions.
For more information on the state attribute, refer to the lifecycle of a plan section.
After a plan is discontinued, any subscriptions currently on that plan continue renewing. You cannot, however, add any new subscriptions to a discontinued plan.
When a plan is deactivated, any subscriptions currently on that plan become ended on their nextInvoiceDate and any new subscriptions that you attempt to add are blocked.
The only two states that allow a plan's subscriptions to continue billing are active and discontinued.
The data in this field is used only for compliance and transparency purposes. Therefore, your integration must be set up to allow customers to after the designated period elapses. Of course, during this contract period, you can always grant customers an exemption and allow them to cancel their subscriptions.
The reminderOffsetDays represents the number of days before the initiation of billing that Digital River sends you the . This event should trigger a corresponding event in your system that sends a reminder to the customer.
Plans can be created in a draft or active state. But subscriptions can only be added to active plans. In other words, once you , Digital River accepts its identifier when you create a subscription.
For details, refer to .
