CLcloudkitchens
orders_endpoints

Create order

Pushes a new order into Otter for the store identified by the X-Store-Id header. Used by ordering marketplaces and other order sources when a customer places an order. Provide the order's line items, fulfillment information, customer payments, and at least one financial breakdown — orderTotal (V1) or orderTotalV2 (V2). Both are accepted; when both are present, V2 takes precedence. New integrations should prefer orderTotalV2. All monetary values use the major unit of the order's currencyCode. The response returns the order reference: the source externalIdentifiers (id and friendlyId) and storeId. Use those values to correlate and update the order later. externalIdentifiers.id is the order's stable identity for the source and store. Retrying with an ID that already exists does not create another order; the API returns 409 Conflict instead of replaying the original success response. Rate limit: 32 requests per minute.

post/v1/orders

Request

Headers

X-Store-Idstring 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).

Example:partner-store-unique-identifier

Request body

currencyCodestring 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.

orderedAtstring date-time nullable

The date (in UTC) when the order was placed by the customer.

customerNotestring nullable

An order-level note provided by the customer.

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.

Example request

{
  "externalIdentifiers": {
    "id": "69f60a06-c335-46d9-b5a1-97f1a211c514",
    "friendlyId": "ABCDE",
    "source": "ubereats",
    "sourceExternalIdentifiers": {
      "id": "69f60a06-c335-46d9-b5a1-97f1a211c514",
      "friendlyId": "ABCDE",
      "source": "ubereats"
    }
  },
  "currencyCode": "EUR",
  "items": [
    {
      "quantity": 1,
      "skuPrice": 5.9,
      "id": "33e0418f-3d56-4360-ba03-18fc5f8844a3",
      "lineItemId": "2f91f9f3-2d7e-4898-ae81-00fe06ed7dbf",
      "skuId": "867b8fdc-cf7b-4fc3-b7e0-4c7b68d8b1cc",
      "name": "Juicy Cheeseburger",
      "note": "Please cook to well done!",
      "categoryId": "303de078-870d-4349-928b-946869d4d69b",
      "internalCategoryId": "76a66bba-48fb-4bac-80ee-2616a5ca1ab9",
      "categoryName": "Burgers",
      "internalCategoryName": "Burgers",
      "stationId": "5247b8a1-77de-4844-b024-cb59fcec59bd",
      "price": 5.9,
      "modifiers": [
        {
          "quantity": 1,
          "skuPrice": 1,
          "id": "d7a21692-9195-43aa-a58f-5395bba8a804",
          "lineItemId": "2f91f9f3-2d7e-4898-ae81-00fe06ed7dbf",
          "skuId": "867b8fdc-cf7b-4fc3-b7e0-4c7b68d8b1cc",
          "name": "Avocado",
          "price": 1,
          "groupName": "Add ons",
          "groupId": "fb52b138-7ac4-42c1-bfd8-664d57113a41",
          "stationId": "a49cbd3e-94e2-462d-a6de-1985e5d98d1c"
        }
      ]
    }
  ],
  "orderedAt": "2007-12-03T09:15:30.000Z",
  "customer": {
    "name": "Jane Doe",
    "phone": "+1-555-555-5555",
    "phoneCode": "111 11 111",
    "email": "email@email.com",
    "personalIdentifiers": {
      "serviceProviderId": "12345ba6-789e-123f-4e56-d78db90d123b"
    }
  },
  "customerNote": "Please include extra napkins!",
  "deliveryInfo": {
    "courier": {
      "name": "Jane Doe",
      "phone": "+1-555-555-5555",
      "phoneCode": "111 11 111",
      "email": "email@email.com",
      "personalIdentifiers": {
        "serviceProviderId": "12345ba6-789e-123f-4e56-d78db90d123b"
      }
    },
    "destination": {
      "fullAddress": "123 Sample Street Ste 100, San Francisco, CA 94103",
      "postalCode": "20500",
      "city": "Washington",
      "state": "DC",
      "countryCode": "US",
      "addressLines": [
        "1600 Pennsylvania Avenue NW",
        "123 Sample Street Ste 100, San Francisco, CA 94103"
      ],
      "linesOfAddress": [
        "1600 Pennsylvania Avenue NW",
        "123 Sample Street Ste 100, San Francisco, CA 94103"
      ],
      "location": {
        "latitude": 38.8977,
        "longitude": 77.0365
      }
    },
    "licensePlate": "ABC 123",
    "makeModel": "Honda CR-V",
    "lastKnownLocation": {
      "latitude": 38.8977,
      "longitude": 77.0365
    },
    "dropoffInstructions": {
      "verificationRequirements": {
        "signatureRequirement": {
          "enabled": true,
          "collectSignerName": true,
          "collectSignerRelationship": true
        },
        "pictureRequirement": {
          "enabled": true
        }
      }
    },
    "note": "Gate code 123"
  },
  "orderTotal": {
    "subtotal": 11.97,
    "claimedSubtotal": 11.97,
    "discount": -1.1,
    "tax": 1.1,
    "tip": 2,
    "deliveryFee": 5,
    "total": 19.07,
    "couponCode": "VWXYZ98765"
  },
  "orderTotalV2": {
    "customerTotal": {
      "foodSales": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "feeForRestaurantProvidedDelivery": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "restaurantFundedDiscount": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "voucherDiscount": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "promotionDiscount": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "operatorDiscount": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "loyaltyDiscount": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "tipForRestaurant": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "adjustments": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "packingFee": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "bagFee": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "serviceProviderDiscount": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "tipForServiceProviderCourier": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "feeForServiceProviderDelivery": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "smallOrderFee": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "serviceFee": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "otherFee": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "netPayout": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "couponCodes": [
        "TACOWED5OFF"
      ]
    },
    "customerPayment": {
      "customerPaymentDue": 1,
      "customerPrepayment": 1,
      "customerAmountToReturn": 1,
      "paymentDueToRestaurant": 1
    },
    "payout": {
      "payoutFromServiceProvider": 1,
      "payoutFrom3rdParty": 1,
      "cashPayout": 1
    },
    "serviceProviderCharge": {
      "commission": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "processingFee": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "salesTaxWithheld": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "deliveryFeeForRestaurant": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "advertisingFee": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "chargesAdjustments": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      },
      "otherFees": {
        "breakdown": [
          {
            "name": "sales tax.",
            "value": 3.4
          }
        ]
      }
    }
  },
  "customerPayments": [
    {
      "value": 2,
      "paymentRecords": [
        {
          "otterPaymentRecordId": "otter_123456789",
          "recordProviderType": "STRIPE",
          "recordPaymentType": "CARD",
          "paymentRecordId": "pm_123456789",
          "payerId": "payer_123456789",
          "balanceTransactionId": "ext_bt_123456789",
          "paymentDetails": {
            "brandType": "VISA",
            "expiration": {
              "year": 2025,
              "month": 12
            },
            "fundingType": "CREDIT",
            "walletType": "APPLE_PAY",
            "lastFour": "1234",
            "walletLastFour": "5678",
            "authorizationCode": "auth_code_123",
            "applicationPreferredName": "MyApp",
            "fingerprint": "fingerprint_abc123",
            "readMethod": "chip"
          }
        }
      ],
      "loyaltyInfo": {
        "hasMembershipPass": true
      }
    }
  ],
  "fulfillmentInfo": {
    "pickupTime": "2007-12-03T09:15:30.000Z",
    "estimatedPickupTime": "2007-12-03T09:15:30.000Z",
    "deliveryTime": "2007-12-03T09:15:30.000Z",
    "tableIdentifier": "R-45"
  },
  "promotionsDetails": [
    {
      "name": "20% off, up to $5",
      "value": 2
    }
  ],
  "preparationTime": {
    "estimatedPreparationTime": "PT30M"
  },
  "cutleryRequest": "CUTLERY_REQUESTED"
}

Response

The order was successfully created.

storeIdstring required

The identifier of the store.

Example response

{
  "externalIdentifiers": {
    "id": "69f60a06-c335-46d9-b5a1-97f1a211c514",
    "friendlyId": "ABCDE",
    "source": "ubereats",
    "sourceExternalIdentifiers": {
      "id": "69f60a06-c335-46d9-b5a1-97f1a211c514",
      "friendlyId": "ABCDE",
      "source": "ubereats"
    }
  },
  "storeId": "ckdss-store-id"
}

Changes

No recorded changes to this operation across all 1 revision of this API.