Skip to content
BaxPayDevelopers

Online shop

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. Bookable services (appointments and classes) are covered in Bookings, and storefront designs in Theme development.

Storefront API

Catalog, cart pricing, checkout and the customer's order page.

Build a headless shop

Bookings

Free time slots, booking at checkout, customer cancel and reschedule.

Sell appointments

Payment links

Every order is paid on a hosted BaxPay payment page.

How orders are paid

Turning the shop on

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

PlatformBaxPay
The online shop is live on the platform.
Planpricing
The merchant's plan includes the online shop.
Online shopmerchant
The merchant switched it on (Business dashboard → Settings, or the Business app → More → Online shop).
Productsmerchant
Products are switched on. Only products sold ONLINE or BOTH appear in the shop (see Products & catalog).
Publishedmerchant
The shop has an address (slug) and is published.

When any of them is off, the Storefront API answers 403 or 404 for that shop.

Addresses and custom domains

Shop addressslug
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 domainplan
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:

RecordHostValue
CNAMEshop.example.comshops.baxpay.com
TXT_baxpay-shop.shop.example.combaxpay-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.

PENDING_PAYMENT

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

PAID

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

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.

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.paidwebhook

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.

metadata.shopSaleGET /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.

Analyticsdashboard

Business analytics report shop sales as the Online shop channel, split into Online shop order and Booking sale types.

payment (excerpt)
{
  "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 and POST /shop/{slug}/quote.

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

RoleView shop & ordersSettings & designPublish, address, domainFulfil orders & bookingsCancel paid & refund
Owner / Admin✓✓✓✓✓
Manager✓✓—✓✓
Viewer✓————
Attendant✓——✓—