Generating the subscriptions

How to trigger the subscription generation based on the source order and the subscription model configuration
Problem
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.
Solution
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.
Example
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"
    }
  }
}
Additional notes
How automatic subscription generation works
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 to true).
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.
Order subscriptions
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.
Order subscription items
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.
Example
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 quantity 1 — SKU codes LENSPACKL125 and LENSPACKR075)
1 SKU with weekly frequency (with quantity 2 and SKU code RAZRFILLPACK4)
1 SKU with no specified frequency (with quantity 1 and SKU code MUGXXXAUFFFFFF00000011OZ)
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):
By frequency
2 order subscriptions and 3 order subscription items:
1 for the monthly frequency, associated with 2 order subscription items (SKU codes LENSPACKL125 and LENSPACKR075, both with quantity 1)
1 for the weekly frequency, associated with 1 order subscription item (SKU code RAZRFILLPACK4 with quantity 2)
In this case, in terms of generated recurring target orders:
every month, 1 order with 2 line items of type skus will be placed (codes LENSPACKL125 and LENSPACKR075, both with quantity 1)
every week, 1 order with 1 line item of type skus will be placed (code RAZRFILLPACK4 with quantity 2)
By line items
3 order subscriptions and 3 order subscription items
1 for the LENSPACKL125 line item, associated with 1 order subscription item (with quantity 1 and frequency monthly)
1 for the LENSPACKR075 line item, associated with 1 order subscription item (with quantity 1 and frequency monthly)
1 for the RAZRFILLPACK4 line item, associated with 1 order subscription item (with quantity 2 and frequency weekly)
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 code LENSPACKL125, the other for the product with code LENSPACKR075, both with quantity 1)
every week 1 order with 1 line item of type skus will be placed (code RAZRFILLPACK4 with quantity 2)
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"
  }
}
More to read
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.
Selecting the source order
Updating the subscriptions
Last modified 1mo ago