Documentation

1Products and Product References

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.

1.1Create Products via the Backend

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.

1.2Create Products via the API

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.

1.2.1Example Request

{
	"failedPaymentSuspensionPeriod": "P:P1M",
	"id": 0,
	"name": "payment service",
	"reference": "payment-service"
}

1.2.2Example Response

{
	"allowedPaymentMethodConfigurations": [],
	"failedPaymentSuspensionPeriod": "P:P1M",
	"id": 3,
	"linkedSpaceId": 1,
	"name": "payment service",
	"plannedPurgeDate": null,
	"reference": "payment-service",
	"sortOrder": 0,
	"spaceId": 1,
	"state": "ACTIVE",
	"version": 1
}

2Product Versions

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.

2.1Create Product Versions

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.

iframe
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
}

2.2Components and Component Groups

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.

iframe
Figure 2. Create Component Groups in the Backend.

2.3Web Service

All the operations can also be triggered via the web service API.

2.3.1Create Subscription Product Component Group Service

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
}

2.3.2Subscription Product Component Service

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
    }
}

3Fees

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.

3.1Setup Fee

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.

iframe
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

3.2Period Fees

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.

iframe
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

3.3Metered Fee

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).

3.3.1Create a Metric

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.

3.3.2Tier Pricing

You do also have the option to define special Tier Prices for metered fees. There are two calculation methods:

  1. 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.

  2. 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.

iframe
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.

iframe
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.

4Retire Product Versions

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.

4.1Retire Product Versions From the Backend

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.

iframe
Figure 7. Retire product versions from the backend.

4.2Web Service API

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.

4.2.1Request & Response

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
}

5Retire Products

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.

5.1Retire Products From the Backend

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.

iframe
Figure 8. Retire products from the backend.

5.2Web Service API

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
}