API
Läs och skriv lojalitetsdata från din egen backend med Gibbonds externa GraphQL API — registrera medlemmar, dela ut och lös in poäng och synkronisera aktivitet från valfri kanal.
På den här sidan
Pro-planen krävs. Det externa API:et ingår i Pro-planen. Uppgradera via Plans & billing i Gibbonds admin för att aktivera det.
Ny på API:et? Läs integrationsguiden med konkreta exempel du kan kopiera — anrop från din backend, integration i en mobil- eller webbapp och poängintjäning från en annan försäljningskanal. Den här sidan innehåller hela schemareferensen.
API:et har en enda GraphQL-slutpunkt. Skicka en POST-begäran med en JSON-kropp som innehåller din query (eller mutation) och valfria variables:
POST https://app.gibbond.com/api/v1/graphqlAlla tidsstämplar är ISO-8601-strängar och alla ID:n är Shopify GID:n (till exempel gid://shopify/Customer/123) om inget annat anges. Poäng är heltal.
Autentisering
Varje begäran innehåller en autentiseringsuppgift i Authorization-headern. Det finns två typer av autentiseringsuppgifter för olika användningsområden.
API-nycklar (på serversidan)
API-nycklar identifierar din backend. Skapa dem på sidan API keys i Gibbonds admin. Varje nyckel tilldelas ett behörighetsomfång (READ, WRITE eller ADMIN). Nyckeln visas bara en gång när den skapas och ser ut så här: glk_live_…. Skicka den som en bearer-token:
Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxxEndast på serversidan. En API-nyckel kan läsa och ändra alla medlemmars uppgifter. Den får därför aldrig exponeras i en webbläsare, mobilapp eller klient som du inte kontrollerar. Förvara den i en miljövariabel på servern och byt ut den i admin om den läcker.
Kundtoken (på klientsidan)
När du behöver anropa API:et från ett kundgränssnitt (en butikswidget eller mobilapp) skapar du en kundtoken med mutationen mintCustomerToken från din backend och lämnar sedan över token till klienten. Kundtoken är kortlivade och begränsade till en enskild kund: en begäran med en sådan token kan bara läsa och utföra åtgärder för den kunden. Frågan me hämtar kunden som token är kopplad till, och redeemReward fungerar för kunden utan en handlar-nyckel, så token kan skickas säkert till webbläsaren.
Authorization: Bearer <customer token>Behörighetsomfång
En API-nyckels behörighetsomfång styr vilka åtgärder den får utföra. Omfången är kumulativa.
| Omfång | Ger behörighet till |
|---|---|
READ | Alla frågor (saldon, historik, belöningar, nivåer och inställningar). |
WRITE | Allt i READ, samt mutationer för att registrera medlemmar, dela ut pluspoäng, lösa in belöningar, bekräfta poäng och skapa kundtoken. |
ADMIN | Allt i WRITE, samt återföring av poäng (clawbackPoints) och negativa justeringar via awardPoints (ett negativt points-värde). |
Använd det lägsta behörighetsomfång som räcker — en READ-nyckel för analys, en WRITE-nyckel för intjäning och inlösen, och spara ADMIN för återbetalningar och korrigeringar.
Anropsbegränsningar
Varje autentiseringsuppgift (API-nyckel eller kundtoken) begränsas till 600 begäranden per minut. Om gränsen överskrids returnerar API:et HTTP 429 med en Retry-After-header som anger hur många sekunder du ska vänta innan du försöker igen.
Frågor
Frågor kräver en nyckel med minst READ-omfång eller en kundtoken (som bara kan läsa uppgifter om kunden den tillhör).
| Fråga | Argument | Resultat / beskrivning |
|---|---|---|
me | — | Kunden som kundtoken är kopplad till. Ger ett fel om den anropas med en API-nyckel för handlare. |
customer | id: ID! | En enskild kund utifrån GID. |
customers | ids: [ID!]! | Läs flera kunder i en batch utifrån GID (handlar-nyckel, READ). |
customerByEmail | email: String! | Sök upp en kund med e-postadress (handlar-nyckel, READ). |
rewards | — | Butikens katalog över belöningar som kan lösas in. |
tiers | — | Butikens VIP-nivåer (slug, namn, gränsvärde och multiplikator). |
shopConfig | — | Programinställningar: namn, valuta, poäng per valutaenhet, bekräftelseläge, nivåer och belöningar. |
pointHistory | customerId: ID!, limit: Int | Kundens poänghändelser, med de senaste först. |
activeCodes | customerId: ID! | Kundens oanvända rabattkoder (inlösen och nivåförmåner). |
referral | customerId: ID! | Kundens värvningskod och antal inbjudna, kvalificerade och belönade personer. |
totalLiability | — | Butikens totala utestående poängskuld, som ett heltal (handlar-nyckel, READ). |
Mutationer
Mutationer kräver en WRITE-nyckel om inget annat anges; åtgärder som kräver ADMIN är markerade.
| Mutation | Argument | Resultat / beskrivning |
|---|---|---|
enrollCustomer | customerId: ID!, email: String | Registrerar en kund i lojalitetsprogrammet (WRITE). Returnerar CustomerResult. |
awardPoints | customerId: ID!, points: Int!, reason: String, idempotencyKey: String | Delar ut eller justerar poäng. Ett negativt points-värde kräver ADMIN; idempotencyKey förhindrar dubletter vid omförsök. Returnerar PointResult. |
awardPointsForOrder | input: OrderInput! | Ger poäng för en order från en annan kanal och använder nivåmultiplikatorer, boosts och milstolpar. Idempotent för orderId (WRITE). Returnerar PointResult. |
redeemReward | customerId: ID!, rewardId: ID! | Löser in en belöning mot en engångsrabattkod (WRITE eller en kundtoken som används för den egna kunden). Returnerar RedeemResult. |
confirmPoints | customerId: ID!, orderId: ID | Bekräftar kundens väntande poäng, till exempel efter att ordern har distribuerats (WRITE). Returnerar antalet bekräftade poäng. |
clawbackPoints | customerId: ID!, orderId: ID!, refundAmount: Float!, orderTotal: Float!, refundId: ID | Återför poäng vid en återbetalning (ADMIN). Returnerar antalet återförda poäng. |
mintCustomerToken | customerId: ID!, ttlSeconds: Int | Skapar en kortlivad kundtoken för användning på klientsidan (WRITE / ADMIN). Returnerar en CustomerToken med värdet expiresAt. |
awardPointsForOrder tar emot ett OrderInput med fälten orderId, customerId, valfria customerEmail och orderName, samt en lista med lineItems. Varje orderrad kan innehålla valfria productId och collectionIds, samt lineTotal — då fungerar produkt- och samlingsspecifika boosts och undantag på samma sätt som för vanliga Shopify-order.
Exempel på begäran
Läs kundens saldo och nivå med en API-nyckel på serversidan:
curl https://app.gibbond.com/api/v1/graphql \
-X POST \
-H "Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"query": "query($id: ID!) { customer(id: $id) { email balance pending lifetime tier { name multiplier } } }",
"variables": { "id": "gid://shopify/Customer/123456789" }
}'Felkoder
Fel följer GraphQL-konventionen: den överordnade arrayen errors innehåller poster med en code i extensions och motsvarande HTTP-status.
| Kod | HTTP | Betydelse |
|---|---|---|
UNAUTHENTICATED | 401 | Autentiseringsuppgiften saknas, är felaktig eller har upphört att gälla. |
FORBIDDEN | 403 | Autentiseringsuppgiften är giltig men saknar behörighet för den här åtgärden. |
RATE_LIMITED | 429 | Anropsgränsen har överskridits; försök igen efter tiden som anges i Retry-After-headern. |
BAD_USER_INPUT | 400 | Ogiltiga argument — felaktigt GID, obligatoriskt fält saknas eller ett värde ligger utanför tillåtet intervall. |
NOT_FOUND | 404 | Den angivna kunden, belöningen eller annan resurs finns inte. |