--- title: "Update order" method: PUT path: "/v1/orders/{orderId}" tags: ["orders_endpoints"] --- # Update order `PUT /v1/orders/{orderId}` ## Request - Base URL: `https://partners.tryotter.com` - URL: `https://partners.tryotter.com/v1/orders/{orderId}` - Auth: OAuth 2 - Authorization code: `/v1/auth/oauth2/authorize` - Client credentials - Token URL: `/v1/auth/token` scopes: `orders.update` - TypeScript: (a function with typed inputs; its response is checked against the schema) Replaces the order identified by `orderId` with the full order payload provided in the request body. Send the complete order representation (the same shape used to create it), not a partial patch. To change only the status, customer payment, or delivery information, prefer the dedicated `/status`, `/payments`, and `/delivery` endpoints. Returns 404 if no order matches the given `orderId` for this store. Rate limit: 32 requests per minute. ## Path parameters - `orderId` string, required: The external order identifier supplied by your app in `externalIdentifiers.id` when the order was created. ## Headers - `X-Store-Id` string, required: The unique identifier of the store in your app. This ID, along with the `Application ID`, will be used to match the correct store when performing operations. It cannot be longer than 255 characters and must only contain printable ASCII characters. During on-boarding, this ID will be similar to `onboarding:905bb725-b141-4a9b-832a-1f254f772c94` (where the UUID is the Internal Store ID). During off-boarding, this field will be filled with the last known Store ID, or with an empty string, in case none is found. In that case, please fall back to the provided `internalStoreId` (a.k.a. Sku-Sku ID). ## Request body - Order: An order placed by a customer. Orders are pushed into Otter by ordering marketplaces / order sources and read back (including merchant-side detail) via the Orders Manager endpoints. The same `Order` object is used as the create/update request body, as the GET response, and as the payload of the order webhooks. Monetary values: every amount on an order uses the major unit of `currencyCode`. The financial breakdown is carried in `orderTotal` (V1, flat aggregates) and/or `orderTotalV2` (V2, line-itemized) — at least one of the two must be provided on create/update; if both are sent, `orderTotalV2` takes precedence for the financial breakdown. - `externalIdentifiers` OrderExternalIdentifiers, required: The external identifiers. - `id` string, required: Unique ID for the order that was placed. - `friendlyId` string, required: ID used for driver pickup and restaurant management. - `source` string, nullable: Describes the source of the order, typically from a food ordering marketplace. - `sourceType` 'POINT_OF_SALE' | 'ORDERING_MARKETPLACE' | 'AGGREGATOR' | 'CUSTOMER_INTERACTION', nullable: source type of the order - `sourceExternalIdentifiers` SourceExternalIdentifiers, nullable: The external identifiers. - `id` string: Unique ID for the order that was placed. - `friendlyId` string: ID used for driver pickup and restaurant management. - `source` string: Describes the source of the order, typically from a food ordering marketplace. - `sourceType` 'POINT_OF_SALE' | 'ORDERING_MARKETPLACE' | 'AGGREGATOR' | 'CUSTOMER_INTERACTION': source type of the order - `sourceExternalIdentifiers` SourceExternalIdentifiers (recursive) - `currencyCode` string, required: The 3-letter currency code (ISO 4217) used for **all** monetary values in this order (item prices, modifier prices, and every amount in `orderTotal` / `orderTotalV2`). All amounts are expressed in the major unit of this currency (for example `12.50`), never in minor units (cents). - `status` 'NEW_ORDER' | 'CONFIRMED' | 'PICKED_UP' | 'CANCELED' | 'FULFILLED' | 'PREPARED' | 'REJECTED' | 'PREVISIT_COMPLETED' | 'PREVISIT_NO_SHOW' | 'UNKNOWN', required: The current status of the order. When creating an order this is typically `NEW_ORDER` (awaiting confirmation) or `CONFIRMED`. `UNKNOWN` is returned only when the status cannot be mapped. - `items` Item[]: The items ordered by the customer, including their modifiers. If you send an order with an empty list, the platform creates a single placeholder "Custom item" priced at the order subtotal. - `quantity` integer, required: The quantity of the item ordered by the customer. - `skuPrice` number, nullable: The stored sku price of this item - `id` string, nullable: The unique ID of the item. - `lineItemId` string, nullable: The unique ID of the instance of an item in an order. Instances of the same item across different orders will have different line item IDs. Multiple instances of the same item in one order will have different line item IDs if their modifiers are different. - `skuId` string, nullable: sku ID of the item. - `name` string, nullable: The name of the item as displayed to the customer. - `note` string, nullable: An optional item-level note provided by the customer. - `categoryId` string, nullable: The unique ID of the category of this item. - `internalCategoryId` string, nullable: Otter's internal identifier for the item's category - `categoryName` string, nullable: The name of the category of this item. - `internalCategoryName` string, nullable: Otter's internal name for the item's category - `stationId` string, nullable: The ID of the station the item is assigned to. - `price` number, nullable: The unit price of the item (the price for a single unit, **not** multiplied by `quantity`), in the major unit of the order's `currencyCode`. The order's `subtotal` is the sum of item and modifier prices across the line items. - `modifiers` ItemModifier[], nullable: Modifiers to the base item. - `quantity` integer, required: The number of times the modifier was applied to the given item. - `skuPrice` number, nullable: The stored sku price of this item - `id` string, nullable: The unique ID of the modifier product. - `lineItemId` string, nullable: The unique ID of the instance of a modifier in an order. Instances of the same modifier across different orders will have different line item IDs. Multiple instances of the same modifier in one order will have different line item IDs if their modifiers are different. - `skuId` string, nullable: sku ID of the item. - `name` string, nullable: The name of the modifier as displayed to the customer. - `price` number, nullable: The unit price of the modifier (the price for a single application of the modifier, **not** multiplied by `quantity`), in the major unit of the order's `currencyCode`. - `groupName` string, nullable: The parent group of the modifier item - `groupId` string, nullable: The unique ID of the parent group - `stationId` string, nullable: The ID of the station the modifier item is assigned to. - `modifiers` ItemModifier[], nullable: Nested modifiers applied to the item. - `orderedAt` string, date-time, nullable: The date (in UTC) when the order was placed by the customer. - `customer` Person, nullable: The recipient information. - `name` string, nullable: The person's name as it should be displayed. - `phone` string, nullable: The person's phone number. - `phoneCode` string, nullable: A code or extension of the phone number. - `email` string, nullable: The person's email address. - `personalIdentifiers` PersonalIdentifiers, nullable: The person's personal identifiers (e.g. tax identification number). - `taxIdentificationNumber` string, nullable: Person tax identification number. - `serviceProviderId` string, nullable: External service provider ID i.e. Courier Id. - `customerNote` string, nullable: An order-level note provided by the customer. - `deliveryInfo` DeliveryInfo, nullable: Information on order's delivery process. - `courier` Courier, nullable: Details about the delivery courier. - `name` string, nullable: The person's name as it should be displayed. - `phone` string, nullable: The person's phone number. - `phoneCode` string, nullable: A code or extension of the phone number. - `email` string, nullable: The person's email address. - `personalIdentifiers` PersonalIdentifiers, nullable: The person's personal identifiers (e.g. tax identification number). - `taxIdentificationNumber` string, nullable: Person tax identification number. - `serviceProviderId` string, nullable: External service provider ID i.e. Courier Id. - `destination` Address, nullable: Order delivery address. - `fullAddress` string, nullable: Full, human comprehensible address. It is usually formatted in the order appropriate for your locale. - `postalCode` string: Postal code of the address. - `city` string: The city/town portion of the address. - `state` string: Highest administrative subdivision which is used for postal addresses of a country or region. For example, this can be a state, a province, or a prefecture. - `countryCode` string: CLDR country code. See http://cldr.unicode.org/ - `addressLines` string[], nullable: Address lines (e.g. street, PO Box, or company name) or the full single line address (e.g. street, city, state, country, zip). - `linesOfAddress` string[], nullable: Deprecated: use addressLines. Address lines (e.g. street, PO Box, or company name) or the full single line address (e.g. street, city, state, country, zip). - `location` Location, nullable: Latitude and longitude of the address. - `latitude` number, double, required: The latitude of the location. - `longitude` number, double, required: The longitude of the location. - `licensePlate` string, nullable: License plate of a vehicle used by the courier. - `makeModel` string, nullable: Make and model of a vehicle used by the courier. - `lastKnownLocation` Location, nullable: Latitude and longitude of the address. - `latitude` number, double, required: The latitude of the location. - `longitude` number, double, required: The longitude of the location. - `dropoffInstructions` DropoffInstructions, nullable: Requirements to verify the completion of the delivery. - `dropoffType` 'MEET_AT_DOOR' | 'LEAVE_AT_DOOR' | 'MEET_IN_LOBBY': The drop-off type for the delivery. - `verificationRequirements` VerificationRequirements, nullable: Verification requirements for the delivery. - `signatureRequirement` SignatureRequirement, nullable: Enables and configure the signature requirement. - `enabled` boolean: Marks the signature requirement as required. - `collectSignerName` boolean: Whether the signer's name should be collected. - `collectSignerRelationship` boolean: Whether the signer's relationship with the intended recipient should be collected. - `pictureRequirement` PictureRequirement, nullable: Enables and configure the picture requirement. - `enabled` boolean: Marks the picture requirement as required. - `note` string, nullable: Special delivery instructions, if any. - `orderTotal` OrderTotal: Flat, customer-facing breakdown of an order's monetary values (V1). `orderTotal` captures only what the customer was charged, as a small set of aggregate figures. It cannot express per-line taxes, the source of a discount, the split of tips/delivery fees between the store and the marketplace, or the store's net payout and the marketplace's charges. For any of those, prefer the richer `orderTotalV2`. When creating or updating an order you must supply **at least one** of `orderTotal` or `orderTotalV2`. You may send both; if you do, `orderTotalV2` takes precedence for the financial breakdown and the `orderTotal` aggregates are checked against it for consistency. All values are in the major unit of the order's `currencyCode`. - `subtotal` number, required: The order's calculated subtotal: the sum of all item and modifier prices **before** tax, tips, fees, and discounts are applied. This is the value the platform computes from the line items. All amounts in this object are expressed in the major unit of the order's `currencyCode` (for example `11.97` means 11 dollars and 97 cents), never in minor units (cents). - `claimedSubtotal` number, nullable: The subtotal as claimed by the order source (the ordering marketplace), which is **not guaranteed to match** the calculated `subtotal`. When you send an order, set this only if the source reports a subtotal that may differ from the sum of the line items; otherwise omit it and `subtotal` is used. Downstream reconciliation and reporting use this to surface discrepancies between what the source claimed and what the items add up to. - `discount` number, nullable: The total discount applied to the order, represented as a **negative** value (a discount reduces what the customer pays), e.g. `-1.10`. On input either sign is accepted — the platform normalizes the value to negative (it takes the absolute value and negates it) — but responses always return it negative. This is a single aggregate figure; to break a discount down by who funded it (restaurant, marketplace, voucher, promotion, operator, or loyalty) use `orderTotalV2` instead. - `tax` number, nullable: Total tax paid by the customer for this order. This is an aggregate; for a per-line tax / VAT breakdown use `orderTotalV2`. - `tip` number, nullable: Total tip paid by the customer. This is an aggregate that does not distinguish a tip destined for the restaurant from a tip destined for the delivery courier — `orderTotalV2` splits those into `tipForRestaurant` and `tipForServiceProviderCourier`. - `deliveryFee` number, nullable: Total delivery fee paid by the customer. This is an aggregate that does not distinguish a fee for store-provided delivery from a fee for marketplace-provided delivery — `orderTotalV2` splits those into `feeForRestaurantProvidedDelivery` and `feeForServiceProviderDelivery`. - `total` number, nullable: The grand total: everything paid by the customer for this order (subtotal + tax + tip + fees − discounts). This is the amount used as the customer-facing order value in receipts, reporting, and reconciliation. - `couponCode` string, nullable: Coupon code applied to the order. When an order carries multiple coupon codes they are joined into this single string with the pipe character (`|`) as a separator (for example `SAVE5|FREESHIP`). To send or receive coupon codes as a structured list, use `orderTotalV2.customerTotal.couponCodes`. - `orderTotalV2` OrderTotalV2, nullable: Richer, line-itemized breakdown of an order's monetary values (V2). `orderTotalV2` is the preferred way to describe order economics. Where the V1 `orderTotal` exposes only flat customer-facing aggregates, V2 captures four distinct perspectives, each as its own object: - **`customerTotal`** — what the customer was charged (food, fees, taxes, discounts, tips), with per-line tax/VAT detail. - **`customerPayment`** — how that total was settled (prepaid vs. collectable, cash change, amount collected directly by the store). - **`payout`** — what the store actually receives. - **`serviceProviderCharge`** — what the marketplace deducts (commission, processing, withholdings, etc.). Sign conventions: charges the customer pays are **positive**; discounts are **negative**. All amounts are in the major unit of the order's `currencyCode`. When creating or updating an order you must supply **at least one** of `orderTotal` or `orderTotalV2`. You may send both; when both are present `orderTotalV2` takes precedence for the financial breakdown. In that case the platform also performs a **soft consistency check** between the V1 aggregates and the V2 line items (within a ±0.01 tolerance): `total` against the sum of the customer-charge lines, `tax` against the sum of all tax lines, `discount` against the funded-discount lines, `deliveryFee` against the delivery-fee lines, and `tip` against the tip lines. A mismatch is logged/recorded for monitoring but does **not** reject the request. - `customerTotal` FinancialData, required: Breakdown of order values. Represents total values, fees, discounts, and any possible adjustments that may happen in the order value. Breakdown lists can be used to represent aggregate values (e.g. order total value) or, when available, can accurately represent the values of each item/fee/tax/charges related to the order. All objects in breakdown lists have a required property "subType". Allowed values are: **VALUE**: represent the net value of the order/item/fee. Should be used in the following cases: - when the amount does not contain taxes or VAT - when tax/VAT is a known value, in that case, the list must contain an object with subtype TAX or VAT representing this value. **TAX**: represent the tax value for the order/item/fee. Should be used when tax amount is available, in that case, this information should be part of the breakdown list with the "VALUE" as the net amount, example below: ``` "breakdown": [ { "name": "Item 1", "value": 10, "subType": "VALUE" }, { "name": "Item 1 - Tax", "value": 2, "subType": "TAX" } ] ``` **VAT**: represents the amount for value-added tax. Should be used when the order/item/fee contains VAT. In that case, this information should be part of the breakdown list with the "VALUE" as net amount, example below: ``` "breakdown": [ { "name": "Item 1", "value": 12, "subType": "VALUE" }, { "name": "Item 1 - Tax", "value": 2, "subType": "VAT" } ] ``` **VALUE_WITH_TAX**: represents the gross value of the order/item/fee. Should be used when the value includes tax/VAT and values related to taxation are not available. ``` "breakdown": [ { "name": "Item 1", "value": 12, "subType": "VALUE_WITH_TAX" } ] ``` - `foodSales` CompositeFinanceLine, required: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `feeForRestaurantProvidedDelivery` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `restaurantFundedDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `voucherDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `promotionDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `operatorDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `loyaltyDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `tipForRestaurant` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `adjustments` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `packingFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `bagFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `serviceProviderDiscount` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `tipForServiceProviderCourier` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `feeForServiceProviderDelivery` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `smallOrderFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `serviceFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `otherFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `netPayout` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `couponCodes` string[], nullable: Any codes entered by the customer at order checkout. - `customerPayment` CustomerPaymentV2, nullable: Details about customer payment. - `customerPaymentDue` number, nullable: The portion of the overall order cost that will be collected when the order is delivered, or when picked up by the customer at the store. This field should not be set if the order was pre-paid. - `customerPrepayment` number, nullable: The portion of the overall order cost that was paid upfront by the customer (online payment), with the remaining portion in the customerPaymentDue. In most cases the order value will be covered entirely by prepayment or entirely by payment_due. But in some cases mixing is allowed. - `customerAmountToReturn` number, nullable: Change (cash back) to be returned to the customer by the courier or store when the order has payment due value. Scenario: 1. Customer places an order for $7.50. 2. In the service app, after selecting Cash as payment type, the customer is presented with an additional field to indicate that order will be paid with a single $20 bill. 3. When the order is delivered, the courier should have $12.50 in cash on hand to complete the transaction. - `paymentDueToRestaurant` number, nullable: The portion of the overall order cost that was received directly by restaurant/store when the order is delivered or picked up. Should be used when customerPaymentDue is set. If payment due is entirely received by the store, customerPaymentDue and paymentDueToRestaurant will have the same value. - `payout` Payout, nullable: Breakdown of the net payout the store receives for this order, by source of the payout. The sum of these fields represents the money the store ultimately nets; pair it with `serviceProviderCharge` to reconcile against the customer-facing `customerTotal`. Amounts are in the major unit of the order's `currencyCode`. - `payoutFromServiceProvider` number, nullable: Amount the store is paid out by the order source (the ordering marketplace the order came from). For marketplace orders this is usually the customer total minus the marketplace's `serviceProviderCharge` deductions. - `payoutFrom3rdParty` number, nullable: Amount the store is paid out by a third-party organization involved in the order (for example a separate payment or delivery aggregator), when applicable. - `cashPayout` number, nullable: Amount the store effectively keeps from cash collected directly from the customer at pickup or delivery (cash never flows through the marketplace). - `serviceProviderCharge` ServiceProviderCharge, nullable: Breakdown of the charges the order source (the ordering marketplace / service provider) deducts from or bills to the store for this order. These are **not** charges paid by the customer — they reduce the store's gross revenue. Each line is a `CompositeFinanceLine` so the value can be split into net value, tax, and VAT. Together with `payout`, this object lets finance, BI, and reporting tools reconcile customer-facing revenue (`customerTotal`) against what the store ultimately nets. - `commission` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `processingFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `salesTaxWithheld` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `deliveryFeeForRestaurant` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `advertisingFee` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `chargesAdjustments` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `otherFees` CompositeFinanceLine: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects - `breakdown` SimpleFinanceLine[], required: Breakdown values for the finance line. - `subType` 'VALUE' | 'TAX' | 'VALUE_WITH_TAX' | 'VAT', required: type of the finance line. - `name` string, required: name of the finance line. - `value` number, required: money amount. - `customerPayments` CustomerPayment[], nullable: How the customer paid, as one entry per payment portion (amount, method, and processing status). These entries must be consistent with the amounts and methods described in `orderTotalV2.customerPayment` when V2 is used. - `value` number, required: The portion of the overall amount that needs to be paid. - `processingStatus` 'COLLECTABLE' | 'PROCESSED', required: The processing status of the payment. (PROCESSED is only valid when the payment method is CARD) - `paymentMethod` 'CASH' | 'CARD' | 'UNKNOWN' | 'OTHER' | 'CHEQUE' | 'GIFT_CARD', required: The method of payment. - `paymentAuthorizer` 'AMEX' | 'APPLE_PAY_AMEX' | 'APPLE_PAY_MASTERCARD' | 'APPLE_PAY_VISA' | 'BANRICOMPRAS' | 'BANRICOMPRAS_DEBIT' | 'CARNET' | 'CHEF_CARD' | 'DEBIT' | 'DINERS' | 'DISCOVER' | 'ELO' | 'ELO_DEBIT' | 'GER_CC_CREDITO' | 'GOODCARD' | 'GOOGLE_PAY_ELO' | 'GOOGLE_PAY_MASTERCARD' | 'GOOGLE_PAY_VISA' | 'HIPERCARD' | 'IFOOD_CORP' | 'LOOP_CLUB' | 'MASTERCARD' | 'MASTERCARD_DEBIT' | 'MASTERCARD_MAESTRO' | 'MOVILE_PAY' | 'MOVILE_PAY_AMEX' | 'MOVILE_PAY_DINERS' | 'MOVILE_PAY_ELO' | 'MOVILE_PAY_HIPERCARD' | 'MOVILE_PAY_MASTERCARD' | 'MOVILE_PAY_VISA' | 'NUGO' | 'NUTRICARD_REFEICAO_E_ALIMENTACAO' | 'OTHER_TYPE' | 'PAYPAL' | 'PIX' | 'PSE' | 'QR_CODE' | 'RAPPI_PAY' | 'TERMINAL_BANCARIA' | 'UNKNOWN_TYPE' | 'VALE_ALELO' | 'VALE_BEN_VIS' | 'VALE_COOPER_CARD' | 'VALE_GREEN_CARD_CARD' | 'VALE_GREEN_CARD_PAPEL' | 'VALE_REFEISUL' | 'VALE_SODEXO' | 'VALE_TICKET_RESTAURANTE' | 'VALE_VEROCARD' | 'VALE_VR_SMART' | 'VERDECARD' | 'VISA' | 'VISA_DEBIT' | 'VISA_ELECTORN', nullable: A payment system type responsible for a card transaction (containing information for payment network and payment type). - `cardInfo` CardInfo, nullable: Additional card information. - `paymentNetwork` 'MASTERCARD' | 'MASTERCARD_MAESTRO' | 'VISA' | 'AMEX' | 'DINERS' | 'ELO' | 'HIPERCARD' | 'BANRICOMPRAS' | 'NUGO' | 'GOODCARD' | 'ELO_MAIS' | 'GREENCARD' | 'VEROCARD' | 'COOPER' | 'NUTRICARD' | 'VR' | 'SODEXO' | 'OTHER', required: The payment network (aka card brand or card scheme) for this card. - `type` 'CREDIT' | 'DEBIT' | 'VOUCHER' | 'OTHER', required: The payment type of the card. - `externalPaymentType` string, nullable: External payment type string. Should be only used if not mapped by any value of paymentAuthorizer, and it's value is OTHER_TYPE. - `paymentRecords` PaymentRecord[], nullable: [WIP - in development, not supported yet] List of payment records, including method and card details and ids from payment processing entities. - `otterPaymentRecordId` string: The identifier for the payment record in the Otter system, for reference. - `recordProviderType` 'ALLINPAY' | 'CHECKOUT' | 'CSS' | 'MERCADO_PAGO' | 'OLIVENETWORKS' | 'SHOUQIANBA' | 'STRIPE' | 'UNIONPAY' | 'VAN_DAOU' | 'VAN_JTNET' | 'VAN_KICC' | 'VAN_KIS' | 'VAN_KOVAN' | 'VAN_KSNET' | 'VAN_NICE' | 'VAN_SMARTRO' | 'UNKNOWN': The type of payment provider. - `recordPaymentType` 'ACH_CREDIT' | 'ACH_DEBIT' | 'ACSS_DEBIT' | 'ALIPAY_MINIAPP' | 'ALI_PAY' | 'BACS_DEBIT' | 'BANK_TRANSFER' | 'BECS_DEBIT' | 'BOLETO' | 'CARD' | 'CARD_PRESENT' | 'CASH' | 'CHECK' | 'CHECKOUT_SESSION' | 'ETC' | 'EXTERNAL_CASH_BALANCE' | 'GIFT_CARD' | 'INTERNAL_CASH_BALANCE' | 'KAKAO_PAY' | 'LIABILITY_BALANCE' | 'LINKED_BANK_ACCOUNT' | 'NAVER_PAY' | 'PIX' | 'QRCODE' | 'QRCODE_ALIPAY' | 'QRCODE_WECHAT' | 'SEPA_DEBIT' | 'SPEI_BANK_TRANSFER' | 'WALLET' | 'WECHAT_PAY' | 'UNKNOWN': The type of payment method. - `paymentRecordId` string: The identifier for the payment record from the payment provider. - `payerId` string: The identifier for the payer from the payment provider. - `balanceTransactionId` string: The balance transaction ID from the payment provider. - `paymentDetails` union: One of the possible payment method details, depending on the payment method type. - PaymentDetailsCard: Details of a card payment method. - `brandType` 'UNKNOWN' | 'AMEX' | 'DINERS_CLUB' | 'DISCOVER' | 'JCB' | 'MASTERCARD' | 'UNION_PAY' | 'VISA' | 'GIROCARD' | 'EFTPOS_AU' | 'INTERAC': The brand of the card. - `expiration` object - `year` integer: The expiration year of the card. - `month` integer: The expiration month of the card. - `fundingType` 'UNKNOWN' | 'CREDIT' | 'DEBIT' | 'PREPAID': The funding type of the card. - `walletType` 'UNKNOWN' | 'APPLE_PAY' | 'GOOGLE_PAY': The type of wallet associated with the card. - `lastFour` string: The last four digits of the card. - `walletLastFour` string: The last four digits of the wallet account. - `authorizationCode` string: The authorization code for the card. - `applicationPreferredName` string: The preferred name of the application. - `fingerprint` string: The fingerprint of the card. - `readMethod` string: The method used to read the card. - PaymentDetailsBacs: Details of a BACS payment method in the UK. - `mandateStatus` 'ACTIVE' | 'INACTIVE' | 'PENDING': The status of the mandate. - `lastFour` string: The last four digits of the BACS account. - `sortCode` string: The sort code of the BACS account. - `mandateId` string: The mandate ID for the BACS account. - `reference` string: The reference for the BACS payment. - `url` string: The URL for the BACS payment details. - PaymentDetailsAcss: Details of an ACSS payment method in Canada. - `mandateStatus` 'ACTIVE' | 'INACTIVE' | 'PENDING': The status of the mandate. - `acceptedAt` string, date-time: The timestamp when the mandate was accepted. - `lastFour` string: The last four digits of the ACSS account. - `transitNumber` string: The transit number of the ACSS account. - `institutionNumber` string: The institution number of the ACSS account. - `bankName` string: The name of the bank. - `mandateId` string: The mandate ID for the ACSS account. - `transactionType` string: The type of transaction. - `intervalDescription` string: The description of the transaction interval. - PaymentDetailsBecs: Details of a BECS payment method in Australia. - `mandateStatus` 'ACTIVE' | 'INACTIVE' | 'PENDING': The status of the mandate. - `lastFour` string: The last four digits of the BECS account. - `bsbNumber` string: The BSB number of the BECS account. - `mandateId` string: The mandate ID for the BECS account. - `url` string: The URL for the BECS payment details. - PaymentDetailsSepa: Details of a SEPA payment method in EU countries. - `mandateStatus` 'ACTIVE' | 'INACTIVE' | 'PENDING': The status of the mandate. - `lastFour` string: The last four digits of the SEPA account. - `branchCode` string: The branch code of the SEPA account. - `bankCode` string: The bank code of the SEPA account. - `countryCode` string: The country code of the SEPA account. - `mandateId` string: The mandate ID for the SEPA account. - `reference` string: The reference for the SEPA payment. - `url` string: The URL for the SEPA payment details. - PaymentDetailsAch: Details of a debit ACH payment method in the US. - `accountHolderType` 'INDIVIDUAL' | 'COMPANY': The type of account holder. - `accountType` 'CHECKING' | 'SAVINGS': The type of ACH account. - `mandateStatus` 'ACTIVE' | 'INACTIVE' | 'PENDING': The status of the mandate. - `lastFour` string: The last four digits of the ACH account. - `routingNumber` string: The routing number of the ACH account. - `bankName` string: The name of the bank. - `mandateId` string: The mandate ID for the ACH account. - `loyaltyInfo` LoyaltyInfo, nullable: The customer's loyalty information. - `hasMembershipPass` boolean: Indicates if the customer has a membership pass. - `fulfillmentInfo` FulfillmentInfo, nullable: Information on order fulfillment. - `pickupTime` string, date-time, nullable: Time (in UTC) specified by the provider when the courier or customer is expected to pick up the order. - `estimatedPickupTime` string, date-time, nullable: Time (in UTC) estimated by the platform when the courier or customer is likely to pick up the order. This estimation takes into account preparation time, order readiness, and other logistical factors. - `deliveryTime` string, date-time, nullable: Estimated time (in UTC) when the order is expected to be delivered. This should be filled in if FulfillmentMode is delivery. - `fulfillmentMode` 'DELIVERY' | 'RESTAURANT_DELIVERY' | 'PICKUP' | 'DINE_IN' | 'DRIVE_THROUGH': How the order is expected to be fulfilled: - `DELIVERY` — delivered by a courier provided by the order source (the ordering marketplace). - `RESTAURANT_DELIVERY` — delivered by the store's own courier. - `PICKUP` — collected by the customer at the store. - `DINE_IN` — eaten at the store. - `DRIVE_THROUGH` — collected by the customer at a drive-through. - `schedulingType` 'ASAP' | 'FIXED_TIME', nullable: Describes whether this order should be cooked as soon as possible, or some time in the future. Please use the pickupTime and/or deliveryTime to indicate when. If no scheduling type is provided, we assume the order should be prepared as soon as possible. - `courierStatus` 'COURIER_ASSIGNED' | 'COURIER_ON_ROUTE_TO_PICKUP' | 'COURIER_ARRIVED' | 'COURIER_PICKED_UP_FOOD' | 'COURIER_COMPLETED', nullable: The current status of the courier, progressing in order: - `COURIER_ASSIGNED` — a courier has been assigned to the order. - `COURIER_ON_ROUTE_TO_PICKUP` — the courier is heading to the store. - `COURIER_ARRIVED` — the courier has arrived at / checked in to the store. - `COURIER_PICKED_UP_FOOD` — the courier has the food and is heading to the customer. - `COURIER_COMPLETED` — the courier has dropped off the order. - `tableIdentifier` string, nullable: The table identification for dine-in orders. - `promotionsDetails` PromotionDetails[], nullable: [WIP - in development, not supported yet] Details about the promotions applied to this order. The sum of these values should equal the sum of the order's discounts. - `externalId` string: External promotion identifier. - `name` string: Promotion name. - `value` number: Promotion value. - `preparationTime` PreparationTime, nullable: Preparation time information for an order. - `estimatedPreparationTime` string: Preparation time estimated by the order provider. Use the Standard ISO 8601 Duration format (E.g. PT1H30M for 1 hour, 30 minutes). - `cutleryRequest` 'CUTLERY_REQUESTED' | 'CUTLERY_NOT_NEEDED', nullable: The customer's cutlery (utensils) preference. Only present when the ordering marketplace offers the customer this choice and reported it to Otter. **An absent or `null` value means no preference was reported and must not be treated as a request for cutlery** — some marketplaces and first-party channels never report it. ## Response `200` The order was successfully updated. - OrderReference: An order reference. - `externalIdentifiers` OrderExternalIdentifiers, required: The external identifiers. - `id` string, required: Unique ID for the order that was placed. - `friendlyId` string, required: ID used for driver pickup and restaurant management. - `source` string, nullable: Describes the source of the order, typically from a food ordering marketplace. - `sourceType` 'POINT_OF_SALE' | 'ORDERING_MARKETPLACE' | 'AGGREGATOR' | 'CUSTOMER_INTERACTION', nullable: source type of the order - `sourceExternalIdentifiers` SourceExternalIdentifiers, nullable: The external identifiers. - `id` string: Unique ID for the order that was placed. - `friendlyId` string: ID used for driver pickup and restaurant management. - `source` string: Describes the source of the order, typically from a food ordering marketplace. - `sourceType` 'POINT_OF_SALE' | 'ORDERING_MARKETPLACE' | 'AGGREGATOR' | 'CUSTOMER_INTERACTION': source type of the order - `sourceExternalIdentifiers` SourceExternalIdentifiers (recursive) - `storeId` string, required: The identifier of the store. ## Other responses - `400`: The request is malformed. - `401`: Invalid authorization. - `403`: Authorization not valid for the requested resource. - `404`: Resource not found. - `422`: The request body is not valid. --- [API](https://skmtc.dev/cloudkitchens/apis/otter-api.md) - [All operations](https://skmtc.dev/cloudkitchens/apis/otter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudkitchens/apis/otter-api/revisions/4c868194a467?raw)