Platforms and Connected Merchants

Overview

A platform is a Breeze merchant that onboards and operates other merchants, called its connected merchants. A platform can:

• Call the Breeze API for a connected merchant with its own API key, by adding the x-breeze-partner-merchant-id header. The request runs as the connected merchant, and the action is attributed to the platform.
• Access each connected merchant's dashboard. The platform's owner account gets the EDITOR role on every connected merchant when the link is created. The role is removed when the link ends.
• List its connected merchants from the dashboard API.
• Receive webhooks for its connected merchants. A connected merchant's webhook events go to the platform's webhook endpoint, signed with the platform's secret. Every webhook carries an X-Breeze-Merchant-Id header naming the merchant the event belongs to.

Onboarding can be run by the platform or directly between Breeze and the merchant.

Breeze sets up platform links, and only with the connected merchant's agreement. Merchants can't create or remove links themselves.

Who is affected

Everything is opt-in. Only platforms need to change anything, and only if they want to use the new header. Existing integrations keep working unchanged.

A merchant is either a platform or a connected merchant, never both. A connected merchant has exactly one platform at a time.

Getting started as a platform

1. Ask Breeze to set up your platform and link your connected merchants. Each link requires that merchant's agreement. New merchants can be linked when Breeze creates them.
2. Get your connected merchant IDs. Call the list endpoint from the dashboard, or ask your account manager.
3. Send the act-as header on API calls. Add x-breeze-partner-merchant-id to any merchant API request made with your platform API key. Don't use a separate API key per connected merchant.
4. Match livemode. Use your live key for live connected merchants and your test key for test ones.

Calling the API for a connected merchant

Authenticate with your platform API key as you do today, and add the header:

POST /v1/<any merchant API route>
Authorization: <your platform API key, as today>
x-breeze-partner-merchant-id: mer_connected_example

The response echoes the header back, so you can confirm which merchant the call ran as:

HTTP/1.1 200 OK
x-breeze-partner-merchant-id: mer_connected_example

The request is processed as the connected merchant: records are created on, and read from, the connected merchant's account. Your own key's settings still apply to the call:

• Your API key's role and permissions
• Your IP allowlist
• Your account must not be offboarded, and neither may the connected merchant

Omit the header and the call runs on your own platform account, as before.

Listing your connected merchants

GET /v1/merchants/platform/connected_merchants returns your active connected merchants, newest first.

This is a dashboard endpoint. Call it with a dashboard session, not an API key.

{
  "data": {
    "connectedMerchants": [
      {
        "id": "mpr_example",
        "connectedMerchantId": "mer_connected_example",
        "connectedMerchantName": "Example Store",
        "status": "ACTIVE",
        "livemode": true,
        "createdAt": 1762819200000
      }
    ],
    "nextCursorToken": "eyJjcmVhdGVkQXQiOi4uLn0="
  },
  "hasMore": true
}

Receiving webhooks for connected merchants

Once a merchant is linked, its webhook events are delivered to your platform's webhook URL, signed with your webhook secret. The connected merchant's own webhook setting isn't used while the link is active. Payloads are unchanged.

We will send a X-Breeze-Merchant-Id header to tell which merchant an event belongs to. It holds the originating merchant's ID: the connected merchant for its events, your own ID for yours.

POST <your webhook URL>
X-Breeze-Merchant-Id: mer_connected_example

Route or filter events on this header rather than on payload fields, which differ by event type.

Dashboard access

The platform's owner account gets EDITOR access to each connected merchant's dashboard. Breeze manages this access, so neither side needs to send an invite.

EDITOR access can't change sensitive account details, such as the settlement bank account. Only an OWNER on the account can change them.

Connected merchants: you'll see your platform's owner in your team list as an EDITOR. If you had already invited that person as an EDITOR yourself, your invite stays in place after an unlink. To remove the platform's access, contact Breeze to end the link.

Platforms: access goes to your owner account only. Other members of your team aren't granted access automatically.