---
title: "Void an Invoice"
method: POST
path: "/invoices/{id}/void"
tags: ["Invoices"]
---

# Void an Invoice

`POST /invoices/{id}/void`

Void an Invoice by its ID with the provided reason

## Path parameters

- `id` string, required

## Request body

- VoidInvoiceRequestDTO
  - `reason` string — Reason for voiding the invoice

## Response `200`

OK

- InvoiceDTO
  - `createdAt` string, date-time, required — The date and time when the entity was created.
  - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
  - `metadata` object, nullable — Metadata used by merchants to store additional information about the entity.
  - `id` string, required — The ID of the invoice
  - `status` 'open' | 'paid' | 'voided', required — The status of the invoice
  - `voidedReason` string, nullable, required — The reason for voiding the invoice
  - `comment` string, nullable, required — An optional comment for the invoice
  - `amount` number, required — The intended amount to pay for the invoice. The actual amount paid can differ if retrying with a percentage discount, in which case the actual amount paid can be found in `payment.amount`
  - `currency` 'usd' | 'eur' | 'gbp' | 'cad' | 'aud' | 'pln' | 'czk' | 'sek' | 'dkk', required — The currency of the amount to be charged
  - `type` 'setup' | 'recurring', required — Indicates whether the invoice is the one that sets up the subscription, or a recurring one
  - `number` string, required — Sequential, unique, and human-readable number of the invoice
  - `subscription` string, nullable, required — The ID of the subscription associated with this invoice
  - `customer` object, required — The customer associated with this invoice
    - `createdAt` string, date-time, required — The date and time when the entity was created.
    - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
    - `metadata` object, nullable — Metadata used by merchants to store additional information about the entity.
    - `id` string, required — The ID of the customer
    - `email` string, required — The email of the customer
    - `name` string, nullable, required — The name of the customer
    - `phoneNumber` string, nullable, required — The phone number of the customer
    - `dateOfBirth` string, date, nullable, required — The date of birth of the customer
    - `gender` 'male' | 'female' | 'other' | 'null', nullable, required — The gender of the customer
    - `restrictMit` boolean — Whether the customer is restricted from making merchant-initiated payments. Only available from the dashboard or the API using a secret key.
    - `restrictCit` boolean — Whether the customer is restricted from making customer-initiated payments. Only available from the dashboard or the API using a secret key.
    - `restrictReason` string, nullable — Reason for restricting the customer. Only available from the dashboard or the API using a secret key.
    - `isRestricted` boolean — Whether the customer has at least one restriction applied (either `restrictMit` or `restrictCit`). Only available from the dashboard or the API using a secret key.
  - `payment` object, nullable, required — The payment associated with this invoice
    - `createdAt` string, date-time, required — The date and time when the entity was created.
    - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
    - `id` string, required — ID of the payment
    - `status` 'open' | 'requires_action' | 'succeeded' | 'cancelled', required — Status of the payment
    - `displayStatus` 'retrying' | 'chargeback' | 'reversed' | 'cancelled' | 'partially_reversed' | 'succeeded' | 'uncaptured' | 'incomplete' | 'failed' | 'unattempted', required — A user-friendly aggregate status for display purposes
    - `amount` number, required — Payment amount in minor currency, e.g. 1500 for 15.00 USD
    - `note` string, nullable — Optional note for the payment. Only available from the dashboard or the API using a secret key.
    - `currency` 'usd' | 'eur' | 'gbp' | 'cad' | 'aud' | 'pln' | 'czk' | 'sek' | 'dkk', required — Currency of the payment
    - `amountReversed` number, required — Amount reversed for the payment
    - `amountCaptured` number, required — Amount captured for the payment
    - `isCaptured` boolean, required — Indicates if the payment has been captured
    - `isRedirectRequired` boolean, required — Indicates if a redirect is required for the payment
    - `isReversed` boolean, required — Indicates if the payment has been partially reversed
    - `isFullyReversed` boolean, required — Indicates if the payment has been fully reversed
    - `isRecovered` boolean, required — Whether the payment recovered after one or more retry attempts and eventually succeeded.
    - `isRetrying` boolean, required — Whether the payment is currently in a retrying state after a failed attempt.
    - `isChargebacked` boolean — Whether a chargeback has been recorded for this payment. Only available from the dashboard or the API using a secret key.
    - `chargebackRecordedAt` string, date-time, nullable — The timestamp when a chargeback was recorded for this payment. Only available from the dashboard or the API using a secret key.
    - `authorizedAt` string, date-time, nullable — The timestamp when an authorization was recorded for this payment. Only available from the dashboard or the API using a secret key.
    - `capturedAt` string, date-time, nullable — The timestamp when a capture was recorded for this payment. Only available from the dashboard or the API using a secret key.
    - `reversedAt` string, date-time, nullable — The timestamp when a reversal was recorded for this payment. Only available from the dashboard or the API using a secret key.
    - `initiator` 'customer' | 'merchant', required — The initiator of the payment, indicating who initiated the payment.
    - `offSessionType` 'recurring' | 'unscheduled' | 'null', nullable, required — The off-session type of the payment. Only present for merchant-initiated payments.
    - `statementDescriptor` string, nullable — Statement to be shown on bank statement. Only available from the dashboard or the API using a secret key.
    - `latestMessage` string, nullable, required — Latest message available for the payment. This message is non-sensitive and may be displayed to the customer.
    - `latestDeclineType` 'soft_decline' | 'hard_decline' | 'null', nullable — The decline type for the latest transaction. Only available from the dashboard or the API using a secret key.
    - `action` object, nullable, required — The action that needs to be taken for this payment, e.g. redirecting the customer to a payment gateway.
      - `redirectUrl` string, required — URL to redirect the customer to for completing payment authentication (e.g., 3D Secure)
    - `checkoutKey` string — The checkout key for this payment, used for client-side payment processing by the Checkout SDK.
    - `metadata` object, nullable, required — Metadata for the payment.
    - `attribution` object, nullable, required — Attribution data for marketing tracking, including UTM parameters and platform click IDs.
      - `utm_source` string, nullable, required — Traffic source (platform/site)
      - `utm_medium` string, nullable, required — Marketing medium/channel
      - `utm_campaign` string, nullable, required — Campaign name/identifier
      - `utm_term` string, nullable, required — Paid search keywords
      - `utm_content` string, nullable, required — Differentiates ads/links
      - `utm_id` string, nullable, required — Used in URLs to assign a unique identifier or numerical ID to a specific marketing campaign
      - `utm_contentid` string, nullable, required — Content ID for tracking
      - `ref_id` string, nullable, required — Reference ID for tracking
      - `fbclid` string, nullable, required — Facebook click identifier
      - `cmpid` string, nullable, required — Campaign ID
      - `sub1` string, nullable, required — Sub-tracking parameter 1
      - `sub2` string, nullable, required — Sub-tracking parameter 2
      - `sub3` string, nullable, required — Sub-tracking parameter 3
      - `sub4` string, nullable, required — Sub-tracking parameter 4
      - `sub5` string, nullable, required — Sub-tracking parameter 5
      - `sub6` string, nullable, required — Sub-tracking parameter 6
      - `sub7` string, nullable, required — Sub-tracking parameter 7
      - `sub8` string, nullable, required — Sub-tracking parameter 8
      - `sub9` string, nullable, required — Sub-tracking parameter 9
      - `sub10` string, nullable, required — Sub-tracking parameter 10
    - `retry` object, nullable — Retry details for this payment.
      - `attempts` number, required — The number of retry attempts made
      - `nextAt` string, date-time, nullable, required — The date when the next retry attempt is scheduled
      - `nextAmount` number, nullable, required — The amount to be charged for the next retry attempt
    - `customer` object, nullable — Customer associated with the payment
      - `createdAt` string, date-time, required — The date and time when the entity was created.
      - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
      - `metadata` object, nullable — Metadata used by merchants to store additional information about the entity.
      - `id` string, required — The ID of the customer
      - `email` string, required — The email of the customer
      - `name` string, nullable, required — The name of the customer
      - `phoneNumber` string, nullable, required — The phone number of the customer
      - `dateOfBirth` string, date, nullable, required — The date of birth of the customer
      - `gender` 'male' | 'female' | 'other' | 'null', nullable, required — The gender of the customer
      - `restrictMit` boolean — Whether the customer is restricted from making merchant-initiated payments. Only available from the dashboard or the API using a secret key.
      - `restrictCit` boolean — Whether the customer is restricted from making customer-initiated payments. Only available from the dashboard or the API using a secret key.
      - `restrictReason` string, nullable — Reason for restricting the customer. Only available from the dashboard or the API using a secret key.
      - `isRestricted` boolean — Whether the customer has at least one restriction applied (either `restrictMit` or `restrictCit`). Only available from the dashboard or the API using a secret key.
      - `billingAddress` object, required — The billing address of the customer
        - `firstName` string, nullable, required
        - `lastName` string, nullable, required
        - `companyName` string, nullable, required
        - `line1` string, nullable, required
        - `line2` string, nullable, required
        - `city` string, nullable, required
        - `state` string, nullable, required
        - `postalCode` string, nullable, required
        - `country` string, nullable, required
      - `shippingAddress` object, required — The shipping address of the customer
        - `firstName` string, nullable, required
        - `lastName` string, nullable, required
        - `companyName` string, nullable, required
        - `line1` string, nullable, required
        - `line2` string, nullable, required
        - `city` string, nullable, required
        - `state` string, nullable, required
        - `postalCode` string, nullable, required
        - `country` string, nullable, required
    - `paymentMethod` object, nullable — Payment method used for the payment. Only available from the dashboard or the API using a secret key.
      - `createdAt` string, date-time, required — The date and time when the entity was created.
      - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
      - `metadata` object, nullable, required — Metadata used by merchants to store additional information about the entity.
      - `id` string, required — The ID of the payment method
      - `type` 'card' | 'paypal' | 'applePay', required — The type of the payment method
      - `customer` string, nullable, required — The ID of the customer who this payment method belongs to
      - `isDefault` boolean, required — Whether the payment method is the default one for the customer
      - `card` object, nullable — The card details of the payment method, only present if the type is `card`
        - `brand` 'visa' | 'mastercard' | 'amex' | 'discover' | 'null', nullable, required — The brand of the card
        - `lastFour` string, required — The last four digits of the card
        - `bin` string, required — The card BIN/IIN (Bank/Issuer Identification Number) - 4 to 8 digits
        - `expMonth` string, nullable, required — The expiration month of the card (in MM format)
        - `expYear` string, nullable, required — The expiration year of the card (in YYYY format)
        - `cardholderName` string, nullable, required — The name on the card
      - `applePay` object, nullable — The Apple Pay details of the payment method, only present if the type is `apple_pay`
        - `displayName` string, nullable, required — The display name of the Apple Pay payment method
    - `latestTransaction` object, nullable, required — The latest transaction for this payment. Only available from the dashboard or the API using a secret key.
      - `createdAt` string, date-time, required — The date and time when the entity was created.
      - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
      - `metadata` object, nullable — Metadata used by merchants to store additional information about the entity.
      - `id` string, required — The unique identifier of the transaction
      - `status` 'pending' | 'confirmation_requested' | 'authorized' | 'failed', required — Current status of the transaction
      - `authentication` 'not_requested' | 'pending' | 'succeeded' | 'failed', required — How far the transaction got through customer authentication — 3-D Secure for a card, the equivalent payer-action step for a redirect-based method. `not_requested` when the gateway never asked for it, so an absent challenge is distinguishable from a failed one.
      - `amount` number, required — Transaction amount in minor currency units (e.g., 1500 for $15.00)
      - `initiator` 'customer' | 'merchant', required — The initiator of the transaction
      - `statementDescriptor` string, nullable — The statement descriptor that will appear on the customer's statement. Only available from the dashboard or the API using a secret key.
      - `amountReversed` number, required — The amount that has been reversed by refunds or voids
      - `amountCaptured` number, required — The amount that has been captured
      - `isReversed` boolean, required — Whether the transaction has been reversed
      - `isFullyReversed` boolean, required — Whether the transaction has been fully reversed
      - `isCaptureFailed` boolean, required — Whether the capture operation failed
      - `isReverseFailed` boolean, required — Whether the reverse operation failed
      - `isRefundFailed` boolean, required — Whether the refund operation failed
      - `isVoidFailed` boolean, required — Whether the void operation failed
      - `isCaptured` boolean, required — Whether the transaction has been captured
      - `isChargebacked` boolean, required — Whether the transaction has a chargeback recorded
      - `chargebackRecordedAt` string, date-time, nullable — The timestamp when a chargeback was recorded for this transaction
      - `captureMethod` 'automatic' | 'automaticDelayed' | 'manual', required — Capture method used for this transaction
      - `captureDelay` number, nullable, required — Delay in days before capture occurs. Only applicable for 'automaticDelayed' capture method.
      - `currency` 'usd' | 'eur' | 'gbp' | 'cad' | 'aud' | 'pln' | 'czk' | 'sek' | 'dkk', required — Currency of the transaction
      - `processorId` string, nullable — The external transaction ID from the payment processor. Only available from the dashboard or the API using a secret key.
      - `outcome` object, nullable — Outcome details from the gateway operation. Only available from the dashboard or the API using a secret key.
        - `status` 'success' | 'partial' | 'failure', required
        - `errorCode` 'internal_error' | 'not_supported' | 'generic_decline' | 'insufficient_funds' | 'authentication_failed' | 'authentication_cancelled' | 'authentication_unavailable' | 'cancelled' | 'invalid_card_details' | 'expired_card' | 'transaction_not_permitted' | 'generic_issuer_error' | 'generic_processor_error' | 'processor_rate_limited' | 'processor_timeout' | 'fraud_suspected' | 'card_restricted' | 'authentication_rejected' | 'generic_hard_decline' | 'null', nullable, required
        - `errorMessage` string, nullable, required
        - `errorCodeUnmapped` boolean, nullable
        - `safeErrorMessage` string, nullable, required
        - `declineType` 'soft_decline' | 'hard_decline' | 'null', nullable, required
        - `retryStrategy` 'never_retry' | 'retry_with_new_payment_method' | 'retry_after_delay' | 'retry_immediately' | 'null', nullable, required
        - `specialCode` 'confirmation_requested' | 'null', nullable, required
        - `processorCode` string, nullable, required
        - `processorMessage` string, nullable, required
      - `gatewayProfile` object — Gateway profile used for this transaction. Only available from the dashboard or the API using a secret key.
        - `createdAt` string, date-time, required — The date and time when the entity was created.
        - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
        - `metadata` object, nullable, required — Metadata used by merchants to store additional information about the entity.
        - `id` string, required — ID of the Gateway Profile
        - `active` boolean, required — Whether the gateway profile is active and available for processing
        - `title` string, required — Title of the Gateway Profile
        - `integration` 'stripe' | 'adyen' | 'checkout' | 'paypal', required — Associated Gateway Integration
        - `environment` 'live' | 'test' | 'null', nullable, required — The environment the gateway profile operates in
        - `supportedPaymentMethods` string[], required — Supported payment methods for the Gateway Profile
      - `execution` string, nullable — The cascade execution associated with this transaction. Only available from the dashboard or the API using a secret key.
      - `paymentMethod` object, required — The payment method used for this transaction
        - `createdAt` string, date-time, required — The date and time when the entity was created.
        - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
        - `metadata` object, nullable — Metadata used by merchants to store additional information about the entity.
        - `id` string, required — The ID of the payment method
        - `type` 'card' | 'paypal' | 'applePay', required — The type of the payment method
        - `customer` string, nullable, required — The ID of the customer who this payment method belongs to
        - `isDefault` boolean, required — Whether the payment method is the default one for the customer
        - `card` object, nullable — The card details of the payment method, only present if the type is `card`
          - `brand` 'visa' | 'mastercard' | 'amex' | 'discover' | 'null', nullable, required — The brand of the card
          - `lastFour` string, required — The last four digits of the card
          - `bin` string, required — The card BIN/IIN (Bank/Issuer Identification Number) - 4 to 8 digits
          - `expMonth` string, nullable, required — The expiration month of the card (in MM format)
          - `expYear` string, nullable, required — The expiration year of the card (in YYYY format)
          - `cardholderName` string, nullable, required — The name on the card
        - `applePay` object, nullable — The Apple Pay details of the payment method, only present if the type is `apple_pay`
          - `displayName` string, nullable, required — The display name of the Apple Pay payment method
      - `customer` string, nullable, required — The ID of the customer associated with this transaction

