In dit onderwerp leer je hoe je klantgegevens (inclusief aangepaste velden) uit de Chargebee API kunt ophalen. Zorg ervoor dat je een Chargebee API-sleutel bij de hand hebt, evenals Invantive Query Tool om de Chargebee-query’s uit te voeren:
Invantive SQL dekt de Chargebee API over tientallen API’s. Vrijwel alle endpoints van API v2 worden ondersteund.
Chargebee-gegevens kunnen niet alleen worden gedownload, maar ook geüpload. Dit stelt SaaS-bedrijven in staat om een datawarehouse te vullen met abonnements-, facturerings- en betalingsgegevens uit alle betaalbronnen. De SQL-driver biedt ook Power BI-rapporten en -dashboards voor de Chargebee API.
Gegevens kunnen niet alleen worden gedownload, maar ook in Chargebee worden geladen met behulp van eenvoudige SQL-statements die direct worden vertaald naar Chargebee API-aanroepen. Hierdoor kunnen SaaS-bedrijven eenvoudig gegevens uit hun backoffice-ERP-systeem naar Chargebee uploaden en de gegevens gesynchroniseerd houden: abonnementen, accounts, betalingen, enz.
API-sleutel voorbereiden
Er is een API-sleutel vereist om je gebruiker bij de API te identificeren. Zonder inloggegevens kunnen er geen Chargebee-gegevens worden opgehaald. De Chargebee API-sleutel is een tekst van 30-40 tekens bestaande uit cijfers, kleine en hoofdletters.
Voer de volgende stappen uit om een API-sleutel te verkrijgen:
- Ga naar User Login - Chargebee.
- Kies je site op User Login - Chargebee.
- Noteer de naam van de site; je hebt deze nodig bij het inloggen.
- Ga naar “Settings” in het linkermenu.
- Klik op “Configure Chargebee”.
- Scroll naar beneden naar “API Keys and Webhooks”:
- Klik op “API Keys”.
- Maak een API-sleutel aan.
- Voor een testsite is het handigst om een Full-Access Key te gebruiken.
Inloggen bij Chargebee API
De eerste stap is om in te loggen bij Chargebee met behulp van de volgende stappen:
- Start de Invantive Query Tool.
- Open de databasegroep “Business Apps”.
- Kies “Chargebee”.
- Vul je API-sleutel in bij het eerste veld “API Key”.
- Vul de sitenaam in bij het tweede veld “Site”.
- Log in via “Connect”.
Eerste Chargebee-gegevens ophalen
Als eerste stap haal je wat betaalbrongegevens op, wat relatief eenvoudige basisgegevens (referentiegegevens) zijn, met behulp van de volgende stappen:
- Klik op het tabblad “Available Objects” onderaan.
- Open het schema “PaymentSources” in de boomstructuur.
- Klik op de tabel “PaymentSources (Payment Sources)”.
- Aan de rechterkant verschijnt een lijst met kolommen.
- Boven de kolommen staan tabbladen.
- Klik op het tabblad “Data”.
- De eerste 50 betaalbronnen verschijnen in een rooster.
API v2-gegevensformaten
De SQL-driver voor de Chargebee API volgt algemene conventies. Enige kennis van de gegevens en datatypes is nuttig, zelfs bij gebruik van Invantive SQL.
Identificatiecodes
ID’s binnen Chargebee hebben verschillende formaten. De betaalbron-ID kan er bijvoorbeeld uitzien als “pm_16CHQ2S9FKpykauA”, met een vergelijkbaar ID-formaat voor Events zoals “ev_6olyVSIlySWm57D”. Merk op dat de eerste twee tekens overeenkomen met de tabelnaam, zoals “pm” voor “Payment” en “ev” voor “Event”. De ID-kolom van andere tabellen, zoals een prijsplan, heeft echter doorgaans een leesbaar code-formaat zoals “agency-gbp-year” en is zichtbaar in de gebruikersinterface. Hetzelfde geldt voor klanten.
Bedragen
Gegevens van de Chargebee API hebben een specifiek formaat voor bedragen. Alle bedragen worden geretourneerd in centeenheden. De Invantive SQL-driver converteert de bedragen automatisch en volledig transparant tussen valuta- en centeenheden.
Aangepaste velden
De Chargebee API ondersteunt aangepaste velden op:
- Add-ons
- Klanten
- Plannen
- Abonnementen
Alle aangepaste velden hebben een tekstformaat. Omdat Chargebee nog geen metadata over de aangepaste velden biedt, levert Invantive SQL extra tabellen om de waarden van de aangepaste velden op te halen:
- AddonCustomFieldValues
- CustomerCustomFieldValues
- PlanCustomFieldValues
- SubscriptionCustomFieldValues
Voor elke combinatie van record en aangepast veld is er één record aanwezig in deze tabellen met aangepaste velden. Wanneer het Chargebee-abonnementstype bijvoorbeeld twee aangepaste velden “erp_id” en “chamber_of_commerce” heeft, bevat de tabel SubscriptionCustomFieldValues maximaal twee rijen per klant.
Eenvoudige query op Chargebee API
De gegevens van Chargebee kunnen eenvoudig worden gecombineerd tot nieuwe rapporten. De volgende query geeft je bijvoorbeeld een lijst van op abonnementen gebaseerde facturen, inclusief het btw-nummer van de klant:
select ctr.last_name
, ctr.vat_number
--
, ssn.plan_id
, ssn.mrr
--
, ive.amount_due
, ive.amount_paid
, ive.currency_code
, ive.po_number
from invoices ive
join customers ctr
on ctr.id = ive.customer_id
join subscriptions ssn
on ssn.id = ive.subscription_id
SQL-query met behulp van Chargebee aangepaste velden
Sommige Chargebee-gegevens bevatten waarden van aangepaste velden. Omdat er voor elke hoofdentiteit meerdere waarden van aangepaste velden kunnen zijn, kan het handig zijn om deze te pivoteren. Dit geldt vooral bij het synchroniseren van de gegevens naar een datawarehouse of operationele datastore in een traditioneel relationeel datamodel. Het volgende voorbeeld laat zien hoe je de Chargebee-klantgegevens kunt pivoteren:
select pvt.customer_id
, pvt.erp_id
, pvt.chamber_of_commerce
from customers cmr
join customercustomfieldvalues
pivot ( min(value)
for key
in
( [erp_id]
, [chamber_of_commerce]
)
) pvt
on 1=1
and cmr.id = customer_id
Nieuwe Chargebee-klant registreren via API en bijwerken
Zoals eerder gezegd, biedt de SQL-driver voor de Chargebee API echter niet alleen gegevensophaling, maar ondersteunt ook DML (data manipulation language) op Chargebee. Het volgende statement maakt een nieuwe klant aan in Chargebee:
insert into customers
( id
, last_name
)
values
( 13031406
, 'Invantive BV'
)
En het volgende statement wijzigt de voornaam van de klant:
update customers
set first_name = 'John'
where id = 13031406
--
-- Zorg ervoor dat gegevens niet uit de cache worden opgehaald.
--
set use-http-memory-cache false
set use-http-disk-cache false
select *
from customers
where id = 13031406
Merk op dat de ID wordt opgegeven in het insert-statement en wordt gebruikt door Chargebee.

