Many systems use plan and subscription as interchangeable terms when discussing recurring billing but in Fusebill a plan and a subscription are very different.
Plans should be thought of as templates for a service you want to sell to your customers. A subscription is the actual implementation of a plan when that plan is attached to a customer. Changes to a plan do not change the subscriptions created from that plan and changes made to a subscription have no effect on the plan they were created from.
In addition, plans can have multiple frequencies (every 2 months, every 4 months, every 1 year, etc). Subscriptions are instances of a particular frequency of a particular plan, so a subscription has only one frequency regardless of how many frequencies were in the plan from which the subscription was created.
Subscription Object Fields
| Property | Type | Description |
|---|---|---|
customerId | Integer | This is the Id of the Customer to whom this Subscription has been applied. [Read Only] |
planFrequency | Object (definition below) | This provides details of the plan frequency that was used to configure the subscription. [Read Only] |
planCode | String | This is the unique code which represents the Plan of which this Subscription is an instance. [Read Only] |
planName | String | This is the name of the plan of which this Subscription is an instance. [Read Only] |
planDescription | String | This is the description text of the Plan of which this Subscription is an instance of. [Read Only] |
planReference | String | This is a text field which will be populated with the reference text from the plan. This field is not exposed on the Invoice. [Read Only] |
status | Enum: {Active, Draft, Cancelled, Provisioning, Expired, Migrated, Suspended, StandingOrder} | This is the status of this subscription. Draft indicates that the Subscription has not yet been activated. Provisioning indicates this Subscription has been provisioned but that the Setup Fee and recurring Charge has not been applied to the Customer. To set a Subscription as "Provisioned" you must set a Scheduled Activation Date for some time in the future. |
reference | String | This is a text field you can populate with reference text for this subscription. This field is not exposed on the Invoice. [Max Length: 255 characters] |
subscriptionOverride | Object. Defined below | This represents a subscription-level override made after the object's creation. |
hasPostedInvoice | Boolean | This indicates if this Subscription has caused an invoice to be created and posted against the Customer's account. [Read Only] |
CreatedTimestamp | DateTime | This indicates when the Subscription was created. [Read Only] |
ActivatedTimestamp | DateTime | This indicates when the Subscription was activated. [Read Only] |
ProvisionedTimestamp | DateTime | This indicates when the Subscription was provisioned. [Read Only] |
NextPeriodStartDate | DateTime | This indicates when the next billing period for the Subscription will begin. Normally, this indicates when the subscription will bill and apply charges to the customer's account. [Read Only] |
lastPeriodStartDate | DateTime | This is the timestamp of when the previous period started for this subscription if there was a previous period. [Read Only] |
ScheduledActivationTimestamp | DateTime | If set, this indicates when the Subscription should activate. The subscription will automatically be set to an "Active" status at this time if it has been set to status "Provisioned". |
subscriptionProducts | List of Objects. See the Subscription Products Object section for the definition. | The list of subscription products on the purchase, both included and excluded. |
remainingInterval | Integer | This is the remaining number of billing intervals in the lifetime of this subscription. If this value is set to null the subscription will renew indefinitely. If this is set to a number then after that number of intervals have passed the subscription will go to the "Expired" status automatically and stop charging the customer. |
remainingIntervalPushOut | Integer | This is the setting to default what the new remaining interval should be when the subscription is renewed. |
openSubscriptionPeriodEndDate | DateTime | This is the date that the current billing period will end. Often, this field will match the nextPeriodStartDate value. |
customFields | List of Objects. See Catalog: Custom Fields for object definition. | Custom fields hold additional data. This data is associated with the subscription. |
planAutoApplyChanges | Boolean | This field related to Grandfathering control. If true, this indicates that the Plan from which this Subscription is made usually pushes changes to the Plan down to existing Subscriptions - this forces existing customers onto the newest version of the Plan. If set to False, this 'grandfathers' the Customer into the version of the Plan they Subscribed to and does not push changes. [Read Only] |
autoApplyCatalogChanges | Boolean | This field controls if this specific Subscription should automatically push changes to the underlying Plan to this Subscription. If set to True, changes will be pushed automatically. If False, this Subscription will not reflect updates to the Plan from which it was made. |
monthlyRecurringRevenue | Decimal | The calculated monthly recurring revenue value being generated by this subscription [Read Only] |
netMonthlyRecurringRevenue | Decimal | The net MRR being generated by this subscription [Read Only] |
amount | Decimal | The amount of the subscription. [Read Only] |
contractStartTimestamp | DateTime | This is the date that the contract period will begin. |
contractEndTimestamp | DateTime | This is the date that the contract period will end. |
expiredTimestamp | DateTime | The timestamp of when this subscription expired if it is in status "Expired" [Read Only] |
cancellationTimestamp | DateTime | The timestamp of when this subscription became cancelled if it is in status "Cancelled" [Read Only] |
modifiedTimestamp | DateTime | The timestamp of the last modification to this entity. [Read Only] |
coupons | List of Objects. See Subscriptions: Coupons Object for details. | The list of coupons that have been applied to this subscription |
invoiceDay | Integer | The day of the month recharge occurs for this subscription. [Read Only] |
invoiceMonth | Integer | Tells the system to create a billing period that cycles on the specified month. Typically only used for yearly frequencies. If this parameter is used for a monthly frequency, Fusebill will adjust the billing period such that the subscription will recharge on the provided day and month. [Read Only] |
canMigrate | Boolean | True as long as their is at least one plan family relationship with this subscription's plan code as the source. [Read Only] |
migrationDate | DateTime | The timestamp when this subscription entered status "Migrated" [Read Only] |
scheduledMigrationDate | DateTime | The timestamp of when the scheduled migration for this subscription will occur if a migration has been scheduled. |
migrations | Object. Defined below. | A summary of the migration which resulted in this subscription, and the migration which was sourced from this subscription. Possibly null if the subscription is not associated to any migrations. |
subscriptionHasRecurringEndOfPeriodCharge | Boolean | True if the subscription has a recurring end of period charge |
nextRechargeDate | DateTime | The timestamp for when this subscription will recharge next. |
billingPeriodDefinitionId | Integer | The Fusebill generated ID that uniquely identifies the associated billing period definition. [Read Only] |
salesforceId | String | The Salesforce ID of the subscription in Salesforce that this object maps to. This is for the Salesforce plugin. |
id | Integer | The Fusebill generated ID that uniquely identifies this subscription [Read Only] |
uri | String | The full string path to this resource [Read Only] |
PlanFrequency Fields
| Property | Type | Description |
|---|---|---|
planRevisionId | Integer | This is the unique identifier for this plan revision [Read Only] |
numberOfIntervals | Integer | This is the number of intervals that this plan will renew for [Read Only] |
interval | Enum:{Yearly, Monthly} | The unit of measurement used for defining billing periods [Read Only] |
numberOfSubscriptions | Integer | This is the number of instances of this plan currently in the system as subscriptions [Read Only] |
status | Enum: {Draft, Active, Retired} | Indicates the status of the plan this subscription was sourced from. [Read Only] |
isProrated | Boolean | This indicates if this Subscription should prorate its charges if activated in the middle of a billing cycle. [Read Only] |
prorationGranularity | Enum:{Monthly, Daily} | This defines how granular the proration calculations are [Read Only] |
planFrequencyUniqueId | Integer | This is an internal identifier. [Read Only] |
remainingInterval | Integer | The default remaining interval for the plan. This is the number of periods before expiry. This can be overwritten or pushed out on the subscription [Read Only] |
salesforceId | String | The ID of the Salesforce price book this plan frequency is associated with in Salesforce. This is for the Salesforce plugin. |
id | Integer | This is the Fusebill generated ID for this plan frequency. [Read Only] |
uri | String | This is full string path to this resource. [Read Only] |
Subscription Override Properties
| Property | Type | Description |
|---|---|---|
name | String | This is the value which will override the planName field value on the subscription. This override value will appear on invoices and in other customer facing locations.[Max Length: 100 characters] |
description | String | This is the value which will override the planDescription field value on the subscription. This override value will appear on invoices and in other customer facing locations.[Max Length: 500 characters] |
id | Integer | The Fusebill generated ID that uniquely identifies this subscription [Read Only] |
uri | String | The full path to this subscription [Read Only] |
Migrations Object
| Property | Type | Description |
|---|---|---|
sourceSubscriptionId | Integer | The Fusebill generated ID of the subscription which migrated to become this subscription. |
sourceRelationshipMigrationType | Enum: {Upgrade, Downgrade, PlanUpdate, FrequencyChange, FreeTrialConversion, Other} | An enum used to describe the general purpose and context of the source migration |
sourceRelationshipId | Integer | The Fusebill generated plan family relationship ID used for the source migration |
destinationSubscriptionId | Integer | The Fusebill generated ID of the subscription which this subscription migrated to become. |
destinationRelationshipMigrationType | Enum: {Upgrade, Downgrade, PlanUpdate, FrequencyChange, FreeTrialConversion, Other} | An enum used to describe the general purpose and context of the destination migration |
destinationRelationshipId | Integer | The Fusebill generated plan family relationship ID used for the destination migration |