# Add lines to a draft invoice (/ar/api-reference/invoices/addInvoiceLines)

Adds up to 50 lines to the end of a draft.

## POST /invoices/{id}/add-lines

### Parameters

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

### Request body (required)

Content type: `application/json`

- `lines` (Array<InvoiceLineInput>, required)
  - `priceId` (string | null) — Catalog price to bill. Its product name and amount are copied onto the line.
  - `description` (string | null) — What is being billed. Required without priceId.
  - `quantity` (number) — Quantity, up to 3 decimal places. Defaults to 1.
  - `unitLabel` (string | null) — Unit, such as hour
  - `unitAmount` (integer | null) — Price of one unit in minor units. Required without priceId. May be negative.
  - `taxRateIds` (Array<string> | null) — Tax rates for this line. Omit to use the invoice default.
  - `discounts` (Array<InvoiceDiscountInput> | null) — Discounts on this line
  - `period` (object | null) — Service period the line covers. Null removes it.
    - `start` (string, required) — Start of the service period
    - `end` (string, required) — End of the service period
  - `metadata` (object | null) — Custom metadata

### Responses

#### 200 — Invoice with the new lines

Content type: `application/json`

- `id` (string, required) — Invoice ID
- `object` (enum("invoice"), required) — Object type
- `merchantId` (string, required) — Merchant ID
- `livemode` (boolean, required) — Whether this is a live mode invoice
- `status` (enum("draft" | "open" | "paid" | "uncollectible" | "void"), required) — Stored status
- `displayStatus` (enum("draft" | "scheduled" | "open" | "past_due" | "partially_paid" | "paid" | "uncollectible" | "void"), required) — Status to show people: adds scheduled, past due and partially paid
- `number` (string | null, required) — Invoice number, assigned when the invoice is finalized
- `collectionMethod` (enum("send_invoice" | "charge_automatically"), required) — How the invoice is collected
- `billingReason` (enum("manual"), required) — Why the invoice was created
- `currency` (enum("EGP" | "USD" | "EUR" | "GBP" | "SAR" | "AED" | "QAR" | "KWD" | "JOD" | "OMR" | "BHD" | "LYD" | "AUD" | "CAD" | "CNY"), required) — Currency of every amount on the invoice
- `customerId` (string, required) — Customer the invoice is for
- `customerName` (string | null, required) — Customer name
- `customerEmail` (string | null, required) — Customer email
- `customerPhone` (string | null, required) — Customer phone number
- `issueDate` (string | null, required) — Date shown on the invoice (YYYY-MM-DD)
- `dueDate` (string | null, required) — Date payment is due (YYYY-MM-DD). Null means due on receipt.
- `daysUntilDue` (integer | null, required) — Days after finalization that payment is due, when set instead of a date
- `isOverdue` (boolean, required) — Whether the due date has passed with an amount remaining
- `daysOverdue` (integer, required) — Whole days past the due date, or 0
- `total` (integer, required) — What the invoice is worth, in minor units
- `amountDue` (integer, required) — What the customer must pay in total, after customer credit. Credit notes do not change it.
- `amountPaid` (integer, required) — Received so far, in minor units
- `amountRemaining` (integer, required) — Still to pay, in minor units
- `statusTransitions` (object, required) — When the invoice reached each status
  - `finalizedAt` (string | null, required) — When the invoice was finalized (ISO 8601)
  - `paidAt` (string | null, required) — When the invoice was paid in full (ISO 8601)
  - `markedUncollectibleAt` (string | null, required) — When the invoice was marked uncollectible (ISO 8601)
  - `voidedAt` (string | null, required) — When the invoice was voided (ISO 8601)
- `sentAt` (string | null, required) — When the invoice was first sent (ISO 8601)
- `firstViewedAt` (string | null, required) — When the customer first opened the invoice (ISO 8601)
- `automaticallyFinalizesAt` (string | null, required) — When a scheduled draft will be finalized and sent (ISO 8601)
- `createdAt` (string, required) — Created timestamp (ISO 8601)
- `updatedAt` (string, required) — Updated timestamp (ISO 8601)
- `customerAddress` (CustomerAddress | null, required) — Customer billing address
- `customerShipping` (CustomerAddress | null, required) — Customer shipping address
- `customerTaxIds` (Array<InvoiceTaxId>, required) — Customer tax IDs shown on the invoice
  - `type` (string, required) — Tax ID type, such as eg_tin
  - `value` (string, required) — Tax ID value
- `customerLocale` (enum("ar" | "en"), required) — Language the customer is addressed in
- `accountName` (string | null, required) — Business name shown on the invoice
- `accountTaxNumber` (string | null, required) — Business tax registration number
- `subtotal` (integer, required) — Sum of line amounts before discounts and exclusive tax
- `totalDiscountAmounts` (Array<object>, required) — Discounts on the invoice, one row each
  - `amount` (integer, required) — Discount amount
  - `name` (string | null, required)
- `subtotalExcludingTax` (integer, required) — Subtotal after discounts, with no tax in it
- `totalExcludingTax` (integer, required) — Total with no tax in it
- `totalTaxes` (Array<InvoiceTaxAmount>, required) — Tax totals, one row per tax 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
- `amountShipping` (integer, required) — Shipping cost before tax
- `shippingCost` (object | null, required) — Shipping charged on the invoice, if any
  - `amountSubtotal` (integer, required) — Shipping before tax
  - `amountTax` (integer, required) — Tax on shipping
  - `amountTotal` (integer, required) — Shipping with tax
  - `taxRateIds` (Array<string>, required) — Tax rates applied to shipping
