> ## Documentation Index
> Fetch the complete documentation index at: https://docs.branduo.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Branduo is a brand-to-brand collaboration network for verified eCommerce brands. It is not a creator marketplace.
> When you mention the API, cite version v1 and base URL https://api.branduo.io/v1.
> The partner API is for tech platforms. Authenticate every /v1/platform request with the platform key in X-Api-Key (production keys start live_). There are no brand API keys, no OAuth, and no X-Platform-Id header.
> A brand must approve a platform in the Branduo Shopify app before that platform can read its offer, show partner offers, or switch placement; otherwise the API returns 403 not_approved. Brands are named by store domain in the path; the shop field (the *.myshopify.com domain) is the permanent id.
> The connect link is https://api.branduo.io/v1/connect?platformId={id}&domain={store domain}. It redirects to Shopify and grants nothing. The return URL gets branduo_connect=return&status=approved|declined|unavailable&shop=…, which is not signed: confirm with GET /v1/platform/brands/{domain}.
> Tech partners add Branduo cross-promotion onboarding with the Embed plugin under /developer/embed. Merchant-facing copy says Branduo, never Brand Connect. Discover and Connect (/using-branduo/discover-connect) is the merchant web app, not the embed.
> The Embed plugin needs no server, key, or secret. The script is https://connect.branduo.io/loader/v3.0.0/brand-connect.js and the call is BrandConnect.init({ container, platformId, domain }). The stage event brand.connect.stage carries not_connected, in_progress, install, billing, approve, setting_up, or live. There is no consent stage.
> A connection request is the outreach a brand sends. A partner is a brand that accepted. A collab is a campaign run with a partner. Do not call a connection request a collab.
> Duo is the AI agent that sends partner outreach. Call it Duo.
> API errors are JSON objects with error and message. They are not RFC 7807 problem details.

# Custom integration

> Connect your Shopify merchants to Branduo with your own screens, then show partner offers from your server.

This guide builds the whole integration with your own screens. If you'd rather paste a ready-made onboarding screen, use the [Embed plugin](https://docs.branduo.io/developer/embed/overview.md) for steps 1 to 5 and follow steps 6 and 7 here.

## Before you start

