API

Læs og skriv loyalitetsdata fra din egen backend med Gibbonds eksterne GraphQL-API — tilmeld medlemmer, tildel og indløs point, og synkronisér aktivitet fra enhver kanal.

På denne side

⚡

Pro-planen er påkrævet. Det eksterne API er tilgængeligt med Pro-planen. Opgradér via Plans & billing i Gibbonds admin for at aktivere det.

🚀

Ny til API'et? Læs integrationsguiden med praktiske eksempler, du kan kopiere — kald fra din backend, integration i en mobil- eller webapp og optjening af point fra en anden salgskanal. Denne side indeholder den fulde skemareference.

API'et har ét GraphQL-endpoint. Send en POST-anmodning med en JSON-body, der indeholder din query (eller mutation) og eventuelle variables:

POST https://app.gibbond.com/api/v1/graphql

Alle tidsstempler er ISO-8601-strenge, og alle ID'er er Shopify-GID'er (for eksempel gid://shopify/Customer/123), medmindre andet er angivet. Point er hele tal.

Godkendelse

Hver anmodning indeholder en legitimationsoplysning i Authorization-headeren. Der findes to slags legitimationsoplysninger til forskellige situationer.

API-nøgler (på serversiden)

API-nøgler identificerer din backend. Opret dem på siden API keys i Gibbonds admin. Hver nøgle får tildelt et adgangsområde (READ, WRITE eller ADMIN). Nøglen vises kun én gang, når den oprettes, og ser sådan ud: glk_live_…. Send den som et bearer-token:

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

⚠️

Kun på serversiden. En API-nøgle kan læse og ændre alle medlemmers data og må derfor aldrig eksponeres i en browser, mobilapp eller klient, du ikke kontrollerer. Opbevar den i en miljøvariabel på serveren, og udskift den i admin, hvis den bliver lækket.

Kundetokens (på klientsiden)

Når du skal kalde API'et fra en kundegrænseflade (en butikswidget eller mobilapp), opretter du et kundetoken med mutationen mintCustomerToken fra din backend og giver derefter tokenet videre til klienten. Kundetokens er kortlivede og begrænset til én kunde: en anmodning med et sådant token kan kun læse data om og udføre handlinger for den pågældende kunde. Forespørgslen me finder kunden bag tokenet, og redeemReward fungerer for kunden uden en forhandlernøgle, så tokenet kan sendes sikkert til browseren.

Authorization: Bearer <customer token>

Adgangsområder

En API-nøgles adgangsområde bestemmer, hvilke handlinger den må udføre. Adgangsområderne er kumulative.

Område	Giver adgang til
`READ`	Alle forespørgsler (saldi, historik, belønninger, niveauer og konfiguration).
`WRITE`	Alt fra `READ` samt mutationer, der tilmelder medlemmer, tildeler positive point, indløser belønninger, bekræfter point og opretter kundetokens.
`ADMIN`	Alt fra `WRITE` samt tilbageførsel af point (`clawbackPoints`) og negative justeringer via `awardPoints` (et negativt `points`-beløb).

ℹ️

Brug det laveste adgangsområde, der løser opgaven — en READ-nøgle til analyse, en WRITE-nøgle til optjening og indløsning, og gem ADMIN til arbejdsgange for refundering og korrektion.

Forespørgselsgrænser

Hver legitimationsoplysning (API-nøgle eller kundetoken) er begrænset til 600 anmodninger i minuttet. Hvis grænsen overskrides, returnerer API'et HTTP 429 med en Retry-After-header, der angiver, hvor mange sekunder du skal vente, før du prøver igen.

Forespørgsler

Forespørgsler kræver en nøgle med mindst READ-adgangsområde eller et kundetoken (som kun kan læse data om den kunde, det tilhører).

Forespørgsel	Argumenter	Resultat / beskrivelse
`me`	—	Kunden, som et kundebegrænset token tilhører. Giver en fejl, hvis det kaldes med en forhandler-API-nøgle.
`customer`	`id: ID!`	En enkelt kunde søgt efter GID.
`customers`	`ids: [ID!]!`	Samlet opslag af kunder efter GID (forhandlernøgle, `READ`).
`customerByEmail`	`email: String!`	Find en kunde via e-mailadresse (forhandlernøgle, `READ`).
`rewards`	—	Butikkens katalog over belønninger, der kan indløses.
`tiers`	—	Butikkens VIP-niveauer (slug, navn, grænse og multiplikator).
`shopConfig`	—	Programkonfiguration: navn, valuta, point pr. valutaenhed, bekræftelsestilstand, niveauer og belønninger.
`pointHistory`	`customerId: ID!`, `limit: Int`	Kundens pointbegivenheder, nyeste først.
`activeCodes`	`customerId: ID!`	Kundens ubrugte rabatkoder (indløsninger og niveaufordele).
`referral`	`customerId: ID!`	Kundens henvisningskode samt antal inviterede, kvalificerede og belønnede.
`totalLiability`	—	Butikkens samlede udestående pointforpligtelse som et heltal (forhandlernøgle, `READ`).

Mutationer

Mutationer kræver en WRITE-nøgle, medmindre andet er angivet; handlinger, der kræver ADMIN, er markeret.

Mutation	Argumenter	Resultat / beskrivelse
`enrollCustomer`	`customerId: ID!`, `email: String`	Tilmeld en kunde til loyalitetsprogrammet (`WRITE`). Returnerer `CustomerResult`.
`awardPoints`	`customerId: ID!`, `points: Int!`, `reason: String`, `idempotencyKey: String`	Tildel eller justér point. Et negativt `points`-beløb kræver `ADMIN`; `idempotencyKey` forhindrer dubletter ved gentagne forsøg. Returnerer `PointResult`.
`awardPointsForOrder`	`input: OrderInput!`	Optjen point for en ordre fra en anden kanal; niveauets multiplikator, boosts og milepæle genbruges. Idempotent ud fra `orderId` (`WRITE`). Returnerer `PointResult`.
`redeemReward`	`customerId: ID!`, `rewardId: ID!`	Indløs en belønning til en engangsrabatkode (`WRITE` eller et kundetoken, der handler på egne vegne). Returnerer `RedeemResult`.
`confirmPoints`	`customerId: ID!`, `orderId: ID`	Bekræft en kundes ventende point, f.eks. efter ordreafsendelse (`WRITE`). Returnerer antallet af bekræftede point.
`clawbackPoints`	`customerId: ID!`, `orderId: ID!`, `refundAmount: Float!`, `orderTotal: Float!`, `refundId: ID`	Tilbagefør point ved en refundering (`ADMIN`). Returnerer antallet af tilbageførte point.
`mintCustomerToken`	`customerId: ID!`, `ttlSeconds: Int`	Opret et kortlivet kundetoken til brug på klientsiden (`WRITE` / `ADMIN`). Returnerer et `CustomerToken` med feltet `expiresAt`.

ℹ️

awardPointsForOrder tager imod et OrderInput med felterne orderId, customerId, eventuelle customerEmail og orderName samt en liste med lineItems. Hver ordrelinje kan have valgfrie productId og collectionIds samt lineTotal — derfor gælder boosts og undtagelser for produkter og kollektioner på samme måde som ved almindelige Shopify-ordrer.

Eksempel på anmodning

Læs en kundes saldo og niveau med en API-nøgle på serversiden:

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" }
  }'

Fejlkoder

Fejl følger GraphQL-konventionen: det øverste array errors indeholder poster med en code i extensions og den tilsvarende HTTP-status.

Kode	HTTP	Betydning
`UNAUTHENTICATED`	401	Legitimationsoplysningen mangler, er ugyldig eller er udløbet.
`FORBIDDEN`	403	Legitimationsoplysningen er gyldig, men mangler adgangsområdet til denne handling.
`RATE_LIMITED`	429	Forespørgselsgrænsen er overskredet; prøv igen efter tidspunktet angivet i `Retry-After`-headeren.
`BAD_USER_INPUT`	400	Ugyldige argumenter — forkert GID, manglende obligatorisk felt eller en værdi uden for det tilladte interval.
`NOT_FOUND`	404	Den angivne kunde, belønning eller anden ressource findes ikke.