Selecting the source order

How to set the subscription first run and add the line items from which to generate the subscriptions

Problem

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.

Solution

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.

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 GET request to the /api/subscription_models/:id, requesting the frequencies.
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:

Shopping cart

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:

Checkout

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.

For the steps you need to follow to add a payment source to a customer wallet and reuse it please refer to our Payments guide, based on the payment gateway of your choice (e.g. Stripe, Adyen, etc.):

Payments

If you're using our hosted Checkout application most of all of the steps above come out of the box! 😉

Example

1. Check the frequencies allowed by the subscription model

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"
    }
  }
}

2. Add a line item with frequency to an order

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"
    }
  }
}

Additional notes

Promotions, discounts, and price frequency tiers

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.

Reusing the source order

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.

Cancelling the source order

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.

Updating the quantity of an existing line item with frequency

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.