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

# Set placement

> Turn a merchant's Branduo placement on your platform off or on, for one offer type.

Turns the merchant's placement for one offer type on your platform off or on. Call it when the merchant turns your Branduo placement off or removes your app (`false`), and when it's back (`true`).

* **Off** pauses all of the merchant's campaigns of that type on your platform. Nothing is deleted, and their results are kept.
* **On** resumes them. For an offer type you started serving after the merchant approved, `true` also starts their campaign of that type.
* It never creates an approval, and it never touches a merchant who hasn't approved you.

If your placement is always on, you never need to call it. Every change is logged with your platform, the time, and the value before and after.

The merchant must have approved your platform.

```curl cURL 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 }'
```

```javascript JavaScript theme={"languages":{"custom":["languages/curl.json"]}}
const response = await fetch(
  "https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/campaigns/post-purchase",
  {
    method: "PUT",
    headers: {
      "X-Api-Key": "YOUR_PLATFORM_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ active: false }),
  },
);

const placement = await response.json();
```

```python Python theme={"languages":{"custom":["languages/curl.json"]}}
import requests

response = requests.put(
    "https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/campaigns/post-purchase",
    headers={"X-Api-Key": "YOUR_PLATFORM_KEY"},
    json={"active": False},
)

placement = response.json()
```

## Path parameters

**domain** `string` *required*

The merchant's store domain, `*.myshopify.com` or custom.

**type** `string` *required*

The offer type key, for example `post-purchase`. It must be a type your
platform serves.

## Request body

**active** `boolean` *required*

`true` to turn the placement on, `false` to turn it off.

```json theme={"languages":{"custom":["languages/curl.json"]}}
{ "active": false }
```

## Response

**shop** `string` *required*

The store's `*.myshopify.com` domain.

**type** `string` *required*

The offer type key.

**placementOn** `boolean` *required*

The placement after this call.

**live** `boolean` *required*

Whether the merchant's campaign of this type is live on your platform now.
Turning placement on doesn't make it live if something else holds it back
(for example, usage billing is off). [Get a
brand](https://docs.branduo.io/developer/platform/get-brand.md) says why in `pausedReason`.

## Errors

| Status | `error` | Cause |
| - | - | - |
| `400` | `invalid_request` | The body isn't `{ "active": true }` or `{ "active": false }`, or `domain` is not a store hostname. |
| `400` | `type_not_served` | Your platform doesn't serve this offer type. |
| `401` | `unauthorized` | The platform key is missing or invalid. |
| `403` | `not_approved` | The merchant hasn't approved your platform. |
| `403` | `platform_inactive` | Your platform isn't active on Branduo. |

```json 200 theme={"languages":{"custom":["languages/curl.json"]}}
{
  "shop": "northwind-goods.myshopify.com",
  "type": "post-purchase",
  "placementOn": false,
  "live": false
}
```

```json 400 theme={"languages":{"custom":["languages/curl.json"]}}
{
  "error": "type_not_served",
  "message": "This platform does not serve that campaign type."
}
```


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