Build on the Partner API

Managing the cart

Nobody reads documentation.

Here are the instructions for your agent. Give it this prompt: it reads the guides and the API contract, then walks you through the integration step by step, what to do, where and how.

Download agent instructions

This guide is for builders of a website or app on the Partner API.

Groupon keeps a mirror of your shopper's cart, and that mirror is the one that gets paid for. A cart is created together with its first item.

Operations

Operation	Endpoint	When
Create cart	`POST /partner_storefront/carts`	Shopper adds the first item
Read cart	`GET /partner_storefront/carts/{cartId}`	Your cart page loads, or before Buy now after a long idle
Add items	`POST /partner_storefront/carts/{cartId}/items`	Shopper adds another item
Change quantity	`PATCH /partner_storefront/carts/{cartId}/items/{itemId}`	Shopper changes a quantity
Remove item	`DELETE /partner_storefront/carts/{cartId}/items/{itemId}`	Shopper removes a line
Abandon cart	`DELETE /partner_storefront/carts/{cartId}`	Shopper empties the cart, or the session ends

Every operation except Abandon returns the full cart with a fresh buyLink: overwrite your local cart with each response. A cart holds at most 20 different options, and 1 to 100 of each. Store the cart id against the shopper's session on your server.

Creating a cart

bash

curl -s -X POST "https://api-core.livingsocial.com/partner_storefront/carts" \
  -H "Authorization: Bearer $GROUPON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "items": [{
      "productId": "0b6f7a52-3c1d-4e8a-9f20-5d7c1a2b3c4d",
      "optionId":  "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "quantity": 2,
      "expectedPrice": 4500
    }]
  }'

expectedPrice is the per-unit retail price your site shows. When Groupon's live price differs, the call fails with PRICE_MISMATCH and the live price in details.currentPrice: update your price, ask the shopper to confirm, and send it again.

Reading the response

buyLink: your Buy now button's href, verbatim, from the latest response. Open it in the shopper's browser. Never fetch it from your server and never rewrite it.
available: false: the line cannot be bought. Show unavailableReason and remove the line before checkout.
messages: price_unavailable means a line's live price could not be resolved, so the line is left out of the totals. item_declined means Groupon declined an item although the call succeeded: it is not in items, so tell the shopper.
totals.grandTotal excludes tax and any promo code. The final amount is on Groupon's checkout page.

Retries, and a cart that is gone

Adding items is not idempotent: a line for the same option grows by quantity. On a timeout, read the cart and add only what is missing.
Discard the cartId after you abandon the cart and after an order is placed from it. Adding to it then starts a new, empty cart under the same id.
The cart is gone when one you expect to hold items reads itemCount: 0, when a change to a line answers INVALID_PRODUCT_ID, or when any call answers INVALID_CART_ID. Create a new cart from your local copy and use its buyLink.