Engineering · Platform entity schema
Affiliate marketing network platform data model
Updated August 11, 2026 · ~12 min read
Search results for “affiliate marketing network platform data model entities schema” often describe click-tracking ledgers — affiliates, clicks, conversions, payouts. Feedico implements a different but equally common platform pattern: multi-network catalogue aggregation. This page documents the entity model behind the unified affiliate API — Account, Integration, Provider, Firm, Coupon, optional Product rows, sync snapshots, and webhook deliveries — so architects, data engineers, and AI agents can reason about the schema before wiring ETL or RAG pipelines.
Catalogue aggregation vs click-tracking schemas
Both are valid “affiliate platform” data models — they solve different problems. Tracking platforms record referral traffic and commission math; aggregation platforms normalize merchant programmes and promotions from CJ, Awin, Impact, and peers into one JSON contract your product consumes.
| Entity | Click-tracking platform | Feedico (catalogue API) |
|---|---|---|
| Affiliate / Publisher | Core identity | Account (tenant) |
| Campaign / Offer | Tracked link config | Coupon + Firm |
| Click | Immutable event | Not modeled (your product owns attribution) |
| Conversion | Commission trigger | Not modeled |
| Payout / Settlement | Financial ledger | Not modeled |
| Merchant programme | Metadata on offer | Firm (first-class row) |
| Network integration | Postback URL config | Integration + Provider |
If you operate both surfaces — a deals site plus internal attribution — treat Feedico as the catalogue source of truth and keep clicks and conversions in your tracker or network reporting. See the unified affiliate API pillar for product positioning.
Entity catalog
These are the platform entities exposed (directly or indirectly) through customer APIs and dashboard integrations. Internal admin tables are omitted — this is the publisher-facing ontology.
| Entity | Role | Natural key | Surface |
|---|---|---|---|
| Account (tenant) | Publisher customer, API token, plan quotas, connected integrations | appUserId | Implicit via Bearer token on /api/v1/me/* |
| Integration | Authorized connection to one affiliate network (credentials + sync state) | (accountId, provider) | Dashboard → Integrations |
| Provider | Upstream network slug attached to every normalized row | provider slug | cj_affiliate, awin_affiliate, impact_com, … |
| Firm | Merchant / programme you are approved to promote | (provider, externalMerchantKey) | POST /api/v1/me/networks |
| Coupon | Coded promo, percentage title, or tracked link offer | (provider, externalCouponId) | POST /api/v1/me/coupons |
| Product | Optional SKU/catalog rows when product feeds are synced | (provider, externalProductId) | Catalog / product list APIs |
| Product list | Customer-defined filter over synced products for a property | listId | Dashboard catalog lists |
| Sync snapshot | Point-in-time upstream entity cache (e.g. Awin programme snapshots) | provider + entity type + snapshot id | Internal sync layer |
| Webhook delivery | Outbound affiliate.delta (or related) event to your endpoint | eventId / delivery id | Webhook subscription settings |
Relationships & entity diagram
An Account owns many Integrations (one per connected network). Each Integration writes Firms and Coupons into tenant-scoped tables during sync. Coupons always reference a parent Firm via networkId. Product rows and Product lists are optional when catalog feeds are enabled. Webhook subscriptions emit delta events when eligible plans expose them.
Core entity relationships (catalogue aggregation)
Firm & coupon JSON shapes
Customer list endpoints return these normalized objects regardless of upstream network. Field-by-field CJ / Awin / Impact mapping lives in the schema normalization deep dive.
{
"id": "88341",
"displayName": "Example Retailer EU",
"provider": "awin_affiliate",
"externalMerchantKey": "12345",
"merchantWebsiteUrl": "https://example-retailer.eu",
"status": "active",
"couponCount": 12,
"lastSyncedAt": "2026-08-10T18:04:00.000Z",
"extra": { /* upstream programme fields */ }
}{
"id": "1849201",
"networkId": "88341",
"networkName": "Example Retailer EU",
"provider": "awin_affiliate",
"externalMerchantKey": "12345",
"externalCouponId": "promo-998877",
"code": "SPRING15",
"title": "15% off sitewide",
"startsAt": "2026-03-01T00:00:00.000Z",
"endsAt": "2026-06-30T23:59:59.000Z",
"offerUrl": "https://…/tracked-offer",
"status": "active",
"extra": { /* voucher type, region flags, native enums */ }
}Dedup keys & lifecycle
- Firms: upsert on
(provider, externalMerchantKey) - Coupons: upsert on
(provider, externalCouponId)within the tenant - Join:
coupon.networkId → firm.id - Soft delete: rows missing from the latest sync pass flip to
status: inactive— warehouses archive instead of hard-deleting history - Provider filter: every list request can scope to one upstream network via the
providerslug
Sync pipeline & webhooks
Scheduled sync jobs pull advertiser programmes and promotions using dashboard credentials. Adapters map upstream payloads into Firm and Coupon rows. Some networks (notably Awin) also maintain entity snapshots for programme metadata between full sync passes. For near-real-time updates, pair batch ETL with webhook delta sync when your plan exposes affiliate.delta events. Reference worker patterns are in the coupon warehouse ETL guide.
OpenAPI & machine-readable schema
The entity model above maps to the customer REST contract documented in openapi-customer.yaml and the interactive explorer linked from REST API (product). Import the spec into Postman or codegen tools to generate typed clients against Firm and Coupon list endpoints.
Frequently asked questions
- What entities does an affiliate marketing network platform need?
- It depends on the product surface. Click-tracking platforms model Affiliates, Clicks, Conversions, and Payouts. Feedico models catalogue aggregation: Account (tenant), Integration (network credentials), Provider (upstream slug), Firm (merchant/programme), Coupon (promo or link offer), optional Product rows, Sync snapshots, and Webhook deliveries — because publishers consume normalized merchant and coupon JSON, not commission ledgers.
- How do Firm and Coupon relate in Feedico's schema?
- Every Coupon references a Firm via networkId (the internal firm row id). Firms deduplicate on (provider, externalMerchantKey); coupons on (provider, externalCouponId). One firm can expose many coupons; coupons inherit networkName and merchant context from the parent firm row.
- Is this the same as an affiliate tracking data model?
- No. Generic affiliate tracker schemas center on referral links, click ids, conversion postbacks, and payout batches. Feedico is a multi-network aggregation layer: sync upstream programme and promotion catalogues, normalize field names, and expose one REST contract — your product still owns attribution and checkout if you run a tracker separately.
- Where do network-native fields live?
- Top-level customer API fields are stable camelCase (provider, externalMerchantKey, code, startsAt, etc.). Upstream-only enums, regional flags, and vendor-specific metadata are preserved in an extra JSON object on each row so warehouses can promote fields later without re-syncing history.
- What are the primary keys for warehouse upserts?
- Use composite natural keys: (provider, externalMerchantKey) for firms and (provider, externalCouponId) for coupons, scoped to your tenant. Feedico id is a stable internal numeric string for CMS foreign keys; external keys track upstream identity across sync runs.
- Where should I read field-by-field CJ/Awin/Impact mapping?
- This page is the platform entity overview. For per-network column mapping, provider tags, pagination normalization, and the extra JSON escape hatch, read the schema normalization deep dive linked below.
You need programme approval and compliant use at each affiliate network. Feedico provides the integration layer - not a substitute for network terms.