openapi: 3.0.0
info:
  version: 1.0.0
  title: Subscriptions Introduction
  description: |
    Elastic Path Subscriptions allows you to offer your customers subscriptions and recurring billing for your products 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 products and plans, using offerings. Offerings can contain any combination of products and plans.

    Here's how a typical subscription works:

    1. Create your repeat products. See [**Repeat Products**](/docs/api/subscriptions/products).   
    2. Create your plans. Plans are the rules that govern your subscription, for example, delivery frequency, the quantity and any discount. You can combine and reuse plans for as many products as you want, making it quick and easy to create your subscription offerings. See [**Plans**](/docs/api/subscriptions/plans).
    3. Create your offerings. Offerings are the product and plans that a customer can choose. An offering can consist of many combinations of a product or plans, depending on the products and services you offer. See [**Offerings**](/docs/api/subscriptions/offerings).
    4. When a [**customer**](/docs/api/subscriptions/subscribers) chooses a plan, a subscription is created. See [**Subscriptions**](/docs/api/subscriptions/subscriptions).
    5. 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/v2
    description: EU west cluster
  - url: https://useast.api.elasticpath.com/v2
    description: US east cluster
security:
  - BearerToken: []
tags:
  - name: Products
    description: |
      Create the products and services that you want to offer in a subscription. For example, an online streaming service organization might have different services available for subscription, such as Standard Definition Streaming, High-Definition Streaming, and 4K Streaming; each service provides a specific level of video quality. 
      Products can have additional attributes, such as price, and rich media assets, such as images or files containing additional product details.

       In addition, you can build offerings with products created in Product Experience Manager. Product Experience Manager manages product information, hierarchies, and price books. Ideally, Product Experience Manager becomes the single source of truth for product data across your organization. See [**Create a Product**](/docs/api/pxm/products/create-product).

      You combine your products and plans into offerings. Offerings can contain any combination of products and plans. See [**Building an Offering**](/docs/api/subscriptions/build-offering).

      Product data is stored in a database. After you have added your products, you can update your product information at any time, and include those products in your subscription offerings.

      ### Product Media
      Images and files are linked to repeat products using a hypertext reference (HREF). You can either upload your images 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) are supported.

      ### Product Pricing
      You can assign prices for your products and services. You can display prices to your customers in their local currency. You can configure up to 10 currencies per subscription. Use the Commerce Currencies API to [**create a currency**](/docs/api/pxm/currencies/create-a-currency). You must select one currency to be the default currency. If a default currency is not selected, the store uses the United States Dollar (USD). 

      In addition, you can specify a unit price for a product. A unit price is the timeframe during which the product price is applicable, either days or months. For example, for a streaming service, the price is $12.99 and the unit price is months. 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 products that all have different prices. Rather than having to create separate plans for each product, you can specify the timeframe during which the product price is applicable and then create one plan that determines the billing frequency for those products.

      Alternatively, when creating a plan, you can configure a total price for all the products in an offering. This is useful, as it allows you to provide a fixed price for all products in an offering, enabling those products to be offered at a discounted price. The prices you specify for a plan override the individual product prices you specified when creating a product. See [**Plan Pricing**](/docs/api/subscriptions/plans#plan-pricing).
  - name: Plans
    description: |
      You can use plans to model your subscription. Plans are a set of rules and conditions that manage the provision of repeat products in an offering. 

      - **Billing Cycles** - Plans specify the frequency at which your customer is billed – yearly, monthly, or weekly. See [**Billing Cycles**](#billing-cycles).
      - **Trial Periods** - Plans specify any trial periods. See [**Trial Periods**](#trial-periods).
      - **Recurring Payments** - Plans specify if the subscription is rolling, (customers pay regularly and repeatedly), or closed (customers split purchases into a few payments). See [**Recurring Payments**](#recurring-payments).
      - **Pricing** - Plans may also specify whether a discount is offered and specify the timeframe during which the discount is available to your customers. See [**Plan Pricing**](#plan-pricing). 

      You create plans based on your business requirements. Once the plans are available, you can associate the repeat products and plans in an offering. You can combine and reuse plans in your offerings. Offerings can contain any combination of products and plans. For example, your company provides customized meal boxes; you can create different subscription plans, like weekly or monthly meal boxes at specific prices.

      ### Trial Periods

      You can configure a trial period when creating a plan by providing a value in `trial_period`. `trial_period` works with `billing_interval_type`. For example, if `billing_interval_type` is months, and `trial_period` is `1` then the trial period is 1 month. The trial period becomes active as soon as a subscription becomes active. When creating a subscription with a trial period, no payment method is required for the customer. An immediate invoice is still created, but for a price of zero.

      When a trial period ends, Subscriptions automatically generates an invoice. 

      ### Billing Cycles

      You can configure the billing cycle when creating a plan. A plan's billing cycle is determined by `billing_interval_type` and `billing_frequency`. For example, a customer with a monthly subscription set to cycle on the 2nd of the month is always billed on the second. The plan is cycled from the date a subscription becomes active. 

      You can also combine `billing_interval_type` with `trial_period` to create a [**trial period**](#trial-period). 

      ### Plan Pricing
      You can provide a price for the total cost of a plan, or, provide a discount on the total cost of all products within an offering. For example, you can configure a percentage discount on the total cost of any products within an offering.  

      You can configure a total price for all the products in an offering. This is useful, as it allows you to provide a fixed price for all products in an offering, enabling these products to be offered at a discounted price. You can enter a price for all the currencies you have configured for your store. See [**Create a Currency**](/docs/api/pxm/currencies/create-a-currency).

      Alternatively, when creating your products, you can configure individual prices for a product. The prices you specify for a plan override the individual product prices you specified when creating a product. See [**Repeat Products**](/docs/api/subscriptions/products#product-pricing).

      ### Recurring Payments
      There are two types of recurring payments:
      - customers pay regularly and repeatedly
      - customers split purchases into a few payments

      You can configure this using `end_behavior`. If `end_behaviour` is `rolling`, the customers pay regularly and repeatedly. If `end_behavior` is `closed`, it allows you to create installment plans where the customer's pay a total amount in a limited number of partial payments.
  - name: Offerings
    description: |
      An offering is a combination of products and plans; products are combined with one or more plans 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 plan.

      Offering products can be either:

      - a subscription product, see [**Create a product**](/docs/api/subscriptions/create-product).
      - a Product Experience Manager product, see [**Create a product**](/docs/api/pxm/products/create-product)

      ### Offering Examples

      Offerings can have any combination of products and plans. The pricing of an offering is determined by the pricing you have configured for your products and plans.

      | Example | Product | Plans | Offering |
      | --- | --- | --- | --- |
      | Single product and plan | One product with a product price of $50 | A monthly plan with a 5% discount | An offering with a monthly plan for $47.50 a month |
      | Single product with multiple plans | One product with a product price of $50 | <ul><li>A monthly plan with a 5% discount</li><li>A yearly plan with a 10% discount</li></ul> | An offering with two plans: <ul><li>A monthly plan for $47.50 a month</li><li>A yearly plan for $45 a month</li></ul> |
      | Multiple products and plan | Two products: <ul><li>One product with a product price of $50.</li><li>One product with a product price of $75.</li></ul> | A monthly plan with a 5% discount. | An offering with a monthly plan for $118.75 a month. | 
      | Multiple products with multiple plans | Two products: <ul><li>One product with a product price of $50.</li><li>One product with a product price of $75.</li></ul> | <ul><li>A monthly plan with a 5% discount</li><li>A yearly plan with a 10% discount</li></ul> | An offering with two plans: <ul><li>A monthly plan for $118.75 a month</li><li>A yearly plan for $112.50 a month</li></ul> | 

      ### Building an Offering

      Offerings represent a snapshot of their products and plans. If you make updates to products or plans within an offering, the original products and plans are not updated. Only the products and plans within the offering are updated. Alternatively, you can create new products or plans and attach them to a new offering.

      When you are building an offering:

      - you can create new plans and products.
      - you can modify existing products and plans. For example, you can modify the product price or any attributes of a plan included in the offering.

      Here's how you build an offering:

      1. Create your repeat products. Products can either be subscription products or Product Experience Manager products. 

           - to create a subscription product, see [**Create a product**](/docs/api/subscriptions/create-product).
           - to create a Product Experience Manager product, see [**Create a product**](/docs/api/pxm/products/create-product)
      2. Create your plans. 
           - Plans are the rules that govern your subscription, for example, any discount. 
           - You can combine and reuse plans for as many products as you want, making it quick and easy to create your subscription offerings. 
           - An offering must have at least one plan. See [**Create a plan**](/docs/api/subscriptions/create-product).
      3. [**Build your offerings**](/docs/api/subscriptions/build-offering). Offerings are the products and plans that a customer can choose. An offering can consist of many combinations of a product or plans, depending on the products and services you offer.

           - When a [**customer**](/docs/api/subscriptions/subscribers) chooses a plan, 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 the existing product and plans. 
      - replace an existing product in an offering with a new one. See [**Replace a Product**](/docs/api/subscriptions/replace-offering-product)
      - attach a new plan to an offering. See [**Attach a Plan**](/docs/api/subscriptions/attach-offering-plan).
      - remove plans. See [**Removing a plan from an offering**](/docs/api/subscriptions/delete-offering-plan).

      Any modifications that you make to offerings, and products or plans 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 products and plans, using offerings. Offerings can contain any combination of plans and a product. When a customer chooses a plan, 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 product. 

      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.
      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-with-account-management-authentication-token) 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 plans. 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. 

      See [Get a job](/docs/api/subscriptions/get-job) and [List jobs](/docs/api/subscriptions/list-jobs).
  - name: Imports
    description: |
      You can import subscription products, plans and subscribers 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 product object | The attributes you specify for a product object are the attributes you specify when [creating a product](/docs/api/subscriptions/create-product). |
      | A plan object | The attributes you specify for a product object are the attributes you specify when [creating a plan](/docs/api/subscriptions/create-plan). | 
      | A subscriber object | The attributes you specify for a product 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 a someone who subscribes to your product 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: <ul><li>`fixed` - use `fixed` if you want a fixed time interval between payment retries.</li><li>`backoff` - use `backoff` if you want the time between retry attempts to increase exponentially.</li><li>`tiered` - use `tiered` if you want to specify a list of time durations.</li></ul>  |
      | `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| Either `elastic_path_payments_stripe` or `authorize_net`. |
      | `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. <ul><li>`off_session`. Must be set to `true`. </li><li>`confirm`. Must be set to `true`.</li></ul> |

      #### 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:

      - Plan upgrades/downgrades:  If a subscriber changes their plan in the middle of a billing cycle, proration adjusts the charges to reflect the time spent on each plan.
      - 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 plans

      Subscriptions manages the subscription end date when shoppers switch from one plan to another. Whether or not an end date is configured depends on the end behavior of the plans you are switching between.

      | Current Subscription | New Subscription | Proration Behavior | End date |
      | --- | --- | --- | --- |
      | `close` | `roll` | The subscription switches from a plan with a fixed end date to a rolling plan so no end date is set after proration. | No end date is configured. |
      | `roll` | `close` | The subscription switches to a fixed plan, and the end date is configured based on the duration of the plan. | An end date is configured. |
      | `close` | `close` | The remaining time on the current plan is not carried over to the new plan. For example, if your current plan has 3 months remaining and you switch to a new plan that has a fixed length of 6 months, the new end date is calculated as 6 months from the day you switch plans, effectively resetting the subscription length to the new plan. | New end date calculated from the day you switched plan. |
  - 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 |
      | --- | --- | --- | --- |
      | Product | <ul><li>Created</li><li>Updated</li><li>Deleted</li></ul> | <ul><li>`subscription-product.created`</li><li>`subscription-product.updated`</li><li>`subscription-product.deleted`</li></ul> | Store |
      | Plan |  <ul><li>Created</li><li>Updated</li><li>Deleted</li></ul> | <ul><li>`subscription-plan.created`</li><li>`subscription-plan.updated`</li><li>`subscription-plan.deleted`</li></ul> | Store |
      | Offering |  <ul><li>Created</li><li>Updated</li><li>Deleted</li></ul> | <ul><li>`subscription-offering.created`</li><li>`subscription-offering.updated`</li><li>`subscription-offering.deleted`</li></ul> | Store |
      | Subscription | <ul><li>Created</li><li>Create-failed</li><li>Paused</li><li>Canceled</li><li>Pending-cancel</li><li>Pending-pause</li><li>Resumed</li><li>Closed</li></ul> | <ul><li>`subscription.created`</li><li>`subscription.create-failed`</li><li>`subscription.canceled`</li><li>`subscription.paused`</li><li>`subscription.pending_cancel`</li><li>`subscription.pending_pause`</li><li>`subscription.resumed`</li><li>`subscription.closed`</li></ul> | Store |
      | Job | <ul><li>Created</li><li>Updated</li><li>Deleted</li></ul> | <ul><li>`subscription-job.created`</li><li>`subscription-job.updated`</li><li>`subscription-job.deleted`</li></ul> | Store |
      | Invoices | <ul><li>Created</li><li>Deleted</li></ul> | <ul><li>`subscription-invoice.created`</li><li>`subscription-offering.deleted`</li></ul> | Store |
      | Schedule | <ul><li>Created</li><li>Updated</li><li>Deleted</li></ul> | <ul><li>`subscription-schedule.created`</li><li>`subscription-schedule.updated`</li><li>`subscription-schedule.deleted`</li></ul> | Store |
      | Subscriber | <ul><li>Created</li><li>Updated</li><li>Deleted</li></ul> | <ul><li>`subscription-subscriber.created`</li><li>`subscription-subscriber.updated`</li><li>`subscription-subscriber.deleted`</li></ul> | Store |
paths:
  /subscriptions/products:
    parameters:
      - $ref: '#/components/parameters/Filter'
    post:
      tags:
        - Products
      summary: Create a product
      operationId: CreateProduct
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/ProductCreate'
      responses:
        '201':
          description: Success. The product is created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
      summary: List products
      description: |
        Retrieves a list of all subscription products.

        ### Filtering

        This endpoint supports filtering. For the general syntax, see [**Filtering**](/docs/commerce-cloud/api-overview/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. |
      operationId: ListProducts
      responses:
        '200':
          description: Success. A list of products is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  links:
                    $ref: '#/components/schemas/Links'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/products/{product_uuid}:
    parameters:
      - name: product_uuid
        in: path
        description: The unique identifier of a product.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    get:
      tags:
        - Products
      summary: Get product
      operationId: GetProduct
      responses:
        '200':
          description: Success. The product details are returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Products
      summary: Delete product
      description: You cannot delete a product if it is part of an offering. You must detach the product from the offering first.
      operationId: DeleteProduct
      responses:
        '204':
          description: Success. The product details are removed.
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - Products
      summary: Update a product
      description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the product is not updated.
      operationId: UpdateProduct
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/ProductUpdate'
      responses:
        '200':
          description: Success. The product details are updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
        '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'
  /subscriptions/plans:
    post:
      tags:
        - Plans
      summary: Create a plan
      operationId: CreatePlan
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/PlanCreate'
      responses:
        '201':
          description: Success. The subscription plan is created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Plan'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
        - Plans
      summary: List plans
      description: |
        Retrieves a list of all subscription plans. 

        ### Filtering

        This endpoint supports filtering. For the general syntax, see [**Filtering**](/docs/commerce-cloud/api-overview/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. |
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
      operationId: ListPlans
      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/Plan'
                  links:
                    $ref: '#/components/schemas/Links'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/plans/{plan_uuid}:
    parameters:
      - name: plan_uuid
        in: path
        description: The unique identifier of the plan.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    get:
      tags:
        - Plans
      summary: Get plan
      operationId: GetPlan
      responses:
        '200':
          description: Success. The details of the plan are returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Plan'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Plans
      summary: Delete plan
      description: You must not delete a plan if it is associated with an offering as this invalidates the offering. You must detach a plan from an offering before deleting it.
      operationId: DeletePlan
      responses:
        '204':
          description: Success. The subscription plan is removed.
    put:
      tags:
        - Plans
      summary: Update a plan
      description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the plan is not updated.
      operationId: UpdatePlan
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/PlanUpdate'
      responses:
        '200':
          description: Success. The details of the plan are updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Plan'
        '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'
  /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**](/docs/commerce-cloud/api-overview/filtering).

        The following attributes and operators are supported.

        | Operator | Attribute | Description |
        | --- | --- | --- | 
        | `eq` | `external_ref`, `proration_policy_id` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
        | `in` | `external_product_refs` | In. Checks if the values are included in the specified string. If they are, the condition is true. |
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/Include'
      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'
  /subscriptions/offerings/build:
    post:
      tags:
        - Offerings
      summary: Build an offering
      description: |
        An offering includes products and plans; products are combined with one or more plans to form an offering. An offering can include either:

        - subscription products. See [**create a product**](/docs/api/subscriptions/create-product).
        - Product Experience Manager products. See [**create a product**](/docs/api/pxm/products/create-product).

        Offerings represent a snapshot of their products and plans. If you make updates to products or plans within an offering, the original products and plans are not updated. Only the products and plans within the offering are updated. Alternatively, you can create new products or plans and attach them to an existing offering.

        When you are building an offering:

        - you can create new plans and products.
        - you can modify an existing product and plans. For example, you can modify the product price or any attributes of a plan included in the offering.

        Here's how you build an offering:

        1. Specify the product to build with the offering. A product can be:

             - subscription products. Specify the subscription product attributes. 
             - Product Experience Manager products. Specify the Product Experience Manager product ID in `external_ref` in `ProductAttributes`. For the remaining product 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 plans to build with the offering. Plans are the rules that govern your subscription, for example, any discount. You can combine and reuse plans for as many products as you want, making it quick and easy to create your subscription offerings.
          An offering must have at least one plan. 
      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 products and plans 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'
  /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/Include'
      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.
      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'
  /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 plans attached with 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'
  /subscriptions/offerings/{offering_uuid}/plans/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 plan
      description: |
        After saving an offering, you can attach new plans to it at any time.

        Attaching new plans to an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created.
      operationId: AttachOfferingPlan
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/OfferingPlanAttach'
      responses:
        '200':
          description: Success. The subscription plan is attached with the offering.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OfferingPlan'
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /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'
    put:
      summary: Updates a plan in an offering
      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:
      tags:
        - Offerings
      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
      responses:
        '204':
          description: Success. The subscription plan is no longer associated with the offering.
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
  /subscriptions/offerings/{offering_uuid}/products:
    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 products
      parameters:
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/PageLimit'
      operationId: ListOfferingProducts
      responses:
        '200':
          description: Success. A list of subscription products attached to the offering is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OfferingProduct'
                  links:
                    $ref: '#/components/schemas/Links'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/offerings/{offering_uuid}/products/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 product
      description: |
        After saving an offering, you can attach new products to it at any time.

        Adding new products does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created.
      operationId: AttachOfferingProduct
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/OfferingProductAttach'
      responses:
        '200':
          description: Success. The subscription product is attached with the offering.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OfferingProduct'
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/offerings/{offering_uuid}/products/replace:
    parameters:
      - name: offering_uuid
        in: path
        description: The unique identifier of the offering.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    put:
      tags:
        - Offerings
      summary: Replace a product
      description: |
        After saving an offering, you can replace its products at any time.

        Replacing products on an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created.
      operationId: ReplaceOfferingProduct
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/OfferingProductReplace'
      responses:
        '200':
          description: Success. The subscription product is replaced on the offering.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OfferingProduct'
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/offerings/{offering_uuid}/relationships/proration-policies:
    parameters:
      - name: offering_uuid
        in: path
        description: The unique identifier of the offering.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    put:
      tags:
        - Offerings
      summary: Manage prorations on an offering
      description: |
        Proration ensures that subscribers are only charged for the actual time they use a service, whether they upgrade, downgrade, start, or cancel their subscription partway through a billing cycle. By default, proration is not enabled for Subscriptions. Once you have attached a proration policy to an offering, proration is enabled automatically.

        You must create a proration policy before you can attach the policy to an offering. See [Create a Proration Policy](/docs/api/subscriptions/create-proration-policy).
      operationId: ManageProrationsOnOffering
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/ProrationPolicyRelationshipAttributes'
      responses:
        '200':
          description: Success. A proration policy relationship is added to the offering.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ProrationPolicyRelationshipAttributes'
        '204':
          description: Success. A proration policy relationship has been removed from the offering.
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/offerings/{offering_uuid}/products/{product_uuid}:
    parameters:
      - name: offering_uuid
        in: path
        description: The unique identifier of the offering.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      - name: product_uuid
        in: path
        description: The unique identifier of the product.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
    put:
      summary: Updates a product in an offering
      description: Use the unique identifier of the product in the offering that you want to update. Any modifications that you make to the products in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created.
      operationId: UpdateOfferingProduct
      tags:
        - Offerings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/OfferingProductUpdate'
      responses:
        '200':
          description: Success. The product details are updated on the offering.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
        '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 product from an offering
      description: |
        After saving an offering, you can remove products from it at any time.

         Removing a product from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created.
      operationId: DeleteOfferingProduct
      tags:
        - Offerings
      responses:
        '204':
          description: Success. The subscription product is removed from the offering.
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
  /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/Include'
      operationId: ListSubscriptions
      description: |
        Retrieves a list of all subscriptions.

        ### Filtering

        This endpoint supports filtering. For the general syntax, see [**Filtering**](/docs/commerce-cloud/api-overview/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. |

        ### Including Resources

        You can use the `include` parameter to include the following resources with this endpoint.

        | Resource | Required | Description |
        | --- | --- | --- |
        | `plans, products` | Optional | Retrieves all plans and products associated with a subscription. |
        | `products` | Optional | Retrieves all products associated with a subscription. |
        | `plans` | Optional | Retrieves all plans associated with a subscription. |

        See [Characteristics of Include Parameter](/docs/commerce-cloud/api-overview/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'
  /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/Include'
      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 plan 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'
  /subscriptions/subscriptions/{subscription_uuid}/products:
    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 products
      description: Retrieves a list of products associated with the specified subscription.
      operationId: ListSubscriptionProducts
      responses:
        '200':
          description: Success. A list of subscription products is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OfferingProduct'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - Subscriptions
      summary: Manage subscription products
      description: Manage subscription products by replacing, changing or detaching products on the subscription
      operationId: ManageSubscriptionProducts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: array
                  description: A list of product IDs to manage on the subscription.
                  items:
                    $ref: '#/components/schemas/ManageSubscriptionProducts'
              example:
                data:
                  - type: attach
                    products:
                      - bafa601f-359c-48da-834e-377b6c0d9466
                  - type: detach
                    products:
                      - a8aad94d-60fc-44f7-8dfa-299249566ec4
      responses:
        '204':
          description: Success. The subscription's products have been updated.
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /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 plans that are currently active in a subscription. If `active_plan` is `true`, a plan is active in a subscription. If `active_plan` is null, the plan 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'
  /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 product. 

        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).
      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'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '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'
  /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'
  /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**](/docs/commerce-cloud/api-overview/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. |
      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'
  /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'
  /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'
  /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:
      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'
  /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'
  /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'
  /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'
  /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'
  /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**](/docs/commerce-cloud/api-overview/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. |
      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'
  /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'
  /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'
  /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'
  /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**](/docs/commerce-cloud/api-overview/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. |
      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'
  /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'
  /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**](/docs/commerce-cloud/api-overview/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. |
      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'
  /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'
  /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'
  /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.
      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'
  /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/manage-prorations-on-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'
  /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/manage-prorations-on-offering).
      operationId: DeleteProrationPolicy
      responses:
        '204':
          description: Success. The proration policy details are removed.
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    BearerToken:
      scheme: bearer
      type: http
  parameters:
    Include:
      name: include
      in: query
      required: false
      schema:
        type: string
        description: A comma-separated list of resources to include. See [Characteristics of Include Parameter](/docs/commerce-cloud/api-overview/includes#characteristics-of-include-parameter).
        example: products,plans
    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**](/docs/commerce-cloud/api-overview/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'
    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:
    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
    SubscriptionProductType:
      type: string
      example: subscription_product
      enum:
        - subscription_product
    ProrationPolicyType:
      type: string
      example: subscription_proration_policy
      enum:
        - subscription_proration_policy
    SubscriptionDunningRuleType:
      type: string
      example: subscription_dunning_rule
      enum:
        - subscription_dunning_rule
    SubscriptionPlanType:
      type: string
      example: subscription_plan
      enum:
        - subscription_plan
    SubscriptionOfferingType:
      type: string
      example: subscription_offering
      enum:
        - subscription_offering
    SubscriptionOfferingProductType:
      type: string
      example: subscription_offering_product
      enum:
        - subscription_offering_product
    SubscriptionOfferingPlanType:
      type: string
      example: subscription_offering_plan
      enum:
        - subscription_offering_plan
    SubscriptionJobType:
      type: string
      example: subscription_job
      enum:
        - subscription_job
    SubscriptionImportType:
      type: string
      example: subscription_import
      enum:
        - subscription_import
    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
    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
    Relationships:
      description: Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.
      additionalProperties:
        $ref: '#/components/schemas/Relationship'
      example:
        plans:
          links:
            related: /offerings/:offering-id/plans
            self: /offerings/:offering-id
          data:
            type: offering-plan
            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: 00000000-0000-0000-0000-000000000000
    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 product 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 products that all have different prices. Rather than having to create separate plans for each product, you can specify the timeframe during which the product price is applicable and then create one plan that determines the billing frequency for those products.
      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 product 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 products that all have different prices. Rather than having to create separate plans for each product, you can specify the timeframe during which the product price is applicable and then create one plan that determines the billing frequency for those products.
      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
            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
    DisplayPrice:
      properties:
        without_tax:
          $ref: '#/components/schemas/PriceFormatting'
        with_tax:
          $ref: '#/components/schemas/PriceFormatting'
      example:
        without_tax:
          amount: 100
          currency: USD
          formatted: $1.00
        with_tax:
          amount: 110
          currency: USD
          formatted: $1.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.
    Product:
      required:
        - type
        - attributes
        - meta
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionProductType'
        attributes:
          $ref: '#/components/schemas/ProductResponseAttributes'
        meta:
          $ref: '#/components/schemas/ProductMeta'
    ProductMeta:
      readOnly: true
      required:
        - owner
        - timestamps
      properties:
        display_price:
          $ref: '#/components/schemas/DisplayPrice'
        owner:
          $ref: '#/components/schemas/OwnerMeta'
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    ProductCreate:
      required:
        - type
        - attributes
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionProductType'
        attributes:
          $ref: '#/components/schemas/ProductAttributes'
    ProductUpdate:
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionProductType'
        attributes:
          $ref: '#/components/schemas/ProductUpdateAttributes'
    ProductResponseAttributes:
      allOf:
        - $ref: '#/components/schemas/ProductAttributes'
        - $ref: '#/components/schemas/Timestamps'
    ProductAttributes:
      required:
        - name
      properties:
        external_ref:
          $ref: '#/components/schemas/ExternalRef'
        name:
          type: string
          description: The name of the product.
          minLength: 3
          maxLength: 1024
          example: Magazine
        description:
          type: string
          description: The product 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 product, if appropriate.
          maxLength: 1024
          example: MAGAZINE1
        main_image:
          type: string
          format: uri
          description: A URL from which an image or file for the product 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'
    ProductUpdateAttributes:
      properties:
        external_ref:
          $ref: '#/components/schemas/ExternalRefUpdate'
        name:
          type: string
          description: The name of the product.
          minLength: 3
          maxLength: 1024
          example: Magazine
        description:
          type: string
          description: The product 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 product, 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 product 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
      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'
    Plan:
      required:
        - type
        - attributes
        - meta
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionPlanType'
        attributes:
          $ref: '#/components/schemas/PlanResponseAttributes'
        meta:
          $ref: '#/components/schemas/PlanMeta'
    PlanMeta:
      readOnly: true
      required:
        - owner
        - timestamps
      properties:
        owner:
          $ref: '#/components/schemas/OwnerMeta'
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    PlanCreate:
      required:
        - type
        - attributes
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionPlanType'
        attributes:
          $ref: '#/components/schemas/PlanAttributes'
    PlanUpdate:
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionPlanType'
        attributes:
          $ref: '#/components/schemas/PlanUpdateAttributes'
    PlanResponseAttributes:
      allOf:
        - $ref: '#/components/schemas/PlanAttributes'
        - $ref: '#/components/schemas/Timestamps'
    PlanAttributes:
      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 plan.
          example: Monthly
          minLength: 3
          maxLength: 1024
        description:
          type: string
          description: The plan 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
        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 products within an offering. For example, you can configure a percentage that equates the cost of a plan to the total value of all products 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 products in an offering.
          example: 90
          minimum: 0
          maximum: 100
        fixed_price:
          $ref: '#/components/schemas/Price'
    PlanUpdateAttributes:
      properties:
        external_ref:
          $ref: '#/components/schemas/ExternalRefUpdate'
        name:
          type: string
          example: Monthly
          minLength: 3
          maxLength: 1024
        description:
          type: string
          description: The plan 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
        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 products within an offering. For example, you can configure a percentage that equates the cost of a plan to the total value of all products 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 products in an offering.
          example: 90
          minimum: 0
          maximum: 100
          nullable: true
        fixed_price:
          $ref: '#/components/schemas/NullablePrice'
    BuildOffering:
      required:
        - name
        - products
        - plans
      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.
        products:
          type: array
          description: Either references of existing products to be attached to the offering or product information to be created directly within the offering
          minItems: 1
          items:
            anyOf:
              - $ref: '#/components/schemas/ExternalRef'
              - $ref: '#/components/schemas/ProductAttributes'
              - $ref: '#/components/schemas/UUID'
        plans:
          type: array
          description: Either references of existing plans to be attached to the offering or plan information to be created directly within the offering
          minItems: 1
          items:
            anyOf:
              - $ref: '#/components/schemas/ExternalRef'
              - $ref: '#/components/schemas/PlanAttributes'
              - $ref: '#/components/schemas/UUID'
    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:
        products:
          type: array
          items:
            $ref: '#/components/schemas/OfferingProduct'
        plans:
          type: array
          items:
            $ref: '#/components/schemas/OfferingPlan'
    OfferingMeta:
      readOnly: true
      required:
        - owner
        - timestamps
        - external_product_refs
      properties:
        external_product_refs:
          type: array
          items:
            $ref: '#/components/schemas/OfferingProductExternalRefMeta'
        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/Relationships'
    OfferingProductUpdate:
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionOfferingProductType'
        attributes:
          $ref: '#/components/schemas/ProductUpdateAttributes'
    OfferingProduct:
      required:
        - type
        - attributes
        - meta
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionOfferingProductType'
        attributes:
          $ref: '#/components/schemas/ProductResponseAttributes'
        relationships:
          $ref: '#/components/schemas/Relationships'
        meta:
          $ref: '#/components/schemas/ProductMeta'
    OfferingPlanUpdate:
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionOfferingPlanType'
        attributes:
          $ref: '#/components/schemas/PlanUpdateAttributes'
    OfferingPlan:
      required:
        - type
        - attributes
        - meta
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionOfferingPlanType'
        attributes:
          $ref: '#/components/schemas/PlanResponseAttributes'
        relationships:
          $ref: '#/components/schemas/Relationships'
        meta:
          $ref: '#/components/schemas/OfferingPlanMeta'
    OfferingPlanMeta:
      readOnly: true
      required:
        - owner
        - timestamps
      properties:
        price:
          $ref: '#/components/schemas/Price'
        display_price:
          $ref: '#/components/schemas/DisplayPrice'
        active_plan:
          $ref: '#/components/schemas/ActivePlan'
        owner:
          $ref: '#/components/schemas/OwnerMeta'
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    OfferingPlanAttach:
      description: A list of plan IDs to attach to the offering. See [**List Plans**](/docs/api/subscriptions/list-plans).
      required:
        - plans
      properties:
        plans:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/UUID'
    OfferingProductAttach:
      description: A list of product IDs to attach to the offering. See [**List Products**](/docs/api/subscriptions/list-products).
      required:
        - products
      properties:
        products:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/UUID'
    OfferingProductReplace:
      description: A list of product IDs to replace on the offering. See [**List Products**](/docs/api/subscriptions/list-products).
      required:
        - products
      properties:
        products:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/UUID'
    OfferingUpdate:
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionOfferingType'
        attributes:
          $ref: '#/components/schemas/OfferingUpdateAttributes'
    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
        proration_policy_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'
        currency:
          $ref: '#/components/schemas/CurrencyIdentifier'
        payment_authority:
          $ref: '#/components/schemas/PaymentAuthority'
        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
        offering:
          $ref: '#/components/schemas/OfferingAttributes'
        products:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ProductAttributes'
        plans:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PlanAttributesAndSelectedMeta'
        selected_plan:
          $ref: '#/components/schemas/ExternalRef'
        meta:
          $ref: '#/components/schemas/SubscriptionMeta'
    PlanAttributesAndSelectedMeta:
      allOf:
        - $ref: '#/components/schemas/PlanAttributes'
        - $ref: '#/components/schemas/SelectedPlanMeta'
    SelectedPlanMeta:
      properties:
        meta:
          properties:
            selected:
              type: boolean
              example: true
              description: One plan 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'
    ManageSubscriptionProducts:
      type: object
      required:
        - type
        - products
      properties:
        type:
          type: string
          enum:
            - attach
            - detach
            - replace
          example: detach
          x-go-type: model.ManageProductsAction
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model
        products:
          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:
        plan_id:
          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:
        products:
          type: array
          items:
            $ref: '#/components/schemas/OfferingProduct'
        plans:
          type: array
          items:
            $ref: '#/components/schemas/OfferingPlan'
    SubscriptionMeta:
      readOnly: true
      required:
        - owner
        - timestamps
        - status
        - canceled
        - paused
        - closed
        - pending
        - suspended
        - invoice_after
        - manual_payments
      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'
        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'
    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.
              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
        - 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'
        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'
    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 product.

        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:
      oneOf:
        - $ref: '#/components/schemas/PaymentAuthorityStripe'
        - $ref: '#/components/schemas/PaymentAuthorityAuthorizeNet'
      discriminator:
        propertyName: type
        mapping:
          elastic_path_payments_stripe: '#/components/schemas/PaymentAuthorityStripe'
          authorize_net: '#/components/schemas/PaymentAuthorityAuthorizeNet'
    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'
    PaymentAuthorityStripe:
      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
    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_product:
              description: The total number of products uploaded.
              type: integer
              example: 50000
            subscription_plan:
              description: The total number of plans 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_product
            - subscription_plan
            - subscription_subscriber
            - subscription_offering
            - subscription
        imported:
          properties:
            subscription_product:
              description: The total number of products imported.
              type: integer
              example: 45090
            subscription_plan:
              description: The total number of plans imported.
              type: integer
              example: 45090
            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_product
            - subscription_plan
            - 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'
    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'
    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'
    JobType:
      type: string
      description: |
        The type of job. One of the following:
         - `billing_run` - a billing run job.
         - `payment_run` - a payment run job.
         - `tax_run` - a tax run job.
      enum:
        - billing-run
        - tax-run
        - payment-run
        - import
      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:
          $ref: '#/components/schemas/JobType'
        taxes:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/InvoiceTaxItems'
    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
    SubscriptionInvoice:
      required:
        - type
        - attributes
        - meta
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionInvoiceType'
        attributes:
          $ref: '#/components/schemas/SubscriptionInvoiceAttributes'
        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
      properties:
        owner:
          $ref: '#/components/schemas/OwnerMeta'
        subscription_id:
          $ref: '#/components/schemas/UUID'
        subscriber_id:
          $ref: '#/components/schemas/UUID'
        price:
          $ref: '#/components/schemas/SingleCurrencyPrice'
        timestamps:
          $ref: '#/components/schemas/InvoiceTimestamps'
        proration_events:
          type: array
          items:
            $ref: '#/components/schemas/ProrationEvent'
    ProrationEvent:
      required:
        - proration_policy_id
        - billing_cost_before_proration
        - refunded_amount_for_unused_plan
        - new_plan_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_plan:
          type: integer
          format: int64
          description: The value as a whole number of the currency's smallest subdivision.
          example: 100
        new_plan_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'
    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
        - 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'
        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'
        product_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.
      x-go-type: uuid.UUID
      x-go-type-import:
        name: uuid
        path: github.com/google/uuid
      example: 00000000-0000-0000-0000-000000000000
    OwnerMeta:
      readOnly: true
      type: string
      format: string
      description: The owner of a resource, either `store` or `organization`.
      example: store
    OfferingProductExternalRefMeta:
      readOnly: true
      type: string
      format: string
      description: The offerings product 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:
        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
    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
    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/JobType'
    ScheduleUpdate:
      required:
        - id
        - type
        - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionScheduleType'
        attributes:
          $ref: '#/components/schemas/ScheduleUpdateAttributes'