Gift Ideas

Creates a checkout from line items and/or a cart. Nothing is charged: the checkout is a 'Review and pay' page on supraise.com (continue_url) where the user adds an address and pays. Returns continue_url, a summary (subtotal and estimated_total, both with the Supraise service fee already in the item prices; tax and shipping are added once the retailer prices the order) and messages: address_required, cannot_ship_to_address, split_orders (items from several sellers become separate orders), price_unknown, over_limit (orders are capped at €200 ($217) for now). The checkout stays open 30 days.

create_checkout

Saves a gift plan: once or on a schedule, a gift within the budget is chosen from the recipient's interests and ordered. recipient: 'self' (contents stay secret until the box arrives), 'someone' (a named person; needs their shipping_address and can carry a note for the packing slip) or 'random' (a stranger who opted in to receive gifts). The plan is saved paused and returns activate_url: nothing is ordered or paid until the user turns it on at supraise.com and funds the gift wallet there.

create_surprise_plan

Returns the signed-in user's Supraise account: saved shipping addresses (from past checkouts and gift recipients), gift wallet balance, gift plans and saved payment methods.

get_account

Returns a checkout's status (open; paid = paid, test orders; completed = paid and ordered; expired), lines, totals, messages, continue_url and, once paid, the order ids.

get_checkout

Returns one product with its options (e.g. Size, Width, Color) and all variants. Given `options` as name/label pairs, selected_variant is the matching variant and its variant_id; when nothing matches, selected_variant is null and the available values are listed in options.

get_product

Returns products already found by search_catalog, by id, without a new search. Unknown ids are listed in not_found.

lookup_catalog

Searches products across Amazon, Walmart, Target, Best Buy, Home Depot and other US retailers in one call, for finding, comparing or buying a product. Returns up to `limit` products, each with title, rating, review count, a one-line summary, image_url, the price from each seller, and product_url (the product's Supraise page, where options are chosen and the purchase is made). Results are also shown as product cards with images. Prices are in USD and already include the Supraise service fee; tax and shipping are added when the retailer prices the order.

search_catalog

Changes an open checkout: line quantities (0 removes), remove_variant_ids, email, or shipping_address. Returns the updated summary and messages. Fails once the checkout is paid or expired.

update_checkout