# Online shop

Every BaxPay merchant can run a storefront at `https://{slug}.baxpay.com` (or their own domain)
for goods and bookable services. Orders are paid through BaxPay payment links, so they settle,
refund and reconcile like any other BaxPay payment.

You can use the storefront BaxPay hosts, or build your own front end on the
[Storefront API](https://developers.baxpay.com/online-shop/storefront-api). Bookable services (appointments and classes) are
covered in [Bookings](https://developers.baxpay.com/online-shop/bookings), and storefront designs in
[Theme development](https://developers.baxpay.com/online-shop/themes).

- [Storefront API](https://developers.baxpay.com/online-shop/storefront-api):
  Catalog, cart pricing, checkout and the customer's order page.
- [Bookings](https://developers.baxpay.com/online-shop/bookings):
  Free time slots, booking at checkout, customer cancel and reschedule.
- [Payment links](https://developers.baxpay.com/payment-links):
  Every order is paid on a hosted BaxPay payment page.

## Turning the shop on

A storefront is public only when all of these are true:

- `Platform` (BaxPay): The online shop is live on the platform.
- `Plan` (pricing): The merchant's plan includes the online shop.
- `Online shop` (merchant): The merchant switched it on (Business dashboard → Settings, or the Business app → More → Online shop).
- `Products` (merchant): Products are switched on. Only products sold `ONLINE` or `BOTH` appear in the shop (see [Products & catalog](https://developers.baxpay.com/products)).
- `Published` (merchant): The shop has an address (`slug`) and is published.

When any of them is off, the [Storefront API](https://developers.baxpay.com/online-shop/storefront-api) answers `403` or `404`
for that shop.

> **Live mode only**
> Shop checkouts always create live payment links: there is no test-mode storefront. Use
> [Sandbox & test mode](https://developers.baxpay.com/sandbox) to try payment links themselves, and keep shop tests to a
> merchant account set up for that purpose.

## Addresses and custom domains

- `Shop address` (slug): 3–48 characters, `a-z`, `0-9` and `-`. Some words are reserved (`www`, `app`, `pay`, `api`, `admin`, `business`, `developers`…). The address cannot change while the shop is published.
- `Default URL`: `https://{slug}.baxpay.com`
- `Custom domain` (plan): When the plan allows it, the merchant claims a domain in the dashboard and adds two DNS records.

For a custom domain such as `shop.example.com`:

| Record | Host | Value |
|--------|------|-------|
| `CNAME` | `shop.example.com` | `shops.baxpay.com` |
| `TXT` | `_baxpay-shop.shop.example.com` | `baxpay-verify=<token from the dashboard>` |

A root domain (`example.com`) cannot use a CNAME: use an `ALIAS` / `ANAME` record at your DNS
provider, or a subdomain. The domain turns active once the merchant clicks **Verify DNS** and the
TXT record is found.

## Orders

Checkout creates an order (`PENDING_PAYMENT`) and a payment link for its total. The customer pays on
the hosted page, then comes back to the shop's order page.

**1. PENDING_PAYMENT**

Order created at checkout; stock is held at the shop's stock location while the link is open.

**2. PAID**

The payment link was paid. The merchant is notified (email, in-app, push) and the customer gets
their confirmation, which is their receipt.

**3. READY_FOR_PICKUP or SHIPPED**

Pickup orders become ready for pickup; delivery orders are shipped, optionally with a tracking
number and an `https://` tracking link. The customer is emailed each time.

**4. COMPLETED**

Done. An order can also be `CANCELLED` before it completes; a paid order can be refunded in full
when it is cancelled.

Order numbers are per merchant and start at `#1001`. Orders are managed in the Business dashboard
(Online shop → Orders) and in the Business app.

### Seeing shop sales in your integration

- `payment_link.paid` (webhook):
  Fires when a shop order is paid, like for any payment link. `reference` is the order number
  (`"#1042"`) and `paymentLinkId` identifies the order's link. See [Webhooks](https://developers.baxpay.com/webhooks).
- `metadata.shopSale` (GET /payments):
  In the payments the Business dashboard, app and terminals read (`GET /payments`, with a
  dashboard or terminal session), a payment that paid a shop order carries
  `{ orderId, orderNumber, sale, bookings }`, where `sale` is `"order"` (goods, or goods and
  services) or `"booking"` (only booked services). Older payments are tagged too.
- `Analytics` (dashboard):
  Business analytics report shop sales as the **Online shop** channel, split into
  **Online shop order** and **Booking** sale types.

```json
{
  "id": "txn_…",
  "amount": 18900,
  "currency": "EUR",
  "status": "CAPTURED",
  "metadata": {
    "paymentLinkId": "…",
    "kind": "payment_link",
    "channel": "online",
    "shopSale": { "orderId": "…", "orderNumber": 1042, "sale": "order", "bookings": 0 }
  }
}
```

## Delivery, pickup and checkout options

The merchant sets these in the dashboard (Online shop → Settings) or in the Business app. The
storefront reads them from [`GET /shop/resolve`](https://developers.baxpay.com/online-shop/storefront-api#resolve-a-shop) and
[`POST /shop/{slug}/quote`](https://developers.baxpay.com/online-shop/storefront-api#price-a-cart).

- `Shipping rates`: Up to 10: name, price, free above an order amount, destination countries (ISO codes), delivery days.
- `Pickup points`: Up to 10: name, address and instructions. Pickup is free.
- `Checkout`: Ask for a phone number; let customers add a note.
- `Stock location`: The location whose stock online orders use.
- `Contact, social links, SEO`: Shown in the storefront footer, emails and search results.

Services never need delivery. Delivery is taxed like the goods it carries, so receipts and
e-invoices always add up to the amount charged.

## Team roles

| Role | View shop & orders | Settings & design | Publish, address, domain | Fulfil orders & bookings | Cancel paid & refund |
|------|:--:|:--:|:--:|:--:|:--:|
| Owner / Admin | ✓ | ✓ | ✓ | ✓ | ✓ |
| Manager | ✓ | ✓ | — | ✓ | ✓ |
| Viewer | ✓ | — | — | — | — |
| Attendant | ✓ | — | — | ✓ | — |

## Related

- [Storefront API](https://developers.baxpay.com/online-shop/storefront-api) — build your own shop front end
- [Bookings](https://developers.baxpay.com/online-shop/bookings) — appointments and classes
- [Products & catalog](https://developers.baxpay.com/products) — what the shop sells
- [Payment links](https://developers.baxpay.com/payment-links) — how orders are paid
- [Webhooks](https://developers.baxpay.com/webhooks) — `payment_link.paid` for paid orders