Integration Patterns
Branded Commerce uses a single primary integration pattern — Firmly-hosted under the partner’s own domain. Every page (landing page, PDP, checkout, thank-you) is rendered by Firmly’s edge and served on a custom domain configured by the partner. Theming is applied from a single per-partner theme object so the buyer-facing identity is consistent end to end.
There is no separate off-domain variant of Branded Commerce. The whole point is that the buyer never leaves the partner’s domain.
The four configuration dimensions
| Dimension | Setting |
|---|---|
| Hosting | Firmly-hosted under the partner’s domain (only mode today — fixed by the solution shape) |
| Theming | Single theme per partner, applied to every page; supports per-property variants if the partner runs multiple brands (fixed by the solution shape) |
| Affiliate mode | BYO (partner’s own affiliate-network credentials) or Firmly-managed — the partner chooses |
| Ad-platform pixel channels | Per platform (Meta, Google, TikTok, etc.), choose pixel-only (client-side) or dual-fire (client + server-side CAPI) — the partner chooses, determined by which credentials they supply |
The first two are fixed by the solution shape; the last two are the real choices, configured during partner onboarding.
Hosting — partner domain via Cloudflare for SaaS
The partner adds two DNS CNAME records — one per environment:
| Environment | Partner hostname | CNAME target |
|---|---|---|
| Production | deals.partner.example (or any subdomain) |
firmly.live |
| UAT / staging | deals-staging.partner.example |
firmlyuat.com |
Each CNAME must be DNS-only (grey-cloud) if the partner’s DNS is on Cloudflare. Firmly enrolls each hostname in its matching Cloudflare zone and provisions TLS via Cloudflare for SaaS.
Staging and production are independent enrollments — no “promotion” path. Staging stays in place after launch for ongoing pre-production testing.
Theming — single theme object, applied to every page
The partner provides brand assets and copy preferences during onboarding (see Partner onboarding for the full intake). Firmly builds a theme object and applies it to all pages:
| Category | What’s needed |
|---|---|
| Brand assets | Logo files (light + dark, SVG preferred), favicon, hero imagery for landing pages |
| Typography | Primary font family, weight scale, licensing, optional display font |
| Palette | Primary, secondary/accent, text, background/surface, border, state colors |
| Button treatment | Corner radius, fill style, hover state, CTA label case |
| Chrome | Header logo placement, header density, back arrow style, footer links |
| Copy preferences | Brand voice, promo language template, CTA verb, savings callout phrasing, merchant identity line |
| Legal copy | T&C URL, privacy policy URL, per-surface disclaimers, jurisdiction |
| Merchant identity | Prominent vs subtle display per merchant, show merchant domain or not |
Per-property theming. Partners running multiple brand properties (e.g., several deal sites under one parent) can have one onboarding produce multiple theme variants, not one theme.
Attribution mode — BYO or Firmly-managed
Affiliate attribution is a configured business choice, not a setting a shopper or a normal drop-in integration changes at runtime. See the Affiliate API overview for the partner-only Start Journey flow and its operating boundaries.
| Mode | Who has the affiliate-network accounts | Who fires the conversion |
|---|---|---|
| BYO | Partner — partner’s own CJ / Impact / Awin / Rakuten / etc. credentials | Firmly fires through the partner’s network using partner’s credentials |
| Firmly-managed | Firmly — Firmly’s existing relationships and accounts | Firmly fires through its own credentials, settles commission to the partner per agreement |
Choose during onboarding. Most partners with existing affiliate businesses pick BYO; partners new to affiliate marketing typically start with Firmly-managed.
The flow for the buyer is identical in either mode — the difference is who provides the tracking relationship.
Ad-platform pixel channels
Per ad platform the partner runs campaigns on, choose between client-side pixel only and dual-fire (client + server-side CAPI). The channel mix is determined by which credentials the partner supplies:
| What the partner provides | Channel mix |
|---|---|
| Pixel ID / dataset ID only | Client-side pixel only |
| Pixel ID + account ID + access token | Dual-fire — client-side pixel + server-side CAPI with event_id dedup |
Recommended: provide both. The server-side channel covers conversions the client-side pixel misses due to ad blockers; the event_id deduplication prevents double-counting.
Supported ad platforms: Meta (CAPI), Google Ads (Enhanced Conversions), TikTok, Pinterest, Snap, Reddit. The partner provides per-platform credentials during onboarding.
Compliance and PCI
The partner’s domain serves Firmly-controlled pages. Payment data is captured by Firmly’s checkout component and tokenized via the merchant’s PSP — never on the partner’s side. The partner takes on no PCI obligations through this integration.
Unlike embedded-widget integrations, there is no partner-side iframe — checkout is a full-page Firmly-rendered surface on the partner’s domain. PCI scope is entirely on Firmly’s side.
What the partner provides vs. what Firmly handles
| Step | Partner | Firmly |
|---|---|---|
| DNS CNAME records | ✓ (two records, one per env) | — |
| TLS provisioning | — | Via Cloudflare for SaaS |
| Brand assets + copy preferences | ✓ (intake form) | Builds theme object |
| Theme application across all pages | — | Applies same theme to every page |
| Affiliate-network credentials (if BYO) | ✓ | Configures + fires |
| Ad-platform credentials | ✓ (per platform) | Fires conversion events |
| Merchant list + onboarding status | Agree with Firmly | Firmly onboards new merchants as needed |
| Staging end-to-end testing | Both | Both |
Pre-launch checklist
Before going live:
- Production CNAME resolves; TLS valid on partner hostname
- Staging CNAME resolves; TLS valid on staging hostname; staging tested end-to-end
- Theme reviewed on staging (Landing page, PDP, Checkout, Thank-you)
- Affiliate mode chosen + credentials configured
- Per-platform ad pixels configured (and, ideally, server-side credentials too for dual-fire)
- At least one test order completes on staging end to end
- Legal copy (T&C, privacy, disclaimers) approved and live
Related
- Operations → Partner onboarding — the full one-time setup
- Operations → Operational workflow — the ongoing per-product / per-campaign workflow
- Why Firmly — what Firmly brings + ownership boundary
- Consent & Disclosure — pre-purchase disclosure responsibilities