Developer & partner docs

This section is for partner engineers whose systems talk to the Freeq Growth Network: a commerce platform pushing orders, a partner backend polling analytics, or a…

This section is for partner engineers whose systems talk to the Freeq Growth Network: a commerce platform pushing orders, a partner backend polling analytics, or a partner frontend calling the API on behalf of its users.

If you are a brand or a creator and want to know how the product behaves, start with the user docs instead, for example How credit is decided. The user docs describe what happens. These pages describe how it is built and what contract you can rely on.

Product name vs code name. The product is called The Freeq Growth Network. The codebase, many identifiers, request headers and log lines still use the original internal name UAM (User Acquisition Marketplace). Wherever you see uam in a parameter, header or id (for example uam_click), it belongs to the Freeq Growth Network.

​

The system in 30 seconds

The Freeq Growth Network is an affiliate platform. Brands (advertisers) fund campaigns. Creators (publishers) share personal links. When a shopper buys after clicking a link, the platform decides which click earned the sale, holds the commission for a safety period, then releases it to the creator, who withdraws it to a bank account.

Creator's link ──► /go redirect ──► brand's store ──► order event
                       │                                   │
                       ▼                                   ▼
                 click recorded                attribution (last click wins)
                 (nothing on-chain)                        │
                                                           ▼
                                        on-chain attribution record
                                                           │
                                                           ▼
                                  escrow hold ──► ledger ──► Stripe payout

Four facts carry most of the weight:

1. One backend. A single NestJS service serves the whole API, the public /go redirect, the partner endpoints and the real-time WebSocket.
2. Last click wins. The most recent eligible click before a purchase earns the commission. See Attribution engine.
3. Attribution is on-chain; money is not. A smart contract records clicks that converted, refunds and settlements as an audit trail. Funds move through Stripe and an internal double-entry ledger. See Money path and Smart contracts.
4. Stores plug in through one contract. Shopify is the main integration; other commerce platforms connect through the same provider interface. See Commerce providers.

​

What is in this section

Page	Read it when you want to…
Architecture	Understand the shape of the backend, the request path, and the names in the code that mislead.
Attribution engine	Know exactly how a click becomes credit for a sale, and why an order was not credited.
Commerce providers	Connect a new store platform, or understand what Shopify and the partner integrations support.
Money path	Follow a commission from campaign funding to creator payout, including refunds and chargebacks.
Partner analytics API	Poll your referral program’s performance from your own backend.
Publisher embed guide	Put creator links on a website or app and keep tracking intact.
Smart contracts	Read the on-chain record, and know what is deliberately not on-chain.
Terminology map	Translate between the words in the UI, the API, the contract and the database.

​

Start here by role

• Connecting a store platform (a cart or marketplace that is not Shopify): read Commerce providers, then Attribution engine section 4 and Money path.
• Reporting on a referral program from your backend: read Partner analytics API.
• Building a partner frontend where your users sign in with your own identity provider: read Architecture, then use the Swagger reference.
• Placing creator links on a site or in an app: read Publisher embed guide.

​

How to use the API reference

These pages explain behaviour and contracts. They deliberately do not list every route, field or setting, because those lists go stale quickly. The live, complete API reference is the Swagger UI that the backend serves at /api. Treat Swagger as the source of truth for request and response fields, and these pages as the source of truth for meaning.

Three request surfaces exist, and they authenticate differently:

Surface	Path prefix	Who calls it	Auth
Application API	/api/...	Browser apps (the Freeq Growth Network web app, partner frontends)	Clerk session token as Authorization: Bearer
Public redirect	/go/...	Shoppers clicking a creator link	None
Partner wire	/partner/...	Partner backends (server to server)	HMAC signature for pushes, bearer key for reads

Note that /go and /partner are served without the /api prefix. That is intentional: those URLs are a published contract.

​

Conventions used in these pages

• “Brand” and “advertiser” mean the same party. “Creator” and “publisher” mean the same party. The Terminology map has the full table, including the contract’s own words (“buyer” and “seller”).
• Money amounts on the wire are exact decimal strings (for example "12.34"), never JSON numbers. Internally they are integer minor units (cents).
• Timestamps are ISO-8601 in UTC unless a page says otherwise.
• Ids that look like campaign_<uuid> or clk_<uuid> are opaque strings. Do not parse them.
• Path parameters in examples use {braces}; placeholders in URLs use <angle brackets>.