API Documentation

# Create Cart v2.0Beta

The Create Cart endpoint creates a new cart for a customer profile. Values supplied will be validated against a set of basic validation rules and a new cart will be created.

# Request

POST /v2.0/customers/{profileKey}/carts

# Authorization

An OAuth 2.0 Bearer token with the Cart.Write scope is required. For more information, see Authentication.

# Path Parameters

A list of the supported path parameters is described below.

Name Required Type Description
profileKey true guid The profile key for the customer.

# Request Body

The request body must be a JSON representation of a CreateCart object which is described below.

# CreateCart

Name Required Type Description
partnerKey true string(4) The partner key assigned to you.
restaurantKey true int The restaurant key that the order should be placed against.
items false CartItem[] A list of items with their selected options to be added to the cart on cart creation. A cart can be created without any items. Additional items can be added over time.
platform true string(50) An identifier for the platform the order is being placed from.
orderingChannel true string(50) The ordering channel for the order. This value can taken from the menu.
fulfilmentChannel true string(50) The fulfilment channel for the order. This value can taken from the menu.
currency true string(3) The ISO 4217 currency code for the currency applicable for the items, totals, fees and tip on the order.
note false string(300) A note to be submitted with the order. Notes may appear on the customers POS invoice.
specialInstructions false string(300) Instructions to be submitted with the order. Special instructions usually only print in the kitchen at the restaurant.

# CartItem

Name Required Type Description
menuKey true string(20) The key for the menu that item is from.
menuVersion true int The menu version for the menu that item is from.
menuItemKey true int64 The key for the menu item.
displayName true string(100) The display name of the item.
currency true string(3) The ISO 4217 currency code for the currency applicable for the item.
price true double The item price excluding the price of any selected options. This is the price of the item on the menu.
quantity true int The quantity of the item and its selected options to order.
options false CartItemOption[] The options the customer selected for the item.
specialInstructions false string(300) Instructions to be submitted for the item. Special instructions print in the kitchen at the restaurant.

# CartItemOption

Name Required Type Description
optionSetKey true int64 The option set that the option set item is from.
optionSetItemKey true int64 The key for the option.
displayName true string(100) The display name of the selected option.
currency true string(3) The ISO 4217 currency code for the currency applicable for the option.
price true double The price of the selected option.

# Sample

{
    "partnerKey": "0087",
    "restaurantKey": 1352,
    "platform": "Branded App",
    "orderingChannel": "Call and Order",
    "fulfilmentChannel": "Takeaway",
    "items": [
        {
            "menuKey": "ROCO-ZA-3",
            "menuVersion": 202107,
            "menuItemKey": 811000176,
            "displayName": "Classic Cheese Burger",
            "currency": "ZAR",
            "price": 69.00,
            "options": [
                {
                    "optionSetKey": 861000001,
                    "optionSetItemKey": 811000011,
                    "displayName": "Beef",
                    "currency": "ZAR",
                    "price": 0.00
                },
                {
                    "optionSetKey": 861000035,
                    "optionSetItemKey": 811000205,
                    "displayName": "Bacon",
                    "currency": "ZAR",
                    "price": 19.00
                }
            ],
            "quantity": 1,
            "specialInstructions": null
        }
    ],
    "currency": "ZAR",
    "note": "This is just an order level note for order.",
    "specialInstructions": "These are special instructions. Treat them with care."
}

# Response

200
OK
Returns an ApiResponse envelope.

# Response Body

The endpoint returns our ApiResponse envelope. The data property of the response will contain a cartId.

Name Required Type Description
cartId true guid The unique identifier for the cart.

# Sample

{
    "message": "The operation succeeded!",
    "notifications": [
        {
            "severity": "Success",
            "text": "The cart was created.",
            "code": null,
            "additionalData": null
        }
    ],
    "data": {
        "cartId": "672fb54a-db33-4549-b55e-90963b721e23"
    }
}

# Errors

The standard error responses apply.

400
Bad Request
When the request fails validation.
401
Unauthorized
When authentication fails.
403
Forbidden
When authorisation fails.

← Get Cart →