How a shopping session works

A search_offers or get_offer call that carries no token starts a shopping session, which LivingSocial calls a journey. Its answer carries a journey.token: a standard LivingSocial API token (grpn_...) that stands for this session, the way a browser's cookie would, without a browser. The server shows the token once, in the answer to that call. The assistant passes it as journeyToken on every later call, so LivingSocial knows the calls belong together and keeps one cart for them.

The cart is the person's. Whatever the assistant puts in it with add_to_cart is what the person sees when they open cartUrl (the cart page on LivingSocial with the session in its link): the page takes the token from the link, drops it from the address and uses it for its own calls, so the assistant and the person share one cart. When the person confirms an email or a phone, their LivingSocial account (found, or created) is attached to the session: from then on the token acts for the account and the cart is the account's.

• Only search_offers and get_offer start a journey. get_journey, add_to_cart, get_purchase_status, link_email, link_phone and prepare_checkout need a journeyToken and never start one. Without it they answer journey_required.
• The token is private to the person. Anyone who holds it can carry on that session and open its cart, so it does not belong in a summary, a share link or a message to someone else. cartUrl already carries it for the person; give them that link and nothing else.
• A token that LivingSocial does not recognise, or that has expired, answers journey_invalid. The same token will be refused again. Explain that access to this cart was lost; start a new session only if the person wants to start again. Never present the new session's empty cart as their previous cart.