Skip to main content

Estimate Checkout

POST 

/api/portal/checkout/estimate

Preview subtotal plus estimated tax and shipping for the current cart before submitting. is_estimate is always true — final totals are confirmed by the merchant on the order. The subtotal here is net of any order-value discount the cart has earned, so it is what the buyer will be billed for goods.

Buyer portal token

Called by a B2B portal buyer with the bearer token POST /api/portal/auth/login returns (or the buyer's feed key) — not with a staff Personal Access Token.

Tax: when the seller has set up sales tax registrations, the ship-to state decides tax — ship_to_address_id (one of the account's saved addresses; defaults to the account's default shipping address). No tax when the seller does not collect in that state or the buyer's exemption is valid there; otherwise the registration's rate. tax_note explains the tax line and tax_status is one of: unknown_destination, not_registered, exempt, taxable, taxable_no_rate (both null when no registrations are set up, in which case an optional tax_rate_id is used as before).

Request fields (all optional)

  • tax_rate_id (integer) — used only when the seller has no sales tax registrations.
  • shipping_method_id (integer) — omitted, the account's default method for the destination is estimated.
  • ship_to_address_id (integer) — a saved address.
  • ship_to (object) — a typed address that is not saved yet (a one-time or dropship address): country_code, province, province_code, zip, city. When no ship_to_address_id is sent, tax and the default shipping method follow this address, so the totals track the address as it is entered.
  • dropship (object) — preview a dropship order: dropship.enabled (boolean) and dropship.shipping_method_id (integer, the requested service; takes precedence over shipping_method_id).

Dropship preview. With dropship.enabled on an account with dropship turned on, subtotal uses the dropship pricing, shipping_estimate is the dropship shipping charge, tax is on the goods, the dropship fee and the shipping charge at the consumer's destination (matching the order that will be created, whose fee and shipping lines carry the order's tax rate), total_estimate is goods + fee + shipping + tax, and min_order_value is null when the program exempts dropship orders. The dropship block adds: fee (dropship fee), shipping and shipping_label (the shipping charge and how it is described), shipping_mode (none, flat, rate_table, actual — billed at label cost after shipping), free_shipping_applied, shipping_available (false when the chosen service is not offered for dropship, so no charge could be worked out), ship_by_date (the date the order would ship by if placed now) and exempt_minimums. dropship is null for a normal estimate.

Shipping: the selected shipping_method_id (else the account's default for the ship-to) is priced for the cart. The ship-to is ship_to_address_id or an ad-hoc ship_to (name, address1, city, province, province_code, zip, country_code) not saved yet. shipping_estimate is null when the method is calculated on review or does not apply. shipping_label is Free, Calculated on review, Estimated (a live carrier rate) or null (a plain flat price); shipping_mode is live_rate, flat, free or on_review; shipping_is_estimate is true for a live rate; free_shipping is the cart's progress toward free shipping (threshold, remaining, met, account_free) or null.

When the seller calculates tax live with a tax engine (Numeral), the engine prices the basket for the ship-to address instead (the Shipping charge included, on the engine's shipping category): tax_status is live_calculated and tax_estimate is the engine's tax, or — when the engine cannot tax the address (ZIP / state mismatch, malformed address) — tax_status is tax_address_invalid, tax_estimate is null and tax_note tells the buyer what to fix. Submitting checkout with such an address returns 422 tax_address_invalid. If the engine is unavailable for any other reason the registration-based estimate above is returned.

Request​

Responses​

OK

Response Headers
    Content-Type