Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
How-tos
How-tos
  • Introduction
  • Product discovery
    • Product listing page
    • Product page
  • Placing orders
    • Shopping cart
      • Creating a shopping cart
      • Adding products to cart
      • Updating cart quantities
      • Removing products from cart
      • Displaying the cart summary
    • Checkout
      • Adding the customer
      • Adding a billing address
      • Adding a shipping address
      • Selecting a shipping method
      • Selecting a payment method
      • Adding a payment source
      • Adding a gift card or coupon
      • Placing the order
    • Subscriptions
      • Configuring a subscription model
      • Selecting the source order
      • Generating the subscriptions
      • Updating the subscriptions
    • Payments
      • Adyen
        • Adding the payment source
        • Sending back the payment details
        • Configuring the notification webhooks
        • Reusing the payment source
      • Axerve
        • Adding the payment source
        • Updating the payment intent
      • Braintree
        • Adding the payment source
        • Sending back the payment method nonce
        • Accepting local payments
        • Reusing the payment source
      • Checkout.com
        • Adding the payment source
        • Getting the payment details
        • Refreshing pending transactions
        • Reusing the payment source
      • Klarna
        • Adding the payment source
        • Sending back the authorization token
        • Reusing the payment source
      • PayPal
        • Adding the payment source
        • Preparing the payment for execution
      • Stripe
        • Adding the payment source
        • Refreshing the payment source
        • Reusing the payment source
      • Manual payments
        • Adding a wire transfer payment source
      • External payments
        • Adding the payment source
        • Reusing the payment source
    • Auto-capture
      • Enabling the auto-capture
      • Limiting the auto-capture amount
  • inventory
    • Inventory strategies
      • No split
      • Split shipments
      • Split by line items
      • Ship from first available (or primary)
      • Ship from primary
  • FAQ
    • Environments and initial setup
    • Authentication and access tokens
On this page
  • Problem
  • Solution
  • Example
  • Additional notes
  • Updating the subscription model
  • More to read
  1. Placing orders
  2. Subscriptions

Configuring a subscription model

How to create a subscription model to set the available subscription frequencies and the subscription strategy for a market

Problem

It's time to start providing subscription features in one of your Commerce Layer markets. You want to define the available subscription frequencies for the market in question and set the subscription strategy based on which the necessary order subscriptions will be automatically generated.

Solution

You need to create and configure a subscription model and associate it with your market. To do that:

  1. Send a POST request to the /api/subscription_models endpoint, setting the frequencies and strategy attributes.

  2. Send a PATCH request to the /api/markets/:id endpoint, setting the subscription_model relationship.

Example

1. Create a new subscription model

The following request creates a new subscription model that allows five subscription frequencies:

curl -g -X POST \
  'https://yourdomain.commercelayer.io/api/subscription_models' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "subscription_models",
    "attributes": {
      "name": "US Subscription Model",
      "frequencies": [
        "hourly",
        "30 10 * * *",
        "weekly",
        "monthly",
        "two-month"
      ]
    }
  }
}'

On success, the API responds with a 201 Created status code, returning the newly created subscription model object (since the subscription strategy wasn't specified in the request, the default one — by_frequency — is used):

{
  "data": {
    "id": "AavWRUbbMQ",
    "type": "subscription_models",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ"
    },
    "attributes": {
      "name": "US Subscription Model",
      "strategy": "by_frequency",
      "frequencies": [
        "hourly",
        "30 10 * * *",
        "weekly",
        "monthly",
        "two-month"
      ],
      "auto_activate": true,
      "auto_cancel": false,
      "created_at": "2023-03-21T16:25:18.162Z",
      "updated_at": "2023-03-21T16:25:18.162Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "markets": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/markets",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/markets"
        }
      },
      "order_subscriptions": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/order_subscriptions",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/order_subscriptions"
        }
      },
      "attachments": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/attachments",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/attachments"
        }
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

2. Associate the new subscription model with an existing market

The following request associates the subscription model identified by the "AavWRUbbMQ" ID with the market identified by the "bgOEQhznoZ" ID:

curl -g -X PATCH \
 'https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "markets",
      "id": "bgOEQhznoZ",
      "relationships": {
        "subscription_model": {
          "data": {
            "type": "subscription_models",
            "id": "AavWRUbbMQ"
          }
        }
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated market object:

{
  "data": {
    "id": "bgOEQhznoZ",
    "type": "markets",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ"
    },
    "attributes": {
      "number": 795,
      "name": "USA",
      "facebook_pixel_id": null,
      "checkout_url": "https://your-checkout-url/:order_id",
      "external_prices_url": null,
      "external_order_validation_url": null,
      "shared_secret": "y0ur_sh4r3dS3c_r3T",
      "private": false,
      "disabled_at": null,
      "created_at": "2019-05-14T10:36:53.010Z",
      "updated_at": "2023-03-21T16:54:43.188Z",
      "reference": "",
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "merchant": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/merchant",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/merchant"
        }
      },
      "price_list": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/price_list",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/price_list"
        }
      },
      "inventory_model": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/inventory_model",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/inventory_model"
        }
      },
      "subscription_model": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/subscription_model",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/subscription_model"
        }
      },
      "tax_calculator": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/tax_calculator",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/tax_calculator"
        }
      },
      "customer_group": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/customer_group",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/customer_group"
        }
      },
      "attachments": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/attachments",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/attachments"
        }
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

Additional notes

Updating the subscription model

Example

The following request updates the subscription model identified by the ID "AavWRUbbMQ", adding an additional allowed frequency and changing both the default subscription strategy and auto-activate / auto-cancel behavior:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "subscription_models",
      "id": "AavWRUbbMQ",
      "attributes": {
        "strategy": "by_line_items",
        "frequencies": [
          "hourly",
          "30 10 * * *",
          "weekly",
          "monthly",
          "two-month",
          "six-month"
        ],
        "auto_activate": false,
        "auto_cancel": true
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated subscription model object:

{
  "data": {
    "id": "AavWRUbbMQ",
    "type": "subscription_models",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ"
    },
    "attributes": {
      "name": "US Subscription Model",
      "strategy": "by_line_items",
      "frequencies": [
        "hourly",
        "30 10 * * *",
        "weekly",
        "monthly",
        "two-month",
        "six-month"
      ],
      "auto_activate": false,
      "auto_cancel": true,
      "created_at": "2023-03-21T16:25:18.162Z",
      "updated_at": "2023-03-21T18:18:42.386Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "markets": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/markets",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/markets"
        }
      },
      "order_subscriptions": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/order_subscriptions",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/order_subscriptions"
        }
      },
      "attachments": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/attachments",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/attachments"
        }
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

More to read

PreviousSubscriptionsNextSelecting the source order

Last updated 1 year ago

To create a new subscription model you need an token of type admin (or a custom role with the necessary permissions).

To update a market you need an token of type admin (or a custom role with the necessary permissions).

You may want to add some new frequencies to an existing subscription model or remove some of the allowed ones, change the subscription strategy or the default behavior in terms of , and more. To do that, you just need to send a PATCH request to the /api/subscription_models/:id endpoint, properly setting the related attributes.

Please note that any changes to an existing subscription model don't affect already generated subscriptions. The changes will apply starting from the next only. If you try to some of the already generated subscriptions in a way that's not consistent with the new changes to the subscription model you will receive a validation error.

To update a subscription model you need an token of type admin (or a custom role with the necessary permissions).

See our API reference if you need more information on how to and , or .

subscription generation
update
integration
integration
integration
automatic subscription activation and cancellation
create
update a subscription model
update a market