The order subscription object and the allowed CRUD operations on the related resource endpoint
Order subscriptions allow repeating a given source order according to a specified frequency: smaller is
hourly, larger is
yearly. If you need a custom frequency that is not in the list of allowed values, you can use a crontab expression.
Order subscriptions can be generated automatically from the line items that have a frequency using a trigger attribute at the order level (in this case recurring order copies are used as the order factory that generates the target orders) or manually (in this case the process usually leverages order copies).
To suspend or cancel an order subscription you can use the
Currently, order subscriptions have no retry policy: in case, for any reason, the order copy fails, the
errors_countcounter is incremented, but the subscription is kept
It is possible to check the
succeeded_on_last_runattribute to inspect subscription last run state: if
false, you can inspect the last associated
order_copyto fix any missing/bad data.
You can attach webhooks on order subscriptions, recurring order copies, and order copies events, to act promptly in case something unexpected happens.
To automatically generate order subscriptions based on a source order's line items with frequency you need to associate a subscription model with your market. The source order is considered the subscription's first run, some of its information is copied (e.g. addresses, customer payment source, etc.), the involved order subscription items are created and associated with the generated order subscriptions, and — upon successful recurring order copy — the target order is placed.
In between each run you can edit the subscription (e.g. changing its frequency, expiration date, status etc.) to dynamically manage the next occurences.
By default, automatically generated order subscriptions are directly activated, unless differently specified at the subscription model level.
When changing the subscription's frequency make sure to also manually update the
next_run_atattribute with the correct time in the future, otherwise the next subscription run couldn't happen when expected.
If no subscription model is associated with the market, manually created order subscriptions — simply based on a source order that not contains any line items with frequency — rely on order copies to create recurring orders. In this case, all the source order's information and line items are cloned into the target order, according to the frequency set for the order subscription. An attempt to place the copied order is done at the end of the process. You can set the
falseat creation time if you prefer to place created orders manually.
By default, manually generated order subscriptions activate from a
placedsource order, which is considered the subscription's first run. In this case, the subscription is marked as
activeand the next run will be scheduled on the current timestamp. If you want full control over the order subscription, you can specify the
falseat creation time. This way, you are not limited to placed source orders (source order status isn't checked), but must define manually the
expires_attime is optional). Also, remember to use the
_activateattribute to activate the subscription, otherwise it will miss the next run.
Order subscriptions that rely on recurring order copies can be created manually too (e.g. if you need to generate subscriptions for some source order's line items only). In this case, you need to set also the relationship with an existing subscription model and a source order, create and associate the order subscription items, and specify the customer payment source.
Check the related ER diagram and explore the flowchart that illustrates how the order subscription resource relates to the other API entities.