--- title: Subscriptions slug: oms/subscriptions docTags: createdAt: 2022-09-16T11:55:36.000Z --- ## Introduction A subscription business model allows customers to subscribe to your products and be charged a recurring fee—usually monthly or yearly. The subscription business model is defined within the Content Management System (CMS) under Content Model. You can populate subscription information for a product through the Subscription attribute in the Contentful or Sanity Product content model. ## Subscription CMS Setup ### Contentful ***Content Model*** The Subscription attribute allows you to enter the following information associated with a subscription: - Name - Slug - Presentation - Discount Percentage - Intervals Navigate to Content Model and click **Add Content Type. ** Type in Subscription and click **Create** ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/as4h0lbQ1EHaBRBiVq2Bj_image-3-9-2023-at-322-pm.jpg" size="72" width="1478" height="1146" position="flex-start" darkWidth="1478" darkHeight="1146" showCaption="false"} Click **Add field** and select **Text**. Type in **Name** and select **Short Text** Click the **Create and Configure** button and select **This field represents the Entry title.** ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/uEiCK5L-2Tk7qD8DhoamC_image-3-9-2023-at-330-pm.jpg" size="76" width="1650" height="1002" position="flex-start" darkWidth="1650" darkHeight="1002" showCaption="false"} Click **Confirm** Click **Add field **again and select **Text**--> **Short Text** for **Slug** and click **Create** Repeat for **Presentation**, **Discount Percentage** and **Intervals, Prepaid Subscription, Gift Subscription, **and** Max Installments** as seen below. ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/Z0qySQzSJUW6XxmBmApbM_image-3-9-2023-at-553-pm.jpg" size="78" width="1668" height="1092" position="flex-start" showCaption="false"} Now that the **Subscription** attribute is created, let's create the **Subscription Interval. ** Click Add Content Type in the **Name** field, type in** Subscription Interval **and **Create.** Click **Add field** and select **Text**. Type in **Name** and select **Short Text.** Click **Create and Configure** and select **This field represents the Entry title.** Add the other following fields as represented below. ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/0CkZKKug-aZOPcrPLcP1i_image-3-9-2023-at-550-pm.jpg" size="74" width="2036" height="940" position="flex-start" showCaption="false"} When creating a **Unit**, please make sure that your **Validation** tab is selected as such. ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/bUDytrrsKDezG2M1cUB7e_image-3-9-2023-at-638-pm.jpg" size="74" width="1666" height="1514" position="flex-start" showCaption="false"} ***Content-Type*** After creating your **Content Model,** you need to create a **Content Type **that will define what your customers will see in your store. Click Content and click **Add Entry** and select **Subscription Intervals. ** ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/OjCkv-WyJubLBuk84pPoN_screen-recording-3-9-2023-at-605-pm.gif" size="34" width="258" height="438" position="flex-start" showCaption="false"} You are now ready to determine the intervals you want to offer your customers. Type in the **Interval Name **associated with the **Unit** you want to create. Repeat for all **Units.** ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/VMauYDzrnKzGV7sbgTb9f_image-3-9-2023-at-641-pm.jpg" size="82" width="1484" height="1258" position="flex-start" showCaption="false"} If you want to provide automatic savings to your customers when they select monthly **subscriptions**, you can create a content-type subscription here. Click **Add Entry** and select **Subscription. ** For this document, we assume you want to create a **Subscribe and Save 15% **based on Monthly Subscriptions. You can publish it when you're ready to test it on Staging or Production. ![](https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/R-3oDtgl4ymm_25EaQsfa_image-3-9-2023-at-644-pm.jpg) :::hint{type="success"} The above is introductory help; please ask your developer/agency partner to help you build Subscription Types and Intervals. ::: ### Sanity ***Content Model*** When using Sanity, as in Contentful, you must create **Subscription** and **Subscription** **Intervals** in the **Content Model. ** Unlike Contentful, in Sanity Studio, defining your content models with code is by design. It makes it easier to version control and puts you and your developers in control. So you decide precisely how the data structures should be. Ask your developer or your agency to create it. A good way to start is described [here.](https://www.sanity.io/docs/content-modelling) ## Chord OMS The OMS syncs with Contentful and Sanity. Once a product is marked subscribable, you will see the product set to **Subscribable** in the Chord Order Management System. Navigate to the Product page and notice the **Subscribable** checkbox. When left unchecked, the product is not available for Subscription. ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/njbsHkcMJrVZcLhXqMIRF_image-11-7-2023-at-744-pm-1.jpg" size="70" width="2558" height="1704" position="flex-start" showCaption="false"} ## Store Checkout Now that your products have been synced and marked as subscribable, your customers can create a subscription order on your site.  Chord allows Customers to proceed with a single purchase and a subscription for the same product within their cart. :::hint{type="info"} Please check with your developer or agency partner to design a site that fits your needs. ::: ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/7Rejxpk5yalmT8GObz0Ra_image-6-2022-09-16-at-80323-am.jpg" size="80" width="3106" height="1442" position="flex-start" showCaption="false"} ## Subscription & My Account Customers can log in to the website through passwordless auth, which allows them to log in with just their email address. Once logged in, customers can see all subscriptions associated with their email on their account page. :::hint{type="info"} You can design the front end with your developers or an agency partner.  ::: ‌On their account page, Chord offers the ability for your customers to manage a subscription where the following behavior is available to them: - Skip the next refill - Cancel subscription - Edit the shipping address associated with the subscription - Edit the billing address associated with the subscription - Pause ## Creating a Subscription in Chord OMS :::hint{type="danger"} An **Account** and **Payment** information must exist for that user to create a Subscription within the OMS. ::: Click **Subscription** --> **New Subscription. ** ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/OTYrQa-m46JbSOhbKWJJz_image-11-7-2023-at-752-pm-1.jpg" size="92" width="3342" height="944" position="flex-start" showCaption="false"} You can either type in the customer's email address in the **Customer** dropdown or select one from the list The **Actionable Date** This is when your subscription will start. :::hint{type="info"} When you first create your **Subscription**, the **Actionable Date** is when the Subscription does start.  When your subscription is **Active**, the Actionable Date is the date of your next installment. ::: The **Interval Length** and **Units** are where you select how often you want to ship the products to your customer. The **Interval Units** are either days, weeks, months, or even years. The **End Date** is when your Subscription will terminate. The **Store** is your website.  Proceed with providing **Billing** and **Shipping** addresses. In the **Line Items section,** select the product(s) and **qty** you need Click **Create** ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/1Wvx38mXzquwlZBExTI1M_image-11-7-2023-at-759-pm.jpg" size="80" width="2630" height="1280" position="flex-start" showCaption="false"} Let's suppose you need to create a Subscription for your customer at the interval of every two months for a year; you would select the following: ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/_LQe5NMfaxlfkW52HeO_w_screen-recording-11-7-2023-at-807-pm.gif" size="90" width="1042" height="600" position="flex-start" showCaption="false"} :::hint{type="info"} To see your products in the dropdown, they must be marked as **Subscribable. ** ::: ## Emails You can set up subscription email reminders several days before the next installments are shipped, allowing your customers to make any adjustments to the order before it is processed. These emails templates found in your CMS are: - Default reminder - Last chance reminder ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/JSkkpjUUa1jO4_kssKPHQ_image-4-10-2023-at-420-pm.jpg" size="66" width="2618" height="1388" position="flex-start" showCaption="false"} ### Environment Variables The Chord OMS contains two environment variables that determine when reminders are sent: 1. SUBSCRIPTION\_DEFAULT\_REMINDER\_DAYS 2. SUBSCRIPTION\_LAST\_CHANCE\_REMINDER\_DAYS The OMS computes when a reminder should be sent based on the Subscription's actionable date and the value provided in these Environment Variables.  ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/v1xwSeaynPWv3T8NyuMaz_image-7-24-2023-at-117-pm.jpg" size="84" width="1936" height="998" position="flex-start" showCaption="false"} ### FAQ and Troubleshooting **Q: What are the statuses of a Subscription?** **** - **Active**: Subscription is Operational - Pending Cancelation - **Canceled**: Your subscription has been canceled. - **Inactive**: Subscription is not currently active. **Q: What are the Processing States of a Subscription?**  **New**: Your subscription is being processed. When payment is processed, the processing state will update to Success. **Failure**: your Subscription has failed. Check the Installment tab and see if your Subscription is fulfilled. More often than not, a failed subscription is due to a payment issue. Expired credit cards are often the case. **Success**: Payment is successful, and your subscription is ready to be fulfilled **Q: Can I edit an Active Subscription? ** Yes, you can edit your subscription whenever you like. Navigate to your Subscription's page and make your edit/update as described above.  **Q: Can I pause a subscription?**  Yes, there are components in our SDK that allow you to provide your customers with the ability to Pause a Subscription in the front end, and you can also Pause it from within the OMS on behalf of your customers. **Q: What happens if a subscription with previously failed installments that are eligible for retry has been paused?** If a subscription with previously failed installments that are eligible for retry has been paused, OMS will *not* reprocess those installments.  **Q: Can I delete a subscription?**  We do recommend that you mark your Subscription as Cancelled. You can click the Cancel icon next to the Subscription you'd like to end/delete on your Subscription page.  Your customers can also end their Subscription in the front end, in My Account.   ** Q: Can I create a Subscription from within the OMS?**  Yes, you can manually create a subscription in your OMS - Navigate to Subscriptions, click New Subscription, and refer to the OMS section in this guide.  **Q: If I modify an existing Subscription in the OMS, will the customer see the change in their Account? **  Yes, you can edit the Actionable Date, address, the dates, products, Payment, and more on your Subscription page.  **Q: Can I change the products in an active subscription?**  Yes, you can. You can scroll down to the Line items section and modify them there.  **Q: What is an Actionable Date?**  When you first create your Subscription, the Actionable Date is when the Subscription does start.  When your subscription is Active, the Actionable Date is the date of your next installment.  **Q: Can I update an address to a subscription?**  Yes, if you need to change billing or shipping addresses, you can do so on the Subscription page.  **Q: Can I change the method of Payment in a subscription?**  You can direct customers to update their credit cards on the Subscription page in My Account, or if they have placed an order with that same payment method, you can do it in the OMS on the Subscription page in the Payment section.   **Q: Will my customers receive an email reminding them of an upcoming subscription?**  Yes, Chord provides email template reminders in your CMS under Transactional Emails.  There are some Environment Variables configurations in Settings --> Store. For more information, please refer to [Environment Variables](https://app.archbee.com/docs/8bOVl7vg1M-0GKcUIBnmZ/OdyQAXuOHBhTJYItCMVpL) document under the Transactional Emails section.  As described in the Emails section of this document, you can select to send your customers reminders. You can specify to send the reminder based on the days before the subscription **actionable date**. **Q: How are the reminder emails being calculated and sent? ** We have a method in place that generates and sends your customers these reminders. They are based on the value you have provided in the Environment Variables and the Actionable Date of subscription orders. That method is triggered in three places: - When the Subscription is created (' activated'). - When the actionable date is updated, whether to get it sooner or at a later date - When a subscription is paused. **Q: If our customers modify their Actionable Date, will they get an email reminding them of the upcoming subscription shipment? This allows them to make any necessary order adjustments before it's shipped.** Absolutely! Your customers can make changes to their subscription's Actionable Date, whether they choose an earlier or a later date, they will still receive a reminder email. The email reminder date will automatically be adjusted based on the new Actionable Date they've selected. This ensures that they're informed and have the opportunity to make any last-minute adjustments to their order before it's shipped. Your customers can update their Actionable Date as needed, and our system will keep them in the loop with the adjusted reminder. **Q: Some of our subscriptions have not shipped, and we see Processing State "Failure" and Shipping State of "Address" what causes this?**  More often than not, when a subscription fails, it is due to a failed payment, such as an expired credit card or even no funds available. We also suggest looking at the inventory since an Out Of Stock product will stop a subscription order from shipping. **Q: Is there a way to retry these subscription orders that have failed? ** **Q: We do not want subscription shipments to be inventory dependent, and having OOS products to stop subscriptions from shipping. What do you recommend? ** We suggest having [backorder](https://app.archbee.com/docs/8bOVl7vg1M-0GKcUIBnmZ/PsMKMQSN-2A1_DzqUj1L_) setting turned ON. For more information about backorder, click on the link. Suppose backorder is not an option you want to use. In that case, you can configure a **subscription type** to fulfill the order with a *different* variant if the scheduled variant is not available/error. So if Product B is out of stock, fulfill it with Product A. For more information about Subscription Type, please refer to this document   **Q: Can i create a Subscription from Chord OMS on behalf of my customer with Store Credit?** Yes, when you create a Subscription for an existing customer who has an existing payment on file. Select **Stripe** a Payment Method and Select the credit card on file as the Payment Source (see screenshot) - When the subscription will be generated, the Chord OMS will look for Store Credit, and if it exists it will deduct it from it ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/-YIS658yvUBDS59sopCWh_image-8-12-2023-at-123-pm.jpg" size="46" width="1958" height="514" position="flex-start" showCaption="false"} Do not worry if you see an Invalid Stripe payment transaction, it is how Chord OMS handles it, but no one is charged. (The breakdown of Store Credit is based on how the SC was accredited. ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/izsSd8XOzZJ_jC7m_zNE1_image-8-12-2023-at-125-pm.jpg" size="66" width="1686" height="730" position="flex-start" showCaption="false"} :::hint{type="info"} Seeing multiple rows of Store Credit transaction, indicates that  the customer must have had individual credits awarded and they were all applied for the order. ::: **Q: Can i create a Subscription from Chord OMS on behalf of my customer using Stripe Invoice? ** Yes, when you create a Subscription, select **Stripe** **Invoice** as **Payment Method** and do not select a **Payment** **Source**. ::Image[When the subscription will be generated, the Chord OMS will look for Store Credit, and if it exists it will deduct it from it ]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/tZWkscFGYoYuoYtBDb_X1_image-8-12-2023-at-137-pm.jpg" size="66" width="1878" height="472" position="flex-start" showCaption="false"} When the subscription order is created the - Order Status will be: **Complete** - Payment Status: **Pending** - Payment Status: **Balance Due ** Navigate to [Stripe](https://dashboard.stripe.com/dashboard) and go to **Payments** --> **Billing** --> **Invoices** and search for the order number, or customer email address. Click **Send Invoice. **When your customer pays or however your business decides to handle Invoices you would still need to go back to Chord OMS and approve the payment. ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/eK3inH5FMj6eXU2Q4Wgsb_image-8-12-2023-at-146-pm.jpg" size="66" width="1182" height="156" position="flex-start" showCaption="false"} Navigate to the **Payments** tab and click the **Capture** icon 👍 ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/kWf9d0z8N-DfVfYKxsdBj_image-8-12-2023-at-143-pm.jpg" size="66" width="1854" height="594" position="flex-start" showCaption="false"} When captured, notice that your transaction is now **Stripe invoice ** ::Image[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/B4g1fytUCQgqr2wMroSFi_image-8-12-2023-at-151-pm.jpg" size="66" width="2032" height="358" position="flex-start" showCaption="false"} :::hint{type="info"} More information on [Invoices](https://docs.chord.co/stripe-invoices) document :::