.png){kind=logo}
Create new subscription type
- 06 Sep 2024
- 9 Minutes to read
- Contributors
- Print
- DarkLight
Create new subscription type
- Updated on 06 Sep 2024
- 9 Minutes to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Post
/subscription/v4/types
Create a new subscription type. This will be created in a DRAFT status.
Security
HTTP
Type bearer
Body parameters
object
name
string Required
Display name for the subscription
Pattern^[^‡]+$
ExampleWeekly Box
shortDescription
string
A short description of the subscription type, up to 80 characters. Useful for display purposes.
Max length80
ExampleA weekly box of fresh fruit and vegetables.
description
string
Long description of the subscription type.
ExampleA weekly box of fresh fruit and vegetables delivered to your door. Perfect for busy families and individuals who want to eat healthily.
phases
Array of object Required
Phases are used to define the lifecycle of a subscription. The configuration defined in a phase will be applied to all orders generated during that phase
Min items1
object
name
string Required
Min length1
ExampleTrial Phase
deliveryCadenceOptions
Array of object Required
Describes how frequently Orders within a phase can be delivered. The example demonstrates that orders in this phase can be delivered either every 1 month, every 2 months, or every week.
Min items1
Example[ { "duration": "MONTH", "values": [ "1", "2" ] }, { "duration": "WEEK", "values": [ "1" ] } ]
object
duration
string Required
A unit of time.
Valid values[ "\"DAY\"", "\"WEEK\"", "\"MONTH\"", "\"QUARTER\"", "\"YEAR\"" ]
values
Array of number Required
The number of 'duration units' that make up this period of time. Together with the duration unit, this defines the length of the period, e.g. '3' months.
Min items1
number
terminationCriteria
Array of object Required
When the phase will end, for example - end the phase after 2 orders
Max items1
Example[ { "orderOrdinal": 1.0 } ]
object
orderOrdinal
number Required
Minimum1
presets
Array of object
A curated list of products and quantities, which should be valid according to the product options defined within the phase. These can be used by merchants to drive their customer UI by creating curated selections of products
Default[]
Example[ { "name": "Assorted Products", "metadata": [], "products": [ { "id": "product-1", "quantity": 20 }, { "id": "product-2", "quantity": 10 } ] } ]
object
name
string Required
Min length1
ExampleWeekly Box
metadata
Array of object
Default[]
object
key
string Required
value
products
Array of object Required
A list of products alongside their quantities associated with the preset
Min items1
object
Example{ "id": "product-1", "quantity": 20 }
id
string Required
quantity
integer Required
Minimum1
productOptions
Array of object
Defines the collections and quantities of products a subscription contract can be created with.
Note - Product Options do not limit the products which can be added directly to orders, or products added to orders via Order Rules, only products added to orders via subscription contracts.
The example demonstrates that a subscription contract can be created with 10 or 20 products from the 'product-collection-1' collection, and 10 products from the 'product-collection-2' collection
Default[]
Example[ { "items": [ { "type": "collection", "id": "product-collection-1" } ], "quantity": [ "10", "20" ] }, { "items": [ { "type": "collection", "id": "whisky-collection-2" } ], "quantity": [ "10" ] } ]
object
items
Array of object Required
The list of product items a subscription contract can choose from, such as a list of product collections.
Min items1
object
The product item based on the type and its corresponding id. E.g. it could be an id of a product collection.
type
string Required
The type of product option, such as a collection.
Valid values[ "\"collection\"" ]
id
string Required
The unique identifier for the item type
quantity
Array of number Required
The quantity of products which can be selected from listed product options
Min items1
number
Minimum0
Maximum1000
pricingCalculator
Controls how orders are priced.
OneOf
object
engine
string Required
Valid values[ "\"fixedBasePrice\"" ]
configuration
object Required
basePrice
A monetary value in the major denomination of the merchants currency, e.g. 1.5 represents £1.50 in GBP
Example1.5
AnyOf
number
number
Minimum0
Maximum9007199254740991
number
number
Minimum-9007199254740991
Maximum0
number
number
Valid values[ "\"0\"" ]
object
engine
string Required
Valid values[ "\"bulkDiscountedCalculator\"" ]
configuration
object Required
basePrice
A monetary value in the major denomination of the merchants currency, e.g. 1.5 represents £1.50 in GBP
Example1.5
AnyOf
number
number
Minimum0
Maximum9007199254740991
number
number
Minimum-9007199254740991
Maximum0
number
number
Valid values[ "\"0\"" ]
bulkOrderDiscountThresholds
object Required
property*
string additionalProperties
Min length1
object
engine
string Required
Valid values[ "\"productVolumeCalculator\"" ]
configuration
object Required
filters
object Required
This can be used to limit the products that discounts are applied to.
collections
Array of string Required
string
Exampleproduct-collection-1
volumesThresholds
object Required
Example{ "28": "-0.2", "56": "-0.3", "84": "-0.5" }
property*
string additionalProperties
Min length1
object
engine
string Required
Valid values[ "\"collectionVolumeDiscountCalculator\"" ]
configuration
object Required
discounts
Array of object Required
A list of all collection volume discounts that can be applied to the orders.
object
collectionsVolume
Array of object Required
The list of collection volume required combination that can be applied to the orders. For example, if order contains products of required volume from Collection1 and Collection2 then a monetary discount of X will be applied to the order total price.
object
collectionId
string Required
volume
integer Required
Minimum0
discount
integer Required
The monetary discount as positive minor number. For example, if the discount is £0.2, the value should be 20.
Minimum0
billingOptions
object Required
frequency
object Required
Describes how frequently Orders within a Subscription Type can be billed. For example, if a subscription has a billing cadence of 2 for EVERY_N_ORDER, we will charge them for order 1 and 2 when order 1 is billed. When order 2 is billed, they will not be charged, and so on.
Example{ "durationUnit": "EVERY_N_ORDER", "values": [ "1", "2", "3" ] }
durationUnit
string Required
The interval unit to define how often the subscription contract is charged.
Valid values[ "\"EVERY_N_ORDER\"" ]
values
Array of integer Required
integer
Minimum1
Maximum1000
Responses
201
Create subscription type.
object
data
object
typeId
string (uuid)
The unique identifier of the subscription type, in UUID format.
status
string
The status of the subscription type. DRAFT - All new Subscription Types are created in this state. Subscription Types in this state need to be activated before they can be used to create a Subscription Contract ACTIVE - Subscription Types in this state can be used to create Subscription Contracts LEGACY - Subscription Types are transitioned to this state when deactivated ARCHIVED - Not yet used.
Valid values[ "\"DRAFT\"", "\"ACTIVE\"", "\"LEGACY\"", "\"ARCHIVED\"" ]
name
string
Display name for the subscription
Pattern^[^‡]+$
ExampleWeekly Box
shortDescription
string
A short description of the subscription type, up to 80 characters. Useful for display purposes.
Max length80
ExampleA weekly box of fresh fruit and vegetables.
description
string
Long description of the subscription type.
ExampleA weekly box of fresh fruit and vegetables delivered to your door. Perfect for busy families and individuals who want to eat healthily.
createdAt
string (date-time)
The date and time when the subscription type was created.
updatedAt
string (date-time)
The date and time when the subscription type was last updated.
phases
Array of object
object
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.
id
string (uuid)
name
string
Min length1
ExampleTrial Phase
deliveryCadenceOptions
Array of object
Describes how frequently Orders within a phase can be delivered. The example demonstrates that orders in this phase can be delivered either every 1 month, every 2 months, or every week.
Min items1
Example[ { "duration": "MONTH", "values": [ "1", "2" ] }, { "duration": "WEEK", "values": [ "1" ] } ]
object
duration
string
A unit of time.
Valid values[ "\"DAY\"", "\"WEEK\"", "\"MONTH\"", "\"QUARTER\"", "\"YEAR\"" ]
values
Array of number
The number of 'duration units' that make up this period of time. Together with the duration unit, this defines the length of the period, e.g. '3' months.
Min items1
number
terminationCriteria
Array of object
When the phase will end, for example - end the phase after 2 orders
Max items1
Example[ { "orderOrdinal": 1.0 } ]
object
orderOrdinal
number
Minimum1
presets
Array of object
A curated list of products and quantities, which should be valid according to the product options defined within the phase. These can be used by merchants to drive their customer UI by creating curated selections of products
Default[]
Example[ { "name": "Assorted Products", "metadata": [], "products": [ { "id": "product-1", "quantity": 20 }, { "id": "product-2", "quantity": 10 } ] } ]
object
name
string
Min length1
ExampleWeekly Box
metadata
Array of object
Default[]
object
key
string
value
products
Array of object
A list of products alongside their quantities associated with the preset
Min items1
object
Example{ "id": "product-1", "quantity": 20 }
id
string
quantity
integer
Minimum1
productOptions
Array of object
Defines the collections and quantities of products a subscription contract can be created with.
Note - Product Options do not limit the products which can be added directly to orders, or products added to orders via Order Rules, only products added to orders via subscription contracts.
The example demonstrates that a subscription contract can be created with 10 or 20 products from the 'product-collection-1' collection, and 10 products from the 'product-collection-2' collection
Default[]
Example[ { "items": [ { "type": "collection", "id": "product-collection-1" } ], "quantity": [ "10", "20" ] }, { "items": [ { "type": "collection", "id": "whisky-collection-2" } ], "quantity": [ "10" ] } ]
object
items
Array of object
The list of product items a subscription contract can choose from, such as a list of product collections.
Min items1
object
The product item based on the type and its corresponding id. E.g. it could be an id of a product collection.
type
string
The type of product option, such as a collection.
Valid values[ "\"collection\"" ]
id
string
The unique identifier for the item type
quantity
Array of number
The quantity of products which can be selected from listed product options
Min items1
number
Minimum0
Maximum1000
pricingCalculator
Controls how orders are priced.
OneOf
object
engine
string
Valid values[ "\"fixedBasePrice\"" ]
configuration
object
basePrice
A monetary value in the major denomination of the merchants currency, e.g. 1.5 represents £1.50 in GBP
Example1.5
AnyOf
number
number
Minimum0
Maximum9007199254740991
number
number
Minimum-9007199254740991
Maximum0
number
number
Valid values[ "\"0\"" ]
object
engine
string
Valid values[ "\"bulkDiscountedCalculator\"" ]
configuration
object
basePrice
A monetary value in the major denomination of the merchants currency, e.g. 1.5 represents £1.50 in GBP
Example1.5
AnyOf
number
number
Minimum0
Maximum9007199254740991
number
number
Minimum-9007199254740991
Maximum0
number
number
Valid values[ "\"0\"" ]
bulkOrderDiscountThresholds
object
property*
string additionalProperties
Min length1
object
engine
string
Valid values[ "\"productVolumeCalculator\"" ]
configuration
object
filters
object
This can be used to limit the products that discounts are applied to.
collections
Array of string
string
Exampleproduct-collection-1
volumesThresholds
object
Example{ "28": "-0.2", "56": "-0.3", "84": "-0.5" }
property*
string additionalProperties
Min length1
object
engine
string
Valid values[ "\"collectionVolumeDiscountCalculator\"" ]
configuration
object
discounts
Array of object
A list of all collection volume discounts that can be applied to the orders.
object
collectionsVolume
Array of object
The list of collection volume required combination that can be applied to the orders. For example, if order contains products of required volume from Collection1 and Collection2 then a monetary discount of X will be applied to the order total price.
object
collectionId
string
volume
integer
Minimum0
discount
integer
The monetary discount as positive minor number. For example, if the discount is £0.2, the value should be 20.
Minimum0
billingOptions
object
frequency
object
Describes how frequently Orders within a Subscription Type can be billed. For example, if a subscription has a billing cadence of 2 for EVERY_N_ORDER, we will charge them for order 1 and 2 when order 1 is billed. When order 2 is billed, they will not be charged, and so on.
Example{ "durationUnit": "EVERY_N_ORDER", "values": [ "1", "2", "3" ] }
durationUnit
string
The interval unit to define how often the subscription contract is charged.
Valid values[ "\"EVERY_N_ORDER\"" ]
values
Array of integer
integer
Minimum1
Maximum1000
400
Invalid Request
object
message
string
A human readable message describing the error.
causes
Array of object
A list of causes for the error.
object
message
string
A human readable message describing the cause of the error.
metadata
A list of metadata describing the cause of the error.
401
Invalid Authentication Credentials
object
message
string
A human readable message describing the error.
causes
Array of object
A list of causes for the error.
object
message
string
A human readable message describing the cause of the error.
metadata
A list of metadata describing the cause of the error.
403
Invalid Authorization Credentials
object
message
string
A human readable message describing the error.
causes
Array of object
A list of causes for the error.
object
message
string
A human readable message describing the cause of the error.
metadata
A list of metadata describing the cause of the error.
500
Internal Server Error
object
message
string
A human readable message describing the error.
causes
Array of object
A list of causes for the error.
object
message
string
A human readable message describing the cause of the error.
metadata
A list of metadata describing the cause of the error.
Was this article helpful?