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 Invoices 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: 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:\n\n- an itemized list of goods and services provided by a subscription.\n- the cost of a subscription.\n- if applicable, any taxes.\n\nThe invoice lifecycle is described below.\n\n1. 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.\n2. 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.\n3. Invoices where `tax_required` is `true` will not have payment taken until a tax run has added the required tax to the invoice.  \n3. 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.\n\n### Payment Retries\n\nIt 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.\n\nIn 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. \n\nOnce the number of payment retries reaches the limit, the payment retries stop, resulting in status of the invoice being unpaid. See [Invoices](#invoices).\n\nWhen configuring payment retries, you have the following options.\n\n| Attribute | Required | Description |\n| --- | --- | --- |\n| `payment_retry_type` | Optional | One of the following options: <ul><li>`fixed` - use `fixed` if you want a fixed time interval between payment retries.</li><li>`backoff` - use `backoff` if you want the time between retry attempts to increase exponentially.</li><li>`tiered` - use `tiered` if you want to specify a list of time durations.</li></ul>  |\n| `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.  |\n| `payment_retry_multiplier` | Optional | Use when `payment_retry_type` is `tiered` and represents the factor by which the time duration increases after each retry.   |\n| `payment_retry_unit` | Optional | Represents the unit of time, either `day` or `week`. |\n\n### Rounding\n\nSubscriptions always rounds down to the penny. \n\n### Tax\n\nSubscriptions allows you to apply any number of tax rates to your invoices and subscriptions. When applying a tax rate, you must specify:\n\n- a name that appears on your customer's invoice that describes the specific type of tax.\n- the tax rate which is the percentage of the subscription amount that is required to be paid as tax.\n\nIn addition, you can optionally specify the jurisdiction which is the geographic area or political entity that has authority to levey and collect taxes.\n\nYou can apply more than one tax rate for all items in an invoice. You cannot apply a tax rate per line item.\n\n### Payments\n\nWhen 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:\n\n- 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. \n- Authorize.Net. \n\n#### Using Elastic Path Payments Powered by Stripe\n\nTo use Elastic Path Payments Powered by Stripe gateway, contact the [**Customer Success Team**](mailto:customersuccess@elasticpath.com). \n\nCreate 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).\n\nOnce 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).\n\n#### Using Authorize.Net\n\nTo use Authorize.Net, you must have: \n\n- an active merchant account with Authorize.Net\n- obtained API credentials. These include an **API Login ID** and a **Transaction Key**.\n- Enabled Authorize.Net in Commerce Manager. See [Enabling Authorize.net](/docs/commerce-manager/payments/configure-other-payment-gateways#enabling-authorizenet).\n\n#### Payment Requests\n\nSubscriptions 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. \n\nWhen sending a payment request to the Payments service, you must specify the following.\n\n| Attribute | Required | Description |\n| --- | --- | --- |\n| `gateway` | Required| One of `elastic_path_payments_stripe`, `authorize_net` and `stripe_payment_intents`. |\n| `method` | Required | Must be `purchase`.\n| `payment` | Required | The type of payment, for example, `pm_card_visa_debit`.\n| `options` | Required | These options must be set as they set up the card to be used in future without the customer being present. If these options are not set, future payments may fail. There are two options. <ul><li>`off_session`. Must be set to `true`. </li><li>`confirm`. Must be set to `true`.</li></ul> |\n\n#### External Payments\n\nExternal 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).\n\nWhen a subscription is created with `manual_payments` set to `true`:\n\n1. 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. \n2. 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.\n3. 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. \n    - If payment is successful, the invoice is updated to `paid` and the billing/payment cycle continues as normal.\n    - 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`.\n\n#### Card Declines\n\nCard 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.\n"
paths:
  /v2/subscriptions/invoices:
    get:
      tags:
      - Invoices
      summary: List invoices
      description: "Retrieves a list of all invoices.\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` | `subscriber_id`, `subscription_id`, `outstanding`, `tax_required` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |\n| `in` | `subscriber_id`, `subscription_id` | In. Checks if the value is in the specified list. If it is, the condition is true. |\n"
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/PageLimit'
      operationId: ListInvoices
      responses:
        '200':
          description: Success. A list of invoices is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubscriptionInvoice'
                  links:
                    $ref: '#/components/schemas/Links'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/subscriptions/invoices/{invoice_uuid}:
    parameters:
    - name: invoice_uuid
      in: path
      description: The unique identifier of the invoice.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    get:
      tags:
      - Invoices
      summary: Get invoice
      operationId: GetInvoice
      responses:
        '200':
          description: Success. The details of the invoice are returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionInvoice'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/subscriptions/invoices/{invoice_uuid}/payments:
    parameters:
    - name: invoice_uuid
      in: path
      description: The unique identifier of the invoice.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    get:
      tags:
      - Invoices
      summary: List invoice payments
      parameters:
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/PageLimit'
      operationId: ListInvoicePayments
      responses:
        '200':
          description: Success. Payments for the invoice are returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubscriptionInvoicePayment'
                  links:
                    $ref: '#/components/schemas/Links'
  /v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}:
    parameters:
    - name: invoice_uuid
      in: path
      description: The unique identifier of the invoice.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    - name: payment_uuid
      in: path
      description: The unique identifier of the payment.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    get:
      tags:
      - Invoices
      summary: Get invoice payment
      operationId: GetInvoicePayment
      responses:
        '200':
          description: Success. Specific payment for the invoice is returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionInvoicePayment'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      tags:
      - Invoices
      summary: Update Invoice Payment
      description: 'External payment methods are payment methods not offered by Elastic Path Subscriptions (such as Elastic Path Payments powered by Stripe or Authorize.net), but they can still be integrated with Subscriptions. You can use the `Update Invoice Payment` endpoint to manually update a payment against an invoice where an external payment method is handling the payment of your invoices. See [External Payments](/docs/api/subscriptions/invoices#external-payments).

        '
      operationId: UpdateInvoicePayment
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/UpdateInvoicePayment'
      responses:
        '200':
          description: Success. Invoice payment has been updated.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionInvoicePayment'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/WriteConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}/refunds:
    parameters:
    - name: invoice_uuid
      in: path
      description: The unique identifier of the invoice.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    - name: payment_uuid
      in: path
      description: The unique identifier of the payment.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    post:
      operationId: CreateInvoicePaymentRefund
      summary: Create a refund for an invoice payment
      description: Creates a refund for a paid invoice.
      tags:
      - Invoices
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/CreateInvoicePaymentRefund'
      responses:
        '201':
          description: Success. The payment refund is completed.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionInvoicePaymentRefund'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      parameters:
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/PageLimit'
      operationId: ListInvoicePaymentRefunds
      summary: List invoice payment refunds
      description: List all refunds for an invoice payments
      tags:
      - Invoices
      responses:
        '200':
          description: Success. Refunds for an invoice payment are returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubscriptionInvoicePaymentRefund'
                  links:
                    $ref: '#/components/schemas/Links'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}/refunds/{refund_uuid}:
    parameters:
    - name: invoice_uuid
      in: path
      description: The unique identifier of the invoice.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    - name: payment_uuid
      in: path
      description: The unique identifier of the payment.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    - name: refund_uuid
      in: path
      description: The unique identifier of the refund.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    get:
      operationId: GetInvoicePaymentRefund
      summary: Get a refund for an invoice payment
      description: Get a refund for a paid invoice.
      tags:
      - Invoices
      responses:
        '200':
          description: Success. Specific refund for the invoice payment is returned
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionInvoicePaymentRefund'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    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
  schemas:
    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
    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.
    ManyRelationship:
      description: The list of resources that are related.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RelationshipData'
        links:
          $ref: '#/components/schemas/RelationshipLinks'
    SubscriptionInvoicePaymentRefundType:
      type: string
      description: This represents the type of resource object being returned. Always `subscription_invoice_payment_refund`.
      example: subscription_invoice_payment_refund
      enum:
      - subscription_invoice_payment_refund
    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.
    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'
    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'
    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
    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
    ErrorResponse:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Link'
    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
    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
    Relationship:
      anyOf:
      - $ref: '#/components/schemas/SingleRelationship'
      - $ref: '#/components/schemas/ManyRelationship'
    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
    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'
    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
    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
    CreateInvoicePaymentRefund:
      required:
      - type
      - attributes
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionInvoicePaymentRefundType'
        attributes:
          type: object
          required:
          - amount
          - reason
          properties:
            amount:
              type: integer
              format: int64
              minimum: 1
              description: The value as a whole number of the currency's smallest subdivision.
              example: 100
            reason:
              type: string
              minLength: 1
              maxLength: 1024
              description: The reason or note for the refund
              example: Customer requested cancellation
    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'
    SingleRelationship:
      description: The subscription resource that is related.
      properties:
        data:
          $ref: '#/components/schemas/RelationshipData'
        links:
          $ref: '#/components/schemas/RelationshipLinks'
    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
    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'
    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'
    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
    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'
    SubscriptionInvoicePaymentRefund:
      required:
      - id
      - type
      - attributes
      - relationships
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionInvoicePaymentRefundType'
        attributes:
          $ref: '#/components/schemas/SubscriptionInvoicePaymentRefundAttributes'
        relationships:
          $ref: '#/components/schemas/Relationships'
    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
    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'
    PaymentFailureDetail:
      type: object
      description: The reason the payment failed.
      properties:
        reason:
          type: string
          example: Card Failure
    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'
    UpdateInvoicePayment:
      required:
      - id
      - type
      - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionInvoicePaymentType'
        attributes:
          $ref: '#/components/schemas/UpdateInvoicePaymentAttributes'
    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
    SubscriptionInvoicePaymentRefundAttributes:
      required:
      - amount
      - reason
      - gateway
      - external_refund_id
      - created_at
      properties:
        amount:
          type: integer
          format: int64
          minimum: 1
          description: The value as a whole number of the currency's smallest subdivision.
          example: 100
        reason:
          type: string
          maxLength: 1024
          description: The reason or note for the refund
          example: Customer requested cancellation
        gateway:
          type: string
          maxLength: 1024
          example: elastic_path_payments_stripe
          description: Specifies the payment gateway.
        external_refund_id:
          type: string
          maxLength: 1024
          example: 33e7ec6b-8b34-4c92-a95b-2e2647922e47
          description: An optional external ID that is specific to the gateway used.
        created_at:
          description: The date and time a resource was created.
          type: string
          example: '2017-01-10T11:41:19.244842Z'
    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
    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'
  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
    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'
    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'
    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'
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer