# Update a credit note (/en/api-reference/credit-notes/updateCreditNote)

Changes the note printed on a credit note, or its metadata. Amounts never change.

## PATCH /credit-notes/{id}

### Parameters

- `id` (string, in: path, required) — Credit note ID

### Request body (required)

Content type: `application/json`

- `memo` (string | null) — Note printed on the credit note
- `metadata` (object | null) — Custom metadata

### Responses

#### 200 — Credit note

Content type: `application/json`

- `id` (string, required) — Credit note ID
- `object` (enum("credit_note"), required) — Object type
- `number` (string, required) — Credit note number: the invoice number, then CN and its count on that invoice
- `status` (enum("issued" | "void"), required) — issued or void
- `type` (enum("pre_payment" | "post_payment" | "mixed"), required) — pre_payment, post_payment or mixed
- `invoiceId` (string, required) — Invoice the credit note is for
- `customerId` (string, required) — Customer
- `currency` (enum("EGP" | "USD" | "EUR" | "GBP" | "SAR" | "AED" | "QAR" | "KWD" | "JOD" | "OMR" | "BHD" | "LYD" | "AUD" | "CAD" | "CNY"), required) — Currency, same as the invoice
- `reason` (enum("duplicate" | "fraudulent" | "order_change" | "product_unsatisfactory" | "other"), required) — Why it was issued
- `memo` (string | null, required) — Note printed on the credit note
- `effectiveAt` (string, required) — Date the credit takes effect (ISO 8601)
- `lines` (Array<CreditNoteLineItem>, required) — What is credited
  - `id` (string, required) — Credit note line ID
  - `object` (enum("credit_note_line_item"), required) — Object type
  - `type` (enum("invoice_line_item" | "custom_line_item"), required) — invoice_line_item or custom_line_item
  - `invoiceLineItemId` (string | null, required) — The credited invoice line, when type is invoice_line_item
  - `description` (string | null, required) — What is credited
  - `quantity` (number | null, required) — Quantity credited
  - `unitAmount` (integer | null, required) — Price of one unit, in minor units
  - `amount` (integer, required) — Amount credited before tax, in minor units
  - `discountAmount` (integer, required) — Discount credited, in minor units
  - `taxes` (Array<InvoiceTaxAmount>, required) — Tax credited on this line, per rate
    - `amount` (integer, required) — Tax amount in minor units
    - `taxableAmount` (integer, required) — Amount the tax was calculated on, in minor units
    - `taxBehavior` (enum("exclusive" | "inclusive"), required) — exclusive or inclusive
    - `taxRateDetails` (InvoiceTaxRateDetails, required) — The tax rate applied
- `amount` (integer, required) — Total of the credit note, including tax
- `amountShipping` (integer, required) — Shipping credited
- `discountAmount` (integer, required) — Discount credited
- `subtotal` (integer, required) — Total before exclusive tax
- `subtotalExcludingTax` (integer, required) — Total before any tax
- `total` (integer, required) — Total credited, including tax
- `totalExcludingTax` (integer, required) — Total credited before tax
- `totalTaxes` (Array<InvoiceTaxAmount>, required) — Tax credited, per rate
  - `amount` (integer, required) — Tax amount in minor units
  - `taxableAmount` (integer, required) — Amount the tax was calculated on, in minor units
  - `taxBehavior` (enum("exclusive" | "inclusive"), required) — exclusive or inclusive
  - `taxRateDetails` (InvoiceTaxRateDetails, required) — The tax rate applied
    - `taxRateId` (string, required) — Tax rate ID
    - `displayName` (string, required) — Tax name
    - `displayNameAr` (string | null, required) — Arabic tax name
    - `percentage` (number, required) — Tax percentage
- `prePaymentAmount` (integer, required) — Part that lowered what the customer still owed
- `postPaymentAmount` (integer, required) — Part that was already paid and went back: refunded, credited to the customer, or returned outside XPay
- `outOfBandAmount` (integer | null, required) — Returned to the customer outside XPay
- `refunds` (Array<CreditNoteRefund>, required) — Refunds that returned money for this note
  - `refundId` (string, required) — Refund that returned the money
  - `amountRefunded` (integer, required) — Amount of the refund that belongs to this credit note
- `customerBalanceTransactionId` (string | null, required) — Customer balance transaction that gave the customer credit, if any
- `voidedAt` (string | null, required) — When it was voided (ISO 8601)
- `metadata` (object | null, required) — Custom metadata
- `merchantId` (string, required) — Merchant ID
- `createdAt` (string, required) — Created timestamp (ISO 8601)
- `updatedAt` (string, required) — Updated timestamp (ISO 8601)

#### 401 — Authentication is required and the request did not present a valid API key.

Content type: `application/json`

- `error` (ApiErrorBody, required) — Structured error body. Returned inside `error` on every 4xx/5xx response. Switch on `code` to handle specific failure modes programmatically; `message` is English for developers.
  - `type` (enum("invalid_request_error" | "authentication_error" | "rate_limit_error" | "api_error" | "card_error" | "idempotency_error"), required) — High-level error category. Use this for branching at the top level of your error handler (e.g. retry on `api_error`, surface a card decline on `card_error`).
  - `code` (enum("apple_pay_certificate_invalid" | "apple_pay_certificate_expired" | "apple_pay_certificate_key_mismatch" | "apple_pay_certificate_identifier_mismatch" | "apple_pay_registration_rejected" | "invalid_request" | "parameter_out_of_range" | "parameter_invalid" | "parameter_missing" | "parameter_unknown" | "parameters_exclusive" | "parameter_requires_another" | "validation_error" | "resource_missing" | "resource_invalid_state" | "resource_already_exists" | "resource_in_use" | "brain_slack_connect_required" | "merchant_conversion_owners_not_allowed" | "contract_stage_not_allowed" | "journey_window_overlap" | "unprintable_characters" | "authentication_required" | "invalid_api_key" | "api_key_inactive" | "invalid_signature" | "merchant_not_activated" | "permission_denied" | "two_factor_required" | "checkout_session_expired" | "checkout_session_complete" | "invalid_client_secret" | "livemode_mismatch" | "amount_reconfirmation_required" | "creation_failed" | "payment_still_confirming" | "payment_already_completed" | "payment_link_inactive" | "payment_link_expired" | "amount_invalid" | "amount_too_small" | "amount_too_large" | "currency_invalid" | "product_archived" | "price_inactive" | "price_not_yet_active" | "price_expired" | "price_sold_out" | "price_date_range_invalid" | "price_stock_invalid" | "price_recurring_not_supported" | "price_immutable_while_used" | "line_item_missing_price" | "line_item_quantity_not_adjustable" | "line_item_quantity_out_of_bounds" | "line_item_quantity_not_supported_for_custom" | "checkout_empty_cart" | "promotion_codes_not_allowed" | "promotion_code_not_found" | "promotion_code_inactive" | "promotion_code_expired" | "promotion_code_max_redemptions" | "promotion_code_customer_mismatch" | "promotion_code_minimum_amount" | "promotion_code_first_time_only" | "coupon_invalid" | "coupon_currency_mismatch" | "coupon_minimum_amount" | "coupon_customer_max_redemptions" | "too_many_discounts" | "payment_method_corrupted" | "payment_method_customer_mismatch" | "payment_intent_customer_mismatch" | "payment_method_mismatch" | "payment_method_not_available" | "payment_intent_unexpected_state" | "charge_not_captured" | "merchant_no_balance" | "insufficient_balance" | "refund_outcome_unconfirmed" | "charge_missing_balance_transaction" | "charge_missing_fee_data" | "charge_incomplete_fee_data" | "cannot_rename_default" | "must_have_enabled_method" | "cannot_delete_default" | "configuration_in_use" | "unsupported_currency" | "exchange_rate_not_found" | "coupon_in_use" | "promotion_code_exists" | "tax_rate_archived" | "invoice_not_editable" | "invoice_not_finalizable" | "invoice_not_open" | "invoice_no_lines" | "invoice_customer_incomplete" | "invoice_already_paid" | "invoice_voided" | "invoice_has_payments" | "invoice_payment_in_progress" | "invoice_amount_not_supported" | "invoice_online_payment_unavailable" | "invoice_partial_payment_not_allowed" | "invoice_partial_amount_invalid" | "invoice_installments_mismatch" | "invoice_plan_with_part_payments" | "invoice_link_expired" | "invoice_currency_mismatch" | "invoice_line_limit_exceeded" | "invoice_number_taken" | "credit_note_amount_too_large" | "credit_note_split_mismatch" | "payout_plan_changed" | "payout_balance_not_entered" | "payout_account_short" | "hold_capture_refund_failed" | "rate_limit" | "idempotency_key_in_use" | "internal_error" | "request_timeout")) — Stable, machine-readable code identifying the specific failure (e.g. `resource_missing`, `parameter_invalid`, `authentication_required`). Always present on documented errors. See the API Error Codes reference for the full list.
  - `message` (string, required) — Human-readable description of what went wrong. Safe to log or display, but not stable — use `code` for programmatic branching.
  - `param` (string) — Name of the request parameter that caused the error, when applicable (e.g. `amount`, `currency`).
  - `doc_url` (string) — URL to the documentation page for this specific error code. Deep-linked into the API Error Codes reference.
  - `minimum_amount` (integer) — The order minimum a promotion code or coupon needs, in the smallest unit of the currency the customer pays in (`presentmentDetails.currency` when set, otherwise `currency`). Present on `promotion_code_minimum_amount` and `coupon_minimum_amount`.
