> ## 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.
> Authenticate with the X-Api-Key header. Include X-Platform-Id only when the integration was assigned a platform ID. OAuth access tokens are the alternative to API keys. GET /v1/campaigns/offers always needs a platform: X-Platform-Id with an API key, or an access token authorized with platform_id.
> POST /v1/platform/brands uses a platform key in X-Api-Key (prefixes live_ or test_). Do not send X-Platform-Id on that route. Omitted brands stay; close a brand with status closed.
> 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, token, or secret. The script is https://connect.branduo.io/loader/v2.0.0/brand-connect.js and the call is BrandConnect.init({ container, platformId, domain }). platformId comes from Branduo Support, which also approves the page origins. Modes are page (default) and drawer (handle.open()). The only event is brand.connect.stage with stage install, plan, setting_up, delayed, consent, or live.
> 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.

# Embed quickstart

> Add the Branduo Embed plugin to your app with one script and one line of setup.

This guide adds the plugin to a page in your app. It takes a few minutes and needs no server changes.

## Before you start

Ask [Branduo Support](/support/contact) for:

* Your **platform ID**. It is public, so it is safe to put in your page.
* Approval for each web address (origin) where the plugin will appear, such as `https://app.example.com`.
* The page in your app where the plugin lives, such as `https://app.example.com/integrations/branduo`. Merchants return there after they approve their plan in Shopify.

## 1. Add the plugin to your page

Add the loader script, an empty element for the plugin, and one call to `BrandConnect.init`:

```html theme={"languages":{"custom":["languages/curl.json"]}}
<script
  src="https://connect.branduo.io/loader/v2.0.0/brand-connect.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>

<div id="brand-connect"></div>

<script>
  BrandConnect.init({
    container: "#brand-connect",
    platformId: "YOUR-PLATFORM-UUID",
    domain: "brand.com",
  });
</script>
```

Then:

* Replace `YOUR-PLATFORM-UUID` with the platform ID from Support.
* Set `domain` to the signed-in merchant's store domain, from your own records. A custom domain (`brand.com`) or the `*.myshopify.com` domain both work. Branduo drops the scheme, any path, and `www.`.
* Replace `sha384-…` with the value published at `https://connect.branduo.io/loader/v2.0.0/brand-connect.js.sri`. The versioned URL never changes, so the hash stays valid until you move to a new version.

That's the whole integration. The plugin works out the merchant's stage and shows the right screen.

| Option | Required | Description |
| - | - | - |
| `container` | Yes | The element, or a selector for it, that the plugin appears in. |
| `platformId` | Yes | Your platform ID, a UUID. |
| `domain` | Yes | The merchant's store domain. |
| `mode` | No | `"page"` (default) or `"drawer"`. |
| `onEvent` | No | Called with `{ type: "brand.connect.stage", stage }` when the plugin loads and whenever the stage changes. See [Stages](/developer/embed/stages). |
| `onClose` | No | Called when the merchant closes the drawer. |

TypeScript types are published at `https://connect.branduo.io/loader/v2.0.0/brand-connect.d.ts`.

## 2. Open it in a drawer (optional)

To open the plugin from a button instead of showing it on the page, set `mode: "drawer"` and call `open()` on the handle that `BrandConnect.init` returns:

```html theme={"languages":{"custom":["languages/curl.json"]}}
<button id="partner-with-brands">Partner with brands</button>
<div id="brand-connect"></div>

<script>
  const handle = BrandConnect.init({
    container: "#brand-connect",
    platformId: "YOUR-PLATFORM-UUID",
    domain: "brand.com",
    mode: "drawer",
    onClose: () => console.log("Drawer closed"),
  });

  document
    .getElementById("partner-with-brands")
    .addEventListener("click", () => handle.open());
</script>
```

The drawer opens from the right, up to 520 pixels wide. It closes with its **Close** button, a click on the backdrop, or the Escape key. Each of these calls `onClose`.

The handle has three methods:

* `open()`: opens the drawer. It does nothing in page mode.
* `close()`: closes the drawer and calls `onClose`.
* `destroy()`: removes the plugin and its listeners.

In page mode, the plugin fills the container's width and grows with its content, starting at 480 pixels tall.

## 3. Allow Branduo in your security policy

If your app uses a Content Security Policy, allow Branduo:

```http theme={"languages":{"custom":["languages/curl.json"]}}
script-src https://connect.branduo.io;
frame-src https://connect.branduo.io;
child-src https://connect.branduo.io;
```

Add these values to your existing policy rather than replacing it.

The plugin only loads on origins Support approved. An origin includes the protocol and hostname, so `https://app.example.com` and `https://example.com` are different. If another site frames your app, ask Support to approve both origins.

## 4. Bring merchants back after they approve their plan

New merchants install Branduo from the Shopify App Store and approve their plan in Shopify. To send them straight back to your app afterward:

1. Give Support the page where the plugin lives (see [Before you start](#before-you-start)). It must be on an approved origin.
2. Sync your merchants' store domains with [Sync platform brands](/developer/platform/brands). Branduo uses that list to know which app a merchant came from.

When both are in place, **Install** and **Approve plan** open in the same tab, and Branduo returns the merchant to your page with `?branduo_connect=return`. The loader removes that parameter from the address bar. In drawer mode, it also reopens the drawer, so call `BrandConnect.init` on that page load as usual.

Without them, those buttons open in a new tab, and the plugin checks again when the merchant comes back to your tab.

## Next steps

See what merchants see at each [stage](/developer/embed/stages). If the plugin does not load, work through [Troubleshooting](/developer/embed/troubleshooting).


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