SubscriptionMgt_SM_TSL (Codeunit)
SubscriptionMgt_SM_TSL codeunit contains all the code blocks for the integration aspect of the Subscription Management app. It comprises multiple functions as described below.
Before progressing, please ensure that the Subscription Management extension is installed into your development environment and the right dependency has been defined in your extension's app.json
:
{
"id": "6717135a-d80c-4a63-8a3a-5ded6717135a",
"publisher": "Theta Systems Limited",
"name": "SubscriptionMgt",
"version": "1.0.0.0"
}
Common Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Your Stripe API Secret This key can perform any API request to Stripe without restriction, we highly recommend you leverage a secure vault to safeguard the integrity of your account. |
PublishableKey | Text | Your Stripe Publishable Key This key exists solely to identify your account with Stripe and can be considered a public identified key that can safely remain in source. |
ProductID | Text[100] | Your Stripe Product Identifier The identifier of the product associated with your extension. |
SecretKey, PublishableKey and ProductID values differ across your Stripe account between your test and live modes. Use test values during development/testing and make sure you use your live key in your production-ready package. The easiest way to do this is by replacing the keyVaultUrls values within your continuous integration process.
Integration API
TryAddProduct (Method)
Requests Subscription Management to start handling your extension. It's recommended to call it with OnInstallAppPerDatabase
and OnUpgradePerDatabase
events.
TryAddProduct(Text;Text;ModuleInfo;Text[100]):Boolean
TryAddProduct(SecretKey,PublishableKey,Info,ProductID)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
PublishableKey | Text | Stripe Publishable Key |
Info | ModuleInfo | It's your extension module info object instance. It can be retrieved by using NavApp.GetCurrentModuleInfo(Info) function. |
ProductID | Text[100] | Stripe Product ID |
Returns
Type | Description |
---|---|
Boolean | Indicating whether the operation completed successfully |
Examples
- Install
- Upgrade
codeunit 50000 InstallExt
{
Subtype = Install;
trigger OnInstallAppPerDatabase()
var
SecretProvider: Codeunit "App Key Vault Secret Provider";
SubscriptionMgt: Codeunit SubscriptionMgt_SM_TSL;
Info: ModuleInfo;
[NonDebuggable]
SecretKey: Text;
[NonDebuggable]
PublishableKey: Text;
ProductID: Text[100];
begin
if NavApp.GetCurrentModuleInfo(Info) then
if SecretProvider.TryInitializeFromCurrentApp() then
if SecretProvider.GetSecret('SecretKey', SecretKey) and
SecretProvider.GetSecret('PublishableKey', PublishableKey) and
SecretProvider.GetSecret('MyAppProductID', ProductID)
then
// highlight-start
SubscriptionMgt.TryAddProduct(
SecretKey,
PublishableKey,
Info,
ProductID);
// highlight-end
end;
}
codeunit 50001 UpgradeExt
{
Subtype = Upgrade;
trigger OnUpgradePerDatabase()
var
SecretProvider: Codeunit "App Key Vault Secret Provider";
SubscriptionMgt: Codeunit SubscriptionMgt_SM_TSL;
Info: ModuleInfo;
[NonDebuggable]
SecretKey: Text;
[NonDebuggable]
PublishableKey: Text;
ProductID: Text[100];
begin
if NavApp.GetCurrentModuleInfo(Info) then
if SecretProvider.TryInitializeFromCurrentApp() then
if SecretProvider.GetSecret('SecretKey', SecretKey) and
SecretProvider.GetSecret('PublishableKey', PublishableKey) and
SecretProvider.GetSecret('MyAppProductID', ProductID)
then
// highlight-start
SubscriptionMgt.TryAddProduct(
SecretKey,
PublishableKey,
Info,
ProductID);
// highlight-end
end;
}
TryAddProduct(Text;Text;Guid;Text[100]):Boolean
TryAddProduct(SecretKey,PublishableKey,AppID,ProductID)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
PublishableKey | Text | Stripe Publishable Key |
AppID | Guid | The unique ID of your extension. You can retrieve it from current module info. |
ProductID | Text[100] | Stripe Product ID |
Returns
Type | Description |
---|---|
Boolean | Indicating whether the operation completed successfully |
Examples
- Install
- Upgrade
codeunit 50000 InstallExt
{
Subtype = Install;
trigger OnInstallAppPerDatabase()
var
SecretProvider: Codeunit "App Key Vault Secret Provider";
SubscriptionMgt: Codeunit SubscriptionMgt_SM_TSL;
Info: ModuleInfo;
[NonDebuggable]
SecretKey: Text;
[NonDebuggable]
PublishableKey: Text;
ProductID: Text[100];
begin
if NavApp.GetCurrentModuleInfo(Info) then
if SecretProvider.TryInitializeFromCurrentApp() then
if SecretProvider.GetSecret('SecretKey', SecretKey) and
SecretProvider.GetSecret('PublishableKey', PublishableKey) and
SecretProvider.GetSecret('MyAppProductID', ProductID)
then
// highlight-start
SubscriptionMgt.TryAddProduct(
SecretKey,
PublishableKey,
Info.Id(),
ProductID);
// highlight-end
end;
}
codeunit 50001 UpgradeExt
{
Subtype = Upgrade;
trigger OnUpgradePerDatabase()
var
SecretProvider: Codeunit "App Key Vault Secret Provider";
SubscriptionMgt: Codeunit SubscriptionMgt_SM_TSL;
Info: ModuleInfo;
[NonDebuggable]
SecretKey: Text;
[NonDebuggable]
PublishableKey: Text;
ProductID: Text[100];
begin
if NavApp.GetCurrentModuleInfo(Info) then
if SecretProvider.TryInitializeFromCurrentApp() then
if SecretProvider.GetSecret('SecretKey', SecretKey) and
SecretProvider.GetSecret('PublishableKey', PublishableKey) and
SecretProvider.GetSecret('MyAppProductID', ProductID)
then
// highlight-start
SubscriptionMgt.TryAddProduct(
SecretKey,
PublishableKey,
Info.Id(),
ProductID);
// highlight-end
end;
}
IsActive (Method)
Checks whether the product subscription is in one of the active states (active, trialing, past_due, incomplete, incomplete_expired).
IsActive(Text;Text[100]):Boolean
IsActive(SecretKey,ProductID)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
Returns
Type | Description |
---|---|
Boolean | Indicates whether product subscription is in one of the active states (active, trialing, past_due, incomplete, incomplete_expired) |
Examples
pageextension 50000 MyExtension extends "Customer Card"
{
trigger OnOpenPage()
begin
CurrPage.Editable := IsActive()
end;
[NonDebuggable]
procedure IsActive(): Boolean
var
SecretProvider: Codeunit "App Key Vault Secret Provider";
SubscriptionMgt: Codeunit SubscriptionMgt_SM_TSL;
SecretKey: Text;
ProductID: Text[100];
begin
if SecretProvider.TryInitializeFromCurrentApp() then
if SecretProvider.GetSecret('SecretKey', SecretKey) and
SecretProvider.GetSecret('MyAppProductID', ProductID)
then
// highlight-next-line
exit(SubscriptionMgt.IsActive(SecretKey, ProductID));
end;
}
IsTrialing (Method)
Returns whether a subscription is currently under a trial period.
IsTrialing(Text;Text[100]):Boolean
IsTrialing(SecretKey,ProductID)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
Returns
Type | Description |
---|---|
Boolean | Indicates whether a subscription is currently under a trial period. |
Examples
pageextension 50000 MyExtension extends "Customer Card"
{
trigger OnOpenPage()
begin
CurrPage.Editable := IsTrialing()
end;
[NonDebuggable]
procedure IsTrialing(): Boolean
var
SecretProvider: Codeunit "App Key Vault Secret Provider";
SubscriptionMgt: Codeunit SubscriptionMgt_SM_TSL;
SecretKey: Text;
ProductID: Text[100];
begin
if SecretProvider.TryInitializeFromCurrentApp() then
if SecretProvider.GetSecret('SecretKey', SecretKey) and
SecretProvider.GetSecret('MyAppProductID', ProductID)
then
// highlight-next-line
exit(SubscriptionMgt.IsTrialing(SecretKey, ProductID));
end;
}
GetPriceName (Method)
Returns name of the user selected plan. Returns ''
if no plan is selected.
GetPriceName(Text;Text[100]):Text
GetPriceName(SecretKey,ProductID)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
Returns
Type | Description |
---|---|
Text | Returns a name of a price which user selected for this product |
ShowNotification (Method)
Force Subscription Management to show a notification to the user to act on the subscription. It will return false if there is nothing to show.
ShowNotification(Text;Text[100]):Boolean
ShowNotification(SecretKey,ProductID)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
Returns
Type | Description |
---|---|
Boolean | Indicates if any notification shows |
Examples
pageextension 50000 MyExtension extends "Customer Card"
{
trigger OnOpenPage()
begin
CurrPage.Editable := IsActive()
end;
[NonDebuggable]
procedure IsActive(): Boolean
var
SecretProvider: Codeunit "App Key Vault Secret Provider";
SubscriptionMgt: Codeunit SubscriptionMgt_SM_TSL;
SecretKey: Text;
ProductID: Text[100];
begin
if SecretProvider.TryInitializeFromCurrentApp() then
if SecretProvider.GetSecret('SecretKey', SecretKey) and
SecretProvider.GetSecret('MyAppProductID', ProductID)
then
if SubscriptionMgt.IsActive(SecretKey, ProductID) then
exit(true)
else
// highlight-next-line
SubscriptionMgt.ShowNotification(SecretKey, ProductID);
end;
}
Quantity API
CountProductLines (Method)
Returns the current quantity of the specified product. Default return value is 1
if the quantity could not be found.
CountProductLines(Text;Text[100]):BigInteger
CountProductLines(SecretKey,ProductID)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
Returns
Type | Description |
---|---|
BigInteger | Current quantity of the product |
GetProductLines (Method)
Returns the list of current quantity lines.
GetProductLines(Text;Text[100];var Dictionary of [Text,JsonObject]):Boolean
GetProductLines(SecretKey,ProductID,ProductLines)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
ProductLines | Dictionary of [Text, JsonObject] | TBD |
Returns
Type | Description |
---|---|
Boolean | Returns true if operation has been successful |
SetProductLines (Method)
Updates the list of current quantity lines.
SetProductLines(Text;Text[100];Dictionary of [Text,JsonObject]):Boolean
SetProductLines(SecretKey,ProductID,ProductLines)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
ProductLines | Dictionary of [Text, JsonObject] | TBD |
Returns
Type | Description |
---|---|
Boolean | Returns true if operation has been successful |
SetProductLines(Text;Text[100];Boolean;Dictionary of [Text,JsonObject]):Boolean
SetProductLines(SecretKey,ProductID,ResetBillingCycle,ProductLines)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
ResetBillingCycle | Boolean | if true , it resets the subscription’s billing cycle anchor to the current time. If false , the quantity changes will be applied to a next invoice date. |
ProductLines | Dictionary of [Text, JsonObject] | TBD |
Returns
Type | Description |
---|---|
Boolean | Returns true if operation has been successful |
SetProductLines(Text;Text[100];Dictionary of [Text,JsonObject];Boolean):Boolean
SetProductLines(SecretKey,ProductID,ProductLines,ShowConfirmation)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
ProductLines | Dictionary of [Text, JsonObject] | TBD |
ShowConfirmation | Boolean | If true , the confirmation dialog pops up with upcoming invoice information and information about what the next payment will look like and asks the user to proceed. |
Returns
Type | Description |
---|---|
Boolean | Returns true if operation has been successful |
SetProductLines(Text;Text[100];Boolean;Dictionary of [Text,JsonObject];Boolean):Boolean
SetProductLines(SecretKey,ProductID,ResetBillingCycle,ProductLines,ShowConfirmation)
Parameters
Name | Type | Description |
---|---|---|
SecretKey | Text | Stripe Secret Key |
ProductID | Text[100] | Stripe Product ID |
ResetBillingCycle | Boolean | if true , it resets the subscription’s billing cycle anchor to the current time. If false , the quantity changes will be applied to a next invoice date. |
ProductLines | Dictionary of [Text, JsonObject] | TBD |
ShowConfirmation | Boolean | If true , the confirmation dialog pops up with upcoming invoice information and information about what the next payment will look like and asks the user to proceed. |
Returns
Type | Description |
---|---|
Boolean | Returns true if operation has been successful |