Skip to main content
This guide builds the whole integration with your own screens. If you’d rather paste a ready-made onboarding screen, use the Embed plugin for steps 1 to 5 and follow steps 6 and 7 here.

Before you start

From Branduo Support, get your platform ID and platform key, and give us your return URL (an https page in your app). See Integration options. 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 first:
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. The button opens:
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.

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:
status is approved, declined, or unavailable (your platform isn’t active on Branduo). Any query string already on your return URL is kept.
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 with the shop value. Store shop: it is the merchant’s permanent ID and never changes, even if their custom domain does.
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. To list every merchant who approved you, page through List brands with approved=true.

6. Show partner offers

Wherever your platform shows offers for this merchant (for example, their order confirmation page), call Get offers from your server at the moment you show them:
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.
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 with active: false. Call it with active: true when it’s back, or to start an offer type you added after the merchant approved.
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 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 before you test, and we’ll help you set up a store to test with.