Generating the subscriptions
How to trigger the subscription generation based on the source order and the subscription model configuration
You have associated a subscription model with your market, setting the allowed subscription frequencies and choosing the subscription strategy. You also have selected a source order containing some line items with frequency from which to start generating the subscriptions and placed it. You now want to trigger the subscription generation.
To start generating the subscription from a placed source order, send a
PATCH
request to the /api/orders/:id
endpoint setting the _create_subscriptions
attribute to true
.Make sure to start the subscription generation upon/after the order placement, otherwise no order subscription will be generated even if the source order contains some line items with frequency.
Request
Response
The following request generates the subscriptions from the source order identified by the "NgojhelVGm" ID:
curl -g -X PATCH \
'https://yourdomain.commercelayer.io/api/orders/NgojhelVGm' \
-H 'Authorization: Bearer your-access-token' \
-H 'Accept: application/vnd.api+json' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "orders",
"id": "NgojhelVGm",
"attributes": {
"_create_subscriptions": true
}
}
}'
On success, the API responds with a
200 OK
status code, returning the updated order object:{
"data": {
"id": "NgojhelVGm",
"type": "orders",
"links": {
"self": "https://yourdomain.commercelayer.io/api/orders/NgojhelVGm"
},
"attributes": {
"number": 35589030,
"autorefresh": true,
"status": "placed",
"payment_status": "authorized",
"fulfillment_status": "unfulfilled",
"guest": false,
"editable": false,
"customer_email": "[email protected]",
"language_code": "en",
"currency_code": "USD",
"tax_included": false,
"tax_rate": null,
"freight_taxable": null,
"requires_billing_info": false,
"country_code": "US",
"shipping_country_code_lock": null,
"coupon_code": null,
"gift_card_code": null,
"gift_card_or_coupon_code": null,
"subtotal_amount_cents": 13249,
"subtotal_amount_float": 132.49,
"formatted_subtotal_amount": "$132.49",
"shipping_amount_cents": 0,
"shipping_amount_float": 0.0,
"formatted_shipping_amount": "$0.00",
"payment_method_amount_cents": 0,
"payment_method_amount_float": 0.0,
"formatted_payment_method_amount": "$0.00",
"discount_amount_cents": 0,
"discount_amount_float": 0.0,
"formatted_discount_amount": "$0.00",
"adjustment_amount_cents": 0,
"adjustment_amount_float": 0.0,
"formatted_adjustment_amount": "$0.00",
"gift_card_amount_cents": 0,
"gift_card_amount_float": 0.0,
"formatted_gift_card_amount": "$0.00",
"total_tax_amount_cents": 0,
"total_tax_amount_float": 0.0,
"formatted_total_tax_amount": "$0.00",
"subtotal_tax_amount_cents": 0,
"subtotal_tax_amount_float": 0.0,
"formatted_subtotal_tax_amount": "$0.00",
"shipping_tax_amount_cents": 0,
"shipping_tax_amount_float": 0.0,
"formatted_shipping_tax_amount": "$0.00",
"payment_method_tax_amount_cents": 0,
"payment_method_tax_amount_float": 0.0,
"formatted_payment_method_tax_amount": "$0.00",
"adjustment_tax_amount_cents": 0,
"adjustment_tax_amount_float": 0.0,
"formatted_adjustment_tax_amount": "$0.00",
"total_amount_cents": 13249,
"total_amount_float": 132.49,
"formatted_total_amount": "$132.49",
"total_taxable_amount_cents": 13249,
"total_taxable_amount_float": 132.49,
"formatted_total_taxable_amount": "$132.49",
"subtotal_taxable_amount_cents": 13249,
"subtotal_taxable_amount_float": 132.49,
"formatted_subtotal_taxable_amount": "$132.49",
"shipping_taxable_amount_cents": 0,
"shipping_taxable_amount_float": 0.0,
"formatted_shipping_taxable_amount": "$0.00",
"payment_method_taxable_amount_cents": 0,
"payment_method_taxable_amount_float": 0.0,
"formatted_payment_method_taxable_amount": "$0.00",
"adjustment_taxable_amount_cents": 0,
"adjustment_taxable_amount_float": 0.0,
"formatted_adjustment_taxable_amount": "$0.00",
"total_amount_with_taxes_cents": 13249,
"total_amount_with_taxes_float": 132.49,
"formatted_total_amount_with_taxes": "$132.49",
"fees_amount_cents": 0,
"fees_amount_float": 0.0,
"formatted_fees_amount": "$0.00",
"duty_amount_cents": null,
"duty_amount_float": null,
"formatted_duty_amount": null,
"skus_count": 5,
"line_item_options_count": 0,
"shipments_count": 1,
"tax_calculations_count": 0,
"payment_source_details": {
"type": "stripe_payment",
"payment_method_id": "pm_1MoVlPJG2nIhpilUloZdYYXx",
"payment_method_type": "card",
"payment_method_details": {
"brand": "visa",
"last4": "4242",
"checks": {
"cvc_check": "pass",
"address_line1_check": "pass",
"address_postal_code_check": "pass"
},
"wallet": null,
"country": "US",
"funding": "credit",
"exp_year": 2034,
"networks": {
"available": [ "visa" ],
"preferred": null
},
"exp_month": 12,
"fingerprint": "5YQL9g2QjCF96IJS",
"generated_from": null,
"three_d_secure_usage": {
"supported": true
}
}
},
"token": "t0k3N0d6984d36e330c002862d91XXx",
"cart_url": null,
"return_url": null,
"terms_url": null,
"privacy_url": null,
"checkout_url": "https://your-checkout-url/NgojhelVGm",
"placed_at": "2023-03-22T17:47:57.794Z",
"approved_at": null,
"cancelled_at": null,
"payment_updated_at": "2023-03-22T17:47:57.230Z",
"fulfillment_updated_at": null,
"refreshed_at": "2023-03-22T17:43:54.246Z",
"archived_at": null,
"expires_at": null,
"subscription_created_at": "2023-03-22T17:56:38.199Z",
"created_at": "2023-03-22T16:01:44.159Z",
"updated_at": "2023-03-22T17:47:57.804Z",
"reference": "",
"reference_origin": "",
"metadata": {}
},
"relationships": {
"market": { ... },
"customer": { ... },
"shipping_address": { ... },
"billing_address": { ... },
"available_payment_methods": { ... },
"available_customer_payment_sources": { ... },
"available_free_skus": { ... },
"available_free_bundles": { ... },
"payment_method": { ... },
"payment_source": { ... },
"line_items": { ... },
"shipments": { ... },
"transactions": { ... },
"authorizations": { ... },
"captures": { ... },
"voids": { ... },
"refunds": { ... },
"returns": { ... },
"order_subscriptions": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/orders/NgojhelVGm/relationships/order_subscriptions",
"related": "https://yourdomain.commercelayer.io/api/orders/NgojhelVGm/order_subscriptions"
}
},
"order_factories": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/orders/NgojhelVGm/relationships/order_factories",
"related": "https://yourdomain.commercelayer.io/api/orders/NgojhelVGm/order_factories"
}
},
"order_copies": { ... },
"recurring_order_copies": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/orders/NgojhelVGm/relationships/recurring_order_copies",
"related": "https://yourdomain.commercelayer.io/api/orders/NgojhelVGm/recurring_order_copies"
}
},
"attachments": { ... },
"events": { ... }
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
}
}
The automatic order subscription generation process is triggered manually by using a specific attribute. The necessary order subscriptions are automatically generated based on the source order’s line item for which you’ve specified a frequency, accordingly to the strategy set at the subscription model level.
- The source order’s customer email is stored, that order is considered the subscription's first run, and the generated order subscriptions are activated (unless differently specified at the subscription model level by setting the
auto_activate
attribute totrue
). - For each automatically generated order subscription, some source order information is copied (e.g. addresses, customer payment source, etc.), the related order subscription items are created and associated with the order subscriptions, and the target order is placed at the scheduled time using the saved customer payment source (if still valid).
During an automatic order subscription generation, the source order is never reused to generate any next runs, which are built on top of the associated order subscription and related order subscription items only.
Which and how many order subscriptions and order subscription items are generated depends on the subscription strategy and source order's line items.
by_frequency
— as many order subscriptions as the different frequencies specified for the source order’s line items are generated, each with the related order subscription items (default strategy).by_line_items
— an order subscription is generated for any source order’s line item that has a frequency, each with the related order subscription item.
by_frequency
— for each automatically generated order subscription as many order subscription items as the source order’s line items that have that specific frequency are generated.by_line_items
— for each automatically generated order subscription a single order subscription item is generated.
Let's look at the source order we used throughout this guide:
Request
Response
The following request fetches the source order, requesting some basic fields and including the line items to check their frequency:
curl -g -X GET \
'http://yourdomain.commercelayer.io/api/orders/NgojhelVGm?include=line_items&fields[orders]=number,customer_email,formatted_total_amount_with_taxes,skus_count&fields[line_items]=name,sku_code,quantity,formatted_unit_amount,formatted_total_amount,frequency' \
-H 'Authorization: Bearer your-access-token' \
-H 'Accept: application/vnd.api+json'
On success, the API responds with a
200 OK
status code, returning the source order object with the requested fields and included items:{
"data": {
"id": "NgojhelVGm",
"type": "orders",
"links": { ... },
"attributes": {
"number": 35589030,
"customer_email": "[email protected]",
"formatted_total_amount_with_taxes": "$132.49",
"skus_count": 5
},
"meta": { ... }
},
"included": [
{
"id": "yDBVtlPZWw",
"type": "line_items",
"links": { ... },
"attributes": {
"sku_code": "LENSPACKL125",
"quantity": 1,
"formatted_unit_amount": "$39.90",
"formatted_total_amount": "$39.90",
"name": "Pack of 30 lenses -1.25",
"frequency": "monthly"
},
"meta": { ... }
},
{
"id": "kJbZtLlxKQ",
"type": "line_items",
"links": { ... },
"attributes": {
"sku_code": "LENSPACKR075",
"quantity": 1,
"formatted_unit_amount": "$39.99",
"formatted_total_amount": "$39.99",
"name": "Pack of 30 lenses -0.75",
"frequency": "monthly"
},
"meta": { ... }
},
{
"id": "vRrYtlbGmx",
"type": "line_items",
"links": { ... },
"attributes": {
"sku_code": "RAZRFILLPACK4",
"quantity": 2,
"formatted_unit_amount": "$14.90",
"formatted_total_amount": "$29.80",
"name": "4-Pack Razorblade Refill",
"frequency": "weekly"
},
"meta": { ... }
},
{
"id": "NYEAtLObAd",
"type": "line_items",
"links": { ... },
"attributes": {
"sku_code": "MUGXXXAUFFFFFF00000011OZ",
"quantity": 1,
"formatted_unit_amount": "$22.80",
"formatted_total_amount": "$22.80",
"name": "White Glossy Mug with Black Logo (11OZ)",
"frequency": null
},
"meta": { ... }
}
]
}
As you can see inspecting the above response it contains 4 line items of type
skus
for a total of 5 SKUs:- 2 SKUs with
monthly
frequency (both with quantity1
— SKU codesLENSPACKL125
andLENSPACKR075
) - 1 SKU with
weekly
frequency (with quantity2
and SKU codeRAZRFILLPACK4
) - 1 SKU with no specified frequency (with quantity
1
and SKU codeMUGXXXAUFFFFFF00000011OZ
)
Based on the subscription strategy these are the subscriptions and subscription items that will be generated (remember that line items without frequency don't generate subscriptions):
2 order subscriptions and 3 order subscription items:
- 1 for the
monthly
frequency, associated with 2 order subscription items (SKU codesLENSPACKL125
andLENSPACKR075
, both with quantity1
) - 1 for the
weekly
frequency, associated with 1 order subscription item (SKU codeRAZRFILLPACK4
with quantity2
)
In this case, in terms of generated recurring target orders:
- every month, 1 order with 2 line items of type
skus
will be placed (codesLENSPACKL125
andLENSPACKR075
, both with quantity1
) - every week, 1 order with 1 line item of type
skus
will be placed (codeRAZRFILLPACK4
with quantity2
)
3 order subscriptions and 3 order subscription items
- 1 for the
LENSPACKL125
line item, associated with 1 order subscription item (with quantity1
and frequencymonthly
) - 1 for the
LENSPACKR075
line item, associated with 1 order subscription item (with quantity1
and frequencymonthly
) - 1 for the
RAZRFILLPACK4
line item, associated with 1 order subscription item (with quantity2
and frequencyweekly
)
In this case, in terms of generated recurring target orders:
- every month 2 orders with 1 line item of type
skus
will be placed (one for the product with codeLENSPACKL125
, the other for the product with codeLENSPACKR075,
both with quantity1)
- every week 1 order with 1 line item of type
skus
will be placed (codeRAZRFILLPACK4
with quantity2
)
The generated recurring target orders cannot be used as source orders from which to trigger a new subscription generation.
You can check the generated order subscriptions and related order subscription items in the Subscriptions section of our admin dashboard, or via API by sending a
GET
request to the /api/order_subscriptions
endpoint, filtered by the source order ID with order subscription items included (the following request is related to the by_frequency
example above):Request
Response
The following request fetches all the order subscriptions associated with the customer identified by the "nDNahABVZR" ID and generated by the source order identified by the "NgojhelVGm" ID, including the related order subscription items:
curl -g -X GET \
'http://yourdomain.commercelayer.io/api/customers/nDNahABVZR/order_subscriptions?filter[q][source_order_id_eq]=NgojhelVGm&include=order_subscription_items' \
-H 'Authorization: Bearer your-access-token' \
-H 'Accept: application/vnd.api+json'
On success, the API responds with a
200 OK
status code, returning a paginated collection of the order subscription objects that match the filter query, including the related order subscription items:{
"data": [
{
"id": "RkRGoFmRyp",
"type": "order_subscriptions",
"links": { ... },
"attributes": {
"number": "820",
"status": "active",
"frequency": "monthly",
"activate_by_source_order": true,
"customer_email": "[email protected]",
"starts_at": "2023-03-22T17:56:38.137Z",
"expires_at": null,
"next_run_at": "2023-04-22T17:56:00.000Z",
"occurrencies": 0,
"errors_count": 0,
"succeeded_on_last_run": true,
"options": {
"place_target_order": true,
"activate_by_source_order": true
},
"created_at": "2023-03-22T17:56:38.140Z",
"updated_at": "2023-03-22T17:56:38.153Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"market": { ... },
"subscription_model": { ... },
"source_order": { ... },
"customer": { ... },
"customer_payment_source": { ... },
"order_subscription_items": {
"links": { ... },
"data": [
{
"type": "order_subscription_items",
"id": "WMNdKqFqnd"
},
{
"type": "order_subscription_items",
"id": "qZzPwPFYNa"
}
]
},
"order_factories": { ... },
"order_copies": { ... },
"recurring_order_copies": { ... },
"orders": { ... },
"events": { ... }
},
"meta": { ... }
},
{
"id": "xPwDMFYljK",
"type": "order_subscriptions",
"links": { ... },
"attributes": {
"number": "821",
"status": "active",
"frequency": "weekly",
"activate_by_source_order": true,
"customer_email": "[email protected]",
"starts_at": "2023-03-22T17:56:38.184Z",
"expires_at": null,
"next_run_at": "2023-03-29T17:56:00.000Z",
"occurrencies": 0,
"errors_count": 0,
"succeeded_on_last_run": true,
"options": {
"place_target_order": true,
"activate_by_source_order": true
},
"created_at": "2023-03-22T17:56:38.186Z",
"updated_at": "2023-03-22T17:56:38.193Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"market": { ... },
"subscription_model": { ... },
"source_order": { ... },
"customer": { ... },
"customer_payment_source": { ... },
"order_subscription_items": {
"links": { ... },
"data": [
{
"type": "order_subscription_items",
"id": "adkLKwFVzG"
}
]
},
"order_factories": { ... },
"order_copies": { ... },
"recurring_order_copies": { ... },
"orders": { ... },
"events": { ...}
},
"meta": { ... }
}
],
"included": [
{
"id": "WMNdKqFqnd",
"type": "order_subscription_items",
"links": { ... },
"attributes": {
"quantity": 1,
"unit_amount_cents": 3990,
"unit_amount_float": 39.9,
"formatted_unit_amount": "$39.90",
"total_amount_cents": 3990,
"total_amount_float": 39.9,
"formatted_total_amount": "$39.90",
"created_at": "2023-03-22T17:56:38.171Z",
"updated_at": "2023-03-22T17:56:38.171Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"order_subscription": { ... },
"item": { ... }
},
"meta": { ...
},
{
"id": "qZzPwPFYNa",
"type": "order_subscription_items",
"links": { ... },
"attributes": {
"quantity": 1,
"unit_amount_cents": 3999,
"unit_amount_float": 39.99,
"formatted_unit_amount": "$39.99",
"total_amount_cents": 3999,
"total_amount_float": 39.99,
"formatted_total_amount": "$39.99",
"created_at": "2023-03-22T17:56:38.182Z",
"updated_at": "2023-03-22T17:56:38.182Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"order_subscription": { ... },
"item": { ... }
},
"meta": { ... }
},
{
"id": "adkLKwFVzG",
"type": "order_subscription_items",
"links": { ... },
"attributes": {
"quantity": 2,
"unit_amount_cents": 1490,
"unit_amount_float": 14.9,
"formatted_unit_amount": "$14.90",
"total_amount_cents": 2980,
"total_amount_float": 29.8,
"formatted_total_amount": "$29.80",
"created_at": "2023-03-22T17:56:38.198Z",
"updated_at": "2023-03-22T17:56:38.198Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"order_subscription": { ... },
"item": { ... }
},
"meta": { ... }
}
],
"meta": {
"record_count": 2,
"page_count": 1
},
"links": {
"first": "https://yourdomain.commercelayer.io/api/order_subscriptions?filter[q][source_order_id_eq]=NgojhelVGm&include=order_subscription_items&page[number]=1&page[size]=10",
"last": "https://yourdomain.commercelayer.io/api/order_subscriptions?filter[q][source_order_id_eq]=NgojhelVGm&include=order_subscription_items&page[number]=1&page[size]=10"
}
}
See our API reference if you need more information on how to retrieve and update an order, filter data, include associations, fetch relationships, or about how order subscriptions and order subscription items work.
Last modified 1mo ago