# How it works

The Groupon Partner API lets partners, influencers and builders (and the AI coding assistants
they use to build with) list Groupon deals on their own site, mirror a shopper's cart in
Groupon, and send the shopper to Groupon's checkout to pay. Only US inventory is exposed today.

## At a glance

- US deals only. Voucher deals only: deals that need a time-slot booking are not offered.
- You keep the catalog in your own database by syncing it. There is no search endpoint.
- You get your API key yourself, in this portal: sign in, register a storefront, create a key.
- Checkout always happens on Groupon's page.
- Earning commission is optional: add a CJ publisher ID after you register your storefront.
- One environment.

## The three API groups

| API group | Purpose |
|---|---|
| Products | Pull Groupon deals into your own database and list them on your site. |
| Cart | Mirror your shopper's cart in Groupon, and get the checkout link. |
| Booking | After payment, read the order's status and the links to the shopper's vouchers. |

## End-to-end flow

```text
1. Get your key      Sign in to this portal, register a storefront, create an API key
2. Sync catalog      GET /partner_storefront/products (full load once, then deltas every few
                      hours) -> your database
3. Shopper browses    Your site renders deals from YOUR database
4. Add to cart        First item:  POST /partner_storefront/carts
                                    -> you receive cart `id` + `buyLink`
                       Later edits: POST/PATCH/DELETE on
                                    /partner_storefront/carts/{cartId}/items
5. Buy now             Your "Buy now" button href = the latest `buyLink` from any cart response
6. Pay at Groupon      Shopper pays on Groupon's checkout page (shows your logo if you gave one)
7. Return              Groupon redirects the shopper to YOUR redirect URL
                        with ?grouponOrderUuid=<uuid>
8. Confirm             GET /partner_storefront/bookings/{bookingId}
                        -> status + one "View on Groupon" link per purchased unit
```

Every path is relative to `https://api-staging-core.livingsocial.com`. Each step has its own guide: [Get your API
key](/docs/get-your-api-key.md), [Syncing the catalog](/docs/syncing-the-catalog.md), [Managing the
cart](/docs/managing-the-cart.md), and [Checkout and order confirmation](/docs/checkout-and-order-confirmation.md).

You keep two carts in step: the one on your site, and its mirror in Groupon. Groupon's copy is
the one that gets paid for.

## Checkout, and earning commission with CJ

Every storefront uses the same checkout: set your Buy now button's href to the `buyLink` from
the latest cart response, verbatim. `buyLink` is present on every cart response. Never build the
checkout URL yourself.

To earn commission, add a CJ (Commission Junction) publisher ID after you register (see [Get
your API key](/docs/get-your-api-key.md)). It is optional, and your code does not change: only what
`buyLink` contains changes.

| | Default | After you add CJ |
|---|---|---|
| What buyLink is | The Groupon checkout URL for the cart. | A CJ affiliate tracking link carrying your publisher ID. It redirects the shopper to Groupon's checkout page for the cart. |
| Commission | None. | Tracked and paid through CJ, monthly: 7% of the net sale when the shopper is new to Groupon, 1% when they are an existing Groupon customer. A refund cancels the commission on that sale. The shopper must reach checkout through buyLink; any other route earns nothing. |

The checkout page always shows your logo if you gave one when you registered your storefront.