## Other responses

- `202` — The merchant is entitled but its environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to a merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway.
- `400` — The request was rejected. `type` is `invalid_request_error` when the request itself is at fault — `errors` then lists every problem found, with field-attributable entries prefixed by the field’s path; `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it; or `payment_error` when the payment was refused by the issuer or processor.
- `401` — No API key was supplied, or the key is not valid. `type` is `authentication_error`.
- `403` — The API key is valid but lacks the permission this operation requires. `type` is `permission_error`.
- `404` — No resource exists with the requested identifier. `type` is `not_found_error`.
- `409` — `type` is `conflict_error`. The supplied `X-Idempotency-Key` was already used with a different request body (`code` is `idempotency_conflict`, and retrying will not help), or the resource is being modified by another in-flight request (`code` is `resource_locked`, and retrying with backoff will).
- `429` — Too many requests. The rate limit is applied per client across all operations. `type` is `rate_limit_error`.
- `500` — The request could not be completed because of an unexpected error. `type` is `api_error`.
- `504` — The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect, so retry with the same idempotency key rather than blindly.

---

[API](https://skmtc.dev/odus/apis/odus-orchestration-api.md) · [All operations](https://skmtc.dev/odus/apis/odus-orchestration-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/odus/odus-orchestration-api/revisions/d5fdcba31576/schema)