Bento API Reference

Get all subscription contracts for a given tenant id and customer.

15 Nov 2024
10 Minutes to read
Contributors

Print
Share
Dark
Light

Get all subscription contracts for a given tenant id and customer.

Updated on 15 Nov 2024
10 Minutes to read
Contributors

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

Get

/subscription/v4/customer/{customerId}/contracts

Get a paginated response containing subscription contracts for a given tenant id and customer with optional filters.

Security

HTTP

Type bearer

Path parameters

customerId

stringRequired

Min length1

Query parameters

status

string

Valid values[ "ACTIVE", "PAUSED", "ENDED", "CANCELLED", "SUSPENDED", "DEACTIVATED" ]

limit

integer

Minimum0

Maximum100

cursor

string

Responses

200

Get all subscription contracts.

Expand All

object

meta

object

pagination

object

moreResults

boolean

True if there are more results.

items

number

Number of items returned.

cursor

string

Cursor from request to start from.

nextCursor

string

Cursor to start from for next page.

data

Array of object

object

contractId

The unique identifier of the subscription contract.

Example05ed19a5-edf3-471c-8417-777732038b0f

AnyOf

string (uuid)

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.

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 }

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" ]

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

Minimum0.0000000000000000000000000000

Maximum9007199254740991

number

Minimum-9007199254740991

Maximum0.0000000000000000000000000000

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

Minimum0.0000000000000000000000000000

Maximum9007199254740991

number

Minimum-9007199254740991

Maximum0.0000000000000000000000000000

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

Minimum0.0000000000000000000000000000

Maximum9007199254740991

number

Minimum-9007199254740991

Maximum0.0000000000000000000000000000

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

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

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

Minimum0.0000000000000000000000000000

Maximum9007199254740991

number

Minimum-9007199254740991

Maximum0.0000000000000000000000000000

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

400

Invalid Request

Expand All

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

Expand All

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

Expand All

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

Expand All

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?

What's Next

Create subscription contract