{
"failedPaymentSuspensionPeriod": "P:P1M",
"id": 0,
"name": "payment service",
"reference": "payment-service"
}A subscription product represents a product to which a subscriber can subscribe to. A product defines how much the subscription costs and in what cycles the subscriber is charged.
You can create new products inside your space under Space > Subscriptions > Products.
A product consists of a general product configuration and product versions. In the general product configuration you set the basic settings such as allowed payment methods or whether you want to activate the email delivery by the platform including the templates which should be used to communicate with your subscribers.
Product versions represent different configurations of a product. Per product there can be only one active
product version. Means a product version represents a set of configurations like prices etc. of a product. When
changes should be applied to the product a new product version has to be created. See below more information
about product versions.
Products can also be created via the API. In order to do this you have to use the Subscription Product Service.
In the example below we created a new product called payment service and the reference payment-service.
Your subscribers subscribe to a product version of your product that represents a price and component setup at a given time.
Once you activate a product version you can no longer make any changes to the product version. However by duplicating the
product version you can create a new product version in the pending state with the same configuration as the original one but
with the possibility to apply changes on it.
This allows you to manage your subscribers in different product versions. When your products evolve you are able to manage
the active contracts.
When you create a new product version it will automatically switch into the pending state. The pending state
allows you to change and configure the product as you like. Once the configuration is done you have to activate
the product version in order to let your customer subscribe to it.
There can only be one active product version where your subscribers can subscribe to. By activating a new product version
the current active version will be marked as obsolete. Product versions that are in the state obsolete
can no longer be subscribed to. However, the subscriber of the product version will be billed according your
billing schedule and the subscribers are not forced to move to the current active version.
Once you created a product you can create the product version by opening your product and click on Create Product Version. This will open a page where you can specify Billing Period, Notice Period, Allowed Currencies, etc.
Figure 1. Create Product Versions via the backend.
Product Versions can also be created via the API. In order to do this you have to use the Subscription Product Version Service.
Request
|
Note
|
The product id in the example below is retrieved from the response in the request above where you
created the product.
|
{
"billingCycle": "P:P1M",
"defaultCurrency": "EUR",
"name": {
"items": [
{
"language": "En",
"translation": "payment-service"
}
]
},
"numberOfNoticePeriods": 1,
"product": {
"id": 3
}
}Response
{
"billingCycle": "P:P1M",
"defaultCurrency": "EUR",
"enabledCurrencies": [
"EUR"
],
"id": 4,
"incrementNumber": 1,
"linkedSpaceId": 1,
"minimalNumberOfPeriods": 1,
"name": {
"availableLanguages": [
"en-US"
],
"id": 20,
"items": [
{
"id": 24,
"language": "en-US",
"languageCode": "en",
"translation": "payment-service",
"version": 0
}
],
"version": 0
},
"numberOfNoticePeriods": 1,
"product": {
"allowedPaymentMethodConfigurations": [],
"failedPaymentSuspensionPeriod": "P:P1M",
"id": 3,
"linkedSpaceId": 1,
"name": "payment service",
"plannedPurgeDate": null,
"reference": "payment-service",
"sortOrder": 0,
"spaceId": 1,
"state": "ACTIVE",
"version": 1
},
"reference": "payment-service-1",
"state": "PENDING",
"version": 0
}A product version consists of components and component groups. A component group contains one or more components. A component represents a specific feature of the product. When there are multiple components per component group the subscriber can select to which of the components he or she wants to subscribe to. Essentially components and component groups allows to create configurable subscription products.
Example
Product Example
For example in the case of a SaaS product there might be different levels of support provided like basic support, phone support or
enterprise support. The assumption is that a subscriber can only subscribe to one of the support levels at once.
To represent this example a component group for support has to be created with three components for each of those levels. Since product components can be linked with fees the different support levels can be charged differently. A component group can be also optional. In the above example this allows to represent the situation when the subscriber has no support at all.
Components itself contain additional settings. The most important setting is the product component reference that allows to identify the component in different product versions. Means the reference links different components together. A reference can only be linked with one product version. When the subscription is changed to another product version - it is not relevant if the versions belong to the same product or not - the product component references allows to identify if the change is a upgrade or a downgrade which reimburses the setup fees (more information under Subscriptions).
Product component reference can be created under Space > Subscription > Configuration > Product Component References. In general it is recommend to name the references like the component groups.
Figure 2. Create Component Groups in the Backend.
All the operations can also be triggered via the web service API.
In order to create a Component Group you have to use the Subscription Product Component Group Service.
Request
{
"name": {
"items": [
{
"language": "English",
"translation": "Base-Settings"
}
]
},
"productVersion": {
"id": 4
}
}Response
{
"id": 1,
"linkedSpaceId": 1,
"name": {
"availableLanguages": [
"en-US"
],
"id": 1,
"items": [
{
"id": 1,
"language": "en-US",
"languageCode": "en",
"translation": "test-payment",
"version": 0
}
],
"version": 0
},
"optional": false,
"productVersion": {
"activatedOn": null,
"billingCycle": "P:P1M",
"comment": "",
"createdOn": "2017-04-23T11:47:21.869Z",
"defaultCurrency": "EUR",
"enabledCurrencies": [
"EUR"
],
"id": 1,
"incrementNumber": 1,
"linkedSpaceId": 1,
"minimalNumberOfPeriods": 1,
"name": {
"availableLanguages": [
"en-US"
],
"id": 1,
"items": [
{
"id": 1,
"language": "en-US",
"languageCode": "en",
"translation": "test-payment",
"version": 0
}
],
"version": 0
},
"numberOfNoticePeriods": 1,
"obsoletedOn": null,
"plannedPurgeDate": null,
"product": {
"allowedPaymentMethodConfigurations": [],
"failedPaymentSuspensionPeriod": "P:P1M",
"id": 1,
"linkedSpaceId": 1,
"name": "test-payment",
"plannedPurgeDate": null,
"reference": "test-payment",
"sortOrder": 0,
"spaceId": 1,
"state": "ACTIVE",
"version": 1
},
"reference": "test-payment-1",
"retiringFinishedOn": null,
"retiringStartedOn": null,
"state": "PENDING",
"version": 0
},
"sortOrder": 0,
"version": 0
}In order to create a Component you have to use the Subscription Product Component Service.
Request
{
"componentGroup": {
"id": 3
},
"name": {
"items": [
{
"language": "English",
"translation": "Base"
}
]
},
"reference": {
"id": 3
},
"taxClass": {
"id": 1
}
}The product fees are attached to a product component and indirectly to a product version. Changes on the product fees are only allowed when the product
version is in the state pending.
In order to create fees you have to open the pending product version and switch into the tab Fees.
Here you can create setup fees, period fees and metered fees for all the allowed currencies in the product configuration.
A setup fee is charged one-time when the subscriber subscribes to a product version and selects the relevant component group. With setup fees you are able to also define amounts that should be debited or credited in case of an up- or downgrade.
The fee has also to be attached to a component. Therefore it is advisable to create a base component that contains the basic product settings.
Figure 3. Create a product setup fee.
This operation can also be triggered via the web service API. In order to do this use the Subscription Product Setup Fee Service
Period fees will be charged every period. You have to define the period fee in all enabled currencies. The fee has also to be attached to a component. Therefore it is advisable to create a base component that contains the basic product settings.
Figure 4. Create a product period fee.
This operation can also be triggered via the web service API. In order to do this use the Subscription Product Period Fee Service
Metered fees are usage dependent and will be calculated by the platform at the end of the billing period based on the usage reports (for more information visit the chapter about billing).
When you create a metered fee you have to define a metric first. Metrics can be created under Subscriptions > Configurations > Metrics. You have the option between the sum of all usage reports or the average. In our example with the payment transaction you would use the sum over all usage reports. In this case all reports will be summarized and multiplied by the price of the metered fee. You want to use the average over usage reports in case the price is dependent on a number of active configurations for example for the number of active subscriber during the period. In this case the platform will create the aritmetric average over all usage reports.
You do also have the option to define special Tier Prices for metered fees. There are two calculation methods:
-
The incremental discount pricing will multiply the usage of each tier and sum them up. So if you have a special price above 1'000 transactions the system will apply the standard price for transaction 1 to 1'000 and then use the lower price for the transactions above 1'001 in the billing period.
-
The cheapest tier pricing will directly apply the tier that is relevant. So in case you have a special transaction price for above 1'000 transaction and you reported 1'500 Transactions, the system will directly apply the cheaper tier price for all 1'500 transactions.
Figure 5. Define the basic settings for the product metered fee.
Once the metered fee is created you can add tier prices inside the fee configuration by clicking on Create Tier.
Figure 6. Define tiers for the metered fees.
Metered fees allow you to specify a price per consumed unit. You simply report the consumed units and we calculate based up on the predefined price within the product how much we have to charge. By defining the tier price you can either define the price per consumed unit for your metric (e. g. price for payment transactions) but you can also use this to apply a percentage based pricing. In this case the tier price represents the percentage points that you want to charge (see example below).
Example
Use Tier Prices For Percentage Prices
Let’s assume you want to charge your client a percentage fee of his turnover and a merchant has sold goods for 1500.- EUR.
In this case you just create a Metric Report and report the consumed price as consumed units after each transaction.
Let’s say you want to charge 2% on the transaction amount you can configure a price of 0.02 within the product. We will multiply the configured price with the reported consumed transaction units. In our case this is 1500 * 0.02 which corresponds to 30 EUR. So we would charge at the end of the period 30 EUR to your subscriber.
There is one issue you have to keep in mind: When you allow the merchant to sell things in different currencies you get a mess. Either you have to setup for each currency a metric or you have to convert the transaction amount into the subscription currency before you report it to us. I would recommend using the later approach. It is simpler and it does not require to setup multiple metrics.
The metered fees are automatically calculated based on the usage reports you created. More information regarding usage report can be found in the billing and charging.
Now as the product version is configured you can set it to active in the version overview.
Product versions can be retired in case you do not want to bill and support a product version anymore. In this
case the product version will be retired and existing subscribers will be migrated to another product version
or product.
|
Note
|
Please be aware you can either retire the whole product or the product version. If you want to retire the whole product you have to use the Subscription Product Retirement Service. More Information about that can be found below. |
In case you click Retire you will be asked whether you want to respect the termination period and which product you want to migrate the subscribers to. In case the termination period is not respected your subscribers will directly be migrated to the defined product or to the active product version in case no target is provided.
Figure 7. Retire product versions from the backend.
You can also retire product version via the web service. In order to do that you have to use the Subscription Product Version Retirement Service.
Request
{
"productVersion": {
"id": 4
},
"respectTerminiationPeriodsEnabled": true
}Response
{
"createdOn": "2017-04-27T21:00:04.684Z",
"id": 4,
"linkedSpaceId": 1,
"productVersion": {
"activatedOn": "2017-04-25T07:57:06.013Z",
"billingCycle": "P:P1M",
"comment": "",
"createdOn": "2017-04-25T07:56:27.455Z",
"defaultCurrency": "EUR",
"enabledCurrencies": [
"EUR"
],
"id": 4,
"incrementNumber": 1,
"linkedSpaceId": 1,
"minimalNumberOfPeriods": 1,
"name": {
"availableLanguages": [
"en-US"
],
"id": 50,
"items": [
{
"id": 54,
"language": "en-US",
"languageCode": "en",
"translation": "Payment Product",
"version": 0
}
],
"version": 0
},
"numberOfNoticePeriods": 1,
"obsoletedOn": "2017-04-26T14:32:27.964Z",
"plannedPurgeDate": "2017-04-27T23:00:04.69+02:00[Europe/Zurich]",
"product": {
"allowedPaymentMethodConfigurations": [],
"failedPaymentSuspensionPeriod": "P:P1M",
"id": 2,
"linkedSpaceId": 1,
"name": "Payment Product",
"reference": "test-1",
"sortOrder": 0,
"spaceId": 1,
"state": "ACTIVE",
"version": 0
},
"reference": "test-1-1",
"retiringStartedOn": "2017-04-27T21:00:04.69Z",
"state": "RETIRING",
"version": 3
},
"respectTerminiationPeriodsEnabled": false,
"version": 0
}Products can be retired in case you do not want to bill and support a product anymore. In this
case the product including all active and obsolete product versions will be retired and existing subscribers will be terminated.
In case a target product is provided, they will be migrated to that product.
You can retire products directly from the backend. For this you have to navigate to Space > Subscriptions > Products. Here you are able to open the product and click on retire. This will start the retirement process once you specified whether you want to respect the termination period and the target product.
Figure 8. Retire products from the backend.
You can also retire product version via the web service. In order to do that you have to use the Subscription Product Retirement Service.
Request
{
“product”: {
“id”: 1
},
“respectTerminiationPeriodsEnabled”: true
}Response
{
“createdOn”: “2017-04-23T12:18:37.722Z”,
“id”: 1,
“linkedSpaceId”: 1,
“product”: {
“allowedPaymentMethodConfigurations”: [],
“failedPaymentSuspensionPeriod”: “P:P1M”,
“id”: 1,
“linkedSpaceId”: 1,
“name”: “Payment Product”,
“plannedPurgeDate”: “2018-05-19T15:58:42.598Z”,
“reference”: “test”,
“sortOrder”: 0,
“spaceId”: 1,
“state”: “RETIRED”,
“version”: 4
},
“respectTerminiationPeriodsEnabled”: false,
“targetProduct”: null,
“version”: 0
}