# Shipping

> The groups a shop sorts its goods into for delivery.

Source: https://storeware.ai/docs/api-reference/rest/shipping

## List shipping classes

`GET /api/v1/stores/{storeId}/shipping-classes`

Every class the shop has, oldest first. A class holds variants that cost the same to send, and a delivery rate can name classes to depend on. `meta.gaps` lists the delivery zones with no rate for a class that has variants in it, because a basket holding one of those cannot be checked out to that zone.

Needs `stores:read`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |

**Answers** `200`

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of [ShippingClassRow](https://storeware.ai/docs/api-reference/rest/objects#shippingclassrow) |  |
| `meta` | object |  |
| `meta.total` | integer |  |
| `meta.gaps` | map of array of string (uuid) | Class id to the ids of the zones with no rate for it. |

```bash
curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/shipping-classes" \
  -H "Authorization: Bearer $TOKEN"
```

## Create a shipping class

`POST /api/v1/stores/{storeId}/shipping-classes`

Answers with the class already holding that name, unchanged, if there is one. Refused with `shipping_class_name_invalid` for a name with no letter or number in it. Send `Idempotency-Key` to make a retry safe.

Needs `stores:write`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | 1 to 120 characters. |
| `description` | string or null | No | Up to 500 characters. |

**Answers** `201`

| Field | Type | Description |
| --- | --- | --- |
| `data` | [ShippingClass](https://storeware.ai/docs/api-reference/rest/objects#shippingclass) |  |

```bash
curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/shipping-classes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
```

## Update a shipping class

`PATCH /api/v1/stores/{storeId}/shipping-classes/{classId}`

Changes only the fields sent. Renaming a class keeps its slug. Refused with `shipping_class_not_found` for a class this shop does not have.

Needs `stores:write`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |
| `classId` | path | string | The class. |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | 1 to 120 characters. |
| `description` | string or null | No | Up to 500 characters. |

**Answers** `200`

| Field | Type | Description |
| --- | --- | --- |
| `data` | [ShippingClass](https://storeware.ai/docs/api-reference/rest/objects#shippingclass) |  |

```bash
curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/shipping-classes/$CLASS_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
```

## Delete a shipping class

`DELETE /api/v1/stores/{storeId}/shipping-classes/{classId}`

The variants in it are left in no class. Refused with `shipping_class_in_use` while a delivery rate names it, because the rate would then be offered to the wrong baskets.

Needs `stores:write`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |
| `classId` | path | string | The class. |

**Answers** `200`

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.variantsCleared` | integer | How many variants were left in no class. |

```bash
curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/shipping-classes/$CLASS_ID" \
  -H "Authorization: Bearer $TOKEN"
```