> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Cancel a recurring series > Stops the series at the payer's request and, with it, the occurrences already materialized for it that are still PENDING. It is the right call when the payer wants the standing payment to end; to drop a single date and keep the series running, cancel that occurrence through POST /v1/scheduled-payments/{schedule_id}/cancel instead. Nothing is released -- nothing was held. WHAT IT DOES NOT STOP. It moves only PENDING occurrences to CANCELLED. It does not change an occurrence in any other status (EXECUTING, DISPATCHED_OUTCOME_UNKNOWN, AWAITING_RETRY, SETTLED, FAILED or CANCELLED), and skippedOccurrences counts those. READING THE RESPONSE. cancelledOccurrences and skippedOccurrences PARTITION the occurrences the series had: every one of them is in exactly one count, which is what lets a client reconcile the figures against the pending occurrences it was displaying a moment earlier. They describe THIS request and are not properties of the series -- re-reading the series afterwards does not report them again. CANCELLING TWICE. The second request meets a series that is already CANCELLED and is refused with PIX-0765, whether or not the replay cache is reachable. The occurrences the first request stopped do not return to PENDING, so a repeat can never undo it. A COMPLETED SERIES CAN STILL BE CANCELLED. completed means every occurrence the series will ever have has been created -- not that they have been paid. A short series reaches that state while every one of its payments is still in the future, so this route accepts it and stops the pending occurrences. A series that really has finished paying is accepted too and truthfully reports zero cancelled. ## OpenAPI ````yaml /en/openapi/v3-current/pix-lerian-spi.yaml post /scheduled-payment-recurrences/{recurrence_id}/cancel openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: Public API for outbound Pix transfers, refunds, and scheduled payments. license: name: Lerian Studio General License title: Pix Lerian — Payments version: 1.1.0 servers: - url: https://api.example.com/spi/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, list, and retrieve Pix refunds. name: Refunds - name: Scheduled Payments description: Register, list, retrieve, and cancel scheduled Pix payments. - description: Initiate, process, list, and retrieve outbound Pix transfers. name: Transfers - description: >- Register, list, retrieve, and cancel recurring series of scheduled Pix payments. name: Scheduled Payment Recurrences paths: /scheduled-payment-recurrences/{recurrence_id}/cancel: post: tags: - Scheduled Payment Recurrences summary: Cancel a recurring series description: >- Stops the series at the payer's request and, with it, the occurrences already materialized for it that are still PENDING. It is the right call when the payer wants the standing payment to end; to drop a single date and keep the series running, cancel that occurrence through POST /v1/scheduled-payments/{schedule_id}/cancel instead. Nothing is released -- nothing was held. WHAT IT DOES NOT STOP. It moves only PENDING occurrences to CANCELLED. It does not change an occurrence in any other status (EXECUTING, DISPATCHED_OUTCOME_UNKNOWN, AWAITING_RETRY, SETTLED, FAILED or CANCELLED), and skippedOccurrences counts those. READING THE RESPONSE. cancelledOccurrences and skippedOccurrences PARTITION the occurrences the series had: every one of them is in exactly one count, which is what lets a client reconcile the figures against the pending occurrences it was displaying a moment earlier. They describe THIS request and are not properties of the series -- re-reading the series afterwards does not report them again. CANCELLING TWICE. The second request meets a series that is already CANCELLED and is refused with PIX-0765, whether or not the replay cache is reachable. The occurrences the first request stopped do not return to PENDING, so a repeat can never undo it. A COMPLETED SERIES CAN STILL BE CANCELLED. completed means every occurrence the series will ever have has been created -- not that they have been paid. A short series reaches that state while every one of its payments is still in the future, so this route accepts it and stops the pending occurrences. A series that really has finished paying is accepted too and truthfully reports zero cancelled. operationId: cancelScheduledPaymentRecurrence parameters: - description: >- REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Series identifier. in: path name: recurrence_id required: true schema: description: Series identifier. examples: - 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 format: uuid type: string responses: '200': content: application/json: example: recurrenceId: 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 status: CANCELLED cancelledOccurrences: 5 skippedOccurrences: 1 schema: $ref: '#/components/schemas/RecurrenceCancellationView' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Two shapes share this status, one per media type. application/problem+json: recurrence_id is not a UUID (PIX-0015). The response names the parameter; the series is never looked up. application/json is the legacy {code,title,message} envelope, from the idempotency gate: X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- No series with that identifier exists for this organization (PIX-0760). A series belonging to another organization answers this too: the write is scoped by the organization on the validated credential, so the row is never seen, and answering 'forbidden' would confirm the identifier exists somewhere. '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The series has already been cancelled (PIX-0765). Re-read it rather than retrying: this is the durable backstop behind the degrading idempotency posture, and it is also the answer a repeated cancellation gets. A COMPLETED series is NOT refused -- completed means every occurrence the series will ever have has been created, not that they have been paid, so its pending occurrences are still stoppable here. '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: >- The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter) or body (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: RecurrenceCancellationView: additionalProperties: false properties: cancelledOccurrences: description: >- How many occurrences this request moved to CANCELLED. It counts ONLY the ones that were still PENDING, and it is the row count of the write itself rather than a census taken beforehand. examples: - 5 format: int64 type: integer recurrenceId: description: The series that was stopped. examples: - 01a0d8fb-1a8b-7a10-b3c4-d5e6f7a8b9c0 type: string skippedOccurrences: description: >- How many materialized occurrences this request did not change, because they were not PENDING. Together with cancelledOccurrences it accounts for every occurrence the series had. examples: - 1 format: int64 type: integer status: description: >- The series' status after the operation. Always CANCELLED on a 200 -- a series that could not be stopped answers PIX-0765 instead of reporting an unchanged status. enum: - ACTIVE - COMPLETED - CANCELLED examples: - CANCELLED type: string required: - recurrenceId - status - cancelledOccurrences - skippedOccurrences type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.