Skip to main content

Apply Sales Order Shipping Estimate

POST 
/api/sales-orders/:salesOrder/shipping-estimates/:shippingEstimate/apply

Applies one rate from a recorded estimate to the sales order: creates or replaces the order's REVENUE "Shipping" financial line (described as "<Carrier> <Service> (est.)", quantity 1, taxed at the order's tax rate), optionally sets the shipping method, marks the estimate applied and clears shipping_pending_review. With record_only it records the cost only and writes no line.

Required scope: orders:write

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

Request body:

  • option_key (string, required, max 120): the key of one of the estimate's options, e.g. UPS|Ground.
  • markup_type (string, nullable): percent or flat. Defaults to the account's default markup.
  • markup_value (number, nullable, 0–100000): percent of the rate, or a flat amount added to it.
  • charge_amount (number, nullable, 0–1000000): charge exactly this amount; wins over any markup.
  • replace_financial_line_id (integer, nullable): the existing Shipping line to replace. When omitted, a order with no Shipping line gets a new one, one with a single Shipping line has it replaced, and one with several is refused with 422 until you name one or send add_new.
  • add_new (boolean): add a new Shipping line even when one exists.
  • set_shipping_method (boolean): also set the shipping method to the account's method that matches this carrier and service, when one clearly does.
  • record_only (boolean): record the rate as the shipping cost only, without adding a charge.

Response (data): financial_line (the line written, with its financial_line_type; null for record_only), estimate (the updated estimate row, as in List Sales Order Shipping Estimates) and shipping_pending_review.

Errors: 404 when the estimate does not belong to this order; 422 when the order cannot be quoted (channel order, cancelled, closed, invoiced), the option_key is not part of the estimate, the named line is not one of the order's Shipping lines, several Shipping lines exist and none was chosen, or an issued invoice already bills the line being replaced.

Authentication: Requires Bearer token.

Requires permission: sales_orders.update

Request​

Responses​

OK

Response Headers
    Content-Type