Branded Marketplace
A marketplace operator builds a branded shopping destination with a curated set of merchants. The buyer searches across the operator’s merchants, selects products, and checks out — each cart scoped to one source merchant. The marketplace identity belongs to the operator; the merchant is the seller of record.
Recommended setup
| Choice | Default | Why |
|---|---|---|
| Integration pattern | Operator-Hosted or Embedded Marketplace | Operator owns the branded UI either fully or embedded in another product |
| Auth | Browser session | Per-user marketplace browsing session |
| Payment | Card (JWE-encrypted) as primary; PayPal, Google Pay, or Klarna per operator preference | A single-merchant cart supports the full payment menu |
| Attribution | Marketplace operator ID + source merchant | Operator’s identity tagged on every order |
API sequence
Follows the Single Product Purchase flow.
| Step | Endpoint |
|---|---|
| 1. Search the marketplace | POST /api/v1/discovery/search |
| 2. Add to cart | POST /api/v2/domains/{domain}/cart/line-items |
| 3. Set shipping address | POST /api/v2/domains/{domain}/cart/shipping-info |
| 4. Pick shipping method | POST /api/v2/domains/{domain}/cart/shipment/methods |
| 5. (Optional) Get delivery availability | POST /api/v2/domains/{domain}/cart/shipments/get-availability |
| 6. (If required) Get + set merchant consents | GET /api/v2/domains/{domain}/cart/consents → PUT /api/v2/domains/{domain}/cart/consents |
| 7. Get payment public key | GET /api/v1/payment/key |
| 8. Complete order | POST /api/v2/payment/domains/{domain}/complete-order |
The valid shipping_method_ids for step 4 come from the cart itself — cart.shipments[].shipping_method_options, populated by step 3 (set-shipping-info). get-availability (step 5) is optional and returns delivery dates, time slots, or pickup locations for scheduled-delivery or in-store-pickup shipments — not shipping methods. Steps 2–6 build the cart, so step 8 finalizes it with complete-order (body: encrypted_card + billing_info); use place-order only for the one-shot create-cart-and-order call.
Considerations the operator owns
- Curated merchant selection. The operator decides which merchants are visible. Typically there’s an admin process to approve merchants before they appear in marketplace search results.
- Brand consistency. Marketplace UI carries the operator’s brand, not the source merchant’s. When the buyer reaches the merchant’s order confirmation, the marketplace UI re-wraps it in operator branding (a link to the merchant’s real confirmation is still surfaced).
- Trust signals. Product-level ratings and review counts come through the catalog; surface them on search results and product pages. Any merchant-level reputation presentation is the operator’s own layer.
- Marketplace-specific commission. If the operator charges a commission, reconcile it from the operator ID carried on each order’s metadata — the operator’s own commission-tracking system matches orders by that identifier.