Search…
API Reference
Resources
Order subscriptions
The order subscription object and its fields
Order subscriptions allow repeating a given source order according to a specified frequency: smaller is daily, larger is yearly.
Order subscriptions by default activates from a placed source order, which is considered the subscription's first run. In such case the subscription is marked as active and the next run will be scheduled on current timestamp.
In case you want full control over the order subscription, you can specify the activate_by_source_order option as false at creation time. In this case you are not limited to placed source orders (source order status isn't checked), but must define manually the starts_at time (expires_at time is optional). Also remember to use the _activate attribute to activate the subscription, otherwise it will miss the next run.
To suspend or cancel an order subscription you can use the _deactivate and _cancel attributes.
Order subscriptions rely on order copies to create periodic orders. A tentative to place the copied order is done at the end of the process. You can set the place_target_order option as false at creation time if you prefer to place created orders manually.
Currently, order subscriptions have no retry policy: in case, for any reason, the order copy fails, the errors_count counter is incremented, but the subscription is kept active (unless expired, deactivated or cancelled).
It is possible to check the succeeded_on_last_run attribute to inspect subscription last run state: in case its value is false, you can inspect the last associated order_copy to fix any missing/bad data and manually place the copied order.
You can attach webhooks on order subscriptions and order copies events, to act promptly in case something unexpected happens.

The order subscription object

An order subscription object is returned as part of the response body of each successful list, retrieve, create or update API call.
Field
Type
Description
type
string
order_subscriptions
id
string
The order subscription unique identifier
links.self
string
The order subscription endpoint URL
attributes.number
string
Unique identifier for the subscription (numeric)
attributes.status
string
The subscription status. One of 'draft' (default), 'inactive', 'active', or 'cancelled'.
attributes.frequency
string
The frequency of the subscription. One of 'daily', 'weekly', 'monthly', 'two-month', 'three-month', 'four-month', 'six-month', or 'yearly'.
attributes.activate_by_source_order
boolean
Indicates if the subscription will be actvated considering the placed source order as its first run, default to true.
attributes.customer_email
string
The email address of the customer, if any, associated to the source order.
attributes.starts_at
datetime
The activation date/time of this subscription.
attributes.expires_at
datetime
The expiration date/time of this subscription (must be after starts_at).
attributes.next_run_at
datetime
The date/time of the subscription next run.
attributes.occurrencies
integer
The number of times this subscription has run.
attributes.errors_count
integer
Indicates the number of subscription errors, if any.
attributes.succeeded_on_last_run
boolean
Indicates if the subscription has succeeded on its last run.
attributes.options
object
The subscription options used to create the order copy (check order_copies for more information). For subscriptions the place_target_order is enabled by default, specify custom options to overwrite it.
attributes._activate
boolean, value is 'true'
Send this attribute if you want to mark this subscription as active.
attributes._deactivate
boolean, value is 'true'
Send this attribute if you want to mark this subscription as inactive.
attributes._cancel
boolean, value is 'true'
Send this attribute if you want to mark this subscription as cancelled.
attributes.created_at
datetime
Time at which the resource was created.
attributes.updated_at
datetime
Time at which the resource was last updated.
attributes.reference
string
A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
attributes.reference_origin
string
Any identifier of the third party system that defines the reference code
attributes.metadata
object
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
relationships.market
object
The associated market, inherited from the source order if not specified.
relationships.source_order
object
The subscription source order.
relationships.customer
object
The subscription customer.
relationships.order_copies
array
The associated order copies.
relationships.orders
array
The associated copied orders.
meta.mode
string
The resource environment (can be one of test or live)
Last modified 23d ago