Overview

Cart state is maintained server-side, which frees up developers from the tricky task of client-side cart management. No call is needed to initiate a session; simply add an item for a given merchant ID and the cart can then be manipulated with the calls listed below.

Cart Session Modes

There are two different cart session modes for authenticated and guest users.

Authenticated User Cart

Authenticated user carts are identified with access tokens passed in the Authorization header. No special actions are necessary.

Guest Cart

Guest carts are identified by the Guest-Token header, the value of which must be generated before initiating a cart session. Guest cart sessions can be integrated into authenticated user sessions by simply passing the Guest-Token header to the login and account creation endpoints, after which the converted carts can be accessed using the authenticated user flow described above.

Retrieve Contents

HTTP Request

GET /customer/cart/{merchant_id}

Request Parameters

  "order_type": "pickup",
  "order_time": "2014-01-19T08:00:00-0500"
Parameter Name Type Notes
Required Parameters
order_type String Must be either ‘pickup’ or ‘delivery’ (Note: Items and Carts are never for pickup or for delivery only. The reason we ask for the type in all the cart operations is so we can calculate details about the cart – delivery fee for example.)
Optional Parameters
order_time String For future orders; must be ISO8601 format
client_id String Required if passing a Guest-Token for unauthenticated users
Required Parameters (Delivery Orders)
zip String 5 characters
city String
state String
latitude Float
longitude Float

Success Response

HTTP 200 OK

{
   "cart":[
      {
         "id":"E33",
         "name":"Tuna Fish Salad Sandwich",
         "quantity":3,
         "type":"item",
         "item_key":0,
         "options":[
            {
               "id":"E34",
               "name":"Choice of Bread",
               "quantity":1,
               "type":"option group",
               "item_key":null,
               "options":[
                  {
                     "id":"E41",
                     "name":"Cinnamon Raisin Bagel",
                     "quantity":1,
                     "type":"option",
                     "item_key":null,
                     "options":[

                     ],
                     "item_label":"",
                     "price_compare_item":false,
                     "laundry_type":null,
                     "anonymous_id":null,
                     "images":[

                     ]
                  }
               ],
               "item_label":"",
               "price_compare_item":false,
               "laundry_type":null,
               "anonymous_id":null,
               "images":[

               ]
            },
            {
               "id":"E44",
               "name":"Choice of Sandwich Condiments\/Extras",
               "quantity":1,
               "type":"option group",
               "item_key":null,
               "options":[
                  {
                     "id":"E46",
                     "name":"Cheddar Cheese",
                     "quantity":1,
                     "type":"option",
                     "item_key":null,
                     "options":[

                     ],
                     "item_label":"",
                     "price_compare_item":false,
                     "laundry_type":null,
                     "anonymous_id":null,
                     "images":[

                     ]
                  }
               ],
               "item_label":"",
               "price_compare_item":false,
               "laundry_type":null,
               "anonymous_id":null,
               "images":[

               ]
            }
         ],
         "item_label":"",
         "price_compare_item":false,
         "laundry_type":null,
         "anonymous_id":null,
         "images":[

         ],
         "price":7.5
      }
   ],
   "item_count":3,
   "subtotal":7.5,
   "tax":0.79,
   "total":14.09,
   "discount":0,
   "discount_percent":0,
   "fees":[
      {
         "name":"Required Tip",
         "value":1.35
      },
      {
         "name":"City Bag Fee",
         "value":0.23
      },
      {
         "name":"Healthy SF Surcharge",
         "value":1.54
      },
      {
         "name":"Convenience Fee",
         "value":0.93
      },
      {
         "name":"Delivery Fee",
         "value":1.75
      }
   ],
   "delivery_points":150,
   "delivery_points_multiplier":1,
   "time_updated":"2016-07-15T13:40:12-0400",
   "asap":true,
   "order_time":"2016-07-15T14:00:00-0400",
   "laundry_pickup_times":[

   ],
   "laundry_delivery_times":[

   ],
   "minutes_left_for_asap_order":599,
   "message":[
      {
         "code":"loc_invalid_range",
         "user_msg":"The address Schenectady NY 12345 is out of the merchant's delivery range.",
         "dev_msg":"The address Schenectady NY 12345 is out of the merchant's delivery range."
      }
   ]
}

Missing Delivery Address Response

HTTP 400 Bad Request

{
  "cart": null,
  "item_count": 0,
  "message": [
    {
      "field": "zip",
      "code": "no_zip",
      "user_msg": "The zip field is required.",
      "dev_msg": "The zip field is required."
    },
    {
      "field": "city",
      "code": "no_city",
      "user_msg": "The city field is required.",
      "dev_msg": "The city field is required."
    },
    {
      "field": "state",
      "code": "no_state",
      "user_msg": "The state field is required.",
      "dev_msg": "The state field is required."
    },
    {
      "field": "latitude",
      "code": "no_latitude",
      "user_msg": "The latitude field is required.",
      "dev_msg": "The latitude field is required."
    },
    {
      "field": "longitude",
      "code": "no_longitude",
      "user_msg": "The longitude field is required.",
      "dev_msg": "The longitude field is required."
    }
  ],
  "subtotal": 0,
  "tax": 0,
  "total": 0,
  "discount": 0,
  "fees": [

  ],
  "order_time": "2014-02-09T23:45:00-0500",
  "asap": true,
  "order_type": "delivery"
}

