Awin.Affiliate 1.4.0

Awin.Affiliate

A lightweight, strongly typed .NET SDK for the Awin Publisher API — affiliate link generation and reports.

Small .NET SDK for the Awin Publisher API.

Maintained by GrecoLabs.

Awin.Affiliate helps affiliate bots, deal monitors, and revenue dashboards build Awin tracking deep links and pull reports (transactions, sales summary, click stats) from the Awin Publisher API.

What It Does

Installation

After the package is published to NuGet:

dotnet add package Awin.Affiliate

To build from source:

git clone https://github.com/gregojoao/awin-affiliate.git
cd awin-affiliate
dotnet restore
dotnet test
dotnet pack -c Release

The package is generated at:

src/Awin.Affiliate/bin/Release/Awin.Affiliate.<version>.nupkg

Quick Start

using Awin.Affiliate.Application;

var options = new AwinAffiliateOptions
{
    PublisherId = Environment.GetEnvironmentVariable("AWIN_PUBLISHER_ID")!
};

using var httpClient = new HttpClient();
var client = new AwinAffiliateClient(httpClient, options);

var result = await client.GenerateAffiliateLinkAsync(new AwinAffiliateLinkRequest
{
    OriginUrl = new Uri("https://www.kabum.com.br/produto/123"),
    AdvertiserId = "12345",                       // Awin advertiser id (a.k.a. awinmid)
    SubIds = new[] { "telegram", "promo-summer" } // clickref / clickref2
});

Console.WriteLine(result.AffiliateUrl);
Console.WriteLine(result.Source);     // TrackingDeepLink
Console.WriteLine(result.OriginUrl);

Configuration

You can pass credentials manually:

using Awin.Affiliate.Application;

var options = new AwinAffiliateOptions
{
    PublisherId = "your-publisher-id",
    Endpoint = AwinAffiliateOptions.DefaultEndpoint,
    TrackingEndpoint = AwinAffiliateOptions.DefaultTrackingEndpoint,
    Timeout = TimeSpan.FromSeconds(30)
};

For ASP.NET Core, Worker Services, or any app using Microsoft.Extensions.DependencyInjection, register the SDK once:

using Awin.Affiliate.Infrastructure;

builder.Services.AddAwinAffiliate(builder.Configuration);

Then configure secrets through environment variables, user secrets, Key Vault, or any other configuration provider:

{
  "Awin": {
    "Affiliate": {
      "PublisherId": "your-publisher-id",
      "Timeout": "00:00:30"
    }
  }
}

In production, prefer environment variables or a secret manager instead of committing secrets to appsettings.json.

After registration, inject the client:

using Awin.Affiliate.Application;

public sealed class DealPublisher(IAwinAffiliateClient awin)
{
    public async Task PublishAsync(string productUrl, string advertiserId)
    {
        var result = await awin.GenerateAffiliateLinkAsync(new AwinAffiliateLinkRequest
        {
            OriginUrl = new Uri(productUrl),
            AdvertiserId = advertiserId
        });

        Console.WriteLine(result.AffiliateUrl);
    }
}

You can also configure options directly in code:

using Awin.Affiliate.Infrastructure;

builder.Services.AddAwinAffiliate(options =>
{
    options.PublisherId = builder.Configuration["AWIN_PUBLISHER_ID"]!;
});

Per-call behavior lives on request objects:

Main APIs

Use IAwinAffiliateClient when credentials are registered through DI. Use AwinAffiliateClient directly when you want to provide AwinAffiliateOptions in code.

GenerateAffiliateLinkAsync

Builds an Awin tracking deep link. No HTTP call is made unless ResolveShortUrls = true.

var result = await client.GenerateAffiliateLinkAsync(new AwinAffiliateLinkRequest
{
    OriginUrl = new Uri(productUrl),
    AdvertiserId = "12345",
    SubIds = new[] { "telegram" }
});

// result.AffiliateUrl =
// https://www.awin1.com/cread.php?awinmid=12345&awinaffid=987654&ued=<encoded>&clickref=telegram

ResolveAwinUrlAsync

Follows redirects for a short URL and returns the final destination. Returns the input URL unchanged on network failure.

Uri resolved = await client.ResolveAwinUrlAsync(new Uri(shortUrl));

Affiliate reports

Reports live in Awin.Affiliate.Reports.Application. They have a separate options type and DI extension so callers that only need link generation don't have to provide an access token.

using Awin.Affiliate.Reports.Configuration;
using Awin.Affiliate.Reports.Application;

var options = new AwinAffiliateReportsOptions
{
    PublisherId = Environment.GetEnvironmentVariable("AWIN_PUBLISHER_ID")!,
    AccessToken = Environment.GetEnvironmentVariable("AWIN_ACCESS_TOKEN")!,
};

using var httpClient = new HttpClient();
IAwinAffiliateReportsClient reports = new AwinAffiliateReportsClient(httpClient, options);

Validate credentials explicitly before running scheduled jobs, onboarding a publisher account, or wiring integrations that need a stable "credentials rejected" signal:

