Skip to main content

Migrate to Order Total v2

Move from deprecated orderTotal to orderTotalV2 for clearer financial breakdown on orders.

Overview​

OrderTotal is being replaced by OrderTotalV2, which separates customer totals, payments, service provider charges, and payout with composable breakdown lines.

Before you begin​

  • You currently send orderTotal on order create or update
  • Ability to validate payloads with a test store

Guidelines​

  • Send at least one of orderTotal or orderTotalV2. Both are accepted during migration; when both are present, orderTotalV2 takes precedence. Prefer V2 alone for new work.
  • Prefer separate VALUE and TAX lines instead of VALUE_WITH_TAX when you know the split. Use VALUE_WITH_TAX only when the breakdown is unknown.
  • Do not send duplicate values. Customer total is the sum of customerTotal fields except those marked as VAT.

orderTotalV2 structure (summary)​

  • customerTotal — food sales, fees, tips, etc., with optional nested breakdown (e.g. foodSales.breakdown with subType VALUE / VAT).
  • customerPayment — payment and prepayment detail.
  • serviceProviderCharge — provider charge breakdown.
  • payout — payout breakdown.

Full field definitions: API reference.

Steps​

  1. Map existing orderTotal fields to orderTotalV2 breakdown lines.
  2. Send test orders with orderTotalV2 only.
  3. Validate totals match your legacy payloads.
  4. Roll out per your release process.

Verify​

Compare order financials in Otter with your source system for several order types (tax-inclusive, discounts, adjustments).

Next​