Request cancellation of a stamped CFDI

curl --request POST \
  --url https://api.timbrix.mx/invoices/{uuid}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "motivo": "02",
  "folioSustitucion": "d3bfbc57-44af-4390-a064-f0afab85e5df"
}
'

import requests

url = "https://api.timbrix.mx/invoices/{uuid}/cancel"

payload = {
    "motivo": "02",
    "folioSustitucion": "d3bfbc57-44af-4390-a064-f0afab85e5df"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({motivo: '02', folioSustitucion: 'd3bfbc57-44af-4390-a064-f0afab85e5df'})
};

fetch('https://api.timbrix.mx/invoices/{uuid}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.timbrix.mx/invoices/{uuid}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'motivo' => '02',
    'folioSustitucion' => 'd3bfbc57-44af-4390-a064-f0afab85e5df'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.timbrix.mx/invoices/{uuid}/cancel"

	payload := strings.NewReader("{\n  \"motivo\": \"02\",\n  \"folioSustitucion\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.timbrix.mx/invoices/{uuid}/cancel")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"motivo\": \"02\",\n  \"folioSustitucion\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.timbrix.mx/invoices/{uuid}/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"motivo\": \"02\",\n  \"folioSustitucion\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "6a1b2c3d-4e5f-4890-9abc-def012345678",
  "invoiceId": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
  "motivo": "02",
  "requiresApproval": false,
  "cancellationStatus": "aceptada",
  "createdAt": "2026-08-09T15:50:03.412Z",
  "folioSustitucion": null,
  "respondBy": null,
  "requestedBy": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
  "resolvedBy": null,
  "resolvedAt": null
}

Invoices

Cancel Invoice

Authenticate with either a Supabase session (member of the invoice’s organization) or an API key belonging to that same organization. Determines automatically whether the cancellation is direct or requires receptor approval per SAT rules — Timbrix cannot confirm receptor approval in real time, so a pending cancellation must be resolved manually via the resolve endpoint. This is a FLAT route — no organizationId in the URL, unlike create/list above; the organization is resolved from the invoice’s globally-unique uuid.

POST

invoices

{uuid}

cancel

Request cancellation of a stamped CFDI

curl --request POST \
  --url https://api.timbrix.mx/invoices/{uuid}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "motivo": "02",
  "folioSustitucion": "d3bfbc57-44af-4390-a064-f0afab85e5df"
}
'

import requests

url = "https://api.timbrix.mx/invoices/{uuid}/cancel"

payload = {
    "motivo": "02",
    "folioSustitucion": "d3bfbc57-44af-4390-a064-f0afab85e5df"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({motivo: '02', folioSustitucion: 'd3bfbc57-44af-4390-a064-f0afab85e5df'})
};

fetch('https://api.timbrix.mx/invoices/{uuid}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.timbrix.mx/invoices/{uuid}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'motivo' => '02',
    'folioSustitucion' => 'd3bfbc57-44af-4390-a064-f0afab85e5df'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.timbrix.mx/invoices/{uuid}/cancel"

	payload := strings.NewReader("{\n  \"motivo\": \"02\",\n  \"folioSustitucion\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.timbrix.mx/invoices/{uuid}/cancel")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"motivo\": \"02\",\n  \"folioSustitucion\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.timbrix.mx/invoices/{uuid}/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"motivo\": \"02\",\n  \"folioSustitucion\": \"d3bfbc57-44af-4390-a064-f0afab85e5df\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "6a1b2c3d-4e5f-4890-9abc-def012345678",
  "invoiceId": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
  "motivo": "02",
  "requiresApproval": false,
  "cancellationStatus": "aceptada",
  "createdAt": "2026-08-09T15:50:03.412Z",
  "folioSustitucion": null,
  "respondBy": null,
  "requestedBy": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
  "resolvedBy": null,
  "resolvedAt": null
}

Requests cancellation of a stamped CFDI 4.0 before the SAT. Unlike Create Invoice and List Invoices, this is a flat route — it does not carry /organizations/{organizationId}/ in the URL. The invoice’s uuid (its folio fiscal, globally unique across all organizations) is enough to resolve the owning organization server-side, combined with the caller’s own auth context (session or API key).

Authentication

Accepts either:

A Supabase Bearer session (Authorization: Bearer <token>) — the authenticated user must be a member of the invoice’s organization.
An API key (X-API-Key: sk_...) with the write:invoices scope — the key’s own organization must match the invoice’s organization, or the request is rejected with 403 Forbidden.

