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.
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 noship_to_address_idis 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) anddropship.shipping_method_id(integer, the requested service; takes precedence overshipping_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
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Validation failed — the body is a field → messages map (Laravel shape) or the platform envelope with a stable machine-readable code. Fix the payload and resubmit.
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.