Home/Docs/Ezra Integration
Docs

Ezra Integration

How Ezra (the conversational AI partner) provisions brands and fires test conversions on Trcker. Service-key authenticated; bypasses the standard signup flow.

What it is

Ezra is the conversational front door for Trcker — brands and affiliates can launch and manage affiliate programs from Slack, iMessage, SMS, or Gmail without ever opening a dashboard. Behind the scenes, Ezra calls a small set of service-authenticated Trcker endpoints to provision and verify everything.

This page documents the Trcker side of that integration. If you're a brand using Ezra, you don't need to know any of this — Ezra handles it for you. This doc is for engineers operating the platform.

Authentication

All Ezra-callable endpoints use a single shared service key set on both sides:

` EZRA_SERVICE_KEY=<32+ char random secret> `

Set this on both: - Trcker (Vercel): so we accept Ezra's calls - Ezra (Fly.io): so it can sign outbound calls

Send via standard bearer header:

` Authorization: Bearer `

The validator uses constant-time comparison and fails closed (returns 503) if the env var is missing or shorter than 32 chars. See src/lib/auth/ezra-service-key.ts.

Endpoints

POST /api/public/brands/create

Provisions a brand on Ezra's behalf. Bypasses the free-email signup gate (Ezra-provisioned brands are vouched for by service-key auth). Idempotent on brandDomain — retrying with the same domain returns the existing brand.

Request body:

`json { "ownerEmail": "sarah@bedrockfit.com", "ownerName": "Sarah Chen", "brandName": "Bedrock Fitness", "brandDomain": "bedrockfit.com", "platform": "shopify", "aov": 85, "vertical": "fitness", "payoutPercent": 0.47 } `

platform is one of: shopify | woocommerce | bigcommerce | wix | stripe | custom. payoutPercent defaults to 0.47 (DTC standard) if omitted.

Response (201 Created):

`json { "data": { "brandId": "uuid", "brandSlug": "bedrock-fitness", "brandApiKey": "trk_...", "offerId": "uuid", "offerSlug": "default-offer", "platform": "shopify", "shopifyInstallUrl": "https://trcker.io/api/public/install/shopify/start?brand_id=...", "alreadyExisted": false } } `

shopifyInstallUrl is null for non-Shopify platforms.

POST /api/internal/test-conversion

Fires a synthetic click + conversion to verify a brand's tracking pipeline is working end-to-end. Both rows are flagged is_test=true (migration 0035) so they're excluded from every reporting query — they never pollute EPC, payouts, or partner stats.

Request body:

`json { "brandSlug": "bedrock-fitness", "offerSlug": "default-offer", "amountCents": 8500 } `

offerSlug defaults to the brand's first offer if omitted. amountCents defaults to the offer's revenueAmountCents.

Response (200 OK):

`json { "data": { "passed": true, "testRunId": "uuid", "clickId": "uuid", "clickDbId": "uuid", "conversionId": "uuid", "revenueCents": 8500, "payoutCents": 4000, "message": "Test conversion fired successfully. Tracking pipeline is live." } } `

How it works

  1. A brand asks Ezra to launch an affiliate program
  2. Ezra calls POST /api/public/brands/create with the basic brand info → receives a brand record + default offer + brand API key
  3. For Shopify brands, Ezra surfaces the returned shopifyInstallUrl to the brand as a one-tap install link
  4. After Shopify install completes (see Shopify Install), Ezra calls POST /api/internal/test-conversion to verify tracking is working
  5. On success, Ezra texts the brand: "Tracking is live."

The brand never opens a dashboard during onboarding. Trcker is the engine; Ezra is the conversation.

Test conversions are excluded from reports

Migration 0035 added is_test BOOLEAN NOT NULL DEFAULT false to both clicks and conversions. Every report query in src/lib/db/queries/reports/* filters is_test = false. Test conversions:

  • Don't count toward partner EPC
  • Don't trigger payouts to partners
  • Don't appear in attribution dashboards
  • Don't fire CAPI events to ad networks

Safe to fire as often as needed during install verification.

Operational notes

  • Brand provisioning audits via Sentry.captureMessage("Ezra brand provisioned", level: "info") — searchable in Sentry by tag route:public/brands/create
  • WorkOS Organization is created for every Ezra-provisioned brand so the brand can later log into trcker.io directly via SSO
  • Service-key rotation: change EZRA_SERVICE_KEY on both Trcker and Ezra simultaneously; existing brand API keys remain valid
  • No retry/backoff is built into the endpoint — Ezra is responsible for retrying on 5xx
← Previous
Autopilot — run your program on agents
Next →
Shopify Install