🤝 Awin Merchant Products (BYOC) — Affiliate Transactions, Promotions & Joined Programmes via Official Awin API

🔗 View on Apify Store | 🇺🇸 English | 🇧🇷 Português

Pull your own Awin affiliate data from the official Awin Publisher API — commission transactions, promotions/vouchers, and joined programmes. This is a BYOC (Bring Your Own Credentials) actor: you supply your Awin Publisher ID and API Access Token, and it authenticates as you. No scraping, no browser, no anti-bot — just clean REST calls to api.awin.com.

✨ Features

• 💸 Transactions mode — Commission history: sale amount, commission, status, click & transaction dates, advertiser
• 🎟️ Promotions mode — Vouchers, discount codes, and offers (title, code, type, validity, regions)
• 🤝 Programmes mode — Your joined advertiser partnerships with commission rates and performance fields
• 🔐 BYOC authentication — Uses your own Awin API token (Bearer auth)
• 📅 Date-range filtering — Custom startDate/endDate for transactions (defaults to the last 30 days)
• 🏷️ Status filtering — pending, approved, declined, or all
• ⚡ Pure REST — Direct calls to the official Awin API; fast, stable, no rendering overhead
• 🧭 Self-diagnosing — On missing credentials, auth errors, rate limits, or empty results, returns a clear setup guide instead of failing silently

📥 Input

Parameter	Type	Required	Default	Description
mode	string	✅	"transactions"	Extraction mode: transactions, promotions, or programmes
publisherId	string	✅	—	Your Awin Affiliate/Publisher account ID (e.g. 123456). Found in the top-right of your Awin dashboard
accessToken	string (secret)	✅	—	Your Awin API Access Token. Generate it at Awin UI → API Credentials → Create API Token
startDate	string	❌	30 days ago	Start date for transactions, YYYY-MM-DD (or ISO). Used in transactions mode
endDate	string	❌	today	End date for transactions, YYYY-MM-DD (or ISO). Used in transactions mode
status	string	❌	"all"	Transaction status filter: all, pending, approved, declined
maxItems	integer	❌	100	Ceiling on records from the single API call (1–1000 accepted; promotions cannot exceed 200)

Input Example

{
  "mode": "transactions",
  "publisherId": "123456",
  "accessToken": "YOUR_AWIN_API_TOKEN",
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "status": "approved",
  "maxItems": 200
}

📤 Output

Output fields depend on the selected mode. Every record also includes a scrapedAt ISO 8601 timestamp.

transactions mode

Field	Type	Description
id	string/number	Awin transaction ID
url	string	Transaction/click URL
advertiserId	number	Advertiser (programme) ID
advertiserName	string	Advertiser display name
clickDate	string	Date of the originating click
transactionDate	string	Date the transaction occurred
saleAmount	number	Sale value amount
commission	number	Commission amount earned
currency	string	Currency of the sale amount
commissionStatus	string	Commission state (e.g. pending, approved, declined)
paymentId	string/number	Associated payment ID
customParameters	array/object	Custom click/transaction parameters

promotions mode

Field	Type	Description
id	string/number	Promotion ID
advertiserId	number	Advertiser ID
advertiserName	string	Advertiser name
title	string	Promotion title
description	string	Promotion description
type	string	Promotion type (e.g. voucher, offer)
code	string	Voucher/discount code
url	string	Promotion landing URL
startDate	string	Promotion start date
endDate	string	Promotion end date
regions	array	Applicable regions

programmes mode

Field	Type	Description
id	number	Programme (advertiser) ID
name	string	Programme name
relationship	string	Relationship status (always joined for this mode)
regions	array	Programme regions
clickThroughRate	number	Click-through rate
conversionRate	number	Conversion rate
validationPeriod	string/number	Commission validation period
leadCommission	object/number	Lead-based commission terms
saleCommission	object/number	Sale-based commission terms

Output Example (transactions)

{
  "id": "11223344",
  "url": "https://www.awin1.com/cread.php?...",
  "advertiserId": 9999,
  "advertiserName": "Famous Brand Ltd",
  "clickDate": "2026-05-20T14:32:00",
  "transactionDate": "2026-05-20T14:35:10",
  "saleAmount": 59.90,
  "commission": 5.99,
  "currency": "EUR",
  "commissionStatus": "approved",
  "paymentId": 12345,
  "customParameters": null,
  "scrapedAt": "2026-06-06T12:00:00.000Z"
}

📋 Use Cases

