.png){kind=logo}
Subscription Type Import Format
- 16 May 2024
- 22 Minutes to read
- Contributors
- Print
- DarkLight
Subscription Type Import Format
- Updated on 16 May 2024
- 22 Minutes to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
This section describes how to provide subscription type data to the import service. A subscription type can be thought of as the definition of a subscription that a customer will sign up for; such as what product it is, how frequently it can be delivered and how much it will cost.
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"type": "object",
"title": "Subscription Types",
"description": "A list of subscription types that can be offered to customers.",
"properties": {
"subscriptionTypes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"typeId": {
"type": "string"
},
"status": {
"enum": ["DRAFT", "ACTIVE", "LEGACY", "ARCHIVED"]
},
"name": {
"type": "string"
},
"shortDescription": {
"type": "string",
"maxLength": 80
},
"phases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"terminationCriteria": {
"type": "array",
"items": {
"type": "object",
"properties": {
"orderOrdinal": {
"type": "integer"
}
},
"required": ["orderOrdinal"]
}
},
"billingOptions": {
"type": "object",
"properties": {
"frequency": {
"type": "object",
"properties": {
"durationUnit": {
"const": "EVERY_N_ORDER"
},
"values": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1
}
},
"required": ["durationUnit", "values"]
}
},
"required": ["frequency"]
},
"presets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"metadata": {
"type": "array",
"items": {}
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"quantity": {
"type": "integer"
}
},
"required": ["id", "quantity"]
}
}
},
"required": ["name", "metadata", "products"]
}
},
"productOptions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"id": {
"type": "string"
}
},
"required": ["type", "id"]
}
},
"quantity": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
}
},
"required": ["items", "quantity"]
}
},
"deliveryCadenceOptions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"duration": {
"enum": ["DAY", "WEEK", "MONTH", "QUARTER", "YEAR"]
},
"values": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
}
},
"required": ["duration", "values"]
}
},
"name": {
"type": "string"
},
"id": {
"type": "string"
},
"pricingCalculator": {
"type": "object",
"oneOf": [
{
"properties": {
"engine": {
"enum": ["fixedBasePrice"]
},
"configuration": {
"type": "object",
"properties": {
"basePrice": {
"type": "number",
"minimum": 0,
"multipleOf": 0.01
}
},
"required": ["basePrice"]
}
}
},
{
"properties": {
"engine": {
"enum": ["bulkDiscountedCalculator"]
},
"configuration": {
"type": "object",
"properties": {
"basePrice": {
"type": "number",
"minimum": 0,
"multipleOf": 0.01
},
"bulkOrderDiscountThresholds": {
"type": "object",
"patternProperties": {
"^[0-9]+$": {
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"minProperties": 2
}
},
"required": ["basePrice", "bulkOrderDiscountThresholds"]
}
}
},
{
"properties": {
"engine": {
"enum": ["productVolumeCalculator"]
},
"configuration": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"properties": {
"collections": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"volumesThresholds": {
"type": "object",
"patternProperties": {
"^[0-9]+$": {
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"minProperties": 2
}
},
"required": ["basePrice", "volumesThresholds"]
}
}
}
],
"required": ["engine", "configuration"]
}
},
"required": [
"terminationCriteria",
"billingOptions",
"presets",
"productOptions",
"deliveryCadenceOptions",
"name",
"id",
"pricingCalculator"
]
}
},
"createdAt": {
"type": "string",
"pattern": "^(19|20)\\d\\d[-](0[1-9]|1[012])[-](0[1-9]|[12][0-9]|3[01])T([01]\\d|2[0-3]):([0-5]\\d):([0-5]\\d)Z?$"
},
"updatedAt": {
"type": "string",
"pattern": "^(19|20)\\d\\d[-](0[1-9]|1[012])[-](0[1-9]|[12][0-9]|3[01])T([01]\\d|2[0-3]):([0-5]\\d):([0-5]\\d)Z?$"
}
},
"required": ["typeId", "status", "name", "shortDescription", "phases"]
}
}
},
"required": ["subscriptionTypes"]
}Field Descriptions
name: a string representing the name of the subscription type.
typeId: a string representing the ID of the customer's subscription, matching the one provided in Orders.
phases: A list of phases for the subscription type. A phase will end based on the termination criteria, will be priced based on the pricing calculator, and can be delivered at the frequencies defined in the delivery cadence options.
terminationCriteria: When the phase will end, for example - end the trial phase after 2 orders.
presets: A curated list of products and quantities, which should be valid according to the product options defined within the phase
billingOptions: an object representing the billing options for the subscription type.
frequency: The frequency of how customer is billed. Right now the option is to bill every N order is delivered
durationUnit: Currently we only support EVERY_N_ORDER.
values: An array of the number of orders a customer is allowed to pay for at a time. For example, an array of [1, 3, 6], means a customer can pay either for every order, pre-pay for 3 orders, or pre-pay for 6 orders at a time.
productOptions: Defines the products and product quantities a Subscription Contract can be created with
items: The list of product items a Subscription Contract can choose from.
type: it's always collection,
id: The unique identifier of the product item
quantity: The number of the product items a Subscription Contract needs to choose.
pricingCalculator: an object representing the pricing calculator for the subscription type, with the following fields:
engine - the type of calculator:
fixedBasePriceCalculator - a pricing calculator whose price does not change based on the setup of the subscription contract.
bulkDiscountedCalculator - a pricing calculator which allows for bulk discounts if a person pays for more orders at a time.
productVolumeCalculator - a pricing calculator which allows for product unit discount if a person buys more products in the order.
configuration - an object configuring the settings for a calculator, to pass to the pricing engine.
basePrice - the value off of whih subscription's price should be based. This is not needed for productVolumeCalculator
bulkOrderDiscountThresholds - required for a bulkDiscountedCalculator, this object sets the percentages of the full price paid by customers who are bulk-ordering, to offer them an incentive to do so. The keys should be the integers of the number of orders, and the values of the percentage of the base price paid at that order amount. These percentages would generally reduce as order numbers increase, for example: { "1": 100, "3": 95, "6": 90 }.
volumesThresholds - required for a productVolumeCalculator, A pricing engine for order product volume discount. An order contains X volume of a product, provide a monetary discount of Y per product. For example, volumesThresholds: { "28": "-0.2", "56": "-0.3", "84": "-0.5", }, it means for 28 or more products, the unit price will be -£0.2, for 56 or more products, unit price will be -£0.3, and for 84 or more products, unit price will be -£0.5.
deliveryCadence: an object representing the delivery cadence for the subscription type.
durationUnit - the unit of time, DAY, MONTH, WEEK, QUARTER, or YEAR.
values - The allowed number of 'duration units' that define this period of time, e.g. '3' months.
status: a string representing the status of the subscription type, which can be one of four values:
DRAFT - the state all subscription types are created in before they are activated. Not yet available to customers.
ACTIVE - available to use for subscriptions.
LEGACY - not available to use on new subscription contracts, but may still be in use for customers who started when it was active.
ARCHIVED - not available for use by active subscriber.
shortDescription: a string representing a short description of the subscription type, with a maximum length of 80 characters.
description: a string representing a longer description of the subscription type.
Example
{
"subscriptionTypes": [
{
"typeId": "8d7b4138-5f92-4e76-a223-5e777b34cbed",
"status": "ACTIVE",
"name": "A Merchant Subscription Type",
"shortDescription": "A Subscription Type representative of Merchant's proposition",
"phases": [
{
"terminationCriteria": [
{
"orderOrdinal": 1
}
],
"billingOptions": {
"frequency": {
"durationUnit": "EVERY_N_ORDER",
"values": [1]
}
},
"presets": [
{
"name": "Assorted",
"metadata": [],
"products": [
{
"id": "a-dummy-product-id",
"quantity": 6
}
]
}
],
"productOptions": [
{
"items": [
{
"type": "collection",
"id": "a-dummy-product-id-1"
}
],
"quantity": [6]
}
],
"deliveryCadenceOptions": [
{
"duration": "DAY",
"values": [12]
}
],
"name": "Trial",
"id": "sub-type-1-phase-id-1",
"pricingCalculator": {
"engine": "fixedBasePrice",
"configuration": {
"basePrice": 1
}
}
},
{
"terminationCriteria": [],
"billingOptions": {
"frequency": {
"durationUnit": "EVERY_N_ORDER",
"values": [1]
}
},
"presets": [
{
"name": "Small",
"metadata": [],
"products": [
{
"id": "a-dummy-product-id-2",
"quantity": 28
}
]
},
{
"name": "Medium",
"metadata": [],
"products": [
{
"id": "a-dummy-product-id-3",
"quantity": 56
}
]
},
{
"name": "Large",
"metadata": [],
"products": [
{
"id": "a-dummy-product-id-4",
"quantity": 84
}
]
}
],
"productOptions": [
{
"items": [
{
"type": "collection",
"id": "collection-2"
}
],
"quantity": [28, 56, 84]
}
],
"deliveryCadenceOptions": [
{
"duration": "WEEK",
"values": [4]
}
],
"name": "Post trial",
"id": "sub-type-1-phase-id-1",
"pricingCalculator": {
"engine": "fixedBasePrice",
"configuration": {
"basePrice": 30
}
}
}
],
"updatedAt": "2024-02-19T15:49:29.854Z"
}
]
}Additional Requirements
When a user creates a subscription contract for a subscription type, the cadence must be one of the periods defined here, with the array of contract cadences being the same length and matching up to the array of delivery cadence steps.
Was this article helpful?