De Advertising API is de koppeling waarmee software je sponsored products op bol beheert. Campagnes aanmaken en aanpassen, biedingen en budgetten zetten, en prestaties ophalen tot op het niveau van zoekterm (bol: Advertising API). Hij staat los van de Retailer API, die over orders, verzendingen en aanbiedingen gaat. Andere credentials, andere endpoints, en een eigen versie: de Advertising API v11.
Die v11 kwam er toen bol zijn sponsored products verhuisde naar een nieuwe omgeving. Early adopters gingen op 18 april 2024 over (bol: roadmap Advertising API). Sindsdien heeft bol er onder meer TACoS, een attributierapport, een biedrapport, share of voice en, in 2026, rapportages voor Branded Shelves aan toegevoegd.
Retailer API of Advertising API?
Retailer API | Advertising API | |
|---|---|---|
Waarvoor | Orders, verzendingen, aanbiedingen, retouren | Sponsored products: campagnes, biedingen, budgetten, rapportages |
Credentials | "Client credentials voor de Retailer API" | "Client credentials voor de Advertising API" |
Versie | v10, met delen in v11 | v11 |
Rapportages | Verkoop- en prestatiedata | Advertentiedata, per dag geaggregeerd |
Met je advertising-credentials kun je ook een handvol Retailer API-endpoints gebruiken die handig zijn bij het adverteren: productrankings, zoektermen, productdetails per EAN, productplaatsing, productlijsten en concurrerende aanbiedingen (bol: Retailer API-toegang voor adverteerders).
Toegang regelen
In de API-instellingen van je verkoopaccount staat onder de Retailer-credentials een apart blok: "Client credentials voor de Advertising API". Klik op Aanmaken, geef de API-gebruiker een naam en je krijgt een Advertiser ID en een secret, dat je zichtbaar maakt met "Toon secret" (bol: credentials voor de Advertising API). Een token vraag je op dezelfde manier aan als bij de Retailer API. Retailer-credentials werken hier niet, en andersom ook niet: een tool die zowel je verkopen als je advertenties leest, heeft dus twee sets nodig.
Hoe een campagne in elkaar zit
Bovenaan staat de campagne, met naam, startdatum, budget, daglimiet en type. Daaronder hangen ad groups, die het campaignId erven. In een ad group zitten de ads (je producten, per EAN) en, afhankelijk van het type, zoekwoorden, negatieve zoekwoorden, doelcategorieën en negatieve doelcategorieën (bol: campaigns). Wat je bovenin verandert, werkt door naar beneden: archiveer je een ad group, dan zijn de producten en zoekwoorden erin niet meer bruikbaar.
Het type is de belangrijkste keuze, want je kunt het achteraf niet wijzigen. Bij AUTO kiest bol de zoekwoorden op basis van je product en biedt automatisch, gericht op een ACoS-doel dat je meegeeft als acosTargetPercentage: 10 betekent dat je 10% van de productomzet aan advertenties wilt uitgeven. Bij MANUAL voeg je zelf zoekwoorden toe en zet je het bod per zoekwoord of doelcategorie. Een ACoS-doel bestaat bij MANUAL niet, en een bod op campagneniveau bestaat nergens. Wil je van type wisselen, dan maak je een nieuwe campagne en verhuis je je ads en zoekwoorden. Welke van de twee wanneer werkt, lees je in automatische of handmatige campagne op bol.
Dagbudget en totaalbudget zijn allebei optioneel. Raakt een van beide op, dan krijgt de campagne de status OUT_OF_DAILY_BUDGET of OUT_OF_TOTAL_BUDGET en draait hij niet meer. Wie dat niet uitleest, merkt het pas aan de omzet.
Tot slot de limieten: maximaal 15.000 niet-gearchiveerde campagnes, maximaal 150 campagnes per aanmaak- of wijzigverzoek (meer geeft een 400), en bij het opvragen maximaal 50 per verzoek, dus je pagineert.
Rapportages ophalen
Prestaties haal je op via bulkrapportages, en dat gaat in drie stappen (bol: bulk performance reports). Je vraagt een rapport aan met een start- en einddatum en krijgt een processStatusId terug. Daarmee controleer je de status; let op, dat endpoint hoort bij de gedeelde v10-API, dus je headers moeten op v10 staan. Is het rapport klaar, dan haal je met het entityId uit die status een downloadlink op. Die link is 15 minuten geldig; daarna vraag je met hetzelfde rapport-ID een nieuwe aan.
Een aanvraag beslaat maximaal 35 dagen, en de startdatum ligt hooguit 12 maanden terug. Wil je een jaar historie, dan zijn dat dus elf aanvragen.
De rapporten bestaan op veel niveaus: van adverteerder, campagne, ad group en ad tot zoekwoord, zoekterm, doelcategorie en doelproduct, plus aparte rapporten voor biedingen, attributie, productpagina's, share of voice en Branded Shelves (bol: overzicht bulkrapportages). Naast vertoningen, klikken, CTR, CPC en kosten krijg je conversies en omzet over 14 dagen, ACoS, ROAS, TACoS, en veilingcijfers als winrate, impression share en het gemiddelde winnende bod.
Twee eigenschappen bepalen hoe je die cijfers moet lezen. Alles is per dag geaggregeerd: een ACoS per uur kun je uit de API niet berekenen. En het attributierapport gaat uit van de verkoopdatum, niet van de klikdatum. Omdat conversies over 14 dagen tellen, zijn de cijfers van de laatste dagen nog niet af en lopen ze vaak nog op.
Waar het misgaat
Een klassieker: rapporten inlezen op kolompositie. Sinds 9 juli 2024 kan bol op elke plek nieuwe kolommen toevoegen, dus een parser die kolom 7 als kosten leest, breekt zonder waarschuwing. Lees altijd op kolomnaam.
Daarnaast bevat een rapport alleen wat in die periode prestaties had. Een ad group zonder vertoningen ontbreekt dus, en wie het rapport als volledige lijst van zijn campagnes behandelt, mist precies de onderdelen die niet draaien. Leg het rapport daarom altijd naast je campagne-instellingen.
En kies het campagnetype bewust. Een AUTO-campagne die je later handmatig wilt sturen, moet je opnieuw opbouwen.
In Rylee
Rylee koppelt met de Advertising API én met de Retailer API, zodat je advertentiecijfers naast je echte winst per product ziet. In het sponsored products-dashboard zie je je campagnes, zoekwoorden en ACoS, zonder zelf rapporten op te vragen en te parsen. Met bol advertenties automatiseren stel je regels in, bijvoorbeeld om producten met lage voorraad uit je campagnes te halen. Meer over het sturen op ACoS lees je in ACoS bij sponsored products.
Vragen die we vaak krijgen
Kost de Advertising API geld?
De API zelf niet. Je betaalt alleen voor je advertenties, net als wanneer je campagnes in de advertentieomgeving van bol beheert.
Kan ik een ACoS-doel instellen voor een handmatige campagne?
Nee. Het ACoS-doel werkt alleen bij AUTO-campagnes. Bij MANUAL stuur je via het bod per zoekwoord of doelcategorie.