using Awin.Affiliate.Infrastructure;

try
{
    await reports.ValidateCredentialsAsync();
}
catch (AwinAffiliateAuthException ex) when (ex.IsCredentialError)
{
    Console.WriteLine($"{ex.Platform}: {ex.Kind}");
    Console.WriteLine(ex.ProviderErrorCode);
    Console.WriteLine(ex.ProviderMessage);
}

Or with DI:

using Awin.Affiliate.Reports.DependencyInjection;

builder.Services.AddAwinAffiliateReports(builder.Configuration);

Reports configuration section:

{
  "Awin": {
    "Reports": {
      "PublisherId": "987654",
      "AccessToken": "your-oauth2-token",
      "DateType": "transaction",
      "Timezone": "Europe/London"
    }
  }
}

ListConversionsAsync

using Awin.Affiliate.Reports.Application.Requests;

var page = await reports.ListConversionsAsync(new ListAwinConversionsRequest
{
    PeriodStart = DateOnly.FromDateTime(DateTime.UtcNow.AddDays(-7)),
    PeriodEnd = DateOnly.FromDateTime(DateTime.UtcNow),
    Status = AwinConversionStatusFilter.Approved,
    AdvertiserIds = new[] { "12345" } // optional
});

foreach (var tx in page.Items)
{
    Console.WriteLine($"{tx.AdvertiserName} — {tx.CommissionAmount} ({tx.Status})");
}

ValidateCredentialsAsync

Calls the lightweight programmes endpoint (GET /publishers/{publisherId}/programmes/) to verify that the configured PublisherId and AccessToken are accepted by Awin.

await reports.ValidateCredentialsAsync();

On success, the method returns normally. On HTTP 401/403, it propagates AwinAffiliateAuthException with a stable credential signal:

HTTP 429 still throws AwinAffiliateRateLimitException; 5xx, network, and timeout failures stay under AwinAffiliateApiException rather than being treated as credential failures.

GetSalesSummaryAsync

var summary = await reports.GetSalesSummaryAsync(new AwinSalesSummaryRequest
{
    PeriodStart = new DateOnly(2026, 5, 1),
    PeriodEnd = new DateOnly(2026, 5, 31)
});

Console.WriteLine($"Conversions: {summary.Conversions}");
Console.WriteLine($"Gross:       {summary.GrossRevenue}");
Console.WriteLine($"Commission:  {summary.Commission}");
Console.WriteLine($"Avg rate:    {summary.AvgCommissionRate:F2}%");
foreach (var advertiser in summary.TopAdvertisers)
{
    Console.WriteLine($"  {advertiser.AdvertiserName}: {advertiser.Commission}");
}

AwinSalesSummary carries:

GetConversionAsync

Searches the last 31 days for a transaction matching the given order reference; throws AwinAffiliateNotFoundException when nothing matches.

var tx = await reports.GetConversionAsync("ORDER-42");

ListAdvertisersAsync

Returns every programme (advertiser) accessible to the configured publisher.

var advertisers = await reports.ListAdvertisersAsync();

GetClickStatsAsync and GetGeneratedLinkUsageAsync

GetClickStatsAsync reads the advertiser performance report (/publishers/{id}/reports/advertiser/); GetGeneratedLinkUsageAsync reads the creative report (/publishers/{id}/reports/creative/), which is scoped to registered creatives. When the account lacks access, or Awin rejects the input, the SDK returns Supported = false with a populated UnsupportedReason instead of throwing.

Why not the creative report for clicks? It only counts registered creatives. Publishers that build deep links on the fly (cread.php?ued=…) get 200 [] there, while the advertiser report returns their traffic. Verified against a live BR account: creative → [], advertiser → {"advertiserId":17729,"clicks":41} for the same window.

Region is required by both reports — omitting it answers HTTP 400 invalid region code list. It has no default (a hardcoded one would answer 200 [] for every publisher outside it — zero clicks that look like a valid answer), and the report calls throw InvalidOperationException when it is empty. It accepts a comma-separated list (GB,IE). Note also that DateType only accepts transaction or validation: Awin rejects click.

A region that is merely wrong (say GB on a BR account) still answers 200 []. If you need to tell "no traffic" from "wrong region", cross-check with ListAdvertisersAsync: programmes present while the advertiser report comes back empty means the region is off.

Clicks come back both aggregated and per advertiser, since the report returns one row per store:

stats.Clicks;                       // 50 — total across advertisers
stats.PerAdvertiser[0].AdvertiserId;   // "17729"
stats.PerAdvertiser[0].AdvertiserName; // "Kabum BR"
stats.PerAdvertiser[0].Clicks;         // 41

Clicks may also arrive on rows with no advertiser. Those are counted in Clicks but absent from PerAdvertiser, so the invariant is Clicks == sum(PerAdvertiser.Clicks) + UnattributedClicks. A non-zero UnattributedClicks means the report shape changed and per-advertiser mirroring is losing rows.

