Elastic Path Dunning Rules API

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 Dunning Rules 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: Dunning Rules
  description: "\nDunning is the process of handling failed payment attempts. This is important for recovering revenue from failed payments, reduces customer churn and maintains cashflow. By implementing efficient dunning processes, you can enhance financial health and operational efficiency.\n\nSubscriptions enables you to create a dunning rule that allows you to configure payment retry schedules. Subscriptions retries failed payments automatically. You can customize the timing and frequency of the payment retries.\n\nDunning is enabled by default. You can choose to disable dunning. If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments.\n\n- Do nothing - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.\n- Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.\n- close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment. \n"
paths:
  /v2/subscriptions/dunning-rules:
    post:
      tags:
      - Dunning Rules
      summary: Create a dunning rule
      description: "Dunning rules must use a `fixed` strategy. This means payments are retried on a fixed schedule. \n\nWhen an invoice is created, it immediately becomes eligible for payment by the next payment run. If the first payment attempt fails then the invoice enters dunning. In subsequent payment runs, invoices are only  considered for payment if they meet the dunning rules you create.\n\nYou can configure a dunning rule to be the default for your store. There can only be one default rule per store. All invoices in your store will then perform dunning according to the specified rules. \n\n:::note\nIf no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments.\n:::\n\nThe following attributes are used to define a `fixed` schedule:\n\n- `payment_retry_unit - the unit of time used to measure the intervals between payment attempts or retries. \n- `payment_retry_interval` - the number of `payment_interval-units` to wait between each payment retry attempt.\n- `payment_retries_limit` - the number of times subscriptions attempts payments retries before an `action` is taken.\n- `action` - the action to take if payment is not successful.\n\nFor example, if:\n\n- the `payment_retry_unit` is `days` \n- the `payment_retry_interval` is `2`\n- the `payment_rety_limit` is `10`\n- the `action` is `close`.\n\nSubscriptions attempts to retry the payment every 2 days until 10 payment attempts have been tried. At that point, the subscription ends and it's status changes to `inacive`. \n\nFollowing on from this, you can specify that the dunning rule is no longer the default. You do not have to specify another rule to replace it. If you do remove the default dunning rule, the store defaults to the behavior that is followed when dunning is not enabled.\n"
      operationId: CreateDunningRule
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/DunningRuleCreate'
      responses:
        '201':
          description: Success. The dunning rule set is created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DunningRule'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Dunning Rules
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/PageLimit'
      summary: List dunning rules
      description: 'Retrieves a list of all dunning rule sets.

        '
      operationId: ListDunningRules
      responses:
        '200':
          description: Success. A list of dunning rules is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DunningRule'
                  links:
                    $ref: '#/components/schemas/Links'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/subscriptions/dunning-rules/{dunning_rule_uuid}:
    parameters:
    - name: dunning_rule_uuid
      in: path
      description: The unique identifier of a dunning rule set.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    get:
      tags:
      - Dunning Rules
      summary: Get dunning rule policy
      operationId: GetDunningRule
      responses:
        '200':
          description: Success. The dunning rule details are returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DunningRule'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Dunning Rules
      summary: Update dunning rule policy
      description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the rule is not updated. For fields that are optional, an existing value can be removed by specifying a value of null.
      operationId: UpdateDunningRule
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/DunningRuleUpdate'
      responses:
        '200':
          description: Success. The dunning rule set has been updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DunningRule'
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/WriteConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Dunning Rules
      summary: Delete dunning rules
      description: You can delete a dunning rule at any time. If a dunning rule is deleted then Subscriptions reverts to the configuration used if no dunning rule is set; payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments. See [Dunning Rules](/docs/api/subscriptions/dunning-rules).
      operationId: DeleteDunningRule
      responses:
        '204':
          description: Success. The dunning rule is removed.
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    DunningRuleAttributes:
      description: 'The dunning rule attributes you can use to configure your payment retry strategy.

        '
      example:
        payment_retry_type: fixed
        payment_retry_unit: day
        payment_retry_interval: 1
        payment_retries_limit: 10
        action: none
      required:
      - payment_retry_type
      - payment_retries_limit
      - action
      properties:
        payment_retry_type:
          type: string
          enum:
          - fixed
          - backoff
          - tiered
          example: fixed
          description: 'The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.

            '
          x-go-type: model.PaymentRetryType
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model
        payment_retry_interval:
          type: integer
          format: int64
          minimum: 1
          maximum: 1024
          example: 1
          description: The number of `payment_interval_unit`s to wait between each payment retry attempt.
        payment_retry_unit:
          type: string
          enum:
          - day
          - week
          example: day
          description: The unit of time used to measure the intervals between payment attempts or retries.
          x-go-type: model.PaymentRetryUnit
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model
        payment_retry_multiplier:
          type: number
          format: double
          minimum: 1
          maximum: 1024
          example: 1
          description: The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types.
        payment_retries_limit:
          type: integer
          format: int64
          minimum: 0
          example: 5
          description: The number of times Subscriptions attempts payment retries before `action` is taken.
        action:
          type: string
          enum:
          - none
          - pause
          - close
          - suspend
          example: none
          description: 'The action to take after all payment attempts for an invoice have failed.


            - None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.

            - Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.

            - close a subscription. The subscription ends and it''s status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.

            '
          x-go-type: model.DunningAction
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model
        default:
          type: boolean
          example: false
          description: Set to `true` if you want this rule to be the default for the store.
    SubscriptionDunningRuleType:
      type: string
      example: subscription_dunning_rule
      enum:
      - subscription_dunning_rule
    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'
    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
    ErrorResponse:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Link'
    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
    DunningRuleMeta:
      readOnly: true
      required:
      - owner
      - timestamps
      properties:
        owner:
          $ref: '#/components/schemas/OwnerMeta'
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    DunningRuleCreate:
      required:
      - type
      - attributes
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionDunningRuleType'
        attributes:
          $ref: '#/components/schemas/DunningRuleAttributes'
    DunningRuleUpdateAttributes:
      properties:
        payment_retry_type:
          type: string
          enum:
          - fixed
          - backoff
          - tiered
          example: fixed
          description: 'The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.

            '
          x-go-type: model.PaymentRetryType
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model
        payment_retry_interval:
          type: integer
          format: int64
          minimum: 1
          maximum: 1024
          example: 1
          description: The number of `payment_interval_unit`s to wait between each payment retry attempt.
          nullable: true
        payment_retry_unit:
          type: string
          enum:
          - day
          - week
          example: day
          description: The unit of time used to measure the intervals between payment attempts or retries.
          nullable: true
          x-go-type: model.PaymentRetryUnit
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model
        payment_retry_multiplier:
          type: number
          format: double
          minimum: 1
          maximum: 1024
          example: 1
          description: The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types.
          nullable: true
        payment_retries_limit:
          type: integer
          format: int64
          minimum: 0
          example: 5
          description: The number of times Subscriptions attempts payment retries before `action` is taken.
        action:
          type: string
          enum:
          - none
          - pause
          - close
          - suspend
          example: none
          description: The action to take after all payment attempts for an invoice have failed.
          x-go-type: model.DunningAction
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model
        default:
          type: boolean
          example: false
          description: Set to `true` if you want this rule to be the default for the store.
    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
    OwnerMeta:
      readOnly: true
      type: string
      format: string
      description: The owner of a resource, either `store` or `organization`.
      example: store
    DunningRuleUpdate:
      required:
      - id
      - type
      - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionDunningRuleType'
        attributes:
          $ref: '#/components/schemas/DunningRuleUpdateAttributes'
    DunningRule:
      required:
      - type
      - attributes
      - meta
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionDunningRuleType'
        attributes:
          $ref: '#/components/schemas/DunningRuleAttributes'
        meta:
          $ref: '#/components/schemas/DunningRuleMeta'
  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
  responses:
    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'
    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
    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