Path Parameters

Parameter	Type	Required	Description
`uuid`	string (UUID)	Yes	Folio fiscal UUID (`uuidFiscal`) of the invoice to cancel — globally unique, not scoped to an organization

Request Body

Field	Type	Required	Description
`motivo`	string	Yes	SAT cancellation reason code — `01`, `02`, `03`, or `04` (see below)
`folioSustitucion`	string	Conditional*	Folio fiscal UUID of the CFDI that replaces this one. Required, and only meaningful, when `motivo` is `01`

* Required when motivo is 01 (sustitución). Must be the folio fiscal of an existing, vigente invoice belonging to the same organization, and cannot be the invoice being cancelled itself — an arbitrary or unverified UUID is rejected with a 400. Ignored for motivo 02, 03, and 04, even if sent.

`motivo` codes

Code	Description	`folioSustitucion`
`01`	Emitido con errores con relación (sustitución)	Required
`02`	Emitido con errores sin relación	Not applicable
`03`	No se llevó a cabo la operación	Not applicable
`04`	Operación nominativa relacionada en factura global	Not applicable

How eligibility is determined

Timbrix computes, from the invoice’s own data, whether the cancellation applies directly or requires the receptor’s approval — this follows the SAT’s own rule and you never send it yourself; it’s returned in the response as requiresApproval. The cancellation is direct (no approval needed) when at least one of these is true:

tipoComprobante is E (Egreso) or T (Traslado)
total is ≤ $5,000 MXN
rfcReceptor is XAXX010101000 (público en general) or XEXX010101000 (residente extranjero)
The invoice was issued 3 business days ago or less (Mon–Fri, America/Mexico_City calendar)

Otherwise, the cancellation requires receptor approval: the SAT notifies the receptor, who has 3 business days to accept or reject it through the SAT portal.

Timbrix cannot poll the SAT in real time for the receptor’s response. A cancellation that requires approval comes back with cancellationStatus: "pendiente" and a respondBy deadline — the invoice stays vigente until you confirm the actual outcome yourself, after checking the SAT portal, via Resolve Cancellation.

A direct cancellation, by contrast, is resolved synchronously in the same request: the response comes back with cancellationStatus: "aceptada" and the invoice’s status flips to cancelado immediately.

Mass cancellation limit

Organizations on the Starter or Pro plan are limited to 50 cancellation requests per calendar day; the 51st request that day returns 400 Bad Request. Business and Enterprise plans have no daily limit.

Example Request

cURL

curl -X POST https://api.timbrix.mx/invoices/d3bfbc57-44af-4390-a064-f0afab85e5df/cancel \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "02"
  }'

TypeScript

// Not yet available in @timbrix/sdk — call the REST endpoint directly
// until SDK support for cancellations ships.
const response = await fetch(
  "https://api.timbrix.mx/invoices/d3bfbc57-44af-4390-a064-f0afab85e5df/cancel",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <your_token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ motivo: "02" }),
  }
)
const cancellation = await response.json()
console.log(cancellation.cancellationStatus)

Sustitución (motivo: "01") — replacing this CFDI with an already-stamped corrected one:

cURL

curl -X POST https://api.timbrix.mx/invoices/d3bfbc57-44af-4390-a064-f0afab85e5df/cancel \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "01",
    "folioSustitucion": "a1b2c3d4-5e6f-4890-9abc-def012345678"
  }'

Example Response

Direct cancellation — resolved immediately:

{
  "id": "6a1b2c3d-4e5f-4890-9abc-def012345678",
  "invoiceId": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
  "motivo": "02",
  "folioSustitucion": null,
  "requiresApproval": false,
  "respondBy": null,
  "cancellationStatus": "aceptada",
  "requestedBy": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
  "resolvedBy": null,
  "resolvedAt": "2026-08-09T15:50:03.412Z",
  "createdAt": "2026-08-09T15:50:03.412Z"
}

Cancellation requiring receptor approval — still pending:

{
  "id": "6a1b2c3d-4e5f-4890-9abc-def012345678",
  "invoiceId": "0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab",
  "motivo": "02",
  "folioSustitucion": null,
  "requiresApproval": true,
  "respondBy": "2026-08-12T15:50:03.412Z",
  "cancellationStatus": "pendiente",
  "requestedBy": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
  "resolvedBy": null,
  "resolvedAt": null,
  "createdAt": "2026-08-09T15:50:03.412Z"
}

