Cancel Invoice

DELETE/api/v1/invoices/{id}Recommended

Soft-cancel an invoice: status becomes CANCELLED and cancelledAt is stamped. Only OPEN and DRAFT invoices qualify — once checkout has opened a payment the invoice is PAYMENT_PENDING and the call fails with INVOICE_CANNOT_BE_CANCELLED. Nothing is deleted; the record and its payments stay queryable.

Authentication

Signature Pattern

HMAC-SHA256(apiSecret, "{t}\nDELETE\n/api/v1/invoices/{id}\n{idempotencyKey}\n{sha256(\"\")}")

Header	Value	Description
`X-API-Key`	a3f9c1e84b7d2065f1a4c8e93b6d0271	Merchant point API key, a hex string issued with its secret when the point is created. Identifies the point whose invoices you can reach.
`X-Signature`	t=1787735662,v1=8c1f0b7d4a29e63f5b0c8d17a4e92f6b3d05c7a81e4f9b26d3c07a5e18b4f962	Request signature, format t={unix_seconds},v1={hex_hmac_sha256}. Timestamp tolerance is 300s.
`Content-Type`	application/json	Always application/json. The signature is taken over the raw body bytes, so send exactly what you signed.
`Idempotency-Key`	9f2b1c44-7a0e-4d63-9f18-2c5b7ea31d04	Required on POST/DELETE. Unique per logical operation; replays return the first response for 24h.

Request Parameters

Name	Type	Required	Description
`id`	string	Required	Path parameter — invoice CUID to cancel.

Response Parameters

Field	Type	Example
`id`	string	"clyv3n8x40001qh7m2k9d5b1t"
`referenceId`	string	"INV-260826-041C"
`orderId`	string	"order-8814"
`description`	string	"Pro plan, annual billing"
`amount`	string	"12500"
`currency`	string	"USD"
`status`	string	"CANCELLED"
`customerEmail`	string	"buyer@example.com"
`customerName`	string	"Ada Lovelace"
`customerMetadata`	object	{…}
`customerMetadata.userId`	integer	4471
`metadata`	object	{…}
`metadata.internalRef`	string	"sub_2026_08_pro"
`returnUrl`	string	"https://merchant.example.com/checkout/su…
`cancelUrl`	string	"https://merchant.example.com/checkout/ca…
`expiresAt`	string	"2026-08-26T10:14:22.481Z"
`viewedAt`	null	null
`paidAt`	null	null
`cancelledAt`	string	"2026-08-26T09:22:10.006Z"
`createdAt`	string	"2026-08-26T09:14:22.481Z"

Response Example

JSONResponse

{
  "success": true,
  "data": {
    "id": "clyv3n8x40001qh7m2k9d5b1t",
    "referenceId": "INV-260826-041C",
    "orderId": "order-8814",
    "description": "Pro plan, annual billing",
    "amount": "12500",
    "currency": "USD",
    "status": "CANCELLED",
    "customerEmail": "buyer@example.com",
    "customerName": "Ada Lovelace",
    "customerMetadata": {
      "userId": 4471
    },
    "metadata": {
      "internalRef": "sub_2026_08_pro"
    },
    "returnUrl": "https://merchant.example.com/checkout/success",
    "cancelUrl": "https://merchant.example.com/checkout/cancel",
    "expiresAt": "2026-08-26T10:14:22.481Z",
    "viewedAt": null,
    "paidAt": null,
    "cancelledAt": "2026-08-26T09:22:10.006Z",
    "createdAt": "2026-08-26T09:14:22.481Z"
  },
  "timestamp": "2026-08-26T13:41:02.477Z",
  "requestId": "req_V1StGXR8_Z5j"
}

Error shape

JSONError

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  },
  "timestamp": "2026-08-26T13:41:02.477Z",
  "requestId": "req_V1StGXR8_Z5j"
}

Status Codes

200Success

201Created

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

Try itMockapi2.havala.io

DELETEhttps://api2.havala.io

← Checkout Invoice