# Verzendmethoden

Verzendmethoden worden door de merchant geconfigureerd. Elke methode heeft een vast `amount` en een optionele `free_over_amount`-drempel: wanneer het bruto goederentotaal van de cart de drempel bereikt, is verzending voor die cart gratis. Dit endpoint geeft elke methode terug met het `effective_amount` al bepaald voor de opgegeven cart, zodat de storefront de verzendkeuze kan tonen zonder de gratis-verzendregel zelf te implementeren.

Verzending geldt alleen voor carts met verzendbare regels: regels waarvan het product `requires_shipping: true` heeft. Zie de pagina Checkout voor wanneer `shipping_method_id` verplicht is.

## GET /v1/api/commerce/carts/{id}/shipping-methods

Geeft de actieve verzendmethoden van de store terug, gesorteerd op naam, met de effectieve prijs voor deze cart. Vereist `commerce:read`. Cart-eigenaarschap wordt afgedwongen (zie de pagina Carts). De lijst is niet gepagineerd.

### Parameters

**Pad**

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `id` | string (UUID) | ja | Cart-id. Elke status wordt geaccepteerd voor de lookup, maar de prijscontext is alleen zinvol voor een `active` cart. |

**Headers**

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | nee | Vereist als de cart gebonden is aan een niet-guest klant. |

### Responsevelden

De envelope is `{"data": [...]}`. Anders dan de geldwaarden van carts en orders zijn de bedragen hier kale integers in minor units, geen money-objecten; de valuta is de valuta van de cart (`EUR`).

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `id` | string (UUID) | altijd | Id van de verzendmethode. Geef dit bij checkout door als `shipping_method_id`. |
| `name` | string | altijd | Weergavenaam. |
| `amount` | integer | altijd | Basisprijs in minor units. |
| `free_over_amount` | integer of null | altijd | Bruto goederentotaal (minor units) waarbij verzending gratis wordt, of null wanneer de methode nooit gratis is. |
| `effective_amount` | integer | altijd | De prijs die deze cart op dit moment zou betalen: 0 wanneer het bruto goederentotaal van de cart `free_over_amount` bereikt, anders `amount`. |

```bash title="Request"
curl https://api.borkol.com/v1/api/commerce/carts/9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4/shipping-methods \
  -H "Authorization: Bearer {api_key}"
```

```javascript title="Request (JS)"
const res = await fetch(
  `https://api.borkol.com/v1/api/commerce/carts/${cartId}/shipping-methods`,
  { headers: { Authorization: `Bearer ${apiKey}` } }
);
const { data: methods } = await res.json();
```

```json title="Response"
{
  "data": [
    {
      "id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
      "name": "Express",
      "amount": 995,
      "free_over_amount": null,
      "effective_amount": 995
    },
    {
      "id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
      "name": "Standard",
      "amount": 495,
      "free_over_amount": 5000,
      "effective_amount": 0
    }
  ]
}
```

`effective_amount` is een momentopname voor de cart zoals hij nu is: het wijzigen van de cartinhoud kan het veranderen, dus haal het opnieuw op na cartmutaties als de verzendkeuze zichtbaar is.

### Fouten

| Status | Body | Wanneer |
| --- | --- | --- |
| 404 | `{"message": "..."}` | Onbekend cart-id of een cart van een andere store. |
| 403 | `{"message": "This cart belongs to a customer."}` | Eigenaarschapscheck mislukt. |
| 403 | scope-, module- of schorsingsbody | Zie de pagina Carts. |
| 429 | `{"message": "Too Many Attempts."}` | Rate limit overschreden. |