API

Reports

The same numbers your team sees in Viffy, from the same source.

Endpoints

GET/reports/summaryThe whole program over a range, by brand. Filter: brandId.

GET/campaigns/{id}/reportOne campaign: totals, a daily series, and its creators ranked (paged).

GET/reports/creator-countsOne row per creator per campaign for your payment process. Filters: brandId, campaignId.

All three take a range: preset, or from and through. See Conventions. Summary and campaign reports accept up to 366 inclusive days; creator counts have no 366-day cap.

Summary

Request and response

GET /reports/summary?preset=30d

{
  "range": { "from": "2026-08-13", "through": "2026-09-11", "timeZone": "America/Chicago", "preset": "30d" },
  "totals": {
    "activeCampaigns": 3, "campaigns": 5,
    "linkViews": 18420, "codesIssued": 2210, "verifiedRedemptions": 640,
    "redemptionRate": 0.2896,
    "estimatedCommission": 319.36, "estimatedSalesValue": 3193.60
  },
  "brands": [
    { "brand": { "id": "9a2b835d-674e-48ab-b012-a93b6407c2e8", "name": "Acme Foods" }, "campaigns": 2, "activeCampaigns": 1,
      "linkViews": 9100, "codesIssued": 1200, "verifiedRedemptions": 350, "redemptionRate": 0.2917, "estimatedCommission": 174.65 },
    { "brand": { "id": "4713e408-cf7b-43ec-a5e1-d9138b079f22", "name": "North Star Foods" }, "campaigns": 3, "activeCampaigns": 2,
      "linkViews": 9320, "codesIssued": 1010, "verifiedRedemptions": 290, "redemptionRate": 0.2871, "estimatedCommission": 144.71 }
  ]
}

The funnel is link views → codes issued → verified redemptions. Only counted redemptions are in it.
Ratios are null, not 0, when there is nothing to divide by.
Brand counts and estimated commission add up to the totals; calculate rates from the counts, not by summing or averaging brand rates.

Campaign report

GET /campaigns/{id}/report?preset=today: 200 response

{
  "range": { "from": "2026-09-11", "through": "2026-09-11", "timeZone": "America/Chicago", "preset": "today" },
  "campaign": { "id": "7c1e29a4-5b68-4d02-91f3-8a4c6e0b752d", "externalReference": "fall-launch-2026", "name": "Fall launch" },
  "brand": { "id": "9a2b835d-674e-48ab-b012-a93b6407c2e8", "name": "Acme Foods" },
  "commission": { "rate": 0.1, "estimatedUnitSalePrice": 4.99, "estimatedPerRedemption": 0.499 },
  "totals": { "linkViews": 100, "codesIssued": 20, "verifiedRedemptions": 5, "redemptionRate": 0.25, "estimatedCommission": 2.495 },
  "daily": [{ "date": "2026-09-11", "linkViews": 100, "codesIssued": 20, "verifiedRedemptions": 5 }],
  "creators": {
    "items": [{ "rank": 1, "creator": { "externalId": "hb-1042", "name": "Jane Doe" }, "active": true,
      "linkViews": 100, "codesIssued": 20, "verifiedRedemptions": 5, "conversionRate": 0.05, "estimatedCommission": 2.495 }],
    "page": 0, "pageSize": 50, "totalCount": 1
  }
}

daily includes every day in the range, including days with no activity. Dates use your organization’s reporting time zone.

creators contains a page of creators ranked by verified redemptions, with their activity and estimated commission. Use page and pageSize to read more creators; totals and daily figures still cover the whole campaign.

What the fields mean

Field	What it is
`range`	Object { from, through, timeZone, preset }. Days include both endpoints; custom dates return preset: custom.
`campaign / brand / creator`	References: campaign { id, externalReference, name }, brand { id, name }, creator { externalId, name }. externalReference can be null.
`totals.campaigns / brands[].campaigns`	Integer count of all campaigns matching the organization and brand filter, including campaigns with no activity in the selected range.
`activeCampaigns`	Integer count currently marked active whose dates overlap the range. This does not reconstruct historical campaign status.
`linkViews`	Integer link opens in the range, counted once per network origin per link per reporting day. A shared connection can undercount individual shoppers.
`codesIssued / verifiedRedemptions`	Integer shopper codes handed out and counted redemptions, each by its own date. Staff test activity is excluded; excluded redemptions are omitted from redemption totals.
`redemptionRate`	Decimal verifiedRedemptions / codesIssued, or null with no issued codes. It can exceed 1 because codes issued earlier may redeem in this range.
`creators.items[].conversionRate`	Decimal verifiedRedemptions / linkViews, or null with no views.
`creators.items[].rank / active`	Integer position in the ranked campaign list and boolean link status, independent of roster status.
`estimatedCommission`	Decimal dollars: current commission rate × current estimated unit price × counted redemptions. Calculations round once to four decimals, ties to even; displayed dollars may use two.
`totals.estimatedSalesValue`	Decimal estimated sales dollars from current unit prices and redemption counts. It is not observed basket value.
`commission / commissionRate / estimatedUnitSalePrice`	Current campaign inputs. commission also contains estimatedPerRedemption; multiplying its rounded value may not reproduce the total.
`daily[].date`	Calendar day in range.timeZone; daily entries also include integer linkViews, codesIssued, and verifiedRedemptions.

Editing a campaign’s rate or estimated price recalculates past estimates. Counts stay unchanged; retain the inputs with any export you use for reconciliation.

Creator counts

Request and response

GET /reports/creator-counts?from=2026-09-01&through=2026-09-30

{
  "range": { "from": "2026-09-01", "through": "2026-09-30", "timeZone": "America/Chicago", "preset": "custom" },
  "items": [
    {
      "creator": { "externalId": "hb-1042", "name": "Jane Doe" },
      "campaign": { "id": "7c1e29a4-5b68-4d02-91f3-8a4c6e0b752d", "externalReference": "fall-launch-2026", "name": "Fall launch" },
      "brand": { "id": "9a2b835d-674e-48ab-b012-a93b6407c2e8", "name": "Acme Foods" },
      "verifiedRedemptions": 42,
      "estimatedCommission": 20.958,
      "commissionRate": 0.1,
      "estimatedUnitSalePrice": 4.99
    }
  ],
  "page": 0, "pageSize": 50, "totalCount": 1
}

These rows match the creator-count CSV for the same dates and filters. Each creator with a campaign link appears, including creators with zero redemptions or paused links.

Read every page using page and pageSize. totalCount counts creator-campaign rows, so a creator on two campaigns appears twice.

Estimate only. Redemption counts are exact; the sale price is your estimate.