- `startingBalance` (integer, required) — Customer balance when the invoice was finalized. Negative is credit. Zero on a draft.
- `endingBalance` (integer | null, required) — Customer balance after the invoice used it. Null until finalized.
- `prePaymentCreditNotesAmount` (integer, required) — Credit notes issued before any payment
- `postPaymentCreditNotesAmount` (integer, required) — Credit notes issued after payment
- `amountOverpaid` (integer, required) — Paid above the amount due, moved to customer credit
- `description` (string | null, required) — Memo shown to the customer
- `footer` (string | null, required) — Footer text
- `customFields` (Array<InvoiceCustomField>, required) — Custom fields, up to 4
  - `name` (string, required) — Field label, such as PO number
  - `value` (string, required) — Field value
- `discounts` (Array<InvoiceDiscount>, required) — Discounts on the whole invoice
  - `type` (enum("percent" | "amount"), required) — Percentage or fixed amount
  - `percent` (number | null, required) — Percentage off, when type is percent
  - `amount` (integer | null, required) — Amount off in minor units, when type is amount
  - `name` (string | null, required) — Name shown on the invoice
  - `couponId` (string | null, required) — Coupon the discount was created from, if any
  - `appliedAmount` (integer, required) — What this discount took off, in minor units
- `defaultTaxRateIds` (Array<string>, required) — Tax rates applied to lines that set none of their own
- `lines` (Array<InvoiceLineItem>, required) — Line items, in order
  - `id` (string, required) — Line item ID
  - `object` (enum("line_item"), required) — Object type
  - `position` (integer, required) — Order of the line on the invoice, starting at 0
  - `description` (string, required) — What is being billed
  - `quantity` (number, required) — Quantity, with up to 3 decimal places
  - `unitLabel` (string | null, required) — Unit shown after the quantity, such as hour
  - `pricing` (object, required) — How the line is priced
    - `unitAmount` (integer, required) — Price of one unit in minor units
    - `priceDetails` (object | null, required) — The catalog price the line was created from, if any
  - `period` (object | null, required) — Service period the line covers, if any
    - `start` (string, required) — Start of the service period (YYYY-MM-DD)
    - `end` (string, required) — End of the service period (YYYY-MM-DD)
  - `discounts` (Array<InvoiceDiscount>, required) — Discounts set on this line
    - `type` (enum("percent" | "amount"), required) — Percentage or fixed amount
    - `percent` (number | null, required) — Percentage off, when type is percent
    - `amount` (integer | null, required) — Amount off in minor units, when type is amount
    - `name` (string | null, required) — Name shown on the invoice
    - `couponId` (string | null, required) — Coupon the discount was created from, if any
    - `appliedAmount` (integer, required) — What this discount took off, in minor units
  - `taxRateIds` (Array<string>, required) — Tax rates applied to this line
  - `inheritsDefaultTaxRates` (boolean, required) — Whether the line has no tax rates of its own and takes the invoice's default ones
  - `subtotal` (integer, required) — Quantity times unit amount, before discounts and taxes
  - `discountAmounts` (Array<object>, required) — Discounts taken off this line, including its share of invoice discounts
    - `amount` (integer, required) — Discount amount
    - `name` (string | null, required)
  - `amount` (integer, required) — Line amount after discounts, before exclusive tax
  - `taxes` (Array<InvoiceTaxAmount>, required) — Tax calculated for this line
    - `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
  - `amountExcludingTax` (integer, required) — Line amount after discounts, with no tax in it
  - `amountTotal` (integer, required) — Line amount after discounts, with tax
  - `metadata` (object | null, required) — Custom metadata
- `installments` (Array<InvoiceInstallment>, required) — Payment plan, empty when there is none
  - `id` (string, required) — Installment ID
  - `object` (enum("invoice_installment"), required) — Object type
  - `position` (integer, required) — Order of the installment, starting at 1
  - `description` (string | null, required) — Optional name, such as Deposit
  - `amountDue` (integer, required) — Installment amount in minor units
  - `amountPaid` (integer, required) — Paid towards this installment in minor units
  - `dueDate` (string, required) — Date the installment is due (YYYY-MM-DD)
  - `status` (enum("open" | "paid" | "past_due"), required) — open, paid or past_due
- `payments` (Array<[Invoice Payment](/ar/api-reference/objects/invoice-payment)>, required) — Payments made on the invoice
- `paymentSettings` (object, required) — How the invoice can be paid
  - `paymentMethodTypes` (Array<enum("card" | "fawry" | "valu" | "apple_pay")> | null, required) — Payment methods the invoice accepts. Null means the account default.
- `allowPartialPayments` (boolean, required) — Whether the customer may pay part of the amount
- `minimumPartialAmount` (integer | null, required) — Smallest part payment accepted, in minor units
- `locale` (enum("auto" | "ar" | "en"), required) — Language of the email and pay page
- `pdfLanguage` (enum("ar" | "en" | "bilingual"), required) — Language of the PDF
- `delivery` (InvoiceDelivery, required) — How the invoice is sent
  - `channels` (Array<enum("email" | "sms")>, required) — Channels used when sending
  - `additionalRecipients` (Array<string>, required) — Extra email recipients
  - `message` (string | null, required) — Personal note added to the email
- `autoAdvance` (boolean, required) — Whether XPay sends reminders and handles overdue for this invoice
- `templateId` (string | null, required) — Template the invoice was created from
- `fromInvoice` (object | null, required) — Set on an invoice that revises another
  - `action` (enum("revision"), required) — What this invoice is to the other one
  - `invoiceId` (string, required) — The invoice this one replaces
- `latestRevisionId` (string | null, required) — Invoice that replaced this one
- `hostedInvoiceUrl` (string | null, required) — Page where the customer views and pays the invoice
- `hostedInvoiceUrlExpiresAt` (string | null, required) — When the link stops working (ISO 8601). Null while the invoice can be paid.
- `metadata` (object | null, required) — Custom metadata

#### 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.