# Tenant Shipping Methods

Manage the shipping methods available to customers on your marketplace. Each shipping method is based on a platform-level template and can be customised with a name, note, ordering, and active/default state per tenant.

## Shipping method types

| Type | Description |
|---|---|
| `standard` | Fixed-rate or free shipping configured manually |
| `external` | Dynamic rates fetched in real-time from a third-party extension at checkout |
| `sendcloud` | Integrated with Sendcloud for label generation and carrier selection |

## Admin vs customer access

- **`GET /v1/tenants/shipping_methods`** — Public-facing; returns only active methods. Pass `account_id` to filter methods assigned to a specific seller account.
- **`POST`, `PUT`, `DELETE`** — Admin only.
- **`GET /:id/external`** — Fetches live rates from an external extension for a specific method; used during checkout.

---

## GET `/v1/tenants/shipping_methods`

Lists shipping methods configured for the tenant.

### Query parameters

| Parameter | Type | Description |
|---|---|---|
| `account_id` | integer | Filter to methods available for a specific seller account |

### Response fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Unique identifier of the tenant shipping method |
| `name` | string | Display name (translated per locale) |
| `note` | string | Optional description shown to customers |
| `logo_path` | string | Logo or image URL |
| `type` | string | Type of the underlying shipping method (`standard`, `external`, `sendcloud`) |
| `channel` | string | Fulfilment channel (e.g. `delivery`, `pickup`) |
| `default` | boolean | Whether this is the pre-selected method at checkout |
| `active` | boolean | Whether this method is available to customers |
| `order_by` | integer | Sort rank (lower = shown first) |
| `metadata` | object | Extension configuration (e.g. `extension_id` for external methods) |

---

## POST `/v1/tenants/shipping_methods`

Adds a new shipping method for the tenant. Admin only.

### Request fields

| Field | Type | Required | Description |
|---|---|---|---|
| `shipping_method.shipping_method_id` | integer | Yes | Platform-level shipping method template ID |
| `shipping_method.name` | string | Yes | Display name |
| `shipping_method.note` | string | No | Customer-facing note or description |
| `shipping_method.default` | boolean | Yes | Set as default checkout method (unsets all others) |
| `shipping_method.active` | boolean | Yes | Make available to customers |
| `shipping_method.order_by` | integer | No | Sort rank |
| `shipping_method.metadata` | object | No | Extra config — e.g. `{ "extension_id": 12 }` for external methods |

---

## PUT `/v1/tenants/shipping_methods/:shipping_method_id`

Updates an existing tenant shipping method. Admin only. Same fields as POST.

---

## DELETE `/v1/tenants/shipping_methods/:shipping_method_id`

Archives a shipping method, removing it from checkout. Admin only.

---

## GET `/v1/tenants/shipping_methods/:shipping_method_id/external`

Fetches live shipping rates from a third-party extension for a specific shipping method. Used during checkout to display dynamic carrier options and pricing.

Requires the shipping method to have `metadata.extension_id` set and the extension to support the `external_shipping_methods` event.

### Query parameters

| Parameter | Type | Description |
|---|---|---|
| `shipping_address_id` | integer | User's saved address ID — passed to the extension to calculate rates |
| `uuid` | string | Cart UUID — used to fetch current cart contents for rate calculation |

### Response fields

| Field | Type | Description |
|---|---|---|
| `external_shipping_methods` | array | Array of carrier options returned by the extension |