Platforms and agencies

E-commerce platforms, marketplaces and agencies manage stores for many merchants. The Partner API lets you onboard them to Phew and run their integration with a single partner credential.

How it fits together

• One partner account, with its own API keys or OAuth client.
• Many merchants, each with a mer_ ID. You create them with POST /v1/merchants.
• Act on behalf of a merchant by adding Phew-Merchant: mer_… to any Checkout API call. Without the header, a partner credential can only call Partner API endpoints.

curl https://api.getphew.com/v1/offers \
  -H "Authorization: Bearer $PHEW_PARTNER_KEY" \
  -H "Phew-Merchant: mer_01JD7Z4K2Q8V6N3R5T7W9Y1A3C" \
  --json @cart.json

Onboarding a merchant

1. Create the merchant with their company details and store URL. The merchant starts in pending status.

2. Merchant accepts. The response contains a one-time onboarding_url. Send the merchant there (or embed it in your admin); they confirm their details and accept the merchant terms. The link works once and expires after 7 days.

3. Phew reviews the merchant and their catalogue. You get a merchant.updated event when the status becomes active, usually within one business day.

4. Start offering. From then on, Checkout API calls with the merchant’s Phew-Merchant header return offers.

Note

Merchants must accept Phew’s merchant terms themselves. A partner can’t accept them on a merchant’s behalf.

Commission

Commission can go to the merchant, to you, or be split between you. The split is set per merchant when you create it (commission.partner_share) within the limits in your partner agreement, and both parties see it on the monthly statement.

Permissions

Restrict each key or OAuth client to what it needs. A typical platform setup:

Credential	Scopes	Used by
Onboarding	merchants:write	Your admin backend
Storefront	offers:write, policies:write, policies:cancel	Your checkout service
Reporting	settlements:read, claims:read	Your finance and support tools

See API keys for how to create restricted keys.