🛒 Rakuten Advertising API — Merchants, Coupons & Products (BYOC)

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

Query the Rakuten Advertising Publisher API (api.linksynergy.com) for affiliate merchants, active coupons, and product search results. BYOC (Bring Your Own Credentials) — you bring your free Rakuten publisher credentials, the Actor handles the OAuth exchange, the XML parsing and the JSON normalization. Official API, so no anti-bot layer and no proxy bill.

One run calls one endpoint and writes flat JSON records to the dataset. The exact field list per queryType is in Output — read it before you pay for a run.

✨ What each run gives you

• 3 query types — productSearch (products across merchants), coupons (active deals), advertisers (merchants you can join)
• Dual auth — OAuth client_credentials grant, or a pre-generated access token from the Rakuten Developer Portal
• XML → JSON — the raw Rakuten XML is parsed with a regex extractor, no lxml / xml2js dependency
• 5 regional networks via the networkId input — 1 US, 3 UK, 7 Australia, 9 Brazil, 14 Germany
• Diagnostic item instead of a FAILED run — bad credentials, an expired token or zero matches produce one labeled setup_status record explaining what to change, and the run still ends SUCCEEDED with no PPE charge
• Owner-skip — internal runs by the Actor owner bypass the PPE charge

🔑 BYOC setup (one-time, free)

1. Sign up at https://developers.rakutenadvertising.com (or use your existing Publisher account)
2. Applications → Create New App → copy Client ID + Client Secret
3. Find your Site ID in your Rakuten Advertising account (~7-digit number)
4. Pick an auth path:
   • Path A (OAuth): fill clientId + clientSecret + siteId. The Actor posts grant_type=client_credentials&scope=<siteId> to https://api.linksynergy.com/token and uses the returned bearer.
   • Path B (pre-generated token): in the Developer Portal click "Generate Token" → paste the value into accessToken. OAuth is skipped entirely. Use this when Path A returns invalid_client.

Rakuten enforces its own quotas on your publisher account. This Actor sends one API request per run, so a run costs you one call against that quota.

📥 Input

Parameter	Type	Required	Default	Description
clientId	string (secret)	Path A	—	OAuth Client ID from Applications
clientSecret	string (secret)	Path A	—	OAuth Client Secret
siteId	string	Path A	—	Publisher Site ID (~7 digits), used as the OAuth scope
accessToken	string (secret)	Path B	—	Pre-generated token; when set, OAuth is skipped and clientId/clientSecret/siteId are not needed
queryType	enum	Yes	productSearch	productSearch / coupons / advertisers
keyword	string	No	""	productSearch → product name; advertisers → merchant name; coupons → offer text
advertiserId	string	No	""	Restrict to one merchant. productSearch sends it as mid, coupons as advertiserid. Ignored by advertisers.
networkId	enum	No	1	1 US, 3 UK, 7 Australia, 9 Brazil, 14 Germany. Used by coupons and advertisers.
maxResults	integer	No	25	1–500. Caps the records written to the dataset.
proxyConfiguration	object	No	{"useApifyProxy": false}	Not needed — the Rakuten API gates on the token, not on your IP

There is no category input. Category arrives as output (category on products, categories on coupons and advertisers).

Example input (Path B — pre-generated token, simpler)

{
  "accessToken": "your-token-from-rakuten-portal",
  "queryType": "productSearch",
  "keyword": "running shoes",
  "maxResults": 50
}

Example input (Path A — OAuth flow)

{
  "clientId": "your-rakuten-client-id",
  "clientSecret": "your-rakuten-client-secret",
  "siteId": "4703080",
  "queryType": "coupons",
  "keyword": "fashion",
  "networkId": "1",
  "maxResults": 100
}

📤 Output

Every record carries queryType, networkId and scrapedAt, so you can merge datasets from several runs and still tell them apart. Field names below are exactly what the Actor writes; the values are placeholders.

queryType=productSearch records

currency is a hard-coded "USD" literal, not a value read from the Rakuten XML — see Capabilities & Limits.

