Partners

Checkout fees

Add required charges and optional services to a market's checkout.

Checkout fees let an integration manage required charges and optional services for a market. Read requests require read_markets; changes require write_markets. Required fees apply automatically. Optional fees are offered for selection. Percentage fees use merchandise after product and order discounts, while fixed fees may apply once per order or once per merchandise unit. A fee's selected market tax class is applied after its amount is resolved.

Endpoints#

List checkout fees

GET read_markets

List the required charges and optional services configured for a market.

Fees are returned in checkout order together with the live authoring contract. Required fees are applied automatically. Optional fees are available for the customer or an admin to select. Percentage fees use merchandise after product and order discounts; fixed per-item fees multiply by the total merchandise quantity.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 404 NOT_FOUND

    The market or checkout fee does not exist in this store.

Get a checkout fee

GET read_markets

Read one checkout fee and its complete amount, application, availability, and tax configuration.

Use the returned currency map and contract metadata when populating an edit form. Historical orders retain the fee snapshot recorded when they were placed.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789
feeId required uuid

Checkout fee ID.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 404 NOT_FOUND

    The market or checkout fee does not exist in this store.

Create a checkout fee

POST write_markets

Add a required charge or optional service to a market.

Fixed fees require an amount for every market currency and may apply once per order or once per merchandise unit. Percentage fees apply once per order to discounted merchandise. A selected tax class must belong to this market. A successful create publishes checkout_fees/create.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name required string

Merchant-facing fee or service name.

Example: Gift wrapping
description string

Optional explanation shown with an optional service.

Example: Wrap the order before dispatch
fee_type required string

Use fixed for currency amounts or percent for a share of discounted merchandise.

Example: fixed
percent_value string|null

Percentage of discounted merchandise when fee_type is percent.

Example: 2.5
fee_amounts object

Positive fixed amount keyed by every market currency when fee_type is fixed. Follow the money_max checkout limit and settled currency precision: for example KRW 0, USD/IDR 2, KWD 3 fractional digits.

Example: {"USD":"5.00"}
apply_per required string

Use order to charge once or item to multiply a fixed fee by total merchandise quantity. Percentage fees use order.

Example: order
tax_class_id uuid|null

Tax class from this market applied to the resolved fee.

Example: 4be5c5d1-0999-48ea-a2e0-f86703d99169
hsn_code string

HSN or SAC code retained with the fee for tax reporting.

Example: 996812
is_enabled required boolean

Whether the fee can participate in checkout.

Example: true
is_optional required boolean

Whether the customer or admin chooses the fee instead of it applying automatically.

Example: true

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    The request body is not valid JSON.
  • 400 CHECKOUT_FEE_NAME_REQUIRED

    name is empty.
  • 400 CHECKOUT_FEE_NAME_TOO_LONG

    name exceeds the live contract limit.
  • 400 CHECKOUT_FEE_DESCRIPTION_TOO_LONG

    description exceeds the live contract limit.
  • 400 CHECKOUT_FEE_TYPE_INVALID

    fee_type or its accompanying value fields are invalid.
  • 400 CHECKOUT_FEE_APPLY_PER_INVALID

    apply_per is not supported for this fee type.
  • 400 CHECKOUT_FEE_PERCENT_RANGE

    percent_value is missing or is outside the accepted range.
  • 400 CHECKOUT_FEE_AMOUNT_NEGATIVE

    A fixed currency amount is negative.
  • 400 INVALID_INPUT

    A required market currency amount is missing or has invalid precision.
  • 400 TAX_CLASS_NOT_IN_MARKET

    The selected tax class does not belong to this market.
  • 404 NOT_FOUND

    The market or checkout fee does not exist in this store.
  • 400 CHECKOUT_FEE_LIMIT_REACHED

    The market already has the maximum number of checkout fees.

Update a checkout fee

PUT write_markets

Replace the editable definition of one checkout fee.

Send the complete definition you want to keep. An unchanged request leaves timestamps, audit history, and webhooks untouched. A successful change publishes checkout_fees/update.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789
feeId required uuid

Checkout fee ID.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name required string

Merchant-facing fee or service name.

Example: Gift wrapping
description string

Optional explanation shown with an optional service.

Example: Wrap the order before dispatch
fee_type required string

Use fixed for currency amounts or percent for a share of discounted merchandise.

Example: fixed
percent_value string|null

Percentage of discounted merchandise when fee_type is percent.

Example: 2.5
fee_amounts object

Positive fixed amount keyed by every market currency when fee_type is fixed. Follow the money_max checkout limit and settled currency precision: for example KRW 0, USD/IDR 2, KWD 3 fractional digits.

Example: {"USD":"5.00"}
apply_per required string

Use order to charge once or item to multiply a fixed fee by total merchandise quantity. Percentage fees use order.

Example: order
tax_class_id uuid|null

Tax class from this market applied to the resolved fee.

Example: 4be5c5d1-0999-48ea-a2e0-f86703d99169
hsn_code string

HSN or SAC code retained with the fee for tax reporting.

Example: 996812
is_enabled required boolean

Whether the fee can participate in checkout.

Example: true
is_optional required boolean

Whether the customer or admin chooses the fee instead of it applying automatically.