Add Item(s)

HTTP Request

POST /customer/cart/{merchant_id}

Request Body

Add One Item

{
   "order_type":"delivery",
   "order_time":"ASAP",
   "item":{
      "item_id":"E761",
      "item_qty":2,
      "option_qty":{
         "E114":1,
         "E428":1,
         "E763":1
      },
      "item_label":"",
      "instructions":""
   },
   "client_id":"MDlkMzY3Nzg3MjU1ZjRkNmY4OWZjNDA0NjBjMTI0MWZl"
}

Add Multiple Items

{
  "order_type": "delivery",
  "instructions": "Some instructions",
  "items":[
      {
         "item_id":"E354",
         "item_qty":1,
         "option_qty":{
            "E4":1,
            "E19":1,
            "E203":1
         },
         "item_label":"",
         "instructions":""
      },
      {
         "item_id":"E145",
         "item_qty":1,
         "option_qty":{
            "E69":1,
            "E134":1,
            "E137":1,
            "E143":1
         },
         "item_label":"",
         "instructions":""
      }
   ],
  "client_id": "NDY4NDAzYzViYmI0YWM0NTM3NTJmYzhmZWJkMWQwMWZi"
}
Property Name Type Notes
Required Parameters
item Item Use this param to add one item to the cart. (To add multiple items, use the following one)
items Array of Item Use this param to add multiple items to the cart at once. (To add one item, use the above one)
order_type String Must be either ‘pickup’ or ‘delivery’ (Note: Items are never for pickup or for delivery only. The reason we ask for the type in all the cart operations is so we can calculate details about the cart – delivery fee for example.)
Optional Parameters
order_time String For future orders; must be ISO8601 format
instructions String Special requests for this particular item
client_id String Required if passing a Guest-Token for unauthenticated users

Success Response

HTTP 200 OK
The response is identical to Retrieve Content endpoint.

Item Object

{
  "item_id": "N9",
  "item_qty": 1,
  "option_qty": {
    "N17": 1
  },
  "instructions": "Item instructions"
}

Modify an Item

HTTP Request

PUT /customer/cart/{merchant_id}

Request Body

{
   "order_type":"delivery",
   "order_time":"ASAP",
   "item":{
      "item_id":"E33",
      "item_qty":2,
      "option_qty":{
         "E41":1,
         "E46":1
      },
      "item_label":""
   },
   "cart_index":0,
   "client_id":"MDlkMzY3Nzg3MjU1ZjRkNmY4OWZjNDA0NjBjMTI0MWZl"
}
Property Name Type Notes
Required Parameters
cart_index Integer The cart item’s item_key value to remove.
item Item The cart item to edit
order_type String Must be either ‘pickup’ or ‘delivery’ (Note: Items are never for pickup or for delivery only. The reason we ask for the type in all the cart operations is so we can calculate details about the cart – delivery fee for example.)
Optional Parameters
order_time String For future orders; must be ISO8601 format
client_id String Required if passing a Guest-Token for unauthenticated users

Success Response

HTTP 200 OK
The response is identical to Retrieve Content endpoint.

Incorrect Cart Index Response

HTTP 400 Bad Request

{
  "message": [
    {
      "code": "cart_index_not_found",
      "user_msg": "The item was not found in your cart.",
      "dev_msg": "Cart index ($cart_index) not found."
    }
  ],
  "subtotal": 27,
  "tax": 2.4,
  "item_key": 0,
  "item_count": 3,
  "order_time": "2014-02-07T18:45:00-0500"
}

Clear Cart / Remove an Item

HTTP Request

DELETE /customer/cart/{merchant_id}

Request Body

{
  "cart_index": 0
}
Property Name Type Notes
Optional Parameters
cart_index Integer The cart item’s item_key value to remove. Only removes specific item; otherwise the cart will be cleared.
client_id String Required if passing a Guest-Token for unauthenticated users

Success Response

HTTP 200 OK
The response is identical to Retrieve Content endpoint.

Generate a Guest Token

HTTP Request

GET /customer/auth/guest

Request Params

{
  "client_id": "NDY4NDAzYzViYmI0YWM0NTM3NTJmYzhmZWJkMWQwMWZi"
}

Success Response

HTTP 200 OK

{
    "Guest-Token": "f528764d624db129b32c21fbca0cb8d652f8625c459096.60225085"
}