diff --git a/.gitignore b/.gitignore index f0c984e..d30aef9 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ epcc epcc-test .envrc build/ + +*.env \ No newline at end of file diff --git a/external/openapi/specs/download_specs.sh b/external/openapi/specs/download_specs.sh index 6cac4a2..019fbf6 100755 --- a/external/openapi/specs/download_specs.sh +++ b/external/openapi/specs/download_specs.sh @@ -42,6 +42,7 @@ download_spec "https://developer.elasticpath.com/assets/openapispecs/promotions- download_spec "https://developer.elasticpath.com/assets/openapispecs/single-sign-on/OpenAPISpec.yaml" "single-sign-on.yaml" download_spec "https://developer.elasticpath.com/assets/openapispecs/addresses/AccountAddresses.OpenAPISpec.yaml" "account-addresses.yaml" download_spec "https://developer.elasticpath.com/assets/openapispecs/settings/OpenAPISpec.yaml" "settings.yaml" +download_spec "https://developer.elasticpath.com/assets/openapispecs/subscriptions/public_openapi.yaml" "subscriptions.yaml" # Integrations doesn't have matching URLs. diff --git a/external/openapi/specs/settings.yaml b/external/openapi/specs/settings.yaml new file mode 100644 index 0000000..7fd867e --- /dev/null +++ b/external/openapi/specs/settings.yaml @@ -0,0 +1,480 @@ +openapi: 3.1.0 +info: + version: 25.1204.6912572 + x-version-timestamp: 2025-12-04T16:22:22Z + title: Settings Introduction + description: | + The Settings API allow you to configure global settings for your project. You can define: + + - [page length when paginating results](/docs/api/settings/settings-introduction#page-length) + - [the calculation method you want to use for cart and order totals](/docs/api/settings/settings-introduction#calculation-method) + - [mandatory address fields](/docs/api/settings/settings-introduction#address-mandatory-fields) + - [shopper address limit](/docs/api/settings/settings-introduction#shopper-address-limit) + - [readonly store settings for internal stores](/docs/api/settings/settings-introduction#readonly-settings) + + ### Page Length + + This defines the number of results per page when paginating results (max: 100). + + | Name | Type | Default | Max | + |--------------|-----------|--------- |-----| + | `page_length` | `integer` | 25 | 100 | + + For more information on pagination including a list of which resources support pagination, see [Pagination](/guides/Getting-Started/pagination). + + ### Calculation Method + + This option defines the method used to calculate cart and order totals. Currently there are two methods: `simple` and `line`. + + The `simple` method is our previous method for calculating cart and order totals which focuses on the total value of the cart. This should only be used in the case where Composable Commerce is not used for tax calculations. The `line` method treats each line item individually resulting in more accurate figures after taxes and promotions are applied. + + | Name | Type | Value | + |--------------|-----------|-------| + | `calculation_method` | `string` | `line` | + | `calculation_method` | `string` | `simple` | + + :::note + + - For stores created since February 2020, `line` is the default calculation method. Stores created before February 2020 use `simple` as their calculation method. + - Line-item discount promotions, such as item percent discount and item fixed discount, are only supported by the line calculation method. For more information, see [Promotions Standard](/docs/api/promotions/promotions-standard-introduction). + + ::: + + ### Address Mandatory Fields + + You can create an address to associate with an account in your storefront. This defines the address fields that you can use when creating an address in Commerce Manager. For more information, see [Addresses](/docs/api/addresses/addresses-introduction). + + Address fields can be required or optional. You can choose which optional address fields to use in your address, depending on your requirements. To change which fields are mandatory for creating an address, see [Update Settings](/docs/api/settings/put-v-2-settings). Changing the mandatory fields does not impact the addresses of customers made before the change. + + The following table describes the address fields, their type and whether they are required by default. + + | Name | Type | Required | + | :--- | :--- |:---------| + | `type` |`string` | Default | + | `first_name` |`string` | Default | + | `last_name` |`string` | Default | + | `name` |`string` | Optional | + | `phone_number` |`string` | Optional | + | `instructions` |`string` | Optional | + | `company_name` |`string` | Optional | + | `line_1` |`string` | Default | + | `line_2` |`string` | Optional | + | `city` |`string` | Optional | + | `county` |`string` | Default | + | `region` |`string` | Optional | + | `postcode` |`string` | Default | + | `country` |`string` | Default | + + ### Shopper Address Limit + + This defines the maximum number of addresses a shopper can create per resource (account). This helps prevent abuse and maintains database performance. + + | Name | Type | Default | Min | Max | + |--------------|-----------|---------|-----|-------| + | `shopper_address_limit` | `integer` | 25 | 1 | 25000 | + + :::note + Only values up to 500 can be set by callers. Please [contact Support](https://support.elasticpath.com/hc/en-us#composable_commerce) if you require a higher limit. + ::: + + ### Readonly Settings + + For internal store configurations, read-only settings are used and updating these settings fails without returning any error. + + :::note + + - Refer to the [Performance](/guides/Getting-Started/pagination#performance) section in the Pagination documentation, which outlines patterns for retrieving all documents without using a higher page offset limit. + - To change any predefined configuration, contact [Elastic Path support team](https://support.elasticpath.com/hc/en-us). + + ::: + + + | Name | Type | Default | + |:------------------------|:----------|:-----------------------------------------------------| + | `currency_limit` | `integer` | `10` | + | `field_limit` | `integer` | `100` | + | `integration_limit` | `integer` | `100` | + | `event_limit` | `integer` | `5` | + | `filter_limit` | `integer` | `10` | + | `tax_item_limit` | `integer` | `5` | + | `promotions_limit` | `integer` | `1000` | + | `promotion_codes_limit` | `integer` | `1000` | + | `page_offset_limit` | `integer` | `10000` | + + contact: + name: Elastic Path + url: 'https://www.elasticpath.com' + email: support@elasticpath.com + license: + url: 'https://elasticpath.dev' + name: MIT +servers: + - url: 'https://useast.api.elasticpath.com' + description: US East + - url: 'https://euwest.api.elasticpath.com' + description: EU West +security: + - BearerToken: [] +tags: + - name: Settings + description: The Settings API allow you to configure global settings for your project. +paths: + /v2/settings: + get: + tags: + - Settings + summary: Get Project Settings + description: |- + You can get all of the project settings via one API call using a `client_credential` token. The response is in object format as shown in the following example. + + :::note + + The default `calculation_method` is `line`. + + ::: + operationId: get-v2-settings + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SettingsResponse' + '401': + $ref: '#/components/responses/UnauthorizedError' + default: + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Settings + summary: Update Project Settings + description: |- + You can use the Settings endpoint to update your project settings at any time. These global settings take immediate effect. + operationId: put-v2-settings + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Settings' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SettingsResponse' + '400': + $ref: '#/components/responses/BadRequestError' + default: + $ref: '#/components/responses/InternalServerError' + delete: + tags: + - Settings + summary: Delete Project Settings + description: |- + Deletes a store setting. Organization settings cannot be deleted. + operationId: delete-v2-settings + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/UnauthorizedError' + default: + $ref: '#/components/responses/InternalServerError' + /v2/settings/cart: + get: + tags: + - Settings + summary: Get Cart Settings + description: |- + Retrieves cart settings + operationId: get-v2-settings-cart + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SettingsCart' + '401': + $ref: '#/components/responses/UnauthorizedError' + default: + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Settings + summary: Update Cart Settings + description: |- + You can modify the cart expiry settings to set it to any number of days up to 365. Any existing carts default to the expiry of 7 days. To update cart settings in Commerce Manager, see [Updating Cart setting](/docs/commerce-manager/settings/general-settings#updating-cart-settings). + + With update cart settings endpoint, you can: + + - Enable or disable custom discounts by setting the `custom_discounts_enabled` field to `true`. This allows you to activate your custom discounts from external services. By default, this setting is determined by the cart settings configured for the store. + - Enable or disable the use of rule promotions within the cart. You can apply this setting either at the store level using the update cart setting endpoint or individually to a specific cart using the [update a cart](/docs/api/carts/update-a-cart) endpoint. + - Enable or disable deferred inventory checks by setting `defer_inventory_check` to `true`. When set, stock levels are not verified for products in a cart until checkout. + - Control whether admins can see all carts or only shopper-associated carts by setting `show_all_carts` to `true` or `false`. + + :::note + + You cannot use both custom discounts and rule promotions at the same time. + + ::: + + ### Errors + + The following error is received if you enable a cart to use both custom discounts and rule promotions: + + ```json + { + "status": 422, + "title": "Cannot use both discounts together", + "detail": "Only one discount setting can be set to true at a time." + } + ``` + operationId: put-v2-settings-cart + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SettingsCart' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SettingsCart' + '400': + $ref: '#/components/responses/BadRequestError' + default: + $ref: '#/components/responses/InternalServerError' +components: + securitySchemes: + BearerToken: + type: http + scheme: bearer + schemas: + Settings: + type: object + properties: + type: + type: string + description: Describes the type of request payload you’re sending. Set this value to `settings`. + example: settings + page_length: + type: integer + description: " Indicates the number of results per page (max: `100`)." + example: 25 + list_child_products: + type: boolean + description: Displays child products or not in product listings. + example: false + additional_languages: + description: Represents an array of alpha2 codes for supported languages. + type: array + items: + type: string + example: ["es", "fr", "de"] + calculation_method: + type: string + description: Displays the method used to calculate card and order totals. + example: line + enum: + - line + - simple + address_mandatory_fields: + type: array + description: Indicates an array of fields that are required for creating an [address](/docs/api/addresses/account-addresses). + items: + type: string + example: ["first_name", "last_name", "line_1", "city", "region", "postcode", "country", "instructions"] + shopper_address_limit: + type: integer + description: The maximum number of addresses a shopper can have per resource. API clients can only set values up to 500, for a higher limit please contact support. + example: 25 + minimum: 1 + maximum: 25000 + required: + - type + SettingsData: + properties: + data: + allOf: + - $ref: '#/components/schemas/Settings' + - type: object + properties: + currency_limit: + description: The currency limit. + type: integer + example: 10 + field_limit: + description: The field limit. + type: integer + example: 100 + integration_limit: + description: The integration limit. + type: integer + example: 100 + event_limit: + description: The event limit. + type: integer + example: 5 + filter_limit: + description: The filter limit. + type: integer + example: 10 + tax_item_limit: + description: The tax item limit. + type: integer + example: 5 + promotions_limit: + description: The promotions limit. + type: integer + example: 1000 + promotion_codes_limit: + description: The promotion codes limit. + type: integer + example: 1000 + page_offset_limit: + description: The page offset limit. + type: integer + example: 10000 + SettingsResponse: + allOf: + - $ref: '#/components/schemas/SettingsData' + - type: object + properties: + meta: + type: object + properties: + owner: + type: string + example: store + SettingsCart: + type: object + properties: + data: + type: object + properties: + type: + type: string + description: Describes the type of request payload you’re sending. Set this value to `settings`. + example: settings + cart_expiry_days: + type: integer + description: Indicates the number of days before a cart expires. + example: 25 + discounts: + type: object + properties: + custom_discounts_enabled: + description: When `true`, custom discounts are enabled. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected. + type: boolean + example: false + use_rule_promotions: + description: When set to `true`, this parameter allows the cart to use rule promotions. + type: boolean + example: false + inventories: + type: object + properties: + defer_inventory_check: + description: When `true`, inventory checks are not performed when adding products to a cart but still occur on checkout as normal. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected. + type: boolean + example: false + show_all_carts: + description: | + When `true`, admins (users with admin scope) can retrieve all carts in the store via `GET /v2/carts`, regardless of customer or account associations. When `false`, admins can only see carts that are registered (associated with customers or accounts). + + For new stores, this defaults to `true`. For existing stores created before this feature was introduced, this defaults to `false` to maintain backward compatibility. + type: boolean + example: true + required: + - type + Error: + required: + - status + - title + properties: + title: + type: string + description: A brief summary of the error. + examples: + - "Bad Request" + status: + type: string + format: string + description: The HTTP response code of the error. + examples: + - "400" + detail: + type: string + description: Optional additional detail about the error. + examples: + - "The field 'name' is required" + ErrorResponse: + required: + - errors + properties: + errors: + type: array + items: + $ref: '#/components/schemas/Error' + responses: + InternalServerError: + description: Internal server error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internal-server-error: + summary: Internal server error + # language=JSON + value: | + { + "errors": [ + { + "title": "Internal Server Error", + "status": "500", + "detail": "there was a problem processing your request" + } + ] + } + BadRequestError: + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + bad-request-error: + # language=JSON + value: | + { + "errors": [ + { + "title": "enum", + "source": "data.type", + "detail": "data.type must be one of the following: \"settings\"" + } + ] + } + UnauthorizedError: + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + unauthorized-error: + # language=JSON + value: | + { + "errors": [ + { + "title": "Unauthorized", + "status": "401" + } + ] + } diff --git a/external/openapi/specs/subscriptions.yaml b/external/openapi/specs/subscriptions.yaml new file mode 100644 index 0000000..8dfc292 --- /dev/null +++ b/external/openapi/specs/subscriptions.yaml @@ -0,0 +1,6317 @@ +openapi: 3.0.0 +info: + version: 25.1231.7008930 + x-version-timestamp: 2025-12-31T11:09:20Z + title: Subscriptions Introduction + description: | + Elastic Path Subscriptions allows you to offer your customers subscriptions and recurring billing for your plans and services. Elastic Path Subscriptions gives you the flexibility to pause, update, or reactivate your subscription offerings, change subscription cycles and apply discounts. + + You can create subscriptions using the Elastic Path Subscriptions API or Commerce Manager See [Subscriptions](/docs/commerce-manager/subscriptions/overview). + + Scenarios include: + + - repeat products that your customers purchase on a recurring basis. + - membership subscriptions where your customers pay a recurring fee to become members of a particular service, program or organization. + - subscribe and save that allows your customers to subscribe to regular deliveries of products they use frequently, for example, household essentials, or personal care items. + + ### How Subscriptions Work + + Elastic Path Subscriptions enables you to manage your subscriptions plans and pricing options, using offerings. Offerings can contain any combination of plans and pricing options. + + Here's how a typical subscription works: + + 1. Create your offerings. Offerings are the plan and pricing options that a customer can choose. An offering can consist of many combinations of a plan or pricing options, depending on the plans and services you offer. See [**Offerings**](/docs/api/subscriptions/offerings). + 2. When a [**customer**](/docs/api/subscriptions/subscribers) chooses a pricing option, a subscription is created. See [**Subscriptions**](/docs/api/subscriptions/subscriptions). + 3. Elastic Path Subscriptions manages the billing and recurring payments associated with the subscription. See [**Invoicing and Payments**](/docs/api/subscriptions/invoices). + + ### Subscriber Management + + Elastic Path Subscriptions enables you to create customer accounts that you can use to manage their subscription details, including payment methods and billing information. See [**Subscribers**](/docs/api/subscriptions/subscribers). + + ### Invoicing & Payments + + Elastic Path Subscriptions enables you to manage the billing and recurring payments associated with your customers subscriptions. Elastic Path Subscriptions provides seamless integration with Elastic Path Payments powered by Stripe. See [**Invoicing and Payments**](/docs/api/subscriptions/invoices). +servers: + - url: https://euwest.api.elasticpath.com + description: EU west cluster + - url: https://useast.api.elasticpath.com + description: US east cluster +security: + - BearerToken: [] +tags: + - name: Features + description: | + A feature indicates some benefit that is received as a result of having an active subscription. This translates to tags being applied to the subscriber's account allowing access to some resource to be controlled. + + There are three types of feature - `access`, `promotion`, and `usage`. + + The `access` feature is designed to simply give access to some resource, for example a streaming service. If its tag is present on the subscriber's account then access to that resource should be provided. + + The `promotion` feature coupled with the [promotions service](/docs/promotions-builder/overview) allows subscribers to get access to a specific promotion. This is achieved using a tag which is used as a constraint on the promotion. A promotion feature may have multiple promotions associated with it, but just one must be selected when configuring the feature for an offering's plan. + + The `usage` feature is designed to measure some sort of usage of a resource. This currently relies on [commerce extensions](/docs/api/commerce-extensions/commerce-extensions-introduction) to manage usage. + + Once defined a feature may be attached to an offering, making it available for use with any of that offering's plans. Once attached it must be configured for each of the offering's plans it is applicable to. For the `promotion` feature this involves specifying which of that feature's tags, and hence which promotion, should be applied when subscribed to that offering. Similarly, for the `promotion` feature the default value for the usage metric must be supplied. + - name: Offerings + description: | + An offering is a combination of plans and pricing options; plans are combined with one or more pricing options to form an offering. + + For example, your company provides online + streaming of movies, web-series, and music. Your customers can purchase these services through either a weekly or monthly pricing option. + + Offering plans can be either: + + - a subscription plan, created within an offering. + - a Product Experience Manager product, see [**Create a product**](/docs/api/pxm/products/create-product) + + ### Offering Examples + + Offerings can have any combination of plans and pricing options. The pricing of an offering is determined by the pricing you have configured for your plans and pricing options. + + | Example | Plan | Pricing options | Offering | + | --- | --- | --- | --- | + | Single plan and pricing option | One plan with a plan price of $50 | A monthly pricing option with a 5% discount | An offering with a monthly pricing option for $47.50 a month | + | Single plan with multiple pricing options | One plan with a plan price of $50 | | An offering with two pricing options: | + | Multiple plans and pricing option | Two plans: | A monthly pricing option with a 5% discount. | An offering with a monthly pricing option for $118.75 a month. | + | Multiple plans with multiple pricing options | Two plans: | | An offering with two pricing options: | + + ### Building an Offering + + When you are building an offering: + + - you can create new pricing options and plans. + - you can modify existing plans and pricing options. For example, you can modify the plan price or any attributes of a pricing option included in the offering. + + Here's how you build an offering: + + When [**building your offerings**](/docs/api/subscriptions/build-offering) you must supply the plans and pricing options that a customer can choose. An offering can consist of many combinations of a plan or pricing options, depending on the plans and services you offer. + + Plans can either be subscription plans or Product Experience Manager products. To create a Product Experience Manager product, see [**Create a product**](/docs/api/pxm/products/create-product) + + Pricing options are the rules that govern your subscription, for example, any discount. + - You can combine and reuse pricing options for as many plans as you want, making it quick and easy to create your subscription offerings. + - An offering must have at least one pricing option. + - Each plan must have the appropriate pricing option associated with it + + When a [**customer**](/docs/api/subscriptions/subscribers) chooses a plan and pricing option, a subscription is created. See [**Subscriptions**](/docs/api/subscriptions/subscriptions). Elastic Path Subscriptions manages the billing and recurring payments associated with the subscription. See [**Invoicing and Billing**](/docs/api/subscriptions/jobs). + + ### Editing Offerings + + After saving an offering, you can, at any time: + + - update an offering's details, for example, name or description. See [**Update an Offering**](/docs/api/subscriptions/update-offering). + - update an existing plan in an offering. See [**Update a plan in an offering**](/docs/api/subscriptions/update-offering-plan) + - add a new plan in an offering. See [**Create a plan inside an offering**](/docs/api/subscriptions/create-offering-plan) + - remove plans. See [**Remove a plan from an offering**](/docs/api/subscriptions/delete-offering-plan). + - update an existing pricing option in an offering. See [**Update a pricing option in an offering**](/docs/api/subscriptions/update-offering-pricing-option) + - add a new pricing option to an offering. See [**Create a pricing option inside an offering**](/docs/api/subscriptions/create-offering-pricing-option). + - remove pricing options. See [**Removing a pricing option from an offering**](/docs/api/subscriptions/delete-offering-plan). + + Any modifications that you make to offerings, and plans or pricing options in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. + - name: Subscriptions + description: | + Elastic Path Subscriptions enables you to manage your subscriptions plans and pricing options, using offerings. Offerings can contain any combination of pricing options and a plan. When a customer chooses a pricing option, a subscription is created. + + ### Managing the Subscription Lifecycle + + The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. + + A subscription can have the following states: + + - `pending` + - `canceled` + - `paused` + - `resumed` + + #### Creating a pending subscription + + A subscription can be created in a `pending` state. This is useful for several reasons. + + - If there are subscriptions that require user setup or onboarding, for example, installing software or setting up preferences. This helps reduce shopper frustration during the onboarding process, as the shopper is not paying for a service that they cannot use yet. + - When offering a free trial or promotion, keeping the subscription in a pending state until the trial or promotion starts or ends allows you to manage transitions more smoothly. + - Before a subscription becomes active, you may need to verify the payment method or authorize the first payment. Keeping the subscription in a pending state allows time to complete these steps without activating the subscription. + + For a subscription with a `pending` state, you can also configure a `go_live_after` date. The subscription starts from the `go_live_after` date. This is useful as it ensures both the subscription provider and subscriber are clear about when a subscription officially begins. Once the `go_live_after` date is passed, the subscription becomes `active`, initiating the billing and payment runs. If a subscription is activated this way, you can see this in the `timestamp` meta. + + You can configure a `go_live_after` date to be a past date. This is useful, for example, for backdating a subscription or managing a delay in activating a subscription. Setting the `go_live_after` date in the past ensures the subscriptions timeline correctly aligns with the agreed-upon service start date. + + :::caution + + Although, billing runs generate one invoice per subscription, if a `go_live_date` is set far in the past, multiple invoices could be generated over the course of several billing runs, which could be frustrating and confusing to your subscribers. + + ::: + + See [create a subscription](/docs/api/subscriptions/create-subscription). + + #### Cancelling or pausing and resuming subscriptions + + A subscriber can decide to cancel or pause and/or resume a subscription. The following example describes pausing or canceling and resuming a subscription. + + 1. The subscriber pauses or cancels the subscription. + - The subscription status is `active`. + - either `paused` or `cancelled` is set to `true`. + - either the `paused_at` or `cancelled_at` timestamp is populated with the date and time the subscription is paused or cancelled. + - for cancelled subscriptions, `end_date` indicates when the subscription will expire and end. + 2. When the next billing run is due, the billing run checks the subscription state. If the subscription state is paused or cancelled then no invoice is created and the subscription status is updated to `inactive`. + 3. Subsequent billing runs skip that subscription completely as the subscription status is `inactive`. + 4. If the subscriber resumes the subscription: + - either `paused` or `cancelled` is set to `false`. + - the `resumed_at` timestamp is populated with the date and time the subscription is resumed. + 5. When the next billing run is due, the billing run checks the subscription state. If the `paused` or `cancelled` is set to `false` then the billing run creates an invoice. + 6. The payment run processes the invoice. Once the payment succeeds then the payment run updates the status of the subscription to `active`. + + ### Orders + + When a customer chooses a subscription, they need to add the subscription to a cart, checkout the cart and then pay for the order. + + 1. When a customer adds a subscription to cart, this is handled using the `Add subscription to cart` endpoint. + 2. Once a subscription has been added to a cart, the [**Checkout API**](/docs/api/carts/checkout-api) converts the cart to an order. + 3. Once the order is created, payment needs to be taken. This is handled by Elastic Path Payments Powered by Stripe. See [**Payments**](/docs/api/subscriptions/invoices#payments). + - name: Jobs + description: | + Jobs are an asynchronous process that can be triggered manually or scheduled. + + There are three types of job: + + - a billing run. Subscriptions generates an [**invoice**](/docs/api/subscriptions/invoices) when a billing run occurs. Billing runs generate invoices for the remaining billing cycles for each subscription. The invoice dates come from your pricing options. Billing runs are independent of payment runs. + - a tax run. Invoices where `tax_required` is `true` will not have payment taken until a tax run has added the required tax to the invoice. + - a payment run. The payment run identifies invoices that are outstanding and attempts to take payment for them. If the payment succeeds the the invoice is no longer outstanding. If the payment fails for any reason, then the invoice remains outstanding and is picked up by the next payment run to retry the payment. + + By scheduling billing and payment runs, you automate the process, reducing manual intervention and ensuring the jobs are run in a timely manner. See [**Schedules**](/docs/api/subscriptions/schedules). + + ### Characteristics of Billing, Tax & Payments Jobs + + Billing and payment jobs have the following characteristics. + + - Jobs are asynchronous. + - Jobs have a different status, depending on where a job is in its lifecycle. + - Jobs report any errors to help you understand the reason for any failed jobs. + - Only one billing run and payment run is allowed per store at a time. Although billing and payments are constantly generated, the jobs are queued. Subscriptions looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. + + ### Billing, Tax & Payments Jobs Lifecycle + + A job can have the following status types: + + - PENDING - Subscriptions has received the request but is currently busy processing other requests. + - STARTED - Subscriptions has started processing the job. + - SUCCESS - The job has successfully completed. + - FAILED - The job has failed. + + ### Billing, Tax & Payment Reports + + You can track your Subscriptions billing, payment and tax operations using reports. There are three types of report: + + - `BillingRunReport` - This report provides invoice summaries such as invoices ready for payment, invoices that require tax, and invoice failures. + - `TaxRunReport` - This report provides invoice summaries such as invoices to which tax was successfully or unsuccessfully added. + - `PaymentRunReport` - This report provides invoice summaries such as invoices for which payment was attempted, failed payment attempts and totals collected by a payment run. + + See [Get a job](/docs/api/subscriptions/get-job) and [List jobs](/docs/api/subscriptions/list-jobs). + - name: Imports + description: | + You can import subscription features, subscribers, offerings and subscriptions using Subscriptions Import. This is useful if you want to import subscriptions from an external system into Elastic Path Subscriptions. + + The API uses a [**JSONL**](https://jsonlines.org/) file. Here is an [**example of a JSONL file**](/assets/subscriptions_import.jsonl). + + When you send an import request, an import job is created. Jobs are processed one at a time. You can continue to send import requests, but those jobs are queued. In other words, Subscriptions looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. Use [List import jobs](/docs/api/subscriptions/list-import-jobs) to see a list of all import jobs. + + A file can include up to 50,000 objects. If you have more than 50,000 objects, then you must create a separate file, and import each file, one at a time. + + ### Characteristics of Subscriptions Import + + The Subscriptions Import API has the following characteristics: + + - The Subscriptions Import API reads the entire file and then creates the subscription objects. This means the subscription objects can be in any order in the file. + + - Subscriptions imports are asynchronous and are processed one at a time. You can continue to send import requests, but these are queued. + + - The API works on a "best endeavours" approach. In other words, the API does its best to create the subscription objects based on the file that you provide. + + ### Subscriptions Import File + + The following table describes the subscriptions objects, and their attributes, that the import file can include. + + | Object | Attributes | + | --- | --- | + | A subscriber object | The attributes you specify for a subscriber object are the attributes you specify when [creating a subscriber](/docs/api/subscriptions/create-subscriber). | + | An offering object | The attributes you specify for an offering object are the attributes you specify when [building an offering](/docs/api/subscriptions/build-offering). | + - name: Schedules + description: | + You can schedule your billing, tax, and payment runs. By scheduling billing, tax, and payment runs, you automate the process, reducing manual intervention and ensuring the jobs are run in a timely manner. You can define a schedule in the format (`* * * * *`) which is a set of five fields in a line, indicating when a job should be executed. For example, you can define a schedule so that your job runs multiple times a day, or runs on specific days and months. + + Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339). + + ### Unrestricted fields + + Setting a field to an asterisk (`*`) is sometimes referred to as leaving a field unrestricted because it is not restricted to a specific value. + + You can use the asterisk (`*`) to indicate the range of all values for the field. When you use the asterisk, the first value in the range is: 0 for the minute, hour, and day of the week (Sunday) fields, and 1 for day of the month and the month fields. + + ### Configuring fields + + The time fields have the following format and possible values and must be specified in the following order: + + | Field | Format | Description | + | --- | --- | -----| + | Minute | 0-59 | Indicates how far past the top of the hour your job runs, in minutes. For example if a minute is set to 0, then the job runs at the top of the hour because it is 0 minutes after the hour. This means if the hour is 8.00 AM, the job runs at 8.00 AM. | + | Hour | 0-23 | Indicates how far past midnight your job runs, in hours. This is rounded down to the nearest hours. This is because minutes are indicated by the minute field. | + | Day of the month | 0-31 | Indicates the calendar date of the month. For example, 1 for the first day of the month. | + | Month | 1-12 or JAN to DEC | Indicates the month. Specify the month number or the first three letters of the month name in uppercase. For example, 1 or JAN for January. | + | Day of the week | 0-6 (or SUN to SAT, or 7 for Sunday) | Indicates the day of the week. Monday is 1, Tuesday is 2, and so on. Either 0 or 7 indicates Sunday. Alternatively, specify the day of the week using the first three letters of the weekday name in uppercase. For example SUN for Sunday. If you use this field with the day of the month field, then this field is evaluated as an inclusive OR. For example, if the day of the month is set to 1 and the day of the week is set to SAT, the job runs on the first day of the month and on every Saturday of the month, even if the first day of the month is not a Saturday. If the day of the week is marked by an asterisk (*) then the field is marked as unrestricted. This means the job only runs on the first day of the month. | + + ### Matching all values + + To match all values for a field, set the field to an asterisk (`*`). When a field is set to an asterisk, the field matches all valid values for that field whenever the other field conditions are satisfied. + + Here are some examples. + + - `* 0 1 1 1`: the job runs every minute of the midnight hour on January 1st and Mondays. + - `* * * * *`: the job runs every minute (of every hour, of every day of the month, of every month, every day of the week, because each of these is unrestricted). + + ### Matching a range + + To match a range of values, specify your start and stop values, separated by a hyphen (`-`). Do not include spaces in the range. Ranges are inclusive. The first number must be less than the second number. If you are using abbreviated names for the month or weekday (for example, JAN instead of 1 for the first month of the year), the first value must come earlier in the month or week than the second value. + + The following equivalent examples run at midnight on Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays (for all months): + + - `0 0 * * 1-5` + - `0 0 * * MON-FRI` + + ### Matching a list + + Lists can contain any valid value for the field, including ranges. Specify your values, separated by a comma (,). Do not include spaces in the list. + + Examples: + + - `0 0,12 * * *`: the job runs at midnight and noon. + - `0-5,30-35 * * * *`: the job runs in each of the first five minutes of every half hour (at the top of the hour and at half past the hour). + + ### Skipping values in a range + + You can skip values in a range by specifying a rate at which to step through the range. To do this, specify the range, followed by the forward slash (`/`) and the rate at which you want to skip through the range. + + The step value cannot be larger than the largest possible value for the field. The default step is 1, so the step function `/1` is the same as not using a step function at all. + + Example ranges that use step functions: + + - `*/2`: this is a valid step function for any field. + - For the minute field, it matches 0, 2, 4, ... , 58. + - For the hour, it matches 0, 2, 4, ... , 22. + - For the day of the month, it matches 1, 3, 5, ... , 31 (for a month with 31 days). + - For the month, it matches 1, 3, 5, ... , 11. + - For the day of the week, it matches 0, 2, 4, 6. + + - `0-12/2`: this is a valid step function for the minute and hour fields. It matches 0, 2, 4, ... , 12. + + Example schedules using step functions: + + - `*/2 * * * *`: the job runs every two minutes. + - `0 0-12/2 * * *`: the job runs every two hours, on the hour. The first run is at midnight. The last run is at noon. + - name: Subscribers + description: | + A subscriber is someone who subscribes to your plan or service. + - name: Invoices + description: | + Invoices represent the amount a customer owes for a subscription. Elastic Path Subscriptions generates an invoice for every period in a subscription billing cycle. Invoices provide: + + - an itemized list of goods and services provided by a subscription. + - the cost of a subscription. + - if applicable, any taxes. + + The invoice lifecycle is described below. + + 1. When a subscription is created, an invoice for the first billing period is created. When a subscription is created as part of an order, the payment for the order covers the first billing period. + 2. Subscription invoices are created by [**billing runs**](/docs/api/subscriptions/jobs). The billing run identifies subscriptions that require a new invoice for their next billing period and creates them. At this point, invoices are marked as outstanding. + 3. Invoices where `tax_required` is `true` will not have payment taken until a tax run has added the required tax to the invoice. + 3. The [**payment run**](/docs/api/subscriptions/jobs) identifies invoices that are still outstanding and attempts to take payment for them. If the payment succeeds the the invoice is no longer outstanding. If the payment fails for any reason, then the invoice remains outstanding and is picked up by the next payment run to retry the payment. If an invoice has a failed payment, payment is only retried if the fixed interval has passed from the last payment attempt as defined in Settings. + + ### Payment Retries + + It is important to limit the number of times Subscriptions retries a failed payment request for many reasons, including: frequent payment retries can indicate fraudulent activities; multiple failed payment attempts can lead to customers accounts being locked out or flagged for suspicious activity resulting in poor customer experience; and excessive retries places an unnecessary load on your payment processing system. + + In Subscriptions, by default, the number of payment retries is 10. You can set this to a limit between 0 - 20, depending on your requirements. Each payment retry is made as a payment run. + + Once the number of payment retries reaches the limit, the payment retries stop, resulting in status of the invoice being unpaid. See [Invoices](#invoices). + + When configuring payment retries, you have the following options. + + | Attribute | Required | Description | + | --- | --- | --- | + | `payment_retry_type` | Optional | One of the following options: | + | `payment_retry_interval` | Optional | Represents the retry interval. For example, if `payment_retry_unit` is `week` and `payment_retry_interval` is `1` then, the payment retry interval is 1 week. | + | `payment_retry_multiplier` | Optional | Use when `payment_retry_type` is `tiered` and represents the factor by which the time duration increases after each retry. | + | `payment_retry_unit` | Optional | Represents the unit of time, either `day` or `week`. | + + ### Rounding + + Subscriptions always rounds down to the penny. + + ### Tax + + Subscriptions allows you to apply any number of tax rates to your invoices and subscriptions. When applying a tax rate, you must specify: + + - a name that appears on your customer's invoice that describes the specific type of tax. + - the tax rate which is the percentage of the subscription amount that is required to be paid as tax. + + In addition, you can optionally specify the jurisdiction which is the geographic area or political entity that has authority to levey and collect taxes. + + You can apply more than one tax rate for all items in an invoice. You cannot apply a tax rate per line item. + + ### Payments + + When your customers add a subscription to a cart and the cart is checked out, an unpaid order is returned. You can process the payment for the order though a payment gateway. You can do this using: + + - Elastic Path Payments Powered by Stripe. The Elastic Path Payments Powered by Stripe gateway interacts with Stripe to allow your subscribers to pay for their subscriptions. + - Authorize.Net. + + #### Using Elastic Path Payments Powered by Stripe + + To use Elastic Path Payments Powered by Stripe gateway, contact the [**Customer Success Team**](mailto:customersuccess@elasticpath.com). + + Create your Stripe account in [**Stripe Dashboard**](https://dashboard.stripe.com/login) and complete an onboarding form to make payments using the gateway. For more information, see [**Onboarding**](/docs/payments/onboarding). + + Once you have signed up for Elastic Path Payments Powered by Stripe, you must configure the payment gateway so that your shoppers can make payments. See [**Configure Elastic Path Payments Powered by Stripe**](/docs/payments/onboarding). + + #### Using Authorize.Net + + To use Authorize.Net, you must have: + + - an active merchant account with Authorize.Net + - obtained API credentials. These include an **API Login ID** and a **Transaction Key**. + - Enabled Authorize.Net in Commerce Manager. See [Enabling Authorize.net](/docs/commerce-manager/payments/configure-other-payment-gateways#enabling-authorizenet). + + #### Payment Requests + + Subscriptions only supports the `purchase` payment mechanism. The gateway attempts to charge the customer immediately, and the result of the attempt is returned. If a payment fails, the invoice is kept as outstanding and the payment information, with the reason for the failure is attached to the invoice. A new payment run is required to attempt another payment. + + When sending a payment request to the Payments service, you must specify the following. + + | Attribute | Required | Description | + | --- | --- | --- | + | `gateway` | Required| One of `elastic_path_payments_stripe`, `authorize_net` and `stripe_payment_intents`. | + | `method` | Required | Must be `purchase`. + | `payment` | Required | The type of payment, for example, `pm_card_visa_debit`. + | `options` | Required | These options must be set as they set up the card to be used in future without the customer being present. If these options are not set, future payments may fail. There are two options. | + + #### External Payments + + External payments are payment methods not offered by Elastic Path Subscriptions (such as Elastic Path Payments powered by Stripe or Authorize.net), but they can still be integrated with Subscriptions. To do this, you must configure your subscriptions to use external payments by setting `manual_payments` to `true`. See [Create a Subscription](/docs/api/subscriptions/create-subscription). + + When a subscription is created with `manual_payments` set to `true`: + + 1. When the payment run processes the generated invoice, it creates a pending payment. A `subscription-invoice-created` event is emitted that includes the `subscription_id`, `invoice_id` and `payment_id`. No payment is taken. + 2. You can use the events generated by Elastic Path Subscriptions to configure your external payment system to respond to these events, ensuring that your external payment system knows when the payment schedule has run and it's time to process the payment. + 3. When the external payment system handles the payment (either takes the payment successfully or the payment fails) the [Update Invoice Payment](/docs/api/subscriptions/update-invoice-payment) endpoint, enables the update of the pending payment. + - If payment is successful, the invoice is updated to `paid` and the billing/payment cycle continues as normal. + - If payment fails, the invoice continues to be marked as `outstanding`. The payment is not `pending` anymore. This is because a payment attempt has been made. Following on from this, the next payment run generates another manual pending payment. The external system is notified of this using the `subscription-invoice-payment-updated`. + + #### Card Declines + + Card payments can fail for a variety of reasons, including insufficient funds, incorrect card data or fraudulent activity. You can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details, enabling you to easily manage your subscription changes. + - name: Dunning Rules + description: | + + Dunning is the process of handling failed payment attempts. This is important for recovering revenue from failed payments, reduces customer churn and maintains cashflow. By implementing efficient dunning processes, you can enhance financial health and operational efficiency. + + Subscriptions enables you to create a dunning rule that allows you to configure payment retry schedules. Subscriptions retries failed payments automatically. You can customize the timing and frequency of the payment retries. + + Dunning is enabled by default. You can choose to disable dunning. If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments. + + - Do nothing - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use. + - Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber. + - close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment. + - name: Proration Policies + description: | + Proration is the adjustment of charges or credits on a subscriber's account based on the amount of time a service is used. Proration ensures that subscribers are only charged for the actual time they use the service, whether they upgrade, downgrade, start, or cancel their subscription partway through a billing cycle. This means fair billing for your subscribers and provides you with the flexibility to change your subscribers subscriptions at any time. + + ::: note + + Subscriptions use client credentials to enable changes to subscriptions, so if you want your shoppers to have the ability to make changes, you can implement a BFF layer using this approach. + + ::: + + Proration occurs for: + + - Pricing option upgrades/downgrades: If a subscriber changes their pricing option in the middle of a billing cycle, proration adjusts the charges to reflect the time spent on each pricing option. + - Service cancellation: If a subscriber cancels a subscription before the end of a billing cycle, they may receive a prorated invoice for the used portion of the subscription. + - Mid-cycle subscription: If a subscriber starts a subscription in the middle of a billing cycle, they are charged a prorated amount for the remaining days in the billing cycle. + + There are several scenarios when implementing proration policies. + + 1. You may want one policy for multiple offerings because only some subscriptions need prorating. + 2. You may want a default proration policy for your store. + 3. You may want several policies for different offerings. + + In Subscriptions, charges only prorate by day. As soon as a subscriber changes their subscription, a manual billing run is triggered and an invoice is generated with the new price on the next billing run and the difference in price is prorated over days. + + By default, proration is not enabled for Subscriptions. Once you have attached a proration policy to an offering, proration is enabled automatically. + + ### End dates when switching pricing options + + Subscriptions manages the subscription end date when shoppers switch from one pricing option to another. Whether or not an end date is configured depends on the end behavior of the pricing options you are switching between. + + | Current Subscription | New Subscription | Proration Behavior | End date | + | --- | --- | --- | --- | + | `close` | `roll` | The subscription switches from a pricing option with a fixed end date to a rolling pricing option so no end date is set after proration. | No end date is configured. | + | `roll` | `close` | The subscription switches to a fixed pricing option, and the end date is configured based on the duration of the pricing option. | An end date is configured. | + | `close` | `close` | The remaining time on the current pricing option is not carried over to the new pricing option. For example, if your current pricing option has 3 months remaining and you switch to a new pricing option that has a fixed length of 6 months, the new end date is calculated as 6 months from the day you switch pricing options, effectively resetting the subscription length to the new pricing option. | New end date calculated from the day you switched pricing option. | + - name: Observable Events + description: | + You can integrate Subscriptions with external systems like enterprise resource planning, fulfilment and other systems. For example, when a subscriber updates their address, the Customer Relationship Management system is updated with the change. + + Events are actions that occur in Subscriptions, such as a subscriber changing their address or a subscription changing from active to inactive. You can create custom functions that perform additional processing outside of Subscriptions, and create integrations so that when an event occurs in your store, the custom function is run. + + Events are processed concurrently. This means that events may not be delivered in the order they are created. For example, if a subscription is updated multiple times, the events may not be delivered in the same sequence they were updated. Events operate on an "at least once" delivery policy. We aim to deliver messages within 30 minutes or less. Ensure that you design your receiving code accordingly. + + For more information about integrating Subscriptions, see [**Integrations (Event Subscriptions/Notifications)**](/docs/api/integrations/integrations-event-subscriptions-notifications#integration-types). + + | Resource | Action | Observable Key | Availability | + | --- | --- | --- | --- | + | Offering | | | Store | + | Subscription | | | Store | + | Job | | | Store | + | Invoices | | | Store | + | Schedule | | | Store | + | Subscriber | | | Store | +paths: + /v2/subscriptions/offerings: + parameters: + - $ref: '#/components/parameters/Filter' + post: + tags: + - Offerings + summary: Create an offering + operationId: CreateOffering + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/OfferingCreate' + responses: + '201': + description: Success. The offering is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Offering' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + get: + tags: + - Offerings + summary: List offerings + description: | + Retrieves a list of all subscription offerings. + + ### Filtering + + This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). + + The following attributes and operators are supported. + + | Operator | Attribute | Description | + | --- | --- | --- | + | `eq` | `external_ref`, `plans.external_ref`, `proration_policy_id` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | + | `in` | `plans.external_ref` | 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/OfferingInclude' + operationId: ListOfferings + responses: + '200': + description: Success. A list of offerings is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Offering' + included: + $ref: '#/components/schemas/OfferingIncludes' + links: + $ref: '#/components/schemas/Links' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/offerings/build: + post: + tags: + - Offerings + summary: Build an offering + description: | + An offering includes plans and pricing options; plans are combined with one or more pricing options to form an offering. An offering can include either: + + - subscription plans (created within an offering). + - Product Experience Manager products. See [**create a product**](/docs/api/pxm/products/create-product). + + When you are building an offering: + + - you can create new pricing options and plans. + - you can modify an existing plan and pricing options. For example, you can modify the plan price or any attributes of a pricing option included in the offering. + + Here's how you build an offering: + + 1. Specify the plan to build with the offering. A plan can be: + + - subscription plans. Specify the subscription plan attributes. + - Product Experience Manager products. Specify the Product Experience Manager product ID in `external_ref` in `PlanAttributes`. For the remaining plan attributes, you can specify their values to match the values of the existing Product Experience Manager product attributes. However, you can also specify different values, depending on your requirements. + + 2. Specify the pricing options to build with the offering. Pricing options are the rules that govern your subscription, for example, any discount. You can combine and reuse pricing options for as many plans as you want, making it quick and easy to create your subscription offerings. + An offering must have at least one pricing option. + operationId: BuildOffering + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/BuildOffering' + responses: + '201': + description: Success. The new subscription offering is created with the specified subscription plans and pricing options attached to the offering. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Offering' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/offerings/{offering_uuid}: + parameters: + - name: offering_uuid + in: path + description: The unique identifier of the offering. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + parameters: + - $ref: '#/components/parameters/OfferingInclude' + tags: + - Offerings + summary: Get offering + operationId: GetOffering + responses: + '200': + description: Success. The details of the subscription offering are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Offering' + included: + $ref: '#/components/schemas/OfferingIncludes' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + tags: + - Offerings + summary: Delete offering + description: When a subscription is created, it creates a snapshot of the offering. This means you can delete an offering without affecting any active subscriptions. + operationId: DeleteOffering + responses: + '204': + description: Success. The subscription offering is removed. + '500': + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Offerings + summary: Update an offering + description: | + After saving an offering, you can update an offering at any time. Updating an offering does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. For fields that are optional, an existing value can be removed by specifying a value of null. + operationId: UpdateOffering + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/OfferingUpdate' + responses: + '200': + description: Success. The details of the subscription offering are updated. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Offering' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/offerings/{offering_uuid}/features/{feature_uuid}: + parameters: + - name: offering_uuid + in: path + description: The unique identifier of the offering. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: feature_uuid + in: path + description: The unique identifier of the feature. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + summary: Get a feature in an offering + operationId: GetOfferingFeature + tags: + - Offerings + responses: + '200': + description: Success. The details of the feature are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingFeature' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + put: + summary: Updates a feature in an offering + description: Use the unique identifier of the feature in the offering that you want to update. Any modifications that you make to the features in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. + operationId: UpdateOfferingFeature + tags: + - Offerings + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/OfferingFeatureUpdate' + responses: + '200': + description: Success. The feature details are updated on the offering. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Feature' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + summary: Remove a feature from an offering + description: | + After saving an offering, you can remove features from it at any time. + + Removing a feature from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created. + operationId: DeleteOfferingFeature + tags: + - Offerings + responses: + '204': + description: Success. The subscription feature is removed from the offering. + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + /v2/subscriptions/offerings/{offering_uuid}/features/attach: + parameters: + - name: offering_uuid + in: path + description: The unique identifier of the offering. + required: true + schema: + $ref: '#/components/schemas/UUID' + post: + tags: + - Offerings + summary: Attach a feature + description: | + After saving an offering, you can attach new features to it at any time. + + Adding new features does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created. + operationId: AttachOfferingFeature + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/OfferingFeatureAttach' + responses: + '200': + description: Success. The subscription feature is attached with the offering. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/OfferingFeature' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/offerings/{offering_uuid}/pricing-options: + parameters: + - name: offering_uuid + in: path + description: The unique identifier of the offering. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Offerings + summary: List an offering's pricing options + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListOfferingPricingOptions + responses: + '200': + description: Success. A list of pricing options attached with the offering is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/OfferingPricingOption' + links: + $ref: '#/components/schemas/Links' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + post: + tags: + - Offerings + summary: Create a pricing option inside an offering + description: | + After saving an offering, you can add new pricing option to it at any time. + operationId: CreateOfferingPricingOption + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/OfferingPricingOptionCreate' + responses: + '201': + description: Success. The pricing option is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingPricingOption' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/offerings/{offering_uuid}/pricing-options/{pricing_option_uuid}: + parameters: + - name: offering_uuid + in: path + description: The unique identifier of the offering. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: pricing_option_uuid + in: path + description: The unique identifier of the pricing option. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + summary: Get a pricing option in an offering + operationId: GetOfferingPricingOption + tags: + - Offerings + responses: + '200': + description: Success. The details of the pricing option are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingPricingOption' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + put: + summary: Update a pricing option in an offering + operationId: UpdateOfferingPricingOption + tags: + - Offerings + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/OfferingPricingOptionUpdate' + responses: + '200': + description: Success. The pricing option details are updated on the offering. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingPricingOption' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + tags: + - Offerings + summary: Remove a pricing option from an offering + description: | + After saving an offering, you can remove pricing options from it at any time. + + Removing a pricing option from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created. + operationId: DeleteOfferingPricingOption + responses: + '204': + description: Success. The subscription pricing option is no longer associated with the offering. + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + /v2/subscriptions/offerings/{offering_uuid}/features: + parameters: + - name: offering_uuid + in: path + description: The unique identifier of the offering. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Offerings + summary: List an offering's features + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListOfferingFeatures + responses: + '200': + description: Success. A list of subscription features attached to the offering is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/OfferingFeature' + links: + $ref: '#/components/schemas/Links' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + post: + tags: + - Offerings + summary: Create a feature directly inside an offering + description: | + After saving an offering, you can add new features to it at any time. + operationId: CreateOfferingFeature + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/OfferingFeatureCreate' + responses: + '201': + description: Success. The feature is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingFeature' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/offerings/{offering_uuid}/plans: + parameters: + - name: offering_uuid + in: path + description: The unique identifier of the offering. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Offerings + summary: List an offering's plans + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListOfferingPlans + responses: + '200': + description: Success. A list of subscription plans attached to the offering is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/OfferingPlan' + links: + $ref: '#/components/schemas/Links' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + post: + tags: + - Offerings + summary: Create a plan inside an offering + description: | + After saving an offering, you can add new plans to it at any time. + operationId: CreateOfferingPlan + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/OfferingPlanCreate' + responses: + '201': + description: Success. The plan is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingPlan' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}: + parameters: + - name: offering_uuid + in: path + description: The unique identifier of the offering. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: plan_uuid + in: path + description: The unique identifier of the plan. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + summary: Get a plan in an offering + operationId: GetOfferingPlan + tags: + - Offerings + responses: + '200': + description: Success. The details of the plan are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingPlan' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + put: + summary: Update a plan in an offering + description: Use the unique identifier of the plan in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. + operationId: UpdateOfferingPlan + tags: + - Offerings + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/OfferingPlanUpdate' + responses: + '200': + description: Success. The plan details are updated on the offering. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingPlan' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + summary: Remove a plan from an offering + description: | + After saving an offering, you can remove plans from it at any time. + + Removing a plan from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created. + operationId: DeleteOfferingPlan + tags: + - Offerings + responses: + '204': + description: Success. The subscription plan is removed from the offering. + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + /v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}/relationships/pricing_options: + parameters: + - name: offering_uuid + in: path + description: The unique identifier of the offering. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: plan_uuid + in: path + description: The unique identifier of the plan. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + summary: List the pricing options available to a plan in an offering + operationId: ListOfferingPlanPricingOptions + tags: + - Offerings + responses: + '200': + description: Success. The pricing option relationships are returned + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/RelationshipData' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + post: + summary: Adds an offering's pricing options to the plan + description: Use the unique identifier of the pricing in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. + operationId: AddOfferingPlanPricingOptions + tags: + - Offerings + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RelationshipsRequest' + responses: + '200': + description: Success. The pricing options are added to the plan + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/RelationshipData' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + summary: Removes an offering's pricing options from the plan + description: Use the unique identifier of the pricing in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. + operationId: RemoveOfferingPlanPricingOptions + tags: + - Offerings + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RelationshipsRequest' + responses: + '200': + description: Success. The pricing options are added to the plan + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/RelationshipData' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions: + parameters: + - $ref: '#/components/parameters/Filter' + post: + tags: + - Subscriptions + summary: Create a subscription + operationId: CreateSubscription + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/BuildSubscription' + responses: + '201': + description: Success. The subscription is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Subscription' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + get: + tags: + - Subscriptions + summary: List subscriptions + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + - $ref: '#/components/parameters/SubscriptionInclude' + operationId: ListSubscriptions + description: | + Retrieves a list of all subscriptions. + + ### Filtering + + This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). + + The following attributes and operators are supported. + + | Operator | Attribute | Description | + | --- | --- | --- | + | `eq` | `account_id`, `name`, `email`, `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | + + ### Including Resources + + You can use the `include` parameter to include the following resources with this endpoint. + + | Resource | Required | Description | + | --- | --- | --- | + | `pricing_options, plans` | Optional | Retrieves all pricing options and plans associated with a subscription. | + | `plans` | Optional | Retrieves all plans associated with a subscription. | + | `pricing_options` | Optional | Retrieves all pricing options associated with a subscription. | + + See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter). + responses: + '200': + description: Success. A list of subscriptions is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Subscription' + included: + $ref: '#/components/schemas/SubscriptionIncludes' + links: + $ref: '#/components/schemas/Links' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + parameters: + - $ref: '#/components/parameters/SubscriptionInclude' + tags: + - Subscriptions + summary: Get subscription + operationId: GetSubscription + responses: + '200': + description: Success. The details of a subscription are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Subscription' + included: + $ref: '#/components/schemas/SubscriptionIncludes' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Subscriptions + summary: Update a subscription + description: | + Updates a subscription. For example, a subscriber can switch from one pricing option to another in a subscription. + operationId: UpdateSubscription + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/SubscriptionUpdate' + responses: + '200': + description: Success. The subscription is updated. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Subscription' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + tags: + - Subscriptions + summary: Delete a subscription + operationId: DeleteSubscription + description: | + Deletes a subscription + responses: + '204': + description: Success. The subscription is removed. + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}/features/{feature_uuid}: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: feature_uuid + in: path + description: The unique identifier of the feature. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + summary: Get a feature in a subscription + operationId: GetSubscriptionFeature + tags: + - Subscriptions + responses: + '200': + description: Success. The details of the feature are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingFeature' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}/plans/{plan_uuid}: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: plan_uuid + in: path + description: The unique identifier of the plan. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + summary: Get a plan in a subscription + operationId: GetSubscriptionPlan + tags: + - Subscriptions + responses: + '200': + description: Success. The details of the plan are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingPlan' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}/pricing-options/{pricing_option_uuid}: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: pricing_option_uuid + in: path + description: The unique identifier of the pricing option. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + summary: Get a pricing option in a subscription + operationId: GetSubscriptionPricingOption + tags: + - Subscriptions + responses: + '200': + description: Success. The details of the pricing option are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/OfferingPricingOption' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}/features: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Subscriptions + summary: List an subscriptions features + operationId: ListSubscriptionFeatures + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + responses: + '200': + description: Success. A list of subscription features is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/OfferingFeature' + links: + $ref: '#/components/schemas/Links' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}/plans: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Subscriptions + summary: List subscription plans + description: Retrieves a list of plans associated with the specified subscription. Using this endpoint you can see the plan that is currently active in a subscription. If `active_plan` is `true`, a plan is active in a subscription. If `active_plan` is null, the pricing option is not active. + operationId: ListSubscriptionPlans + responses: + '200': + description: Success. A list of subscription plans is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/OfferingPlan' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Subscriptions + summary: Manage subscription plans + description: Manage subscription plans by replacing, changing or detaching plans on the subscription + operationId: ManageSubscriptionPlans + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + description: A list of plan IDs to manage on the subscription. + items: + $ref: '#/components/schemas/ManageSubscriptionPlans' + example: + data: + - type: attach + plans: + - bafa601f-359c-48da-834e-377b6c0d9466 + - type: detach + plans: + - a8aad94d-60fc-44f7-8dfa-299249566ec4 + responses: + '204': + description: Success. The subscription's plans have been updated. + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}/pricing-options: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Subscriptions + summary: List subscription pricing options + description: Retrieves a list of pricing options associated with the specified subscription. Using this endpoint you can see the pricing options that are currently active in a subscription. If `active_pricing_option` is `true`, a pricing option is active in a subscription. If `active_pricing_option` is null, the pricing option is not active. + operationId: ListSubscriptionPricingOptions + responses: + '200': + description: Success. A list of subscription pricing options is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/OfferingPricingOption' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}/states: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + post: + tags: + - Subscriptions + summary: Create a subscription state + description: | + The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. + + A subscription can have the following states: + + - `pending` + - `canceled` + - `paused` + - `resumed` + For more information, see [Managing the Subscription Lifecycle](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle). + 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' + /v2/subscriptions/subscriptions/{subscription_uuid}/states/{state_uuid}: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: state_uuid + in: path + description: The unique identifier of the subscription state. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Subscriptions + summary: Get subscription state + operationId: GetSubscriptionState + responses: + '200': + description: Success. A subscription state is returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/SubscriptionState' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/jobs: + parameters: + - $ref: '#/components/parameters/Filter' + post: + tags: + - Jobs + summary: Create a job + operationId: CreateJob + requestBody: + content: + application/json: + schema: + type: object + title: JobCreateJSON + required: + - data + properties: + data: + $ref: '#/components/schemas/JobCreate' + responses: + '201': + description: Success. The job was created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Job' + '400': + $ref: '#/components/responses/ValidationError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + get: + tags: + - Jobs + summary: List jobs + description: | + Retrieves a list of all jobs. + + ### Filtering + + This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). + + The following attributes and operators are supported. + + | Operator | Attribute | Description | + | --- | --- | --- | + | `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListJobs + responses: + '200': + description: Success. A list of jobs is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Job' + links: + $ref: '#/components/schemas/Links' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/jobs/{job_uuid}: + parameters: + - name: job_uuid + in: path + description: The unique identifier of the job. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Jobs + summary: Get job + operationId: GetJob + responses: + '200': + description: Success. The job is returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Job' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + tags: + - Jobs + summary: Delete job + operationId: DeleteJob + responses: + '204': + description: Success. The job was deleted. + '409': + $ref: '#/components/responses/WriteConflictError' + /v2/subscriptions/imports: + parameters: + - $ref: '#/components/parameters/Filter' + post: + tags: + - Imports + summary: Import a dataset + operationId: CreateImport + requestBody: + content: + multipart/form-data: + schema: + type: object + required: + - import_file + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + import_file: + description: The JSONL file you want to upload. + type: string + format: binary + responses: + '201': + description: Success. The import was started. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Import' + '400': + $ref: '#/components/responses/ValidationError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + get: + tags: + - Imports + summary: List import jobs + description: | + Retrieves a list of all import jobs. + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListImportJobs + responses: + '200': + description: Success. A list of import jobs is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Import' + links: + $ref: '#/components/schemas/Links' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/imports/{import_uuid}: + parameters: + - name: import_uuid + in: path + description: The unique identifier of the import. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + tags: + - Imports + summary: Get import + description: Retrieves the import job for the specified ID. + operationId: GetImport + responses: + '200': + description: Success. The import is returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Import' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/imports/{import_uuid}/errors: + parameters: + - name: import_uuid + in: path + description: The unique identifier of the import. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Imports + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + summary: Get import errors + description: | + Retrieves all errors encountered as part of the import. Each error is attributed to a line in the JSONL file + imported, so for example, if at line 1 in your JSONL you had a subscription_offering without a name, there would + be a minimum string error for the `name` attribute with `"line_number": 1`. + + Errors are also ordered by line number ascending, and can be paginated. + operationId: GetImportErrors + responses: + '200': + description: Success. The import errors are returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/SubscriptionImportError' + links: + $ref: '#/components/schemas/Links' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}/invoices: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Subscriptions + summary: List subscription invoices + description: Lists all invoices for a given subscription. + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListSubscriptionInvoices + responses: + '200': + description: Success. A list of invoices is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/SubscriptionInvoice' + links: + $ref: '#/components/schemas/Links' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscriptions/{subscription_uuid}/invoices/{invoice_uuid}/payments: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: invoice_uuid + in: path + description: The unique identifier of the invoice. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Subscriptions + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + summary: List subscription invoice payments + description: Lists all invoice payments for a given invoice. + operationId: ListSubscriptionInvoicePayments + responses: + '200': + description: Success. Payments for the invoice are returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/SubscriptionInvoicePayment' + links: + $ref: '#/components/schemas/Links' + /v2/subscriptions/subscriptions/{subscription_uuid}/invoices/{invoice_uuid}/payments/{payment_uuid}: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: invoice_uuid + in: path + description: The unique identifier of the invoice. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: payment_uuid + in: path + description: The unique identifier of the payment. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Subscriptions + summary: Get subscription invoice payment + description: Gets a specific payment for a given invoice. + operationId: GetSubscriptionInvoicePayment + responses: + '200': + description: Success. Specific payment for the invoice is returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/SubscriptionInvoicePayment' + '404': + $ref: '#/components/responses/NotFoundError' + /v2/subscriptions/subscriptions/{subscription_uuid}/invoices/{invoice_uuid}: + parameters: + - name: subscription_uuid + in: path + description: The unique identifier of the subscription. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: invoice_uuid + in: path + description: The unique identifier of the invoice. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Subscriptions + summary: Get subscription invoice + description: Gets a specific invoice for a given subscription. + operationId: GetSubscriptionInvoice + responses: + '200': + description: Success. An invoice is returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/SubscriptionInvoice' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/invoices: + get: + tags: + - Invoices + summary: List invoices + description: | + Retrieves a list of all invoices. + + ### Filtering + + This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). + + The following attributes and operators are supported. + + | Operator |Attribute | Description | + | --- | --- | --- | + | `eq` | `subscriber_id`, `subscription_id`, `outstanding`, `tax_required` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | + parameters: + - $ref: '#/components/parameters/Filter' + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListInvoices + responses: + '200': + description: Success. A list of invoices is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/SubscriptionInvoice' + links: + $ref: '#/components/schemas/Links' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/invoices/{invoice_uuid}: + parameters: + - name: invoice_uuid + in: path + description: The unique identifier of the invoice. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Invoices + summary: Get invoice + operationId: GetInvoice + responses: + '200': + description: Success. The details of the invoice are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/SubscriptionInvoice' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/invoices/{invoice_uuid}/payments: + parameters: + - name: invoice_uuid + in: path + description: The unique identifier of the invoice. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Invoices + summary: List invoice payments + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListInvoicePayments + responses: + '200': + description: Success. Payments for the invoice are returned + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/SubscriptionInvoicePayment' + links: + $ref: '#/components/schemas/Links' + /v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}: + parameters: + - name: invoice_uuid + in: path + description: The unique identifier of the invoice. + required: true + schema: + $ref: '#/components/schemas/UUID' + - name: payment_uuid + in: path + description: The unique identifier of the payment. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Invoices + summary: Get invoice payment + operationId: GetInvoicePayment + responses: + '200': + description: Success. Specific payment for the invoice is returned + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/SubscriptionInvoicePayment' + '404': + $ref: '#/components/responses/NotFoundError' + put: + tags: + - Invoices + summary: Update Invoice Payment + description: | + External payment methods are payment methods not offered by Elastic Path Subscriptions (such as Elastic Path Payments powered by Stripe or Authorize.net), but they can still be integrated with Subscriptions. You can use the `Update Invoice Payment` endpoint to manually update a payment against an invoice where an external payment method is handling the payment of your invoices. See [External Payments](/docs/api/subscriptions/invoices#external-payments). + operationId: UpdateInvoicePayment + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/UpdateInvoicePayment' + responses: + '200': + description: Success. Invoice payment has been updated. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/SubscriptionInvoicePayment' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/schedules: + parameters: + - $ref: '#/components/parameters/Filter' + get: + tags: + - Schedules + summary: List schedules + description: | + Retrieves a list of all schedules. + + ### Filtering + + This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). + + The following attributes and operators are supported. + + | Operator | Attribute | Description | + | --- | --- | --- | + | `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListSchedules + responses: + '200': + description: Success. A list of schedules is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Schedule' + links: + $ref: '#/components/schemas/Links' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + post: + tags: + - Schedules + summary: Create a schedule + operationId: CreateSchedule + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ScheduleCreate' + responses: + '201': + description: Success. The schedule is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Schedule' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/schedules/{schedule_uuid}: + parameters: + - name: schedule_uuid + in: path + description: The unique identifier of the schedule. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Schedules + summary: Get a schedule + operationId: GetSchedule + responses: + '200': + description: Success. A schedule is returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Schedule' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Schedules + summary: Update a schedule + operationId: UpdateSchedule + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ScheduleUpdate' + responses: + '200': + description: Success. The schedule details are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Schedule' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + tags: + - Schedules + summary: Delete schedule + operationId: DeleteSchedule + responses: + '204': + description: Success. The schedule is removed. + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscribers: + parameters: + - $ref: '#/components/parameters/Filter' + get: + tags: + - Subscribers + summary: List subscribers + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + operationId: ListSubscribers + description: | + Retrieves a list of all subscribers. + + ### Filtering + + This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). + + The following attributes and operators are supported. + + | Operator | Attribute | Description | + | --- | --- | --- | + | `eq` | `account_id`, `name`, `email`, `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | + responses: + '200': + description: Success. A list of subscribers is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Subscriber' + links: + $ref: '#/components/schemas/Links' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + post: + tags: + - Subscribers + summary: Create a subscriber + operationId: CreateSubscriber + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/SubscriberCreate' + responses: + '201': + description: Success. The subscriber is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Subscriber' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/subscribers/{subscriber_uuid}: + parameters: + - name: subscriber_uuid + in: path + description: The unique identifier of the subscriber. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Subscribers + summary: Get a subscriber + operationId: GetSubscriber + responses: + '200': + description: Success. A subscriber is returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Subscriber' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Subscribers + summary: Update a subscriber + operationId: UpdateSubscriber + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/SubscriberUpdate' + responses: + '200': + description: Success. The subscriber details are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Subscriber' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + tags: + - Subscribers + summary: Delete subscriber + operationId: DeleteSubscriber + responses: + '204': + description: Success. The subscriber is removed. + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/dunning-rules: + post: + tags: + - Dunning Rules + summary: Create a dunning rule + description: | + Dunning rules must use a `fixed` strategy. This means payments are retried on a fixed schedule. + + When an invoice is created, it immediately becomes eligible for payment by the next payment run. If the first payment attempt fails then the invoice enters dunning. In subsequent payment runs, invoices are only considered for payment if they meet the dunning rules you create. + + You can configure a dunning rule to be the default for your store. There can only be one default rule per store. All invoices in your store will then perform dunning according to the specified rules. + + :::note + If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments. + ::: + + The following attributes are used to define a `fixed` schedule: + + - `payment_retry_unit - the unit of time used to measure the intervals between payment attempts or retries. + - `payment_retry_interval` - the number of `payment_interval-units` to wait between each payment retry attempt. + - `payment_retries_limit` - the number of times subscriptions attempts payments retries before an `action` is taken. + - `action` - the action to take if payment is not successful. + + For example, if: + + - the `payment_retry_unit` is `days` + - the `payment_retry_interval` is `2` + - the `payment_rety_limit` is `10` + - the `action` is `close`. + + Subscriptions attempts to retry the payment every 2 days until 10 payment attempts have been tried. At that point, the subscription ends and it's status changes to `inacive`. + + Following on from this, you can specify that the dunning rule is no longer the default. You do not have to specify another rule to replace it. If you do remove the default dunning rule, the store defaults to the behavior that is followed when dunning is not enabled. + operationId: CreateDunningRule + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/DunningRuleCreate' + responses: + '201': + description: Success. The dunning rule set is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/DunningRule' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + get: + tags: + - Dunning Rules + parameters: + - $ref: '#/components/parameters/Filter' + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + summary: List dunning rules + description: | + Retrieves a list of all dunning rule sets. + operationId: ListDunningRules + responses: + '200': + description: Success. A list of dunning rules is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/DunningRule' + links: + $ref: '#/components/schemas/Links' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/dunning-rules/{dunning_rule_uuid}: + parameters: + - name: dunning_rule_uuid + in: path + description: The unique identifier of a dunning rule set. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Dunning Rules + summary: Get dunning rule policy + operationId: GetDunningRule + responses: + '200': + description: Success. The dunning rule details are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/DunningRule' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Dunning Rules + summary: Update dunning rule policy + description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the rule is not updated. For fields that are optional, an existing value can be removed by specifying a value of null. + operationId: UpdateDunningRule + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/DunningRuleUpdate' + responses: + '200': + description: Success. The dunning rule set has been updated. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/DunningRule' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + tags: + - Dunning Rules + summary: Delete dunning rules + description: You can delete a dunning rule at any time. If a dunning rule is deleted then Subscriptions reverts to the configuration used if no dunning rule is set; payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments. See [Dunning Rules](/docs/api/subscriptions/dunning-rules). + operationId: DeleteDunningRule + responses: + '204': + description: Success. The dunning rule is removed. + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/proration-policies: + post: + tags: + - Proration Policies + summary: Create a Proration Policy + description: | + In Subscriptions, you configure proration by creating a proration policy and attaching it to an offering. Once you have [attached](/docs/api/subscriptions/update-offering) the policy, the proration policy applies to all subscriptions that use the offering. + operationId: CreateProrationPolicy + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ProrationPolicyCreate' + responses: + '201': + description: Success. The proration policy is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/ProrationPolicy' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + get: + tags: + - Proration Policies + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + summary: List proration policies + description: | + Retrieves a list of all proration policies. + operationId: ListProrationPolicies + responses: + '200': + description: Success. A list of proration policies is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ProrationPolicy' + links: + $ref: '#/components/schemas/Links' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/proration-policies/{proration_policy_uuid}: + parameters: + - name: proration_policy_uuid + in: path + description: The unique identifier of a proration policy. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Proration Policies + summary: Get proration policy + operationId: GetProrationPolicy + responses: + '200': + description: Success. The proration policy details are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/ProrationPolicy' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Proration Policies + summary: Update proration policy + description: | + You can update a proration policy at any time. For any subscriptions that are using the updated proration policy, the changes are also applied. Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the proration policy is not updated. + + When updating proration policies: + + - You can change the name of an existing policy. + - You can update `rounding`. + - You can update `external_ref` as long as `external_ref` is still unique in your store. + - You can remove `external_ref` as this attribute is optional. + - You cannot remove any required attributes, such as `name` or `rounding`. + operationId: UpdateProrationPolicy + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ProrationPolicyUpdate' + responses: + '200': + description: Success. The proration policy details are updated. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/ProrationPolicy' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + delete: + tags: + - Proration Policies + summary: Delete proration policy + description: A proration policy cannot be deleted if it is being used by any subscriptions. This means you must detach a proration policy that you want to delete from any offerings using that policy before deleting the policy. See [Remove a proration policy from an offering](/docs/api/subscriptions/update-offering). + operationId: DeleteProrationPolicy + responses: + '204': + description: Success. The proration policy details are removed. + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/features: + parameters: + - $ref: '#/components/parameters/Filter' + post: + tags: + - Features + summary: Create a feature + operationId: CreateFeature + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/FeatureCreate' + responses: + '201': + description: Success. The feature is created. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Feature' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + get: + tags: + - Features + parameters: + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/PageLimit' + summary: List features + description: | + Retrieves a list of all subscription features. + + ### Filtering + + This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering). + + The following attributes and operators are supported. + + | Operator | Attribute | Description | + | --- | --- | --- | + | `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | + | `eq` | `tag` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | + operationId: ListFeatures + responses: + '200': + description: Success. A list of features is returned. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Feature' + links: + $ref: '#/components/schemas/Links' + '400': + $ref: '#/components/responses/ValidationError' + '500': + $ref: '#/components/responses/InternalServerError' + /v2/subscriptions/features/{feature_uuid}: + parameters: + - name: feature_uuid + in: path + description: The unique identifier of a feature. + required: true + schema: + $ref: '#/components/schemas/UUID' + get: + tags: + - Features + summary: Get feature + operationId: GetFeature + responses: + '200': + description: Success. The feature details are returned. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Feature' + '400': + $ref: '#/components/responses/ValidationError' + '404': + $ref: '#/components/responses/NotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + delete: + tags: + - Features + summary: Delete feature + description: Remove a feature. + operationId: DeleteFeature + responses: + '204': + description: Success. The feature is removed. + '500': + $ref: '#/components/responses/InternalServerError' + put: + tags: + - Features + summary: Update a feature + description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the feature is not updated. For fields that are optional, an existing value can be removed by specifying a value of null. + operationId: UpdateFeature + requestBody: + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/FeatureUpdate' + responses: + '200': + description: Success. The feature details are updated. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Feature' + '400': + $ref: '#/components/responses/ValidationError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/NotFoundError' + '409': + $ref: '#/components/responses/WriteConflictError' + '500': + $ref: '#/components/responses/InternalServerError' +components: + securitySchemes: + BearerToken: + scheme: bearer + type: http + parameters: + OfferingInclude: + name: include + in: query + required: false + style: form + explode: false + schema: + type: array + description: A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter). + example: plans,pricing_options + items: + type: string + enum: + - plans + - pricing_options + - features + SubscriptionInclude: + name: include + in: query + required: false + style: form + explode: false + schema: + type: array + description: A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter). + example: plans,pricing_options + items: + type: string + enum: + - plans + - pricing_options + Filter: + name: filter + in: query + required: false + schema: + type: string + format: string + description: | + Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports. + example: eq(name,Alan Turing) + PageOffset: + name: page[offset] + description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used. + in: query + required: false + schema: + type: integer + format: int64 + minimum: 0 + maximum: 10000 + example: 10 + PageLimit: + name: page[limit] + description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used. + in: query + required: false + schema: + type: integer + format: int64 + minimum: 0 + example: 100 + responses: + InternalServerError: + description: Internal server error. There was a system failure in the platform. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internal-server-error: + value: + errors: + - title: Internal Server Error + status: '500' + NotFoundError: + description: Not found. The requested entity does not exist. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + not-found: + value: + errors: + - title: Not Found + status: '404' + detail: No plan found + ForbiddenError: + description: Forbidden. The operation is forbidden on this entity. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + not-found: + value: + errors: + - title: Permission denied + status: '404' + detail: 'Permission denied: plan tenancy mismatch' + ValidationError: + description: Bad request. The request failed validation. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + missing-name: + value: + errors: + - title: Validation Error + status: '400' + detail: 'data.attributes.name: "name" is required' + WriteConflictError: + description: Write conflict. Unable to perform the operation at this time. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + errors: + - title: Write Conflict + status: '409' + schemas: + ActivePricingOption: + type: boolean + description: Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription. + example: true + ActivePlan: + type: boolean + description: Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription. + example: true + ExternalRef: + description: A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters. + type: string + example: abc123 + maxLength: 2048 + ExternalRefUpdate: + description: A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters. + type: string + example: abc123 + maxLength: 2048 + nullable: true + SubscriptionType: + type: string + example: subscription + enum: + - subscription + ProrationPolicyType: + type: string + example: subscription_proration_policy + enum: + - subscription_proration_policy + SubscriptionDunningRuleType: + type: string + example: subscription_dunning_rule + enum: + - subscription_dunning_rule + SubscriptionFeatureType: + type: string + example: subscription_feature + enum: + - subscription_feature + SubscriptionOfferingType: + type: string + example: subscription_offering + enum: + - subscription_offering + SubscriptionOfferingFeatureType: + type: string + example: subscription_offering_feature + enum: + - subscription_offering_feature + SubscriptionOfferingPlanType: + type: string + example: subscription_offering_plan + enum: + - subscription_offering_plan + SubscriptionOfferingPricingOptionType: + type: string + example: subscription_offering_pricing_option + enum: + - subscription_offering_pricing_option + SubscriptionJobType: + type: string + example: subscription_job + enum: + - subscription_job + SubscriptionImportType: + type: string + example: subscription_import + enum: + - subscription_import + SubscriptionImportErrorType: + type: string + example: subscription_import_error + enum: + - subscription_import_error + SubscriptionImportError: + type: object + required: + - id + - type + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionImportErrorType' + meta: + $ref: '#/components/schemas/SubscriptionImportErrorMeta' + SubscriptionImportErrorMeta: + type: object + required: + - owner + - timestamps + - error + - field + - line_number + properties: + owner: + type: string + example: store + timestamps: + $ref: '#/components/schemas/Timestamps' + error: + type: string + example: offering name cannot be empty + field: + type: string + example: name + line_number: + type: integer + description: The line in the imported JSONL file at which the validation error occurred. Starts from 1. + example: 123 + external_ref: + $ref: '#/components/schemas/ExternalRef' + SubscriptionInvoiceType: + description: This represents the type of resource object being returned. Always `subscription_invoice`. + type: string + example: subscription_invoice + enum: + - subscription_invoice + SubscriptionInvoicePaymentType: + type: string + description: This represents the type of resource object being returned. Always `subscription_invoice_payment`. + example: subscription_invoice_payment + enum: + - subscription_invoice_payment + Links: + type: object + additionalProperties: + $ref: '#/components/schemas/Link' + Link: + anyOf: + - $ref: '#/components/schemas/LinkURI' + - $ref: '#/components/schemas/LinkObject' + LinkURI: + type: string + format: uri + example: http://example.com/articles/1/comments + nullable: true + LinkObject: + type: object + properties: + href: + type: string + format: uri + example: http://example.com/articles/1/comments + title: + type: string + example: Comments + describedby: + type: string + format: uri + example: http://example.com/schemas/article-comments + Timestamps: + required: + - created_at + - updated_at + properties: + updated_at: + description: The date and time a resource was updated. + type: string + example: '2017-01-10T11:41:19.244842Z' + created_at: + description: The date and time a resource was created. + type: string + example: '2017-01-10T11:41:19.244842Z' + Status: + type: string + description: The status of a subscription, either `active` or `inactive`. + example: active + enum: + - active + - inactive + x-go-type: model.SubscriptionStatus + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + RelationshipsRequest: + description: Enumerates a list of resources that are related. + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/RelationshipData' + Relationships: + description: Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it. + additionalProperties: + $ref: '#/components/schemas/Relationship' + example: + pricing-options: + links: + related: /offerings/:offering-id/pricing-options + self: /offerings/:offering-id + data: + type: offering-pricing-option + id: 625fe958-7b4b-40a0-a2c0-dbb8f31eec0d + Relationship: + anyOf: + - $ref: '#/components/schemas/SingleRelationship' + - $ref: '#/components/schemas/ManyRelationship' + ManyRelationship: + description: The list of resources that are related. + properties: + data: + type: array + items: + $ref: '#/components/schemas/RelationshipData' + links: + $ref: '#/components/schemas/RelationshipLinks' + SingleRelationship: + description: The subscription resource that is related. + properties: + data: + $ref: '#/components/schemas/RelationshipData' + links: + $ref: '#/components/schemas/RelationshipLinks' + RelationshipData: + type: object + required: + - id + - type + properties: + id: + $ref: '#/components/schemas/UUID' + type: + type: string + description: This represents the type of resource being returned. + example: 11111111-2222-3333-4444-555555555555 + RelationshipLinks: + description: | + Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. + + - current - Always the current page. + - first - Always the first page. + - last - always `null`. + - next - `null` if the user is on the first page. + - previous - `null` if there is only one page. + type: object + properties: + related: + type: string + example: foo.bar + TimePeriod: + description: A period of time between a start and end point. + required: + - start + - end + properties: + start: + description: The date and time a billing period started. + type: string + format: date-time + example: '2017-07-21T17:32:28Z' + end: + description: The date and time a billing period ended. + type: string + format: date-time + example: '2017-07-21T17:32:28Z' + SingleCurrencyPrice: + description: A price in a single currency. + required: + - amount + - currency + properties: + currency: + type: string + description: The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price. + example: USD + maxLength: 1024 + amount: + type: integer + format: int64 + description: The value as a whole number of the currency's smallest subdivision. + example: 100 + includes_tax: + type: boolean + description: Whether the amount includes any taxes. + example: true + example: + currency: USD + amount: 100 + includes_tax: false + PriceUnits: + type: object + description: The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans. + required: + - unit + - amount + properties: + unit: + type: string + description: A unit of time. + enum: + - day + - month + example: day + x-go-type: model.PriceUnitsUnit + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + amount: + type: integer + description: The number of days or months the period covers. + example: 7 + minimum: 1 + NullablePriceUnits: + type: object + nullable: true + description: The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans. + required: + - unit + - amount + properties: + unit: + type: string + description: A unit of time, either days or months. + enum: + - day + - month + example: day + x-go-type: model.PriceUnitsUnit + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + amount: + type: integer + description: The number of days or months the period covers. + example: 7 + minimum: 1 + Price: + additionalProperties: + type: object + description: The base price. + required: + - amount + properties: + amount: + type: integer + format: int64 + example: 100 + description: The value as a whole number of the currency's smallest subdivision. + includes_tax: + type: boolean + example: true + description: Indicates whether the amount includes any taxes. + example: + USD: + amount: 100 + includes_tax: false + GBP: + amount: 90 + includes_tax: true + NullablePrice: + type: object + additionalProperties: + type: object + required: + - amount + properties: + amount: + type: integer + format: int64 + example: 100 + description: The value as a whole number of the currency's smallest subdivision. + includes_tax: + type: boolean + example: true + description: Whether the amount includes any taxes. + nullable: true + example: + USD: + amount: 100 + includes_tax: false + GBP: + amount: 90 + includes_tax: true + nullable: true + OfferingPlanPrices: + type: object + description: A list of plan prices for each of its pricing options. + additionalProperties: + $ref: '#/components/schemas/OfferingPlanPriceForPricingOption' + OfferingPlanPriceForPricingOption: + properties: + price: + $ref: '#/components/schemas/Price' + display_price: + $ref: '#/components/schemas/DisplayPrice' + DisplayPrice: + properties: + without_tax: + $ref: '#/components/schemas/PriceFormatting' + with_tax: + $ref: '#/components/schemas/PriceFormatting' + 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. + Feature: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionFeatureType' + attributes: + $ref: '#/components/schemas/FeatureResponseAttributes' + meta: + $ref: '#/components/schemas/FeatureMeta' + FeatureMeta: + readOnly: true + required: + - owner + - timestamps + properties: + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/Timestamps' + FeatureCreate: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/SubscriptionFeatureType' + attributes: + $ref: '#/components/schemas/FeatureAttributes' + FeatureUpdate: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionFeatureType' + attributes: + $ref: '#/components/schemas/FeatureUpdateAttributes' + OfferingFeatureCreate: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/SubscriptionOfferingFeatureType' + attributes: + $ref: '#/components/schemas/FeatureAttributes' + FeatureResponseAttributes: + allOf: + - $ref: '#/components/schemas/FeatureAttributes' + FeatureTag: + type: string + description: A tag to add to the customer's account when entitled to the feature. + minLength: 1 + maxLength: 64 + pattern: ^[0-9A-Za-z_-]+$ + example: digital_library_access + FeatureAccessAttributes: + required: + - type + - tag + properties: + type: + type: string + enum: + - access + example: access + tag: + $ref: '#/components/schemas/FeatureTag' + FeaturePromotion: + required: + - name + - tag + properties: + name: + type: string + description: The name of the feature. + minLength: 3 + maxLength: 1024 + example: Digital library access + tag: + $ref: '#/components/schemas/FeatureTag' + promotion_id: + $ref: '#/components/schemas/UUID' + FeaturePromotionAttributes: + required: + - type + - promotions + properties: + type: + type: string + enum: + - promotion + example: promotion + promotions: + type: array + items: + $ref: '#/components/schemas/FeaturePromotion' + FeatureUsageAttributes: + required: + - type + - tag + - label + - default_value + properties: + type: + type: string + enum: + - usage + example: usage + tag: + $ref: '#/components/schemas/FeatureTag' + label: + type: string + description: The property that has a usage limit. + minLength: 3 + maxLength: 1024 + example: Digital downloads + default_value: + type: integer + description: The default initial value + example: 10 + FeatureConfiguration: + type: object + required: + - type + properties: + type: + description: The type of feature, one of access, promotion or usage. + enum: + - access + - promotion + - usage + example: access + x-go-type: string + oneOf: + - $ref: '#/components/schemas/FeatureAccessAttributes' + - $ref: '#/components/schemas/FeaturePromotionAttributes' + - $ref: '#/components/schemas/FeatureUsageAttributes' + discriminator: + propertyName: type + mapping: + access: '#/components/schemas/FeatureAccessAttributes' + promotion: '#/components/schemas/FeaturePromotionAttributes' + usage: '#/components/schemas/FeatureUsageAttributes' + FeatureAttributes: + required: + - name + - configuration + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + name: + type: string + description: The name of the feature. + minLength: 3 + maxLength: 1024 + example: Digital library access + description: + type: string + description: The feature description to display to customers. + maxLength: 1024 + example: Access to over 100 ebooks via the digital library. + configuration: + $ref: '#/components/schemas/FeatureConfiguration' + FeatureUpdateAttributes: + properties: + external_ref: + $ref: '#/components/schemas/ExternalRefUpdate' + name: + type: string + description: The name of the feature. + minLength: 3 + maxLength: 1024 + example: Digital library access + description: + type: string + description: The feature description to display to customers. + maxLength: 1024 + example: Access to over 100 ebooks via the digital library. + nullable: true + configuration: + $ref: '#/components/schemas/FeatureConfiguration' + PlanMeta: + readOnly: true + required: + - owner + - timestamps + properties: + prices: + $ref: '#/components/schemas/OfferingPlanPrices' + display_price: + $ref: '#/components/schemas/DisplayPrice' + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/Timestamps' + active_plan: + $ref: '#/components/schemas/ActivePlan' + OfferingPlanCreate: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/SubscriptionOfferingPlanType' + attributes: + $ref: '#/components/schemas/OfferingPlanAttributes' + relationships: + $ref: '#/components/schemas/Relationships' + OfferingPlanAttributes: + allOf: + - $ref: '#/components/schemas/PlanAttributes' + - $ref: '#/components/schemas/OfferingPlanExtraAttributes' + OfferingPlanResponseAttributes: + allOf: + - $ref: '#/components/schemas/PlanResponseAttributes' + - $ref: '#/components/schemas/OfferingPlanResponseExtraAttributes' + OfferingPlanExtraAttributes: + properties: + feature_configurations: + type: object + description: A map of configurations indicating which features are available for the plan + additionalProperties: + $ref: '#/components/schemas/FeaturePlanConfiguration' + OfferingPlanResponseExtraAttributes: + required: + - feature_configurations + properties: + feature_configurations: + type: object + description: A map of configurations indicating which features are available for the plan + additionalProperties: + $ref: '#/components/schemas/FeaturePlanConfiguration' + PlanResponseAttributes: + allOf: + - $ref: '#/components/schemas/PlanAttributes' + - $ref: '#/components/schemas/Timestamps' + PlanAttributes: + required: + - name + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + name: + type: string + description: The name of the plan. + minLength: 3 + maxLength: 1024 + example: Magazine + description: + type: string + description: The plan or service description to display to customers. + maxLength: 1024 + example: A lovely magazine that is published every month. + sku: + type: string + description: A stock keeping unit for the plan, if appropriate. + maxLength: 1024 + example: MAGAZINE1 + main_image: + type: string + format: uri + description: A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported. + maxLength: 1024 + example: https://magazine.com/cover.jpg + price: + $ref: '#/components/schemas/Price' + price_units: + $ref: '#/components/schemas/PriceUnits' + OfferingPlanUpdateAttributes: + allOf: + - $ref: '#/components/schemas/PlanUpdateAttributes' + - $ref: '#/components/schemas/OfferingPlanUpdateExtraAttributes' + OfferingPlanUpdateExtraAttributes: + properties: + feature_configurations: + type: object + description: A map of configurations indicating which features are available for the plan + additionalProperties: + $ref: '#/components/schemas/FeaturePlanConfigurationUpdate' + PlanUpdateAttributes: + properties: + external_ref: + $ref: '#/components/schemas/ExternalRefUpdate' + name: + type: string + description: The name of the plan. + minLength: 3 + maxLength: 1024 + example: Magazine + description: + type: string + description: The plan or service description to display to customers. + maxLength: 1024 + example: A lovely magazine that is published every month. + nullable: true + sku: + type: string + description: A stock keeping unit for the plan, if appropriate. + maxLength: 1024 + example: MAGAZINE1 + nullable: true + main_image: + type: string + format: uri + description: A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported. + maxLength: 1024 + example: https://magazine.com/cover.jpg + nullable: true + price: + $ref: '#/components/schemas/NullablePrice' + price_units: + $ref: '#/components/schemas/NullablePriceUnits' + DunningRule: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionDunningRuleType' + attributes: + $ref: '#/components/schemas/DunningRuleAttributes' + meta: + $ref: '#/components/schemas/DunningRuleMeta' + DunningRuleMeta: + readOnly: true + required: + - owner + - timestamps + properties: + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/Timestamps' + DunningRuleCreate: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/SubscriptionDunningRuleType' + attributes: + $ref: '#/components/schemas/DunningRuleAttributes' + DunningRuleUpdate: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionDunningRuleType' + attributes: + $ref: '#/components/schemas/DunningRuleUpdateAttributes' + DunningRuleAttributes: + description: | + The dunning rule attributes you can use to configure your payment retry strategy. + example: + payment_retry_type: fixed + payment_retry_unit: day + payment_retry_interval: 1 + payment_retries_limit: 10 + action: none + required: + - payment_retry_type + - payment_retries_limit + - action + properties: + payment_retry_type: + type: string + enum: + - fixed + - backoff + - tiered + example: fixed + description: | + The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days. + x-go-type: model.PaymentRetryType + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + payment_retry_interval: + type: integer + format: int64 + minimum: 1 + maximum: 1024 + example: 1 + description: The number of `payment_interval_unit`s to wait between each payment retry attempt. + payment_retry_unit: + type: string + enum: + - day + - week + example: day + description: The unit of time used to measure the intervals between payment attempts or retries. + x-go-type: model.PaymentRetryUnit + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + payment_retry_multiplier: + type: number + format: double + minimum: 1 + maximum: 1024 + example: 1 + description: The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types. + payment_retries_limit: + type: integer + format: int64 + minimum: 0 + example: 5 + description: The number of times Subscriptions attempts payment retries before `action` is taken. + action: + type: string + enum: + - none + - pause + - close + - suspend + example: none + description: | + The action to take after all payment attempts for an invoice have failed. + + - None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use. + - Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber. + - close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment. + x-go-type: model.DunningAction + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + default: + type: boolean + example: false + description: Set to `true` if you want this rule to be the default for the store. + DunningRuleUpdateAttributes: + properties: + payment_retry_type: + type: string + enum: + - fixed + - backoff + - tiered + example: fixed + description: | + The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days. + x-go-type: model.PaymentRetryType + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + payment_retry_interval: + type: integer + format: int64 + minimum: 1 + maximum: 1024 + example: 1 + description: The number of `payment_interval_unit`s to wait between each payment retry attempt. + nullable: true + payment_retry_unit: + type: string + enum: + - day + - week + example: day + description: The unit of time used to measure the intervals between payment attempts or retries. + nullable: true + x-go-type: model.PaymentRetryUnit + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + payment_retry_multiplier: + type: number + format: double + minimum: 1 + maximum: 1024 + example: 1 + description: The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types. + nullable: true + payment_retries_limit: + type: integer + format: int64 + minimum: 0 + example: 5 + description: The number of times Subscriptions attempts payment retries before `action` is taken. + action: + type: string + enum: + - none + - pause + - close + - suspend + example: none + description: The action to take after all payment attempts for an invoice have failed. + x-go-type: model.DunningAction + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + default: + type: boolean + example: false + description: Set to `true` if you want this rule to be the default for the store. + ProrationPolicy: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/ProrationPolicyType' + attributes: + $ref: '#/components/schemas/ProrationPolicyResponseAttributes' + meta: + $ref: '#/components/schemas/ProrationPolicyMeta' + ProrationPolicyUpdate: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/ProrationPolicyType' + attributes: + $ref: '#/components/schemas/ProrationPolicyUpdateAttributes' + ProrationPolicyRelationshipAttributes: + type: object + required: + - type + - id + properties: + type: + $ref: '#/components/schemas/ProrationPolicyType' + id: + $ref: '#/components/schemas/UUID' + ProrationPolicyUpdateRelationshipAttributes: + type: object + nullable: true + required: + - type + - id + properties: + type: + $ref: '#/components/schemas/ProrationPolicyType' + id: + $ref: '#/components/schemas/UUID' + ProrationPolicyResponseAttributes: + allOf: + - $ref: '#/components/schemas/ProrationPolicyAttributes' + ProrationPolicyCreate: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/ProrationPolicyType' + attributes: + $ref: '#/components/schemas/ProrationPolicyAttributes' + ProrationPolicyAttributes: + required: + - name + - rounding + properties: + name: + type: string + description: A name for the proration policy. + example: Main Policy + minLength: 3 + maxLength: 1024 + rounding: + type: string + description: | + When rounding in proration, you must decide how to round the units of time used to calculate the charges. + + - round up to the next unit, ensuring subscribers are charged slightly more to cover any partial use. + - round down to the previous whole unit, providing subscribers with a slight benefit by not charging for partial use. + - round to the nearest whole unit, whether up or down, based on standard rounding rules. For example, rounding 0.5 up and rounding 0.5 down. + enum: + - up + - down + - nearest + example: up + x-go-type: model.ProrationPolicyRounding + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + external_ref: + $ref: '#/components/schemas/ExternalRef' + ProrationPolicyUpdateAttributes: + properties: + external_ref: + $ref: '#/components/schemas/ExternalRefUpdate' + name: + type: string + description: The name of the proration policy. + minLength: 3 + maxLength: 1024 + example: Main Policy + rounding: + type: string + description: Whether to round up or down + enum: + - up + - down + - nearest + example: up + x-go-type: model.ProrationPolicyRounding + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + ProrationPolicyMeta: + readOnly: true + required: + - owner + - timestamps + properties: + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/Timestamps' + OfferingPricingOptionCreate: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/SubscriptionOfferingPricingOptionType' + attributes: + $ref: '#/components/schemas/PricingOptionAttributes' + PricingOptionResponseAttributes: + allOf: + - $ref: '#/components/schemas/PricingOptionAttributes' + - $ref: '#/components/schemas/Timestamps' + PricingOptionAttributes: + required: + - name + - billing_interval_type + - billing_frequency + - plan_length + - end_behavior + - can_pause + - can_resume + - can_cancel + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + name: + type: string + description: A name for the pricing option. + example: Monthly + minLength: 3 + maxLength: 1024 + description: + type: string + description: The pricing option description to display to customers. + maxLength: 1024 + example: A monthly subscription. + billing_interval_type: + type: string + description: The unit of time that billing intervals are measured. + example: month + enum: + - day + - week + - month + - year + x-go-type: model.BillingIntervalType + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + billing_frequency: + type: integer + description: The number of intervals between issuing bills. + example: 1 + minimum: 1 + trial_period: + type: integer + description: The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month. + example: 7 + minimum: 0 + lead_time: + $ref: '#/components/schemas/LeadTime' + plan_length: + type: integer + description: The number of intervals that the subscription runs for. + example: 12 + minimum: 1 + end_behavior: + type: string + description: Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments. + example: close + enum: + - close + - roll + x-go-type: model.EndBehavior + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + can_pause: + type: boolean + description: The subscriber can pause a subscription. + example: false + can_resume: + type: boolean + description: The subscriber can resume a paused subscription. + example: false + can_cancel: + type: boolean + description: The subscriber can cancel a subscription. + example: false + base_price_percentage: + type: number + format: double + description: A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering. + example: 90 + minimum: 0 + maximum: 100 + fixed_price: + $ref: '#/components/schemas/Price' + PricingOptionUpdateAttributes: + properties: + external_ref: + $ref: '#/components/schemas/ExternalRefUpdate' + name: + type: string + example: Monthly + minLength: 3 + maxLength: 1024 + description: + type: string + description: The pricing option description to display to customers. + example: A monthly subscription. + maxLength: 1024 + nullable: true + billing_interval_type: + type: string + description: The unit of time in which billing intervals are measured. + example: month + enum: + - day + - week + - month + - year + x-go-type: model.BillingIntervalType + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + billing_frequency: + type: integer + description: The number of intervals between issuing bills. + example: 1 + minimum: 1 + trial_period: + type: integer + description: The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month. + example: 7 + minimum: 0 + nullable: true + plan_length: + type: integer + description: The length of time for which a subscription plan is valid. For example, six months after which the plan is renewed. + example: 12 + minimum: 1 + lead_time: + $ref: '#/components/schemas/NullableLeadTime' + end_behavior: + type: string + description: Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments. + example: close + enum: + - close + - roll + x-go-type: model.EndBehavior + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + can_pause: + type: boolean + description: The subscriber can pause a subscription. + example: false + can_resume: + type: boolean + description: The subscriber can resume a paused subscription. + example: false + can_cancel: + type: boolean + description: The subscriber can cancel a subscription. + example: false + base_price_percentage: + type: number + format: double + description: A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering. + example: 90 + minimum: 0 + maximum: 100 + nullable: true + fixed_price: + $ref: '#/components/schemas/NullablePrice' + BuildOffering: + required: + - name + - plans + - pricing_options + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + name: + type: string + description: The name of the offering. + minLength: 3 + maxLength: 1024 + example: Magazine + description: + type: string + description: The offering description to display to customers. + maxLength: 1024 + example: A lovely magazine that is published every month. + proration_policy_id: + type: string + description: The unique ID or external ref of the proration policy + example: 11111111-2222-3333-4444-555555555555 + configured_features: + $ref: '#/components/schemas/OfferingBuildConfiguredFeatures' + pricing_option_associations: + $ref: '#/components/schemas/OfferingBuildPricingOptionAssociations' + features: + type: array + description: Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering + minItems: 1 + items: + anyOf: + - $ref: '#/components/schemas/ExternalRef' + - $ref: '#/components/schemas/FeatureAttributes' + - $ref: '#/components/schemas/UUID' + plans: + type: array + description: Plan information to be created within the offering + minItems: 1 + items: + anyOf: + - $ref: '#/components/schemas/OfferingPlanAttributes' + pricing_options: + type: array + description: Pricing options information to be created within the offering + minItems: 1 + items: + $ref: '#/components/schemas/PricingOptionAttributes' + Offering: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionOfferingType' + attributes: + $ref: '#/components/schemas/OfferingResponseAttributes' + relationships: + $ref: '#/components/schemas/Relationships' + meta: + $ref: '#/components/schemas/OfferingMeta' + OfferingIncludes: + readOnly: true + properties: + features: + type: array + items: + $ref: '#/components/schemas/OfferingFeature' + plans: + type: array + items: + $ref: '#/components/schemas/OfferingPlan' + pricing_options: + type: array + items: + $ref: '#/components/schemas/OfferingPricingOption' + OfferingMeta: + readOnly: true + required: + - owner + - timestamps + - external_plan_refs + properties: + external_plan_refs: + type: array + items: + $ref: '#/components/schemas/OfferingPlanExternalRefMeta' + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/Timestamps' + OfferingCreate: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/SubscriptionOfferingType' + attributes: + $ref: '#/components/schemas/OfferingAttributes' + relationships: + $ref: '#/components/schemas/OfferingRelationships' + OfferingPlanUpdate: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionOfferingPlanType' + attributes: + $ref: '#/components/schemas/OfferingPlanUpdateAttributes' + FeatureConfigAccessAttributes: + description: Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. + required: + - type + properties: + type: + type: string + enum: + - access + example: access + FeatureConfigPromotionAttributes: + description: Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied. + required: + - type + - tag + properties: + type: + type: string + enum: + - promotion + example: promotion + tag: + $ref: '#/components/schemas/FeatureTag' + FeatureConfigUsageAttributes: + description: Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied. + required: + - type + - default_value + properties: + type: + type: string + enum: + - usage + example: usage + default_value: + type: integer + description: The default initial value + example: 10 + FeaturePlanConfiguration: + type: object + oneOf: + - $ref: '#/components/schemas/FeatureConfigAccessAttributes' + - $ref: '#/components/schemas/FeatureConfigPromotionAttributes' + - $ref: '#/components/schemas/FeatureConfigUsageAttributes' + discriminator: + propertyName: type + mapping: + access: '#/components/schemas/FeatureConfigAccessAttributes' + promotion: '#/components/schemas/FeatureConfigPromotionAttributes' + usage: '#/components/schemas/FeatureConfigUsageAttributes' + required: + - type + properties: + type: + description: The type of feature, one of access, promotion or usage. + enum: + - access + - promotion + - usage + example: access + x-go-type: string + FeaturePlanConfigurationUpdate: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/FeatureConfigAccessAttributes' + - $ref: '#/components/schemas/FeatureConfigPromotionAttributes' + - $ref: '#/components/schemas/FeatureConfigUsageAttributes' + discriminator: + propertyName: type + mapping: + access: '#/components/schemas/FeatureConfigAccessAttributes' + promotion: '#/components/schemas/FeatureConfigPromotionAttributes' + usage: '#/components/schemas/FeatureConfigUsageAttributes' + required: + - type + properties: + type: + description: The type of feature, one of access, promotion or usage. + enum: + - access + - promotion + - usage + example: access + x-go-type: string + OfferingBuildPlanPricingOptions: + type: array + items: + type: string + description: The unique ID or external ref of the pricing option + example: 11111111-2222-3333-4444-555555555555 + OfferingBuildPricingOptionAssociations: + type: object + description: A map of plans keyed by plan UUID or external_ref to a list of associated pricing options, similarly keyed. + additionalProperties: + $ref: '#/components/schemas/OfferingBuildPlanPricingOptions' + OfferingBuildConfiguredFeatures: + type: object + description: Map of feature configurations keyed by plan UUID or external_ref + additionalProperties: + $ref: '#/components/schemas/OfferingBuildPlanFeatures' + OfferingBuildPlanFeatures: + type: object + description: A map of configurations indicating which features are available for the plan + additionalProperties: + $ref: '#/components/schemas/FeaturePlanConfiguration' + OfferingFeatureUpdate: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionOfferingFeatureType' + attributes: + $ref: '#/components/schemas/FeatureUpdateAttributes' + OfferingFeature: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionOfferingFeatureType' + attributes: + $ref: '#/components/schemas/FeatureResponseAttributes' + relationships: + $ref: '#/components/schemas/Relationships' + meta: + $ref: '#/components/schemas/FeatureMeta' + OfferingPlan: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionOfferingPlanType' + attributes: + $ref: '#/components/schemas/OfferingPlanResponseAttributes' + relationships: + $ref: '#/components/schemas/Relationships' + meta: + $ref: '#/components/schemas/PlanMeta' + OfferingPricingOptionUpdate: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionOfferingPricingOptionType' + attributes: + $ref: '#/components/schemas/PricingOptionUpdateAttributes' + OfferingPricingOption: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionOfferingPricingOptionType' + attributes: + $ref: '#/components/schemas/PricingOptionResponseAttributes' + relationships: + $ref: '#/components/schemas/Relationships' + meta: + $ref: '#/components/schemas/OfferingPricingOptionMeta' + OfferingPricingOptionMeta: + readOnly: true + required: + - owner + - timestamps + properties: + prices: + $ref: '#/components/schemas/OfferingPricingOptionPrices' + price: + $ref: '#/components/schemas/Price' + display_price: + $ref: '#/components/schemas/DisplayPrice' + active_pricing_option: + $ref: '#/components/schemas/ActivePricingOption' + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/Timestamps' + OfferingPricingOptionPrices: + type: object + description: The price of each plan within the offering that this pricing option may be applied to. + readOnly: true + additionalProperties: + $ref: '#/components/schemas/OfferingPricingOptionPriceForPlan' + OfferingPricingOptionPriceForPlan: + readOnly: true + properties: + price: + $ref: '#/components/schemas/Price' + display_price: + $ref: '#/components/schemas/DisplayPrice' + OfferingFeatureAttach: + description: A list of feature IDs to attach to the offering. See [**List Features**](/docs/api/subscriptions/list-features). + required: + - features + properties: + features: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/UUID' + OfferingUpdate: + anyOf: + - required: + - attributes + - required: + - relationships + required: + - id + - type + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionOfferingType' + attributes: + $ref: '#/components/schemas/OfferingUpdateAttributes' + relationships: + $ref: '#/components/schemas/OfferingUpdateRelationships' + OfferingResponseAttributes: + allOf: + - $ref: '#/components/schemas/OfferingAttributes' + - $ref: '#/components/schemas/Timestamps' + OfferingAttributes: + required: + - name + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + name: + type: string + description: The name of the offering. + minLength: 3 + maxLength: 1024 + example: Magazine + description: + type: string + description: The offering description to display to customers. + maxLength: 1024 + example: A lovely magazine that is published every month. + OfferingUpdateAttributes: + properties: + external_ref: + $ref: '#/components/schemas/ExternalRefUpdate' + name: + type: string + description: The name of the offering. + minLength: 3 + maxLength: 1024 + example: Magazine + description: + type: string + description: The offering description to display to customers. + maxLength: 1024 + example: A lovely magazine that is published every month. + nullable: true + OfferingRelationships: + properties: + proration_policy: + $ref: '#/components/schemas/ProrationPolicyRelationshipAttributes' + OfferingUpdateRelationships: + properties: + proration_policy: + $ref: '#/components/schemas/ProrationPolicyUpdateRelationshipAttributes' + BuildSubscriptionOrder: + description: A subscription may optionally be associated with an item in an order by supplying both the order ID and the ID of the item within that order. + required: + - order_id + - order_item_id + properties: + order_id: + $ref: '#/components/schemas/UUID' + order_item_id: + $ref: '#/components/schemas/UUID' + BuildSubscription: + required: + - account_id + - currency + - name + - email + - manual_payments + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + account_id: + $ref: '#/components/schemas/UUID' + address_id: + $ref: '#/components/schemas/UUID' + offering_external_ref: + $ref: '#/components/schemas/ExternalRef' + offering_id: + $ref: '#/components/schemas/UUID' + plan_id: + $ref: '#/components/schemas/UUID' + pricing_option_id: + $ref: '#/components/schemas/UUID' + currency: + $ref: '#/components/schemas/CurrencyIdentifier' + payment_authority: + $ref: '#/components/schemas/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 + first_invoice_paid: + type: boolean + description: Indicates that payment for the first billing period of the subscription has already been taken. As well as creating the subscription a settled invoice is created to cover the first period. + example: false + started_at: + description: When importing an active subscription from an existing system you can specify the date and time of the start of the most recent period. This may only be supplied when `first_invoice_paid` is true. As well as creating the subscription a settled invoice is created to cover the correct billing period. + type: string + example: '2017-01-10T11:41:19.244842Z' + offering: + $ref: '#/components/schemas/OfferingAttributes' + features: + type: array + description: Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering + minItems: 1 + items: + anyOf: + - $ref: '#/components/schemas/ExternalRef' + - $ref: '#/components/schemas/FeatureAttributes' + - $ref: '#/components/schemas/UUID' + plans: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/PlanAttributesAndSelectedMeta' + pricing_options: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/PricingOptionAttributesAndSelectedMeta' + configured_features: + $ref: '#/components/schemas/OfferingBuildConfiguredFeatures' + pricing_option_associations: + $ref: '#/components/schemas/OfferingBuildPricingOptionAssociations' + selected_plan: + $ref: '#/components/schemas/ExternalRef' + selected_pricing_option: + $ref: '#/components/schemas/ExternalRef' + order: + $ref: '#/components/schemas/BuildSubscriptionOrder' + meta: + $ref: '#/components/schemas/SubscriptionMeta' + PricingOptionAttributesAndSelectedMeta: + allOf: + - $ref: '#/components/schemas/PricingOptionAttributes' + - $ref: '#/components/schemas/SelectedMeta' + PlanAttributesAndSelectedMeta: + allOf: + - $ref: '#/components/schemas/PlanAttributes' + - $ref: '#/components/schemas/SelectedMeta' + SelectedMeta: + properties: + meta: + $ref: '#/components/schemas/SelectedMetaAttributes' + SelectedMetaAttributes: + properties: + selected: + type: boolean + example: true + description: One item must be selected for use in the subscription + Subscription: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionType' + attributes: + $ref: '#/components/schemas/SubscriptionAttributes' + relationships: + $ref: '#/components/schemas/Relationships' + meta: + $ref: '#/components/schemas/SubscriptionMeta' + ManageSubscriptionPlans: + type: object + required: + - type + - plans + properties: + type: + type: string + enum: + - detach + example: detach + x-go-type: model.ManagePlansAction + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + plans: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/UUID' + SubscriptionUpdate: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionType' + attributes: + $ref: '#/components/schemas/SubscriptionUpdateAttributes' + SubscriptionUpdateAttributes: + properties: + pricing_option_id: + x-go-type: uuid.UUID + x-go-type-import: + name: uuid + path: github.com/google/uuid + example: 00000000-0000-0000-0000-000000000001 + 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: + plans: + type: array + items: + $ref: '#/components/schemas/OfferingPlan' + pricing_options: + type: array + items: + $ref: '#/components/schemas/OfferingPricingOption' + SubscriptionMeta: + readOnly: true + required: + - owner + - timestamps + - status + - canceled + - paused + - closed + - pending + - suspended + - invoice_after + - manual_payments + - first_invoice_prepaid + properties: + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/SubscriptionTimestamps' + status: + $ref: '#/components/schemas/Status' + state: + $ref: '#/components/schemas/SubscriptionState' + manual_payments: + $ref: '#/components/schemas/ManualPayments' + first_invoice_prepaid: + type: boolean + description: Indicates that the first billing period of this subscription was paid for outside of the subscriptions service. + example: false + canceled: + type: boolean + description: Whether a subscription is canceled or not. + example: true + paused: + type: boolean + description: Whether a subscription is paused or not. + example: true + closed: + type: boolean + description: Whether a subscription is closed or not. + example: true + suspended: + type: boolean + description: Whether a subscription is suspended or not. + example: false + pending: + type: boolean + description: Whether a subscription is pending activation or not. + example: false + invoice_after: + description: The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point. + type: string + example: '2017-01-10T11:41:19.244842Z' + SubscriptionTimestamps: + allOf: + - $ref: '#/components/schemas/Timestamps' + - properties: + canceled_at: + description: The date and time a subscription was cancelled. + type: string + example: '2017-01-10T11:41:19.244842Z' + paused_at: + description: The date and time a subscription was paused. + type: string + example: '2017-01-10T11:41:19.244842Z' + resumed_at: + description: The date and time a subscription was resumed. + type: string + example: '2017-01-10T11:41:19.244842Z' + end_date: + description: | + The date and time a subscription will end. + - If the subscription offering pricing option end behavior is `close`, `end_date` is set to the billing period end date upon subscription creation. + - If the subscription offering pricing option end behavior is "roll": `end_date` is set to the billing period end date when the subscription is cancelled. + type: string + example: '2017-01-10T11:41:19.244842Z' + go_live_after: + description: The date and time a subscription will go live and become active. + type: string + example: '2017-01-10T11:41:19.244842Z' + go_live: + description: The date and time a subscription was released from the pending state and made active. + type: string + example: '2017-01-10T11:41:19.244842Z' + SubscriptionAttributes: + required: + - account_id + - pricing_option_id + - plan_id + - offering + - currency + - name + - email + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + account_id: + $ref: '#/components/schemas/UUID' + address_id: + $ref: '#/components/schemas/UUID' + offering: + $ref: '#/components/schemas/Offering' + pricing_option_id: + $ref: '#/components/schemas/UUID' + plan_id: + $ref: '#/components/schemas/UUID' + currency: + $ref: '#/components/schemas/CurrencyIdentifier' + payment_authority: + $ref: '#/components/schemas/PaymentAuthority' + ChangeState: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/SubscriptionStateType' + attributes: + $ref: '#/components/schemas/SubscriptionStateAttributes' + SubscriptionStateAttributes: + required: + - action + properties: + action: + $ref: '#/components/schemas/SubscriptionStateAction' + SubscriptionStateType: + type: string + description: This represents the type of resource object being returned. Always `subscription_state`. + example: subscription_state + enum: + - subscription_state + SubscriptionStateAction: + type: string + description: | + The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. + + A subscription can have the following states; `canceled`, `paused`, or `resumed`. + + See [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle). + example: cancel + enum: + - cancel + - pause + - resume + - pending + x-go-type: model.SubscriptionAction + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + StateMeta: + readOnly: true + required: + - created_at + properties: + created_at: + description: The date and time a resource was created. + type: string + example: '2017-01-10T11:41:19.244842Z' + SubscriptionState: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionStateType' + attributes: + $ref: '#/components/schemas/SubscriptionStateAttributes' + meta: + $ref: '#/components/schemas/StateMeta' + ManualPayments: + type: boolean + example: false + default: false + description: When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments). + PaymentAuthority: + type: object + oneOf: + - $ref: '#/components/schemas/PaymentAuthorityEPPayments' + - $ref: '#/components/schemas/PaymentAuthorityStripe' + - $ref: '#/components/schemas/PaymentAuthorityAuthorizeNet' + discriminator: + propertyName: type + mapping: + elastic_path_payments_stripe: '#/components/schemas/PaymentAuthorityEPPayments' + stripe_payment_intents: '#/components/schemas/PaymentAuthorityStripe' + authorize_net: '#/components/schemas/PaymentAuthorityAuthorizeNet' + required: + - type + properties: + type: + description: The name of the payment gateway facilitating the secure transmission of payment data. + type: string + example: elastic_path_payments_stripe + enum: + - authorize_net + - elastic_path_payments_stripe + - stripe_payment_intents + x-go-type: paymentgateways.GatewayName + x-go-type-import: + name: paymentgateways + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways + NullablePaymentAuthority: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/PaymentAuthorityEPPayments' + - $ref: '#/components/schemas/PaymentAuthorityStripe' + - $ref: '#/components/schemas/PaymentAuthorityAuthorizeNet' + discriminator: + propertyName: type + mapping: + elastic_path_payments_stripe: '#/components/schemas/PaymentAuthorityEPPayments' + stripe_payment_intents: '#/components/schemas/PaymentAuthorityStripe' + authorize_net: '#/components/schemas/PaymentAuthorityAuthorizeNet' + required: + - type + properties: + type: + description: The name of the payment gateway facilitating the secure transmission of payment data. + type: string + example: elastic_path_payments_stripe + enum: + - authorize_net + - elastic_path_payments_stripe + - stripe_payment_intents + x-go-type: paymentgateways.GatewayName + x-go-type-import: + name: paymentgateways + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways + PaymentAuthorityAuthorizeNet: + type: object + required: + - type + properties: + type: + description: The name of the payment gateway facilitating the secure transmission of payment data. + type: string + example: authorize_net + enum: + - authorize_net + x-go-type: paymentgateways.GatewayName + x-go-type-import: + name: paymentgateways + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways + payment_profile_id: + description: The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription. + type: string + minLength: 3 + maxLength: 1024 + example: '1511660856' + customer_profile_id: + description: The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription. + type: string + minLength: 3 + maxLength: 1024 + example: '1511736979' + PaymentAuthorityEPPayments: + writeOnly: true + type: object + required: + - type + properties: + type: + description: The name of the payment gateway facilitating the secure transmission of payment data. + type: string + example: elastic_path_payments_stripe + enum: + - elastic_path_payments_stripe + x-go-type: paymentgateways.GatewayName + x-go-type-import: + name: paymentgateways + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways + customer_id: + description: The unique identifier for a customer. + type: string + minLength: 3 + maxLength: 1024 + example: cus_OPfKlxWV3hp9h6 + card_id: + description: The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines). + type: string + minLength: 3 + maxLength: 1024 + example: card_8Diw3FQPhxK27WADPVMeXieP + PaymentAuthorityStripe: + writeOnly: true + type: object + required: + - type + properties: + type: + description: The name of the payment gateway facilitating the secure transmission of payment data. + type: string + example: stripe_payment_intents + enum: + - stripe_payment_intents + x-go-type: paymentgateways.GatewayName + x-go-type-import: + name: paymentgateways + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways + customer_id: + description: The unique identifier for a customer. + type: string + minLength: 3 + maxLength: 1024 + example: cus_OPfKlxWV3hp9h6 + card_id: + description: The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines). + type: string + minLength: 3 + maxLength: 1024 + example: card_8Diw3FQPhxK27WADPVMeXieP + Import: + required: + - type + - meta + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionImportType' + attributes: + $ref: '#/components/schemas/ImportAttributes' + meta: + $ref: '#/components/schemas/ImportMeta' + ImportAttributes: + required: + - status + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + status: + type: string + description: | + The status of job. + - **pending** - Commerce has received the request but is currently busy processing other requests. + - **started** - Commerce has started processing the job. + - **success** - The job has successfully completed. + - **failed** - The job has failed. + enum: + - pending + - started + - success + - failed + example: pending + x-go-type: model.JobStatus + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + ImportMeta: + readOnly: true + required: + - owner + - timestamps + - records + properties: + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/JobTimestamps' + records: + $ref: '#/components/schemas/ImportRecords' + ImportRecords: + type: object + description: You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported into Subscriptions. However, this does not mean they are valid subscription objects, only that they have the correct type and their JSON format is properly formatted. Imported shows the number of records that have been both validated and successfully added to Subscriptions. + required: + - uploaded + - imported + properties: + uploaded: + type: object + properties: + subscription_feature: + description: The total number of features uploaded. + type: integer + example: 50000 + subscription_subscriber: + description: The total number of subscribers uploaded. + type: integer + example: 50000 + subscription_offering: + description: The total number of offerings uploaded. + type: integer + example: 50000 + subscription: + description: The total number of subscriptions uploaded. + type: integer + example: 50000 + required: + - subscription_feature + - subscription_subscriber + - subscription_offering + - subscription + imported: + properties: + subscription_feature: + description: The total number of features uploaded. + type: integer + example: 50000 + subscription_subscriber: + description: The total number of subscribers imported. + type: integer + example: 45090 + subscription_offering: + description: The total number of offerings imported. + type: integer + example: 45090 + subscription: + description: The total number of subscriptions imported. + type: integer + example: 45090 + required: + - subscription_feature + - subscription_subscriber + - subscription_offering + - subscription + Job: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionJobType' + attributes: + $ref: '#/components/schemas/JobResponseAttributes' + relationships: + $ref: '#/components/schemas/Relationships' + meta: + $ref: '#/components/schemas/JobMeta' + JobMeta: + readOnly: true + required: + - owner + - timestamps + properties: + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/JobTimestamps' + report: + $ref: '#/components/schemas/JobReport' + JobReport: + description: You can track your Subscriptions billing, tax, and payment operations using reports. + oneOf: + - $ref: '#/components/schemas/BillingRunReport' + - $ref: '#/components/schemas/TaxRunReport' + - $ref: '#/components/schemas/PaymentRunReport' + 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' + relationships: + $ref: '#/components/schemas/Relationships' + meta: + $ref: '#/components/schemas/SubscriptionInvoiceMeta' + UpdateInvoicePayment: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionInvoicePaymentType' + attributes: + $ref: '#/components/schemas/UpdateInvoicePaymentAttributes' + UpdateInvoicePaymentAttributes: + required: + - success + properties: + success: + type: boolean + example: true + description: Whether the payment was successful. + external_payment_id: + type: string + maxLength: 1024 + example: 33e7ec6b-8b34-4c92-a95b-2e2647922e47 + description: An optional external ID that is specific to the gateway used. + failure_detail: + description: A message generated by an external payment method that describes why a payment fails. + type: string + example: Card Failure + payment_taken_at: + description: The date and time the invoice payment was taken at. + type: string + example: '2017-01-10T11:41:19.244842Z' + SubscriptionInvoicePayment: + required: + - id + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionInvoicePaymentType' + attributes: + $ref: '#/components/schemas/SubscriptionInvoicePaymentAttributes' + meta: + $ref: '#/components/schemas/SubscriptionInvoicePaymentMeta' + SubscriptionInvoiceMeta: + readOnly: true + required: + - owner + - timestamps + - proration_events + 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_pricing_option + - new_pricing_option_cost + - prorated_at + properties: + proration_policy_id: + $ref: '#/components/schemas/UUID' + billing_cost_before_proration: + type: integer + format: int64 + description: The value as a whole number of the currency's smallest subdivision + example: 100 + refunded_amount_for_unused_pricing_option: + type: integer + format: int64 + description: The value as a whole number of the currency's smallest subdivision. + example: 100 + new_pricing_option_cost: + type: integer + format: int64 + description: The value as a whole number of the currency's smallest subdivision. + example: 100 + prorated_at: + description: The date and time the subscription was prorated. + type: string + example: '2017-01-10T11:41:19.244842Z' + InvoiceTimestamps: + allOf: + - $ref: '#/components/schemas/Timestamps' + - properties: + taxes_added_at: + description: The date and time taxes were added to an invoice. + type: string + example: '2017-01-10T11:41:19.244842Z' + SubscriptionInvoicePaymentMeta: + readOnly: true + required: + - owner + - timestamps + - invoice_id + - subscription_id + - job_id + - manual_payment + properties: + owner: + $ref: '#/components/schemas/OwnerMeta' + subscription_id: + $ref: '#/components/schemas/UUID' + invoice_id: + $ref: '#/components/schemas/UUID' + job_id: + $ref: '#/components/schemas/UUID' + timestamps: + $ref: '#/components/schemas/InvoicePaymentTimestamps' + manual_payment: + type: boolean + example: false + description: Whether manual payments are enabled or the payment will be handled by the configured gateway. + InvoicePaymentTimestamps: + allOf: + - $ref: '#/components/schemas/Timestamps' + - properties: + payment_taken_at: + description: The date and time a payment was taken. + type: string + example: '2017-01-10T11:41:19.244842Z' + SubscriptionInvoiceAttributes: + required: + - billing_period + - pro_forma + - invoice_items + - outstanding + - tax_required + - payment_retries_limit_reached + - manual_payment_pending + properties: + billing_period: + $ref: '#/components/schemas/TimePeriod' + invoice_items: + type: array + items: + $ref: '#/components/schemas/SubscriptionInvoiceItem' + tax_items: + type: array + items: + $ref: '#/components/schemas/TaxItem' + outstanding: + type: boolean + description: The invoice still requires payment if `true`. + example: true + number: + type: integer + description: A sequential number assigned by the billing run. + example: 1 + tax_required: + type: boolean + description: Whether tax is required for this invoice. + example: true + payment_retries_limit_reached: + type: boolean + description: Whether the limit of payment retries has been reached. + example: false + updated_at: + description: The date and time an invoice was updated. + type: string + example: '2017-01-10T11:41:19.244842Z' + created_at: + description: The date and time an invoice was created. + type: string + example: '2017-01-10T11:41:19.244842Z' + pro_forma: + description: | + Whether the invoice is a Pro Forma invoice (generated ahead of payment) or not. + + Pro Forma Invoices are created ahead of payment time (for example, a week in advance of payment so + you can notify customers) and will not be picked up by a payment run until on or after their valid_from + date. + type: boolean + example: false + valid_from: + description: | + The date and time at which an invoice will be valid from. + + If generated with no lead time then the invoice will be valid immediately. + + If generated with a lead time, then the valid_from will be the data at which the Invoice transitions from + it's Pro Forma state to one that can have payment taken. + type: string + example: '2017-01-10T11:41:19.244842Z' + manual_payment_pending: + type: boolean + description: Whether there is a manual pending payment pending on the invoice. + example: true + SubscriptionInvoicePaymentAttributes: + required: + - success + - amount + - gateway + properties: + success: + type: boolean + example: true + description: Whether the payment was successful. + pending: + type: boolean + example: true + description: Whether the payment is pending (only for manual payments). + gateway: + type: string + maxLength: 1024 + example: elastic_path_payments_stripe + description: Specifies the payment gateway. + external_payment_id: + type: string + maxLength: 1024 + example: 33e7ec6b-8b34-4c92-a95b-2e2647922e47 + description: An optional external ID that is specific to the gateway used. + failure_detail: + $ref: '#/components/schemas/PaymentFailureDetail' + amount: + $ref: '#/components/schemas/SingleCurrencyPrice' + PaymentFailureDetail: + type: object + description: The reason the payment failed. + properties: + reason: + type: string + example: Card Failure + SubscriptionInvoiceItem: + required: + - description + - price + properties: + description: + type: string + description: A description of the subscribed item. + example: Magazine issue + price: + $ref: '#/components/schemas/SingleCurrencyPrice' + plan_id: + $ref: '#/components/schemas/UUID' + from_time_period: + description: The start date and time of the billing period in this price + type: string + example: '2017-01-10T11:41:19.244842Z' + until_time_period: + description: The end date and time of the billing period in this price + type: string + example: '2017-01-10T11:41:19.244842Z' + ErrorResponse: + required: + - errors + properties: + errors: + type: array + items: + $ref: '#/components/schemas/Error' + Error: + required: + - status + - title + properties: + status: + type: string + description: The HTTP response code of the error. + example: '500' + title: + type: string + description: A brief summary of the error. + example: Internal server error + detail: + type: string + description: Optional additional detail about the error. + example: An internal error has occurred. + meta: + type: object + description: Additional supporting meta data for the error. + example: + missing_ids: + - e7d50bd5-1833-43c0-9848-f9d325b08be8 + CurrencyIdentifier: + type: string + description: The three-letter [**ISO currency code**](https://www.iso.org/iso-4217-currency-codes.html) in uppercase. + maxLength: 1024 + example: USD + UUID: + type: string + description: The unique identifier. + x-go-type: uuid.UUID + x-go-type-import: + name: uuid + path: github.com/google/uuid + example: 11111111-2222-3333-4444-555555555555 + OwnerMeta: + readOnly: true + type: string + format: string + description: The owner of a resource, either `store` or `organization`. + example: store + OfferingPlanExternalRefMeta: + readOnly: true + type: string + format: string + description: The offerings plan external_ref value + example: 97dddc65-eabd-45d8-b45b-2ece5cfc8c50 + Subscriber: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionSubscriberType' + attributes: + $ref: '#/components/schemas/SubscriberResponseAttributes' + meta: + $ref: '#/components/schemas/SubscriberMeta' + SubscriberMeta: + readOnly: true + required: + - owner + - timestamps + properties: + feature_entitlements: + type: array + description: A list of entitlement tags currently active for the subscriber + example: + - tag1 + - tag2 + items: + $ref: '#/components/schemas/FeatureTag' + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/Timestamps' + SubscriptionSubscriberType: + type: string + example: subscription_subscriber + enum: + - subscription_subscriber + SubscriberResponseAttributes: + allOf: + - $ref: '#/components/schemas/SubscriberAttributes' + - $ref: '#/components/schemas/Timestamps' + SubscriberAttributes: + required: + - name + - email + - account_id + properties: + account_id: + $ref: '#/components/schemas/UUID' + name: + type: string + description: The name of the subscriber. + minLength: 3 + maxLength: 1024 + example: John Doe + email: + type: string + format: email + description: The email of the subscriber. + minLength: 3 + maxLength: 1024 + example: john.doe@example.com + x-go-type: types.Email + x-go-type-import: + name: email + path: github.com/oapi-codegen/runtime/types + payment_authority: + $ref: '#/components/schemas/PaymentAuthority' + SubscriberUpdateAttributes: + properties: + name: + type: string + description: The name of the subscriber. + minLength: 3 + maxLength: 1024 + example: John Doe + email: + type: string + format: email + description: The email of the subscriber. + minLength: 3 + maxLength: 1024 + example: john.doe@example.com + x-go-type: types.Email + x-go-type-import: + name: email + path: github.com/oapi-codegen/runtime/types + payment_authority: + $ref: '#/components/schemas/NullablePaymentAuthority' + SubscriberCreate: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/SubscriptionSubscriberType' + attributes: + $ref: '#/components/schemas/SubscriberAttributes' + SubscriberUpdate: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionSubscriberType' + attributes: + $ref: '#/components/schemas/SubscriberUpdateAttributes' + ScheduleCreate: + required: + - type + - attributes + properties: + type: + $ref: '#/components/schemas/SubscriptionScheduleType' + attributes: + $ref: '#/components/schemas/ScheduleAttributes' + Schedule: + required: + - type + - attributes + - meta + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionScheduleType' + attributes: + $ref: '#/components/schemas/ScheduleResponseAttributes' + meta: + $ref: '#/components/schemas/ScheduleMeta' + ScheduleMeta: + readOnly: true + required: + - owner + - timestamps + properties: + scheduled_for: + type: string + format: date-time + example: '2017-07-21T17:32:28Z' + owner: + $ref: '#/components/schemas/OwnerMeta' + timestamps: + $ref: '#/components/schemas/Timestamps' + SubscriptionScheduleType: + type: string + example: subscription_schedule + enum: + - subscription_schedule + ScheduleResponseAttributes: + allOf: + - $ref: '#/components/schemas/ScheduleAttributes' + - $ref: '#/components/schemas/Timestamps' + ScheduleAttributes: + required: + - specification + - location + - job + properties: + external_ref: + $ref: '#/components/schemas/ExternalRef' + name: + type: string + description: The name of the schedule. + minLength: 3 + maxLength: 1024 + example: Daily billing run. + specification: + type: string + description: A cron-style specification of when the jobs should be created. See [**Schedules**](/docs/api/subscriptions/schedules). + maxLength: 1024 + example: 30 0 * * * + location: + type: string + description: The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339). + maxLength: 1024 + example: Europe/London + job: + $ref: '#/components/schemas/ScheduleJob' + ScheduleUpdateAttributes: + properties: + external_ref: + $ref: '#/components/schemas/ExternalRefUpdate' + name: + type: string + description: The name of the schedule. + minLength: 3 + maxLength: 1024 + example: Daily billing run. + nullable: true + specification: + type: string + description: A cron-style specification of when the jobs should be created. + maxLength: 1024 + example: 30 0 * * * + location: + type: string + description: The location of the time zone that the schedule operates in. + maxLength: 1024 + example: Europe/London + job: + $ref: '#/components/schemas/ScheduleJob' + ScheduleJob: + required: + - job_type + properties: + job_type: + $ref: '#/components/schemas/JobType' + ScheduleUpdate: + required: + - id + - type + - attributes + properties: + id: + $ref: '#/components/schemas/UUID' + type: + $ref: '#/components/schemas/SubscriptionScheduleType' + attributes: + $ref: '#/components/schemas/ScheduleUpdateAttributes' + LeadTime: + type: object + description: Configuration of the lead time to generate an invoice ahead of time in a pro-forma state + properties: + type: + type: string + description: The unit of time that lead time is measured in. + example: day + enum: + - day + - week + x-go-type: model.LeadTimeType + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + time: + type: integer + description: The lead time to generate an invoice ahead of time in a pro-forma state + example: 14 + minimum: 1 + required: + - type + - time + NullableLeadTime: + type: object + description: Configuration of the lead time to generate an invoice ahead of time in a pro-forma state + nullable: true + properties: + type: + type: string + description: The unit of time that lead time is measured in. + example: week + enum: + - day + - week + x-go-type: model.LeadTimeType + x-go-type-import: + name: model + path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model + time: + type: integer + description: The lead time to generate an invoice ahead of time in a pro-forma state + example: 14 + minimum: 1 + required: + - type + - time diff --git a/external/resources/yaml/carts-and-orders.yaml b/external/resources/yaml/carts-and-orders.yaml index fa080f2..3e9bc5b 100644 --- a/external/resources/yaml/carts-and-orders.yaml +++ b/external/resources/yaml/carts-and-orders.yaml @@ -141,6 +141,26 @@ cart-product-items: location: type: RESOURCE_ID:mli-inventory-locations alias_attribute: slug +cart-subscription-items: + singular-name: "cart-subscription-item" + json-api-type: "subscription_item" + json-api-format: "legacy" + docs: "https://elasticpath.dev/docs/api/carts/manage-carts#add-subscription-item-to-cart" + create-entity: + docs: "https://elasticpath.dev/docs/api/carts/manage-carts#add-subscription-item-to-cart" + url: "/v2/carts/{carts}/items" + openapi-operation-id: manageCarts + content-type: application/json + attributes: + id: + type: RESOURCE_ID:subscription-offerings + quantity: + type: INT + autofill: VALUE:1 + subscription_configuration.plan: + type: STRING + subscription_configuration.pricing_option: + type: STRING cart-custom-items: singular-name: "cart-custom-item" json-api-type: "custom_item" diff --git a/external/resources/yaml/misc.yaml b/external/resources/yaml/misc.yaml index bebbb1b..6eed482 100644 --- a/external/resources/yaml/misc.yaml +++ b/external/resources/yaml/misc.yaml @@ -121,12 +121,15 @@ settings: get-collection: docs: "https://elasticpath.dev/docs/api/settings/get-v-2-settings" url: "/v2/settings" + openapi-operation-id: get-v2-settings get-entity: docs: "https://elasticpath.dev/docs/api/settings/get-v-2-settings" url: "/v2/settings" + openapi-operation-id: get-v2-settings update-entity: docs: "https://elasticpath.dev/docs/api/settings/put-v-2-settings" url: "/v2/settings" + openapi-operation-id: put-v2-settings attributes: page_length: type: STRING @@ -158,12 +161,15 @@ cart-settings: get-collection: docs: "https://elasticpath.dev/docs/api/settings/get-v-2-settings-cart" url: "/v2/settings/cart" + openapi-operation-id: get-v2-settings-cart get-entity: docs: "https://elasticpath.dev/docs/api/settings/get-v-2-settings-cart" url: "/v2/settings/cart" + openapi-operation-id: get-v2-settings-cart update-entity: docs: "https://elasticpath.dev/docs/api/settings/get-v-2-settings-cart" url: "/v2/settings/cart" + openapi-operation-id: put-v2-settings-cart attributes: cart_expiry_days: type: INT diff --git a/external/resources/yaml/promotions.yaml b/external/resources/yaml/promotions.yaml index 3ca7c6c..11f3e01 100644 --- a/external/resources/yaml/promotions.yaml +++ b/external/resources/yaml/promotions.yaml @@ -151,14 +151,14 @@ rule-promotions: rule_set.rules.strategy: type: ENUM:account_tags,cart_total,cart_custom_attribute,item_price,item_sku,item_product_id,item_quantity,item_category,item_attribute,item_identifier,items_bundle,and,or rule_set.rules.operator: - type: ENUM:in,nin,eq,lt,lte,gt,gte,range - usage: "The strategies cart_total, item_price, and item_quantity support the operators [gt, lt, gte, lte, eq]. Strategies cart_custom_attribute, item_sku, item_product_id, item_identifier, item_category, and item_attribute support the operators [in, nin]." + type: ENUM:in,nin,eq,lt,lte,gt,gte,range,contains_all,contains_any,not_contains_any,not_contains_all + usage: "The strategies cart_total, item_price, and item_quantity support the operators [gt, lt, gte, lte, eq]. Strategies cart_custom_attribute, item_sku, item_product_id, item_identifier, item_category, and item_attribute support the operators [in, nin]. Strategy account_tags supports the operators [contains_all, contains_any, not_contains_any, not_contains_all]." rule_set.rules.args[n]: type: STRING rule_set.rules.children[n].strategy: type: ENUM:account_tags,cart_total,cart_custom_attribute,item_price,item_sku,item_product_id,item_quantity,item_category,item_attribute,item_identifier,items_bundle,and,or rule_set.rules.children[n].operator: - type: ENUM:in,nin,eq,lt,lte,gt,gte + type: ENUM:in,nin,eq,lt,lte,gt,gte,contains_all,contains_any,not_contains_any,not_contains_all rule_set.rules.children[n].args[n]: type: STRING rule_set.catalog_ids[n]: diff --git a/external/resources/yaml/resources_yaml_test.go b/external/resources/yaml/resources_yaml_test.go index 9cfc2b6..356c890 100644 --- a/external/resources/yaml/resources_yaml_test.go +++ b/external/resources/yaml/resources_yaml_test.go @@ -35,7 +35,7 @@ func TestExpectedNumberOfResources(t *testing.T) { resourceCount := len(resources.GetPluralResources()) // Verification - require.Equal(t, resourceCount, 140) + require.Equal(t, resourceCount, 159) } func TestCreatedByTemplatesAllReferenceValidResource(t *testing.T) { diff --git a/external/resources/yaml/subscriptions.yaml b/external/resources/yaml/subscriptions.yaml index 39af598..a373326 100644 --- a/external/resources/yaml/subscriptions.yaml +++ b/external/resources/yaml/subscriptions.yaml @@ -1,106 +1,3 @@ -#subscription-products: -# docs: "https://elasticpath.dev/docs/api/subscriptions/products" -# json-api-type: subscription_product -# json-api-format: compliant -# singular-name: subscription-product -# get-collection: -# docs: "https://elasticpath.dev/docs/api/subscriptions/list-products" -# url: /v2/subscriptions/products -# get-entity: -# docs: "https://elasticpath.dev/docs/api/subscriptions/get-product" -# url: /v2/subscriptions/products/{subscription_products} -# create-entity: -# docs: "https://elasticpath.dev/docs/api/subscriptions/create-product" -# url: /v2/subscriptions/products -# update-entity: -# docs: "https://elasticpath.dev/docs/api/subscriptions/update-product" -# url: /v2/subscriptions/products/{subscription_products} -# delete-entity: -# docs: "https://elasticpath.dev/docs/api/subscriptions/delete-product" -# url: /v2/subscriptions/products/{subscription_products} -# attributes: -# ^price\.([a-zA-Z0-9-_]+)\.amount$: -# type: INT -# ^price\.([a-zA-Z0-9-_]+)\.includes_tax$: -# type: BOOL -# description: -# type: STRING -# autofill: VALUE:Auto Generated -# external_ref: -# type: STRING -# main_image: -# type: STRING -# name: -# type: STRING -# autofill: FUNC:Name -# price_units.amount: -# type: INT -# price_units.unit: -# type: ENUM:day,month -# sku: -# type: STRING -#subscription-plans: -# docs: "https://elasticpath.dev/docs/api/subscriptions/plans" -# json-api-type: subscription_plan -# json-api-format: compliant -# singular-name: subscription-plan -# get-collection: -# docs: "https://elasticpath.dev/docs/api/subscriptions/list-plans" -# url: /v2/subscriptions/plans -# get-entity: -# docs: "https://elasticpath.dev/docs/api/subscriptions/get-plan" -# url: /v2/subscriptions/plans/{subscription_plans} -# create-entity: -# docs: "https://elasticpath.dev/docs/api/subscriptions/create-plan" -# url: /v2/subscriptions/plans -# update-entity: -# docs: "https://elasticpath.dev/docs/api/subscriptions/update-plan" -# url: /v2/subscriptions/plans/{subscription_plans} -# delete-entity: -# docs: "https://elasticpath.dev/docs/api/subscriptions/delete-plan" -# url: /v2/subscriptions/plans/{subscription_plans} -# attributes: -# ^fixed_price\.(USD|[a-zA-Z0-9-_]+)\.amount$: -# type: INT -# ^fixed_price\.(USD|[a-zA-Z0-9-_]+)\.includes_tax$: -# type: BOOL -# billing_day: -# type: INT -# billing_frequency: -# type: INT -# autofill: VALUE:1 -# billing_interval_type: -# type: ENUM:day,week,month,year -# autofill: VALUE:day -# billing_month_day: -# type: INT -# can_cancel: -# type: BOOL -# autofill: VALUE:true -# can_pause: -# type: BOOL -# autofill: VALUE:true -# can_resume: -# type: BOOL -# autofill: VALUE:true -# description: -# type: STRING -# autofill: VALUE:Auto Generated -# end_behavior: -# type: ENUM:close,roll -# autofill: VALUE:close -# external_ref: -# type: STRING -# name: -# type: STRING -# autofill: FUNC:Name -# plan_length: -# type: INT -# autofill: VALUE:1 -# status: -# type: ENUM:active,draft,archive -# trial_period: -# type: INT subscription-offerings: docs: "https://elasticpath.dev/docs/api/subscriptions/offerings" json-api-type: subscription_offering @@ -109,18 +6,35 @@ subscription-offerings: get-collection: docs: "https://elasticpath.dev/docs/api/subscriptions/create-offering" url: /v2/subscriptions/offerings + openapi-operation-id: ListOfferings + query: + - name: filter + type: STRING + - name: page[offset] + type: INT + - name: page[limit] + type: INT + - name: include + type: STRING get-entity: docs: "https://elasticpath.dev/docs/api/subscriptions/get-offering" url: /v2/subscriptions/offerings/{subscription_offerings} + openapi-operation-id: GetOffering + query: + - name: include + type: STRING create-entity: docs: "https://elasticpath.dev/docs/api/subscriptions/create-offering" url: /v2/subscriptions/offerings + openapi-operation-id: CreateOffering update-entity: docs: "https://elasticpath.dev/docs/api/subscriptions/update-offering" url: /v2/subscriptions/offerings/{subscription_offerings} + openapi-operation-id: UpdateOffering delete-entity: docs: "https://elasticpath.dev/docs/api/subscriptions/delete-offering" url: /v2/subscriptions/offerings/{subscription_offerings} + openapi-operation-id: DeleteOffering attributes: description: type: STRING @@ -144,22 +58,673 @@ subscription-proration-policies: get-collection: docs: "https://elasticpath.dev/docs/api/subscriptions/list-proration-policies" url: /v2/subscriptions/proration-policies + openapi-operation-id: ListProrationPolicies + query: + - name: page[offset] + type: INT + - name: page[limit] + type: INT get-entity: docs: "https://elasticpath.dev/docs/api/subscriptions/get-proration-policy" url: /v2/subscriptions/proration-policies/{subscription_proration_policies} + openapi-operation-id: GetProrationPolicy create-entity: docs: "https://elasticpath.dev/docs/api/subscriptions/create-proration-policy" url: /v2/subscriptions/proration-policies + openapi-operation-id: CreateProrationPolicy update-entity: docs: "https://elasticpath.dev/docs/api/subscriptions/update-proration-policy" url: /v2/subscriptions/proration-policies/{subscription_proration_policies} + openapi-operation-id: UpdateProrationPolicy delete-entity: docs: "https://elasticpath.dev/docs/api/subscriptions/delete-proration-policy" url: /v2/subscriptions/proration-policies/{subscription_proration_policies} + openapi-operation-id: DeleteProrationPolicy attributes: external_ref: type: STRING name: type: STRING + autofill: FUNC:Company rounding: type: ENUM:up,down,nearest +subscription-features: + docs: "https://elasticpath.dev/docs/api/subscriptions/features" + json-api-type: subscription_feature + json-api-format: compliant + singular-name: subscription-feature + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-features" + url: /v2/subscriptions/features + openapi-operation-id: ListFeatures + query: + - name: filter + type: STRING + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-feature" + url: /v2/subscriptions/features/{subscription_features} + openapi-operation-id: GetFeature + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-feature" + url: /v2/subscriptions/features + openapi-operation-id: CreateFeature + update-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/update-feature" + url: /v2/subscriptions/features/{subscription_features} + openapi-operation-id: UpdateFeature + delete-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/delete-feature" + url: /v2/subscriptions/features/{subscription_features} + openapi-operation-id: DeleteFeature + attributes: + name: + type: STRING + autofill: FUNC:Name + description: + type: STRING + autofill: VALUE:Auto Generated + external_ref: + type: STRING + configuration.type: + type: ENUM:access,promotion,usage + configuration.tag: + type: STRING + autofill: FUNC:BuzzWord + configuration.label: + type: STRING + configuration.default_value: + type: STRING + configuration.promotions[n].name: + type: STRING + configuration.promotions[n].tag: + type: STRING + configuration.promotions[n].promotion_id: + type: RESOURCE_ID:rule-promotions +subscription-subscribers: + docs: "https://elasticpath.dev/docs/api/subscriptions/subscribers" + json-api-type: subscription_subscriber + json-api-format: compliant + singular-name: subscription-subscriber + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-subscribers" + url: /v2/subscriptions/subscribers + openapi-operation-id: ListSubscribers + query: + - name: filter + type: STRING + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-subscriber" + url: /v2/subscriptions/subscribers/{subscription_subscribers} + openapi-operation-id: GetSubscriber + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-subscriber" + url: /v2/subscriptions/subscribers + openapi-operation-id: CreateSubscriber + update-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/update-subscriber" + url: /v2/subscriptions/subscribers/{subscription_subscribers} + openapi-operation-id: UpdateSubscriber + delete-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/delete-subscriber" + url: /v2/subscriptions/subscribers/{subscription_subscribers} + openapi-operation-id: DeleteSubscriber + attributes: + account_id: + type: RESOURCE_ID:accounts + name: + type: STRING + autofill: FUNC:Name + email: + type: STRING + autofill: FUNC:Email +subscriptions: + docs: "https://elasticpath.dev/docs/api/subscriptions/subscriptions" + json-api-type: subscription + json-api-format: compliant + singular-name: subscription + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-subscriptions" + url: /v2/subscriptions/subscriptions + openapi-operation-id: ListSubscriptions + query: + - name: filter + type: STRING + - name: page[offset] + type: INT + - name: page[limit] + type: INT + - name: include + type: STRING + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-subscription" + url: /v2/subscriptions/subscriptions/{subscriptions} + openapi-operation-id: GetSubscription + query: + - name: include + type: STRING + update-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/update-subscription" + url: /v2/subscriptions/subscriptions/{subscriptions} + openapi-operation-id: UpdateSubscription + delete-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/delete-subscription" + url: /v2/subscriptions/subscriptions/{subscriptions} + openapi-operation-id: DeleteSubscription + attributes: + pricing_option_id: + type: RESOURCE_ID:subscription-offering-pricing-options + plan_id: + type: RESOURCE_ID:subscription-offering-plans + address_id: + type: STRING + go_live_after: + type: STRING +subscription-create: + docs: "https://elasticpath.dev/docs/api/subscriptions/subscriptions" + json-api-type: subscription + json-api-format: compliant + singular-name: subscription-create + no-wrapping: true + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-subscription" + url: /v2/subscriptions/subscriptions + openapi-operation-id: CreateSubscription + creates: subscriptions + attributes: + data.account_id: + type: RESOURCE_ID:accounts + data.currency: + type: STRING + autofill: VALUE:USD + data.name: + type: STRING + autofill: FUNC:Name + data.email: + type: STRING + autofill: FUNC:Email + data.manual_payments: + type: BOOL + data.external_ref: + type: STRING + data.offering_id: + type: RESOURCE_ID:subscription-offerings + data.plan_id: + type: RESOURCE_ID:subscription-offering-plans + data.pricing_option_id: + type: RESOURCE_ID:subscription-offering-pricing-options + data.address_id: + type: STRING + data.pending: + type: BOOL +subscription-schedules: + docs: "https://elasticpath.dev/docs/api/subscriptions/schedules" + json-api-type: subscription_schedule + json-api-format: compliant + singular-name: subscription-schedule + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-schedules" + url: /v2/subscriptions/schedules + openapi-operation-id: ListSchedules + query: + - name: filter + type: STRING + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-schedule" + url: /v2/subscriptions/schedules/{subscription_schedules} + openapi-operation-id: GetSchedule + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-schedule" + url: /v2/subscriptions/schedules + openapi-operation-id: CreateSchedule + update-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/update-schedule" + url: /v2/subscriptions/schedules/{subscription_schedules} + openapi-operation-id: UpdateSchedule + delete-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/delete-schedule" + url: /v2/subscriptions/schedules/{subscription_schedules} + openapi-operation-id: DeleteSchedule + attributes: + name: + type: STRING + autofill: FUNC:Name + external_ref: + type: STRING + specification: + type: STRING + location: + type: STRING + job.job_type: + type: ENUM:billing-run,tax-run,payment-run,import +subscription-dunning-rules: + docs: "https://elasticpath.dev/docs/api/subscriptions/dunning-rules" + json-api-type: subscription_dunning_rule + json-api-format: compliant + singular-name: subscription-dunning-rule + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-dunning-rules" + url: /v2/subscriptions/dunning-rules + openapi-operation-id: ListDunningRules + query: + - name: filter + type: STRING + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-dunning-rule" + url: /v2/subscriptions/dunning-rules/{subscription_dunning_rules} + openapi-operation-id: GetDunningRule + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-dunning-rule" + url: /v2/subscriptions/dunning-rules + openapi-operation-id: CreateDunningRule + update-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/update-dunning-rule" + url: /v2/subscriptions/dunning-rules/{subscription_dunning_rules} + openapi-operation-id: UpdateDunningRule + delete-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/delete-dunning-rule" + url: /v2/subscriptions/dunning-rules/{subscription_dunning_rules} + openapi-operation-id: DeleteDunningRule + attributes: + payment_retry_type: + type: ENUM:fixed,backoff,tiered + payment_retry_interval: + type: INT + autofill: VALUE:1 + payment_retry_unit: + type: ENUM:day,week + payment_retry_multiplier: + type: FLOAT + payment_retries_limit: + type: INT + autofill: VALUE:3 + action: + type: ENUM:none,pause,close,suspend + default: + type: BOOL +subscription-jobs: + docs: "https://elasticpath.dev/docs/api/subscriptions/jobs" + json-api-type: subscription_job + json-api-format: compliant + singular-name: subscription-job + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-jobs" + url: /v2/subscriptions/jobs + openapi-operation-id: ListJobs + query: + - name: filter + type: STRING + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-job" + url: /v2/subscriptions/jobs/{subscription_jobs} + openapi-operation-id: GetJob + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-job" + url: /v2/subscriptions/jobs + openapi-operation-id: CreateJob + delete-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/delete-job" + url: /v2/subscriptions/jobs/{subscription_jobs} + openapi-operation-id: DeleteJob + attributes: + external_ref: + type: STRING + job_type: + type: ENUM:billing-run,tax-run,payment-run,import +subscription-offering-plans: + docs: "https://elasticpath.dev/docs/api/subscriptions/offerings" + json-api-type: subscription_offering_plan + json-api-format: compliant + singular-name: subscription-offering-plan + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-offering-plans" + url: /v2/subscriptions/offerings/{subscription_offerings}/plans + openapi-operation-id: ListOfferingPlans + query: + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-offering-plan" + url: /v2/subscriptions/offerings/{subscription_offerings}/plans/{subscription_offering_plans} + openapi-operation-id: GetOfferingPlan + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-offering-plan" + url: /v2/subscriptions/offerings/{subscription_offerings}/plans + openapi-operation-id: CreateOfferingPlan + update-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/update-offering-plan" + url: /v2/subscriptions/offerings/{subscription_offerings}/plans/{subscription_offering_plans} + openapi-operation-id: UpdateOfferingPlan + delete-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/delete-offering-plan" + url: /v2/subscriptions/offerings/{subscription_offerings}/plans/{subscription_offering_plans} + openapi-operation-id: DeleteOfferingPlan + attributes: + name: + type: STRING + autofill: FUNC:Name + description: + type: STRING + autofill: VALUE:Auto Generated + sku: + type: STRING + autofill: FUNC:BuzzWord + main_image: + type: STRING + external_ref: + type: STRING + ^price\.(.+)\.amount$: + type: INT + ^price\.(.+)\.includes_tax$: + type: BOOL + price_units.unit: + type: ENUM:day,month + price_units.amount: + type: INT +subscription-offering-pricing-options: + docs: "https://elasticpath.dev/docs/api/subscriptions/offerings" + json-api-type: subscription_offering_pricing_option + json-api-format: compliant + singular-name: subscription-offering-pricing-option + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-offering-pricing-options" + url: /v2/subscriptions/offerings/{subscription_offerings}/pricing-options + openapi-operation-id: ListOfferingPricingOptions + query: + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-offering-pricing-option" + url: /v2/subscriptions/offerings/{subscription_offerings}/pricing-options/{subscription_offering_pricing_options} + openapi-operation-id: GetOfferingPricingOption + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-offering-pricing-option" + url: /v2/subscriptions/offerings/{subscription_offerings}/pricing-options + openapi-operation-id: CreateOfferingPricingOption + update-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/update-offering-pricing-option" + url: /v2/subscriptions/offerings/{subscription_offerings}/pricing-options/{subscription_offering_pricing_options} + openapi-operation-id: UpdateOfferingPricingOption + delete-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/delete-offering-pricing-option" + url: /v2/subscriptions/offerings/{subscription_offerings}/pricing-options/{subscription_offering_pricing_options} + openapi-operation-id: DeleteOfferingPricingOption + attributes: + name: + type: STRING + autofill: FUNC:Name + description: + type: STRING + autofill: VALUE:Auto Generated + external_ref: + type: STRING + billing_interval_type: + type: ENUM:day,week,month,year + billing_frequency: + type: INT + autofill: VALUE:1 + trial_period: + type: INT + plan_length: + type: INT + autofill: VALUE:12 + end_behavior: + type: ENUM:close,roll + can_pause: + type: BOOL + can_resume: + type: BOOL + can_cancel: + type: BOOL + base_price_percentage: + type: FLOAT + autofill: VALUE:100 + ^fixed_price\.(.+)\.amount$: + type: INT + ^fixed_price\.(.+)\.includes_tax$: + type: BOOL + lead_time.type: + type: ENUM:day,week + lead_time.time: + type: INT +subscription-offering-features: + docs: "https://elasticpath.dev/docs/api/subscriptions/offerings" + json-api-type: subscription_offering_feature + json-api-format: compliant + singular-name: subscription-offering-feature + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-offering-features" + url: /v2/subscriptions/offerings/{subscription_offerings}/features + openapi-operation-id: ListOfferingFeatures + query: + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-offering-feature" + url: /v2/subscriptions/offerings/{subscription_offerings}/features/{subscription_offering_features} + openapi-operation-id: GetOfferingFeature + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-offering-feature" + url: /v2/subscriptions/offerings/{subscription_offerings}/features + openapi-operation-id: CreateOfferingFeature + update-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/update-offering-feature" + url: /v2/subscriptions/offerings/{subscription_offerings}/features/{subscription_offering_features} + openapi-operation-id: UpdateOfferingFeature + delete-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/delete-offering-feature" + url: /v2/subscriptions/offerings/{subscription_offerings}/features/{subscription_offering_features} + openapi-operation-id: DeleteOfferingFeature + attributes: + name: + type: STRING + autofill: FUNC:Name + description: + type: STRING + autofill: VALUE:Auto Generated + external_ref: + type: STRING + configuration.type: + type: ENUM:access,promotion,usage + configuration.tag: + type: STRING + autofill: FUNC:BuzzWord + configuration.label: + type: STRING + configuration.default_value: + type: STRING + configuration.promotions[n].name: + type: STRING + configuration.promotions[n].tag: + type: STRING + configuration.promotions[n].promotion_id: + type: RESOURCE_ID:rule-promotions +subscription-invoices: + docs: "https://elasticpath.dev/docs/api/subscriptions/invoices" + json-api-type: subscription_invoice + json-api-format: compliant + singular-name: subscription-invoice + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-invoices" + url: /v2/subscriptions/invoices + openapi-operation-id: ListInvoices + query: + - name: filter + type: STRING + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-invoice" + url: /v2/subscriptions/invoices/{subscription_invoices} + openapi-operation-id: GetInvoice +subscription-invoice-payments: + docs: "https://elasticpath.dev/docs/api/subscriptions/invoices" + json-api-type: subscription_invoice_payment + json-api-format: compliant + singular-name: subscription-invoice-payment + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-invoice-payments" + url: /v2/subscriptions/invoices/{subscription_invoices}/payments + openapi-operation-id: ListInvoicePayments + query: + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-invoice-payment" + url: /v2/subscriptions/invoices/{subscription_invoices}/payments/{subscription_invoice_payments} + openapi-operation-id: GetInvoicePayment + update-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/update-invoice-payment" + url: /v2/subscriptions/invoices/{subscription_invoices}/payments/{subscription_invoice_payments} + openapi-operation-id: UpdateInvoicePayment + attributes: + success: + type: BOOL + external_payment_id: + type: STRING + failure_detail.reason: + type: STRING + payment_taken_at: + type: STRING +subscription-states: + docs: "https://elasticpath.dev/docs/api/subscriptions/subscriptions" + json-api-type: subscription_state + json-api-format: compliant + singular-name: subscription-state + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-subscription-states" + url: /v2/subscriptions/subscriptions/{subscriptions}/states + openapi-operation-id: ListSubscriptionStates + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-subscription-state" + url: /v2/subscriptions/subscriptions/{subscriptions}/states/{subscription_states} + openapi-operation-id: GetSubscriptionState + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-subscription-state" + url: /v2/subscriptions/subscriptions/{subscriptions}/states + openapi-operation-id: CreateSubscriptionState + attributes: + action: + type: ENUM:cancel,pause,resume,pending +subscription-plans: + docs: "https://elasticpath.dev/docs/api/subscriptions/subscriptions" + json-api-type: subscription_offering_plan + json-api-format: compliant + singular-name: subscription-plan + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-subscription-plans" + url: /v2/subscriptions/subscriptions/{subscriptions}/plans + openapi-operation-id: ListSubscriptionPlans + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-subscription-plan" + url: /v2/subscriptions/subscriptions/{subscriptions}/plans/{subscription_plans} + openapi-operation-id: GetSubscriptionPlan +subscription-pricing-options: + docs: "https://elasticpath.dev/docs/api/subscriptions/subscriptions" + json-api-type: subscription_offering_pricing_option + json-api-format: compliant + singular-name: subscription-pricing-option + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-subscription-pricing-options" + url: /v2/subscriptions/subscriptions/{subscriptions}/pricing-options + openapi-operation-id: ListSubscriptionPricingOptions + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-subscription-pricing-option" + url: /v2/subscriptions/subscriptions/{subscriptions}/pricing-options/{subscription_pricing_options} + openapi-operation-id: GetSubscriptionPricingOption +subscription-entitlements: + docs: "https://elasticpath.dev/docs/api/subscriptions/subscriptions" + json-api-type: subscription_offering_feature + json-api-format: compliant + singular-name: subscription-entitlement + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-subscription-features" + url: /v2/subscriptions/subscriptions/{subscriptions}/features + openapi-operation-id: ListSubscriptionFeatures + query: + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-subscription-feature" + url: /v2/subscriptions/subscriptions/{subscriptions}/features/{subscription_entitlements} + openapi-operation-id: GetSubscriptionFeature +subscription-imports: + docs: "https://elasticpath.dev/docs/api/subscriptions/imports" + json-api-type: subscription_import + json-api-format: compliant + singular-name: subscription-import + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/list-import-jobs" + url: /v2/subscriptions/imports + openapi-operation-id: ListImportJobs + query: + - name: filter + type: STRING + - name: page[offset] + type: INT + - name: page[limit] + type: INT + get-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-import" + url: /v2/subscriptions/imports/{subscription_imports} + openapi-operation-id: GetImport + query: + - name: page[offset] + type: INT + - name: page[limit] + type: INT + create-entity: + docs: "https://elasticpath.dev/docs/api/subscriptions/create-import" + url: /v2/subscriptions/imports + openapi-operation-id: CreateImport + content-type: "multipart/form-data" + attributes: + import_file: + type: FILE + external_ref: + type: STRING +subscription-import-errors: + docs: "https://elasticpath.dev/docs/api/subscriptions/imports" + json-api-type: subscription_import_error + json-api-format: compliant + singular-name: subscription-import-error + get-collection: + docs: "https://elasticpath.dev/docs/api/subscriptions/get-import-errors" + url: /v2/subscriptions/imports/{subscription_imports}/errors + openapi-operation-id: GetImportErrors + query: + - name: page[offset] + type: INT + - name: page[limit] + type: INT diff --git a/external/runbooks/run-all-runbooks.sh b/external/runbooks/run-all-runbooks.sh index b946743..cbb074d 100755 --- a/external/runbooks/run-all-runbooks.sh +++ b/external/runbooks/run-all-runbooks.sh @@ -63,8 +63,7 @@ epcc runbooks run commerce-extensions create-review-for-random-product epcc runbooks run commerce-extensions delete-product-review-custom-api echo "Starting Subscriptions Tests" -epcc reset-store .+ -epcc runbooks run subscriptions create-subscription-offerings +"$SCRIPT_DIR/run-subscriptions-runbooks.sh" echo "Starting Account Cart Association Tests" epcc reset-store .+ diff --git a/external/runbooks/run-subscriptions-runbooks.sh b/external/runbooks/run-subscriptions-runbooks.sh new file mode 100755 index 0000000..8a9ec80 --- /dev/null +++ b/external/runbooks/run-subscriptions-runbooks.sh @@ -0,0 +1,111 @@ +#!/usr/bin/env bash + +set -e +set -x + +SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) + +echo "Starting Subscriptions Runbook - Clean up subscription resources" +epcc delete-all subscription-offerings +epcc delete-all subscription-subscribers +epcc delete-all subscription-schedules +epcc delete-all subscription-dunning-rules +epcc delete-all subscription-jobs +epcc delete-all subscription-features +epcc delete-all rule-promotions +epcc delete-all account-tags + +echo "Starting Subscriptions Runbook - Create Offering" +epcc runbooks run subscriptions create-offering + +echo "Starting Subscriptions Runbook - Verify Offering Resources" +# Verify nested resources were created under the offering +NUM_PLANS=$(epcc get subscription-offering-plans name=Streaming_Service --output-jq '.data | length') +if [ "$NUM_PLANS" -eq 1 ]; then + echo "Correct number of offering plans: 1" +else + echo "Expected 1 offering plan, but found $NUM_PLANS" + exit 1 +fi + +NUM_PRICING_OPTIONS=$(epcc get subscription-offering-pricing-options name=Streaming_Service --output-jq '.data | length') +if [ "$NUM_PRICING_OPTIONS" -eq 1 ]; then + echo "Correct number of offering pricing options: 1" +else + echo "Expected 1 offering pricing option, but found $NUM_PRICING_OPTIONS" + exit 1 +fi + +NUM_FEATURES=$(epcc get subscription-offering-features name=Streaming_Service --output-jq '.data | length') +if [ "$NUM_FEATURES" -eq 1 ]; then + echo "Correct number of offering features: 1" +else + echo "Expected 1 offering feature, but found $NUM_FEATURES" + exit 1 +fi + +echo "Starting Subscriptions Runbook - Create Offering Promotion" +epcc runbooks run subscriptions create-offering-promotion + +echo "Starting Subscriptions Runbook - Verify Promotion Feature on Offering" +NUM_FEATURES=$(epcc get subscription-offering-features name=Streaming_Service --output-jq '.data | length') +if [ "$NUM_FEATURES" -eq 2 ]; then + echo "Correct number of offering features: 2 (1 access + 1 promotion)" +else + echo "Expected 2 offering features, but found $NUM_FEATURES" + exit 1 +fi + +echo "Starting Subscriptions Runbook - Create Account and Subscriber" +epcc runbooks run subscriptions create-account-and-subscriber + +echo "Starting Subscriptions Runbook - Verify Subscriber" +NUM_SUBSCRIBERS=$(epcc get subscription-subscribers --output-jq '.data | length') +if [ "$NUM_SUBSCRIBERS" -ge 1 ]; then + echo "Correct: at least 1 subscriber found" +else + echo "Expected at least 1 subscriber, but found $NUM_SUBSCRIBERS" + exit 1 +fi + +echo "Starting Subscriptions Runbook - Setup Billing" +epcc runbooks run subscriptions setup-billing + +echo "Starting Subscriptions Runbook - Verify Billing Resources" +NUM_SCHEDULES=$(epcc get subscription-schedules --output-jq '.data | length') +if [ "$NUM_SCHEDULES" -ge 1 ]; then + echo "Correct: at least 1 schedule found" +else + echo "Expected at least 1 schedule, but found $NUM_SCHEDULES" + exit 1 +fi + +NUM_DUNNING_RULES=$(epcc get subscription-dunning-rules --output-jq '.data | length') +if [ "$NUM_DUNNING_RULES" -ge 1 ]; then + echo "Correct: at least 1 dunning rule found" +else + echo "Expected at least 1 dunning rule, but found $NUM_DUNNING_RULES" + exit 1 +fi + +echo "Starting Subscriptions Runbook - Run Billing Job" +epcc runbooks run subscriptions run-billing-job + +echo "Starting Subscriptions Runbook - View Invoices (listing only, billing job is async)" +epcc get subscription-invoices + +echo "Starting Subscriptions Runbook - Bulk Create Offerings" +epcc runbooks run subscriptions create-subscription-offerings --count 3 + +NUM_OFFERINGS=$(epcc get subscription-offerings --output-jq '.data | length') +if [ "$NUM_OFFERINGS" -ge 4 ]; then + echo "Correct: at least 4 offerings found (1 named + 3 bulk)" +else + echo "Expected at least 4 offerings, but found $NUM_OFFERINGS" + exit 1 +fi + +echo "Starting Subscriptions Runbook - Reset" +epcc runbooks run subscriptions reset + +echo "Subscriptions Runbook - SUCCESS" diff --git a/external/runbooks/subscriptions.epcc.yml b/external/runbooks/subscriptions.epcc.yml index c523329..ba32fb4 100644 --- a/external/runbooks/subscriptions.epcc.yml +++ b/external/runbooks/subscriptions.epcc.yml @@ -1,45 +1,292 @@ name: "subscriptions" description: - long: "Utilities for working with subscriptions" - short: "Utilities for working with subscriptions" + long: "End-to-end subscription workflows: create offerings, add to cart, checkout, manage lifecycle, and handle invoices" + short: "Subscription offering, checkout, and lifecycle workflows" actions: -# create-subscription-products: -# variables: -# count: -# type: INT -# default: 10 -# description: -# short: "Create a lot of subscription products" -# description: -# short: "Create a number of products" -# commands: -# - | -# {{ range untilStep 0 .count 1 -}}epcc create --skip-alias-processing -s subscription-product --auto-fill -# {{ end }} -# create-subscription-plans: -# variables: -# count: -# type: INT -# default: 10 -# description: -# short: "Create a lot of subscription plans" -# description: -# short: "Create a number of orders" -# commands: -# - | -# {{ range untilStep 0 .count 1 -}}epcc create --skip-alias-processing -s subscription-plan status active --auto-fill billing_interval_type day billing_frequency 214 plan_length 1 end_behavior close can_pause true can_resume true can_cancel true fixed_price.USD.amount {{ pseudoRandInt 1 200 }}00 fixed_price.USD.includes_tax true -# {{ end }} + create-offering: + description: + short: "Create a complete subscription offering with a plan, pricing option, and feature" + variables: + offering-name: + type: STRING + default: "Streaming Service" + description: + short: "Name of the offering" + plan-name: + type: STRING + default: "HD Plan" + description: + short: "Name of the plan" + plan-price: + type: INT + default: 999 + description: + short: "Plan price in smallest currency unit (e.g., 999 = $9.99)" + currency: + type: STRING + default: "USD" + description: + short: "Currency code for plan pricing" + pricing-option-name: + type: STRING + default: "Monthly" + description: + short: "Name of the pricing option" + billing-interval: + type: ENUM:day,week,month,year + default: "month" + description: + short: "Billing interval type" + billing-frequency: + type: INT + default: 1 + description: + short: "How often to bill (e.g., 1 = every interval, 2 = every other)" + plan-length: + type: INT + default: 12 + description: + short: "Length of the plan in billing intervals (e.g., 12 months)" + feature-name: + type: STRING + default: "Premium Access" + description: + short: "Name of the feature/entitlement" + feature-type: + type: ENUM:access,promotion,usage + default: "access" + description: + short: "Type of feature" + feature-tag: + type: STRING + default: "premium" + description: + short: "Tag for the feature" + commands: + # Create the offering + - epcc create subscription-offering name "{{ index . "offering-name" }}" description "{{ index . "offering-name" }}" + # Create a plan within the offering + - epcc create subscription-offering-plan last_read=entity name "{{ index . "plan-name" }}" description "{{ index . "plan-name" }}" price.{{ .currency }}.amount {{ index . "plan-price" }} price.{{ .currency }}.includes_tax false price_units.unit month price_units.amount 1 + # Create a pricing option within the offering + - epcc create subscription-offering-pricing-option name=Streaming_Service name "{{ index . "pricing-option-name" }}" description "{{ index . "pricing-option-name" }}" billing_interval_type {{ index . "billing-interval" }} billing_frequency {{ index . "billing-frequency" }} plan_length {{ index . "plan-length" }} base_price_percentage 100.0 end_behavior roll can_pause true can_resume true can_cancel true + # Create a feature within the offering + - epcc create subscription-offering-feature name=Streaming_Service name "{{ index . "feature-name" }}" description "{{ index . "feature-name" }}" configuration.type {{ index . "feature-type" }} configuration.tag {{ index . "feature-tag" }} + + create-offering-promotion: + description: + short: "Create an account tag, a rule promotion triggered by that tag, and link it to an offering as a promotion feature" + variables: + promotion-name: + type: STRING + default: "Subscriber Discount" + description: + short: "Name of the rule promotion" + discount-percent: + type: INT + default: 10 + description: + short: "Percent discount to apply to the cart" + promotion-tag: + type: STRING + default: "subscriber_discount" + description: + short: "Account tag name that triggers the promotion" + commands: + # Create an account tag - when a subscriber activates, this tag is applied to their account + - epcc create account-tag name "{{ index . "promotion-tag" }}" description "Tag applied to subscriber accounts for promotion eligibility" + # Create a rule promotion that fires when an account has this tag (args are account tag UUIDs) + - epcc create rule-promotion --auto-fill name "{{ index . "promotion-name" }}" description "{{ index . "discount-percent" }}% cart discount for subscribers with tag {{ index . "promotion-tag" }}" enabled true automatic true rule_set.rules.strategy account_tags rule_set.rules.operator contains_any rule_set.rules.args[0] alias/account_tag/name={{ index . "promotion-tag" }}/id rule_set.actions[0].strategy cart_discount rule_set.actions[0].args[0] percent rule_set.actions[0].args[1] {{ index . "discount-percent" }} + # Create a promotion feature on the offering that links to the rule promotion via promotion_id + - epcc create subscription-offering-feature name=Streaming_Service name "{{ index . "promotion-name" }} Feature" description "Applies {{ index . "promotion-name" }} via rule promotion" configuration.type promotion configuration.promotions[0].tag "{{ index . "promotion-tag" }}" configuration.promotions[0].name "{{ index . "promotion-name" }}" configuration.promotions[0].promotion_id alias/rule_promotion/name=Subscriber_Discount/id + + create-account-and-subscriber: + description: + short: "Create an account and linked subscriber" + variables: + account-name: + type: STRING + default: "Acme Corp" + description: + short: "Name of the account" + member-name: + type: STRING + default: "Jane Doe" + description: + short: "Name of the subscriber" + member-email: + type: STRING + default: "jane@acme.com" + description: + short: "Email of the subscriber" + commands: + # Create account + - epcc create -s account name "{{ index . "account-name" }}" legal_name "{{ index . "account-name" }}" + # Create subscriber linked to the account + - epcc create subscription-subscriber account_id name=Acme_Corp name "{{ index . "member-name" }}" email "{{ index . "member-email" }}" + + subscribe-via-cart: + description: + short: "Add a subscription offering to a cart and check out with an account" + variables: + cart-name: + type: STRING + default: "subscription-cart" + description: + short: "Cart ID to use" + commands: + # Create a cart + - epcc create cart name "{{ index . "cart-name" }}" id {{ index . "cart-name" }} description "Subscription checkout cart" + # Add subscription offering to cart (requires offering, plan, and pricing option IDs) + - epcc create cart-subscription-item id={{ index . "cart-name" }} id name=Streaming_Service quantity 1 subscription_configuration.plan last_read=subscription-offering-plan subscription_configuration.pricing_option last_read=subscription-offering-pricing-option + # Checkout with the account + - epcc create cart-checkout {{ index . "cart-name" }} account.id name=Acme_Corp contact.name "Jane Doe" contact.email "jane@acme.com" billing_address.first_name Jane billing_address.last_name Doe billing_address.line_1 "123 Main St" billing_address.city "Anytown" billing_address.postcode '"12345"' billing_address.county "State" billing_address.country US shipping_address.first_name Jane shipping_address.last_name Doe shipping_address.line_1 "123 Main St" shipping_address.city "Anytown" shipping_address.postcode '"12345"' shipping_address.county "State" shipping_address.country US + + setup-billing: + description: + short: "Create a billing schedule and dunning rule for failed payment retries" + variables: + schedule-name: + type: STRING + default: "Daily Billing" + description: + short: "Name of the billing schedule" + cron: + type: STRING + default: "0 2 * * *" + description: + short: "Cron specification for the schedule" + timezone: + type: STRING + default: "America/New_York" + description: + short: "Timezone for the schedule" + commands: + # Create a billing schedule + - epcc create subscription-schedule name "{{ index . "schedule-name" }}" specification "{{ .cron }}" location "{{ .timezone }}" job.job_type billing-run + # Create a dunning rule for retrying failed payments + - epcc create subscription-dunning-rule payment_retry_type backoff payment_retry_interval 1 payment_retry_unit day payment_retry_multiplier 2.0 payment_retries_limit 5 action suspend default true + + manage-subscription-lifecycle: + description: + short: "Pause, resume, or cancel a subscription" + variables: + action: + type: ENUM:pause,resume,cancel + default: "pause" + description: + short: "Lifecycle action to perform" + commands: + # List subscriptions to find the one to manage + - epcc get subscriptions + # Perform the lifecycle action + - epcc create subscription-state last_read=entity action {{ .action }} + # View the state history + - epcc get subscription-states last_read=entity + + view-subscription-details: + description: + short: "View a subscription with its plans, pricing options, entitlements, and states" + commands: + # List subscriptions + - epcc get subscriptions + # View details of the most recent subscription + - epcc get subscription last_read=entity + # View the plans attached to this subscription + - epcc get subscription-plans last_read=entity + # View the pricing options + - epcc get subscription-pricing-options last_read=entity + # View entitlements (features) + - epcc get subscription-entitlements last_read=entity + # View state history + - epcc get subscription-states last_read=entity + + view-invoices: + description: + short: "List invoices and view payment details" + commands: + # List all invoices + - epcc get subscription-invoices + # View the most recent invoice + - epcc get subscription-invoice last_read=entity + # View payments for the invoice + - epcc get subscription-invoice-payments last_read=entity + + record-manual-payment: + description: + short: "Record a manual payment against an invoice" + variables: + external-payment-id: + type: STRING + default: "manual-pay-001" + description: + short: "External payment reference ID" + commands: + # List invoices to find one to pay + - epcc get subscription-invoices + # View payments for the most recent invoice + - epcc get subscription-invoice-payments last_read=entity + # Mark the payment as successful + - epcc update subscription-invoice-payment last_read=entity last_read=entity success true external_payment_id "{{ index . "external-payment-id" }}" + + run-billing-job: + description: + short: "Manually trigger a billing run job" + commands: + - epcc create subscription-job job_type billing-run + - epcc get subscription-job last_read=entity + + import-subscribers: + description: + short: "Import subscribers from a CSV file and check for errors" + variables: + file: + type: STRING + default: "import.csv" + description: + short: "Path to the CSV import file" + commands: + # Upload the import file + - epcc create subscription-import import_file {{ .file }} + # Check import status + - epcc get subscription-import last_read=entity + # Check for errors + - epcc get subscription-import-errors last_read=entity + create-subscription-offerings: variables: count: type: INT default: 10 description: - short: "Create a lot of subscription offerings" + short: "Number of subscription offerings to create" description: - short: "Create a number of offerings" + short: "Create a number of offerings (bulk)" commands: - | {{ range untilStep 0 .count 1 -}}epcc create --skip-alias-processing -s subscription-offering --auto-fill {{ end }} - + + reset: + description: + short: "Clean up resources created by this runbook" + ignore_errors: true + commands: + - | + epcc get -s subscription-offerings + epcc get -s subscription-schedules + epcc get -s subscription-dunning-rules + epcc get -s subscriptions + epcc get -s subscription-subscribers + epcc get -s accounts + epcc get -s rule-promotions + epcc get -s account-tags + - | + epcc delete subscription-offering name=Streaming_Service --if-alias-exists name=Streaming_Service + epcc delete subscription-schedule name=Daily_Billing --if-alias-exists name=Daily_Billing + epcc delete subscription-dunning-rule last_read=entity --if-alias-exists last_read=entity + epcc delete subscription-subscriber name=Jane_Doe --if-alias-exists name=Jane_Doe + epcc delete account name=Acme_Corp --if-alias-exists name=Acme_Corp + epcc delete rule-promotion name=Subscriber_Discount --if-alias-exists name=Subscriber_Discount + epcc delete account-tag name=subscriber_discount --if-alias-exists name=subscriber_discount + - | + epcc delete cart subscription-cart