.png){kind=logo}
Create subscription contract
- 22 Nov 2024
- 16 Minutes to read
- Contributors
- Print
- DarkLight
Create subscription contract
- Updated on 22 Nov 2024
- 16 Minutes to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Post
/subscription/v4/customer/{customerId}/contracts
Create subscription contract for given customer.
The values of the subscription contract, such as pricing engine configuration etc, will be retrieved from the Subscription Type on generation. This allows for the Subscription Type to evolve independently of any Subscription Contracts.
If the customer will exceed the maximum number of allowed ACTIVE subscriptions a 409 error will be thrown.
Security
HTTP
Type bearer
Header parameters
Idempotency-Key
string
Min length1
Path parameters
customerId
stringRequired
Min length1
Body parameters
object
subscriptionTypeId
string (uuid) Required
The subscription type that this contract is based on
Min length1
metadata
Array of object
Metadata associated with the subscription.
Example[ { "key": "VIP", "value": true } ]
object
key
string Required
The key of the metadata item.
Min length1
value
The value of the metadata item.
delegate
object
Used to link a Bento Subscription Contract to a Subscription from another platform.
delegateName
string Required
The e-commerce platform that this subscription contract is from.
Valid values[ "SHOPIFY", "CUSTOM" ]
delegateSubscriptionId
string Required
The subscription contract ID from the other platform
Exampledelegate-id
discounts
Array of object
A list of discount codes to apply to orders generated for this subscription contract.
Example[ { "code": "100OFF", "terminationCriteria": { "orderOrdinal": 3 } } ]
object
code
string Required
The discount code to apply to the subscription contract.
addedAt
string (date-time)
The ISO8601 datetime the discount code was added to the subscription contract.
orderOrdinals
Array of integer
A list of order ordinals that the discount code will be applied to.
integer
terminationCriteria
object
Deprecated: The order ordinal beyond which the discount code will no longer be applied.
orderOrdinal
integer Required
enabled
boolean
A flag to indicate whether the discount code is enabled.
credit
Array of object | null Required
Used to associate credits with a subscription contract.
object
A credit applied to the subscription contract.
Example{ "type": "OrderCredit", "value": 2.0 }
type
string Required
Types of credit. An OrderCredit will bring an order's price to 0, and is used for pre-paid orders.
Valid values[ "OrderCredit" ]
value
number Required
The value of the credit. Currently represents the number of order credits, but will in future be used for other credit types, such as the amount of monetary credit.
deliveryDetails
object Required
addressId
string Required
Delivery address for the subscription, based on the id associated with the Customer entity
Min length1
Exampleaddress-1
nextOrderOverride
object | null Required
Instead of inferring the next order from the previousOrder, this field allows it's properties to be specified exactly.
orderOrdinal
integer Required
The position of the order relative to other orders in the subscription contract. The first order in the subscription contract has ordinal '1'.
playlistPosition
integer Required
An identifier to track the order's position within a playlist. This typically matches the orderOrdinal but doesn't have to, for instance if a subscription started half-way through a playlist
previousOrder
object | null Required
Details of the last order delivered for this subscription contract.
deliveryDate
string (date) Required
Date the order was scheduled for delivery
orderOrdinal
Array of integer Required
Ordinals for multiple orders on the same day.
Min items1
integer
playlistPosition
Array of integer Required
Playlist position for multiple orders on the same day.
Min items1
integer
adjustedDates
Array of array Required
Used to adjust the delivery date of an order. The example demonstrates an order for 2022-01-01 being moved to 2022-01-10
Example[ [ "2022-01-01T12:00:00Z", "2022-01-10T12:00:00Z" ] ]
Array
Min items2
Max items2
AnyOf
string (date)
string
baseDate
string (date) Required
The date which defines when the first order (or next order after a contract change) is sent. This date is used as a base to determine the day of the month / week on which all future orders are sent.
terminationCriteria
object
For non-rolling pre-paid subscriptions, the subscription will terminate after this many orders have been delivered.
Example{ "orderOrdinal": 3 }
orderOrdinal
integer Required
The position of the order relative to other orders in the subscription contract. The first order in the subscription contract has ordinal '1'.
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
id
string (uuid) Required
The unique identifier of the corresponding phase from the Subscription Type
deliveryCadence
object Required
The frequency at which orders within the phase will be delivered, must be valid according to the options defined on the relevant Subscription Type phase
Example{ "durationUnit": "MONTH", "quantity": 1.0 }
durationUnit
string Required
Valid values[ "DAY", "WEEK", "MONTH", "QUARTER", "YEAR" ]
quantity
number Required
billing
object Required
frequency
object Required
How often to bill the customer. Must be valid according to the billing options defined on the Subscription Type.
Example{ "durationUnit": "EVERY_N_ORDER", "quantity": 1 }
durationUnit
string Required
The interval unit to define how often the subscription contract is charged.
Valid values[ "EVERY_N_ORDER" ]
quantity
integer Required
The number of 'duration units' that make up this period of time
Minimum1
Maximum1000
products
Array of object Required
Products added to each order created based on this subscription contract. Must be valid according to the Product Options defined on the Subscription Type
Example[ { "id": "product-1", "quantity": 2 }, { "id": "product-2", "quantity": 1 } ]
object
id
string Required
The product id from the Product entity.
Min length1
quantity
integer Required
The quantity of the product to add to the order.
Minimum1
pricing
object
The pricing of a subscription type. For now it only contains deliveryPrice
Example{ "deliveryPrice": { "type": "FIXED", "amount": 3 } }
deliveryPrice
object Required
The delivery price of a subscription type
Example{ "type": "FIXED", "amount": 3 }
type
string Required
The type of delivery price. For now it can only be FIXED
Valid values[ "FIXED" ]
amount
AnyOf
number
number
Minimum0.0000000000000000000000000000
Maximum9007199254740991
number
number
Minimum-9007199254740991
Maximum0.0000000000000000000000000000
number
number
Valid values[ "0" ]
paymentMethod
object Required
source
string Required
Valid values[ "SHOPIFY", "BRAINTREE", "STRIPE", "BENTO" ]
token
string Required
The payment token from the payment provider
Min length1
status
string
The status of the subscription contract. ACTIVE - The contract has not yet ended, there are still orders to deliver PAUSED - Can be set by the merchant to temporarily pause billing and delivery ENDED - The contract will transition to this status once there are no more orders to deliver CANCELLED - Can be set by the merchant to cancel a contract, and stop delivering orders SUSPENDED - The contract will transition to this status if there is a failed billing attempt DEACTIVATED - Currently unused
Valid values[ "ACTIVE", "PAUSED", "ENDED", "CANCELLED", "SUSPENDED", "DEACTIVATED" ]
Default"ACTIVE"
ExampleACTIVE
Responses
201
Create subscription contract.
object
data
object
contract
object
contractId
The unique identifier of the subscription contract.
Example05ed19a5-edf3-471c-8417-777732038b0f
AnyOf
string (uuid)
string
string
string
Pattern^[0-9]\d*$
version
number
The version number of the subscription contract.
Example1
customerId
string
The customer's unique identifier. Merchants can opt to assign this using either their own customer service system or Bento's customer service during the onboarding process.
Min length1
status
string
Valid values[ "ACTIVE", "PAUSED", "ENDED", "CANCELLED", "SUSPENDED", "DEACTIVATED", "SIGNUP_PENDING", "SIGNUP_FAILED" ]
subscriptionTypeId
string (uuid)
The unique identifier of the subscription type that this subscription contract subscribed to
delegate
object
Used to link a Bento Subscription Contract to a Subscription from another platform.
delegateName
string
The e-commerce platform that this subscription contract is from.
Valid values[ "SHOPIFY", "CUSTOM" ]
delegateSubscriptionId
string
The subscription contract ID from the other platform
Exampledelegate-id
discounts
Array of object
A list of discount codes to apply to orders generated for this subscription contract.
Example[ { "code": "100OFF", "terminationCriteria": { "orderOrdinal": 3 } } ]
object
code
string
The discount code to apply to the subscription contract.
addedAt
string (date-time)
The ISO8601 datetime the discount code was added to the subscription contract.
orderOrdinals
Array of integer
A list of order ordinals that the discount code will be applied to.
integer
terminationCriteria
object
Deprecated: The order ordinal beyond which the discount code will no longer be applied.
orderOrdinal
integer
enabled
boolean
A flag to indicate whether the discount code is enabled.
credit
Array of object | null
Used to associate credits with a subscription contract.
object
A credit applied to the subscription contract.
Example{ "type": "OrderCredit", "value": 2.0 }
type
string
Types of credit. An OrderCredit will bring an order's price to 0, and is used for pre-paid orders.
Valid values[ "OrderCredit" ]
value
number
The value of the credit. Currently represents the number of order credits, but will in future be used for other credit types, such as the amount of monetary credit.
createdAt
string
The date the subscription contract was created.
updatedAt
string
The date the subscription contract was last updated.
metadata
Array of object
Metadata associated with the subscription.
Example[ { "key": "VIP", "value": true } ]
object
key
string
The key of the metadata item.
Min length1
value
The value of the metadata item.
subscriptionType
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.0000000000000000000000000000
Maximum9007199254740991
number
number
Minimum-9007199254740991
Maximum0.0000000000000000000000000000
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.0000000000000000000000000000
Maximum9007199254740991
number
number
Minimum-9007199254740991
Maximum0.0000000000000000000000000000
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
pricing
object
The pricing of a subscription type. For now it only contains deliveryPrice
Default{ "deliveryPrice": { "type": "FIXED", "amount": 0 } }
Example{ "deliveryPrice": { "type": "FIXED", "amount": 3 } }
deliveryPrice
object
The delivery price of a subscription type
Example{ "type": "FIXED", "amount": 3 }
type
string
The type of delivery price. For now it can only be FIXED
Valid values[ "FIXED" ]
amount
AnyOf
number
number
Minimum0.0000000000000000000000000000
Maximum9007199254740991
number
number
Minimum-9007199254740991
Maximum0.0000000000000000000000000000
number
number
Valid values[ "0" ]
phases
Array of object
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
id
string (uuid)
The unique identifier of the corresponding phase from the Subscription Type
deliveryCadence
object
The frequency at which orders within the phase will be delivered, must be valid according to the options defined on the relevant Subscription Type phase
Example{ "durationUnit": "MONTH", "quantity": 1.0 }
durationUnit
string
Valid values[ "DAY", "WEEK", "MONTH", "QUARTER", "YEAR" ]
quantity
number
billing
object
frequency
object
How often to bill the customer. Must be valid according to the billing options defined on the Subscription Type.
Example{ "durationUnit": "EVERY_N_ORDER", "quantity": 1 }
durationUnit
string
The interval unit to define how often the subscription contract is charged.
Valid values[ "EVERY_N_ORDER" ]
quantity
integer
The number of 'duration units' that make up this period of time
Minimum1
Maximum1000
products
Array of object
Products added to each order created based on this subscription contract. Must be valid according to the Product Options defined on the Subscription Type
Example[ { "id": "product-1", "quantity": 2 }, { "id": "product-2", "quantity": 1 } ]
object
id
string
The product id from the Product entity.
Min length1
quantity
integer
The quantity of the product to add to the order.
Minimum1
pricing
object
The pricing of a subscription type. For now it only contains deliveryPrice
Example{ "deliveryPrice": { "type": "FIXED", "amount": 3 } }
deliveryPrice
object
The delivery price of a subscription type
Example{ "type": "FIXED", "amount": 3 }
type
string
The type of delivery price. For now it can only be FIXED
Valid values[ "FIXED" ]
amount
AnyOf
number
number
Minimum0.0000000000000000000000000000
Maximum9007199254740991
number
number
Minimum-9007199254740991
Maximum0.0000000000000000000000000000
number
number
Valid values[ "0" ]
deliveryDetails
object
addressId
string
Delivery address for the subscription, based on the id associated with the Customer entity
Min length1
Exampleaddress-1
nextOrderOverride
object | null
Instead of inferring the next order from the previousOrder, this field allows it's properties to be specified exactly.
orderOrdinal
integer
The position of the order relative to other orders in the subscription contract. The first order in the subscription contract has ordinal '1'.
playlistPosition
integer
An identifier to track the order's position within a playlist. This typically matches the orderOrdinal but doesn't have to, for instance if a subscription started half-way through a playlist
previousOrder
object | null
Details of the last order delivered for this subscription contract.
deliveryDate
string (date)
Date the order was scheduled for delivery
orderOrdinal
Array of integer
Ordinals for multiple orders on the same day.
Min items1
integer
playlistPosition
Array of integer
Playlist position for multiple orders on the same day.
Min items1
integer
adjustedDates
Array of array
Used to adjust the delivery date of an order. The example demonstrates an order for 2022-01-01 being moved to 2022-01-10
Example[ [ "2022-01-01T12:00:00Z", "2022-01-10T12:00:00Z" ] ]
Array
Min items2
Max items2
AnyOf
string (date)
string
baseDate
string (date)
The date which defines when the first order (or next order after a contract change) is sent. This date is used as a base to determine the day of the month / week on which all future orders are sent.
terminationCriteria
object
For non-rolling pre-paid subscriptions, the subscription will terminate after this many orders have been delivered.
Example{ "orderOrdinal": 3 }
orderOrdinal
integer
The position of the order relative to other orders in the subscription contract. The first order in the subscription contract has ordinal '1'.
paymentMethod
object
source
string
Valid values[ "SHOPIFY", "BRAINTREE", "STRIPE", "BENTO" ]
token
string
The payment token from the payment provider
Min length1
orders
Array of object
object
deliveryDate
string (date)
Date the order is scheduled for delivery
orderOrdinal
integer
The lifetime order number in relation to other orders within the subscription contract. The first order in the subscription contract has ordinal '1'.
Example1
playlistPosition
integer
An identifier to track the order's position within a playlist.
Example1
skipped
boolean
Whether the order has been skipped.
ExampleFalse
skipReason
string
The reason the order was skipped, optional.
subscriptionTypeId
string (uuid)
The unique identifier for the subscription type that this order is based on.
discountCodes
Array of string
The discount codes applied to the order.
Example[ "NEW_YEAR_PROMO" ]
string
discounts
Array of object
The discount codes applied to the order.
object
code
string
addedAt
string
products
Array of object
The products which will be added to the order by the subscription contract.
Example[ { "id": "whisky-1", "quantity": 5.0 }, { "id": "whisky-2", "quantity": 5.0 } ]
object
id
string
The unique identifier for the product
quantity
number
The quantity of this product in the order
phaseId
string (uuid)
The subscription phase the order is associated with
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.
404
Resource Not Found
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?