# Shipping zones (/ai/reference/orders/shipping-zones)

Toolset `shipping_zones`, 6 tools.

## Records [#records]

### `fulfillment_set` [#fulfillment_set]

How a stock location ships (type shipping) or hands over (type pickup), with its service zones and the countries, regions, cities or postcodes each zone covers. A shipping option belongs to one service zone.

- Permission: `settings.read`
- Tools: `fulfillment_set_list`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `stock_location_id` | string |  |  |
| `type` | string |  | e.g. shipping or pickup |

## Actions [#actions]

### `fulfillment_set_create` [#fulfillment_set_create]

Let a stock location ship or hand over orders.

- Action key: `fulfillment_set.create`
- Permission: `settings.write` and `products.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `stock_location_id` | string | yes |  |
| `name` | string | yes | at least 1 characters |
| `type` | string | yes | one of "shipping", "pickup" |

Example input:

```json
{
  "stock_location_id": "019bb6f8-b1b2-7f60-90b5-2b8ebca0b3c7",
  "name": "Budapest warehouse shipping",
  "type": "shipping"
}
```

### `fulfillment_set_delete` [#fulfillment_set_delete]

Delete a fulfillment set with its service zones and their shipping options.

- Action key: `fulfillment_set.delete`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fulfillment_set_id` | string | yes |  |

Example input:

```json
{
  "fulfillment_set_id": "019bb2e2-45a6-7aae-bca2-7caf85e4df62"
}
```

### `service_zone_create` [#service_zone_create]

Add an area a fulfillment set delivers to, by country, region, city or postcode.

- Action key: `service_zone.create`
- Permission: `settings.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fulfillment_set_id` | string | yes |  |
| `name` | string | yes | at least 1 characters |
| `geo_zones` | list of object, one shape of: | yes | at least 1 items |

Example input:

```json
{
  "fulfillment_set_id": "019bb2e2-45a6-7aae-bca2-7caf85e4df62",
  "name": "Hungary",
  "geo_zones": [
    {
      "type": "country",
      "country_code": "hu"
    }
  ]
}
```

### `service_zone_delete` [#service_zone_delete]

Delete a service zone with its shipping options.

- Action key: `service_zone.delete`
- Permission: `settings.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fulfillment_set_id` | string | yes |  |
| `service_zone_id` | string | yes |  |

Example input:

```json
{
  "fulfillment_set_id": "019bb2e2-45a6-7aae-bca2-7caf85e4df62",
  "service_zone_id": "019bb6f0-e6c3-7b49-9df3-11f85d8b1249"
}
```

### `service_zone_update` [#service_zone_update]

Rename a service zone or replace the areas it covers.

geo_zones replaces the whole list: keep a zone by passing its id. A dry run returns the zone as it is now and changes nothing.

- Action key: `service_zone.update`
- Permission: `settings.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
- Dry run: supported, with `dry_run` set to true.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fulfillment_set_id` | string | yes |  |
| `service_zone_id` | string | yes |  |
| `name` | string |  | at least 1 characters |
| `geo_zones` | list of object, one shape of: |  |  |

Example input:

```json
{
  "fulfillment_set_id": "019bb2e2-45a6-7aae-bca2-7caf85e4df62",
  "service_zone_id": "019bb6f0-e6c3-7b49-9df3-11f85d8b1249",
  "geo_zones": [
    {
      "type": "country",
      "country_code": "hu"
    },
    {
      "type": "country",
      "country_code": "at"
    }
  ]
}
```