Fra bestilling til pakke på vei

Få vite at det kom en bestilling

To måter. Legg inn en webhook på order.paid, og få en signert POST i det kjøpet går gjennom. Eller hent dem selv med GET /v1/orders?status=paid og updated_since, hvis du heller vil eie tidspunktet selv.

Velg webhook for frakt. En pakke som blir liggende til neste runde, går ikke i dag. Bruk rundene som sikkerhetsnett ved siden av, så en utsending du gikk glipp av blir tatt igjen.

Sjekk signaturen før du stoler på bodyen, og dedupliser på id: vi lover ikke at en hendelse kommer bare én gang, og et nytt forsøk etter et svar som gikk tapt ser likt ut for oss. Slik sjekker du signaturen →

Hent hele bestillingen

Lista over bestillinger er uten varelinjer. En liste som bar hver eneste varelinje ville vært mange ganger så stor for noe de fleste kall ikke bruker. Skal du pakke noe, henter du den ene bestillingen.

shipping_address er null når det ikke er noe å sende, altså på rent digitale kjøp. Det er den sjekken som avgjør om bestillingen i det hele tatt skal inn i fraktsystemet ditt. Adressefeltene inni er hver for seg nullbare, så ikke regn med at line2 finnes.

Alt på en varelinje er et øyeblikksbilde fra kjøpet. title og unit_price_ore er slik de var da det ble handlet, ikke slik produktet er i dag, og product_id kan være null hvis produktet er borte siden. Pakksedler skal bruke varelinja, ikke slå opp produktet på nytt.

curl https://api.skribb.no/v1/orders/ord_3Ln9Ra \
  -H "Authorization: Bearer skribb_sk_…"

Merk som sendt

Når pakken er på vei, merker du bestillingen. Det er dette kallet som sender kjøperen e-post med sporingsnummeret, så det skal skje når pakken er levert til fraktselskapet, ikke når etiketten er skrevet ut.

Navngir du fraktselskapet, blir nummeret en lenke kjøperen kan åpne, og bestillinger du leser ut igjen får tracking_url ferdig satt sammen. Gyldige verdier er posten, postnord og helthjem. Noe annet svarer 422 bad-carrier. Begge feltene er valgfrie, men uten fraktselskap blir sporingsnummeret bare tekst.

curl -X POST https://api.skribb.no/v1/orders/ord_3Ln9Ra/fulfill \
  -H "Authorization: Bearer skribb_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"tracking_note": "CJ123456789NO", "tracking_carrier": "posten"}'

Å merke som sendt to ganger

Merker du en bestilling som alt er merket, svarer vi 409 not-fulfillable og gjør ingenting. Svaret bærer status, så du ser hvorfor.

Fraktsystemer sender gjerne den samme hendelsen om igjen, og uten sperren ville kjøperen fått to e-poster om den samme pakken. Behandle not-fulfillable med status fulfilled som «alt gjort», ikke som en feil verdt å varsle om.

async function ship(orderId) {
  const { order } = await api(`/orders/${orderId}`);

  // Ingenting å sende: rent digitalt kjøp.
  if (!order.shipping_address) return { skipped: "digital" };

  const label = await yourCarrier.createLabel({
    to: order.shipping_address,
    lines: order.items.map((i) => ({ title: i.title, quantity: i.quantity })),
  });

  try {
    await api(`/orders/${orderId}/fulfill`, {
      method: "POST",
      body: JSON.stringify({
        tracking_note: label.trackingNumber,
        tracking_carrier: label.carrier, // posten | postnord | helthjem
      }),
    });
  } catch (err) {
    // Alt merket. Som regel den samme hendelsen om igjen, ikke en feil.
    if (err.body?.error === "not-fulfillable" && err.body?.status === "fulfilled") {
      return { alreadyDone: true };
    }
    throw err;
  }
  return { shipped: true };
}

Fraktprisene kjøperen ser

Prisen kjøperen betalte for frakt, kommer fra fraktabellen under butikkinnstillinger, ikke fra fraktsystemet ditt. Raden velges av vekten på varene, som er weight_grams på hvert produkt. Uten vekt har tabellen ingenting å prise mot.

Endrer fraktselskapet prisene sine, er det denne tabellen du oppdaterer. Den ligger bak en egen tilgang, shop-settings:write, som ikke følger med orders:write: en nøkkel som finnes for å merke pakker som sendt, har ingenting med hva kjøperen betaler å gjøre.

Refusjon

POST /orders/{id}/refund refunderer hele beløpet. 200 betyr at Stripe tok imot refusjonen, ikke at bestillingen alt står som refundert: statusen settes av Stripes eget varsel like etter. Svaret viser bestillingen slik den er i øyeblikket, som regel fortsatt paid. Vil du vite når statusen endres, er order.refunded hendelsen du lytter på.

Videre

Referansen for det denne guiden bruker:

• Bestillinger →
• Butikkinnstillinger →
• Alle guidene →