Subscriptions from Proposal Object
Overview
Subscriptions behavior in the CPQ flow.
How Subscriptions Work in the CPQ Flow
Initial Deal
When a new order is placed in the CPQ App, an API call is made to place a new order that will also contain the details of the INITIAL_DEAL. Additionally, the new order could also contain the B2B flag, which will be saved in the sales_additional_information table. If the order is flagged as B2B, when the subscription for this order is generated, it will also be set at the subscription level in the licences_additional_information table.
When a renewal (auto or manual, from any flow) or an upgrade (either silent upgrade or manual upgrade) is performed on a subscription that has the B2B flag set in the licences_additional_information table, this flag will also be associated with the renewal/upgrade order from the start (from the moment the order is placed, so this flag will be set even when the order is pending).
The INITIAL_DEAL details sent through the placeOrder call via the 2Checkout API are validated and then passed on to the core platform and inserted in the licences_scheduled_settings SQL table. By validation, the field attributes from the INITIAL_DEAL API call are the same as on the order:
- IdProduct
- PriceOptionCodes
- CustomUnitPrice
- CustomPriceType
- Quantity
- Currency
The other fields can be different than those in the catalog product's settings.
An INITIAL_DEAL record for the API call will look like in this example:
{
"IdLicencesScheduledSettings" : {primary key, auto-incremented at insert},
"IdSale" : {IdSale of the newly created order},
"LicenceCode" : {empty string},
"EventType" : "INITIAL_DEAL",
"ImmediateAction" : 0,
"IdProduct" : 7628649,
"PriceOptionCodes" : "OptGrp2Code1",
"CustomUnitPrice" : "88.8",
"CustomPriceType" : "GROSS",
"Quantity" : 1,
"Currency" : "USD",
"ContractPeriod" : 48,
"ContractUnit" : "MONTH",
"RenewalInterval" : 6,
"RenewalIntervalUnit" : "MONTH",
"ActionAfterCycles" : "CANCEL",
"ExternalIdentifier" : "APIv6ProposalId",
"DateAdded" : "2020-03-17T08:48:18Z",
"DateProcessed" : null,
"DateCancelled" : null,
"Autostamp" : "2020-03-18T11:23:33Z"
}
After the order is saved in the database, the normal flow of approval/completion of the order is resumed.
When the subscription for this order is generated (the moment when this is done can differ based on the set-up of the vendor/product), the following actions are triggered:
- the INITIAL_DEAL details are used for the subscription instead of the normal details;
- the subscription is generated with these custom deal details;
- the record in the licences_scheduled_settings mentioned above is updated like this:
- the LicenceCode field will be updated and will now store the LicenceCode of the subscription;
- the DateProcessed field will be marked with the date when this update is made;
The method that was changed so that the details from the INITIAL_DEAL are taken into account instead of the catalog product's details is COrderBase → GenerateNewLicence.
For a detailed list of the replaced fields (and where they were taken from before), have a look at the COrderBase → GenerateNewLicence method.
Once the subscription is successfully generated, the deal's details are saved on it and the following renewals will be made taking into account these settings, instead of the catalog product's settings.
Renew Deal
Let's assume that a merchant sends an "Initial Deal" proposal to a client with a contract period of 12 months. At the end of those 12 months any subscription generated by that “Initial Deal” will stop the auto-recurring billing process (this option is configurable). In order to prevent this, the merchant can send a "Renew Deal" proposal to their customer.
When the proposal is accepted by the customer, an API call is triggered, which will save the info from that proposal in the 2Checkout database (table: licences_scheduled_settings).
A “Renew Deal” proposal translates into an entry like this:
{
"IdLicencesScheduledSettings" : 10,
"IdSale" : null,
"LicenceCode" : "8E292180CB",
"EventType" : "RENEW_DEAL",
"ImmediateAction" : 0,
"IdProduct" : 7628649,
"PriceOptionCodes" : "OptGrp2Code1",
"CustomUnitPrice" : "88.8",
"CustomPriceType" : "GROSS",
"Quantity" : 1,
"Currency" : "USD",
"ContractPeriod" : 48,
"ContractUnit" : "MONTH",
"RenewalInterval" : 6,
"RenewalIntervalUnit" : "MONTH",
"ActionAfterCycles" : "CANCEL",
"ExternalIdentifier" : "APIv6ProposalId",
"DateAdded" : "2020-03-17T08:48:18Z",
"DateProcessed" : null,
"DateCancelled" : null,
"Autostamp" : "2020-03-18T11:23:33Z"
}
When a renewal (auto or manual) is made, if this is the last renewal in the current contract, two scenarios can happen:
- there is a pending renewal deal, and in this case the subscription contract will be “extended”;
- there is no pending renewal deal, and in this case no next billing date will be set, and the subscription will expire at the end of the current billing cycle.
For the 1st scenario the following actions take place:
- A renewal order is created using the information from the renewal deal.
- The order is then saved and an order ID is generated.
- The renewal deal is updated with the order ID.
- The license is renewed using the information from the renew deal.
- The “custom tables” are populated with the corresponding data from the renewal deal (licences_custom_renewal_settings, licences_custom_prices).
- Finally, the renewal deal is marked as processed.
Through the renewal deal proposal a merchant can change the following properties for a subscription:
- CustomUnitPrice
- CustomPriceType
- ContractPeriod
- ContractUnit
- RenewalInterval
- RenewalIntervalUnit
- ActionAfterCycles
- PriceOptionCodeS
Upgrade Deal
An upgrade deal implies two potential scenarios:
- Upgrade deal with immediate action
- Upgrade deal with action at the end of the billing cycle
For the 2nd scenario, upgrade deal with action at the end of the billing cycle, the upgrade is similar to the renew deal, but instead of it being processed only on the last renewal cycle in the contract, it will be processed at the end of the current billing cycle (at the next renewal, auto or manual).
Also, the merchant can use an upgrade deal to change the product on the subscription.
Price Type
On B2B deals, there is a need to have the price type configured on the proposal (both gross or net price).
To achieve that, the CustomPriceType column was added on the licences_custom_prices and assigned a value only for B2B deals. For the B2C deals, the field will have NULL value.
The custom price is added into licences_custom_prices at the moment of the license renewal (the renewLicence method from COrderBase).
The row inserted into licence_history will include the CustomPriceType.
Wherever the price for the subscription is displayed (2Checkout MyAccount, Merchant Control Panel), the price should be the one from the licences_custom_prices table for B2B licenses and from price configuration for B2C licenses.
