Skip to content
API
Open .md
On this page

Cancel

Cancel an open invoice before the customer locks an asset, understand the allowed state transition, and handle the cancellation response.

POST/v1/invoices/:invoice_id/cancel

API key: Payment

Cancel an invoice that is still in awaiting_client status. Once the customer selects a token/network and the invoice moves to awaiting_payment, cancellation is no longer possible — and a paid or expired invoice can never be cancelled. Cancelling an already-cancelled invoice is a no-op: it returns 200 with the same invoice, not an error.

Request body

reason is required (max 500 characters). It is recorded in the audit log and carried on the invoice.cancelled webhook.

{
  "reason": "Customer requested cancellation"
}

Response (200 OK)

{
  "invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
  "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
  "status": "cancelled",
  "is_final": true,
  "is_test": true,
  "payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
  "order": {
    "external_id": "order-12345",
    "client_id": "customer-67890",
    "amount": "100.00",
    "currency": "USD"
  },
  "created_at": 1739280600,
  "updated_at": 1739280660,
  "expires_at": 1739284200
}

Errors

See Error Codes for the full catalogue. The type URI in every error response deep-links to the matching row.

Previous Get Invoice Next Simulate Invoice Payment