What your assistant can do

The server exposes these shopping tools. Their arguments and answers use camelCase names, the same as the public reads.

Tool	What it is for
search_offers	Find offers by words
get_offer	Read one offer in full
get_journey	See what LivingSocial knows about the current shopping session, its cart included
get_cart	Read current items, quantities, total and the private cart link
update_cart	Set the final quantity of a line returned by the cart
remove_from_cart	Remove a line returned by the cart
add_to_cart	Put an option in the person's cart, the one they open on LivingSocial
prepare_checkout	Prepare a purchase the person pays for on Groupon
get_purchase_status	Read how each prepared purchase stands
link_email, link_phone	Optionally attach the person's LivingSocial account to the session, with a six-digit code or a link

• search_offers finds United States offers by words. It takes query (1 to 200 characters: every word must match unless none can, quotes keep a phrase together, a leading minus excludes a word, or accepts either word) and can narrow by city, category, maxPriceMinor with currency, or near (a point with a radiusKm of up to 200). limit is 1 to 20, and 10 when left out. Each offer comes with its id and permalink, status, price and options, places, categories, whether it can be bought now, and unknown, the list of facts LivingSocial does not have. It changes nothing for the person.
• get_offer reads one offer in full, by its id or permalink (offer): every option with its price, the places, the categories, the fine print where LivingSocial has it, and when LivingSocial last read the offer from Groupon (observedAt). An expired or sold-out offer still answers, says so, and is marked as not purchasable.
• get_journey tells the assistant what LivingSocial knows about the current shopping session: its id, whether the person's identity is anonymous or confirmed, the cart as it stands (its lines and total), cartUrl (the cart page on LivingSocial with the session in its link), how many checkouts are still open, and a note on what the record can and cannot show. It never starts a session.
• add_to_cart puts one option of one offer in the person's cart after checking it is still sellable at the price shown. The cart is the person's own: the same cart they see when they open cartUrl on LivingSocial. The quantity is set, so a repeat changes nothing. Nothing is paid.
• get_cart reads the current cart. Use it to answer "what is in my cart?" and before editing. An empty new session is not proof that the person's separate browser or account cart is empty.
• update_cart takes a lineId from the cart and the desired final quantity (1 to 50). Repeating a set does not add units. remove_from_cart takes the same lineId and removes it. Both return the full remaining cart and cartUrl; never use an offer or option id as a line id.
• prepare_checkout prepares the purchase the person chose. It sets the chosen option in the cart and starts a checkout with Groupon for the cart, and it answers a private link (handoffUrl) for the person to open. It never charges anyone and never pays.
• get_purchase_status reads how each of the session's checkouts stands, whether the status is final, and what the person should do next. It can be limited to one checkout with checkoutId.
• link_email and link_phone are optional. Searching and buying never need them, and the person needs no LivingSocial account beforehand. action: "start" sends one email or text message to the contact the person gave, carrying a six-digit code and a confirmation link; action: "confirm" with code takes the code the person tells the assistant; action: "status" reports whether the person confirmed and whether their account is attached.