{
  "productName": "Air Zoom Pegasus - Running Shoe",
  "sku": "PEGASUS-US-10",
  "merchantName": "Example Sportswear US",
  "merchantId": "39247",
  "price": 129.99,
  "salePrice": null,
  "currency": "USD",
  "category": "Athletic Shoes",
  "description": "Short description taken from the advertiser feed",
  "productUrl": "https://click.linksynergy.com/deeplink?id=...",
  "imageUrl": "https://images.example-merchant.com/pegasus.jpg",
  "upc": "091202394857",
  "queryType": "productSearch",
  "networkId": "1",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

price and salePrice are numbers (null when Rakuten sends nothing parseable). sku falls back to the feed's link id when the advertiser omits a SKU.

queryType=coupons records

{
  "couponCode": "RUN20",
  "offerDescription": "20% off running shoes",
  "offerStartDate": "2026-05-01",
  "offerEndDate": "2026-05-31",
  "merchantName": "Example Sportswear US",
  "merchantId": "39247",
  "categories": "Apparel",
  "promotionTypes": "Percentage Off",
  "clickUrl": "https://click.linksynergy.com/fs-bin/click?id=...",
  "queryType": "coupons",
  "networkId": "1",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

categories and promotionTypes are strings, whitespace-collapsed straight from the XML — not arrays. Split them yourself if your pipeline needs a list.

queryType=advertisers records

{
  "merchantId": "39247",
  "merchantName": "Example Sportswear US",
  "applicationStatus": "approved",
  "categories": "Apparel",
  "networks": "1",
  "offer": "Offer text as returned by the advertiser search endpoint",
  "queryType": "advertisers",
  "networkId": "1",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

applicationStatus tells you whether your publisher account can already send traffic to that merchant.

Diagnostic records

When something is off, the Actor writes a single labeled record and exits SUCCEEDED without charging PPE. Two shapes exist.

Missing credentials:

{
  "setup_status": "CREDENTIALS_REQUIRED",
  "message": "Rakuten Affiliate API access requires clientId, clientSecret, siteId OR a pre-generated accessToken. Please follow the instructions to set them up.",
  "instructions": ["1. Log in or sign up at https://developers.rakutenadvertising.com/", "..."],
  "platform": "rakuten",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

OAuth failure, API error (401 / endpoint not enabled), invalid queryType, or zero parsed records:

{
  "setup_status": "DIAGNOSTIC_GUIDE",
  "_dataQuality": "diagnostic",
  "message": "[DIAGNÓSTICO] Zero items extracted from Rakuten advertisers ...",
  "potential_causes": ["wrong networkId (1=US, 3=UK, 7=AU, 9=BR, 14=DE)", "..."],
  "remediations": ["try queryType=advertisers first to list merchants you can join", "..."],
  "queryType": "advertisers",
  "networkId": "1",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

Filter on _dataQuality == "diagnostic" or on the presence of setup_status to keep these out of your production tables.

✅ Capabilities & Limits

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

Hard-coded currency: in queryType=productSearch the currency field is the literal string USD, not a value read from the Rakuten XML — every product record is stamped USD regardless of merchant or network. Treat price and salePrice as raw numbers from the advertiser feed and confirm the currency out of band before using them for price comparison.

No pagination loop: the Actor performs a single HTTP request per run and then truncates the parsed blocks to maxResults. For productSearch it sends max=maxResults, for coupons it sends resultsperpage=maxResults, and for advertisers it sends no size parameter at all — you get whatever that one response contains. There is no offset/page cursor, so a run cannot return more than one API page no matter how high maxResults goes. To sweep a large catalog, schedule several runs with different keyword or advertiserId values.

Records with no name are dropped: a parsed block that has no merchantName, no productName and no offerDescription is skipped before pushData, so the item count can be lower than the block count in the log.

Heads up: this Actor needs credentials you provide yourself (clientId + clientSecret + siteId, or accessToken). It cannot run without them.

Input / feature	Supported	Notes
queryType	✅	Picks the endpoint: productsearch/1.0, coupon/1.0 or advertisersearch/1.0
keyword	✅	Mapped to keyword (productSearch, coupons) or merchantname (advertisers)
advertiserId	✅	mid for productSearch, advertiserid for coupons; the advertisers endpoint ignores it
networkId	✅	Applied to coupons and advertisers; productSearch searches the network tied to your token
siteId	✅	Used as the OAuth scope on Path A; not sent on Path B
maxResults	⚠️	Caps the dataset, but cannot exceed one API page (no pagination loop)
currency in output	⚠️	Fixed "USD" literal for productSearch; absent from coupons and advertisers records
categories / promotionTypes	⚠️	Delivered as plain strings, not arrays
Proxy	⚠️	Configurable, but the Rakuten API authenticates by token; the setting only matters if your own network blocks api.linksynergy.com
clientId / clientSecret / accessToken	🔑	Your own credentials, marked isSecret so Apify masks them in logs

💰 Pricing

$0.005 per record written (item-scraped), Apify platform usage of the run is included — you are not billed separately for compute or proxy.

Pay-per-event (PPE): charged per record written. The diagnostic paths (missing credentials, OAuth failure, API error, invalid queryType, zero records) exit before the charge call, so a run that returns no real data costs nothing. Owner runs skip the charge as well.

🚀 Use cases

• Affiliate program discovery — run queryType=advertisers to list merchants and read applicationStatus before applying
• Coupon aggregation — feed a deals page with couponCode, offerDescription, offerEndDate and clickUrl
• Product catalog import — seed a comparison site with productName, price, imageUrl, productUrl and upc
• Merchant mapping — join merchantId across coupons and products to build one merchant table

⚠️ Common errors

The Actor turns each of these into a dataset record instead of a FAILED run, so the message reaches you in the dataset and in the log.

Log message	Cause	Fix
[OAUTH] Rakuten token endpoint returned 401	Client ID/Secret revoked, or siteId is not in scope for that app	Recheck the app in the Developer Portal, or switch to Path B and paste a generated token
[API] ... returned 401	Token expired, or the app is not subscribed to that endpoint	Regenerate the token, or supply clientId + clientSecret + siteId so the Actor mints a fresh one each run
[API] ... returned 429	You hit the rate limit of your Rakuten publisher account	Space out your scheduled runs
setup_status: DIAGNOSTIC_GUIDE with zero records	Keyword too narrow, wrong networkId, or merchants not joined yet	Broaden keyword, match networkId to your regional account, join the merchants, re-run
setup_status: CREDENTIALS_REQUIRED	No accessToken and an incomplete OAuth triple	Fill clientId + clientSecret + siteId, or just accessToken

🔒 Privacy & security

Your clientSecret and accessToken go directly to api.linksynergy.com over HTTPS. The input schema marks those fields isSecret: true, so Apify Console masks them. Nothing is stored, logged or relayed through our servers.

📚 Related actors

• CJ Affiliate Products — Commission Junction API (BYOC)
• Impact.com Affiliate Network — Impact REST API (BYOC)
• Awin Multi-Merchant Affiliate — Awin Publisher API (BYOC)
• ShareASale Publisher (BYOC) — ShareASale Affiliate API (BYOC)

🆕 Changelog

• v1.0 (2026-05-14): Initial release. 3 query types, dual auth (OAuth + pre-generated token), XML regex parser, diagnostic-record guard instead of failed runs, owner-skip PPE.

---

Português

🛒 Rakuten Advertising API — Merchants, Coupons & Products (BYOC)

Consulta a API oficial Rakuten Advertising Publisher (api.linksynergy.com) para descobrir merchants, cupons ativos e produtos. BYOC (Bring Your Own Credentials) — você traz suas credenciais grátis de publisher, o Actor faz a troca OAuth, o parsing do XML e a normalização para JSON. API oficial: sem camada anti-bot e sem conta de proxy residencial.

Cada execução chama um endpoint e grava registros JSON planos no dataset. A lista exata de campos por queryType está em Saída — leia antes de gastar uma execução.

O que cada execução entrega

• 3 tipos de consulta — productSearch (produtos entre merchants), coupons (ofertas ativas), advertisers (merchants aos quais você pode se filiar)
• Duas autenticações — grant OAuth client_credentials ou token pré-gerado no Rakuten Developer Portal
• XML → JSON — o XML bruto do Rakuten é lido por um extrator de regex, sem dependência de lxml / xml2js
• 5 redes regionais pelo input networkId — 1 EUA, 3 Reino Unido, 7 Austrália, 9 Brasil, 14 Alemanha
• Registro de diagnóstico no lugar de run FAILED — credencial errada, token expirado ou zero resultados geram um registro setup_status explicando o que mudar, e a execução termina SUCCEEDED sem cobrança PPE
• Owner-skip — execuções internas do dono do Actor não passam pela cobrança

🔑 Setup BYOC (uma vez, grátis)

1. Cadastre-se em https://developers.rakutenadvertising.com (ou use sua conta Publisher existente)
2. Applications → Create New App → copie Client ID + Client Secret
3. Encontre seu Site ID na conta Rakuten Advertising (número de ~7 dígitos)
4. Escolha o caminho de autenticação:
   • Caminho A (OAuth): preencha clientId + clientSecret + siteId. O Actor envia grant_type=client_credentials&scope=<siteId> para https://api.linksynergy.com/token e usa o bearer devolvido.
   • Caminho B (token pré-gerado): no Developer Portal clique em "Generate Token" → cole o valor em accessToken. O OAuth é pulado. Use quando o Caminho A responder invalid_client.

O Rakuten aplica as próprias quotas à sua conta de publisher. Este Actor envia uma requisição por execução, então cada run consome uma chamada dessa quota.

📥 Entrada

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
clientId	string (secret)	Caminho A	—	Client ID OAuth em Applications
clientSecret	string (secret)	Caminho A	—	Client Secret OAuth
siteId	string	Caminho A	—	Publisher Site ID (~7 dígitos), usado como scope do OAuth
accessToken	string (secret)	Caminho B	—	Token pré-gerado; quando preenchido, o OAuth é pulado e clientId/clientSecret/siteId ficam dispensáveis
queryType	enum	Sim	productSearch	productSearch / coupons / advertisers
keyword	string	Não	""	productSearch → nome do produto; advertisers → nome do merchant; coupons → texto da oferta
advertiserId	string	Não	""	Restringe a um merchant. productSearch envia como mid, coupons como advertiserid. advertisers ignora.
networkId	enum	Não	1	1 EUA, 3 Reino Unido, 7 Austrália, 9 Brasil, 14 Alemanha. Usado por coupons e advertisers.
maxResults	integer	Não	25	1–500. Limita os registros gravados no dataset.
proxyConfiguration	object	Não	{"useApifyProxy": false}	Dispensável — a API Rakuten valida o token, não o seu IP

Não existe input category. Categoria vem na saída (category nos produtos, categories em cupons e advertisers).

Exemplo de input (Caminho B — token pré-gerado, mais simples)

{
  "accessToken": "your-token-from-rakuten-portal",
  "queryType": "productSearch",
  "keyword": "running shoes",
  "maxResults": 50
}

Exemplo de input (Caminho A — fluxo OAuth)

{
  "clientId": "your-rakuten-client-id",
  "clientSecret": "your-rakuten-client-secret",
  "siteId": "4703080",
  "queryType": "coupons",
  "keyword": "fashion",
  "networkId": "1",
  "maxResults": 100
}

📤 Saída

Todo registro carrega queryType, networkId e scrapedAt, então você pode juntar datasets de execuções diferentes sem perder a origem. Os nomes de campo abaixo são exatamente os que o Actor grava; os valores são placeholders.

Registros queryType=productSearch

currency é o literal "USD" fixo no código, não um valor lido do XML — veja Capacidades e limites.

{
  "productName": "Air Zoom Pegasus - Running Shoe",
  "sku": "PEGASUS-US-10",
  "merchantName": "Example Sportswear US",
  "merchantId": "39247",
  "price": 129.99,
  "salePrice": null,
  "currency": "USD",
  "category": "Athletic Shoes",
  "description": "Descrição curta vinda do feed do anunciante",
  "productUrl": "https://click.linksynergy.com/deeplink?id=...",
  "imageUrl": "https://images.example-merchant.com/pegasus.jpg",
  "upc": "091202394857",
  "queryType": "productSearch",
  "networkId": "1",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

price e salePrice são números (null quando o Rakuten não manda nada parseável). sku cai para o link id do feed quando o anunciante omite o SKU.

Registros queryType=coupons

{
  "couponCode": "RUN20",
  "offerDescription": "20% off running shoes",
  "offerStartDate": "2026-05-01",
  "offerEndDate": "2026-05-31",
  "merchantName": "Example Sportswear US",
  "merchantId": "39247",
  "categories": "Apparel",
  "promotionTypes": "Percentage Off",
  "clickUrl": "https://click.linksynergy.com/fs-bin/click?id=...",
  "queryType": "coupons",
  "networkId": "1",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

categories e promotionTypes chegam como string com espaços normalizados, direto do XML — não são arrays. Faça o split você mesmo se o seu pipeline precisar de lista.

Registros queryType=advertisers

{
  "merchantId": "39247",
  "merchantName": "Example Sportswear US",
  "applicationStatus": "approved",
  "categories": "Apparel",
  "networks": "1",
  "offer": "Texto da oferta como devolvido pelo endpoint de advertiser search",
  "queryType": "advertisers",
  "networkId": "1",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

applicationStatus diz se sua conta de publisher já pode mandar tráfego para aquele merchant.

Registros de diagnóstico

Quando algo está errado, o Actor grava um único registro rotulado e sai SUCCEEDED sem cobrar PPE. Existem duas formas.

Credenciais ausentes:

{
  "setup_status": "CREDENTIALS_REQUIRED",
  "message": "Rakuten Affiliate API access requires clientId, clientSecret, siteId OR a pre-generated accessToken. Please follow the instructions to set them up.",
  "instructions": ["1. Log in or sign up at https://developers.rakutenadvertising.com/", "..."],
  "platform": "rakuten",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

Falha de OAuth, erro da API (401 / endpoint não habilitado), queryType inválido ou zero registros parseados:

{
  "setup_status": "DIAGNOSTIC_GUIDE",
  "_dataQuality": "diagnostic",
  "message": "[DIAGNÓSTICO] Zero items extracted from Rakuten advertisers ...",
  "potential_causes": ["wrong networkId (1=US, 3=UK, 7=AU, 9=BR, 14=DE)", "..."],
  "remediations": ["try queryType=advertisers first to list merchants you can join", "..."],
  "queryType": "advertisers",
  "networkId": "1",
  "scrapedAt": "2026-05-15T13:45:00.000Z"
}

Filtre por _dataQuality == "diagnostic" ou pela presença de setup_status para manter esses registros fora das suas tabelas de produção.

✅ Capacidades e limites

Declarado de antemão, para você não gastar uma execução descobrindo.

Moeda fixa: em queryType=productSearch o campo currency é a string literal USD, não um valor lido do XML Rakuten — todo registro de produto sai carimbado como USD, seja qual for o merchant ou a rede. Trate price e salePrice como números crus do feed do anunciante e confirme a moeda por fora antes de comparar preços.

Sem laço de paginação: o Actor faz uma única requisição HTTP por execução e depois corta os blocos parseados em maxResults. Para productSearch ele envia max=maxResults, para coupons envia resultsperpage=maxResults, e para advertisers não envia parâmetro de tamanho nenhum — você recebe o que vier naquela resposta. Não há cursor de offset/página, então uma execução não retorna mais que uma página da API por mais alto que maxResults esteja. Para varrer um catálogo grande, agende várias execuções com keyword ou advertiserId diferentes.

Registro sem nome é descartado: um bloco parseado sem merchantName, sem productName e sem offerDescription é pulado antes do pushData, então a contagem de itens pode ficar abaixo da contagem de blocos que aparece no log.

Atenção: este Actor exige credenciais suas (clientId + clientSecret + siteId, ou accessToken). Sem elas ele não roda.

Input / recurso	Suportado	Observação
queryType	✅	Escolhe o endpoint: productsearch/1.0, coupon/1.0 ou advertisersearch/1.0
keyword	✅	Mapeado para keyword (productSearch, coupons) ou merchantname (advertisers)
advertiserId	✅	mid no productSearch, advertiserid nos coupons; o endpoint de advertisers ignora
networkId	✅	Aplicado em coupons e advertisers; productSearch busca na rede vinculada ao seu token
siteId	✅	Usado como scope do OAuth no Caminho A; não é enviado no Caminho B
maxResults	⚠️	Limita o dataset, mas não ultrapassa uma página da API (não há laço de paginação)
currency na saída	⚠️	Literal "USD" fixo no productSearch; ausente nos registros de coupons e advertisers
categories / promotionTypes	⚠️	Entregues como string, não como array
Proxy	⚠️	Configurável, mas a API Rakuten autentica por token; a configuração só importa se a sua própria rede bloquear api.linksynergy.com
clientId / clientSecret / accessToken	🔑	Credenciais suas, marcadas como isSecret para o Apify mascarar nos logs

💰 Preços

$0.005 por registro gravado (item-scraped), o uso de plataforma da Apify está incluído — compute e proxy não são cobrados à parte.

Pay-per-event (PPE): cobrado por registro gravado. Os caminhos de diagnóstico (credencial ausente, falha de OAuth, erro de API, queryType inválido, zero registros) saem antes da chamada de cobrança, então execução sem dado real custa zero. Execuções do dono também pulam a cobrança.

🚀 Casos de uso

• Descoberta de programas de afiliados — rode queryType=advertisers para listar merchants e leia applicationStatus antes de se candidatar
• Agregação de cupons — abasteça uma página de ofertas com couponCode, offerDescription, offerEndDate e clickUrl
• Importação de catálogo — popule um site de comparação com productName, price, imageUrl, productUrl e upc
• Mapeamento de merchants — cruze merchantId entre cupons e produtos para montar uma tabela única de merchants

⚠️ Erros comuns

O Actor converte cada um destes em registro no dataset em vez de run FAILED, então a mensagem chega até você no dataset e no log.

Mensagem no log	Causa	Solução
[OAUTH] Rakuten token endpoint returned 401	Client ID/Secret revogado, ou siteId fora do escopo do app	Revise o app no Developer Portal, ou vá para o Caminho B e cole um token gerado
[API] ... returned 401	Token expirado, ou app sem assinatura naquele endpoint	Gere outro token, ou informe clientId + clientSecret + siteId para o Actor emitir um novo a cada execução
[API] ... returned 429	Você bateu no rate limit da sua conta de publisher Rakuten	Espace as execuções agendadas
setup_status: DIAGNOSTIC_GUIDE com zero registros	Keyword restrita demais, networkId errado, ou merchants ainda não filiados	Amplie o keyword, alinhe o networkId com sua conta regional, filie-se aos merchants e rode de novo
setup_status: CREDENTIALS_REQUIRED	Sem accessToken e com a trinca OAuth incompleta	Preencha clientId + clientSecret + siteId, ou apenas accessToken

🔒 Privacidade e segurança

Seu clientSecret e seu accessToken vão direto para api.linksynergy.com sobre HTTPS. O input schema marca esses campos como isSecret: true, então o Apify Console os mascara. Nada é armazenado, logado ou intermediado pelos nossos servidores.

📚 Actors Relacionados

• CJ Affiliate Products — API da Commission Junction (BYOC)
• Impact.com Affiliate Network — API REST da Impact (BYOC)
• Awin Multi-Merchant Affiliate — API Publisher da Awin (BYOC)
• ShareASale Publisher (BYOC) — API de Afiliados da ShareASale (BYOC)

🆕 Histórico de Versões

• v1.0 (2026-05-14): Lançamento inicial. 3 tipos de consulta, autenticação dupla (OAuth + token pré-gerado), parser XML por regex, registro de diagnóstico no lugar de run FAILED, PPE com owner-skip.