• Commission reconciliation — Match Awin payouts against your own records
• Affiliate revenue dashboards — Feed pending/approved/declined commissions into BI tools
• Voucher/offer syndication — Pull active promotions and codes to publish on your sites or apps
• Programme audit — List every advertiser you've joined with commission rates and metrics
• Period reporting — Slice transactions by custom date ranges for monthly/quarterly reports
• Data warehousing — Land clean, normalized Awin records into your pipeline on a schedule

✅ Capabilities & Limits

Stated up front, so you do not pay a run to find out.

Built here: in transactions mode the date window is always sent to Awin expanded to full days and pinned to UTC (T00:00:00 to T23:59:59, timezone=UTC), regardless of your Awin account's reporting timezone. Day boundaries - and therefore daily and monthly totals - can differ from what the Awin dashboard shows for the same startDate and endDate. Each mode issues exactly one API call and slices the response to maxItems; the run log states this before the call, and warns explicitly when maxItems exceeds the 200-record promotions ceiling.

Heads up: this Actor needs credentials you provide yourself (accessToken). It cannot run without them.

Input / feature	Supported	Notes
mode — required	✅	Mode of extraction: transactions (historical commission data), promotions (vouchers, discounts, and offers), or programmes (advertiser partnerships).
publisherId — required	✅	Your Awin Affiliate/Publisher account ID (e.g. 123456). Found in the top right corner of your Awin dashboard.
accessToken — credential	⚠️ Required	Your API token / Access Token. Generate it at Awin UI -> API Credentials -> Create API Token.
startDate	✅	Start date for transactions. Required in YYYY-MM-DD format (or ISO). Defaults to 30 days ago.
endDate	✅	End date for transactions. Required in YYYY-MM-DD format (or ISO). Defaults to today.
status	✅	Filter transactions by status: all, pending, approved, declined.
Result volume (maxItems)	⚠️	Ceiling on the single API response, not a target the run works toward
Pagination	❌	One Awin API call per run in every mode; no second page is ever requested
promotions beyond 200 records	❌	The request carries pageSize 200 and page 1, so maxItems above 200 is unreachable in this mode

❓ FAQ

Q: Do I need my own Awin account and API token? A: Yes. This is a BYOC actor. Provide your Awin Publisher (Affiliate) ID and an API Access Token from Awin UI → API Credentials → Create API Token; the actor authenticates as you.

Q: Is my API token safe? A: The accessToken field is marked as secret in the input schema, so Apify stores it encrypted. It is sent only to api.awin.com over HTTPS using Bearer authentication.

Q: What's the difference between the three modes? A: transactions returns commission history, promotions returns vouchers/discounts/offers, and programmes returns the advertiser partnerships you have joined.

Q: Why did my run "succeed" but return only a diagnostic message? A: On a recoverable condition — missing publisherId/accessToken, invalid token (401), no access / wrong publisher (403), rate limit (429), or zero records — the actor pushes a single labeled setup-guide item and exits successfully. No Pay-Per-Event charge is applied on that path. Fix the issue and re-run.

Q: Will maxItems: 1000 give me 1000 records? A: No. The Actor makes one Awin API call per run and cuts the response down to maxItems — it never asks for a second page. You get whatever your account returns in that single call. In promotions mode the call is sent with pageSize 200, so 200 is the hard ceiling there and the run log says so before the call goes out.

Q: I get a rate-limit error. What now? A: The Awin API allows roughly 20 calls per minute. On a 429, wait about a minute and re-run.

Q: How far back can I pull transactions? A: Set startDate and endDate (YYYY-MM-DD). If omitted, it defaults to the last 30 days through today.

💰 Pricing

$0.005 per transaction fetched, Apify platform usage of the run is included — compute and proxy are not billed to you separately.

This actor uses Pay-Per-Event (PPE) pricing. You are charged per record actually returned:

Event	When it fires
transaction-fetched	Once per transaction returned in transactions mode
item-fetched	Once per record returned in promotions and programmes modes

No charge is applied to diagnostic/setup-guide runs (missing credentials, auth errors, rate limits, or zero results). Runs made by the portfolio owner account are never charged. For current per-event prices, see the live pricing on the Apify Store page: https://apify.com/viralanalyzer/awin-merchant-products-byoc

🔗 Related Actors

• Yahoo Finance Intelligence — Stock quotes, fundamentals & analyst ratings
• Amazon Brazil Intelligence — Product, price & review data
• Mercado Livre Scraper — Marketplace listings & pricing
• Shopify Store Intelligence — E-commerce competitive analysis

📝 Changelog

v1.0 (Current)

• ✅ Three modes: transactions, promotions, programmes (joined) via the official Awin Publisher API
• ✅ BYOC Bearer authentication with secret token storage
• ✅ Date-range and status filtering for transactions
• ✅ Normalized output per mode with scrapedAt timestamps
• ✅ Self-diagnosing setup guide on recoverable failures (succeeds without PPE charge)
• ✅ Explicit handling for 401 / 403 / 429 Awin API responses
• ✅ Pay-Per-Event billing with owner-skip (transaction-fetched / item-fetched)

