openapi: 3.2.0 info: title: Otter Manager Orders Webhooks API version: v1 contact: name: Kin Lane email: kin@apievangelist.com license: name: Proprietary x-generated-from: documentation x-last-validated: '2026-06-03' x-source-url: https://developer-guides.tryotter.com/api-reference/ description: 'Operations tagged Manager Orders Webhooks across 19 of this provider''s published API definitions: otter-account-pairing-endpoints-api-openapi.yml, otter-auth-endpoints-api-openapi.yml, otter-callback-endpoints-api-openapi.yml, otter-delivery-endpoints-api-openapi.yml, otter-direct-orders-endpoints-api-openapi.yml, otter-finance-endpoints-api-openapi.yml, otter-inventory-endpoints-api-openapi.yml, otter-manager-loyalty-endpoints-api-openapi.yml, otter-manager-menu-endpoints-api-openapi.yml, otter-manager-order-endpoints-api-openapi.yml, otter-manager-storefront-endpoints-api-openapi.yml, otter-market-intel-endpoints-api-openapi.yml, otter-menus-endpoints-api-openapi.yml, otter-orders-endpoints-api-openapi.yml, otter-organization-endpoints-api-openapi.yml, otter-ping-endpoints-api-openapi.yml, otter-reports-endpoints-api-openapi.yml, otter-reviews-endpoints-api-openapi.yml, otter-storefront-endpoints-api-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://{public-api-url}/ description: Otter Public API base URL. The concrete host is provisioned per integration partner/account via your Otter account representative; substitute the value provided during onboarding. variables: public-api-url: default: public-api-url description: Account-specific Public API host provided by Otter during onboarding. tags: - name: Manager Orders Webhooks paths: {} webhooks: orderCreate: post: tags: - Manager Orders Webhooks summary: Otter Order Creation Webhook operationId: orderCreateWebhook requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/EventNotification' - type: object properties: metadata: type: object properties: payload: $ref: '#/components/schemas/Order' - example: eventType: orders.new_order examples: OrderCreateWebhookRequestExample: summary: Default orderCreateWebhook request x-microcks-default: true value: eventId: c75d9460-5d48-423d-8d01-f825fd5b1672 eventTime: '2007-12-03T10:15:30+01:00' eventType: orders.new_order metadata: payload: externalIdentifiers: {} currencyCode: EUR status: NEW_ORDER items: - {} orderedAt: '2007-12-03T10:15:30+01:00' customer: {} customerNote: Please include extra napkins! deliveryInfo: {} orderTotal: {} orderTotalV2: {} customerPayments: - {} fulfillmentInfo: {} promotionsDetails: - {} preparationTime: {} responses: '200': $ref: '#/components/responses/200' '202': $ref: '#/components/responses/202' x-microcks-operation: delay: 0 dispatcher: FALLBACK servers: - url: https://{public-api-url}/ description: Otter Public API base URL. The concrete host is provisioned per integration partner/account via your Otter account representative; substitute the value provided during onboarding. variables: public-api-url: default: public-api-url description: Account-specific Public API host provided by Otter during onboarding. orderUpdate: post: tags: - Manager Orders Webhooks summary: Otter Order Update Webhook operationId: orderUpdateWebhook requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/EventNotification' - type: object properties: metadata: type: object properties: payload: $ref: '#/components/schemas/Order' - example: eventType: orders.update examples: OrderUpdateWebhookRequestExample: summary: Default orderUpdateWebhook request x-microcks-default: true value: eventId: c75d9460-5d48-423d-8d01-f825fd5b1672 eventTime: '2007-12-03T10:15:30+01:00' eventType: orders.update metadata: payload: externalIdentifiers: {} currencyCode: EUR status: NEW_ORDER items: - {} orderedAt: '2007-12-03T10:15:30+01:00' customer: {} customerNote: Please include extra napkins! deliveryInfo: {} orderTotal: {} orderTotalV2: {} customerPayments: - {} fulfillmentInfo: {} promotionsDetails: - {} preparationTime: {} responses: '200': $ref: '#/components/responses/200' '202': $ref: '#/components/responses/202' x-microcks-operation: delay: 0 dispatcher: FALLBACK servers: - url: https://{public-api-url}/ description: Otter Public API base URL. The concrete host is provisioned per integration partner/account via your Otter account representative; substitute the value provided during onboarding. variables: public-api-url: default: public-api-url description: Account-specific Public API host provided by Otter during onboarding. orderConfirm: post: tags: - Manager Orders Webhooks summary: Otter Order Confirm Notification Webhook operationId: orderConfirmWebhook requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/EventNotification' - type: object properties: metadata: type: object properties: payload: $ref: '#/components/schemas/OrderConfirmEvent' - example: eventType: orders.confirm examples: OrderConfirmWebhookRequestExample: summary: Default orderConfirmWebhook request x-microcks-default: true value: eventId: c75d9460-5d48-423d-8d01-f825fd5b1672 eventTime: '2007-12-03T10:15:30+01:00' eventType: orders.confirm metadata: payload: orderId: 69f60a06-c335-46d9-b5a1-97f1a211c514 responses: 2XX: $ref: '#/components/responses/2XX' x-microcks-operation: delay: 0 dispatcher: FALLBACK servers: - url: https://{public-api-url}/ description: Otter Public API base URL. The concrete host is provisioned per integration partner/account via your Otter account representative; substitute the value provided during onboarding. variables: public-api-url: default: public-api-url description: Account-specific Public API host provided by Otter during onboarding. orderReady: post: tags: - Manager Orders Webhooks summary: Otter Order Ready Status Notification Webhook operationId: orderReady requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/EventNotification' - type: object properties: metadata: type: object properties: payload: $ref: '#/components/schemas/OrderReadyEvent' - example: eventType: orders.order_ready examples: OrderReadyRequestExample: summary: Default orderReady request x-microcks-default: true value: eventId: c75d9460-5d48-423d-8d01-f825fd5b1672 eventTime: '2007-12-03T10:15:30+01:00' eventType: orders.order_ready metadata: payload: orderId: 69f60a06-c335-46d9-b5a1-97f1a211c514 responses: 2XX: $ref: '#/components/responses/2XX' x-microcks-operation: delay: 0 dispatcher: FALLBACK servers: - url: https://{public-api-url}/ description: Otter Public API base URL. The concrete host is provisioned per integration partner/account via your Otter account representative; substitute the value provided during onboarding. variables: public-api-url: default: public-api-url description: Account-specific Public API host provided by Otter during onboarding. orderHandedOff: post: tags: - Manager Orders Webhooks summary: Otter Order Handed Off Status Notification Webhook operationId: orderHandedOff requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/EventNotification' - type: object properties: metadata: type: object properties: payload: $ref: '#/components/schemas/OrderHandedOffEvent' - example: eventType: orders.order_handed_off examples: OrderHandedOffRequestExample: summary: Default orderHandedOff request x-microcks-default: true value: eventId: c75d9460-5d48-423d-8d01-f825fd5b1672 eventTime: '2007-12-03T10:15:30+01:00' eventType: orders.order_handed_off metadata: payload: orderId: 69f60a06-c335-46d9-b5a1-97f1a211c514 courierPhone: 415-234-3212 courierBodyTempFahrenheit: 36.6 isCourierWearingMask: true responses: 2XX: $ref: '#/components/responses/2XX' x-microcks-operation: delay: 0 dispatcher: FALLBACK servers: - url: https://{public-api-url}/ description: Otter Public API base URL. The concrete host is provisioned per integration partner/account via your Otter account representative; substitute the value provided during onboarding. variables: public-api-url: default: public-api-url description: Account-specific Public API host provided by Otter during onboarding. orderFulfilled: post: tags: - Manager Orders Webhooks summary: Otter Order Fulfilled Status Notification Webhook operationId: orderFulfilled requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/EventNotification' - type: object properties: metadata: type: object properties: payload: $ref: '#/components/schemas/OrderFulfilledEvent' - example: eventType: orders.order_fulfilled examples: OrderFulfilledRequestExample: summary: Default orderFulfilled request x-microcks-default: true value: eventId: c75d9460-5d48-423d-8d01-f825fd5b1672 eventTime: '2007-12-03T10:15:30+01:00' eventType: orders.order_fulfilled metadata: payload: orderId: 69f60a06-c335-46d9-b5a1-97f1a211c514 responses: 2XX: $ref: '#/components/responses/2XX' x-microcks-operation: delay: 0 dispatcher: FALLBACK servers: - url: https://{public-api-url}/ description: Otter Public API base URL. The concrete host is provisioned per integration partner/account via your Otter account representative; substitute the value provided during onboarding. variables: public-api-url: default: public-api-url description: Account-specific Public API host provided by Otter during onboarding. components: schemas: PreparationTime: type: - object - 'null' description: Preparation time information for an order. properties: estimatedPreparationTime: type: string description: Preparation time estimated by the order provider. Use the Standard ISO 8601 Duration format (E.g. PT1H30M for 1 hour, 30 minutes). example: PT30M SignatureRequirement: type: - object - 'null' properties: enabled: type: boolean description: Marks the signature requirement as required. example: true collectSignerName: type: boolean description: Whether the signer's name should be collected. example: true collectSignerRelationship: type: boolean description: Whether the signer's relationship with the intended recipient should be collected. example: true description: Enables and configure the signature requirement. PaymentDetailsBecs: type: object description: Details of a BECS payment method in Australia. properties: mandateStatus: $ref: '#/components/schemas/MandateStatus' lastFour: type: string description: The last four digits of the BECS account. example: '3210' bsbNumber: type: string description: The BSB number of the BECS account. example: 062-001 mandateId: type: string description: The mandate ID for the BECS account. example: becs_mandate_789 url: type: string description: The URL for the BECS payment details. example: http://example.com/becs RecordProviderType: type: string enum: - 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 example: STRIPE description: The type of payment provider. SourceExternalIdentifiers: type: - object - 'null' properties: id: type: string description: Unique ID for the order that was placed. example: 69f60a06-c335-46d9-b5a1-97f1a211c514 friendlyId: type: string description: ID used for driver pickup and restaurant management. example: ABCDE source: type: string description: Describes the source of the order, typically from a food ordering marketplace. example: ubereats sourceType: type: string description: source type of the order enum: - POINT_OF_SALE - ORDERING_MARKETPLACE - AGGREGATOR - CUSTOMER_INTERACTION example: POINT_OF_SALE sourceExternalIdentifiers: $ref: '#/components/schemas/SourceExternalIdentifiers' description: The external identifiers. Address: type: - object - 'null' properties: fullAddress: type: - string - 'null' description: Full, human comprehensible address. It is usually formatted in the order appropriate for your locale. example: 123 Sample Street Ste 100, San Francisco, CA 94103 postalCode: type: string description: Postal code of the address. example: '20500' city: type: string description: The city/town portion of the address. example: Washington state: type: string description: 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. example: DC countryCode: type: string description: CLDR country code. See http://cldr.unicode.org/ example: US addressLines: type: - array - 'null' description: Address lines (e.g. street, PO Box, or company name) or the full single line address (e.g. street, city, state, country, zip). example: - 1600 Pennsylvania Avenue NW - 123 Sample Street Ste 100, San Francisco, CA 94103 items: type: string linesOfAddress: type: - array - 'null' deprecated: true description: '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).' example: - 1600 Pennsylvania Avenue NW - 123 Sample Street Ste 100, San Francisco, CA 94103 items: type: string location: $ref: '#/components/schemas/Location' description: Order delivery address. PaymentDetailsSepa: type: object description: Details of a SEPA payment method in EU countries. properties: mandateStatus: $ref: '#/components/schemas/MandateStatus' lastFour: type: string description: The last four digits of the SEPA account. example: '4321' branchCode: type: string description: The branch code of the SEPA account. example: branch_001 bankCode: type: string description: The bank code of the SEPA account. example: bank_001 countryCode: type: string description: The country code of the SEPA account. example: DE mandateId: type: string description: The mandate ID for the SEPA account. example: sepa_mandate_012 reference: type: string description: The reference for the SEPA payment. example: reference_xyz url: type: string description: The URL for the SEPA payment details. example: http://example.com/sepa FulfillmentInfo: type: - object - 'null' properties: pickupTime: type: - string - 'null' description: Time (in UTC) specified by the provider when the courier or customer is expected to pick up the order. format: date-time example: '2007-12-03T10:15:30+01:00' estimatedPickupTime: type: - string - 'null' description: 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. format: date-time example: '2007-12-03T10:15:30+01:00' deliveryTime: type: - string - 'null' description: Estimated time (in UTC) when the order is expected to be delivered. This should be filled in if FulfillmentMode is delivery. format: date-time example: '2007-12-03T10:15:30+01:00' fulfillmentMode: type: string description: How an order is expected to be fulfilled. default: DELIVERY enum: - DELIVERY - RESTAURANT_DELIVERY - PICKUP - DINE_IN - DRIVE_THROUGH example: DELIVERY schedulingType: type: - string - 'null' description: 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. enum: - ASAP - FIXED_TIME example: ASAP courierStatus: type: - string - 'null' description: The status of the courier. enum: - COURIER_ASSIGNED - COURIER_ON_ROUTE_TO_PICKUP - COURIER_ARRIVED - COURIER_PICKED_UP_FOOD - COURIER_COMPLETED example: COURIER_ASSIGNED tableIdentifier: type: - string - 'null' description: The table identification for dine-in orders. example: R-45 description: Information on order fulfillment. Person: type: - object - 'null' properties: name: type: - string - 'null' description: The person's name as it should be displayed. example: Jane Doe maxLength: 255 phone: type: - string - 'null' description: The person's phone number. example: +1-555-555-5555 maxLength: 25 phoneCode: type: - string - 'null' description: A code or extension of the phone number. example: 111 11 111 maxLength: 25 email: type: - string - 'null' description: The person's email address. example: email@email.com personalIdentifiers: $ref: '#/components/schemas/PersonalIdentifiers' description: The recipient information. CustomerPayment: required: - paymentMethod - processingStatus - value type: object properties: value: type: number description: The portion of the overall amount that needs to be paid. example: 2 processingStatus: type: string description: The processing status of the payment. (PROCESSED is only valid when the payment method is CARD) enum: - COLLECTABLE - PROCESSED example: COLLECTABLE paymentMethod: type: string description: The method of payment. enum: - CASH - CARD - UNKNOWN - OTHER - CHEQUE - GIFT_CARD example: CASH paymentAuthorizer: type: - string - 'null' description: A payment system type responsible for a card transaction (containing information for payment network and payment type). enum: - UNKNOWN_TYPE - OTHER_TYPE - MASTERCARD - MASTERCARD_MAESTRO - MASTERCARD_DEBIT - VISA - VISA_DEBIT - AMEX - VISA_ELECTORN - DINERS - ELO - ELO_DEBIT - HIPERCARD - BANRICOMPRAS - BANRICOMPRAS_DEBIT - NUGO - GOODCARD - VERDECARD - CARNET - CHEF_CARD - GER_CC_CREDITO - TERMINAL_BANCARIA - DEBIT - QR_CODE - RAPPI_PAY - DISCOVER - VALE_GREEN_CARD_PAPEL - VALE_GREEN_CARD_CARD - VALE_REFEISUL - VALE_VEROCARD - VALE_VR_SMART - VALE_SODEXO - VALE_TICKET_RESTAURANTE - VALE_ALELO - VALE_BEN_VIS - VALE_COOPER_CARD - NUTRICARD_REFEICAO_E_ALIMENTACAO - APPLE_PAY_MASTERCARD - APPLE_PAY_VISA - APPLE_PAY_AMEX - GOOGLE_PAY_ELO - GOOGLE_PAY_MASTERCARD - GOOGLE_PAY_VISA - MOVILE_PAY - MOVILE_PAY_AMEX - MOVILE_PAY_DINERS - MOVILE_PAY_ELO - MOVILE_PAY_HIPERCARD - MOVILE_PAY_MASTERCARD - MOVILE_PAY_VISA - IFOOD_CORP - LOOP_CLUB - PAYPAL - PSE - PIX example: UNKNOWN_TYPE cardInfo: deprecated: true $ref: '#/components/schemas/CardInfo' externalPaymentType: type: - string - 'null' description: External payment type string. Should be only used if not mapped by any value of paymentAuthorizer, and it's value is OTHER_TYPE. example: string paymentRecords: type: - array - 'null' description: '[WIP - in development, not supported yet] List of payment records, including method and card details and ids from payment processing entities.' items: $ref: '#/components/schemas/PaymentRecord' loyaltyInfo: $ref: '#/components/schemas/LoyaltyInfo' PersonalIdentifiers: type: - object - 'null' properties: taxIdentificationNumber: type: - string - 'null' description: Person tax identification number. example: 1234567890 serviceProviderId: type: - string - 'null' description: External service provider ID i.e. Courier Id. example: 12345ba6-789e-123f-4e56-d78db90d123b description: The person's personal identifiers (e.g. tax identification number). VerificationRequirements: type: - object - 'null' properties: signatureRequirement: $ref: '#/components/schemas/SignatureRequirement' pictureRequirement: $ref: '#/components/schemas/PictureRequirement' description: Verification requirements for the delivery. MandateStatus: type: string enum: - ACTIVE - INACTIVE - PENDING description: The status of the mandate. example: ACTIVE CompositeFinanceLine: required: - breakdown type: object properties: breakdown: type: array minItems: 1 description: Breakdown values for the finance line. items: $ref: '#/components/schemas/SimpleFinanceLine' description: composite finance line can represent a value, tax and VAT for a given line as a list of SimpleFinanceLine objects SimpleFinanceLine: required: - subType - name - value type: object properties: subType: type: string enum: - VALUE - TAX - VALUE_WITH_TAX - VAT description: type of the finance line. example: VALUE name: type: string description: name of the finance line. example: sales tax. value: type: number description: money amount. example: 3.4 description: simple finance line. CardInfo: required: - paymentNetwork - type type: - object - 'null' deprecated: true description: Additional card information. properties: paymentNetwork: type: string description: The payment network (aka card brand or card scheme) for this card. enum: - MASTERCARD - MASTERCARD_MAESTRO - VISA - AMEX - DINERS - ELO - HIPERCARD - BANRICOMPRAS - NUGO - GOODCARD - ELO_MAIS - GREENCARD - VEROCARD - COOPER - NUTRICARD - VR - SODEXO - OTHER example: MASTERCARD type: type: string description: The payment type of the card. enum: - CREDIT - DEBIT - VOUCHER - OTHER example: CREDIT Courier: type: - object - 'null' properties: name: type: - string - 'null' description: The person's name as it should be displayed. example: Jane Doe phone: type: - string - 'null' description: The person's phone number. example: +1-555-555-5555 phoneCode: type: - string - 'null' description: A code or extension of the phone number. example: 111 11 111 email: type: - string - 'null' description: The person's email address. example: email@email.com personalIdentifiers: $ref: '#/components/schemas/PersonalIdentifiers' description: Details about the delivery courier. PictureRequirement: type: - object - 'null' properties: enabled: type: boolean description: Marks the picture requirement as required. example: true description: Enables and configure the picture requirement. PaymentDetailsBacs: type: object description: Details of a BACS payment method in the UK. properties: mandateStatus: $ref: '#/components/schemas/MandateStatus' lastFour: type: string description: The last four digits of the BACS account. example: '9876' sortCode: type: string description: The sort code of the BACS account. example: 12-34-56 mandateId: type: string description: The mandate ID for the BACS account. example: mandate_123 reference: type: string description: The reference for the BACS payment. example: reference_abc url: type: string description: The URL for the BACS payment details. example: http://example.com/bacs CustomerPaymentV2: type: - object - 'null' properties: customerPaymentDue: type: - number - 'null' description: 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. example: 1 customerPrepayment: type: - number - 'null' description: 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. example: 1 customerAmountToReturn: type: - number - 'null' description: "Change (cash back) to be returned to the customer by the courier or store when the order has payment due value.\n\n Scenario:\n 1. Customer places an order for $7.50.\n 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.\n 3. When the order is delivered, the courier should have $12.50 in cash on hand to complete the transaction.\n" example: 1 paymentDueToRestaurant: type: - number - 'null' description: 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. example: 1 description: Details about customer payment. FinancialData: required: - foodSales type: object properties: foodSales: description: Breakdown of the total value of items within the order. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' feeForRestaurantProvidedDelivery: description: Extra charge to the customer when order is delivered by the store itself. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' restaurantFundedDiscount: description: Discount funded by the restaurant. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' voucherDiscount: description: Discount provided by voucher. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' promotionDiscount: description: Discount provided by item promotion. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' operatorDiscount: description: Discount provided by operator when the order was placed. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' loyaltyDiscount: description: Discount provided by loyalty programs. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' tipForRestaurant: description: Tip for the restaurant. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' adjustments: description: Any adjustments that may happen to the order total value. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' packingFee: description: Fee charged to the customer for the process of packing and fulfilling the order. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' bagFee: description: Fee charged to the customer for providing bags for the order. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' serviceProviderDiscount: description: Discount funded by the service provider (order source). allOf: - $ref: '#/components/schemas/CompositeFinanceLine' tipForServiceProviderCourier: description: Tip for the courier from the service provider. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' feeForServiceProviderDelivery: description: Fee charged to the customer for a delivery provided by the service provider. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' smallOrderFee: description: Fee charged to the customer when the order value is less than the minimum value. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' serviceFee: description: Any service fees charged by the service provider to the customer. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' otherFee: description: All the extra costs that the customer has to pay, are different from tips, delivery fees, bag fees, packing fees, and service fees. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' netPayout: description: The net payout received by the store. allOf: - $ref: '#/components/schemas/CompositeFinanceLine' couponCodes: type: - array - 'null' items: type: string description: Any codes entered by the customer at order checkout. example: - TACOWED5OFF description: "Breakdown of order values. Represents total values, fees, discounts, and any possible adjustments that may happen in the order value.\n\nBreakdown 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.\n\nAll objects in breakdown lists have a required property \"subType\". Allowed values are:\n\n**VALUE**: represent the net value of the order/item/fee. Should be used in the following cases:\n - when the amount does not contain taxes or VAT\n - when tax/VAT is a known value, in that case, the list must contain an object with subtype TAX or VAT representing this value.\n\n**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:\n\n\n ```\n \"breakdown\": [\n {\n \"name\": \"Item 1\",\n \"value\": 10,\n \"subType\": \"VALUE\"\n },\n {\n \"name\": \"Item 1 - Tax\",\n \"value\": 2,\n \"subType\": \"TAX\"\n }\n ]\n ```\n\n\n**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:\n\n\n ```\n \"breakdown\": [\n {\n \"name\": \"Item 1\",\n \"value\": 12,\n \"subType\": \"VALUE\"\n },\n {\n \"name\": \"Item 1 - Tax\",\n \"value\": 2,\n \"subType\": \"VAT\"\n }\n ]\n ```\n\n\n**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.\n\n\n ```\n \"breakdown\": [\n {\n \"name\": \"Item 1\",\n \"value\": 12,\n \"subType\": \"VALUE_WITH_TAX\"\n }\n ]\n ```" CardBrandType: type: string enum: - UNKNOWN - AMEX - DINERS_CLUB - DISCOVER - JCB - MASTERCARD - UNION_PAY - VISA - GIROCARD - EFTPOS_AU - INTERAC description: The brand of the card. example: VISA LoyaltyInfo: type: - object - 'null' description: The customer's loyalty information. properties: hasMembershipPass: type: boolean description: Indicates if the customer has a membership pass. example: true OrderTotalV2: required: - customerTotal type: - object - 'null' properties: customerTotal: allOf: - $ref: '#/components/schemas/FinancialData' customerPayment: description: The customer perspective, each price field in this model is meant to represent the values the customer paid/received and how. Values must match amounts and payment methods described in customerPayments. allOf: - $ref: '#/components/schemas/CustomerPaymentV2' payout: description: Breakdown of net payout received by the store. Optional object, should be provided when payout information is available during the order lifecycle. allOf: - $ref: '#/components/schemas/Payout' description: V2 for details about values of the order, provides richer objects allowing to capture taxes, misc charges, payments more precisely. AccountHolderType: type: string enum: - INDIVIDUAL - COMPANY description: The type of account holder. example: INDIVIDUAL Item: required: - quantity type: object properties: quantity: minimum: 1 maximum: 1000 type: integer description: The quantity of the item ordered by the customer. format: int32 example: 1 skuPrice: type: - number - 'null' description: The stored sku price of this item readOnly: true example: 5.9 id: type: - string - 'null' description: The unique ID of the item. example: 33e0418f-3d56-4360-ba03-18fc5f8844a3 lineItemId: type: - string - 'null' description: 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. readOnly: true example: 2f91f9f3-2d7e-4898-ae81-00fe06ed7dbf skuId: type: - string - 'null' description: sku ID of the item. example: 867b8fdc-cf7b-4fc3-b7e0-4c7b68d8b1cc name: type: - string - 'null' description: The name of the item as displayed to the customer. example: Juicy Cheeseburger note: type: - string - 'null' description: An optional item-level note provided by the customer. example: Please cook to well done! categoryId: deprecated: true type: - string - 'null' description: The unique ID of the category of this item. example: 303de078-870d-4349-928b-946869d4d69b internalCategoryId: type: - string - 'null' description: Otter's internal identifier for the item's category example: 76a66bba-48fb-4bac-80ee-2616a5ca1ab9 categoryName: deprecated: true type: - string - 'null' description: The name of the category of this item. example: Burgers internalCategoryName: type: - string - 'null' description: Otter's internal name for the item's category example: Burgers stationId: type: - string - 'null' description: The ID of the station the item is assigned to. readOnly: true example: 5247b8a1-77de-4844-b024-cb59fcec59bd price: type: - number - 'null' description: The price of the sold item. example: 5.9 modifiers: type: - array - 'null' description: Modifiers to the base item. maxItems: 100 items: $ref: '#/components/schemas/ItemModifier' PromotionDetails: type: - object - 'null' description: Order promotion details. properties: externalId: type: string description: External promotion identifier. example: store_123 name: type: string description: Promotion name. example: 20% off, up to $5 value: type: number description: Promotion value. example: 2 Location: required: - latitude - longitude type: - object - 'null' properties: latitude: type: number description: The latitude of the location. format: double example: 38.8977 longitude: type: number description: The longitude of the location. format: double example: 77.0365 description: Latitude and longitude of the address. Payout: type: - object - 'null' properties: payoutFromServiceProvider: type: - number - 'null' description: Payout amount that will be received from service provider (usually the order source). example: 1 payoutFrom3rdParty: type: - number - 'null' description: Payout amount that will be received from any 3rd party organization involved. example: 1 cashPayout: type: - number - 'null' description: Payout amount received from orders paid in cash directly to the store. example: 1 description: Details on payout. OrderTotal: required: - subtotal type: object properties: subtotal: type: number description: The order's subtotal, as the sum of all item and modifier prices. example: 11.97 claimedSubtotal: type: - number - 'null' description: The order's claimed subtotal, without guaranteeing this will match calculated subtotal. example: 1.0 discount: type: - number - 'null' description: Any discount amount for the order. example: 1 tax: type: - number - 'null' description: Tax paid by the customer. example: 1.1 tip: type: - number - 'null' description: Tip paid by the customer. example: 2 deliveryFee: type: - number - 'null' description: Delivery fee. example: 5 total: type: - number - 'null' description: Order total including everything paid by the customer. example: 19.07 couponCode: type: - string - 'null' description: Coupon code applied to the order. example: VWXYZ98765 description: Details about values of the order. RecordPaymentType: type: string enum: - 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 example: CARD description: The type of payment method. PaymentDetailsAch: type: object description: Details of a debit ACH payment method in the US. properties: accountHolderType: $ref: '#/components/schemas/AccountHolderType' accountType: $ref: '#/components/schemas/AccountType' mandateStatus: $ref: '#/components/schemas/MandateStatus' lastFour: type: string description: The last four digits of the ACH account. example: '7890' routingNumber: type: string description: The routing number of the ACH account. example: '123456789' bankName: type: string description: The name of the bank. example: Example Bank mandateId: type: string description: The mandate ID for the ACH account. example: ach_mandate_345 PaymentDetailsAcss: type: object description: Details of an ACSS payment method in Canada. properties: mandateStatus: $ref: '#/components/schemas/MandateStatus' acceptedAt: type: string format: date-time description: The timestamp when the mandate was accepted. example: '2023-01-01T12:00:00Z' lastFour: type: string description: The last four digits of the ACSS account. example: '6543' transitNumber: type: string description: The transit number of the ACSS account. example: '11001' institutionNumber: type: string description: The institution number of the ACSS account. example: '001' bankName: type: string description: The name of the bank. example: Bank of Examples mandateId: type: string description: The mandate ID for the ACSS account. example: acss_mandate_456 transactionType: type: string description: The type of transaction. example: recurring intervalDescription: type: string description: The description of the transaction interval. example: monthly DeliveryInfo: type: - object - 'null' properties: courier: $ref: '#/components/schemas/Courier' destination: $ref: '#/components/schemas/Address' licensePlate: type: - string - 'null' description: License plate of a vehicle used by the courier. example: ABC 123 makeModel: type: - string - 'null' description: Make and model of a vehicle used by the courier. example: Honda CR-V lastKnownLocation: $ref: '#/components/schemas/Location' dropoffInstructions: $ref: '#/components/schemas/DropoffInstructions' note: type: - string - 'null' description: Special delivery instructions, if any. example: Gate code 123 description: Information on order's delivery process. PaymentRecord: type: object description: Represents the details and metadata of a payment method used in transactions. properties: otterPaymentRecordId: type: string description: The identifier for the payment record in the Otter system, for reference. example: otter_123456789 recordProviderType: description: The type of payment provider. $ref: '#/components/schemas/RecordProviderType' recordPaymentType: description: The type of payment method. $ref: '#/components/schemas/RecordPaymentType' paymentRecordId: type: string description: The identifier for the payment record from the payment provider. example: pm_123456789 payerId: type: string description: The identifier for the payer from the payment provider. example: payer_123456789 balanceTransactionId: type: string description: The balance transaction ID from the payment provider. example: ext_bt_123456789 paymentDetails: description: One of the possible payment method details, depending on the payment method type. oneOf: - $ref: '#/components/schemas/PaymentDetailsCard' - $ref: '#/components/schemas/PaymentDetailsBacs' - $ref: '#/components/schemas/PaymentDetailsAcss' - $ref: '#/components/schemas/PaymentDetailsBecs' - $ref: '#/components/schemas/PaymentDetailsSepa' - $ref: '#/components/schemas/PaymentDetailsAch' AccountType: type: string enum: - CHECKING - SAVINGS description: The type of ACH account. example: CHECKING CardWalletType: type: string enum: - UNKNOWN - APPLE_PAY - GOOGLE_PAY description: The type of wallet associated with the card. example: APPLE_PAY Order: required: - currencyCode - externalIdentifiers - status type: object properties: externalIdentifiers: $ref: '#/components/schemas/OrderExternalIdentifiers' currencyCode: maxLength: 3 minLength: 3 type: string description: The 3-letter currency code (ISO 4217) to use for all monetary values in this order. example: EUR status: type: string description: The status of the order. enum: - NEW_ORDER - CONFIRMED - PICKED_UP - CANCELED - FULFILLED - PREPARED - REJECTED - UNKNOWN example: NEW_ORDER items: type: array description: Items ordered. maxItems: 100 items: $ref: '#/components/schemas/Item' orderedAt: type: - string - 'null' description: The date (in UTC) when the order was placed by the customer. format: date-time example: '2007-12-03T10:15:30+01:00' customer: $ref: '#/components/schemas/Person' customerNote: type: - string - 'null' description: An order-level note provided by the customer. example: Please include extra napkins! deliveryInfo: $ref: '#/components/schemas/DeliveryInfo' orderTotal: $ref: '#/components/schemas/OrderTotal' orderTotalV2: $ref: '#/components/schemas/OrderTotalV2' customerPayments: type: - array - 'null' description: Details about the payments made by the customer. items: $ref: '#/components/schemas/CustomerPayment' fulfillmentInfo: $ref: '#/components/schemas/FulfillmentInfo' promotionsDetails: type: - array - 'null' description: '[WIP - in development, not supported yet] Details about the promotions applied to this order. The sum of values should be equal to the sum of order total discounts."' items: $ref: '#/components/schemas/PromotionDetails' preparationTime: $ref: '#/components/schemas/PreparationTime' description: An order placed by a customer. OrderExternalIdentifiers: required: - friendlyId - id type: object properties: id: type: string description: Unique ID for the order that was placed. example: 69f60a06-c335-46d9-b5a1-97f1a211c514 friendlyId: type: string description: ID used for driver pickup and restaurant management. example: ABCDE source: type: - string - 'null' description: Describes the source of the order, typically from a food ordering marketplace. example: ubereats sourceType: type: - string - 'null' description: source type of the order enum: - POINT_OF_SALE - ORDERING_MARKETPLACE - AGGREGATOR - CUSTOMER_INTERACTION example: POINT_OF_SALE sourceExternalIdentifiers: $ref: '#/components/schemas/SourceExternalIdentifiers' description: The external identifiers. CardFundingType: type: string enum: - UNKNOWN - CREDIT - DEBIT - PREPAID description: The funding type of the card. example: CREDIT ItemModifier: required: - quantity type: object properties: quantity: minimum: 1 maximum: 1000 type: integer description: The number of times the modifier was applied to the given item. format: int32 example: 1 skuPrice: type: - number - 'null' description: The stored sku price of this item readOnly: true example: 1 id: type: - string - 'null' description: The unique ID of the modifier product. example: d7a21692-9195-43aa-a58f-5395bba8a804 lineItemId: type: - string - 'null' description: 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. readOnly: true example: 2f91f9f3-2d7e-4898-ae81-00fe06ed7dbf skuId: type: - string - 'null' description: sku ID of the item. example: 867b8fdc-cf7b-4fc3-b7e0-4c7b68d8b1cc name: type: - string - 'null' description: The name of the modifier as displayed to the customer. example: Avocado price: type: - number - 'null' description: The price of the sold modifier. example: 1 groupName: type: - string - 'null' description: The parent group of the modifier item example: Add ons groupId: type: - string - 'null' description: The unique ID of the parent group example: fb52b138-7ac4-42c1-bfd8-664d57113a41 stationId: type: - string - 'null' description: The ID of the station the modifier item is assigned to. readOnly: true example: a49cbd3e-94e2-462d-a6de-1985e5d98d1c modifiers: type: - array - 'null' description: Nested modifiers applied to the item. maxItems: 100 items: $ref: '#/components/schemas/ItemModifier' PaymentDetailsCard: type: object description: Details of a card payment method. properties: brandType: $ref: '#/components/schemas/CardBrandType' expiration: type: object properties: year: type: integer description: The expiration year of the card. example: 2025 month: type: integer description: The expiration month of the card. example: 12 fundingType: $ref: '#/components/schemas/CardFundingType' walletType: $ref: '#/components/schemas/CardWalletType' lastFour: type: string description: The last four digits of the card. example: '1234' walletLastFour: type: string description: The last four digits of the wallet account. example: '5678' authorizationCode: type: string description: The authorization code for the card. example: auth_code_123 applicationPreferredName: type: string description: The preferred name of the application. example: MyApp fingerprint: type: string description: The fingerprint of the card. example: fingerprint_abc123 readMethod: type: string description: The method used to read the card. example: chip DropoffInstructions: type: - object - 'null' properties: dropoffType: type: string description: The drop-off type for the delivery. enum: - MEET_AT_DOOR - LEAVE_AT_DOOR - MEET_IN_LOBBY example: MEET_AT_DOOR verificationRequirements: $ref: '#/components/schemas/VerificationRequirements' description: Requirements to verify the completion of the delivery. securitySchemes: OAuth2.0: type: oauth2 description: "The **Authorization API** is based on the [OAuth2.0 protocol](https://tools.ietf.org/html/rfc6749), supporting the (Client Credentials)[https://datatracker.ietf.org/doc/html/rfc6749#section-4.4] and the (Authorization Code)[https://datatracker.ietf.org/doc/html/rfc6749#section-4.1] flows. Resources expect a valid token sent as a `Bearer` token in the HTTP `Authorization` header.\n### Scopes\nScopes must be configured by our internal team to be enabled for an app. Once the scopes are configured they can be enabled on the Application Settings Page in Developer Portal. Each endpoint requires a given scope that can be verified on each endpoint documentation. When generating an OAuth2.0 token multiple scopes can be requested.\n\n### Authorization Code Flow\nTo perform this flow, the authorization code flow must be enabled in the Application Settings Page in Developer Portal. When enabling the flow it is mandatory to provide a redirect URI pointing to your application. Once the flow is complete we will redirect the user to this URI passing the 'code' and 'state' parameters.\nThe Authorization Code flow provides a temporary code that the client application can exchange for an access token. To start the flow the application must request the user authorization. This is done by sending a request to https://{{public-api-url}}/v1/auth/oauth2/authorize.\nExample\n```\ncurl --location 'https://{{public-api-url}}/v1/auth/oauth2/authorize?client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]&response_type=code&scope=organization.read&state=8A9D16B4C3E25F6A'\n```\nThis call will return a 302 redirecting the user to our authorization page. If the user approves the application, we will redirect to configured URI passing the authorization code in the query parameter 'code'. The 'state' parameter is also sent to ensure the source of the data.\nWith the authorization code, the client application can generate the token.\n### Client Credentials Flow\nThe client_credentials flow does not require any steps before generating the token. Once your application is ready, and the client_id and client_secret are available, the token can be generated by following the instructions in the next section.\n\n### Generate Token\nTo generate the token, use the `Client ID` and `Client Secret` (provided during onboarding), and optionally the authorization code obtained after performing the Authorization Code flow, to the [Token Auth endpoint](#operation/requestToken) endpoint. The result of this invocation is a token that is valid for a pre-determined time or until it is manually revoked.\n\nThe access token obtained will be sent as a `Bearer` value of the `Authorization` HTTP header.\n\nClient credentials in the request-body and HTTP Basic Auth are supported.\n\n#### Request Example for client_credentials\n```\ncurl --location --request POST 'https://{{public-api-url}}/v1/auth/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'scope=ping' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'client_id=[APPLICATION_ID]' \\\n --data-urlencode 'client_secret=[CLIENT_SECRET]'\n\n```\n#### Request Example for authorization_code\n```\ncurl --location --request POST 'https://{{public-api-url}}/v1/auth/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'scope=ping' \\\n --data-urlencode 'grant_type=authorization_code' \\\n --data-urlencode 'client_id=[APPLICATION_ID]' \\\n --data-urlencode 'client_secret=[CLIENT_SECRET]' \\\n --data-urlencode 'code=[code]' \\\n --data-urlencode 'redirect_uri=[redirect_uri]'\n\n```\n#### Response Example\n```\n{\n \"access_token\": \"oMahtBwBbnZeh4Q66mSuLFmk2V0_CLCKVt0aYcNJlcg.yditzjwCP7yp0PgR6AzQR3wQ1rTdCjkcPeAMuyfK-NU\",\n \"expires_in\": 2627999,\n \"scope\": \"ping orders.create\",\n \"token_type\": \"bearer\"\n}\n```\n\n### Token Usage\n\nThe token provided in field `access_token` is used to authenticate when consuming the API endpoints. Send the token value in the `Authorization` header of every request. The token expiration time is represented in the field `expired_in`, in seconds. Currently, all tokens are valid for 30 days and should be stored and re-used while still valid.\n\nNote that occasionally, a 401 error may be returned for a valid token due to an internal service issue. Such occurrences should be rare. To prevent exposing potential vulnerabilities to attackers, the Public API does not disclose other types of errors in the authentication flow if for any reason the token can't be validated (when it's a valid token then it's ok to return 5XX or other 4XX though - such as 403). In such scenarios, although the internal auth flow avoids retries to prevent attacks, if the token is known to be valid and not expired, a retry with a backoff interval by the client is advised. Another option is to request a new token.\n\n#### Example\n\n```\ncurl --location --request GET 'https://{{public-api-url}}/v1/ping' \\\n --header 'Authorization: Bearer ' \\\n --header 'X-Store-Id: '\n\n```\n" flows: clientCredentials: tokenUrl: /v1/auth/token scopes: catalog: Permission to interact with product inventory for existing stores. delivery.provider: Permission to provide delivery services for existing orders. finance: Permission to provide financial data for orders/stores. manager.menus: Permission to manage menus. manager.orders: Permission to manage orders. manager.storefront: Permission to manage storefront. menus.async_job.read: Permission to read the status of a menu upsert job. menus.entity_suspension: Permission to notify the result of a menu entity availability update, after being requested by a webhook event. menus.get_current: Permission to send the current state of a menu, after being requested by a webhook event. menus.publish: Permission to notify the result of a publish menus operation for a given store. menus.read: Permission to read the current menus for a given store. menus.upsert: Permission to create/update menus for a given store. menus.upsert_hours: Permission to notify the receiving of the upsert hours menu event, after being requested by a webhook event. orders.create: Permission to create new order for a given store. orders.read: Permission to read orders and connected data. orders.update: Permission to create and update new orders for a given store. ping: Permission to ping the system. reports.generate_report: Permission to request reports for given store(s) and period of time. reviews.reply: Permission to reply to reviews. storefront.store_pause_unpause: Permission to notify the result of a pause/unpause operation, after being requested by a webhook event. storefront.store_availability: Permission to send the current state of store. storefront.store_hours_configuration: Permission to send the current store hours configuration. stores.manage: Permission to onboard stores and update the identifier. callback.error.write: Token has permission to send failed webhook event results. manager.loyalty: Permission to interact with loyalty services. direct.orders: Permission to interact with direct order services. store.read: Permission to query store information. authorizationCode: authorizationUrl: /v1/auth/oauth2/authorize tokenUrl: /v1/auth/token scopes: organization.read: Permission to read data for organization/brands/stores on behalf of a user. organization.service_integration: Permission to manage the your integration with a given store on behalf of a user. x-refined-from: - otter-account-pairing-endpoints-api-openapi.yml - otter-auth-endpoints-api-openapi.yml - otter-callback-endpoints-api-openapi.yml - otter-delivery-endpoints-api-openapi.yml - otter-direct-orders-endpoints-api-openapi.yml - otter-finance-endpoints-api-openapi.yml - otter-inventory-endpoints-api-openapi.yml - otter-manager-loyalty-endpoints-api-openapi.yml - otter-manager-menu-endpoints-api-openapi.yml - otter-manager-order-endpoints-api-openapi.yml - otter-manager-storefront-endpoints-api-openapi.yml - otter-market-intel-endpoints-api-openapi.yml - otter-menus-endpoints-api-openapi.yml - otter-orders-endpoints-api-openapi.yml - otter-organization-endpoints-api-openapi.yml - otter-ping-endpoints-api-openapi.yml - otter-reports-endpoints-api-openapi.yml - otter-reviews-endpoints-api-openapi.yml - otter-storefront-endpoints-api-openapi.yml x-tagGroups: - name: Endpoints tags: - Account Pairing Endpoints - Auth Endpoints - Callback Endpoints - Delivery Endpoints - Finance Endpoints - Inventory Endpoints - Manager Menu Endpoints - Manager Order Endpoints - Manager Storefront Endpoints - Menus Endpoints - Orders Endpoints - Organization Endpoints - Ping Endpoints - Reports Endpoints - Reviews Endpoints - Storefront Endpoints - Manager Loyalty Endpoints - Direct Orders Endpoints - Store Endpoints - name: Webhooks tags: - Account Pairing Webhooks - Delivery Webhooks - Manager Orders Webhooks - Menus Webhooks - Orders Webhooks - Ping Webhooks - Reports Webhooks - Storefront Webhooks