Selecting the source order
How to set the subscription first run and add the line items from which to generate the subscriptions
You have associated a subscription model with your market, setting the allowed subscription frequencies and choosing the subscription strategy. Now you want to create the source order from which the subscription will be generated, add a customer payment source, and place it.
Subscriptions can be automatically generated from orders that contain at least one line item that has a frequency defined. The source order is considered the subscription's first run and the recurring target orders that are created are scheduled on it for placement, according to the related frequency.
The frequency of the source order's line items must be among the ones allowed by the market's subscription model. You can specify a frequency for line items of type
skus, bundles, and adjustments only. - 1.As a sales channel, first you need to check which those allowed frequencies are so that you can show them to the user for selection. To do that, send a
GETrequest to the/api/subscription_models/:id, requesting thefrequencies. - 2.For the steps you need to follow to create a new order and add line items to it please refer to our Shopping cart guide:
- 3.For the steps you need to follow to prepare your order for placement (e.g. adding the customer addresses, shipping methods, etc.) and place it please refer to our Checkout guide:
Except for the case of wire transfers, automatic target order placement can be successful only if the source order comes with a payment source saved in the customer wallet, so that the source order's customer payment source can be copied.
If you're using our hosted Checkout application most of all of the steps above come out of the box!
😉
Request
Response
The following request fetches the frequencies allowed by the subscription model identified by the "AavWRUbbMQ" ID:
curl -g -X GET \
'http://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ?fields[subscription_models]=frequencies' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token'
On success, the API responds with a
200 OK status code, returning the requested frequencies:{
"data": {
"id": "AavWRUbbMQ",
"type": "subscription_models",
"links": {
"self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ"
},
"attributes": {
"frequencies": [
"hourly",
"30 10 * * *",
"weekly",
"monthly",
"two-month"
]
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
}
}
Request
Response
The following request adds the SKU identified by the "RAZRFILLPACK4" code to the order identified by the "NgojhelVGm" ID, setting a weekly frequency for the line item:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/line_items' \
-H 'Authorization: Bearer your-access-token' \
-H 'Accept: application/vnd.api+json' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "line_items",
"attributes": {
"quantity": 2,
"sku_code": "RAZRFILLPACK4",
"name": "4-Pack Razorblade Refill",
"frequency": "weekly",
"image_url": "https://img.yourdomain.com/skus/RAZRFILLPACK4.png"
},
"relationships": {
"order": {
"data": {
"type": "orders",
"id": "NgojhelVGm"
}
}
}
}
}'
On success, the API responds with a
201 Created status code, returning the created line item object:{
"data": {
"id": "vRrYtlbGmx",
"type": "line_items",
"links": {
"self": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx"
},
"attributes": {
"sku_code": "RAZRFILLPACK4",
"bundle_code": null,
"quantity": 2,
"currency_code": "USD",
"unit_amount_cents": 1490,
"unit_amount_float": 14.9,
"formatted_unit_amount": "$14.90",
"options_amount_cents": 0,
"options_amount_float": 0.0,
"formatted_options_amount": "$0.00",
"discount_cents": 0,
"discount_float": 0.0,
"formatted_discount": "$0.00",
"total_amount_cents": 2980,
"total_amount_float": 29.8,
"formatted_total_amount": "$29.80",
"tax_amount_cents": 0,
"tax_amount_float": 0.0,
"formatted_tax_amount": "$0.00",
"name": "4-Pack Razorblade Refill",
"image_url": "https://img.yourdomain.com/skus/RAZRFILLPACK4.png",
"discount_breakdown": {},
"tax_rate": 0.0,
"tax_breakdown": {},
"item_type": "skus",
"frequency": "weekly",
"created_at": "2023-03-22T16:08:49.593Z",
"updated_at": "2023-03-22T16:08:49.593Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"order": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/relationships/order",
"related": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/order"
}
},
"item": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/relationships/item",
"related": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/item"
}
},
"line_item_options": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/relationships/line_item_options",
"related": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/line_item_options"
}
},
"shipment_line_items": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/relationships/shipment_line_items",
"related": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/shipment_line_items"
}
},
"stock_line_items": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/relationships/stock_line_items",
"related": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/stock_line_items"
}
},
"stock_transfers": {
"links": {
"self": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/relationships/stock_transfers",
"related": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx/stock_transfers"
}
}
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
}
}
The process of automatic order subscription generation doesn't transfer to the target orders or re-compute promotions or gift cards applied to the source order. That means that you can apply promotions to the source order only but not to the automatically generated recurring target orders (e.g. offering the first occurrence for free and letting the customer pay starting from the second one).
To offer a discount based on the subscription frequency you can set some price frequency tiers. In this case, the price of the source order's line items that have a frequency is set by the tier the related frequency falls within.
Please note that any changes to an existing price tier don't affect the already generated order subscription items (unless you nullify the related order subscription item price). The changes will apply starting from the next subscription generation only.
Once triggered the subscription generation from a source order, that order cannot be reused, even if some changes that could lead to the generation of different subscriptions (e.g. at the subscription model or price tiers level) occurred in the meantime. You need to create a new identical order and trigger the new subscription generation from it.
If the source order is cancelled the already generated order subscriptions keep running, unless differently specified at the subscription model level by setting the
auto_cancel attribute to true.When adding a line item with frequency to an order, you can still leverage the
_update_quantity trigger attribute as explained here. Just make sure use it to update the quantity of an existing line item with the same frequency.The update of the quantity has priority over the frequency assignment (i.e. if you try to add a line item with an SKU code already present in the order but with a different frequency and set the
_update_quantity attribute to true, no additional line item will be created, the quantity of the existing one will be updated, keeping its original frequency.See our API reference if you need more information on how to create or update an order, create a line item, or about how price frequency tiers work.
Last modified 1mo ago