Skip to main content

Create Sales Order Discount

POST 
/api/sales-orders/:salesOrder/discounts

Adds a discount to a sales order and recalculates the order's discount totals.

Required scope: orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token.

Request body fields:

  • scope (string, required): line (applies to one product line or charge line) or order (applies to the whole order).
  • type (string, required): percentage or fixed_amount.
  • rate (number, required when type is percentage): Percentage rate, 0-100.
  • amount (number, required when type is fixed_amount): Discount amount in the order currency, minimum 0. Defaults to 0 when omitted.
  • name (string, required, max 255): Display label.
  • sales_order_line_id (integer, required when scope is line): Existing product line on the order the discount applies to.
  • financial_line_id (integer, optional): Existing charge line (e.g. shipping) the discount applies to instead of a product line.
  • source_type (string, optional, max 50): Origin of the discount. Defaults to manual.
  • source_reference (string, optional, max 255): External reference such as a coupon code.
  • apply_before_tax (boolean, optional, default true): Whether the discount applies before tax is calculated.
  • sequence (integer, optional, min 0, default 0): Application order — lower values apply first.

Behavior:

  • Creating a discount immediately recalculates the order: per-line discount totals, proportional allocation of order-level discounts across product lines (any rounding remainder goes to the largest line), and the order's denormalized discount totals.
  • For percentage discounts the effective amount is computed during this recalculation and returned in the response.
  • Order-level percentage discounts are based on the order subtotal after line discounts; tax is included in the base when the order is configured to discount the grand total.

The response is the created discount object (no envelope), returned with status 201.

Path parameters:

  • salesOrder (required): Sales order ID.

Requires permission: sales_orders.update

Request​

Responses​

Created

Response Headers
    Content-Type