- `request_id` (string) — Unique identifier for this request, propagated to logs and traces. Include it when contacting support.

#### 403 — The credential is valid but lacks the permission this endpoint requires. Check the API key's allowed permissions in the dashboard.

Content type: `application/json`

- `error` (ApiErrorBody, required) — Structured error body. Returned inside `error` on every 4xx/5xx response. Switch on `code` to handle specific failure modes programmatically; `message` is English for developers.
  - `type` (enum("invalid_request_error" | "authentication_error" | "rate_limit_error" | "api_error" | "card_error" | "idempotency_error"), required) — High-level error category. Use this for branching at the top level of your error handler (e.g. retry on `api_error`, surface a card decline on `card_error`).
  - `code` (enum("apple_pay_certificate_invalid" | "apple_pay_certificate_expired" | "apple_pay_certificate_key_mismatch" | "apple_pay_certificate_identifier_mismatch" | "apple_pay_registration_rejected" | "invalid_request" | "parameter_out_of_range" | "parameter_invalid" | "parameter_missing" | "parameter_unknown" | "parameters_exclusive" | "parameter_requires_another" | "validation_error" | "resource_missing" | "resource_invalid_state" | "resource_already_exists" | "resource_in_use" | "brain_slack_connect_required" | "merchant_conversion_owners_not_allowed" | "contract_stage_not_allowed" | "journey_window_overlap" | "unprintable_characters" | "authentication_required" | "invalid_api_key" | "api_key_inactive" | "invalid_signature" | "merchant_not_activated" | "permission_denied" | "two_factor_required" | "checkout_session_expired" | "checkout_session_complete" | "invalid_client_secret" | "livemode_mismatch" | "amount_reconfirmation_required" | "creation_failed" | "payment_still_confirming" | "payment_already_completed" | "payment_link_inactive" | "payment_link_expired" | "amount_invalid" | "amount_too_small" | "amount_too_large" | "currency_invalid" | "product_archived" | "price_inactive" | "price_not_yet_active" | "price_expired" | "price_sold_out" | "price_date_range_invalid" | "price_stock_invalid" | "price_recurring_not_supported" | "price_immutable_while_used" | "line_item_missing_price" | "line_item_quantity_not_adjustable" | "line_item_quantity_out_of_bounds" | "line_item_quantity_not_supported_for_custom" | "checkout_empty_cart" | "promotion_codes_not_allowed" | "promotion_code_not_found" | "promotion_code_inactive" | "promotion_code_expired" | "promotion_code_max_redemptions" | "promotion_code_customer_mismatch" | "promotion_code_minimum_amount" | "promotion_code_first_time_only" | "coupon_invalid" | "coupon_currency_mismatch" | "coupon_minimum_amount" | "coupon_customer_max_redemptions" | "too_many_discounts" | "payment_method_corrupted" | "payment_method_customer_mismatch" | "payment_intent_customer_mismatch" | "payment_method_mismatch" | "payment_method_not_available" | "payment_intent_unexpected_state" | "charge_not_captured" | "merchant_no_balance" | "insufficient_balance" | "refund_outcome_unconfirmed" | "charge_missing_balance_transaction" | "charge_missing_fee_data" | "charge_incomplete_fee_data" | "cannot_rename_default" | "must_have_enabled_method" | "cannot_delete_default" | "configuration_in_use" | "unsupported_currency" | "exchange_rate_not_found" | "coupon_in_use" | "promotion_code_exists" | "tax_rate_archived" | "invoice_not_editable" | "invoice_not_finalizable" | "invoice_not_open" | "invoice_no_lines" | "invoice_customer_incomplete" | "invoice_already_paid" | "invoice_voided" | "invoice_has_payments" | "invoice_payment_in_progress" | "invoice_amount_not_supported" | "invoice_online_payment_unavailable" | "invoice_partial_payment_not_allowed" | "invoice_partial_amount_invalid" | "invoice_installments_mismatch" | "invoice_plan_with_part_payments" | "invoice_link_expired" | "invoice_currency_mismatch" | "invoice_line_limit_exceeded" | "invoice_number_taken" | "credit_note_amount_too_large" | "credit_note_split_mismatch" | "payout_plan_changed" | "payout_balance_not_entered" | "payout_account_short" | "hold_capture_refund_failed" | "rate_limit" | "idempotency_key_in_use" | "internal_error" | "request_timeout")) — Stable, machine-readable code identifying the specific failure (e.g. `resource_missing`, `parameter_invalid`, `authentication_required`). Always present on documented errors. See the API Error Codes reference for the full list.
  - `message` (string, required) — Human-readable description of what went wrong. Safe to log or display, but not stable — use `code` for programmatic branching.
  - `param` (string) — Name of the request parameter that caused the error, when applicable (e.g. `amount`, `currency`).
  - `doc_url` (string) — URL to the documentation page for this specific error code. Deep-linked into the API Error Codes reference.
  - `minimum_amount` (integer) — The order minimum a promotion code or coupon needs, in the smallest unit of the currency the customer pays in (`presentmentDetails.currency` when set, otherwise `currency`). Present on `promotion_code_minimum_amount` and `coupon_minimum_amount`.
