- v1.0.0-latest-prod
This page will introduce the various domain entities related to subscriptions, and the Subscription domain itself. It will explain the consequences that setting key fields has across the service and beyond.
The Subscription domain is central to the Billing service. As it stands, Subscriptions are the sole entity for which the service bills customers.
The nextBillDate field holds the date after which this Subscription will be billed by the Subscription Billing Job.
The subscriptionStatus field holds a subscription’s current status. This field has far-reaching effects throughout the service. Here are a few highlights:
Only subscriptions in ACTIVE status are billed by the Subscription Billing Job
Only subscriptions in ACTIVE status are cancelled as prior subscriptions to facilitate activating a new subscription (upgraded or downgraded) after a successful billing.
The subscriptionNextStatus field holds a subscription’s next status
This status will become the current status through the flow described here.
The nextStatusChangeDate field holds the date the subscriptionNextStatus will become the subscription’s current status
By default, this is set to equal the nextBillDate.
The billingFrequency field holds the frequency that this subscription gets billed.
A respective processor is used for each frequency to calculate the nextBillDate (e.g. AnnualSubscriptionNextBillDateProcessor).
To create a custom value (beyond ones provided out-of-box in DefaultSubscriptionBillingFrequencyEnum), see the Custom Billing Frequency section.
Note that this field’s value is also transferred to BillingEventPayment’s retryScheduleCode field when it is created as part of the Subscription Billing Job.
The preferredPaymentAccountId field holds a preferred payment account to use when billing for this subscription.
This field overrides the standard ordering of payment methods as provided by the PaymentTransactionServices.
For more information, see Preferred Payment Account.
The nextSubscription field holds a reference to a subscription that is superseding this subscription in the future.
This field is mostly used when a subscription is upgraded or downgraded.
The lastBillingOperationStatus field holds the result of the last billing attempt for this subscription.
A value of FAILURE will restrict this subscription from attempting to bill again.
The nextPeriod field holds the next period of this subscription.
This value is a one-based integer. The first period of a subscription’s activity is 1, then 2, and so on.
This value correlates to SubscriptionAdjustment’s and SubscriptionItemAdjustment’s beginPeriod and endPeriod fields.
The needGrantEntitlements field shows whether the service has outstanding Entitlements to grant on this subscription
A SubscriptionAdjustment represents a discount for a given Subscription. It is usually derived from an offer that affects this subscription.
The subscriptionAdjustmentType field holds the type of "discount" that this adjustment represents
By default, the possible values are PERCENT_OFF, AMOUNT_OFF, or `FIXED_PRICE. They replicate possible offer discount types from PromotionServices.
The beginPeriod field holds the number of the subscription’s billing period that this adjustment is due to start.
On the Subscription domain, the nextPeriod field holds the subscription’s next billing period number.
The endPeriod field holds the number of the subscription’s billing period that this adjustment is due to end.
If this field is empty, the adjustment is considered indefinite.
A SubscriptionItem represents a specific line item for a Subscription that may include several products.
The itemRef field references the original order item this subscription item represents
The itemName field is the name of the original order item
The itemUnitPrice field has the price of a single unit for this item
The taxable field determines whether this item should be taxed in the tax module
A SubscriptionItemAdjustment represents a discount for a given Subscription’s line item (i.e. SubscriptionItem). It represents a specific discount to a single line item.
The fields of this object are nearly identical to that of a SubscriptionAdjustment entity, except they reference a subscription item instead of a subscription.
|
Note
|
It is not necessary to create prorated SubscriptionItemAdjustments for an event-level SubscriptionAdjustment, as the Subscription Billing Job will prorate the event-level discounts to the item level when it bills.
|