API

Les og skriv lojalitetsdata fra din egen backend med Gibbonds eksterne GraphQL-API — registrer medlemmer, tildel og løs inn poeng, og synkroniser aktivitet fra alle kanaler.

På denne siden

⚡

Pro-abonnement kreves. Det eksterne API-et er tilgjengelig med Pro-abonnementet. Oppgrader under Abonnementer og fakturering i Gibbond-administrasjonen for å aktivere det.

🚀

Ny med API-et? Integrasjonsveiledningen viser praktiske eksempler du kan kopiere og bruke — kall fra backend, integrasjon i en mobil- eller nettapp og opptjening av poeng fra en annen salgskanal. Denne siden er den fullstendige skjemareferansen.

API-et har ett GraphQL-endepunkt. Send en POST-forespørsel med en JSON-kropp som inneholder query (eller en mutasjon) og eventuelt variables:

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

Alle tidsstempler er ISO-8601-strenger, og alle ID-er er Shopify-GID-er (for eksempel gid://shopify/Customer/123), med mindre annet er oppgitt. Poeng er heltall.

Autentisering

Hver forespørsel inneholder autentiseringsinformasjon i Authorization-headeren. Det finnes to typer autentiseringsinformasjon for to ulike situasjoner.

API-nøkler (på serversiden)

API-nøkler identifiserer backend-en din. Opprett dem på siden API-nøkler i Gibbond-administrasjonen, der hver nøkkel får et tilgangsnivå (READ, WRITE eller ADMIN). En nøkkel vises bare én gang, når den opprettes, og ser slik ut: glk_live_…. Send den som et bearer-token:

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxx

⚠️

Kun på serversiden. En API-nøkkel kan lese og endre dataene til alle medlemmer. Den må derfor aldri eksponeres i en nettleser, mobilapp eller klient du ikke kontrollerer. Lagre den i en miljøvariabel på serveren. Hvis den lekker, tilbakekall den eksponerte nøkkelen og opprett en ny i administrasjonen.

Kundetokener (på klientsiden)

Når du trenger å kalle API-et fra et grensesnitt for kunder (en butikkwidget eller en mobilapp), oppretter du et kundetoken med mutasjonen mintCustomerToken fra backend-en og sender deretter tokenet til klienten. Kundetokener har kort levetid og er begrenset til én kunde: en forespørsel med et slikt token kan bare lese data og utføre handlinger for denne kunden. Spørringen me returnerer kunden tokenet tilhører, og redeemReward fungerer for denne kunden uten en forhandlernøkkel — derfor kan tokenet trygt sendes til nettleseren.

Authorization: Bearer <customer token>

Tilgangsnivåer

Tilgangsnivået til en API-nøkkel styrer hvilke operasjoner den kan utføre. Tilgangsnivåene er kumulative.

Tilgangsnivå	Gir tilgang til
`READ`	Alle spørringer (saldoer, historikk, belønninger, nivåer og konfigurasjon).
`WRITE`	Alt i `READ`, samt mutasjoner som registrerer medlemmer, tildeler positive poeng, løser inn belønninger, bekrefter poeng og oppretter kundetokener.
`ADMIN`	Alt i `WRITE`, samt tilbakeføring av poeng (`clawbackPoints`) og negative justeringer via `awardPoints` (en negativ `points`-verdi).

ℹ️

Bruk det laveste tilgangsnivået som dekker behovet — en READ-nøkkel til analyse, en WRITE-nøkkel til opptjening og innløsning, og reserver ADMIN for refusjoner og korrigeringer.

Forespørselsgrenser

Hver autentiseringsopplysning (hver API-nøkkel og hvert kundetoken) er begrenset til 600 forespørsler per minutt. Når grensen overskrides, returnerer API-et HTTP 429 med en Retry-After-header som angir hvor mange sekunder du må vente før du prøver igjen.

Spørringer

Spørringer krever en nøkkel med minst READ-tilgang eller et kundetoken (som bare kan lese data for sin egen kunde).

Spørring	Argumenter	Returverdi / beskrivelse
`me`	—	Kunden som et kundespesifikt token tilhører. Gir en feil når den kalles med en API-nøkkel for forhandleren.
`customer`	`id: ID!`	Én kunde basert på GID.
`customers`	`ids: [ID!]!`	Les flere kunder samtidig basert på GID (forhandlernøkkel, `READ`).
`customerByEmail`	`email: String!`	Finn en kunde ved hjelp av e-postadressen (forhandlernøkkel, `READ`).
`rewards`	—	Butikkens katalog over belønninger som kan løses inn.
`tiers`	—	Butikkens VIP-nivåer (slug, navn, terskel og multiplikator).
`shopConfig`	—	Programkonfigurasjon: navn, valuta, poeng per dollar, bekreftelsesmodus, nivåer og belønninger.
`pointHistory`	`customerId: ID!`, `limit: Int`	En kundes poenghendelser, nyeste først.
`activeCodes`	`customerId: ID!`	En kundes ubrukte rabattkoder (innløsninger og nivåfordeler).
`referral`	`customerId: ID!`	En kundes vervekode og antall inviterte, kvalifiserte og belønnede kunder.
`totalLiability`	—	Butikkens samlede utestående poengforpliktelse som et heltall (forhandlernøkkel, `READ`).

Mutasjoner

Mutasjoner krever en WRITE-nøkkel med mindre annet er oppgitt. Operasjoner som krever ADMIN, er merket.

Mutasjon	Argumenter	Returverdi / beskrivelse
`enrollCustomer`	`customerId: ID!`, `email: String`	Registrer en kunde i lojalitetsprogrammet (`WRITE`). Returnerer `CustomerResult`.
`awardPoints`	`customerId: ID!`, `points: Int!`, `reason: String`, `idempotencyKey: String`	Tildel eller juster poeng. En negativ `points`-verdi krever `ADMIN`; `idempotencyKey` hindrer duplikater ved gjentatte forsøk. Returnerer `PointResult`.
`awardPointsForOrder`	`input: OrderInput!`	Tjen poeng for en bestilling lagt inn i en annen kanal; bruker nivåmultiplikatoren, Boosts og milepæler på nytt. Idempotent basert på `orderId` (`WRITE`). Returnerer `PointResult`.
`redeemReward`	`customerId: ID!`, `rewardId: ID!`	Løs inn en belønning mot en rabattkode som kan brukes én gang (`WRITE` eller et kundetoken som handler for sin egen kunde). Returnerer `RedeemResult`.
`confirmPoints`	`customerId: ID!`, `orderId: ID`	Bekreft en kundes ventende poeng, for eksempel etter at bestillingen er oppfylt (`WRITE`). Returnerer antall bekreftede poeng.
`clawbackPoints`	`customerId: ID!`, `orderId: ID!`, `refundAmount: Float!`, `orderTotal: Float!`, `refundId: ID`	Tilbakefør poeng ved en refusjon (`ADMIN`). Returnerer antall tilbakeførte poeng.
`mintCustomerToken`	`customerId: ID!`, `ttlSeconds: Int`	Opprett et kundespesifikt token med kort levetid for bruk på klientsiden (`WRITE` / `ADMIN`). Returnerer et `CustomerToken` med `expiresAt`.

ℹ️

awardPointsForOrder tar imot et OrderInput: orderId, customerId, valgfrie customerEmail og orderName, samt en liste med lineItems. Hver varelinje inneholder en valgfri productId, valgfrie collectionIds og en lineTotal — slik at produkt- og kolleksjonsspesifikke Boosts og unntak gjelder på samme måte som for vanlige Shopify-bestillinger.

Eksempel på forespørsel

Les en kundes saldo og nivå med en API-nøkkel 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" }
  }'

Feilkoder

Feil følger GraphQL-konvensjonen: en errors-liste på øverste nivå, der hver oppføring inneholder en code i extensions og en tilsvarende HTTP-status.

Kode	HTTP	Betydning
`UNAUTHENTICATED`	401	Manglende, ugyldig formatert eller utløpt autentiseringsinformasjon.
`FORBIDDEN`	403	Autentiseringsinformasjonen er gyldig, men mangler tilgangsnivået denne operasjonen krever.
`RATE_LIMITED`	429	Forespørselsgrensen er overskredet; prøv igjen etter ventetiden angitt i `Retry-After`-headeren.
`BAD_USER_INPUT`	400	Ugyldige argumenter — feil GID, manglende obligatorisk felt eller en verdi utenfor tillatt område.
`NOT_FOUND`	404	Kunden, belønningen eller ressursen det henvises til, finnes ikke.