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