Neither report supports a daily breakdown: the response aggregates the whole window. To get a value per day, call it once per day (PeriodStart == PeriodEnd) — the daily figures sum exactly to the aggregate.

⚠️ The day is cut in Timezone, which defaults to Europe/London. Going day by day without matching your own day boundary silently reshuffles the series: the window total stays right and the individual days move. Measured on one real account, same week, same total of 41 clicks:

UTC               4  2  9  7   9  9  1
Europe/London     4  1  9  6  11  9  1
America/Sao_Paulo 3  4  8  6  12  6  2

FormatStart/FormatEnd build T00:00:00/T23:59:59 that Awin interprets in that timezone, so the DateOnly you compute and the Timezone you pass must come from the same clock — otherwise you store an off-by-one day.

var clicks = await reports.GetClickStatsAsync(new AwinClickStatsRequest
{
    PeriodStart = new DateOnly(2026, 5, 1),
    PeriodEnd = new DateOnly(2026, 5, 31)
});

var usage = await reports.GetGeneratedLinkUsageAsync(new AwinGeneratedLinkUsageRequest
{
    PeriodStart = new DateOnly(2026, 5, 1),
    PeriodEnd = new DateOnly(2026, 5, 31),
    LinkId = "creative-id-or-link-id"
});

Methods and exceptions

Exception hierarchy:

AwinAffiliateException
├── AwinAffiliateApiException       (4xx/5xx, malformed body)
├── AwinAffiliateAuthException      (401/403)
├── AwinAffiliateRateLimitException (429)
├── AwinAffiliateNotFoundException  (missing resource)
└── AwinAffiliateUnsupportedException (feature not available)

AwinAffiliateAuthException is the programmatic credential failure signal for integrations such as Awin-backed merchant adapters:

The transport sanitizes authentication response bodies before attaching them to the exception, including token-like fields and bearer-token text.

Limits and conventions

• 31-day window: Awin's transactions/ and reports/aggregated/ endpoints reject windows larger than 31 days. The SDK validates this client-side and throws ArgumentException early.
• Time zone: defaults to Europe/London (Awin's account default). Override via AwinAffiliateReportsOptions.Timezone.
• Token lifetime: OAuth2 tokens issued via Toolbox > API credentials are long-lived and do not need refresh. The SDK simply sends them as Authorization: Bearer {token}.
• Rate limit: Awin documents a soft limit around 20 requests/second per publisher. The transport retries once on transient 5xx and timeout errors with exponential backoff; 429 responses surface as AwinAffiliateRateLimitException (no implicit retry — back off and retry yourself).
• Sub-ids: Awin honours clickref and clickref2. Sub-ids beyond the first two are silently dropped.
• Currency: every monetary value flows through the Money value object ({ Amount, Currency }). Aggregations refuse to combine mismatched currencies.

Authentication

1. Sign in to https://ui.awin.com.
2. Open Toolbox > API credentials.
3. Click Create OAuth2 token.
4. Store the token in a secret manager and expose it as AwinAffiliateReportsOptions.AccessToken.

The link client (AwinAffiliateClient) does not need a token — Awin tracking deep links are built client-side.

GenerateAffiliateLinkAsync intentionally does not validate credentials over the network. If your application needs to confirm that an Awin AccessToken is valid, call IAwinAffiliateReportsClient.ValidateCredentialsAsync explicitly.

Architecture

The SDK is organized with a small DDD-inspired structure:

Public namespaces follow the physical project structure:

• Awin.Affiliate.Application — link client, options, requests, results
• Awin.Affiliate.Domain — value objects
• Awin.Affiliate.Infrastructure — DI registration, exceptions, defaults
• Awin.Affiliate.Reports.Application — reports client, requests
• Awin.Affiliate.Reports.Configuration — reports options
• Awin.Affiliate.Reports.Domain — typed reports models
• Awin.Affiliate.Reports.DependencyInjection — AddAwinAffiliateReports

Returned Data

AwinAffiliateLinkResult contains:

AwinConversion contains:

Supported URL formats

The SDK accepts any HTTP/HTTPS URL as the affiliate destination. With ResolveShortUrls = true, the SDK first follows redirects on the input — handy for short URLs such as https://s.click.partner.test/abc.

var resolved = await client.ResolveAwinUrlAsync(new Uri("https://s.click.test/abc"));

The cread.php link itself works on every Awin endpoint that uses the awin1.com tracking infrastructure (www.awin1.com, awin.com, regional aliases).

Development

dotnet restore
dotnet test
dotnet pack -c Release

Publishing

Before publishing a new NuGet version:

1. Update <Version> and <PackageReleaseNotes> in src/Awin.Affiliate/Awin.Affiliate.csproj.
2. Run the validation:

dotnet test
dotnet pack -c Release

3. Push the package:

dotnet nuget push src/Awin.Affiliate/bin/Release/Awin.Affiliate.*.nupkg --api-key "$NUGET_API_KEY" --source https://api.nuget.org/v3/index.json

See PUBLISHING.md for the full release checklist.

License

This project is licensed under the MIT License. See LICENSE for details.