Subscription guide
Guide to creating and changing subscriptions
Orders are intricate structures with various levels and fields that behave differently based on use cases. This section outlines the fundamentals for creating and modifying subscriptions via the API.
This guide uses endpoints found in API v2 Subscriptions
Creating a Subscription
To create a minimal subscription, reference an existing account. This generates a draft subscription without products, starting on the first of the next month.
Account: Reference to an existing accountStatus: Specify if it’s a draft or if it should be activated. If Activate, a product is requiredEffectiveStartDate: Date of when the subscription starts. The first of next month is set by defaultCurrency: Specified currency for the order. If not set, the account currency will be used by default.Products: List of order products to create.
Request example for creating an active order with an order product based on P-000001:
{
"account": "A-000002",
"status": "active",
"effectiveStartDate": "2025-07-01",
"currency": "SEK",
"products": [
{
"product": "P-000001"
}
]
}Fields that reference related entities like product and account In this case are called lookup keys and provide functionality to reference an entity in different ways eg. using an entity number. The developer resources describe these in more detail.
Adding order products and order charges
An active subscription must include at least one order product, listed in the request with the required product field from the product catalog. By default, the order product inherits values from the product and its initial charge plan. These can be modified, and the order charges can be explicitly defined as shown below, referencing the charge field. For products of type MultipleChargePlans or Full it's recommended to specify the charge plan in the request.
Product: Reference to an existing product from the product catalogChargePlan: Reference to a charge plan on the referenced product
{
"account": "A-000002",
"status": "active",
"effectiveStartDate": "2025-07-01",
"currency": "SEK",
"products": [
{
"product": "P-000001",
"chargePlan": "CP-000001",
"charges": [
{
"charge": "C-000001",
"quantity": 20
}
]
}
]
}The order product is created using charges from the charge plan and the order's currency details (or the account's currency). In this case quantity is set explicitly overwritten from the charge's default values, and therefore, both a reference to the charge plan and the charge are required.
The referenced charge must exist on the referenced charge plan, and product. else, a validation error will be thrown.
Defining price details on the order charge
In certain situations, you need to set new price details, overwriting the default from the charge. This is done using the priceDetails field.
When setting new price details, no default values from the existing charge will be applied. Therefore, if a charge includes a tiered pricing structure, every tier must be explicitly specified in the request. The charge model and type logic will apply to the new price details. The following example demonstrates how to define price details and what fields can be set.
{
"account": "A-000002",
"status": "active",
"effectiveStartDate": "2025-07-01",
"currency": "SEK",
"products": [
{
"product": "P-000001",
"chargePlan": "CP-000001",
"charges": [
{
"charge": "C-000002",
"quantity": 20,
"priceDetails": [
{
"price": 700,
"listPrice": 700,
"toQuantity": 0,
"tier": 0,
"description": "Price description",
"priceBase": "flat",
}
]
}
]
}
]
}Price details and Discount
In the price detail request, only one of the following fields should be set as they are interrelated and managed automatically: price, linediscountAmount, or lineDiscountPercent. If none are specified, the default ListPrice will be used.
ListPrice: The list price and the basis for the price and discountsprice: The actual price used and calculated after discounts.LineDiscountPercent: Discount in percentLineDiscountAmount: Discount amount
Tiered price details
In a flat or quantity charge model, only one price detail is allowed. The fields tier or toQuantity do not affect these models.
For volume or tiered models, consider the following rules when adding multiple price detail tiers:
The
tierfield, indicating the order of price details, is crucial.The tier index must start at 0 and increase by 1 for each successive tier. Skipping an index will return a validation error.
Each
toQuantitymust exceed that of the previous tier. ThefromQuantity(not directly settable) is calculated accordingly.Set
toQuantityfor each tier, except if the last one hasisInfiniteset to true.If
toQuantityis 0 or less, or not set, it defaults to thefromQuantityvalue or 0 if the tier is 0.isInfinite, when true, only applies to the last tier and overridestoQuantity.
Adding Order Discounts
Discounts can be applied when setting up an order. You can specify the discount percentage, start and end dates, and select which charges will be affected.
If OnSpecificCharges is true, the discount applies only to the specified charges in the order. The orderProductCharges list must be provided in this case. If false, the discount applies to all charges in the order.
{
"account": "A-000002",
"status": "active",
"effectiveStartDate": "2025-07-01",
"currency": "SEK",
"products": [...],
"orderDiscounts": [{
"operation": "create",
"percent": 10,
"onSpecificCharges": false,
"startOn": "alignToOrder",
"endOn": "alignToOrder",
}],
}In the orderProductCharges list, specific charges should correspond to those in the added order products in the request. If the order discount references charges not present in the order, a validation error will occur. The example below illustrates setting order discounts on the charge for “C-000002” only.
{
"account": "A-000002",
"status": "active",
"effectiveStartDate": "2025-07-01",
"currency": "SEK",
"products": [
{
"product": "P-000001",
"chargePlan": "CP-000001",
"charges": [
{
"charge": "C-000002",
"quantity": 20,
}
]
},
{
"product": "P-000002",
"chargePlan": "CP-000004",
"charges": [
{
"charge": "C-000010",
"quantity": 20,
}
]
}
],
"orderDiscounts": [
{
"operation": "Create",
"percent": 5,
"onSpecificCharges": true,
"orderProductCharges": [{
"charge": "C-000002"
}],
}
],
}Change Subscription
When you change a subscription, a new version is created. This change acts as a patch, updating only the components specified in the request payload, while existing elements like order products, order charges, and order discounts that aren't specified will be retained in the new version. However, note that charges on order products may be changed based on changes to the subscription itself.\
Below is an example in which a new order product is added to the subscription, effective from the first of September.
{
"effectiveChangeDate": "2025-09-01",
"products": [
{
"operation": "Create",
"product": "P-000001",
"chargePlan": "CP-000003"
}
]
}Changing, adding, and canceling order products
Order products can be affected by three types of operations: change, create and cancel.
Just like when creating subscriptions, the product and charge fields need to be set and referenced correctly. However, depending on the operation, the source of the reference differs.
When the operation is
create: the source reference will be products and charges from the product catalog.When the operation is
change,cancelorremove: The reference source will be the order products and order charges on existing orders
Create
A new product is added to the subscription. In this case, the product will always reference a product from the product catalog and will follow the same logic as for order products added when creating a subscription.
{
"effectiveChangeDate": "2024-09-01",
"products": [
{
"operation": "Create",
"product": "P-000001",
"chargePlan": "CP-000003"
}
]
}Cancel
Canceling a product requires a reference to the existing order product. Order products cannot be removed, only cancelled.
{
"effectiveChangeDate": "2024-09-01",
"products": [
{
"operation": "Cancel",
"product": "OP-000237",
"CancelProductOn": "specificDate",
"CancelationDate": "2024-09-01"
}
]
}Change
Changing a product requires a reference to the existing order product as well as any reference to the order product charges that will be changed.
{
"effectiveChangeDate": "2024-09-01",
"products": [
{
"operation": "Change",
"product": "OP-000237",
"charges": [
{
"charge": "OPC-000301",
"quantity": 12,
"priceDetails": [
{
"tier": 0,
"price": 89,
"listPrice": 89
}
]
}
]
}
]
}
Price details
Price details on a change follow one of two behaviors:
On a created order charge.
If a new order product with charges is added (operation: create) and price details are defined. The price details will be overwritten and display the same behavior when specified in a create subscription request.
On a changed order charge
When an order charge is being changed (operation: change) price details will be modified using the operation field and can be changed, created, or removed. Price details not specified in the request should be unaffected with the exception of having Tier and fromQuantity automatically adjusted to account for added, changed, or removed price details.
The following example shows a request where a tiered price detail is being changed.
{
"effectiveChangeDate": "2024-09-01",
"products": [
{
"operation": "Change",
"product": "OP-000237",
"charges": [
{
"charge": "OPC-000301",
"priceDetails": [
{
"toQuantity": 100,
"operation": "Change",
"tier": 1,
"price": 100,
"listPrice": 100,
},
{
"toQuantity": 400,
"operation": "Create",
"tier": 4,
"price": 120,
"listPrice": 120,
},
{
"isInfinite": true,
"operation": "Create",
"tier": 5,
"price": 150,
"listPrice": 150,
}
]
}
]
}
]
}Changes to order discounts
Order discounts can be added, removed, or modified when a subscription is changed.
Operation: Specify the operation ascreate,remove, orchange. By default, it'schangeorcreate.OnSpecificCharges: Determine if the discount should apply to all charges (false) or specific ones (true).OrderProductCharges: Provide a list of order product charges for discounts ifOnSpecificChargesistrue.
Example of adding an order discount for all charges with start and end dates.
{
"effectiveChangeDate": "2025-07-01",
"products": [...],
"orderDiscounts": [
{
"operation": "create",
"percent": 12,
"onSpecificCharges": false,
"startOn": "specificDate",
"endOn": "specificDate",
"startDate": "2024-07-01",
"endDate": "2024-09-01"
}
],
}Example of a change where a new product is incorporated, and an order discount applies to both the new and existing charges.
{
"account": "A-000002",
"status": "active",
"effectiveStartDate": "2025-07-01",
"currency": "SEK",
"products": [
{
"product": "P-000001",
"chargePlan": "CP-000001",
"operation": "create",
"charges": [
{
"charge": "C-000002",
"quantity": 20,
}
]
},
{
"product": "OP-000267",
"operation": "change",
"charges": [
{
"charge": "OPC-000322",
"quantity": 18,
}
]
},
],
"orderDiscounts": [{
"operation": "create",
"percent": 8,
"onSpecificCharges": true,
"orderProductCharges": [
{
"charge": "C-000002",
"operation": "Add"
},
{
"charge": "OPC-000322",
"operation": "Add"
},
],
}],
}Example of removing an existing order discount
{
"effectiveChangeDate": "2025-07-01",
"products": [...],
"orderDiscounts": [
{
"operation": "remove",
"orderDiscountId": "1b80a3a9-e171-40ed-fd1b-08dca02399df"
}
],
}Example of changing an existing order discount.
{
"effectiveChangeDate": "2025-07-01",
"products": [
{
"operation": "change",
"product": "OP-002591",
"charges": [
{
"charge": "OPC-002038"
}
]
},
{
"operation": "change",
"product": "OP-002590",
"charges": [
{
"charge": "OPC-002037"
}
]
}
],
"orderDiscounts": [
{
"operation": "change",
"orderDiscountId": "1b80a3a9-e171-40ed-fd1b-08dca02399df",
"percent": 12,
"onSpecificCharges": true,
"orderProductCharges": [
{
"charge": "OPC-002038",
"operation": "remove"
},
{
"charge": "OPC-002037",
"operation": "add"
}
],
}
],
}
Last updated
Was this helpful?