- `request_id` (string) — Unique identifier for this request, propagated to logs and traces. Include it when contacting support.

#### 404 — The referenced resource does not exist in this account / mode. Confirm the ID and that you're calling the correct mode (test vs live).

Content type: `application/json`

- `error` (ApiErrorBody, required) — Structured error body. Returned inside `error` on every 4xx/5xx response. Switch on `code` to handle specific failure modes programmatically; `message` is English for developers.
  - `type` (enum("invalid_request_error" | "authentication_error" | "rate_limit_error" | "api_error" | "card_error" | "idempotency_error"), required) — High-level error category. Use this for branching at the top level of your error handler (e.g. retry on `api_error`, surface a card decline on `card_error`).
  - `code` (enum("apple_pay_certificate_invalid" | "apple_pay_certificate_expired" | "apple_pay_certificate_key_mismatch" | "apple_pay_certificate_identifier_mismatch" | "apple_pay_registration_rejected" | "invalid_request" | "parameter_out_of_range" | "parameter_invalid" | "parameter_missing" | "parameter_unknown" | "parameters_exclusive" | "parameter_requires_another" | "validation_error" | "resource_missing" | "resource_invalid_state" | "resource_already_exists" | "resource_in_use" | "brain_slack_connect_required" | "merchant_conversion_owners_not_allowed" | "contract_stage_not_allowed" | "journey_window_overlap" | "unprintable_characters" | "authentication_required" | "invalid_api_key" | "api_key_inactive" | "invalid_signature" | "merchant_not_activated" | "permission_denied" | "two_factor_required" | "checkout_session_expired" | "checkout_session_complete" | "invalid_client_secret" | "livemode_mismatch" | "amount_reconfirmation_required" | "creation_failed" | "payment_still_confirming" | "payment_already_completed" | "payment_link_inactive" | "payment_link_expired" | "amount_invalid" | "amount_too_small" | "amount_too_large" | "currency_invalid" | "product_archived" | "price_inactive" | "price_not_yet_active" | "price_expired" | "price_sold_out" | "price_date_range_invalid" | "price_stock_invalid" | "price_recurring_not_supported" | "price_immutable_while_used" | "line_item_missing_price" | "line_item_quantity_not_adjustable" | "line_item_quantity_out_of_bounds" | "line_item_quantity_not_supported_for_custom" | "checkout_empty_cart" | "promotion_codes_not_allowed" | "promotion_code_not_found" | "promotion_code_inactive" | "promotion_code_expired" | "promotion_code_max_redemptions" | "promotion_code_customer_mismatch" | "promotion_code_minimum_amount" | "promotion_code_first_time_only" | "coupon_invalid" | "coupon_currency_mismatch" | "coupon_minimum_amount" | "coupon_customer_max_redemptions" | "too_many_discounts" | "payment_method_corrupted" | "payment_method_customer_mismatch" | "payment_intent_customer_mismatch" | "payment_method_mismatch" | "payment_method_not_available" | "payment_intent_unexpected_state" | "charge_not_captured" | "merchant_no_balance" | "insufficient_balance" | "refund_outcome_unconfirmed" | "charge_missing_balance_transaction" | "charge_missing_fee_data" | "charge_incomplete_fee_data" | "cannot_rename_default" | "must_have_enabled_method" | "cannot_delete_default" | "configuration_in_use" | "unsupported_currency" | "exchange_rate_not_found" | "coupon_in_use" | "promotion_code_exists" | "tax_rate_archived" | "invoice_not_editable" | "invoice_not_finalizable" | "invoice_not_open" | "invoice_no_lines" | "invoice_customer_incomplete" | "invoice_already_paid" | "invoice_voided" | "invoice_has_payments" | "invoice_payment_in_progress" | "invoice_amount_not_supported" | "invoice_online_payment_unavailable" | "invoice_partial_payment_not_allowed" | "invoice_partial_amount_invalid" | "invoice_installments_mismatch" | "invoice_plan_with_part_payments" | "invoice_link_expired" | "invoice_currency_mismatch" | "invoice_line_limit_exceeded" | "invoice_number_taken" | "credit_note_amount_too_large" | "credit_note_split_mismatch" | "payout_plan_changed" | "payout_balance_not_entered" | "payout_account_short" | "hold_capture_refund_failed" | "rate_limit" | "idempotency_key_in_use" | "internal_error" | "request_timeout")) — Stable, machine-readable code identifying the specific failure (e.g. `resource_missing`, `parameter_invalid`, `authentication_required`). Always present on documented errors. See the API Error Codes reference for the full list.
  - `message` (string, required) — Human-readable description of what went wrong. Safe to log or display, but not stable — use `code` for programmatic branching.
  - `param` (string) — Name of the request parameter that caused the error, when applicable (e.g. `amount`, `currency`).
  - `doc_url` (string) — URL to the documentation page for this specific error code. Deep-linked into the API Error Codes reference.
  - `minimum_amount` (integer) — The order minimum a promotion code or coupon needs, in the smallest unit of the currency the customer pays in (`presentmentDetails.currency` when set, otherwise `currency`). Present on `promotion_code_minimum_amount` and `coupon_minimum_amount`.
