# Selecting the source order

## Problem

You have [associated a subscription model with your market](https://docs.commercelayer.io/how-tos/placing-orders/subscriptions/configuring-a-subscription-model), 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](#2.-add-a-line-item-with-frequency-to-an-order). 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.

{% hint style="info" %}
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. 
{% endhint %}

1. As a sales channel, first you need to [check which those allowed frequencies are](#1.-check-the-frequencies-allowed-by-the-subscription-model) 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`.
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:

{% content-ref url="../shopping-cart" %}
[shopping-cart](https://docs.commercelayer.io/how-tos/placing-orders/shopping-cart)
{% endcontent-ref %}

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:

{% content-ref url="../checkout" %}
[checkout](https://docs.commercelayer.io/how-tos/placing-orders/checkout)
{% endcontent-ref %}

{% hint style="info" %}
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.
{% endhint %}

4. 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](https://docs.commercelayer.io/how-tos/placing-orders/payments/stripe/reusing-the-payment-source), [Adyen](https://docs.commercelayer.io/how-tos/placing-orders/payments/adyen/reusing-the-payment-source), etc.):

{% content-ref url="../payments" %}
[payments](https://docs.commercelayer.io/how-tos/placing-orders/payments)
{% endcontent-ref %}

{% hint style="success" %}
If you're using our hosted [Checkout](https://github.com/commercelayer/commercelayer-react-checkout) application most of all of the steps above come out of the box! :wink:
{% endhint %}

### Example

#### 1. Check the frequencies allowed by the subscription model

{% tabs %}
{% tab title="Request" %}
The following request fetches the frequencies allowed by the subscription model identified by the "AavWRUbbMQ" ID:

```sh
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'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the requested frequencies:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "AavWRUbbMQ",
    "type": "subscription_models",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ"
    },
    "attributes": {
<strong>      "frequencies": [
</strong><strong>        "hourly",
</strong><strong>        "30 10 * * *",
</strong><strong>         "weekly",
</strong><strong>         "monthly",
</strong><strong>         "two-month"
</strong><strong>      ]
</strong>    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

#### 2. Add a line item with frequency to an order

{% tabs %}
{% tab title="Request" %}
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:

<pre class="language-sh"><code class="lang-sh">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",
<strong>        "frequency": "weekly",
</strong>        "image_url": "https://img.yourdomain.com/skus/RAZRFILLPACK4.png"
      },
      "relationships": {
        "order": {
          "data": {
            "type": "orders",
            "id": "NgojhelVGm"
          }
        }
      }
    }
  }'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created line item object:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "vRrYtlbGmx",
    "type": "line_items",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/line_items/vRrYtlbGmx"
    },
    "attributes": {
      "sku_code": "RAZRFILLPACK4",
      "bundle_code": null,
<strong>      "quantity": 2,
</strong>      "currency_code": "USD",
<strong>      "unit_amount_cents": 1490,
</strong><strong>      "unit_amount_float": 14.9,
</strong><strong>      "formatted_unit_amount": "$14.90",
</strong>      "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": {},
<strong>      "item_type": "skus",
</strong><strong>      "frequency": "weekly",
</strong>      "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"
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

## 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.&#x20;

{% hint style="warning" %}
Please note that any changes to an existing price tier don't affect the already generated order subscription items (unless you [nullify](https://docs.commercelayer.io/how-tos/placing-orders/updating-the-subscriptions#changing-the-price-of-a-product-belonging-to-a-subscription) the related order subscription item price). The changes will apply starting from the next [subscription generation](https://docs.commercelayer.io/how-tos/placing-orders/subscriptions/generating-the-subscriptions) only.
{% endhint %}

### 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](https://docs.commercelayer.io/how-tos/placing-orders/configuring-a-subscription-model#updating-the-subscription-model) 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](https://docs.commercelayer.io/how-tos/shopping-cart/add-to-cart#the-_update_quantity-param). Just make sure use it to update the quantity of an existing line item with the same frequency.

{% hint style="warning" %}
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.
{% endhint %}

## More to read

See our API reference if you need more information on how to [create](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/orders/create) or [update an order](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/orders/update), [create a line item](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/line_items/create), or about how [price frequency tiers](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/price_frequency_tiers) work.