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

# Connect link

> The URL behind your Connect Branduo button, where it sends merchants, and how they come back to your app.

The connect link is a plain URL. Put it behind the **Connect Branduo** button in your app. It needs no key and grants nothing: it tells Branduo that your platform sent this store, then sends the merchant to Shopify, where they approve your platform in the Branduo app.

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

Open it in the browser, as a link or a new tab. Don't call it from your server: it answers with a redirect, not JSON, unless the IP address is [rate limited](https://docs.branduo.io/developer/rate-limiting.md).

## Query parameters

**platformId** `string` *required*

Your platform ID, a UUID from Branduo Support. It is public.

**domain** `string`

The merchant's store domain: their `*.myshopify.com` domain or their own
domain, such as `northwindgoods.com`. Branduo drops the scheme, `www.`, the
port, and any path. Send it whenever you know it. Without it, the merchant is
asked for their store name first.

## Where it sends the merchant

| The store | The merchant goes to |
| - | - |
| Already on Branduo | The Branduo app in that store's Shopify admin, where the approval is waiting. If they removed the app, its install. |
| 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` sent | **Enter your Shopify store**: a Branduo page with one box for the store name (`northwind-goods` `.myshopify.com`). **Continue** comes back to the connect link with the full domain. |
| Your platform isn't active on Branduo | Your return URL with `status=unavailable`, or a Branduo page saying brand partnerships aren't available yet. Nothing is recorded. |

Branduo remembers that you sent the store for **7 days**. While it does:

* Opening the Branduo Shopify app shows the merchant **Run your offer on \{your platform}** until they choose **Approve** or **Not now**.
* [Get a brand](https://docs.branduo.io/developer/platform/get-brand.md) shows you the merchant's full stage (install, billing, approve) before they approve.

If the store installs Branduo within 24 hours of the last click on your link, Branduo also records your platform as the one that brought it.

A merchant can always choose **Not now**. Sending the link again asks again.

## Coming back to your app

After **Approve** or **Not now**, the Branduo Shopify app opens your return URL (set up with Support) in the merchant's browser:

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

| Parameter | Value |
| - | - |
| `branduo_connect` | Always `return`. Use it to recognize the return. |
| `status` | `approved`, `declined` (the merchant chose **Not now**), or `unavailable` (your platform isn't active on Branduo) |
| `shop` | The store's `*.myshopify.com` domain. Left out for `unavailable` when the link had no `*.myshopify.com` domain. |

Query parameters already on your return URL are kept.

> [!WARNING]
>
> The return is not signed. Anyone can open your return URL with
> `status=approved`. Always confirm with [Get a brand](https://docs.branduo.io/developer/platform/get-brand.md)
> before you change anything.

Without a return URL on file, the merchant stays in the Branduo Shopify app after approving.

## Limits

Branduo records at most 5 clicks per store per hour, and at most 300 per platform per minute. Clicks past those limits still redirect; they just aren't recorded again. Separately, one IP address can open the link 120 times a minute; past that it returns HTTP **429** with the [`rate_limit` JSON body](https://docs.branduo.io/developer/rate-limiting) and a `Retry-After` header (seconds left in the window) instead of redirecting.


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