Field	Type	Description
`id`	string	Cancellation request ID
`invoiceId`	string	Timbrix invoice record ID (not the folio fiscal UUID)
`motivo`	string	The cancellation reason code sent in the request
`folioSustitucion`	string \| null	Folio fiscal UUID of the replacement CFDI — only set for `motivo: "01"`
`requiresApproval`	boolean	Whether this cancellation needed receptor approval, computed server-side
`respondBy`	string \| null	Deadline (ISO 8601) for the receptor to respond — 3 business days from when the cancellation was requested. `null` for direct cancellations
`cancellationStatus`	string	`pendiente`, `aceptada`, or `rechazada`
`requestedBy`	string \| null	Timbrix user ID who requested the cancellation
`resolvedBy`	string \| null	Timbrix user ID who confirmed the final outcome — `null` for direct cancellations, which resolve automatically
`resolvedAt`	string \| null	ISO 8601 timestamp the outcome was confirmed — `null` while `pendiente`
`createdAt`	string	ISO 8601 timestamp the cancellation was requested

Common Errors

400 Bad Request

motivo is invalid; folioSustitucion is missing when motivo is 01, is not a vigente invoice of the same organization, or is the same invoice being cancelled; the invoice is already cancelado; or the organization has hit the daily mass-cancellation limit (Starter/Pro plans).

{
  "statusCode": 400,
  "message": "`folioSustitucion` es requerido cuando `motivo` es 01 (sustitución)",
  "error": "BAD_REQUEST"
}

401 Unauthorized

Missing or invalid Bearer token / API key.

403 Forbidden

The authenticated user is not a member of the invoice’s organization, or the API key does not have the write:invoices scope / belongs to a different organization than the one that owns the invoice.

404 Not Found

uuid does not match any invoice, or (when motivo is 01) folioSustitucion does not match any invoice belonging to the same organization.

409 Conflict

A cancellation is already pendiente for this invoice. Resolve it via Resolve Cancellation — or wait for the receptor to respond — before requesting another.

{
  "statusCode": 409,
  "message": "Esta factura ya tiene una cancelación pendiente de resolución",
  "error": "CONFLICT"
}

Authorizations

X-API-Key

string

header

required

API Key for authentication (format: sk_...)

Path Parameters

uuid

string

required

Folio fiscal UUID of the invoice to cancel

Body

application/json

motivo

enum<string>

required

01 = emitido con errores con relación (requiere folioSustitucion), 02 = emitido con errores sin relación, 03 = no se llevó a cabo la operación, 04 = operación nominativa relacionada en factura global

Available options:

01,

02,

03,

04

Example:

"02"

folioSustitucion

string

UUID fiscal del CFDI que sustituye a este. Requerido cuando motivo=01, debe ser una factura vigente de la misma organización.

Example:

"d3bfbc57-44af-4390-a064-f0afab85e5df"

Response

string

required

Example:

"6a1b2c3d-4e5f-4890-9abc-def012345678"

invoiceId

string

required

Timbrix invoice record ID

Example:

"0f2a1c3e-1a2b-4c3d-9e8f-1234567890ab"

motivo

enum<string>

required

Available options:

01,

02,

03,

04

Example:

"02"

requiresApproval

boolean

required

Example:

false

cancellationStatus

enum<string>

required

Available options:

pendiente,

aceptada,

rechazada

Example:

"aceptada"

createdAt

string<date-time>

required

Example:

"2026-08-09T15:50:03.412Z"

folioSustitucion

string | null

Example:

null

respondBy

string<date-time> | null

Example:

null

requestedBy

string | null

Example:

"9f8e7d6c-5b4a-3210-fedc-ba9876543210"

resolvedBy

string | null

Example:

null

resolvedAt

string<date-time> | null

Example:

null

API documentation

Organizations

Members

Invites

Auth

OAuth

Customers

SAT Catalogs

Invoices

Products

Users

Webhooks

API Keys

Cancel Invoice

Authentication

Path Parameters

Request Body

`motivo` codes

How eligibility is determined

Mass cancellation limit

Example Request

Example Response

Common Errors

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

Authorizations

Path Parameters

Body

Response

​Authentication

​Path Parameters

​Request Body

​motivo codes

​How eligibility is determined

​Mass cancellation limit

​Example Request

​Example Response

​Common Errors

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​409 Conflict

Authorizations

Path Parameters

Body

Response

Authentication

Path Parameters

Request Body

`motivo` codes

How eligibility is determined

Mass cancellation limit

Example Request

Example Response

Common Errors

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict