Skip to content

AWIN

AWIN connects Vectis to the Awin affiliate network so merchants can run their Awin program alongside the native affiliate module. Publishers stay on Awin's side — the extension pulls transactions and publisher performance reports over Awin's REST API for unified reporting inside the admin, next to Vectis-native affiliate attributions.

At a glance
Extension id awin
Category affiliate
Version 0.1.0
Provides Admin GraphQL queries (awinConnectivity, awinTransactions, awinPublisherReport)
External account Awin advertiser account with an API token

What It Provides

Three admin-only GraphQL queries, contributed through the extension GraphQL registry surface:

  • awinConnectivity — connection check; calls Awin's programme-details endpoint and returns connected, the advertiser id, and an error message on failure.
  • awinTransactions(dateFrom, dateTo, status) — transactions attributed to your advertiser account in the window, with publisher id, status, commission status, order reference, commission and sale amounts, currency, and click / transaction / validation dates. status optionally filters on pending | approved | declined.
  • awinPublisherReport(dateFrom, dateTo) — aggregated per-publisher performance: impressions, clicks, conversions, sale amount, commission amount.

The surface is read-only — the extension exposes no mutations, and results are not persisted in the Vectis database; the admin renders them live. The Reports > Affiliates page (/reports/affiliates) shows the connectivity indicator and the Awin data alongside native affiliate reporting — see Affiliates.

Setup

  1. Enable AWIN for your channel under Settings > Extensions and open its configuration.
  2. Enter your Advertiser ID (the numeric Awin advertiser account id) and API Token, generated under My Account > API Credentials in the Awin UI. The token is stored encrypted and never exposed to the browser.
  3. Open Reports > Affiliates — the page shows a connection indicator backed by awinConnectivity (a live call to Awin's programme-details endpoint) and surfaces the error message when credentials don't work.

Configuration Reference

Key Type Required Secret Description
advertiser_id string Yes No Your numeric Awin advertiser account id.
api_token string Yes Yes Generate under My Account → API Credentials in the Awin UI. Stored encrypted; never exposed to the browser.
region string No No Two-letter region code — US, UK, EU, etc. Default US.
sync_enabled boolean No No Enable nightly transaction sync. Default true.
sync_window_days number No No Nightly syncs re-fetch transactions created in the last N days so status changes (approve / decline) flow back. Default 7.

Secret fields are stored Fernet-encrypted and masked in the admin.

No scheduled sync exists yet

Despite the sync_enabled / sync_window_days fields, the extension registers no Temporal workflows or schedules — nothing copies Awin transactions into the Vectis database on a timer. All Awin data is fetched live, per admin query; the resolver code notes a nightly caching workflow as a future step once volume justifies it. The region field is likewise not read by the current resolvers — the publisher report is requested with the client's default region (US).

Permissions

  • affiliate.manage — required by all three queries; unauthenticated or unauthorized callers are rejected.

Permissions are upserted at boot from the manifest; assigning them to roles is currently a manual step.

Operational Notes

  • Endpoints used — GET /advertisers/{advertiser_id}/transactions/ (window bounded by startDate/endDate, called with dateType=transaction and timezone=UTC), GET /advertisers/{advertiser_id}/reports/publisher, and GET /advertisers/{advertiser_id}/programmedetails for the connectivity check — all against https://api.awin.com with Authorization: Bearer auth and a 15-second timeout.
  • Failures degrade to empty results — transaction/report fetch errors are logged as warnings and the queries return empty lists; the connectivity query returns connected: false with the error message truncated to 200 characters.
  • Single-channel config resolution — the resolvers read the first enabled AWIN channel-extension row across any channel; per-channel Awin accounts are noted in-code as backlog.

Source: ext_awin/ (extension.py, client.py, resolvers.py) — in the enterprise-extensions repo.