- `request_id` (string) — Unique identifier for this request, propagated to logs and traces. Include it when contacting support.

#### 500 — Something went wrong on our end. Safe to retry idempotent requests; for non-idempotent calls, consult the `request_id` before resubmitting.

Content type: `application/json`

- `error` (ApiErrorBody, required) — Structured error body. Returned inside `error` on every 4xx/5xx response. Switch on `code` to handle specific failure modes programmatically; `message` is English for developers.
  - `type` (enum("invalid_request_error" | "authentication_error" | "rate_limit_error" | "api_error" | "card_error" | "idempotency_error"), required) — High-level error category. Use this for branching at the top level of your error handler (e.g. retry on `api_error`, surface a card decline on `card_error`).
  - `code` (enum("apple_pay_certificate_invalid" | "apple_pay_certificate_expired" | "apple_pay_certificate_key_mismatch" | "apple_pay_certificate_identifier_mismatch" | "apple_pay_registration_rejected" | "invalid_request" | "parameter_out_of_range" | "parameter_invalid" | "parameter_missing" | "parameter_unknown" | "parameters_exclusive" | "parameter_requires_another" | "validation_error" | "resource_missing" | "resource_invalid_state" | "resource_already_exists" | "resource_in_use" | "brain_slack_connect_required" | "merchant_conversion_owners_not_allowed" | "contract_stage_not_allowed" | "journey_window_overlap" | "unprintable_characters" | "authentication_required" | "invalid_api_key" | "api_key_inactive" | "invalid_signature" | "merchant_not_activated" | "permission_denied" | "two_factor_required" | "checkout_session_expired" | "checkout_session_complete" | "invalid_client_secret" | "livemode_mismatch" | "amount_reconfirmation_required" | "creation_failed" | "payment_still_confirming" | "payment_already_completed" | "payment_link_inactive" | "payment_link_expired" | "amount_invalid" | "amount_too_small" | "amount_too_large" | "currency_invalid" | "product_archived" | "price_inactive" | "price_not_yet_active" | "price_expired" | "price_sold_out" | "price_date_range_invalid" | "price_stock_invalid" | "price_recurring_not_supported" | "price_immutable_while_used" | "line_item_missing_price" | "line_item_quantity_not_adjustable" | "line_item_quantity_out_of_bounds" | "line_item_quantity_not_supported_for_custom" | "checkout_empty_cart" | "promotion_codes_not_allowed" | "promotion_code_not_found" | "promotion_code_inactive" | "promotion_code_expired" | "promotion_code_max_redemptions" | "promotion_code_customer_mismatch" | "promotion_code_minimum_amount" | "promotion_code_first_time_only" | "coupon_invalid" | "coupon_currency_mismatch" | "coupon_minimum_amount" | "coupon_customer_max_redemptions" | "too_many_discounts" | "payment_method_corrupted" | "payment_method_customer_mismatch" | "payment_intent_customer_mismatch" | "payment_method_mismatch" | "payment_method_not_available" | "payment_intent_unexpected_state" | "charge_not_captured" | "merchant_no_balance" | "insufficient_balance" | "refund_outcome_unconfirmed" | "charge_missing_balance_transaction" | "charge_missing_fee_data" | "charge_incomplete_fee_data" | "cannot_rename_default" | "must_have_enabled_method" | "cannot_delete_default" | "configuration_in_use" | "unsupported_currency" | "exchange_rate_not_found" | "coupon_in_use" | "promotion_code_exists" | "tax_rate_archived" | "invoice_not_editable" | "invoice_not_finalizable" | "invoice_not_open" | "invoice_no_lines" | "invoice_customer_incomplete" | "invoice_already_paid" | "invoice_voided" | "invoice_has_payments" | "invoice_payment_in_progress" | "invoice_amount_not_supported" | "invoice_online_payment_unavailable" | "invoice_partial_payment_not_allowed" | "invoice_partial_amount_invalid" | "invoice_installments_mismatch" | "invoice_plan_with_part_payments" | "invoice_link_expired" | "invoice_currency_mismatch" | "invoice_line_limit_exceeded" | "invoice_number_taken" | "credit_note_amount_too_large" | "credit_note_split_mismatch" | "payout_plan_changed" | "payout_balance_not_entered" | "payout_account_short" | "hold_capture_refund_failed" | "rate_limit" | "idempotency_key_in_use" | "internal_error" | "request_timeout")) — Stable, machine-readable code identifying the specific failure (e.g. `resource_missing`, `parameter_invalid`, `authentication_required`). Always present on documented errors. See the API Error Codes reference for the full list.
  - `message` (string, required) — Human-readable description of what went wrong. Safe to log or display, but not stable — use `code` for programmatic branching.
  - `param` (string) — Name of the request parameter that caused the error, when applicable (e.g. `amount`, `currency`).
  - `doc_url` (string) — URL to the documentation page for this specific error code. Deep-linked into the API Error Codes reference.
  - `minimum_amount` (integer) — The order minimum a promotion code or coupon needs, in the smallest unit of the currency the customer pays in (`presentmentDetails.currency` when set, otherwise `currency`). Present on `promotion_code_minimum_amount` and `coupon_minimum_amount`.
- `request_id` (string) — Unique identifier for this request, propagated to logs and traces. Include it when contacting support.