openapi: 3.0.0 info: version: 26.0427.7514362 x-version-timestamp: 2026-04-27T13:44:44Z title: Subscriptions Introduction description: | Elastic Path Subscriptions allows you to offer your customers subscriptions and recurring billing for your plans and services. Elastic Path Subscriptions gives you the flexibility to pause, update, or reactivate your subscription offerings, change subscription cycles and apply discounts. You can create subscriptions using the Elastic Path Subscriptions API or Commerce Manager See [Subscriptions](/docs/commerce-manager/subscriptions/overview). Scenarios include: - repeat products that your customers purchase on a recurring basis. - membership subscriptions where your customers pay a recurring fee to become members of a particular service, program or organization. - subscribe and save that allows your customers to subscribe to regular deliveries of products they use frequently, for example, household essentials, or personal care items. ### How Subscriptions Work Elastic Path Subscriptions enables you to manage your subscriptions plans and pricing options, using offerings. Offerings can contain any combination of plans and pricing options. Here's how a typical subscription works: 1. Create your offerings. Offerings are the plan and pricing options that a customer can choose. An offering can consist of many combinations of a plan or pricing options, depending on the plans and services you offer. See [**Offerings**](/docs/api/subscriptions/offerings). 2. When a [**customer**](/docs/api/subscriptions/subscribers) chooses a pricing option, a subscription is created. See [**Subscriptions**](/docs/api/subscriptions/subscriptions). 3. Elastic Path Subscriptions manages the billing and recurring payments associated with the subscription. See [**Invoicing and Payments**](/docs/api/subscriptions/invoices). ### Subscriber Management Elastic Path Subscriptions enables you to create customer accounts that you can use to manage their subscription details, including payment methods and billing information. See [**Subscribers**](/docs/api/subscriptions/subscribers). ### Invoicing & Payments Elastic Path Subscriptions enables you to manage the billing and recurring payments associated with your customers subscriptions. Elastic Path Subscriptions provides seamless integration with Elastic Path Payments powered by Stripe. See [**Invoicing and Payments**](/docs/api/subscriptions/invoices). servers: - url: https://euwest.api.elasticpath.com description: EU west cluster - url: https://useast.api.elasticpath.com description: US east cluster security: - BearerToken: [] tags: - name: Features description: | A feature indicates some benefit that is received as a result of having an active subscription. This translates to tags being applied to the subscriber's account allowing access to some resource to be controlled. There are three types of feature - `access`, `promotion`, and `usage`. The `access` feature is designed to simply give access to some resource, for example a streaming service. If its tag is present on the subscriber's account then access to that resource should be provided. The `promotion` feature coupled with the [promotions service](/docs/promotions-builder/overview) allows subscribers to get access to a specific promotion. This is achieved using a tag which is used as a constraint on the promotion. A promotion feature may have multiple promotions associated with it, but just one must be selected when configuring the feature for an offering's plan. The `usage` feature is designed to measure some sort of usage of a resource. This currently relies on [commerce extensions](/docs/api/commerce-extensions/commerce-extensions-introduction) to manage usage. Once defined a feature may be attached to an offering, making it available for use with any of that offering's plans. Once attached it must be configured for each of the offering's plans it is applicable to. For the `promotion` feature this involves specifying which of that feature's tags, and hence which promotion, should be applied when subscribed to that offering. Similarly, for the `promotion` feature the default value for the usage metric must be supplied. - name: Offerings description: | An offering is a combination of plans and pricing options; plans are combined with one or more pricing options to form an offering. For example, your company provides online streaming of movies, web-series, and music. Your customers can purchase these services through either a weekly or monthly pricing option. Offering plans can be either: - a subscription plan, created within an offering. - a Product Experience Manager product, see [**Create a product**](/docs/api/pxm/products/create-product) ### Offering Examples Offerings can have any combination of plans and pricing options. The pricing of an offering is determined by the pricing you have configured for your plans and pricing options. | Example | Plan | Pricing options | Offering | | --- | --- | --- | --- | | Single plan and pricing option | One plan with a plan price of $50 | A monthly pricing option with a 5% discount | An offering with a monthly pricing option for $47.50 a month | | Single plan with multiple pricing options | One plan with a plan price of $50 | | An offering with two pricing options: | | Multiple plans and pricing option | Two plans: | A monthly pricing option with a 5% discount. | An offering with a monthly pricing option for $118.75 a month. | | Multiple plans with multiple pricing options | Two plans: | | An offering with two pricing options: | ### Building an Offering When you are building an offering: - you can create new pricing options and plans. - you can modify existing plans and pricing options. For example, you can modify the plan price or any attributes of a pricing option included in the offering. Here's how you build an offering: When [**building your offerings**](/docs/api/subscriptions/build-offering) you must supply the plans and pricing options that a customer can choose. An offering can consist of many combinations of a plan or pricing options, depending on the plans and services you offer. Plans can either be subscription plans or Product Experience Manager products. To create a Product Experience Manager product, see [**Create a product**](/docs/api/pxm/products/create-product) Pricing options are the rules that govern your subscription, for example, any discount. - You can combine and reuse pricing options for as many plans as you want, making it quick and easy to create your subscription offerings. - An offering must have at least one pricing option. - Each plan must have the appropriate pricing option associated with it When a [**customer**](/docs/api/subscriptions/subscribers) chooses a plan and pricing option, a subscription is created. See [**Subscriptions**](/docs/api/subscriptions/subscriptions). Elastic Path Subscriptions manages the billing and recurring payments associated with the subscription. See [**Invoicing and Billing**](/docs/api/subscriptions/jobs). ### Editing Offerings After saving an offering, you can, at any time: - update an offering's details, for example, name or description. See [**Update an Offering**](/docs/api/subscriptions/update-offering). - update an existing plan in an offering. See [**Update a plan in an offering**](/docs/api/subscriptions/update-offering-plan) - add a new plan in an offering. See [**Create a plan inside an offering**](/docs/api/subscriptions/create-offering-plan) - remove plans. See [**Remove a plan from an offering**](/docs/api/subscriptions/delete-offering-plan). - update an existing pricing option in an offering. See [**Update a pricing option in an offering**](/docs/api/subscriptions/update-offering-pricing-option) - add a new pricing option to an offering. See [**Create a pricing option inside an offering**](/docs/api/subscriptions/create-offering-pricing-option). - remove pricing options. See [**Removing a pricing option from an offering**](/docs/api/subscriptions/delete-offering-plan). Any modifications that you make to offerings, and plans or pricing options in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. - name: Subscriptions description: | Elastic Path Subscriptions enables you to manage your subscriptions plans and pricing options, using offerings. Offerings can contain any combination of pricing options and a plan. When a customer chooses a pricing option, a subscription is created. ### Managing the Subscription Lifecycle The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. A subscription can have the following states: - `pending` - `canceled` - `paused` - `resumed` #### Creating a pending subscription A subscription can be created in a `pending` state. This is useful for several reasons. - If there are subscriptions that require user setup or onboarding, for example, installing software or setting up preferences. This helps reduce shopper frustration during the onboarding process, as the shopper is not paying for a service that they cannot use yet. - When offering a free trial or promotion, keeping the subscription in a pending state until the trial or promotion starts or ends allows you to manage transitions more smoothly. - Before a subscription becomes active, you may need to verify the payment method or authorize the first payment. Keeping the subscription in a pending state allows time to complete these steps without activating the subscription. For a subscription with a `pending` state, you can also configure a `go_live_after` date. The subscription starts from the `go_live_after` date. This is useful as it ensures both the subscription provider and subscriber are clear about when a subscription officially begins. Once the `go_live_after` date is passed, the subscription becomes `active`, initiating the billing and payment runs. If a subscription is activated this way, you can see this in the `timestamp` meta. You can configure a `go_live_after` date to be a past date. This is useful, for example, for backdating a subscription or managing a delay in activating a subscription. Setting the `go_live_after` date in the past ensures the subscriptions timeline correctly aligns with the agreed-upon service start date. :::caution Although, billing runs generate one invoice per subscription, if a `go_live_date` is set far in the past, multiple invoices could be generated over the course of several billing runs, which could be frustrating and confusing to your subscribers. ::: See [create a subscription](/docs/api/subscriptions/create-subscription). #### Cancelling or pausing and resuming subscriptions A subscriber can decide to cancel or pause and/or resume a subscription. The following example describes pausing or canceling and resuming a subscription. 1. The subscriber pauses or cancels the subscription. - The subscription status is `active`. - either `paused` or `cancelled` is set to `true`. - either the `paused_at` or `cancelled_at` timestamp is populated with the date and time the subscription is paused or cancelled. - for cancelled subscriptions, `end_date` indicates when the subscription will expire and end. 2. When the next billing run is due, the billing run checks the subscription state. If the subscription state is paused or cancelled then no invoice is created and the subscription status is updated to `inactive`. 3. Subsequent billing runs skip that subscription completely as the subscription status is `inactive`. 4. If the subscriber resumes the subscription: - either `paused` or `cancelled` is set to `false`. - the `resumed_at` timestamp is populated with the date and time the subscription is resumed. 5. When the next billing run is due, the billing run checks the subscription state. If the `paused` or `cancelled` is set to `false` then the billing run creates an invoice. 6. The payment run processes the invoice. Once the payment succeeds then the payment run updates the status of the subscription to `active`. ### Orders When a customer chooses a subscription, they need to add the subscription to a cart, checkout the cart and then pay for the order. 1. When a customer adds a subscription to cart, this is handled using the `Add subscription to cart` endpoint. 2. Once a subscription has been added to a cart, the [**Checkout API**](/docs/api/carts/checkout-api) converts the cart to an order. 3. Once the order is created, payment needs to be taken. This is handled by Elastic Path Payments Powered by Stripe. See [**Payments**](/docs/api/subscriptions/invoices#payments). - name: Jobs description: | Jobs are an asynchronous process that can be triggered manually or scheduled. There are three types of job: - a billing run. Subscriptions generates an [**invoice**](/docs/api/subscriptions/invoices) when a billing run occurs. Billing runs generate invoices for the remaining billing cycles for each subscription. The invoice dates come from your pricing options. Billing runs are independent of payment runs. - a tax run. Invoices where `tax_required` is `true` will not have payment taken until a tax run has added the required tax to the invoice. - a payment run. The payment run identifies invoices that are outstanding and attempts to take payment for them. If the payment succeeds the the invoice is no longer outstanding. If the payment fails for any reason, then the invoice remains outstanding and is picked up by the next payment run to retry the payment. By scheduling billing and payment runs, you automate the process, reducing manual intervention and ensuring the jobs are run in a timely manner. See [**Schedules**](/docs/api/subscriptions/schedules). ### Characteristics of Billing, Tax & Payments Jobs Billing and payment jobs have the following characteristics. - Jobs are asynchronous. - Jobs have a different status, depending on where a job is in its lifecycle. - Jobs report any errors to help you understand the reason for any failed jobs. - Only one billing run and payment run is allowed per store at a time. Although billing and payments are constantly generated, the jobs are queued. Subscriptions looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. ### Billing, Tax & Payments Jobs Lifecycle A job can have the following status types: - PENDING - Subscriptions has received the request but is currently busy processing other requests. - STARTED - Subscriptions has started processing the job. - SUCCESS - The job has successfully completed. - FAILED - The job has failed. ### Billing, Tax & Payment Reports You can track your Subscriptions billing, payment and tax operations using reports. There are three types of report: - `BillingRunReport` - This report provides invoice summaries such as invoices ready for payment, invoices that require tax, and invoice failures. - `TaxRunReport` - This report provides invoice summaries such as invoices to which tax was successfully or unsuccessfully added. - `PaymentRunReport` - This report provides invoice summaries such as invoices for which payment was attempted, failed payment attempts and totals collected by a payment run. - `NotificationRunReport` - This report provides notification summaries such as notifications sent and failed to send. - `SubscriptionUpdateReport` - This report provides subscription update summaries such as subscriptions that were updated successfully and failed updates. See [Get a job](/docs/api/subscriptions/get-job) and [List jobs](/docs/api/subscriptions/list-jobs). - name: Imports description: | You can import subscription features, subscribers, offerings and subscriptions using Subscriptions Import. This is useful if you want to import subscriptions from an external system into Elastic Path Subscriptions. The API uses a [**JSONL**](https://jsonlines.org/) file. Here is an [**example of a JSONL file**](/assets/subscriptions_import.jsonl). When you send an import request, an import job is created. Jobs are processed one at a time. You can continue to send import requests, but those jobs are queued. In other words, Subscriptions looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. Use [List import jobs](/docs/api/subscriptions/list-import-jobs) to see a list of all import jobs. A file can include up to 50,000 objects. If you have more than 50,000 objects, then you must create a separate file, and import each file, one at a time. ### Characteristics of Subscriptions Import The Subscriptions Import API has the following characteristics: - The Subscriptions Import API reads the entire file and then creates the subscription objects. This means the subscription objects can be in any order in the file. - Subscriptions imports are asynchronous and are processed one at a time. You can continue to send import requests, but these are queued. - The API works on a "best endeavours" approach. In other words, the API does its best to create the subscription objects based on the file that you provide. ### Subscriptions Import File The following table describes the subscriptions objects, and their attributes, that the import file can include. | Object | Attributes | | --- | --- | | A subscriber object | The attributes you specify for a subscriber object are the attributes you specify when [creating a subscriber](/docs/api/subscriptions/create-subscriber). | | An offering object | The attributes you specify for an offering object are the attributes you specify when [building an offering](/docs/api/subscriptions/build-offering). | - name: Schedules description: | You can schedule your billing, tax, and payment runs. By scheduling billing, tax, and payment runs, you automate the process, reducing manual intervention and ensuring the jobs are run in a timely manner. You can define a schedule in the format (`* * * * *`) which is a set of five fields in a line, indicating when a job should be executed. For example, you can define a schedule so that your job runs multiple times a day, or runs on specific days and months. Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339). ### Unrestricted fields Setting a field to an asterisk (`*`) is sometimes referred to as leaving a field unrestricted because it is not restricted to a specific value. You can use the asterisk (`*`) to indicate the range of all values for the field. When you use the asterisk, the first value in the range is: 0 for the minute, hour, and day of the week (Sunday) fields, and 1 for day of the month and the month fields. ### Configuring fields The time fields have the following format and possible values and must be specified in the following order: | Field | Format | Description | | --- | --- | -----| | Minute | 0-59 | Indicates how far past the top of the hour your job runs, in minutes. For example if a minute is set to 0, then the job runs at the top of the hour because it is 0 minutes after the hour. This means if the hour is 8.00 AM, the job runs at 8.00 AM. | | Hour | 0-23 | Indicates how far past midnight your job runs, in hours. This is rounded down to the nearest hours. This is because minutes are indicated by the minute field. | | Day of the month | 0-31 | Indicates the calendar date of the month. For example, 1 for the first day of the month. | | Month | 1-12 or JAN to DEC | Indicates the month. Specify the month number or the first three letters of the month name in uppercase. For example, 1 or JAN for January. | | Day of the week | 0-6 (or SUN to SAT, or 7 for Sunday) | Indicates the day of the week. Monday is 1, Tuesday is 2, and so on. Either 0 or 7 indicates Sunday. Alternatively, specify the day of the week using the first three letters of the weekday name in uppercase. For example SUN for Sunday. If you use this field with the day of the month field, then this field is evaluated as an inclusive OR. For example, if the day of the month is set to 1 and the day of the week is set to SAT, the job runs on the first day of the month and on every Saturday of the month, even if the first day of the month is not a Saturday. If the day of the week is marked by an asterisk (*) then the field is marked as unrestricted. This means the job only runs on the first day of the month. | ### Matching all values To match all values for a field, set the field to an asterisk (`*`). When a field is set to an asterisk, the field matches all valid values for that field whenever the other field conditions are satisfied. Here are some examples. - `* 0 1 1 1`: the job runs every minute of the midnight hour on January 1st and Mondays. - `* * * * *`: the job runs every minute (of every hour, of every day of the month, of every month, every day of the week, because each of these is unrestricted). ### Matching a range To match a range of values, specify your start and stop values, separated by a hyphen (`-`). Do not include spaces in the range. Ranges are inclusive. The first number must be less than the second number. If you are using abbreviated names for the month or weekday (for example, JAN instead of 1 for the first month of the year), the first value must come earlier in the month or week than the second value. The following equivalent examples run at midnight on Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays (for all months): - `0 0 * * 1-5` - `0 0 * * MON-FRI` ### Matching a list Lists can contain any valid value for the field, including ranges. Specify your values, separated by a comma (,). Do not include spaces in the list. Examples: - `0 0,12 * * *`: the job runs at midnight and noon. - `0-5,30-35 * * * *`: the job runs in each of the first five minutes of every half hour (at the top of the hour and at half past the hour). ### Skipping values in a range You can skip values in a range by specifying a rate at which to step through the range. To do this, specify the range, followed by the forward slash (`/`) and the rate at which you want to skip through the range. The step value cannot be larger than the largest possible value for the field. The default step is 1, so the step function `/1` is the same as not using a step function at all. Example ranges that use step functions: - `*/2`: this is a valid step function for any field. - For the minute field, it matches 0, 2, 4, ... , 58. - For the hour, it matches 0, 2, 4, ... , 22. - For the day of the month, it matches 1, 3, 5, ... , 31 (for a month with 31 days). - For the month, it matches 1, 3, 5, ... , 11. - For the day of the week, it matches 0, 2, 4, 6. - `0-12/2`: this is a valid step function for the minute and hour fields. It matches 0, 2, 4, ... , 12. Example schedules using step functions: - `*/2 * * * *`: the job runs every two minutes. - `0 0-12/2 * * *`: the job runs every two hours, on the hour. The first run is at midnight. The last run is at noon. - name: Subscribers description: | A subscriber is someone who subscribes to your plan or service. - name: Invoices description: | Invoices represent the amount a customer owes for a subscription. Elastic Path Subscriptions generates an invoice for every period in a subscription billing cycle. Invoices provide: - an itemized list of goods and services provided by a subscription. - the cost of a subscription. - if applicable, any taxes. The invoice lifecycle is described below. 1. When a subscription is created, an invoice for the first billing period is created. When a subscription is created as part of an order, the payment for the order covers the first billing period. 2. Subscription invoices are created by [**billing runs**](/docs/api/subscriptions/jobs). The billing run identifies subscriptions that require a new invoice for their next billing period and creates them. At this point, invoices are marked as outstanding. 3. Invoices where `tax_required` is `true` will not have payment taken until a tax run has added the required tax to the invoice. 3. The [**payment run**](/docs/api/subscriptions/jobs) identifies invoices that are still outstanding and attempts to take payment for them. If the payment succeeds the the invoice is no longer outstanding. If the payment fails for any reason, then the invoice remains outstanding and is picked up by the next payment run to retry the payment. If an invoice has a failed payment, payment is only retried if the fixed interval has passed from the last payment attempt as defined in Settings. ### Payment Retries It is important to limit the number of times Subscriptions retries a failed payment request for many reasons, including: frequent payment retries can indicate fraudulent activities; multiple failed payment attempts can lead to customers accounts being locked out or flagged for suspicious activity resulting in poor customer experience; and excessive retries places an unnecessary load on your payment processing system. In Subscriptions, by default, the number of payment retries is 10. You can set this to a limit between 0 - 20, depending on your requirements. Each payment retry is made as a payment run. Once the number of payment retries reaches the limit, the payment retries stop, resulting in status of the invoice being unpaid. See [Invoices](#invoices). When configuring payment retries, you have the following options. | Attribute | Required | Description | | --- | --- | --- | | `payment_retry_type` | Optional | One of the following options: | | `payment_retry_interval` | Optional | Represents the retry interval. For example, if `payment_retry_unit` is `week` and `payment_retry_interval` is `1` then, the payment retry interval is 1 week. | | `payment_retry_multiplier` | Optional | Use when `payment_retry_type` is `tiered` and represents the factor by which the time duration increases after each retry. | | `payment_retry_unit` | Optional | Represents the unit of time, either `day` or `week`. | ### Rounding Subscriptions always rounds down to the penny. ### Tax Subscriptions allows you to apply any number of tax rates to your invoices and subscriptions. When applying a tax rate, you must specify: - a name that appears on your customer's invoice that describes the specific type of tax. - the tax rate which is the percentage of the subscription amount that is required to be paid as tax. In addition, you can optionally specify the jurisdiction which is the geographic area or political entity that has authority to levey and collect taxes. You can apply more than one tax rate for all items in an invoice. You cannot apply a tax rate per line item. ### Payments When your customers add a subscription to a cart and the cart is checked out, an unpaid order is returned. You can process the payment for the order though a payment gateway. You can do this using: - Elastic Path Payments Powered by Stripe. The Elastic Path Payments Powered by Stripe gateway interacts with Stripe to allow your subscribers to pay for their subscriptions. - Authorize.Net. #### Using Elastic Path Payments Powered by Stripe To use Elastic Path Payments Powered by Stripe gateway, contact the [**Customer Success Team**](mailto:customersuccess@elasticpath.com). Create your Stripe account in [**Stripe Dashboard**](https://dashboard.stripe.com/login) and complete an onboarding form to make payments using the gateway. For more information, see [**Onboarding**](/docs/payments/onboarding). Once you have signed up for Elastic Path Payments Powered by Stripe, you must configure the payment gateway so that your shoppers can make payments. See [**Configure Elastic Path Payments Powered by Stripe**](/docs/payments/onboarding). #### Using Authorize.Net To use Authorize.Net, you must have: - an active merchant account with Authorize.Net - obtained API credentials. These include an **API Login ID** and a **Transaction Key**. - Enabled Authorize.Net in Commerce Manager. See [Enabling Authorize.net](/docs/commerce-manager/payments/configure-other-payment-gateways#enabling-authorizenet). #### Payment Requests Subscriptions only supports the `purchase` payment mechanism. The gateway attempts to charge the customer immediately, and the result of the attempt is returned. If a payment fails, the invoice is kept as outstanding and the payment information, with the reason for the failure is attached to the invoice. A new payment run is required to attempt another payment. When sending a payment request to the Payments service, you must specify the following. | Attribute | Required | Description | | --- | --- | --- | | `gateway` | Required| One of `elastic_path_payments_stripe`, `authorize_net` and `stripe_payment_intents`. | | `method` | Required | Must be `purchase`. | `payment` | Required | The type of payment, for example, `pm_card_visa_debit`. | `options` | Required | These options must be set as they set up the card to be used in future without the customer being present. If these options are not set, future payments may fail. There are two options. | #### External Payments External payments are payment methods not offered by Elastic Path Subscriptions (such as Elastic Path Payments powered by Stripe or Authorize.net), but they can still be integrated with Subscriptions. To do this, you must configure your subscriptions to use external payments by setting `manual_payments` to `true`. See [Create a Subscription](/docs/api/subscriptions/create-subscription). When a subscription is created with `manual_payments` set to `true`: 1. When the payment run processes the generated invoice, it creates a pending payment. A `subscription-invoice-created` event is emitted that includes the `subscription_id`, `invoice_id` and `payment_id`. No payment is taken. 2. You can use the events generated by Elastic Path Subscriptions to configure your external payment system to respond to these events, ensuring that your external payment system knows when the payment schedule has run and it's time to process the payment. 3. When the external payment system handles the payment (either takes the payment successfully or the payment fails) the [Update Invoice Payment](/docs/api/subscriptions/update-invoice-payment) endpoint, enables the update of the pending payment. - If payment is successful, the invoice is updated to `paid` and the billing/payment cycle continues as normal. - If payment fails, the invoice continues to be marked as `outstanding`. The payment is not `pending` anymore. This is because a payment attempt has been made. Following on from this, the next payment run generates another manual pending payment. The external system is notified of this using the `subscription-invoice-payment-updated`. #### Card Declines Card payments can fail for a variety of reasons, including insufficient funds, incorrect card data or fraudulent activity. You can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details, enabling you to easily manage your subscription changes. - name: Dunning Rules description: | Dunning is the process of handling failed payment attempts. This is important for recovering revenue from failed payments, reduces customer churn and maintains cashflow. By implementing efficient dunning processes, you can enhance financial health and operational efficiency. Subscriptions enables you to create a dunning rule that allows you to configure payment retry schedules. Subscriptions retries failed payments automatically. You can customize the timing and frequency of the payment retries. Dunning is enabled by default. You can choose to disable dunning. If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments. - Do nothing - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use. - Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber. - close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment. - name: Proration Policies description: | Proration is the adjustment of charges or credits on a subscriber's account based on the amount of time a service is used. Proration ensures that subscribers are only charged for the actual time they use the service, whether they upgrade, downgrade, start, or cancel their subscription partway through a billing cycle. This means fair billing for your subscribers and provides you with the flexibility to change your subscribers subscriptions at any time. ::: note Subscriptions use client credentials to enable changes to subscriptions, so if you want your shoppers to have the ability to make changes, you can implement a BFF layer using this approach. ::: Proration occurs for: - Pricing option upgrades/downgrades: If a subscriber changes their pricing option in the middle of a billing cycle, proration adjusts the charges to reflect the time spent on each pricing option. - Service cancellation: If a subscriber cancels a subscription before the end of a billing cycle, they may receive a prorated invoice for the used portion of the subscription. - Mid-cycle subscription: If a subscriber starts a subscription in the middle of a billing cycle, they are charged a prorated amount for the remaining days in the billing cycle. There are several scenarios when implementing proration policies. 1. You may want one policy for multiple offerings because only some subscriptions need prorating. 2. You may want a default proration policy for your store. 3. You may want several policies for different offerings. In Subscriptions, charges only prorate by day. As soon as a subscriber changes their subscription, a manual billing run is triggered and an invoice is generated with the new price on the next billing run and the difference in price is prorated over days. By default, proration is not enabled for Subscriptions. Once you have attached a proration policy to an offering, proration is enabled automatically. ### End dates when switching pricing options Subscriptions manages the subscription end date when shoppers switch from one pricing option to another. Whether or not an end date is configured depends on the end behavior of the pricing options you are switching between. | Current Subscription | New Subscription | Proration Behavior | End date | | --- | --- | --- | --- | | `close` | `roll` | The subscription switches from a pricing option with a fixed end date to a rolling pricing option so no end date is set after proration. | No end date is configured. | | `roll` | `close` | The subscription switches to a fixed pricing option, and the end date is configured based on the duration of the pricing option. | An end date is configured. | | `close` | `close` | The remaining time on the current pricing option is not carried over to the new pricing option. For example, if your current pricing option has 3 months remaining and you switch to a new pricing option that has a fixed length of 6 months, the new end date is calculated as 6 months from the day you switch pricing options, effectively resetting the subscription length to the new pricing option. | New end date calculated from the day you switched pricing option. | - name: Observable Events description: | You can integrate Subscriptions with external systems like enterprise resource planning, fulfilment and other systems. For example, when a subscriber updates their address, the Customer Relationship Management system is updated with the change. Events are actions that occur in Subscriptions, such as a subscriber changing their address or a subscription changing from active to inactive. You can create custom functions that perform additional processing outside of Subscriptions, and create integrations so that when an event occurs in your store, the custom function is run. Events are processed concurrently. This means that events may not be delivered in the order they are created. For example, if a subscription is updated multiple times, the events may not be delivered in the same sequence they were updated. Events operate on an "at least once" delivery policy. We aim to deliver messages within 30 minutes or less. Ensure that you design your receiving code accordingly. For more information about integrating Subscriptions, see [**Integrations (Event Subscriptions/Notifications)**](/docs/api/integrations/integrations-event-subscriptions-notifications#integration-types). | Resource | Action | Observable Key | Availability | | --- | --- | --- | --- | | Offering | | | Store | | Subscription | | | Store | | Job | | | Store | | Invoices | | | Store | | Schedule | | | Store | | Subscriber | | | Store | paths: /v2/subscriptions/offerings: parameters: - $ref: '#/components/parameters/Filter' post: tags: - Offerings summary: Create an offering operationId: CreateOffering requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OfferingCreate' responses: '201': description: Success. The offering is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Offering' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' get: tags: - Offerings summary: List offerings description: | Retrieves a list of all subscription offerings. ### Filtering This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). The following attributes and operators are supported. | Operator | Attribute | Description | | --- | --- | --- | | `eq` | `external_ref`, `plans.external_ref`, `proration_policy_id` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | | `in` | `external_ref`, `plans.external_ref`, `proration_policy_id` | In. Checks if the value is in the specified list. If it is, the condition is true. | parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/OfferingInclude' operationId: ListOfferings responses: '200': description: Success. A list of offerings is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Offering' included: $ref: '#/components/schemas/OfferingIncludes' links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/offerings/build: post: tags: - Offerings summary: Build an offering description: | An offering includes plans and pricing options; plans are combined with one or more pricing options to form an offering. An offering can include either: - subscription plans (created within an offering). - Product Experience Manager products. See [**create a product**](/docs/api/pxm/products/create-product). When you are building an offering: - you can create new pricing options and plans. - you can modify an existing plan and pricing options. For example, you can modify the plan price or any attributes of a pricing option included in the offering. Here's how you build an offering: 1. Specify the plan to build with the offering. A plan can be: - subscription plans. Specify the subscription plan attributes. - Product Experience Manager products. Specify the Product Experience Manager product ID in `external_ref` in `PlanAttributes`. For the remaining plan attributes, you can specify their values to match the values of the existing Product Experience Manager product attributes. However, you can also specify different values, depending on your requirements. 2. Specify the pricing options to build with the offering. Pricing options are the rules that govern your subscription, for example, any discount. You can combine and reuse pricing options for as many plans as you want, making it quick and easy to create your subscription offerings. An offering must have at least one pricing option. operationId: BuildOffering requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/BuildOffering' responses: '201': description: Success. The new subscription offering is created with the specified subscription plans and pricing options attached to the offering. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Offering' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/offerings/{offering_uuid}: parameters: - name: offering_uuid in: path description: The unique identifier of the offering. required: true schema: $ref: '#/components/schemas/UUID' get: parameters: - $ref: '#/components/parameters/OfferingInclude' tags: - Offerings summary: Get offering operationId: GetOffering responses: '200': description: Success. The details of the subscription offering are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Offering' included: $ref: '#/components/schemas/OfferingIncludes' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Offerings summary: Delete offering description: When a subscription is created, it creates a snapshot of the offering. This means you can delete an offering without affecting any active subscriptions. operationId: DeleteOffering responses: '204': description: Success. The subscription offering is removed. '500': $ref: '#/components/responses/InternalServerError' put: tags: - Offerings summary: Update an offering description: | After saving an offering, you can update an offering at any time. Updating an offering does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. For fields that are optional, an existing value can be removed by specifying a value of null. operationId: UpdateOffering requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OfferingUpdate' responses: '200': description: Success. The details of the subscription offering are updated. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Offering' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/offerings/{offering_uuid}/features/{feature_uuid}: parameters: - name: offering_uuid in: path description: The unique identifier of the offering. required: true schema: $ref: '#/components/schemas/UUID' - name: feature_uuid in: path description: The unique identifier of the feature. required: true schema: $ref: '#/components/schemas/UUID' get: summary: Get a feature in an offering operationId: GetOfferingFeature tags: - Offerings responses: '200': description: Success. The details of the feature are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingFeature' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' put: summary: Updates a feature in an offering description: Use the unique identifier of the feature in the offering that you want to update. Any modifications that you make to the features in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. operationId: UpdateOfferingFeature tags: - Offerings requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OfferingFeatureUpdate' responses: '200': description: Success. The feature details are updated on the offering. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Feature' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' delete: summary: Remove a feature from an offering description: | After saving an offering, you can remove features from it at any time. Removing a feature from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created. operationId: DeleteOfferingFeature tags: - Offerings responses: '204': description: Success. The subscription feature is removed from the offering. '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' /v2/subscriptions/offerings/{offering_uuid}/features/attach: parameters: - name: offering_uuid in: path description: The unique identifier of the offering. required: true schema: $ref: '#/components/schemas/UUID' post: tags: - Offerings summary: Attach a feature description: | After saving an offering, you can attach new features to it at any time. Adding new features does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created. operationId: AttachOfferingFeature requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OfferingFeatureAttach' responses: '200': description: Success. The subscription feature is attached with the offering. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/OfferingFeature' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/offerings/{offering_uuid}/pricing-options: parameters: - name: offering_uuid in: path description: The unique identifier of the offering. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Offerings summary: List an offering's pricing options parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListOfferingPricingOptions responses: '200': description: Success. A list of pricing options attached with the offering is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/OfferingPricingOption' links: $ref: '#/components/schemas/Links' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' post: tags: - Offerings summary: Create a pricing option inside an offering description: | After saving an offering, you can add new pricing option to it at any time. operationId: CreateOfferingPricingOption requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OfferingPricingOptionCreate' responses: '201': description: Success. The pricing option is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingPricingOption' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/offerings/{offering_uuid}/pricing-options/{pricing_option_uuid}: parameters: - name: offering_uuid in: path description: The unique identifier of the offering. required: true schema: $ref: '#/components/schemas/UUID' - name: pricing_option_uuid in: path description: The unique identifier of the pricing option. required: true schema: $ref: '#/components/schemas/UUID' get: summary: Get a pricing option in an offering operationId: GetOfferingPricingOption tags: - Offerings responses: '200': description: Success. The details of the pricing option are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingPricingOption' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' put: summary: Update a pricing option in an offering operationId: UpdateOfferingPricingOption tags: - Offerings requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OfferingPricingOptionUpdate' responses: '200': description: Success. The pricing option details are updated on the offering. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingPricingOption' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Offerings summary: Remove a pricing option from an offering description: | After saving an offering, you can remove pricing options from it at any time. Removing a pricing option from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created. operationId: DeleteOfferingPricingOption responses: '204': description: Success. The subscription pricing option is no longer associated with the offering. '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' /v2/subscriptions/offerings/{offering_uuid}/features: parameters: - name: offering_uuid in: path description: The unique identifier of the offering. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Offerings summary: List an offering's features parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListOfferingFeatures responses: '200': description: Success. A list of subscription features attached to the offering is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/OfferingFeature' links: $ref: '#/components/schemas/Links' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' post: tags: - Offerings summary: Create a feature directly inside an offering description: | After saving an offering, you can add new features to it at any time. operationId: CreateOfferingFeature requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OfferingFeatureCreate' responses: '201': description: Success. The feature is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingFeature' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/offerings/{offering_uuid}/plans: parameters: - name: offering_uuid in: path description: The unique identifier of the offering. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Offerings summary: List an offering's plans parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListOfferingPlans responses: '200': description: Success. A list of subscription plans attached to the offering is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/OfferingPlan' links: $ref: '#/components/schemas/Links' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' post: tags: - Offerings summary: Create a plan inside an offering description: | After saving an offering, you can add new plans to it at any time. operationId: CreateOfferingPlan requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OfferingPlanCreate' responses: '201': description: Success. The plan is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingPlan' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}: parameters: - name: offering_uuid in: path description: The unique identifier of the offering. required: true schema: $ref: '#/components/schemas/UUID' - name: plan_uuid in: path description: The unique identifier of the plan. required: true schema: $ref: '#/components/schemas/UUID' get: summary: Get a plan in an offering operationId: GetOfferingPlan tags: - Offerings responses: '200': description: Success. The details of the plan are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingPlan' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' put: summary: Update a plan in an offering description: Use the unique identifier of the plan in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. operationId: UpdateOfferingPlan tags: - Offerings requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OfferingPlanUpdate' responses: '200': description: Success. The plan details are updated on the offering. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingPlan' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' delete: summary: Remove a plan from an offering description: | After saving an offering, you can remove plans from it at any time. Removing a plan from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created. operationId: DeleteOfferingPlan tags: - Offerings responses: '204': description: Success. The subscription plan is removed from the offering. '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' /v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}/relationships/pricing_options: parameters: - name: offering_uuid in: path description: The unique identifier of the offering. required: true schema: $ref: '#/components/schemas/UUID' - name: plan_uuid in: path description: The unique identifier of the plan. required: true schema: $ref: '#/components/schemas/UUID' get: summary: List the pricing options available to a plan in an offering operationId: ListOfferingPlanPricingOptions tags: - Offerings responses: '200': description: Success. The pricing option relationships are returned content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/RelationshipData' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' post: summary: Adds an offering's pricing options to the plan description: Use the unique identifier of the pricing in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. operationId: AddOfferingPlanPricingOptions tags: - Offerings requestBody: content: application/json: schema: $ref: '#/components/schemas/RelationshipsRequest' responses: '200': description: Success. The pricing options are added to the plan content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/RelationshipData' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' delete: summary: Removes an offering's pricing options from the plan description: Use the unique identifier of the pricing in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. operationId: RemoveOfferingPlanPricingOptions tags: - Offerings requestBody: content: application/json: schema: $ref: '#/components/schemas/RelationshipsRequest' responses: '200': description: Success. The pricing options are added to the plan content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/RelationshipData' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions: parameters: - $ref: '#/components/parameters/Filter' post: tags: - Subscriptions summary: Create a subscription operationId: CreateSubscription requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/BuildSubscription' responses: '201': description: Success. The subscription is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Subscription' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' get: tags: - Subscriptions summary: List subscriptions parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/SubscriptionInclude' operationId: ListSubscriptions description: | Retrieves a list of all subscriptions. ### Filtering This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). The following attributes and operators are supported. | Operator | Attribute | Description | | --- | --- | --- | | `eq` | `account_id`, `name`, `email`, `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | | `in` | `account_id`, `name`, `email`, `external_ref` | In. Checks if the value is in the specified list. If it is, the condition is true. | ### Including Resources You can use the `include` parameter to include the following resources with this endpoint. | Resource | Required | Description | | --- | --- | --- | | `pricing_options, plans` | Optional | Retrieves all pricing options and plans associated with a subscription. | | `plans` | Optional | Retrieves all plans associated with a subscription. | | `pricing_options` | Optional | Retrieves all pricing options associated with a subscription. | See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter). responses: '200': description: Success. A list of subscriptions is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Subscription' included: $ref: '#/components/schemas/SubscriptionIncludes' links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' get: parameters: - $ref: '#/components/parameters/SubscriptionInclude' tags: - Subscriptions summary: Get subscription operationId: GetSubscription responses: '200': description: Success. The details of a subscription are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Subscription' included: $ref: '#/components/schemas/SubscriptionIncludes' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Subscriptions summary: Update a subscription description: | Updates a subscription. For example, a subscriber can switch from one pricing option to another in a subscription. operationId: UpdateSubscription requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SubscriptionUpdate' responses: '200': description: Success. The subscription is updated. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Subscription' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Subscriptions summary: Delete a subscription operationId: DeleteSubscription description: | Deletes a subscription responses: '204': description: Success. The subscription is removed. '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/features/{feature_uuid}: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' - name: feature_uuid in: path description: The unique identifier of the feature. required: true schema: $ref: '#/components/schemas/UUID' get: summary: Get a feature in a subscription operationId: GetSubscriptionFeature tags: - Subscriptions responses: '200': description: Success. The details of the feature are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingFeature' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/plans/{plan_uuid}: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' - name: plan_uuid in: path description: The unique identifier of the plan. required: true schema: $ref: '#/components/schemas/UUID' get: summary: Get a plan in a subscription operationId: GetSubscriptionPlan tags: - Subscriptions responses: '200': description: Success. The details of the plan are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingPlan' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/pricing-options/{pricing_option_uuid}: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' - name: pricing_option_uuid in: path description: The unique identifier of the pricing option. required: true schema: $ref: '#/components/schemas/UUID' get: summary: Get a pricing option in a subscription operationId: GetSubscriptionPricingOption tags: - Subscriptions responses: '200': description: Success. The details of the pricing option are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OfferingPricingOption' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/features: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscriptions summary: List an subscriptions features operationId: ListSubscriptionFeatures parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' responses: '200': description: Success. A list of subscription features is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/OfferingFeature' links: $ref: '#/components/schemas/Links' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/plans: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscriptions summary: List subscription plans description: Retrieves a list of plans associated with the specified subscription. Using this endpoint you can see the plan that is currently active in a subscription. If `active_plan` is `true`, a plan is active in a subscription. If `active_plan` is null, the pricing option is not active. operationId: ListSubscriptionPlans responses: '200': description: Success. A list of subscription plans is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/OfferingPlan' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Subscriptions summary: Manage subscription plans description: Manage subscription plans by replacing, changing or detaching plans on the subscription operationId: ManageSubscriptionPlans requestBody: content: application/json: schema: type: object required: - data properties: data: type: array description: A list of plan IDs to manage on the subscription. items: $ref: '#/components/schemas/ManageSubscriptionPlans' example: data: - type: attach plans: - bafa601f-359c-48da-834e-377b6c0d9466 - type: detach plans: - a8aad94d-60fc-44f7-8dfa-299249566ec4 responses: '204': description: Success. The subscription's plans have been updated. '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/pricing-options: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscriptions summary: List subscription pricing options description: Retrieves a list of pricing options associated with the specified subscription. Using this endpoint you can see the pricing options that are currently active in a subscription. If `active_pricing_option` is `true`, a pricing option is active in a subscription. If `active_pricing_option` is null, the pricing option is not active. operationId: ListSubscriptionPricingOptions responses: '200': description: Success. A list of subscription pricing options is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/OfferingPricingOption' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/states: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' post: tags: - Subscriptions summary: Create a subscription state description: | The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. A subscription can have the following states: - `pending` - `canceled` - `paused` - `resumed` For more information, see [Managing the Subscription Lifecycle](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle). Immediate cancellation (`cancel` with `cancel_immediately: true`) ends the subscription and updates entitlements in this request; it does **not** issue refunds or modify paid invoices. Use payments refund flows separately if needed. operationId: CreateSubscriptionState requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ChangeState' responses: '204': description: Success. The subscription's state has changed. '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '422': $ref: '#/components/responses/UnprocessableContent' '500': $ref: '#/components/responses/InternalServerError' get: tags: - Subscriptions summary: List subscription states operationId: ListSubscriptionStates responses: '200': description: Success. A list of subscription states is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SubscriptionState' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/states/{state_uuid}: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' - name: state_uuid in: path description: The unique identifier of the subscription state. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscriptions summary: Get subscription state operationId: GetSubscriptionState responses: '200': description: Success. A subscription state is returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SubscriptionState' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/jobs: parameters: - $ref: '#/components/parameters/Filter' post: tags: - Jobs summary: Create a job operationId: CreateJob requestBody: content: application/json: schema: type: object title: JobCreateJSON required: - data properties: data: $ref: '#/components/schemas/JobCreate' responses: '201': description: Success. The job was created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Job' '400': $ref: '#/components/responses/ValidationError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' get: tags: - Jobs summary: List jobs description: | Retrieves a list of all jobs. ### Filtering This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). The following attributes and operators are supported. | Operator | Attribute | Description | | --- | --- | --- | | `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | | `in` | `external_ref` | In. Checks if the value is in the specified list. If it is, the condition is true. | parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListJobs responses: '200': description: Success. A list of jobs is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Job' links: $ref: '#/components/schemas/Links' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/jobs/{job_uuid}: parameters: - name: job_uuid in: path description: The unique identifier of the job. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Jobs summary: Get job operationId: GetJob responses: '200': description: Success. The job is returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Job' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Jobs summary: Delete job operationId: DeleteJob responses: '204': description: Success. The job was deleted. '409': $ref: '#/components/responses/WriteConflictError' /v2/subscriptions/imports: parameters: - $ref: '#/components/parameters/Filter' post: tags: - Imports summary: Import a dataset operationId: CreateImport requestBody: content: multipart/form-data: schema: type: object required: - import_file properties: external_ref: $ref: '#/components/schemas/ExternalRef' import_file: description: The JSONL file you want to upload. type: string format: binary responses: '201': description: Success. The import was started. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Import' '400': $ref: '#/components/responses/ValidationError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' get: tags: - Imports summary: List import jobs description: | Retrieves a list of all import jobs. parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListImportJobs responses: '200': description: Success. A list of import jobs is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Import' links: $ref: '#/components/schemas/Links' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/imports/{import_uuid}: parameters: - name: import_uuid in: path description: The unique identifier of the import. required: true schema: $ref: '#/components/schemas/UUID' get: parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' tags: - Imports summary: Get import description: Retrieves the import job for the specified ID. operationId: GetImport responses: '200': description: Success. The import is returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Import' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/imports/{import_uuid}/errors: parameters: - name: import_uuid in: path description: The unique identifier of the import. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Imports parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' summary: Get import errors description: | Retrieves all errors encountered as part of the import. Each error is attributed to a line in the JSONL file imported, so for example, if at line 1 in your JSONL you had a subscription_offering without a name, there would be a minimum string error for the `name` attribute with `"line_number": 1`. Errors are also ordered by line number ascending, and can be paginated. operationId: GetImportErrors responses: '200': description: Success. The import errors are returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SubscriptionImportError' links: $ref: '#/components/schemas/Links' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/invoices: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscriptions summary: List subscription invoices description: Lists all invoices for a given subscription. parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListSubscriptionInvoices responses: '200': description: Success. A list of invoices is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SubscriptionInvoice' links: $ref: '#/components/schemas/Links' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/invoices/{invoice_uuid}/payments: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' - name: invoice_uuid in: path description: The unique identifier of the invoice. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscriptions parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' summary: List subscription invoice payments description: Lists all invoice payments for a given invoice. operationId: ListSubscriptionInvoicePayments responses: '200': description: Success. Payments for the invoice are returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SubscriptionInvoicePayment' links: $ref: '#/components/schemas/Links' /v2/subscriptions/subscriptions/{subscription_uuid}/invoices/{invoice_uuid}/payments/{payment_uuid}: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' - name: invoice_uuid in: path description: The unique identifier of the invoice. required: true schema: $ref: '#/components/schemas/UUID' - name: payment_uuid in: path description: The unique identifier of the payment. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscriptions summary: Get subscription invoice payment description: Gets a specific payment for a given invoice. operationId: GetSubscriptionInvoicePayment responses: '200': description: Success. Specific payment for the invoice is returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SubscriptionInvoicePayment' '404': $ref: '#/components/responses/NotFoundError' /v2/subscriptions/subscriptions/{subscription_uuid}/invoices/{invoice_uuid}: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' - name: invoice_uuid in: path description: The unique identifier of the invoice. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscriptions summary: Get subscription invoice description: Gets a specific invoice for a given subscription. operationId: GetSubscriptionInvoice responses: '200': description: Success. An invoice is returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SubscriptionInvoice' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/invoices: get: tags: - Invoices summary: List invoices description: | Retrieves a list of all invoices. ### Filtering This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). The following attributes and operators are supported. | Operator |Attribute | Description | | --- | --- | --- | | `eq` | `subscriber_id`, `subscription_id`, `outstanding`, `tax_required` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | | `in` | `subscriber_id`, `subscription_id` | In. Checks if the value is in the specified list. If it is, the condition is true. | parameters: - $ref: '#/components/parameters/Filter' - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListInvoices responses: '200': description: Success. A list of invoices is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SubscriptionInvoice' links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/invoices/{invoice_uuid}: parameters: - name: invoice_uuid in: path description: The unique identifier of the invoice. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Invoices summary: Get invoice operationId: GetInvoice responses: '200': description: Success. The details of the invoice are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SubscriptionInvoice' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/invoices/{invoice_uuid}/payments: parameters: - name: invoice_uuid in: path description: The unique identifier of the invoice. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Invoices summary: List invoice payments parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListInvoicePayments responses: '200': description: Success. Payments for the invoice are returned content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SubscriptionInvoicePayment' links: $ref: '#/components/schemas/Links' /v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}: parameters: - name: invoice_uuid in: path description: The unique identifier of the invoice. required: true schema: $ref: '#/components/schemas/UUID' - name: payment_uuid in: path description: The unique identifier of the payment. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Invoices summary: Get invoice payment operationId: GetInvoicePayment responses: '200': description: Success. Specific payment for the invoice is returned content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SubscriptionInvoicePayment' '404': $ref: '#/components/responses/NotFoundError' put: tags: - Invoices summary: Update Invoice Payment description: | External payment methods are payment methods not offered by Elastic Path Subscriptions (such as Elastic Path Payments powered by Stripe or Authorize.net), but they can still be integrated with Subscriptions. You can use the `Update Invoice Payment` endpoint to manually update a payment against an invoice where an external payment method is handling the payment of your invoices. See [External Payments](/docs/api/subscriptions/invoices#external-payments). operationId: UpdateInvoicePayment requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/UpdateInvoicePayment' responses: '200': description: Success. Invoice payment has been updated. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SubscriptionInvoicePayment' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}/refunds: parameters: - name: invoice_uuid in: path description: The unique identifier of the invoice. required: true schema: $ref: '#/components/schemas/UUID' - name: payment_uuid in: path description: The unique identifier of the payment. required: true schema: $ref: '#/components/schemas/UUID' post: operationId: CreateInvoicePaymentRefund summary: Create a refund for an invoice payment description: Creates a refund for a paid invoice. tags: - Invoices requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/CreateInvoicePaymentRefund' responses: '201': description: Success. The payment refund is completed. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SubscriptionInvoicePaymentRefund' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '422': $ref: '#/components/responses/UnprocessableContent' '500': $ref: '#/components/responses/InternalServerError' get: parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListInvoicePaymentRefunds summary: List invoice payment refunds description: List all refunds for an invoice payments tags: - Invoices responses: '200': description: Success. Refunds for an invoice payment are returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SubscriptionInvoicePaymentRefund' links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}/refunds/{refund_uuid}: parameters: - name: invoice_uuid in: path description: The unique identifier of the invoice. required: true schema: $ref: '#/components/schemas/UUID' - name: payment_uuid in: path description: The unique identifier of the payment. required: true schema: $ref: '#/components/schemas/UUID' - name: refund_uuid in: path description: The unique identifier of the refund. required: true schema: $ref: '#/components/schemas/UUID' get: operationId: GetInvoicePaymentRefund summary: Get a refund for an invoice payment description: Get a refund for a paid invoice. tags: - Invoices responses: '200': description: Success. Specific refund for the invoice payment is returned content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SubscriptionInvoicePaymentRefund' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/schedules: parameters: - $ref: '#/components/parameters/Filter' get: tags: - Schedules summary: List schedules description: | Retrieves a list of all schedules. ### Filtering This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). The following attributes and operators are supported. | Operator | Attribute | Description | | --- | --- | --- | | `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | | `in` | `external_ref` | In. Checks if the value is in the specified list. If it is, the condition is true. | parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListSchedules responses: '200': description: Success. A list of schedules is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Schedule' links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' post: tags: - Schedules summary: Create a schedule operationId: CreateSchedule requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ScheduleCreate' responses: '201': description: Success. The schedule is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Schedule' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/schedules/{schedule_uuid}: parameters: - name: schedule_uuid in: path description: The unique identifier of the schedule. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Schedules summary: Get a schedule operationId: GetSchedule responses: '200': description: Success. A schedule is returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Schedule' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Schedules summary: Update a schedule operationId: UpdateSchedule requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ScheduleUpdate' responses: '200': description: Success. The schedule details are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Schedule' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Schedules summary: Delete schedule operationId: DeleteSchedule responses: '204': description: Success. The schedule is removed. '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscribers: parameters: - $ref: '#/components/parameters/Filter' get: tags: - Subscribers summary: List subscribers parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' operationId: ListSubscribers description: | Retrieves a list of all subscribers. ### Filtering This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). The following attributes and operators are supported. | Operator | Attribute | Description | | --- | --- | --- | | `eq` | `account_id`, `name`, `email`, `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | | `in` | `account_id`, `name`, `email`, `external_ref` | In. Checks if the value is in the specified list. If it is, the condition is true. | | `like` | `name`, `email` | Partial match (case-sensitive). Use `*` at the start, end, or both to match any sequence of characters (e.g. `*substring`, `substring*`, `*substring*`). | | `ilike` | `name`, `email` | Partial match (case-insensitive). Same as `like` but matching ignores case. Use `*` at the start, end, or both to match any sequence of characters. | responses: '200': description: Success. A list of subscribers is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Subscriber' links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' post: tags: - Subscribers summary: Create a subscriber operationId: CreateSubscriber requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SubscriberCreate' responses: '201': description: Success. The subscriber is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Subscriber' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscribers/{subscriber_uuid}: parameters: - name: subscriber_uuid in: path description: The unique identifier of the subscriber. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscribers summary: Get a subscriber operationId: GetSubscriber responses: '200': description: Success. A subscriber is returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Subscriber' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Subscribers summary: Update a subscriber operationId: UpdateSubscriber requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SubscriberUpdate' responses: '200': description: Success. The subscriber details are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Subscriber' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Subscribers summary: Delete subscriber operationId: DeleteSubscriber responses: '204': description: Success. The subscriber is removed. '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/dunning-rules: post: tags: - Dunning Rules summary: Create a dunning rule description: | Dunning rules must use a `fixed` strategy. This means payments are retried on a fixed schedule. When an invoice is created, it immediately becomes eligible for payment by the next payment run. If the first payment attempt fails then the invoice enters dunning. In subsequent payment runs, invoices are only considered for payment if they meet the dunning rules you create. You can configure a dunning rule to be the default for your store. There can only be one default rule per store. All invoices in your store will then perform dunning according to the specified rules. :::note If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments. ::: The following attributes are used to define a `fixed` schedule: - `payment_retry_unit - the unit of time used to measure the intervals between payment attempts or retries. - `payment_retry_interval` - the number of `payment_interval-units` to wait between each payment retry attempt. - `payment_retries_limit` - the number of times subscriptions attempts payments retries before an `action` is taken. - `action` - the action to take if payment is not successful. For example, if: - the `payment_retry_unit` is `days` - the `payment_retry_interval` is `2` - the `payment_rety_limit` is `10` - the `action` is `close`. Subscriptions attempts to retry the payment every 2 days until 10 payment attempts have been tried. At that point, the subscription ends and it's status changes to `inacive`. Following on from this, you can specify that the dunning rule is no longer the default. You do not have to specify another rule to replace it. If you do remove the default dunning rule, the store defaults to the behavior that is followed when dunning is not enabled. operationId: CreateDunningRule requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DunningRuleCreate' responses: '201': description: Success. The dunning rule set is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DunningRule' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' get: tags: - Dunning Rules parameters: - $ref: '#/components/parameters/Filter' - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' summary: List dunning rules description: | Retrieves a list of all dunning rule sets. operationId: ListDunningRules responses: '200': description: Success. A list of dunning rules is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/DunningRule' links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/dunning-rules/{dunning_rule_uuid}: parameters: - name: dunning_rule_uuid in: path description: The unique identifier of a dunning rule set. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Dunning Rules summary: Get dunning rule policy operationId: GetDunningRule responses: '200': description: Success. The dunning rule details are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DunningRule' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Dunning Rules summary: Update dunning rule policy description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the rule is not updated. For fields that are optional, an existing value can be removed by specifying a value of null. operationId: UpdateDunningRule requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DunningRuleUpdate' responses: '200': description: Success. The dunning rule set has been updated. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DunningRule' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Dunning Rules summary: Delete dunning rules description: You can delete a dunning rule at any time. If a dunning rule is deleted then Subscriptions reverts to the configuration used if no dunning rule is set; payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments. See [Dunning Rules](/docs/api/subscriptions/dunning-rules). operationId: DeleteDunningRule responses: '204': description: Success. The dunning rule is removed. '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/proration-policies: post: tags: - Proration Policies summary: Create a Proration Policy description: | In Subscriptions, you configure proration by creating a proration policy and attaching it to an offering. Once you have [attached](/docs/api/subscriptions/update-offering) the policy, the proration policy applies to all subscriptions that use the offering. operationId: CreateProrationPolicy requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ProrationPolicyCreate' responses: '201': description: Success. The proration policy is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ProrationPolicy' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' get: tags: - Proration Policies parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' summary: List proration policies description: | Retrieves a list of all proration policies. operationId: ListProrationPolicies responses: '200': description: Success. A list of proration policies is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ProrationPolicy' links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/proration-policies/{proration_policy_uuid}: parameters: - name: proration_policy_uuid in: path description: The unique identifier of a proration policy. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Proration Policies summary: Get proration policy operationId: GetProrationPolicy responses: '200': description: Success. The proration policy details are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ProrationPolicy' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Proration Policies summary: Update proration policy description: | You can update a proration policy at any time. For any subscriptions that are using the updated proration policy, the changes are also applied. Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the proration policy is not updated. When updating proration policies: - You can change the name of an existing policy. - You can update `rounding`. - You can update `external_ref` as long as `external_ref` is still unique in your store. - You can remove `external_ref` as this attribute is optional. - You cannot remove any required attributes, such as `name` or `rounding`. operationId: UpdateProrationPolicy requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ProrationPolicyUpdate' responses: '200': description: Success. The proration policy details are updated. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ProrationPolicy' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' delete: tags: - Proration Policies summary: Delete proration policy description: A proration policy cannot be deleted if it is being used by any subscriptions. This means you must detach a proration policy that you want to delete from any offerings using that policy before deleting the policy. See [Remove a proration policy from an offering](/docs/api/subscriptions/update-offering). operationId: DeleteProrationPolicy responses: '204': description: Success. The proration policy details are removed. '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/features: parameters: - $ref: '#/components/parameters/Filter' post: tags: - Features summary: Create a feature operationId: CreateFeature requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/FeatureCreate' responses: '201': description: Success. The feature is created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Feature' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' get: tags: - Features parameters: - $ref: '#/components/parameters/PageOffset' - $ref: '#/components/parameters/PageLimit' summary: List features description: | Retrieves a list of all subscription features. ### Filtering This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). The following attributes and operators are supported. | Operator | Attribute | Description | | --- | --- | --- | | `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | | `eq` | `tag` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | | `in` | `external_ref`, `tag` | In. Checks if the value is in the specified list. If it is, the condition is true. | operationId: ListFeatures responses: '200': description: Success. A list of features is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Feature' links: $ref: '#/components/schemas/Links' '400': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/features/{feature_uuid}: parameters: - name: feature_uuid in: path description: The unique identifier of a feature. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Features summary: Get feature operationId: GetFeature responses: '200': description: Success. The feature details are returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Feature' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Features summary: Delete feature description: Remove a feature. operationId: DeleteFeature responses: '204': description: Success. The feature is removed. '500': $ref: '#/components/responses/InternalServerError' put: tags: - Features summary: Update a feature description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the feature is not updated. For fields that are optional, an existing value can be removed by specifying a value of null. operationId: UpdateFeature requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/FeatureUpdate' responses: '200': description: Success. The feature details are updated. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Feature' '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/WriteConflictError' '500': $ref: '#/components/responses/InternalServerError' components: securitySchemes: BearerToken: scheme: bearer type: http parameters: OfferingInclude: name: include in: query required: false style: form explode: false schema: type: array description: A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter). example: plans,pricing_options items: type: string enum: - plans - pricing_options - features SubscriptionInclude: name: include in: query required: false style: form explode: false schema: type: array description: A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter). example: plans,pricing_options items: type: string enum: - plans - pricing_options Filter: name: filter in: query required: false schema: type: string format: string description: | Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports. example: eq(name,Alan Turing) PageOffset: name: page[offset] description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used. in: query required: false schema: type: integer format: int64 minimum: 0 maximum: 10000 example: 10 PageLimit: name: page[limit] description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used. in: query required: false schema: type: integer format: int64 minimum: 0 example: 100 responses: InternalServerError: description: Internal server error. There was a system failure in the platform. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal-server-error: value: errors: - title: Internal Server Error status: '500' NotFoundError: description: Not found. The requested entity does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not-found: value: errors: - title: Not Found status: '404' detail: No plan found ForbiddenError: description: Forbidden. The operation is forbidden on this entity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not-found: value: errors: - title: Permission denied status: '404' detail: 'Permission denied: plan tenancy mismatch' UnprocessableContent: description: Unprocessable Content. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: cannot-process-refund: value: errors: - title: Unprocessable Content status: '422' detail: 'Unprocessable Content: cannot process the refund' ValidationError: description: Bad request. The request failed validation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing-name: value: errors: - title: Validation Error status: '400' detail: 'data.attributes.name: "name" is required' WriteConflictError: description: Write conflict. Unable to perform the operation at this time. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - title: Write Conflict status: '409' schemas: ActivePricingOption: type: boolean description: Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription. example: true ActivePlan: type: boolean description: Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription. example: true ExternalRef: description: A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters. type: string example: abc123 maxLength: 2048 ExternalRefUpdate: description: A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters. type: string example: abc123 maxLength: 2048 nullable: true SubscriptionType: type: string example: subscription enum: - subscription ProrationPolicyType: type: string example: subscription_proration_policy enum: - subscription_proration_policy SubscriptionDunningRuleType: type: string example: subscription_dunning_rule enum: - subscription_dunning_rule SubscriptionFeatureType: type: string example: subscription_feature enum: - subscription_feature SubscriptionOfferingType: type: string example: subscription_offering enum: - subscription_offering SubscriptionOfferingFeatureType: type: string example: subscription_offering_feature enum: - subscription_offering_feature SubscriptionOfferingPlanType: type: string example: subscription_offering_plan enum: - subscription_offering_plan SubscriptionOfferingPricingOptionType: type: string example: subscription_offering_pricing_option enum: - subscription_offering_pricing_option SubscriptionJobType: type: string example: subscription_job enum: - subscription_job SubscriptionImportType: type: string example: subscription_import enum: - subscription_import SubscriptionImportErrorType: type: string example: subscription_import_error enum: - subscription_import_error SubscriptionImportError: type: object required: - id - type - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionImportErrorType' meta: $ref: '#/components/schemas/SubscriptionImportErrorMeta' SubscriptionImportErrorMeta: type: object required: - owner - timestamps - error - field - line_number properties: owner: type: string example: store timestamps: $ref: '#/components/schemas/Timestamps' error: type: string example: offering name cannot be empty field: type: string example: name line_number: type: integer description: The line in the imported JSONL file at which the validation error occurred. Starts from 1. example: 123 external_ref: $ref: '#/components/schemas/ExternalRef' SubscriptionInvoiceType: description: This represents the type of resource object being returned. Always `subscription_invoice`. type: string example: subscription_invoice enum: - subscription_invoice SubscriptionInvoicePaymentType: type: string description: This represents the type of resource object being returned. Always `subscription_invoice_payment`. example: subscription_invoice_payment enum: - subscription_invoice_payment SubscriptionInvoicePaymentRefundType: type: string description: This represents the type of resource object being returned. Always `subscription_invoice_payment_refund`. example: subscription_invoice_payment_refund enum: - subscription_invoice_payment_refund Links: type: object additionalProperties: $ref: '#/components/schemas/Link' Link: anyOf: - $ref: '#/components/schemas/LinkURI' - $ref: '#/components/schemas/LinkObject' LinkURI: type: string format: uri example: http://example.com/articles/1/comments nullable: true LinkObject: type: object properties: href: type: string format: uri example: http://example.com/articles/1/comments title: type: string example: Comments describedby: type: string format: uri example: http://example.com/schemas/article-comments Timestamps: required: - created_at - updated_at properties: updated_at: description: The date and time a resource was updated. type: string example: '2017-01-10T11:41:19.244842Z' created_at: description: The date and time a resource was created. type: string example: '2017-01-10T11:41:19.244842Z' Status: type: string description: The status of a subscription, either `active` or `inactive`. example: active enum: - active - inactive x-go-type: model.SubscriptionStatus x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model RelationshipsRequest: description: Enumerates a list of resources that are related. required: - data properties: data: type: array items: $ref: '#/components/schemas/RelationshipData' Relationships: description: Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it. additionalProperties: $ref: '#/components/schemas/Relationship' example: pricing-options: links: related: /offerings/:offering-id/pricing-options self: /offerings/:offering-id data: type: offering-pricing-option id: 625fe958-7b4b-40a0-a2c0-dbb8f31eec0d Relationship: anyOf: - $ref: '#/components/schemas/SingleRelationship' - $ref: '#/components/schemas/ManyRelationship' ManyRelationship: description: The list of resources that are related. properties: data: type: array items: $ref: '#/components/schemas/RelationshipData' links: $ref: '#/components/schemas/RelationshipLinks' SingleRelationship: description: The subscription resource that is related. properties: data: $ref: '#/components/schemas/RelationshipData' links: $ref: '#/components/schemas/RelationshipLinks' RelationshipData: type: object required: - id - type properties: id: $ref: '#/components/schemas/UUID' type: type: string description: This represents the type of resource being returned. example: 11111111-2222-3333-4444-555555555555 RelationshipLinks: description: | Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. - current - Always the current page. - first - Always the first page. - last - always `null`. - next - `null` if the user is on the first page. - previous - `null` if there is only one page. type: object properties: related: type: string example: foo.bar TimePeriod: description: A period of time between a start and end point. required: - start - end properties: start: description: The date and time a billing period started. type: string format: date-time example: '2017-07-21T17:32:28Z' end: description: The date and time a billing period ended. type: string format: date-time example: '2017-07-21T17:32:28Z' SingleCurrencyPrice: description: A price in a single currency. required: - amount - currency properties: currency: type: string description: The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price. example: USD maxLength: 1024 amount: type: integer format: int64 description: The value as a whole number of the currency's smallest subdivision. example: 100 includes_tax: type: boolean description: Whether the amount includes any taxes. example: true example: currency: USD amount: 100 includes_tax: false PriceUnits: type: object description: The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans. required: - unit - amount properties: unit: type: string description: A unit of time. enum: - day - month example: day x-go-type: model.PriceUnitsUnit x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model amount: type: integer description: The number of days or months the period covers. example: 7 minimum: 1 NullablePriceUnits: type: object nullable: true description: The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans. required: - unit - amount properties: unit: type: string description: A unit of time, either days or months. enum: - day - month example: day x-go-type: model.PriceUnitsUnit x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model amount: type: integer description: The number of days or months the period covers. example: 7 minimum: 1 Price: additionalProperties: type: object description: The base price. required: - amount properties: amount: type: integer format: int64 minimum: 0 example: 100 description: The value as a whole number of the currency's smallest subdivision. includes_tax: type: boolean example: true description: Indicates whether the amount includes any taxes. example: USD: amount: 100 includes_tax: false GBP: amount: 90 includes_tax: true NullablePrice: type: object additionalProperties: type: object required: - amount properties: amount: type: integer format: int64 example: 100 description: The value as a whole number of the currency's smallest subdivision. includes_tax: type: boolean example: true description: Whether the amount includes any taxes. nullable: true example: USD: amount: 100 includes_tax: false GBP: amount: 90 includes_tax: true nullable: true OfferingPlanPrices: type: object description: A list of plan prices for each of its pricing options. additionalProperties: $ref: '#/components/schemas/OfferingPlanPriceForPricingOption' OfferingPlanPriceForPricingOption: properties: price: $ref: '#/components/schemas/Price' display_price: $ref: '#/components/schemas/DisplayPrice' DisplayPrice: properties: without_tax: $ref: '#/components/schemas/PriceFormatting' with_tax: $ref: '#/components/schemas/PriceFormatting' tax: description: | Tax component when itemized (for example on subscription invoices). Omitted for catalog prices that only expose with/without tax. $ref: '#/components/schemas/PriceFormatting' example: without_tax: amount: 100 currency: USD formatted: $1.00 with_tax: amount: 110 currency: USD formatted: $1.10 tax: amount: 10 currency: USD formatted: $0.10 PriceFormatting: required: - amount - currency - formatted properties: amount: type: integer format: int64 example: 100 description: The unformatted amount for the objects. currency: type: string format: string example: USD description: The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price. formatted: type: string format: string example: $1.00 description: The formatted amount for the objects. Feature: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionFeatureType' attributes: $ref: '#/components/schemas/FeatureResponseAttributes' meta: $ref: '#/components/schemas/FeatureMeta' FeatureMeta: readOnly: true required: - owner - timestamps properties: owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/Timestamps' FeatureCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionFeatureType' attributes: $ref: '#/components/schemas/FeatureAttributes' FeatureUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionFeatureType' attributes: $ref: '#/components/schemas/FeatureUpdateAttributes' OfferingFeatureCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionOfferingFeatureType' attributes: $ref: '#/components/schemas/FeatureAttributes' FeatureResponseAttributes: allOf: - $ref: '#/components/schemas/FeatureAttributes' FeatureTag: type: string description: A tag to add to the customer's account when entitled to the feature. minLength: 1 maxLength: 64 pattern: ^[0-9A-Za-z_-]+$ example: digital_library_access FeatureAccessAttributes: required: - type - tag properties: type: type: string enum: - access example: access tag: $ref: '#/components/schemas/FeatureTag' FeaturePromotion: required: - name - tag properties: name: type: string description: The name of the feature. minLength: 3 maxLength: 1024 example: Digital library access tag: $ref: '#/components/schemas/FeatureTag' promotion_id: $ref: '#/components/schemas/UUID' FeaturePromotionAttributes: required: - type - promotions properties: type: type: string enum: - promotion example: promotion promotions: type: array items: $ref: '#/components/schemas/FeaturePromotion' FeatureUsageAttributes: required: - type - tag - label - default_value properties: type: type: string enum: - usage example: usage tag: $ref: '#/components/schemas/FeatureTag' label: type: string description: The property that has a usage limit. minLength: 3 maxLength: 1024 example: Digital downloads default_value: type: integer description: The default initial value example: 10 FeatureConfiguration: type: object required: - type properties: type: description: The type of feature, one of access, promotion or usage. enum: - access - promotion - usage example: access x-go-type: string oneOf: - $ref: '#/components/schemas/FeatureAccessAttributes' - $ref: '#/components/schemas/FeaturePromotionAttributes' - $ref: '#/components/schemas/FeatureUsageAttributes' discriminator: propertyName: type mapping: access: '#/components/schemas/FeatureAccessAttributes' promotion: '#/components/schemas/FeaturePromotionAttributes' usage: '#/components/schemas/FeatureUsageAttributes' FeatureAttributes: required: - name - configuration properties: external_ref: $ref: '#/components/schemas/ExternalRef' name: type: string description: The name of the feature. minLength: 3 maxLength: 1024 example: Digital library access description: type: string description: The feature description to display to customers. maxLength: 1024 example: Access to over 100 ebooks via the digital library. configuration: $ref: '#/components/schemas/FeatureConfiguration' FeatureUpdateAttributes: properties: external_ref: $ref: '#/components/schemas/ExternalRefUpdate' name: type: string description: The name of the feature. minLength: 3 maxLength: 1024 example: Digital library access description: type: string description: The feature description to display to customers. maxLength: 1024 example: Access to over 100 ebooks via the digital library. nullable: true configuration: $ref: '#/components/schemas/FeatureConfiguration' PlanMeta: readOnly: true required: - owner - timestamps properties: prices: $ref: '#/components/schemas/OfferingPlanPrices' display_price: $ref: '#/components/schemas/DisplayPrice' owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/Timestamps' active_plan: $ref: '#/components/schemas/ActivePlan' OfferingPlanCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionOfferingPlanType' attributes: $ref: '#/components/schemas/OfferingPlanAttributes' relationships: $ref: '#/components/schemas/Relationships' OfferingPlanAttributes: allOf: - $ref: '#/components/schemas/PlanAttributes' - $ref: '#/components/schemas/OfferingPlanExtraAttributes' OfferingPlanResponseAttributes: allOf: - $ref: '#/components/schemas/PlanResponseAttributes' - $ref: '#/components/schemas/OfferingPlanResponseExtraAttributes' OfferingPlanExtraAttributes: properties: feature_configurations: type: object description: A map of configurations indicating which features are available for the plan additionalProperties: $ref: '#/components/schemas/FeaturePlanConfiguration' OfferingPlanResponseExtraAttributes: required: - feature_configurations properties: feature_configurations: type: object description: A map of configurations indicating which features are available for the plan additionalProperties: $ref: '#/components/schemas/FeaturePlanConfiguration' PlanResponseAttributes: allOf: - $ref: '#/components/schemas/PlanAttributes' - $ref: '#/components/schemas/Timestamps' PlanAttributes: required: - name properties: external_ref: $ref: '#/components/schemas/ExternalRef' name: type: string description: The name of the plan. minLength: 3 maxLength: 1024 example: Magazine description: type: string description: The plan or service description to display to customers. maxLength: 1024 example: A lovely magazine that is published every month. sku: type: string description: A stock keeping unit for the plan, if appropriate. maxLength: 1024 example: MAGAZINE1 main_image: type: string format: uri description: A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported. maxLength: 1024 example: https://magazine.com/cover.jpg price: $ref: '#/components/schemas/Price' price_units: $ref: '#/components/schemas/PriceUnits' OfferingPlanUpdateAttributes: allOf: - $ref: '#/components/schemas/PlanUpdateAttributes' - $ref: '#/components/schemas/OfferingPlanUpdateExtraAttributes' OfferingPlanUpdateExtraAttributes: properties: feature_configurations: type: object description: A map of configurations indicating which features are available for the plan additionalProperties: $ref: '#/components/schemas/FeaturePlanConfigurationUpdate' PlanUpdateAttributes: properties: external_ref: $ref: '#/components/schemas/ExternalRefUpdate' name: type: string description: The name of the plan. minLength: 3 maxLength: 1024 example: Magazine description: type: string description: The plan or service description to display to customers. maxLength: 1024 example: A lovely magazine that is published every month. nullable: true sku: type: string description: A stock keeping unit for the plan, if appropriate. maxLength: 1024 example: MAGAZINE1 nullable: true main_image: type: string format: uri description: A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported. maxLength: 1024 example: https://magazine.com/cover.jpg nullable: true price: $ref: '#/components/schemas/NullablePrice' price_units: $ref: '#/components/schemas/NullablePriceUnits' DunningRule: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionDunningRuleType' attributes: $ref: '#/components/schemas/DunningRuleAttributes' meta: $ref: '#/components/schemas/DunningRuleMeta' DunningRuleMeta: readOnly: true required: - owner - timestamps properties: owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/Timestamps' DunningRuleCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionDunningRuleType' attributes: $ref: '#/components/schemas/DunningRuleAttributes' DunningRuleUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionDunningRuleType' attributes: $ref: '#/components/schemas/DunningRuleUpdateAttributes' DunningRuleAttributes: description: | The dunning rule attributes you can use to configure your payment retry strategy. example: payment_retry_type: fixed payment_retry_unit: day payment_retry_interval: 1 payment_retries_limit: 10 action: none required: - payment_retry_type - payment_retries_limit - action properties: payment_retry_type: type: string enum: - fixed - backoff - tiered example: fixed description: | The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days. x-go-type: model.PaymentRetryType x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model payment_retry_interval: type: integer format: int64 minimum: 1 maximum: 1024 example: 1 description: The number of `payment_interval_unit`s to wait between each payment retry attempt. payment_retry_unit: type: string enum: - day - week example: day description: The unit of time used to measure the intervals between payment attempts or retries. x-go-type: model.PaymentRetryUnit x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model payment_retry_multiplier: type: number format: double minimum: 1 maximum: 1024 example: 1 description: The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types. payment_retries_limit: type: integer format: int64 minimum: 0 example: 5 description: The number of times Subscriptions attempts payment retries before `action` is taken. action: type: string enum: - none - pause - close - suspend example: none description: | The action to take after all payment attempts for an invoice have failed. - None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use. - Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber. - close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment. x-go-type: model.DunningAction x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model default: type: boolean example: false description: Set to `true` if you want this rule to be the default for the store. DunningRuleUpdateAttributes: properties: payment_retry_type: type: string enum: - fixed - backoff - tiered example: fixed description: | The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days. x-go-type: model.PaymentRetryType x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model payment_retry_interval: type: integer format: int64 minimum: 1 maximum: 1024 example: 1 description: The number of `payment_interval_unit`s to wait between each payment retry attempt. nullable: true payment_retry_unit: type: string enum: - day - week example: day description: The unit of time used to measure the intervals between payment attempts or retries. nullable: true x-go-type: model.PaymentRetryUnit x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model payment_retry_multiplier: type: number format: double minimum: 1 maximum: 1024 example: 1 description: The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types. nullable: true payment_retries_limit: type: integer format: int64 minimum: 0 example: 5 description: The number of times Subscriptions attempts payment retries before `action` is taken. action: type: string enum: - none - pause - close - suspend example: none description: The action to take after all payment attempts for an invoice have failed. x-go-type: model.DunningAction x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model default: type: boolean example: false description: Set to `true` if you want this rule to be the default for the store. ProrationPolicy: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/ProrationPolicyType' attributes: $ref: '#/components/schemas/ProrationPolicyResponseAttributes' meta: $ref: '#/components/schemas/ProrationPolicyMeta' ProrationPolicyUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/ProrationPolicyType' attributes: $ref: '#/components/schemas/ProrationPolicyUpdateAttributes' ProrationPolicyRelationshipAttributes: type: object required: - type - id properties: type: $ref: '#/components/schemas/ProrationPolicyType' id: $ref: '#/components/schemas/UUID' ProrationPolicyUpdateRelationshipAttributes: type: object nullable: true required: - type - id properties: type: $ref: '#/components/schemas/ProrationPolicyType' id: $ref: '#/components/schemas/UUID' ProrationPolicyResponseAttributes: allOf: - $ref: '#/components/schemas/ProrationPolicyAttributes' ProrationPolicyCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/ProrationPolicyType' attributes: $ref: '#/components/schemas/ProrationPolicyAttributes' ProrationPolicyAttributes: required: - name - rounding properties: name: type: string description: A name for the proration policy. example: Main Policy minLength: 3 maxLength: 1024 rounding: type: string description: | When rounding in proration, you must decide how to round the units of time used to calculate the charges. - round up to the next unit, ensuring subscribers are charged slightly more to cover any partial use. - round down to the previous whole unit, providing subscribers with a slight benefit by not charging for partial use. - round to the nearest whole unit, whether up or down, based on standard rounding rules. For example, rounding 0.5 up and rounding 0.5 down. enum: - up - down - nearest example: up x-go-type: model.ProrationPolicyRounding x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model external_ref: $ref: '#/components/schemas/ExternalRef' ProrationPolicyUpdateAttributes: properties: external_ref: $ref: '#/components/schemas/ExternalRefUpdate' name: type: string description: The name of the proration policy. minLength: 3 maxLength: 1024 example: Main Policy rounding: type: string description: Whether to round up or down enum: - up - down - nearest example: up x-go-type: model.ProrationPolicyRounding x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model ProrationPolicyMeta: readOnly: true required: - owner - timestamps properties: owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/Timestamps' OfferingPricingOptionCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionOfferingPricingOptionType' attributes: $ref: '#/components/schemas/PricingOptionAttributes' PricingOptionResponseAttributes: allOf: - $ref: '#/components/schemas/PricingOptionAttributes' - $ref: '#/components/schemas/Timestamps' PricingOptionAttributes: required: - name - billing_interval_type - billing_frequency - plan_length - end_behavior - can_pause - can_resume - can_cancel properties: external_ref: $ref: '#/components/schemas/ExternalRef' name: type: string description: A name for the pricing option. example: Monthly minLength: 3 maxLength: 1024 description: type: string description: The pricing option description to display to customers. maxLength: 1024 example: A monthly subscription. billing_interval_type: type: string description: The unit of time that billing intervals are measured. example: month enum: - day - week - month - year x-go-type: model.BillingIntervalType x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model billing_frequency: type: integer description: The number of intervals between issuing bills. example: 1 minimum: 1 trial_period: type: integer description: The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month. example: 7 minimum: 0 lead_time: $ref: '#/components/schemas/LeadTime' notification_schedule: type: array x-go-type-skip-optional-pointer: true items: $ref: '#/components/schemas/NotificationSchedule' plan_length: type: integer description: The number of intervals that the subscription runs for. example: 12 minimum: 1 end_behavior: type: string description: Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments. example: close enum: - close - roll x-go-type: model.EndBehavior x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model can_pause: type: boolean description: The subscriber can pause a subscription. example: false can_resume: type: boolean description: The subscriber can resume a paused subscription. example: false can_cancel: type: boolean description: The subscriber can cancel a subscription. example: false base_price_percentage: type: number format: double description: A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering. example: 90 minimum: 0 maximum: 100 fixed_price: $ref: '#/components/schemas/Price' PricingOptionUpdateAttributes: properties: external_ref: $ref: '#/components/schemas/ExternalRefUpdate' name: type: string example: Monthly minLength: 3 maxLength: 1024 description: type: string description: The pricing option description to display to customers. example: A monthly subscription. maxLength: 1024 nullable: true billing_interval_type: type: string description: The unit of time in which billing intervals are measured. example: month enum: - day - week - month - year x-go-type: model.BillingIntervalType x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model billing_frequency: type: integer description: The number of intervals between issuing bills. example: 1 minimum: 1 trial_period: type: integer description: The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month. example: 7 minimum: 0 nullable: true plan_length: type: integer description: The length of time for which a subscription plan is valid. For example, six months after which the plan is renewed. example: 12 minimum: 1 lead_time: $ref: '#/components/schemas/NullableLeadTime' notification_schedule: type: array items: $ref: '#/components/schemas/NotificationSchedule' end_behavior: type: string description: Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments. example: close enum: - close - roll x-go-type: model.EndBehavior x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model can_pause: type: boolean description: The subscriber can pause a subscription. example: false can_resume: type: boolean description: The subscriber can resume a paused subscription. example: false can_cancel: type: boolean description: The subscriber can cancel a subscription. example: false base_price_percentage: type: number format: double description: A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering. example: 90 minimum: 0 maximum: 100 nullable: true fixed_price: $ref: '#/components/schemas/NullablePrice' BuildOffering: required: - name - plans - pricing_options properties: external_ref: $ref: '#/components/schemas/ExternalRef' name: type: string description: The name of the offering. minLength: 3 maxLength: 1024 example: Magazine description: type: string description: The offering description to display to customers. maxLength: 1024 example: A lovely magazine that is published every month. proration_policy_id: type: string description: The unique ID or external ref of the proration policy example: 11111111-2222-3333-4444-555555555555 configured_features: $ref: '#/components/schemas/OfferingBuildConfiguredFeatures' pricing_option_associations: $ref: '#/components/schemas/OfferingBuildPricingOptionAssociations' features: type: array description: Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering minItems: 1 items: anyOf: - $ref: '#/components/schemas/ExternalRef' - $ref: '#/components/schemas/FeatureAttributes' - $ref: '#/components/schemas/UUID' plans: type: array description: Plan information to be created within the offering minItems: 1 items: anyOf: - $ref: '#/components/schemas/OfferingPlanAttributes' pricing_options: type: array description: Pricing options information to be created within the offering minItems: 1 items: $ref: '#/components/schemas/PricingOptionAttributes' Offering: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionOfferingType' attributes: $ref: '#/components/schemas/OfferingResponseAttributes' relationships: $ref: '#/components/schemas/Relationships' meta: $ref: '#/components/schemas/OfferingMeta' OfferingIncludes: readOnly: true properties: features: type: array items: $ref: '#/components/schemas/OfferingFeature' plans: type: array items: $ref: '#/components/schemas/OfferingPlan' pricing_options: type: array items: $ref: '#/components/schemas/OfferingPricingOption' OfferingMeta: readOnly: true required: - owner - timestamps - external_plan_refs properties: external_plan_refs: type: array items: $ref: '#/components/schemas/OfferingPlanExternalRefMeta' owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/Timestamps' OfferingCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionOfferingType' attributes: $ref: '#/components/schemas/OfferingAttributes' relationships: $ref: '#/components/schemas/OfferingRelationships' OfferingPlanUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionOfferingPlanType' attributes: $ref: '#/components/schemas/OfferingPlanUpdateAttributes' FeatureConfigAccessAttributes: description: Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. required: - type properties: type: type: string enum: - access example: access FeatureConfigPromotionAttributes: description: Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied. required: - type - tag properties: type: type: string enum: - promotion example: promotion tag: $ref: '#/components/schemas/FeatureTag' FeatureConfigUsageAttributes: description: Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied. required: - type - default_value properties: type: type: string enum: - usage example: usage default_value: type: integer description: The default initial value example: 10 FeaturePlanConfiguration: type: object oneOf: - $ref: '#/components/schemas/FeatureConfigAccessAttributes' - $ref: '#/components/schemas/FeatureConfigPromotionAttributes' - $ref: '#/components/schemas/FeatureConfigUsageAttributes' discriminator: propertyName: type mapping: access: '#/components/schemas/FeatureConfigAccessAttributes' promotion: '#/components/schemas/FeatureConfigPromotionAttributes' usage: '#/components/schemas/FeatureConfigUsageAttributes' required: - type properties: type: description: The type of feature, one of access, promotion or usage. enum: - access - promotion - usage example: access x-go-type: string FeaturePlanConfigurationUpdate: type: object nullable: true oneOf: - $ref: '#/components/schemas/FeatureConfigAccessAttributes' - $ref: '#/components/schemas/FeatureConfigPromotionAttributes' - $ref: '#/components/schemas/FeatureConfigUsageAttributes' discriminator: propertyName: type mapping: access: '#/components/schemas/FeatureConfigAccessAttributes' promotion: '#/components/schemas/FeatureConfigPromotionAttributes' usage: '#/components/schemas/FeatureConfigUsageAttributes' required: - type properties: type: description: The type of feature, one of access, promotion or usage. enum: - access - promotion - usage example: access x-go-type: string OfferingBuildPlanPricingOptions: type: array items: type: string description: The unique ID or external ref of the pricing option example: 11111111-2222-3333-4444-555555555555 OfferingBuildPricingOptionAssociations: type: object description: A map of plans keyed by plan UUID or external_ref to a list of associated pricing options, similarly keyed. additionalProperties: $ref: '#/components/schemas/OfferingBuildPlanPricingOptions' OfferingBuildConfiguredFeatures: type: object description: Map of feature configurations keyed by plan UUID or external_ref additionalProperties: $ref: '#/components/schemas/OfferingBuildPlanFeatures' OfferingBuildPlanFeatures: type: object description: A map of configurations indicating which features are available for the plan additionalProperties: $ref: '#/components/schemas/FeaturePlanConfiguration' OfferingFeatureUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionOfferingFeatureType' attributes: $ref: '#/components/schemas/FeatureUpdateAttributes' OfferingFeature: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionOfferingFeatureType' attributes: $ref: '#/components/schemas/FeatureResponseAttributes' relationships: $ref: '#/components/schemas/Relationships' meta: $ref: '#/components/schemas/FeatureMeta' OfferingPlan: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionOfferingPlanType' attributes: $ref: '#/components/schemas/OfferingPlanResponseAttributes' relationships: $ref: '#/components/schemas/Relationships' meta: $ref: '#/components/schemas/PlanMeta' OfferingPricingOptionUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionOfferingPricingOptionType' attributes: $ref: '#/components/schemas/PricingOptionUpdateAttributes' OfferingPricingOption: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionOfferingPricingOptionType' attributes: $ref: '#/components/schemas/PricingOptionResponseAttributes' relationships: $ref: '#/components/schemas/Relationships' meta: $ref: '#/components/schemas/OfferingPricingOptionMeta' OfferingPricingOptionMeta: readOnly: true required: - owner - timestamps properties: prices: $ref: '#/components/schemas/OfferingPricingOptionPrices' price: $ref: '#/components/schemas/Price' display_price: $ref: '#/components/schemas/DisplayPrice' active_pricing_option: $ref: '#/components/schemas/ActivePricingOption' owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/Timestamps' OfferingPricingOptionPrices: type: object description: The price of each plan within the offering that this pricing option may be applied to. readOnly: true additionalProperties: $ref: '#/components/schemas/OfferingPricingOptionPriceForPlan' OfferingPricingOptionPriceForPlan: readOnly: true properties: price: $ref: '#/components/schemas/Price' display_price: $ref: '#/components/schemas/DisplayPrice' OfferingFeatureAttach: description: A list of feature IDs to attach to the offering. See [**List Features**](/docs/api/subscriptions/list-features). required: - features properties: features: type: array minItems: 1 items: $ref: '#/components/schemas/UUID' OfferingUpdate: anyOf: - required: - attributes - required: - relationships required: - id - type properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionOfferingType' attributes: $ref: '#/components/schemas/OfferingUpdateAttributes' relationships: $ref: '#/components/schemas/OfferingUpdateRelationships' OfferingResponseAttributes: allOf: - $ref: '#/components/schemas/OfferingAttributes' - $ref: '#/components/schemas/Timestamps' OfferingAttributes: required: - name properties: external_ref: $ref: '#/components/schemas/ExternalRef' name: type: string description: The name of the offering. minLength: 3 maxLength: 1024 example: Magazine description: type: string description: The offering description to display to customers. maxLength: 1024 example: A lovely magazine that is published every month. OfferingUpdateAttributes: properties: external_ref: $ref: '#/components/schemas/ExternalRefUpdate' name: type: string description: The name of the offering. minLength: 3 maxLength: 1024 example: Magazine description: type: string description: The offering description to display to customers. maxLength: 1024 example: A lovely magazine that is published every month. nullable: true OfferingRelationships: properties: proration_policy: $ref: '#/components/schemas/ProrationPolicyRelationshipAttributes' OfferingUpdateRelationships: properties: proration_policy: $ref: '#/components/schemas/ProrationPolicyUpdateRelationshipAttributes' BuildSubscriptionOrder: description: A subscription may optionally be associated with an item in an order by supplying both the order ID and the ID of the item within that order. required: - order_id - order_item_id properties: order_id: $ref: '#/components/schemas/UUID' order_item_id: $ref: '#/components/schemas/UUID' BuildSubscription: required: - account_id - currency - name - email - manual_payments properties: external_ref: $ref: '#/components/schemas/ExternalRef' account_id: $ref: '#/components/schemas/UUID' address_id: $ref: '#/components/schemas/UUID' offering_external_ref: $ref: '#/components/schemas/ExternalRef' offering_id: $ref: '#/components/schemas/UUID' plan_id: $ref: '#/components/schemas/UUID' pricing_option_id: $ref: '#/components/schemas/UUID' currency: $ref: '#/components/schemas/CurrencyIdentifier' payment_authority: $ref: '#/components/schemas/CreatePaymentAuthority' manual_payments: $ref: '#/components/schemas/ManualPayments' name: type: string minLength: 3 maxLength: 1024 example: Albert Einstein email: type: string format: email minLength: 3 maxLength: 1024 example: albert@elasticpath.com pending: type: boolean description: Whether a subscription is pending activation or not. See [Creating a pending subscription](/docs/api/subscriptions/subscriptions#creating-a-pending-subscription). example: false first_invoice_paid: type: boolean description: Indicates that payment for the first billing period of the subscription has already been taken. As well as creating the subscription a settled invoice is created to cover the first period. example: false started_at: description: When importing an active subscription from an existing system you can specify the date and time of the start of the most recent period. This may only be supplied when `first_invoice_paid` is true. As well as creating the subscription a settled invoice is created to cover the correct billing period. type: string example: '2017-01-10T11:41:19.244842Z' override_first_period_end_date: description: Optional. May only be set when `started_at` is set. When supplied, overrides the default first billing period end (start + 1 interval). The first billing period runs from the subscription start date to this date. The subscriber is charged the standard period price for the first period. Subsequent billing periods start from this date. Must be after the subscription start date. type: string format: date-time example: '2027-02-01T00:00:00Z' offering: $ref: '#/components/schemas/OfferingAttributes' features: type: array description: Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering minItems: 1 items: anyOf: - $ref: '#/components/schemas/ExternalRef' - $ref: '#/components/schemas/FeatureAttributes' - $ref: '#/components/schemas/UUID' plans: type: array minItems: 1 items: $ref: '#/components/schemas/PlanAttributesAndSelectedMeta' pricing_options: type: array minItems: 1 items: $ref: '#/components/schemas/PricingOptionAttributesAndSelectedMeta' configured_features: $ref: '#/components/schemas/OfferingBuildConfiguredFeatures' pricing_option_associations: $ref: '#/components/schemas/OfferingBuildPricingOptionAssociations' selected_plan: $ref: '#/components/schemas/ExternalRef' selected_pricing_option: $ref: '#/components/schemas/ExternalRef' order: $ref: '#/components/schemas/BuildSubscriptionOrder' meta: $ref: '#/components/schemas/SubscriptionMeta' PricingOptionAttributesAndSelectedMeta: allOf: - $ref: '#/components/schemas/PricingOptionAttributes' - $ref: '#/components/schemas/SelectedMeta' PlanAttributesAndSelectedMeta: allOf: - $ref: '#/components/schemas/PlanAttributes' - $ref: '#/components/schemas/SelectedMeta' SelectedMeta: properties: meta: $ref: '#/components/schemas/SelectedMetaAttributes' SelectedMetaAttributes: properties: selected: type: boolean example: true description: One item must be selected for use in the subscription Subscription: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionType' attributes: $ref: '#/components/schemas/SubscriptionAttributes' relationships: $ref: '#/components/schemas/Relationships' meta: $ref: '#/components/schemas/SubscriptionMeta' ManageSubscriptionPlans: type: object required: - type - plans properties: type: type: string enum: - detach example: detach x-go-type: model.ManagePlansAction x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model plans: type: array minItems: 1 items: $ref: '#/components/schemas/UUID' SubscriptionUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionType' attributes: $ref: '#/components/schemas/SubscriptionUpdateAttributes' SubscriptionUpdateAttributes: properties: pricing_option_id: type: string format: uuid x-go-type: uuid.UUID x-go-type-import: name: uuid path: github.com/google/uuid example: 00000000-0000-0000-0000-000000000001 plan_id: type: string format: uuid x-go-type: uuid.UUID x-go-type-import: name: uuid path: github.com/google/uuid example: 00000000-0000-0000-0000-000000000001 address_id: type: string format: UUID nullable: true x-go-type: uuid.UUID x-go-type-import: name: uuid path: github.com/google/uuid example: 00000000-0000-0000-0000-000000000001 payment_authority: $ref: '#/components/schemas/PaymentAuthority' go_live_after: description: The date and time a `pending` subscription goes live and becomes active. See [Creating a pending subscription](/docs/api/subscriptions/subscriptions#creating-a-pending-subscription). type: string example: '2017-01-10T11:41:19.244842Z' nullable: true SubscriptionIncludes: readOnly: true properties: plans: type: array items: $ref: '#/components/schemas/OfferingPlan' pricing_options: type: array items: $ref: '#/components/schemas/OfferingPricingOption' SubscriptionMeta: readOnly: true required: - owner - timestamps - status - canceled - paused - closed - pending - suspended - invoice_after - manual_payments - first_invoice_prepaid properties: owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/SubscriptionTimestamps' status: $ref: '#/components/schemas/Status' state: $ref: '#/components/schemas/SubscriptionState' manual_payments: $ref: '#/components/schemas/ManualPayments' first_invoice_prepaid: type: boolean description: Indicates that the first billing period of this subscription was paid for outside of the subscriptions service. example: false canceled: type: boolean description: Whether a subscription is canceled or not. example: true paused: type: boolean description: Whether a subscription is paused or not. example: true closed: type: boolean description: Whether a subscription is closed or not. example: true suspended: type: boolean description: Whether a subscription is suspended or not. example: false pending: type: boolean description: Whether a subscription is pending activation or not. example: false invoice_after: description: The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point. type: string example: '2017-01-10T11:41:19.244842Z' pending_price_change: $ref: '#/components/schemas/SubscriptionPriceChanges' price_update_history: description: A history of price updates that have been applied to this subscription. type: array x-go-type-skip-optional-pointer: true items: $ref: '#/components/schemas/SubscriptionPriceUpdateHistoryEntry' SubscriptionTimestamps: allOf: - $ref: '#/components/schemas/Timestamps' - properties: canceled_at: description: The date and time a subscription was cancelled. type: string example: '2017-01-10T11:41:19.244842Z' paused_at: description: The date and time a subscription was paused. type: string example: '2017-01-10T11:41:19.244842Z' resumed_at: description: The date and time a subscription was resumed. type: string example: '2017-01-10T11:41:19.244842Z' end_date: description: | The date and time a subscription will end. - If the subscription offering pricing option end behavior is `close`, `end_date` is set to the billing period end date upon subscription creation. - If the subscription offering pricing option end behavior is "roll": `end_date` is set to the billing period end date when the subscription is cancelled. type: string example: '2017-01-10T11:41:19.244842Z' go_live_after: description: The date and time a subscription will go live and become active. type: string example: '2017-01-10T11:41:19.244842Z' go_live: description: The date and time a subscription was released from the pending state and made active. type: string example: '2017-01-10T11:41:19.244842Z' SubscriptionAttributes: required: - account_id - pricing_option_id - plan_id - offering - currency - name - email properties: external_ref: $ref: '#/components/schemas/ExternalRef' account_id: $ref: '#/components/schemas/UUID' address_id: $ref: '#/components/schemas/UUID' offering: $ref: '#/components/schemas/Offering' pricing_option_id: $ref: '#/components/schemas/UUID' plan_id: $ref: '#/components/schemas/UUID' currency: $ref: '#/components/schemas/CurrencyIdentifier' payment_authority: $ref: '#/components/schemas/PaymentAuthority' ChangeState: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionStateType' attributes: $ref: '#/components/schemas/SubscriptionStateAttributes' SubscriptionStateAttributes: required: - action properties: action: $ref: '#/components/schemas/SubscriptionStateAction' cancel_immediately: type: boolean default: false example: false description: | When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request, and a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation. Subscribers may not set this to `true` and will receive a 403. Immediate cancellation does **not** trigger any sort of refund; those require separate API flows. SubscriptionStateType: type: string description: This represents the type of resource object being returned. Always `subscription_state`. example: subscription_state enum: - subscription_state SubscriptionStateAction: type: string description: | The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. A subscription can have the following states; `canceled`, `paused`, or `resumed`. See [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle). example: cancel enum: - cancel - pause - resume - pending x-go-type: model.SubscriptionAction x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model StateMeta: readOnly: true required: - created_at properties: created_at: description: The date and time a resource was created. type: string example: '2017-01-10T11:41:19.244842Z' SubscriptionState: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionStateType' attributes: $ref: '#/components/schemas/SubscriptionStateAttributes' meta: $ref: '#/components/schemas/StateMeta' ManualPayments: type: boolean example: false default: false description: When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments). PaymentAuthority: type: object oneOf: - $ref: '#/components/schemas/PaymentAuthorityEPPayments' - $ref: '#/components/schemas/PaymentAuthorityStripe' - $ref: '#/components/schemas/PaymentAuthorityAuthorizeNet' discriminator: propertyName: type mapping: elastic_path_payments_stripe: '#/components/schemas/PaymentAuthorityEPPayments' stripe_payment_intents: '#/components/schemas/PaymentAuthorityStripe' authorize_net: '#/components/schemas/PaymentAuthorityAuthorizeNet' required: - type properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: elastic_path_payments_stripe enum: - authorize_net - elastic_path_payments_stripe - stripe_payment_intents x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways NullablePaymentAuthority: type: object nullable: true oneOf: - $ref: '#/components/schemas/PaymentAuthorityEPPayments' - $ref: '#/components/schemas/PaymentAuthorityStripe' - $ref: '#/components/schemas/PaymentAuthorityAuthorizeNet' discriminator: propertyName: type mapping: elastic_path_payments_stripe: '#/components/schemas/PaymentAuthorityEPPayments' stripe_payment_intents: '#/components/schemas/PaymentAuthorityStripe' authorize_net: '#/components/schemas/PaymentAuthorityAuthorizeNet' required: - type properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: elastic_path_payments_stripe enum: - authorize_net - elastic_path_payments_stripe - stripe_payment_intents x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways CreatePaymentAuthority: type: object oneOf: - $ref: '#/components/schemas/CreatePaymentAuthorityEPPayments' - $ref: '#/components/schemas/CreatePaymentAuthorityStripe' - $ref: '#/components/schemas/CreatePaymentAuthorityAuthorizeNet' discriminator: propertyName: type mapping: elastic_path_payments_stripe: '#/components/schemas/CreatePaymentAuthorityEPPayments' stripe_payment_intents: '#/components/schemas/CreatePaymentAuthorityStripe' authorize_net: '#/components/schemas/CreatePaymentAuthorityAuthorizeNet' required: - type properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: elastic_path_payments_stripe enum: - authorize_net - elastic_path_payments_stripe - stripe_payment_intents x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways CreatePaymentAuthorityAuthorizeNet: type: object required: - type - payment_profile_id - customer_profile_id properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: authorize_net enum: - authorize_net x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways payment_profile_id: description: The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: '1511660856' customer_profile_id: description: The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: '1511736979' CreatePaymentAuthorityEPPayments: writeOnly: true type: object required: - type - customer_id - card_id properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: elastic_path_payments_stripe enum: - elastic_path_payments_stripe x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways customer_id: description: The unique identifier for a customer. type: string minLength: 3 maxLength: 1024 example: cus_OPfKlxWV3hp9h6 card_id: description: The unique identifier of the card used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: card_8Diw3FQPhxK27WADPVMeXieP CreatePaymentAuthorityStripe: writeOnly: true type: object required: - type - customer_id - card_id properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: stripe_payment_intents enum: - stripe_payment_intents x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways customer_id: description: The unique identifier for a customer. type: string minLength: 3 maxLength: 1024 example: cus_OPfKlxWV3hp9h6 card_id: description: The unique identifier of the card used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: card_8Diw3FQPhxK27WADPVMeXieP PaymentAuthorityAuthorizeNet: type: object required: - type properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: authorize_net enum: - authorize_net x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways payment_profile_id: description: The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: '1511660856' customer_profile_id: description: The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: '1511736979' PaymentAuthorityEPPayments: writeOnly: true type: object required: - type properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: elastic_path_payments_stripe enum: - elastic_path_payments_stripe x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways customer_id: description: The unique identifier for a customer. type: string minLength: 3 maxLength: 1024 example: cus_OPfKlxWV3hp9h6 card_id: description: The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines). type: string minLength: 3 maxLength: 1024 example: card_8Diw3FQPhxK27WADPVMeXieP PaymentAuthorityStripe: writeOnly: true type: object required: - type properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: stripe_payment_intents enum: - stripe_payment_intents x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways customer_id: description: The unique identifier for a customer. type: string minLength: 3 maxLength: 1024 example: cus_OPfKlxWV3hp9h6 card_id: description: The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines). type: string minLength: 3 maxLength: 1024 example: card_8Diw3FQPhxK27WADPVMeXieP Import: required: - type - meta - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionImportType' attributes: $ref: '#/components/schemas/ImportAttributes' meta: $ref: '#/components/schemas/ImportMeta' ImportAttributes: required: - status properties: external_ref: $ref: '#/components/schemas/ExternalRef' status: type: string description: | The status of job. - **pending** - Commerce has received the request but is currently busy processing other requests. - **started** - Commerce has started processing the job. - **success** - The job has successfully completed. - **failed** - The job has failed. enum: - pending - started - success - failed example: pending x-go-type: model.JobStatus x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model ImportMeta: readOnly: true required: - owner - timestamps - records properties: owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/JobTimestamps' records: $ref: '#/components/schemas/ImportRecords' ImportRecords: type: object description: You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported into Subscriptions. However, this does not mean they are valid subscription objects, only that they have the correct type and their JSON format is properly formatted. Imported shows the number of records that have been both validated and successfully added to Subscriptions. required: - uploaded - imported properties: uploaded: type: object properties: subscription_feature: description: The total number of features uploaded. type: integer example: 50000 subscription_subscriber: description: The total number of subscribers uploaded. type: integer example: 50000 subscription_offering: description: The total number of offerings uploaded. type: integer example: 50000 subscription: description: The total number of subscriptions uploaded. type: integer example: 50000 required: - subscription_feature - subscription_subscriber - subscription_offering - subscription imported: properties: subscription_feature: description: The total number of features uploaded. type: integer example: 50000 subscription_subscriber: description: The total number of subscribers imported. type: integer example: 45090 subscription_offering: description: The total number of offerings imported. type: integer example: 45090 subscription: description: The total number of subscriptions imported. type: integer example: 45090 required: - subscription_feature - subscription_subscriber - subscription_offering - subscription Job: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionJobType' attributes: $ref: '#/components/schemas/JobResponseAttributes' relationships: $ref: '#/components/schemas/Relationships' meta: $ref: '#/components/schemas/JobMeta' JobMeta: readOnly: true required: - owner - timestamps properties: owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/JobTimestamps' report: $ref: '#/components/schemas/JobReport' JobReport: description: You can track your Subscriptions billing, tax, and payment operations using reports. oneOf: - $ref: '#/components/schemas/BillingRunReport' - $ref: '#/components/schemas/TaxRunReport' - $ref: '#/components/schemas/PaymentRunReport' - $ref: '#/components/schemas/NotificationRunReport' - $ref: '#/components/schemas/SubscriptionUpdateReport' BillingRunReport: required: - invoices_ready_for_payment - invoices_tax_required - invoice_failures - total_ready_for_payment - total_tax_required properties: invoices_ready_for_payment: description: The total number of invoices created that are ready for payment. type: integer example: 100 invoices_tax_required: description: The total number of invoices created that need taxes to be applied before payment can be made. type: integer example: 100 invoice_failures: description: The total number of invoices that were scheduled but creation failed. type: integer example: 0 total_ready_for_payment: allOf: - description: The total amount ready for payment invoiced in the billing run, segmented by currency. - $ref: '#/components/schemas/Price' total_tax_required: allOf: - description: The total amount (excluding tax) invoiced in the billing run but still requiring taxes, segmented by currency. - $ref: '#/components/schemas/Price' TaxRunReport: required: - invoices_updated - invoice_failures properties: invoices_updated: description: The total number of invoices to which tax was successfully added. type: integer example: 100 invoice_failures: description: The total number of invoices to which tax could not be added. type: integer example: 0 PaymentRunReport: required: - total_payment_attempts - failed_payments - total_collected properties: total_payment_attempts: description: The total number of invoices for which payment was attempted. type: integer example: 100 failed_payments: description: The number of failed payment attempts. type: integer example: 0 total_collected: allOf: - description: The total amount collected by the payment run, segmented by currency. - $ref: '#/components/schemas/Price' NotificationRunReport: required: - total_notifications_sent - failed_notifications properties: total_notifications_sent: description: The total number of notifications sent. type: integer example: 100 failed_notifications: description: The number of failed notifications. type: integer example: 0 SubscriptionUpdateReport: required: - subscriptions_updated - subscription_failures - total_processed properties: subscriptions_updated: description: The total number of subscriptions updated. type: integer example: 100 subscription_failures: description: The total number of subscriptions that failed to be updated. type: integer example: 0 total_processed: description: The total number of subscriptions processed. type: integer example: 100 JobTimestamps: allOf: - $ref: '#/components/schemas/Timestamps' - properties: started_at: description: The date and time a job is started. type: string example: '2017-01-10T11:41:19.244842Z' finished_at: description: The date and time a job finished. type: string example: '2017-01-10T11:41:19.244842Z' JobCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionJobType' attributes: $ref: '#/components/schemas/JobCreateAttributes' JobResponseAttributes: allOf: - $ref: '#/components/schemas/JobCreateAttributes' - $ref: '#/components/schemas/JobAttributes' - $ref: '#/components/schemas/Timestamps' ScheduleJobType: type: string description: | The type of job. One of the following: - `billing-run` - a billing run job. - `payment-run` - a payment run job. - `notification-run` - a notification run job. enum: - billing-run - payment-run - notification-run example: billing-run x-go-type: model.JobType x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model JobCreateAttributes: required: - job_type properties: external_ref: $ref: '#/components/schemas/ExternalRef' job_type: type: string description: | The type of job. One of the following: - `billing-run` - a billing run job. - `tax-run` - a tax run job. - `payment-run` - a payment run job. - `import` - an import job. - `notification-run` - a notification run job. - `subscription-update` - a subscription update run job. enum: - billing-run - tax-run - payment-run - import - notification-run - subscription-update example: billing-run x-go-type: string oneOf: - $ref: '#/components/schemas/BillingRunJobAttributes' - $ref: '#/components/schemas/TaxRunJobAttributes' - $ref: '#/components/schemas/PaymentRunJobAttributes' - $ref: '#/components/schemas/ImportJobAttributes' - $ref: '#/components/schemas/NotificationRunJobAttributes' - $ref: '#/components/schemas/SubscriptionUpdateRunJobAttributes' discriminator: propertyName: job_type mapping: billing-run: '#/components/schemas/BillingRunJobAttributes' tax-run: '#/components/schemas/TaxRunJobAttributes' payment-run: '#/components/schemas/PaymentRunJobAttributes' import: '#/components/schemas/ImportJobAttributes' notification-run: '#/components/schemas/NotificationRunJobAttributes' subscription-update: '#/components/schemas/SubscriptionUpdateRunJobAttributes' BillingRunJobAttributes: required: - job_type properties: job_type: type: string example: billing-run TaxRunJobAttributes: required: - job_type properties: job_type: type: string example: tax-run taxes: type: array minItems: 1 items: $ref: '#/components/schemas/InvoiceTaxItems' PaymentRunJobAttributes: required: - job_type properties: job_type: type: string example: payment-run ImportJobAttributes: required: - job_type properties: job_type: type: string example: import NotificationRunJobAttributes: required: - job_type properties: job_type: type: string example: notification-run SubscriptionUpdateRunJobAttributes: required: - job_type - price_changes properties: job_type: type: string example: subscription-update offering_id: description: | The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`. type: string format: uuid x-go-type: uuid.UUID x-go-type-import: name: uuid path: github.com/google/uuid example: 11111111-2222-3333-4444-555555555555 excluded_subscription_ids: description: | Subscriptions to exclude from the price update. Only valid when `offering_id` is provided. type: array items: $ref: '#/components/schemas/UUID' x-go-type-skip-optional-pointer: true subscription_ids: description: | Specific subscriptions to update. Mutually exclusive with `offering_id`. type: array items: $ref: '#/components/schemas/UUID' x-go-type-skip-optional-pointer: true price_changes: $ref: '#/components/schemas/SubscriptionPriceChanges' SubscriptionPriceChanges: properties: plan_prices: x-go-type-skip-optional-pointer: true additionalProperties: $ref: '#/components/schemas/Price' example: 197a11f4-d341-4594-9574-7fbfbe6a671d: USD: amount: 100 includes_tax: false GBP: amount: 90 includes_tax: true pricing_option_prices: x-go-type-skip-optional-pointer: true additionalProperties: $ref: '#/components/schemas/PricingOptionPrice' example: 83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c: base_price_percentage: 90 197a11f4-d341-4594-9574-7fbfbe6a671d: USD: amount: 100 includes_tax: false GBP: amount: 90 includes_tax: true SubscriptionPriceUpdateHistoryEntry: description: A record of the previous prices of a subscription before a price change was applied required: - price_changes - valid_until properties: price_changes: $ref: '#/components/schemas/SubscriptionPriceChanges' valid_until: description: The date and time when the prices were changed (when these previous prices stopped being active) type: string format: date-time example: '2017-01-10T11:41:19.244842Z' PricingOptionPrice: properties: base_price_percentage: type: number format: double description: A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering. example: 90 minimum: 0 maximum: 100 fixed_price: $ref: '#/components/schemas/Price' JobAttributes: required: - status properties: external_ref: $ref: '#/components/schemas/ExternalRef' status: type: string description: The status of job. enum: - pending - started - success - failed example: pending x-go-type: model.JobStatus x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model InvoiceTaxItems: required: - invoice_id - tax_items properties: invoice_id: $ref: '#/components/schemas/UUID' tax_items: type: array items: $ref: '#/components/schemas/TaxItem' TaxItem: required: - type - rate properties: type: description: This represents the type of resource object being returned. Always `tax_item`. type: string enum: - tax_item example: tax_item name: description: The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`. type: string maxLength: 1024 example: GST code: description: The unique identifier assigned to goods and services for taxation purposes. type: string maxLength: 1024 example: 20.0 % S rate: description: The tax rate is the percentage of the subscription amount that is required to be paid as tax. type: number format: double example: 0.2 jurisdiction: description: The geographic area or political entity that has authority to levy and collect taxes. type: string maxLength: 1024 example: USA InvoiceNotification: description: A notification scheduled for an invoice. required: - name - due properties: name: description: The name of the notification schedule that generated this notification. type: string example: 7 days before renewal due: description: The date and time when the notification is due to be sent. type: string format: date-time example: '2024-01-24T00:00:00Z' sent_at: description: The date and time when the notification was sent. type: string format: date-time example: '2024-01-24T00:00:00Z' SubscriptionInvoice: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionInvoiceType' attributes: $ref: '#/components/schemas/SubscriptionInvoiceAttributes' relationships: $ref: '#/components/schemas/Relationships' meta: $ref: '#/components/schemas/SubscriptionInvoiceMeta' UpdateInvoicePayment: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionInvoicePaymentType' attributes: $ref: '#/components/schemas/UpdateInvoicePaymentAttributes' UpdateInvoicePaymentAttributes: required: - success properties: success: type: boolean example: true description: Whether the payment was successful. external_payment_id: type: string maxLength: 1024 example: 33e7ec6b-8b34-4c92-a95b-2e2647922e47 description: An optional external ID that is specific to the gateway used. failure_detail: description: A message generated by an external payment method that describes why a payment fails. type: string example: Card Failure payment_taken_at: description: The date and time the invoice payment was taken at. type: string example: '2017-01-10T11:41:19.244842Z' SubscriptionInvoicePayment: required: - id - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionInvoicePaymentType' attributes: $ref: '#/components/schemas/SubscriptionInvoicePaymentAttributes' meta: $ref: '#/components/schemas/SubscriptionInvoicePaymentMeta' SubscriptionInvoiceMeta: readOnly: true required: - owner - timestamps - proration_events - pro_rata_remaining_value - display_price properties: owner: $ref: '#/components/schemas/OwnerMeta' subscription_id: $ref: '#/components/schemas/UUID' subscriber_id: $ref: '#/components/schemas/UUID' price: $ref: '#/components/schemas/SingleCurrencyPrice' display_price: description: | Invoice totals formatted for display (`with_tax`, `without_tax`, `tax`). Amounts are in the currency's smallest subdivision. $ref: '#/components/schemas/DisplayPrice' notifications: description: | A list of notifications scheduled for this invoice. These are derived from the notification schedules configured on the pricing option at the time the invoice was created. Each notification has a due date calculated relative to the billing period end date. type: array items: $ref: '#/components/schemas/InvoiceNotification' timestamps: $ref: '#/components/schemas/InvoiceTimestamps' proration_events: type: array items: $ref: '#/components/schemas/ProrationEvent' pro_rata_remaining_value: type: integer format: int64 description: The pro-rated remaining value for the billing period example: 500 ProrationEvent: required: - proration_policy_id - billing_cost_before_proration - refunded_amount_for_unused_pricing_option - new_pricing_option_cost - prorated_at properties: proration_policy_id: $ref: '#/components/schemas/UUID' billing_cost_before_proration: type: integer format: int64 description: The value as a whole number of the currency's smallest subdivision example: 100 refunded_amount_for_unused_pricing_option: type: integer format: int64 description: The value as a whole number of the currency's smallest subdivision. example: 100 new_pricing_option_cost: type: integer format: int64 description: The value as a whole number of the currency's smallest subdivision. example: 100 prorated_at: description: The date and time the subscription was prorated. type: string example: '2017-01-10T11:41:19.244842Z' SubscriptionInvoicePaymentRefund: required: - id - type - attributes - relationships properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionInvoicePaymentRefundType' attributes: $ref: '#/components/schemas/SubscriptionInvoicePaymentRefundAttributes' relationships: $ref: '#/components/schemas/Relationships' SubscriptionInvoicePaymentRefundAttributes: required: - amount - reason - gateway - external_refund_id - created_at properties: amount: type: integer format: int64 minimum: 1 description: The value as a whole number of the currency's smallest subdivision. example: 100 reason: type: string maxLength: 1024 description: The reason or note for the refund example: Customer requested cancellation gateway: type: string maxLength: 1024 example: elastic_path_payments_stripe description: Specifies the payment gateway. external_refund_id: type: string maxLength: 1024 example: 33e7ec6b-8b34-4c92-a95b-2e2647922e47 description: An optional external ID that is specific to the gateway used. created_at: description: The date and time a resource was created. type: string example: '2017-01-10T11:41:19.244842Z' CreateInvoicePaymentRefund: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionInvoicePaymentRefundType' attributes: type: object required: - amount - reason properties: amount: type: integer format: int64 minimum: 1 description: The value as a whole number of the currency's smallest subdivision. example: 100 reason: type: string minLength: 1 maxLength: 1024 description: The reason or note for the refund example: Customer requested cancellation InvoiceTimestamps: allOf: - $ref: '#/components/schemas/Timestamps' - properties: taxes_added_at: description: The date and time taxes were added to an invoice. type: string example: '2017-01-10T11:41:19.244842Z' SubscriptionInvoicePaymentMeta: readOnly: true required: - owner - timestamps - invoice_id - subscription_id - job_id - manual_payment properties: owner: $ref: '#/components/schemas/OwnerMeta' subscription_id: $ref: '#/components/schemas/UUID' invoice_id: $ref: '#/components/schemas/UUID' job_id: $ref: '#/components/schemas/UUID' timestamps: $ref: '#/components/schemas/InvoicePaymentTimestamps' manual_payment: type: boolean example: false description: Whether manual payments are enabled or the payment will be handled by the configured gateway. InvoicePaymentTimestamps: allOf: - $ref: '#/components/schemas/Timestamps' - properties: payment_taken_at: description: The date and time a payment was taken. type: string example: '2017-01-10T11:41:19.244842Z' SubscriptionInvoiceAttributes: required: - billing_period - pro_forma - invoice_items - outstanding - tax_required - payment_retries_limit_reached - manual_payment_pending properties: billing_period: $ref: '#/components/schemas/TimePeriod' invoice_items: type: array items: $ref: '#/components/schemas/SubscriptionInvoiceItem' tax_items: type: array items: $ref: '#/components/schemas/TaxItem' outstanding: type: boolean description: The invoice still requires payment if `true`. example: true number: type: integer description: A sequential number assigned by the billing run. example: 1 tax_required: type: boolean description: Whether tax is required for this invoice. example: true payment_retries_limit_reached: type: boolean description: Whether the limit of payment retries has been reached. example: false updated_at: description: The date and time an invoice was updated. type: string example: '2017-01-10T11:41:19.244842Z' created_at: description: The date and time an invoice was created. type: string example: '2017-01-10T11:41:19.244842Z' pro_forma: description: | Whether the invoice is a Pro Forma invoice (generated ahead of payment) or not. Pro Forma Invoices are created ahead of payment time (for example, a week in advance of payment so you can notify customers) and will not be picked up by a payment run until on or after their valid_from date. type: boolean example: false valid_from: description: | The date and time at which an invoice will be valid from. If generated with no lead time then the invoice will be valid immediately. If generated with a lead time, then the valid_from will be the data at which the Invoice transitions from it's Pro Forma state to one that can have payment taken. type: string example: '2017-01-10T11:41:19.244842Z' manual_payment_pending: type: boolean description: Whether there is a manual pending payment pending on the invoice. example: true SubscriptionInvoicePaymentAttributes: required: - success - amount - gateway properties: success: type: boolean example: true description: Whether the payment was successful. pending: type: boolean example: true description: Whether the payment is pending (only for manual payments). gateway: type: string maxLength: 1024 example: elastic_path_payments_stripe description: Specifies the payment gateway. external_payment_id: type: string maxLength: 1024 example: 33e7ec6b-8b34-4c92-a95b-2e2647922e47 description: An optional external ID that is specific to the gateway used. failure_detail: $ref: '#/components/schemas/PaymentFailureDetail' amount: $ref: '#/components/schemas/SingleCurrencyPrice' PaymentFailureDetail: type: object description: The reason the payment failed. properties: reason: type: string example: Card Failure SubscriptionInvoiceItem: required: - description - price properties: description: type: string description: A description of the subscribed item. example: Magazine issue price: $ref: '#/components/schemas/SingleCurrencyPrice' plan_id: $ref: '#/components/schemas/UUID' from_time_period: description: The start date and time of the billing period in this price type: string example: '2017-01-10T11:41:19.244842Z' until_time_period: description: The end date and time of the billing period in this price type: string example: '2017-01-10T11:41:19.244842Z' ErrorResponse: required: - errors properties: errors: type: array items: $ref: '#/components/schemas/Error' Error: required: - status - title properties: status: type: string description: The HTTP response code of the error. example: '500' title: type: string description: A brief summary of the error. example: Internal server error detail: type: string description: Optional additional detail about the error. example: An internal error has occurred. meta: type: object description: Additional supporting meta data for the error. example: missing_ids: - e7d50bd5-1833-43c0-9848-f9d325b08be8 CurrencyIdentifier: type: string description: The three-letter [**ISO currency code**](https://www.iso.org/iso-4217-currency-codes.html) in uppercase. maxLength: 1024 example: USD UUID: type: string description: The unique identifier. format: uuid x-go-type: uuid.UUID x-go-type-import: name: uuid path: github.com/google/uuid example: 11111111-2222-3333-4444-555555555555 OwnerMeta: readOnly: true type: string format: string description: The owner of a resource, either `store` or `organization`. example: store OfferingPlanExternalRefMeta: readOnly: true type: string format: string description: The offerings plan external_ref value example: 97dddc65-eabd-45d8-b45b-2ece5cfc8c50 Subscriber: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionSubscriberType' attributes: $ref: '#/components/schemas/SubscriberResponseAttributes' meta: $ref: '#/components/schemas/SubscriberMeta' SubscriberMeta: readOnly: true required: - owner - timestamps properties: feature_entitlements: type: array description: A list of entitlement tags currently active for the subscriber example: - tag1 - tag2 items: $ref: '#/components/schemas/FeatureTag' owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/Timestamps' SubscriptionSubscriberType: type: string example: subscription_subscriber enum: - subscription_subscriber SubscriberResponseAttributes: allOf: - $ref: '#/components/schemas/SubscriberAttributes' - $ref: '#/components/schemas/Timestamps' SubscriberAttributes: required: - name - email - account_id properties: account_id: $ref: '#/components/schemas/UUID' name: type: string description: The name of the subscriber. minLength: 3 maxLength: 1024 example: John Doe email: type: string format: email description: The email of the subscriber. minLength: 3 maxLength: 1024 example: john.doe@example.com x-go-type: types.Email x-go-type-import: name: email path: github.com/oapi-codegen/runtime/types payment_authority: $ref: '#/components/schemas/PaymentAuthority' SubscriberUpdateAttributes: properties: name: type: string description: The name of the subscriber. minLength: 3 maxLength: 1024 example: John Doe email: type: string format: email description: The email of the subscriber. minLength: 3 maxLength: 1024 example: john.doe@example.com x-go-type: types.Email x-go-type-import: name: email path: github.com/oapi-codegen/runtime/types payment_authority: $ref: '#/components/schemas/NullablePaymentAuthority' SubscriberCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionSubscriberType' attributes: $ref: '#/components/schemas/SubscriberAttributes' SubscriberUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionSubscriberType' attributes: $ref: '#/components/schemas/SubscriberUpdateAttributes' ScheduleCreate: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionScheduleType' attributes: $ref: '#/components/schemas/ScheduleAttributes' Schedule: required: - type - attributes - meta properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionScheduleType' attributes: $ref: '#/components/schemas/ScheduleResponseAttributes' meta: $ref: '#/components/schemas/ScheduleMeta' ScheduleMeta: readOnly: true required: - owner - timestamps properties: scheduled_for: type: string format: date-time example: '2017-07-21T17:32:28Z' owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/Timestamps' SubscriptionScheduleType: type: string example: subscription_schedule enum: - subscription_schedule ScheduleResponseAttributes: allOf: - $ref: '#/components/schemas/ScheduleAttributes' - $ref: '#/components/schemas/Timestamps' ScheduleAttributes: required: - specification - location - job properties: external_ref: $ref: '#/components/schemas/ExternalRef' name: type: string description: The name of the schedule. minLength: 3 maxLength: 1024 example: Daily billing run. specification: type: string description: A cron-style specification of when the jobs should be created. See [**Schedules**](/docs/api/subscriptions/schedules). maxLength: 1024 example: 30 0 * * * location: type: string description: The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339). maxLength: 1024 example: Europe/London job: $ref: '#/components/schemas/ScheduleJob' ScheduleUpdateAttributes: properties: external_ref: $ref: '#/components/schemas/ExternalRefUpdate' name: type: string description: The name of the schedule. minLength: 3 maxLength: 1024 example: Daily billing run. nullable: true specification: type: string description: A cron-style specification of when the jobs should be created. maxLength: 1024 example: 30 0 * * * location: type: string description: The location of the time zone that the schedule operates in. maxLength: 1024 example: Europe/London job: $ref: '#/components/schemas/ScheduleJob' ScheduleJob: required: - job_type properties: job_type: $ref: '#/components/schemas/ScheduleJobType' ScheduleUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionScheduleType' attributes: $ref: '#/components/schemas/ScheduleUpdateAttributes' LeadTime: type: object description: Configuration of the lead time to generate an invoice ahead of time in a pro-forma state properties: type: type: string description: The unit of time that lead time is measured in. example: day enum: - day - week x-go-type: model.LeadTimeType x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model time: type: integer description: The lead time to generate an invoice ahead of time in a pro-forma state example: 14 minimum: 1 required: - type - time NullableLeadTime: type: object description: Configuration of the lead time to generate an invoice ahead of time in a pro-forma state nullable: true properties: type: type: string description: The unit of time that lead time is measured in. example: week enum: - day - week x-go-type: model.LeadTimeType x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model time: type: integer description: The lead time to generate an invoice ahead of time in a pro-forma state example: 14 minimum: 1 required: - type - time NotificationSchedule: type: object required: - name - unit - amount properties: name: type: string description: The name of the schedule. minLength: 1 maxLength: 1024 example: Daily billing run. unit: type: string description: The unit of time that the schedule is measured in. example: day enum: - day - week - month x-go-type: model.NotificationScheduleUnit x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model amount: type: integer format: int64 description: The number of units between each notification. example: 100 minimum: 1