---

🤝 Awin Merchant Products (BYOC) — Transações de Afiliado, Promoções & Programas via API Oficial da Awin

🇺🇸 English | 🇧🇷 Português

Extraia seus próprios dados de afiliado da Awin da API oficial de Publisher da Awin — transações de comissão, promoções/vouchers e programas dos quais você participa. Este é um actor BYOC (Bring Your Own Credentials): você fornece seu Publisher ID e Token de Acesso da API, e ele autentica como você. Sem scraping, sem navegador, sem anti-bot — apenas chamadas REST limpas para api.awin.com.

✨ Funcionalidades

• 💸 Modo Transações — Histórico de comissão: valor da venda, comissão, status, datas de clique e transação, anunciante
• 🎟️ Modo Promoções — Vouchers, códigos de desconto e ofertas (título, código, tipo, validade, regiões)
• 🤝 Modo Programas — Suas parcerias com anunciantes (joined), com taxas de comissão e campos de performance
• 🔐 Autenticação BYOC — Usa seu próprio token de API da Awin (auth Bearer)
• 📅 Filtro por período — startDate/endDate personalizados para transações (padrão: últimos 30 dias)
• 🏷️ Filtro por status — pending, approved, declined ou all
• ⚡ REST puro — Chamadas diretas à API oficial da Awin; rápido, estável, sem overhead de renderização
• 🧭 Autodiagnóstico — Em caso de credenciais ausentes, erros de auth, rate limit ou resultados vazios, retorna um guia de configuração em vez de falhar silenciosamente

📥 Entrada

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
mode	string	✅	"transactions"	Modo de extração: transactions, promotions ou programmes
publisherId	string	✅	—	Seu ID de conta Afiliado/Publisher da Awin (ex: 123456). No canto superior direito do painel Awin
accessToken	string (secreto)	✅	—	Seu Token de Acesso da API da Awin. Gere em Awin UI → API Credentials → Create API Token
startDate	string	❌	30 dias atrás	Data inicial das transações, AAAA-MM-DD (ou ISO). Usado no modo transactions
endDate	string	❌	hoje	Data final das transações, AAAA-MM-DD (ou ISO). Usado no modo transactions
status	string	❌	"all"	Filtro de status: all, pending, approved, declined
maxItems	integer	❌	100	Teto de registros da única chamada à API (1–1000 aceitos; promotions não passa de 200)

Exemplo de Entrada

{
  "mode": "transactions",
  "publisherId": "123456",
  "accessToken": "SEU_TOKEN_API_AWIN",
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "status": "approved",
  "maxItems": 200
}

📤 Saída

Os campos de saída dependem do mode selecionado. Todo registro inclui também um timestamp scrapedAt em ISO 8601.

Modo transactions

Campo	Tipo	Descrição
id	string/número	ID da transação na Awin
url	string	URL da transação/clique
advertiserId	número	ID do anunciante (programa)
advertiserName	string	Nome do anunciante
clickDate	string	Data do clique de origem
transactionDate	string	Data em que a transação ocorreu
saleAmount	número	Valor da venda
commission	número	Valor da comissão ganha
currency	string	Moeda do valor da venda
commissionStatus	string	Estado da comissão (ex: pending, approved, declined)
paymentId	string/número	ID do pagamento associado
customParameters	array/objeto	Parâmetros personalizados de clique/transação

Modo promotions

Campo	Tipo	Descrição
id	string/número	ID da promoção
advertiserId	número	ID do anunciante
advertiserName	string	Nome do anunciante
title	string	Título da promoção
description	string	Descrição da promoção
type	string	Tipo da promoção (ex: voucher, oferta)
code	string	Código de voucher/desconto
url	string	URL de destino da promoção
startDate	string	Data de início da promoção
endDate	string	Data de término da promoção
regions	array	Regiões aplicáveis

Modo programmes

Campo	Tipo	Descrição
id	número	ID do programa (anunciante)
name	string	Nome do programa
relationship	string	Status do relacionamento (sempre joined neste modo)
regions	array	Regiões do programa
clickThroughRate	número	Taxa de clique
conversionRate	número	Taxa de conversão
validationPeriod	string/número	Período de validação da comissão
leadCommission	objeto/número	Termos de comissão por lead
saleCommission	objeto/número	Termos de comissão por venda

Exemplo de Saída (transactions)

