# Create a tax rate (/en/api-reference/tax-rates/createTaxRate)

Creates a reusable tax rate. The percentage and the inclusive setting cannot be changed later.

## POST /tax-rates

### Request body (required)

Content type: `application/json`

- `displayName` (string, required) — Name shown on invoices, such as VAT
- `displayNameAr` (string | null) — Arabic name shown on Arabic and bilingual invoices
- `percentage` (number, required) — Tax percentage, up to 4 decimal places
- `inclusive` (boolean, required) — Whether prices already include this tax
- `description` (string | null) — Internal note
- `metadata` (object | null) — Custom metadata

### Responses

#### 201 — Tax rate created

Content type: `application/json`

- `id` (string, required) — Tax rate ID
- `object` (enum("tax_rate"), required) — Object type
- `displayName` (string, required) — Name shown on invoices, such as VAT
- `displayNameAr` (string | null, required) — Arabic name shown on Arabic and bilingual invoices
- `percentage` (number, required) — Tax percentage
- `inclusive` (boolean, required) — Whether prices already include this tax. Cannot change after creation.
- `description` (string | null, required) — Internal note, not shown to customers
- `active` (boolean, required) — Archived rates stay on existing invoices but cannot be added
- `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)

#### 400 — Invalid tax rate.

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.

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