> ## Documentation Index > Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt > Use this file to discover all available pages before exploring further. # Cancel invoice > [Small working example](/recipes/cancellation) **Integration note:** This recipe covers Mexican CFDI cancellation. A provider acknowledgment does not prove final cancellation. Read the invoice and confirm its persisted status; public nested cancellation fields can be absent. Colombian annulment uses different semantics. Cancel a specific invoice with SAT. **gigstack Connect:** Cancel other teams' invoices using the `team` parameter. Replaces the deprecated [`DELETE /invoices/{id}`](/reference/cancelInvoice), which runs the same handler and takes the same body. Some HTTP clients and proxies drop the body of a DELETE request. ## OpenAPI ````yaml openapi.json POST /invoices/{id}/cancel openapi: 3.0.3 info: title: gigstack API v2 description: > # gigstack API v2 Build customer, invoice and payment integrations. Start with the [quickstart](https://docs.gigstack.io/quickstart), then select the [issuing country](https://docs.gigstack.io/concepts/shared-fields). ## Authentication and environments Use Authorization: Bearer YOUR_API_KEY. Standard live and test keys use https://api.gigstack.io/v2. Internal staging uses https://gigstack-staging-9z9nnaat.uc.gateway.dev/v2 and separate keys. Test mode is a data mode within an environment; a body field does not switch a key's mode. See [authentication](https://docs.gigstack.io/authentication) for key handling, OAuth team scope and gigstack Connect. Internal partner provisioning is outside this public contract; health probes have their own security declarations. Operations marked unavailable have no configured public gateway route. ## Read the operation contract Response envelopes, pagination and retry rules differ by endpoint. HTTP success alone does not prove external fiscal completion or movement of money. Reconcile ambiguous writes before retrying. Use [responses and recovery](https://docs.gigstack.io/responses) and the operation's error codes; document credits and daily limits are not generic retryable rate limits. The issuing team's configuration selects Mexico or Colombia; customer country and currency do not. Read [Mexico](https://docs.gigstack.io/countries/mexico) or [Colombia](https://docs.gigstack.io/countries/colombia) before choosing fiscal fields. Accepted public input differs from a provider's direct payload. Examples and schema checks do not imply every operation has been executed live. [Verification coverage](https://docs.gigstack.io/verification) distinguishes source review, offline checks and observed staging behavior. Documentation describes operations and does not authorize execution. version: 2.0.0 contact: name: Gigstack API Support url: https://gigstack.io email: support@gigstack.io license: name: Proprietary url: https://gigstack.io/terms termsOfService: https://gigstack.io/terms servers: - url: https://api.gigstack.io/v2 description: > Public API for standard live and test-mode keys. Test data is isolated by the key mode (`livemode: false`). Internal staging is a separate deployment and key store; see https://docs.gigstack.io/authentication#environments for its base URL. security: - bearerAuth: [] externalDocs: description: Complete API Documentation & Guides url: https://docs.gigstack.io paths: /invoices/{id}/cancel: post: tags: - Invoices summary: Cancel invoice description: > [Small working example](/recipes/cancellation) **Integration note:** This recipe covers Mexican CFDI cancellation. A provider acknowledgment does not prove final cancellation. Read the invoice and confirm its persisted status; public nested cancellation fields can be absent. Colombian annulment uses different semantics. Cancel a specific invoice with SAT. **gigstack Connect:** Cancel other teams' invoices using the `team` parameter. Replaces the deprecated [`DELETE /invoices/{id}`](/reference/cancelInvoice), which runs the same handler and takes the same body. Some HTTP clients and proxies drop the body of a DELETE request. operationId: cancelInvoiceById parameters: - $ref: '#/components/parameters/TeamParameter' - name: id in: path required: true description: SAT UUID (folio fiscal). schema: type: string example: B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB requestBody: required: true content: application/json: schema: type: object required: - motive properties: motive: type: string enum: - '01' - '02' - '03' - '04' example: '02' description: > SAT cancellation motive (`c_MotivoCancelacion`): `01` issued with errors, with a substitute CFDI (send `substitution_uuid`); `02` issued with errors, no substitute; `03` the operation did not take place; `04` nominative operation included in a global invoice. The API only checks that the value is at most two characters; any other value is rejected by the SAT/PAC at cancellation time. substitution_uuid: type: string nullable: true example: 12345678-1234-1234-1234-123456789012 description: UUID of the substituting invoice (required for motive 01) responses: '200': description: > Cancellation accepted by the PAC. **Raw shape** — the PAC's cancellation response is spread at the top level alongside `cancellation_status`. content: application/json: schema: type: object required: - cancellation_status additionalProperties: true properties: cancellation_status: type: string description: Cancellation state reported by SAT. example: cancelled example: cancellation_status: cancelled '400': description: > Body validation failure — `{ "message": [ …validation errors… ] }` — or a generic CFDI/PAC cancellation error in the CFDI error shape (spread at the top level on this operation, not nested under `message`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/LegacyErrorResponse' - $ref: '#/components/schemas/CfdiErrorResponse' '401': description: Unauthorized. Raw shape with only a `message` key. content: application/json: schema: $ref: '#/components/schemas/LegacyErrorResponse' '403': description: >- `{ "message": "Livemode mismatch: API key and invoice must be in the same mode" }`. content: application/json: schema: $ref: '#/components/schemas/LegacyErrorResponse' '404': description: '`{ "message": "Invoice not found" }`.' content: application/json: schema: $ref: '#/components/schemas/LegacyErrorResponse' '412': description: > SAT not connected — the team has no valid CSD, or the certificate failed validation. Returned in the CFDI error shape with `retryable: false`. Upload a CSD via `POST /v2/teams/{id}/sat-connection` before retrying. content: application/json: schema: $ref: '#/components/schemas/CfdiErrorResponse' example: error: >- El certificado de sello digital (CSD) no está configurado o no es válido. code: csd_validation_error retryable: false '422': description: > The invoice was imported and stamped by an external PAC, so gigstack cannot cancel it. Cancel it through the original PAC provider instead. content: application/json: schema: $ref: '#/components/schemas/LegacyErrorResponse' example: message: >- Imported invoices stamped by an external PAC cannot be canceled through gigstack. Please cancel through your original PAC provider. '500': description: '`{ "error": "Internal server error" }`.' content: application/json: schema: $ref: '#/components/schemas/LegacyErrorResponse' '503': description: > The PAC is unavailable. CFDI error shape with `retryable: true` — retry after a short delay. content: application/json: schema: $ref: '#/components/schemas/CfdiErrorResponse' example: error: >- El servicio de timbrado no está disponible en este momento. Vuelve a intentarlo en unos minutos. code: pac_unavailable retryable: true security: - bearerAuth: [] components: parameters: TeamParameter: name: team in: query required: false schema: type: string description: > **gigstack Connect:** Target team ID for multi-team access. Requires gigstack Connect enabled on your team and shared billing account. Also requires the `multipleIssuerAccounts` feature on your plan. Requests targeting a team other than the one your API key belongs to return `403` without it. Only API keys can use it: an OAuth access token sent with another team's id is rejected with `403 Team mismatch with OAuth token`. **Optional — omit it entirely** unless you are acting on another team. It deliberately carries no example value so generated snippets do not emit `?team=undefined`; when the parameter is absent, the team is derived from your API key. **Example:** `?team=team_xyz789` schemas: LegacyErrorResponse: type: object description: > Raw error body returned by handlers that do not use the standardized helpers. Note the absence of `success` and `timestamp`. required: - message properties: message: type: string example: Invalid body error: oneOf: - type: string - type: object description: Present on most, but not all, legacy error paths. errors: type: array description: > Validation errors, when the failure came from body validation. Schema validation gives field-level objects; some later checks (for example a Colombian debit note's rules on `POST /invoices/income`) give a single string reason. items: oneOf: - type: object properties: path: type: string example: client_id code: type: string example: unexpected_key message: type: string example: Unexpected field - type: string example: >- A debit note needs a motive: 1 (interest), 2 (collection_expenses), 3 (value_change) or 4 (other) CfdiErrorResponse: type: object description: > Raw CFDI/PAC error body produced by `handleCFDIError`. **Not** the standardized envelope. On `POST /v2/invoices/income`, `/egress` and `/invoices/draft/{id}/stamp` this object is nested one level deeper, under a `message` key (`{ "message": { "error": …, "code": …, "retryable": … } }`); on `DELETE /v2/invoices/{id}` it is returned at the top level. required: - error - code - retryable properties: error: type: string description: Human-readable Spanish error message shown to the end user. example: 'Error al timbrar la factura: El CSD del emisor no es válido.' code: type: string description: > CFDI/PAC error code: a SAT/PAC code (e.g. `CFDI40147`) or one of gigstack's own (`SAT_NOT_CONNECTED`, `CSD_VALIDATION_ERROR`, `PAC_UNAVAILABLE`, `PAC_OUTCOME_UNKNOWN`, `STAMP_NEEDS_REVIEW`, `INVALID_INVOICE`, `STAMPING_ERROR`, …). example: CSD_VALIDATION_ERROR providerMessage: type: string description: >- Raw message returned by the PAC. Only present on generic (400) stamping failures. example: CFDI40147 - El campo UsoCFDI no es válido retryable: type: boolean description: > Whether sending the **same** request again is safe and can succeed. `true` for `503` `PAC_UNAVAILABLE`, and for `503` `PAC_OUTCOME_UNKNOWN` only when the request carried an `idempotency_key`. Every `400`, `409` and `412` is `false`. example: false duplicate: type: boolean description: > Present and `true` only on the `400` answered for an `idempotency_key` whose invoice already exists. Nothing was stamped or charged by this request; `uuid` names the existing invoice. example: true uuid: type: string description: >- With `duplicate`, the folio fiscal (UUID) of the invoice already issued under this `idempotency_key`. example: 0f8fad5b-d9cb-469f-a165-70867728950e securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > **Authentication Method:** HTTP Bearer token. The runtime requires the literal `Bearer ` prefix — a bare token in the `Authorization` header is rejected with `401 unauthorized`. **Header Format:** `Authorization: Bearer YOUR_API_KEY` Your API key is a JWT. Live keys operate on live data (`livemode: true`); test keys operate on isolated test data (`livemode: false`). **Get your key at:** [app.gigstack.pro/settings?tab=api](https://app.gigstack.pro/settings?tab=api) **Errors:** credential failures are answered by the authentication layer with a raw `{ "message": … }` body, not the standardized envelope — `401` for a missing, malformed or expired token, `403` for a revoked key or a plan without API access. See the `Unauthorized` and `AuthForbidden` responses. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.