Borkol Docs startpagina

Winkelwagens & Checkout

Een cart claimen

Een guest-cart koppelen aan een ingelogde klant, waarbij een eventuele bestaande cart van de klant wordt samengevoegd.

Bekijk als Markdown

Een bezoeker bouwt een cart doorgaans anoniem op en logt pas later in. Claimen koppelt die anonieme cart aan de ingelogde klant die door X-Customer-Token wordt geïdentificeerd. Vanaf dat moment is de cart klanteigendom: requests erop moeten het token van de eigenaar meesturen (zie de eigenaarschapsregels op de pagina Carts), prijzen worden bepaald in de pricingcontext van de klant, en checkout koppelt de order aan de klant.

Samenvoeggedrag

Als de klant al andere active carts had, wordt elk daarvan in de geclaimde cart gevouwen:

  • Regels dedupliceren op de combinatie van product, variant en configuratie: van overeenkomende regels worden de hoeveelheden opgeteld en vervolgens begrensd op max_quantity_per_line uit de policy.
  • Extra afzonderlijke regels uit de oude cart vervallen zodra de geclaimde cart max_lines bereikt.
  • De geclaimde cart behoudt zijn eigen email en metadata als die gezet zijn; is een van beide null, dan neemt hij de waarde van de oude cart over.
  • De status van elke oude cart wordt merged en zijn voorraadreserveringen worden vrijgegeven. Een merged cart-id blijft werken op GET /carts/{id} maar geeft een 404 op schrijfacties.

Een cart claimen die al aan dezelfde klant toebehoort is een no-op en geeft de cart ongewijzigd terug. Een cart claimen die aan een andere klant toebehoort faalt met een 403.

Let op: een cart die via e-mailregistratie aan een guest-klantrij is gebonden (PATCH /carts/{id} met email) heeft ook customer_id gezet: die claimen slaagt alleen wanneer het token naar diezelfde klant herleidt; anders geldt het 403-geval.

POST /v1/api/commerce/carts/{id}/claim

Vereist commerce:write en een active cart. X-Customer-Token is verplicht: zonder een herleidbaar token faalt de request met status 401 en een lege body. Geen request body. Geeft de volledige cart-envelope terug, dezelfde vorm als GET /v1/api/commerce/carts/{id}, nu inclusief eventueel samengevoegde regels, met status 200.

Parameters

Pad

NaamTypeVerplichtBeschrijving
idstring (UUID)jaCart-id. Moet een active cart zijn.

Headers

NaamTypeVerplichtBeschrijving
X-Customer-TokenstringjaKlantsessietoken. Moet naar een klant herleiden, anders 401.

Geen body.

Request
curl -X POST https://api.borkol.com/v1/api/commerce/carts/9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4/claim \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: {customer_token}"
Request (JS)
const res = await fetch(
  `https://api.borkol.com/v1/api/commerce/carts/${cartId}/claim`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "X-Customer-Token": customerToken,
    },
  }
);
const { data: cart } = await res.json();
Response
{
  "data": {
    "id": "9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4",
    "status": "active",
    "lines": [
      { "id": "5e6f7a8b-...", "quantity": 3, "...": "..." },
      { "id": "6f7a8b9c-...", "quantity": 1, "...": "merged in from the customer's previous cart" }
    ],
    "...": "same cart shape as GET /v1/api/commerce/carts/{id}"
  }
}

Fouten

StatusBodyWanneer
401lege bodyX-Customer-Token ontbreekt of is niet herleidbaar, of de customers-module is niet beschikbaar.
403lege bodyDe cart is al gebonden aan een andere klant.
404{"message": "..."}Cart onbekend, verlopen of niet active.
403scope-, module- of schorsingsbodyZie de pagina Carts.
429{"message": "Too Many Attempts."}Rate limit overschreden.