openapi: 3.1.0 info: version: 25.1126.6886238 x-version-timestamp: 2025-11-26 19:10:23+00:00 title: Addresses Introduction Account Addresses Subscriptions API description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour. You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token. ' 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: 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. \n\n### Managing the Subscription Lifecycle\n\nThe subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. \n\nA subscription can have the following states:\n\n- `pending`\n- `canceled`\n- `paused`\n- `resumed`\n\n#### Creating a pending subscription \n\nA subscription can be created in a `pending` state. This is useful for several reasons.\n\n- 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.\n- 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. \n- 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.\n\nFor 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. \n\nYou 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. \n\n:::caution\n\nAlthough, 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. \n\n:::\n\nSee [create a subscription](/docs/api/subscriptions/create-subscription).\n\n#### Cancelling or pausing and resuming subscriptions\n\nA subscriber can decide to cancel or pause and/or resume a subscription. The following example describes pausing or canceling and resuming a subscription.\n\n1. The subscriber pauses or cancels the subscription. \n - The subscription status is `active`. \n - either `paused` or `cancelled` is set to `true`.\n - either the `paused_at` or `cancelled_at` timestamp is populated with the date and time the subscription is paused or cancelled.\n - for cancelled subscriptions, `end_date` indicates when the subscription will expire and end.\n2. 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`.\n3. Subsequent billing runs skip that subscription completely as the subscription status is `inactive`.\n4. If the subscriber resumes the subscription:\n - either `paused` or `cancelled` is set to `false`.\n - the `resumed_at` timestamp is populated with the date and time the subscription is resumed.\n5. 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.\n6. The payment run processes the invoice. Once the payment succeeds then the payment run updates the status of the subscription to `active`.\n\n### Orders\n\nWhen a customer chooses a subscription, they need to add the subscription to a cart, checkout the cart and then pay for the order. \n\n1. When a customer adds a subscription to cart, this is handled using the `Add subscription to cart` endpoint. \n2. Once a subscription has been added to a cart, the [**Checkout API**](/docs/api/carts/checkout-api) converts the cart to an order. \n3. 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).\n" paths: /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.\n\n### Filtering\n\nThis endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering).\n\nThe following attributes and operators are supported.\n\n| Operator | Attribute | Description |\n| --- | --- | --- | \n| `eq` | `account_id`, `name`, `email`, `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |\n| `in` | `account_id`, `name`, `email`, `external_ref` | In. Checks if the value is in the specified list. If it is, the condition is true. |\n\n### Including Resources\n\nYou can use the `include` parameter to include the following resources with this endpoint.\n\n| Resource | Required | Description |\n| --- | --- | --- |\n| `pricing_options, plans` | Optional | Retrieves all pricing options and plans associated with a subscription. |\n| `plans` | Optional | Retrieves all plans associated with a subscription. |\n| `pricing_options` | Optional | Retrieves all pricing options associated with a subscription. |\n\nSee [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).\n" 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. \n\nA subscription can have the following states:\n\n- `pending` \n- `canceled`\n- `paused`\n- `resumed`\nFor more information, see [Managing the Subscription Lifecycle](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).\n\nImmediate cancellation (`cancel` with `cancel_immediately: true`) ends the subscription and updates entitlements in this request; it does **not** issue refunds or modify paid invoices. Use payments refund flows separately if needed.\n" operationId: CreateSubscriptionState requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ChangeState' responses: '204': description: Success. The subscription's state has changed. '400': $ref: '#/components/responses/ValidationError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '422': $ref: '#/components/responses/UnprocessableContent' '500': $ref: '#/components/responses/InternalServerError' get: tags: - Subscriptions summary: List subscription states operationId: ListSubscriptionStates responses: '200': description: Success. A list of subscription states is returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SubscriptionState' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/subscriptions/{subscription_uuid}/states/{state_uuid}: parameters: - name: subscription_uuid in: path description: The unique identifier of the subscription. required: true schema: $ref: '#/components/schemas/UUID' - name: state_uuid in: path description: The unique identifier of the subscription state. required: true schema: $ref: '#/components/schemas/UUID' get: tags: - Subscriptions summary: Get subscription state operationId: GetSubscriptionState responses: '200': description: Success. A subscription state is returned. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SubscriptionState' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' /v2/subscriptions/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' components: schemas: 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 PlanResponseAttributes: allOf: - $ref: '#/components/schemas/PlanAttributes' - $ref: '#/components/schemas/Timestamps' 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' FeatureResponseAttributes: allOf: - $ref: '#/components/schemas/FeatureAttributes' 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' Link: anyOf: - $ref: '#/components/schemas/LinkURI' - $ref: '#/components/schemas/LinkObject' 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 Relationship: anyOf: - $ref: '#/components/schemas/SingleRelationship' - $ref: '#/components/schemas/ManyRelationship' SubscriptionOfferingPlanType: type: string example: subscription_offering_plan enum: - subscription_offering_plan 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' 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' PricingOptionAttributes: required: - name - billing_interval_type - billing_frequency - plan_length - end_behavior - can_pause - can_resume - can_cancel properties: external_ref: $ref: '#/components/schemas/ExternalRef' name: type: string description: A name for the pricing option. example: Monthly minLength: 3 maxLength: 1024 description: type: string description: The pricing option description to display to customers. maxLength: 1024 example: A monthly subscription. billing_interval_type: type: string description: The unit of time that billing intervals are measured. example: month enum: - day - week - month - year x-go-type: model.BillingIntervalType x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model billing_frequency: type: integer description: The number of intervals between issuing bills. example: 1 minimum: 1 trial_period: type: integer description: The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month. example: 7 minimum: 0 lead_time: $ref: '#/components/schemas/LeadTime' notification_schedule: type: array x-go-type-skip-optional-pointer: true items: $ref: '#/components/schemas/NotificationSchedule' plan_length: type: integer description: The number of intervals that the subscription runs for. example: 12 minimum: 1 end_behavior: type: string description: Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments. example: close enum: - close - roll x-go-type: model.EndBehavior x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model can_pause: type: boolean description: The subscriber can pause a subscription. example: false can_resume: type: boolean description: The subscriber can resume a paused subscription. example: false can_cancel: type: boolean description: The subscriber can cancel a subscription. example: false base_price_percentage: type: number format: double description: A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering. example: 90 minimum: 0 maximum: 100 fixed_price: $ref: '#/components/schemas/Price' 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 SubscriptionType: type: string example: subscription enum: - subscription 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' 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' 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' FeaturePromotionAttributes: required: - type - promotions properties: type: type: string enum: - promotion example: promotion promotions: type: array items: $ref: '#/components/schemas/FeaturePromotion' 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 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 OfferingBuildPlanPricingOptions: type: array items: type: string description: The unique ID or external ref of the pricing option example: 11111111-2222-3333-4444-555555555555 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. SubscriptionIncludes: readOnly: true properties: plans: type: array items: $ref: '#/components/schemas/OfferingPlan' pricing_options: type: array items: $ref: '#/components/schemas/OfferingPricingOption' SubscriptionUpdateAttributes: properties: pricing_option_id: type: string format: uuid x-go-type: uuid.UUID x-go-type-import: name: uuid path: github.com/google/uuid example: 00000000-0000-0000-0000-000000000001 plan_id: type: string format: uuid x-go-type: uuid.UUID x-go-type-import: name: uuid path: github.com/google/uuid example: 00000000-0000-0000-0000-000000000001 address_id: type: string format: UUID nullable: true x-go-type: uuid.UUID x-go-type-import: name: uuid path: github.com/google/uuid example: 00000000-0000-0000-0000-000000000001 payment_authority: $ref: '#/components/schemas/PaymentAuthority' go_live_after: description: The date and time a `pending` subscription goes live and becomes active. See [Creating a pending subscription](/docs/api/subscriptions/subscriptions#creating-a-pending-subscription). type: string example: '2017-01-10T11:41:19.244842Z' nullable: true SelectedMeta: properties: meta: $ref: '#/components/schemas/SelectedMetaAttributes' 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. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n" type: object properties: related: type: string example: foo.bar ChangeState: required: - type - attributes properties: type: $ref: '#/components/schemas/SubscriptionStateType' attributes: $ref: '#/components/schemas/SubscriptionStateAttributes' SubscriptionPriceUpdateHistoryEntry: description: A record of the previous prices of a subscription before a price change was applied required: - price_changes - valid_until properties: price_changes: $ref: '#/components/schemas/SubscriptionPriceChanges' valid_until: description: The date and time when the prices were changed (when these previous prices stopped being active) type: string format: date-time example: '2017-01-10T11:41:19.244842Z' 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 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). 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' SubscriptionUpdate: required: - id - type - attributes properties: id: $ref: '#/components/schemas/UUID' type: $ref: '#/components/schemas/SubscriptionType' attributes: $ref: '#/components/schemas/SubscriptionUpdateAttributes' PlanAttributesAndSelectedMeta: allOf: - $ref: '#/components/schemas/PlanAttributes' - $ref: '#/components/schemas/SelectedMeta' Price: additionalProperties: type: object description: The base price. required: - amount properties: amount: type: integer format: int64 minimum: 0 example: 100 description: The value as a whole number of the currency's smallest subdivision. includes_tax: type: boolean example: true description: Indicates whether the amount includes any taxes. example: USD: amount: 100 includes_tax: false GBP: amount: 90 includes_tax: true 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' SelectedMetaAttributes: properties: selected: type: boolean example: true description: One item must be selected for use in the subscription 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' OfferingPlanExternalRefMeta: readOnly: true type: string format: string description: The offerings plan external_ref value example: 97dddc65-eabd-45d8-b45b-2ece5cfc8c50 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 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 SubscriptionPriceChanges: properties: plan_prices: x-go-type-skip-optional-pointer: true additionalProperties: $ref: '#/components/schemas/Price' example: 197a11f4-d341-4594-9574-7fbfbe6a671d: USD: amount: 100 includes_tax: false GBP: amount: 90 includes_tax: true pricing_option_prices: x-go-type-skip-optional-pointer: true additionalProperties: $ref: '#/components/schemas/PricingOptionPrice' example: 83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c: base_price_percentage: 90 197a11f4-d341-4594-9574-7fbfbe6a671d: USD: amount: 100 includes_tax: false GBP: amount: 90 includes_tax: true PaymentFailureDetail: type: object description: The reason the payment failed. properties: reason: type: string example: Card Failure 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 CreatePaymentAuthority: type: object oneOf: - $ref: '#/components/schemas/CreatePaymentAuthorityEPPayments' - $ref: '#/components/schemas/CreatePaymentAuthorityStripe' - $ref: '#/components/schemas/CreatePaymentAuthorityAuthorizeNet' discriminator: propertyName: type mapping: elastic_path_payments_stripe: '#/components/schemas/CreatePaymentAuthorityEPPayments' stripe_payment_intents: '#/components/schemas/CreatePaymentAuthorityStripe' authorize_net: '#/components/schemas/CreatePaymentAuthorityAuthorizeNet' required: - type properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: elastic_path_payments_stripe enum: - authorize_net - elastic_path_payments_stripe - stripe_payment_intents x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways 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 FeatureMeta: readOnly: true required: - owner - timestamps properties: owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/Timestamps' 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' CreatePaymentAuthorityStripe: writeOnly: true type: object required: - type - customer_id - card_id properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: stripe_payment_intents enum: - stripe_payment_intents x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways customer_id: description: The unique identifier for a customer. type: string minLength: 3 maxLength: 1024 example: cus_OPfKlxWV3hp9h6 card_id: description: The unique identifier of the card used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: card_8Diw3FQPhxK27WADPVMeXieP DisplayPrice: properties: without_tax: $ref: '#/components/schemas/PriceFormatting' with_tax: $ref: '#/components/schemas/PriceFormatting' tax: description: 'Tax component when itemized (for example on subscription invoices). Omitted for catalog prices that only expose with/without tax. ' $ref: '#/components/schemas/PriceFormatting' example: without_tax: amount: 100 currency: USD formatted: $1.00 with_tax: amount: 110 currency: USD formatted: $1.10 tax: amount: 10 currency: USD formatted: $0.10 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 SubscriptionOfferingPricingOptionType: type: string example: subscription_offering_pricing_option enum: - subscription_offering_pricing_option CreatePaymentAuthorityAuthorizeNet: type: object required: - type - payment_profile_id - customer_profile_id properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: authorize_net enum: - authorize_net x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways payment_profile_id: description: The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: '1511660856' customer_profile_id: description: The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: '1511736979' 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' 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 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' 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' 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 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' SubscriptionOfferingType: type: string example: subscription_offering enum: - subscription_offering 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 ErrorResponse: required: - errors properties: errors: type: array items: $ref: '#/components/schemas/Error' 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' OfferingPlanPrices: type: object description: A list of plan prices for each of its pricing options. additionalProperties: $ref: '#/components/schemas/OfferingPlanPriceForPricingOption' 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 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 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' 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 PricingOptionAttributesAndSelectedMeta: allOf: - $ref: '#/components/schemas/PricingOptionAttributes' - $ref: '#/components/schemas/SelectedMeta' 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' 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 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' SingleRelationship: description: The subscription resource that is related. properties: data: $ref: '#/components/schemas/RelationshipData' links: $ref: '#/components/schemas/RelationshipLinks' BuildSubscription: required: - account_id - currency - name - email - manual_payments properties: external_ref: $ref: '#/components/schemas/ExternalRef' account_id: $ref: '#/components/schemas/UUID' address_id: $ref: '#/components/schemas/UUID' offering_external_ref: $ref: '#/components/schemas/ExternalRef' offering_id: $ref: '#/components/schemas/UUID' plan_id: $ref: '#/components/schemas/UUID' pricing_option_id: $ref: '#/components/schemas/UUID' currency: $ref: '#/components/schemas/CurrencyIdentifier' payment_authority: $ref: '#/components/schemas/CreatePaymentAuthority' manual_payments: $ref: '#/components/schemas/ManualPayments' name: type: string minLength: 3 maxLength: 1024 example: Albert Einstein email: type: string format: email minLength: 3 maxLength: 1024 example: albert@elasticpath.com pending: type: boolean description: Whether a subscription is pending activation or not. See [Creating a pending subscription](/docs/api/subscriptions/subscriptions#creating-a-pending-subscription). example: false first_invoice_paid: type: boolean description: Indicates that payment for the first billing period of the subscription has already been taken. As well as creating the subscription a settled invoice is created to cover the first period. example: false started_at: description: When importing an active subscription from an existing system you can specify the date and time of the start of the most recent period. This may only be supplied when `first_invoice_paid` is true. As well as creating the subscription a settled invoice is created to cover the correct billing period. type: string example: '2017-01-10T11:41:19.244842Z' override_first_period_end_date: description: Optional. May only be set when `started_at` is set. When supplied, overrides the default first billing period end (start + 1 interval). The first billing period runs from the subscription start date to this date. The subscriber is charged the standard period price for the first period. Subsequent billing periods start from this date. Must be after the subscription start date. type: string format: date-time example: '2027-02-01T00:00:00Z' offering: $ref: '#/components/schemas/OfferingAttributes' features: type: array description: Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering minItems: 1 items: anyOf: - $ref: '#/components/schemas/ExternalRef' - $ref: '#/components/schemas/FeatureAttributes' - $ref: '#/components/schemas/UUID' plans: type: array minItems: 1 items: $ref: '#/components/schemas/PlanAttributesAndSelectedMeta' pricing_options: type: array minItems: 1 items: $ref: '#/components/schemas/PricingOptionAttributesAndSelectedMeta' configured_features: $ref: '#/components/schemas/OfferingBuildConfiguredFeatures' pricing_option_associations: $ref: '#/components/schemas/OfferingBuildPricingOptionAssociations' selected_plan: $ref: '#/components/schemas/ExternalRef' selected_pricing_option: $ref: '#/components/schemas/ExternalRef' order: $ref: '#/components/schemas/BuildSubscriptionOrder' meta: $ref: '#/components/schemas/SubscriptionMeta' UUID: type: string description: The unique identifier. format: uuid x-go-type: uuid.UUID x-go-type-import: name: uuid path: github.com/google/uuid example: 11111111-2222-3333-4444-555555555555 LinkURI: type: string format: uri example: http://example.com/articles/1/comments nullable: 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' 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' 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' InvoiceNotification: description: A notification scheduled for an invoice. required: - name - due properties: name: description: The name of the notification schedule that generated this notification. type: string example: 7 days before renewal due: description: The date and time when the notification is due to be sent. type: string format: date-time example: '2024-01-24T00:00:00Z' sent_at: description: The date and time when the notification was sent. type: string format: date-time example: '2024-01-24T00:00:00Z' SubscriptionOfferingFeatureType: type: string example: subscription_offering_feature enum: - subscription_offering_feature 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' OfferingResponseAttributes: allOf: - $ref: '#/components/schemas/OfferingAttributes' - $ref: '#/components/schemas/Timestamps' 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 OfferingBuildPlanFeatures: type: object description: A map of configurations indicating which features are available for the plan additionalProperties: $ref: '#/components/schemas/FeaturePlanConfiguration' 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' SubscriptionStateType: type: string description: This represents the type of resource object being returned. Always `subscription_state`. example: subscription_state enum: - subscription_state 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' SubscriptionMeta: readOnly: true required: - owner - timestamps - status - canceled - paused - closed - pending - suspended - invoice_after - manual_payments - first_invoice_prepaid properties: owner: $ref: '#/components/schemas/OwnerMeta' timestamps: $ref: '#/components/schemas/SubscriptionTimestamps' status: $ref: '#/components/schemas/Status' state: $ref: '#/components/schemas/SubscriptionState' manual_payments: $ref: '#/components/schemas/ManualPayments' first_invoice_prepaid: type: boolean description: Indicates that the first billing period of this subscription was paid for outside of the subscriptions service. example: false canceled: type: boolean description: Whether a subscription is canceled or not. example: true paused: type: boolean description: Whether a subscription is paused or not. example: true closed: type: boolean description: Whether a subscription is closed or not. example: true suspended: type: boolean description: Whether a subscription is suspended or not. example: false pending: type: boolean description: Whether a subscription is pending activation or not. example: false invoice_after: description: The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point. type: string example: '2017-01-10T11:41:19.244842Z' pending_price_change: $ref: '#/components/schemas/SubscriptionPriceChanges' price_update_history: description: A history of price updates that have been applied to this subscription. type: array x-go-type-skip-optional-pointer: true items: $ref: '#/components/schemas/SubscriptionPriceUpdateHistoryEntry' OfferingBuildConfiguredFeatures: type: object description: Map of feature configurations keyed by plan UUID or external_ref additionalProperties: $ref: '#/components/schemas/OfferingBuildPlanFeatures' 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' ManyRelationship: description: The list of resources that are related. properties: data: type: array items: $ref: '#/components/schemas/RelationshipData' links: $ref: '#/components/schemas/RelationshipLinks' 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. 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 FeatureAccessAttributes: required: - type - tag properties: type: type: string enum: - access example: access tag: $ref: '#/components/schemas/FeatureTag' 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' 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' 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' 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. 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 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 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' PricingOptionPrice: properties: base_price_percentage: type: number format: double description: A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering. example: 90 minimum: 0 maximum: 100 fixed_price: $ref: '#/components/schemas/Price' NotificationSchedule: type: object required: - name - unit - amount properties: name: type: string description: The name of the schedule. minLength: 1 maxLength: 1024 example: Daily billing run. unit: type: string description: The unit of time that the schedule is measured in. example: day enum: - day - week - month x-go-type: model.NotificationScheduleUnit x-go-type-import: name: model path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model amount: type: integer format: int64 description: The number of units between each notification. example: 100 minimum: 1 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' 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 OfferingPlanPriceForPricingOption: properties: price: $ref: '#/components/schemas/Price' display_price: $ref: '#/components/schemas/DisplayPrice' SubscriptionInvoiceType: description: This represents the type of resource object being returned. Always `subscription_invoice`. type: string example: subscription_invoice enum: - subscription_invoice OwnerMeta: readOnly: true type: string format: string description: The owner of a resource, either `store` or `organization`. example: store CreatePaymentAuthorityEPPayments: writeOnly: true type: object required: - type - customer_id - card_id properties: type: description: The name of the payment gateway facilitating the secure transmission of payment data. type: string example: elastic_path_payments_stripe enum: - elastic_path_payments_stripe x-go-type: paymentgateways.GatewayName x-go-type-import: name: paymentgateways path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways customer_id: description: The unique identifier for a customer. type: string minLength: 3 maxLength: 1024 example: cus_OPfKlxWV3hp9h6 card_id: description: The unique identifier of the card used to facilitate payment of the subscription. type: string minLength: 3 maxLength: 1024 example: card_8Diw3FQPhxK27WADPVMeXieP SubscriptionInvoiceMeta: readOnly: true required: - owner - timestamps - proration_events - pro_rata_remaining_value - display_price properties: owner: $ref: '#/components/schemas/OwnerMeta' subscription_id: $ref: '#/components/schemas/UUID' subscriber_id: $ref: '#/components/schemas/UUID' price: $ref: '#/components/schemas/SingleCurrencyPrice' display_price: description: 'Invoice totals formatted for display (`with_tax`, `without_tax`, `tax`). Amounts are in the currency''s smallest subdivision. ' $ref: '#/components/schemas/DisplayPrice' notifications: description: 'A list of notifications scheduled for this invoice. These are derived from the notification schedules configured on the pricing option at the time the invoice was created. Each notification has a due date calculated relative to the billing period end date. ' type: array items: $ref: '#/components/schemas/InvoiceNotification' timestamps: $ref: '#/components/schemas/InvoiceTimestamps' proration_events: type: array items: $ref: '#/components/schemas/ProrationEvent' pro_rata_remaining_value: type: integer format: int64 description: The pro-rated remaining value for the billing period example: 500 OfferingPricingOptionPriceForPlan: readOnly: true properties: price: $ref: '#/components/schemas/Price' display_price: $ref: '#/components/schemas/DisplayPrice' 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' PricingOptionResponseAttributes: allOf: - $ref: '#/components/schemas/PricingOptionAttributes' - $ref: '#/components/schemas/Timestamps' OfferingPlanResponseAttributes: allOf: - $ref: '#/components/schemas/PlanResponseAttributes' - $ref: '#/components/schemas/OfferingPlanResponseExtraAttributes' 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' SubscriptionStateAttributes: required: - action properties: action: $ref: '#/components/schemas/SubscriptionStateAction' cancel_immediately: type: boolean default: false example: false description: 'When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request, and a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation. Subscribers may not set this to `true` and will receive a 403. Immediate cancellation does **not** trigger any sort of refund; those require separate API flows. ' responses: 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 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' 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' UnprocessableContent: description: Unprocessable Content. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: cannot-process-refund: value: errors: - title: Unprocessable Content status: '422' detail: 'Unprocessable Content: cannot process the refund' 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' parameters: 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 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 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) 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 securitySchemes: BearerToken: type: http scheme: bearer