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

# Get offers

> The partner offers to show on a merchant's surface, by offer type.

Returns the partner brands' offers to show on this merchant's surface on your platform, for one offer type. For example, `post-purchase` offers appear on the merchant's order confirmation page.

Call it from your server at the moment you show the offers. Views and orders from these offers are credited to your platform.

The merchant must have approved your platform.

```curl cURL icon="terminal" theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}} 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'
```

```javascript JavaScript theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}}
const response = await fetch("https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/offers?type=post-purchase&viewId=ORDER_ID", {
  method: "GET",
  headers: {
    "X-Api-Key": "YOUR_PLATFORM_KEY",
  },
});

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

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

response = requests.request(
    "GET",
    "https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/offers?type=post-purchase&viewId=ORDER_ID",
    headers={
        "X-Api-Key": "YOUR_PLATFORM_KEY",
    },
)

data = response.json()
```

```php PHP theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}}
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/offers?type=post-purchase&viewId=ORDER_ID",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: YOUR_PLATFORM_KEY"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

```go Go theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}}
package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  url := "https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/offers?type=post-purchase&viewId=ORDER_ID"
  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("X-Api-Key", "YOUR_PLATFORM_KEY")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}
```

```ruby Ruby theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}}
require "uri"
require "net/http"

url = URI("https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/offers?type=post-purchase&viewId=ORDER_ID")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP.const_get("GET".capitalize).new(url)
request["X-Api-Key"] = "YOUR_PLATFORM_KEY"

response = http.request(request)
puts response.read_body
```

```csharp C# theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}}
using var client = new HttpClient();
using var request = new HttpRequestMessage(
    new HttpMethod("GET"),
    "https://api.branduo.io/v1/platform/brands/northwind-goods.myshopify.com/offers?type=post-purchase&viewId=ORDER_ID");
request.Headers.TryAddWithoutValidation("X-Api-Key", "YOUR_PLATFORM_KEY");

using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
```

```java Java theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}} theme={"languages":{"custom":["languages/curl.json"]}}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class BranduoRequest {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("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")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}
```

## When the list is empty

The response is `{ "offers": [] }` whenever the merchant's campaign of this type isn't live on your platform: placement is off, usage billing is off, setup isn't finished, or there's no partner offer to show right now. Show nothing in that case. It isn't an error.

The first call from a merchant's surface also tells Branduo that the merchant can show partner offers. A merchant's own offer is shown to other brands' shoppers only after one of their surfaces has asked, so call this route wherever you show offers, even while it returns nothing.

## Path parameters

**domain** `string` *required*

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

## Query parameters

**type** `string` *required*

The offer type. Today the only value is `post-purchase`: offers shown after
checkout, such as on the order confirmation page.

**viewId** `string`

Optional but recommended. A unique ID for one display of the offers. For an
order confirmation page, use the order ID. Repeating a `viewId` returns the
same offer and counts one view, even if the page is refreshed. Up to 200
printable characters; a longer or unprintable value is ignored, and the
request counts as a new view.

## Response

**offers** `object[]` *required*

The offers to show. Empty when the merchant's campaign isn't live here.

**properties**

**imageUrl** `string` *required*

URL of the offer image.

**referralUrl** `string` *required*

A Branduo short link (`https://go.branduo.io/r/…`) that sends the shopper
to the partner's store, with its discount when the offer has one. It is
specific to your platform and counts the click, so link to it exactly as
returned. Don't add parameters or resolve it ahead of time.

**title** `string` *required*

Primary offer text.

**subtitle** `string`

Supporting offer text. Left out when the offer has none.

**brandName** `string | null` *required*

The partner brand's name.

**logoUrl** `string | null` *required*

The partner brand's logo.

**domain** `string | null` *required*

The partner brand's store hostname.

**discountPercent** `integer | null` *required*

The partner's discount for new customers, as a whole percent. `null` when
there is no redeemable percent.

**products** `object[]` *required*

Up to three featured products. Empty when the partner has none.

**properties**

**title** `string` *required*

Product title.

**price** `string` *required*

Decimal amount as text, for example `"139.95"`.

**currency** `string` *required*

ISO currency code.

**imageUrl** `string` *required*

Product image URL.

Each offer returned counts as one view for your platform, once per `viewId`. This route allows 1,200 requests per minute per key; see [Rate limiting](https://docs.branduo.io/developer/rate-limiting.md).

## Errors

| Status | `error` | Cause |
| - | - | - |
| `400` | `invalid_offer_type` | `type` is missing or unknown. `allowed` lists the accepted values. |
| `400` | `invalid_request` | `domain` is not a store hostname. |
| `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"]}}
{
  "offers": [
    {
      "imageUrl": "https://cdn.example.com/offer.png",
      "referralUrl": "https://go.branduo.io/r/K7Q2M9XA",
      "title": "Claim 25% off",
      "subtitle": "Sheet sets, pillowcases & eye masks",
      "brandName": "Northwind Linen",
      "logoUrl": "https://cdn.example.com/northwind-logo.png",
      "domain": "northwindlinen.com",
      "discountPercent": 25,
      "products": [
        {
          "title": "Sateen Sheet Set",
          "price": "99.00",
          "currency": "USD",
          "imageUrl": "https://cdn.example.com/sheet-set.jpg"
        }
      ]
    }
  ]
}
```

```json 400 theme={"languages":{"custom":["languages/curl.json"]}}
{
  "error": "invalid_offer_type",
  "message": "type must be an offer type this API accepts.",
  "allowed": ["post-purchase"]
}
```

```json 403 theme={"languages":{"custom":["languages/curl.json"]}}
{
  "error": "not_approved",
  "message": "This brand has not approved your platform."
}
```


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