Skip to content

API

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.

Get Invoice Simulate Invoice Payment