# Preview an invoice PDF (/en/api-reference/invoices/previewInvoicePdf)

Returns the PDF an invoice with this content would have, without saving it. It is the same document the customer receives, marked as a draft.

## POST /invoices/preview/pdf

### Request body (required)

Content type: `application/json`

- `customerId` (string | null) — Customer, to apply their credit
- `currency` (enum("EGP" | "USD" | "EUR" | "GBP" | "SAR" | "AED" | "QAR" | "KWD" | "JOD" | "OMR" | "BHD" | "LYD" | "AUD" | "CAD" | "CNY")) — Currency. Defaults to the account's.
- `lines` (Array<InvoiceLineInput>)
  - `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
- `dueDate` (string | null) — Date payment is due. Null means due on receipt.
- `daysUntilDue` (integer | null) — Days after finalization that payment is due. Cannot be sent with dueDate.
- `issueDate` (string | null) — Date shown on the invoice. Defaults to the day it is finalized.
- `discounts` (Array<InvoiceDiscountInput>) — Discounts on the whole invoice. Replaces the existing list.
- `defaultTaxRateIds` (Array<string>) — Tax rates applied to lines that set none of their own
- `shipping` (InvoiceShippingInput | null) — Shipping cost. Null removes it.
- `description` (string | null) — Memo shown to the customer
- `footer` (string | null) — Footer text
- `customFields` (Array<object>) — Custom fields, up to 4. Replaces the existing list.
  - `name` (string, required)
  - `value` (string, required)
- `paymentMethodTypes` (Array<enum("card" | "fawry" | "valu" | "apple_pay")> | null) — Payment methods the invoice accepts. Null means the account default.
- `allowPartialPayments` (boolean) — Let the customer pay part of the amount
- `minimumPartialAmount` (integer | null) — Smallest part payment accepted, in minor units
- `locale` (enum("auto" | "ar" | "en")) — Language of the email and pay page
- `pdfLanguage` (enum("ar" | "en" | "bilingual")) — Language of the PDF
- `delivery` (InvoiceDeliveryInput) — How the invoice is sent
  - `channels` (Array<enum("email" | "sms")>) — Channels to send on. Empty means you share the link yourself.
  - `additionalRecipients` (Array<string>) — Extra email recipients, up to 5
  - `message` (string | null) — Personal note added to the email
- `autoAdvance` (boolean) — Let XPay send reminders and handle overdue for this invoice
- `automaticallyFinalizesAt` (string (date-time) | null) — Finalize and send the draft at this time. Null cancels the schedule.
- `templateId` (string | null) — Template to take memo, footer and fields from
- `metadata` (object | null) — Custom metadata
- `settings` (InvoicePreviewSettingsInput) — Show the PDF with these invoice settings instead of the saved ones
  - `pdfPageSize` (enum("A4" | "Letter")) — Paper size
  - `taxRounding` (enum("per_line" | "per_invoice")) — Whether tax is rounded per line or once
  - `sample` (boolean) — Fill in a sample customer and pay link, to show a complete invoice

### Responses

#### 200 — PDF file

Content type: `application/pdf`

Type: `string`

#### 400 — Invalid invoice.

Content type: `application/pdf`

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

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

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