{
  "id": "11223344",
  "url": "https://www.awin1.com/cread.php?...",
  "advertiserId": 9999,
  "advertiserName": "Loja Famosa Ltda",
  "clickDate": "2026-05-20T14:32:00",
  "transactionDate": "2026-05-20T14:35:10",
  "saleAmount": 59.90,
  "commission": 5.99,
  "currency": "EUR",
  "commissionStatus": "approved",
  "paymentId": 12345,
  "customParameters": null,
  "scrapedAt": "2026-06-06T12:00:00.000Z"
}

📋 Casos de Uso

• Conciliação de comissões — Confira os repasses da Awin com seus registros
• Dashboards de receita de afiliado — Alimente comissões pending/approved/declined em ferramentas de BI
• Distribuição de vouchers/ofertas — Puxe promoções e códigos ativos para publicar em seus sites ou apps
• Auditoria de programas — Liste cada anunciante do qual você participa, com taxas de comissão e métricas
• Relatórios por período — Fatie transações por intervalos de data para relatórios mensais/trimestrais
• Data warehousing — Carregue registros Awin limpos e normalizados no seu pipeline de forma agendada

❓ Perguntas Frequentes

P: Preciso da minha própria conta e token da API da Awin? R: Sim. Este é um actor BYOC. Forneça seu Publisher (Affiliate) ID e um Token de Acesso gerado em Awin UI → API Credentials → Create API Token; o actor autentica como você.

P: Meu token da API está seguro? R: O campo accessToken é marcado como secreto no input schema, então a Apify o armazena criptografado. Ele é enviado apenas para api.awin.com via HTTPS, usando autenticação Bearer.

P: Qual a diferença entre os três modos? R: transactions retorna histórico de comissão, promotions retorna vouchers/descontos/ofertas e programmes retorna as parcerias com anunciantes das quais você participa.

P: Por que minha execução "teve sucesso" mas só retornou uma mensagem de diagnóstico? R: Numa condição recuperável — publisherId/accessToken ausente, token inválido (401), sem acesso / publisher errado (403), rate limit (429) ou zero registros — o actor envia um único item de guia de configuração e finaliza com sucesso. Nenhuma cobrança Pay-Per-Event é aplicada nesse caminho. Corrija o problema e execute novamente.

P: maxItems: 1000 me dá 1000 registros? R: Não. O Actor faz uma chamada à API da Awin por execução e corta a resposta em maxItems — nunca pede uma segunda página. Você recebe o que a sua conta devolver nessa única chamada. No modo promotions a chamada vai com pageSize 200, então 200 é o teto rígido ali, e o log avisa isso antes de a chamada sair.

P: Recebi erro de rate limit. E agora? R: A API da Awin permite cerca de 20 chamadas por minuto. Num 429, aguarde cerca de um minuto e execute novamente.

P: Até onde posso puxar transações no passado? R: Defina startDate e endDate (AAAA-MM-DD). Se omitidos, usa por padrão os últimos 30 dias até hoje.

💰 Preços

$0.005 por transação obtida, o uso de plataforma da Apify está incluído — compute e proxy não são cobrados à parte.

Este actor usa precificação Pay-Per-Event (PPE). A cobrança é por registro efetivamente retornado:

Evento	Quando dispara
transaction-fetched	Uma vez por transação retornada no modo transactions
item-fetched	Uma vez por registro retornado nos modos promotions e programmes

Nenhuma cobrança é aplicada em execuções de diagnóstico/guia de configuração (credenciais ausentes, erros de auth, rate limit ou zero resultados). Execuções feitas pela conta dona do portfólio nunca são cobradas. Para os preços por evento atuais, consulte a precificação ao vivo na página da Apify Store: https://apify.com/viralanalyzer/awin-merchant-products-byoc

🔗 Actors Relacionados

• Yahoo Finance Intelligence — Cotações, fundamentos & ratings de analistas
• Amazon Brazil Intelligence — Dados de produto, preço & avaliações
• Mercado Livre Scraper — Anúncios & preços do marketplace
• Shopify Store Intelligence — Análise competitiva de e-commerce

📝 Changelog

v1.0 (Atual)

• ✅ Três modos: transactions, promotions, programmes (joined) via API oficial de Publisher da Awin
• ✅ Autenticação BYOC Bearer com armazenamento de token secreto
• ✅ Filtros de período e status para transações
• ✅ Saída normalizada por modo com timestamps scrapedAt
• ✅ Guia de configuração autodiagnóstico em falhas recuperáveis (sucesso sem cobrança PPE)
• ✅ Tratamento explícito para respostas 401 / 403 / 429 da API Awin
• ✅ Cobrança Pay-Per-Event com owner-skip (transaction-fetched / item-fetched)