Example: true

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 STORE_API_INVALID_REQUEST_BODY

    The request body is not valid JSON.
  • 400 CHECKOUT_FEE_NAME_REQUIRED

    name is empty.
  • 400 CHECKOUT_FEE_NAME_TOO_LONG

    name exceeds the live contract limit.
  • 400 CHECKOUT_FEE_DESCRIPTION_TOO_LONG

    description exceeds the live contract limit.
  • 400 CHECKOUT_FEE_TYPE_INVALID

    fee_type or its accompanying value fields are invalid.
  • 400 CHECKOUT_FEE_APPLY_PER_INVALID

    apply_per is not supported for this fee type.
  • 400 CHECKOUT_FEE_PERCENT_RANGE

    percent_value is missing or is outside the accepted range.
  • 400 CHECKOUT_FEE_AMOUNT_NEGATIVE

    A fixed currency amount is negative.
  • 400 INVALID_INPUT

    A required market currency amount is missing or has invalid precision.
  • 400 TAX_CLASS_NOT_IN_MARKET

    The selected tax class does not belong to this market.
  • 404 NOT_FOUND

    The market or checkout fee does not exist in this store.

Delete a checkout fee

DELETE write_markets

Remove a checkout fee from future calculations.

Existing orders keep their saved fee and tax evidence. A successful deletion publishes checkout_fees/delete with the fee's last known identity.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789
feeId required uuid

Checkout fee ID.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 404 NOT_FOUND

    The market or checkout fee does not exist in this store.

Reorder checkout fees

POST write_markets

Set the order in which checkout fees are presented.

Send every current fee id exactly once. An unchanged order is a no-op. A successful change publishes checkout_fees/reorder with the complete ordered id list.

Path parameters

Name Type Description
marketId required uuid

Market id.

Example: 9a1f2c3d-4e5f-6789-abcd-ef0123456789

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
fee_ids required array<uuid>

Every current checkout fee id in the order checkout should present them.

Example: ["2a7f1c3d-4e5b-4890-a6c8-1d3e5f7a9b0c","6a9d2e4f-1b3c-4785-9a0d-2e4f6a8b1c3d"]

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    marketId must be a valid UUID.
  • 400 CHECKOUT_FEE_REORDER_INVALID

    fee_ids does not contain every current checkout fee exactly once.
  • 404 NOT_FOUND

    The market does not exist in this store.

Webhook events#

Subscribe to these events when your app keeps a local copy of checkout fees. Create and update events contain the complete saved fee. Delete identifies the removed fee. Reorder contains the complete ordered id list. Requests that make no effective change do not publish an event.

Checkout fee created

EVENT checkout_fees/create App scope: read_markets Staff permission: markets:write

Subscribe to receive a checkout fee after it is created in a market.

Payload fields

Field Type Description
checkout_fee.id string Always present
checkout_fee.market_id string Selectable in the Payload builder
checkout_fee.name string Selectable in the Payload builder
checkout_fee.description string Selectable in the Payload builder
checkout_fee.fee_type string Selectable in the Payload builder
checkout_fee.percent_value string Selectable in the Payload builder
checkout_fee.fee_amounts object Selectable in the Payload builder
checkout_fee.apply_per string Selectable in the Payload builder
checkout_fee.tax_class_id string Selectable in the Payload builder
checkout_fee.hsn_code string Selectable in the Payload builder
checkout_fee.is_enabled boolean Selectable in the Payload builder
checkout_fee.is_optional boolean Selectable in the Payload builder
checkout_fee.sort_order integer Selectable in the Payload builder
checkout_fee.created_at string Selectable in the Payload builder
checkout_fee.updated_at string Selectable in the Payload builder

Checkout fee updated

EVENT checkout_fees/update App scope: read_markets Staff permission: markets:write

Subscribe to receive the current checkout fee after its amount, application, tax treatment, availability, or position changes.

Payload fields

Field Type Description
checkout_fee.id string Always present
checkout_fee.market_id string Selectable in the Payload builder
checkout_fee.name string Selectable in the Payload builder
checkout_fee.description string Selectable in the Payload builder
checkout_fee.fee_type string Selectable in the Payload builder
checkout_fee.percent_value string Selectable in the Payload builder
checkout_fee.fee_amounts object Selectable in the Payload builder
checkout_fee.apply_per string Selectable in the Payload builder
checkout_fee.tax_class_id string Selectable in the Payload builder
checkout_fee.hsn_code string Selectable in the Payload builder
checkout_fee.is_enabled boolean Selectable in the Payload builder
checkout_fee.is_optional boolean Selectable in the Payload builder
checkout_fee.sort_order integer Selectable in the Payload builder
checkout_fee.created_at string Selectable in the Payload builder
checkout_fee.updated_at string Selectable in the Payload builder

Checkout fee deleted

EVENT checkout_fees/delete App scope: read_markets Staff permission: markets:write

Subscribe to remove a deleted checkout fee from your integration. The payload keeps its id, market id, and last known name.

Payload fields

Field Type Description
checkout_fee.id string Always present
checkout_fee.market_id string Selectable in the Payload builder
checkout_fee.name string Selectable in the Payload builder

Checkout fees reordered

EVENT checkout_fees/reorder App scope: read_markets Staff permission: markets:write

Subscribe to receive the complete checkout fee order after fees are rearranged in a market.

Payload fields

Field Type Description
market_id string Always present
fee_ids array Selectable in the Payload builder

Last updated Oct 21, 2026