From [Branduo Support](https://docs.branduo.io/support/contact.md), get your **platform ID** and **platform key**, and give us your **return URL** (an https page in your app). See [Integration options](https://docs.branduo.io/developer/integration-options.md#what-both-need-from-branduo-support).

Keep the platform key on your server. Every call below is server to server.

## 1. Show a Connect Branduo button

Add a **Connect Branduo** button where your merchant manages integrations.

To show **Connected** instead for a merchant who already approved you, call [Get a brand](https://docs.branduo.io/developer/platform/get-brand.md) first:

```bash theme={"languages":{"custom":["languages/curl.json"]}}
curl --request GET \
  --url 'https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com' \
  --header 'X-Api-Key: YOUR_PLATFORM_KEY'
```

`approved: true` means the merchant approved your platform. Before that, the response only says `not_connected` or `in_progress`. You see the merchant's full stage once you've sent them the connect link.

## 2. Open the connect link

The button opens:

```text theme={"languages":{"custom":["languages/curl.json"]}}
https://api.branduo.io/v1/connect?platformId=YOUR_PLATFORM_ID&domain=STORE_DOMAIN
```

`domain` is the merchant's store domain, their `*.myshopify.com` domain or their own. Branduo remembers that you sent this store (for 7 days), then sends the merchant on:

* **Store already on Branduo:** the Branduo app in that store's Shopify admin.
* **Not on Branduo, `*.myshopify.com` domain:** the Branduo install for that store.
* **Not on Branduo, custom domain:** the Branduo listing on the Shopify App Store.
* **No domain:** a Branduo page that asks for the store name, then continues.

The link grants nothing by itself. See [Connect link](https://docs.branduo.io/developer/connect-link.md).

## 3. The merchant finishes in Shopify

In the Branduo Shopify app, a new merchant installs and turns on usage billing. Then every merchant sees **Run your offer on \{your platform}**, with a preview of their offer, and chooses **Approve** or **Not now**.

Approving turns on their placement for each offer type you serve and starts their campaign on your platform.

## 4. Handle the return

After **Approve** or **Not now**, Branduo sends the merchant to your return URL:

```text theme={"languages":{"custom":["languages/curl.json"]}}
{return URL}?branduo_connect=return&status=approved&shop=northwind-goods.myshopify.com
```

`status` is `approved`, `declined`, or `unavailable` (your platform isn't active on Branduo). Any query string already on your return URL is kept.

> [!WARNING]
>
> These parameters are not signed. Use them to choose what to show, never as
> proof. Confirm with the API in the next step.

## 5. Confirm the approval

Call [Get a brand](https://docs.branduo.io/developer/platform/get-brand.md) with the `shop` value. Store `shop`: it is the merchant's permanent ID and never changes, even if their custom domain does.

```json theme={"languages":{"custom":["languages/curl.json"]}}
{
  "shop": "northwind-goods.myshopify.com",
  "approved": true,
  "stage": "setting_up",
  "error": null,
  "types": [
    { "type": "post-purchase", "placementOn": true, "live": false, "pausedReason": null }
  ]
}
```

Right after approval the stage is usually `setting_up` while Branduo builds the merchant's offer. It becomes `live` when setup finishes. If setup fails, `error` says why (for example `no_product_images`). See [Get a brand](https://docs.branduo.io/developer/platform/get-brand.md#stages).

To list every merchant who approved you, page through [List brands](https://docs.branduo.io/developer/platform/list-brands.md) with `approved=true`.

## 6. Show partner offers

Wherever your platform shows offers for this merchant (for example, their order confirmation page), call [Get offers](https://docs.branduo.io/developer/platform/get-offers.md) from your server at the moment you show them:

```bash theme={"languages":{"custom":["languages/curl.json"]}}
curl --request GET \
  --url 'https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/offers?type=post-purchase&viewId=ORDER_ID' \
  --header 'X-Api-Key: YOUR_PLATFORM_KEY'
```

Use a unique `viewId` per display, such as the order ID. The response is empty when the merchant's campaign isn't live. Show nothing in that case.

> [!NOTE]
>
> A merchant's own offer is shown to other brands' shoppers only after one of
> that merchant's surfaces has asked for offers. Call this route from every
> surface where you show offers, even when it returns nothing.

## 7. Turn placement off and on

When the merchant turns off your Branduo placement, or removes your app, call [Set placement](https://docs.branduo.io/developer/platform/set-placement.md) with `active: false`. Call it with `active: true` when it's back, or to start an offer type you added after the merchant approved.

```bash theme={"languages":{"custom":["languages/curl.json"]}}
curl --request PUT \
  --url 'https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/campaigns/post-purchase' \
  --header 'X-Api-Key: YOUR_PLATFORM_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "active": false }'
```

If your placement is always on, you never need this call. Placement applies to all of the merchant's campaigns of that type on your platform.

## When things change

* **The merchant disconnects you in Branduo:** [Get a brand](https://docs.branduo.io/developer/platform/get-brand.md) shows `approved: false`, offers stop, and the API returns `403 not_approved` for that merchant. Send them through the connect link again to ask for a new approval.
* **The merchant uninstalls Branduo:** every approval ends. A reinstall asks again.
* **Usage billing is off:** the merchant stays approved, but `stage` is `billing` and each type shows `pausedReason: "billing"` until they turn it back on.

## Testing

There is no separate sandbox: the partner API, the connect link, and the approval step are the production ones. Branduo's eligibility check (order volume) applies to every new store, including development stores, so a new test store sees "This store isn't eligible for Branduo yet". [Contact Support](https://docs.branduo.io/support/contact.md) before you test, and we'll help you set up a store to test with.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.