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

Toolset `shipping`, 19 tools.

## Records [#records]

### `courier` [#courier]

Every courier the store ships with or could add: the built-in manual delivery and each courier app, whether the app is installed, switched on and set up, the locations it is connected to, its services (parcel locker, home delivery) and whether a new shipping option can use it and checkout offers it. id is the provider_id a new shipping option takes; it is null until the app is installed.

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

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `stock_location_id` | string |  | Only report connections to this location, e.g. the location of a shipping zone |

### `fulfillment_provider` [#fulfillment_provider]

A carrier app or the manual provider that ships orders. get adds the options it offers, which a shipping option names in its data.

- Permission: `settings.read`
- Tools: `fulfillment_provider_list`, `fulfillment_provider_get`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `is_enabled` | boolean |  |  |
| `stock_location_id` | string |  |  |

### `shipping_option` [#shipping_option]

A delivery method customers pick at checkout, or a return method, as the admin shows it: its courier, pricing, prices, whether checkout shows it, its conditions, zone, location and shipping profile, plus the ids the write tools take. The courier of an existing option is fixed. With order_id, the options that order can use.

- Permission: `settings.read`
- Tools: `shipping_option_list`, `shipping_option_get`
- Sorts: `created_at`, `name`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `order_id` | string |  | Only the options that can ship this order, e.g. for a return or an edit |
| `q` | string |  |  |
| `service_zone_id` | string |  |  |
| `shipping_profile_id` | string |  |  |
| `stock_location_id` | string |  |  |
| `is_return` | boolean |  | Return options only, or outbound only |

### `shipping_option_type` [#shipping_option_type]

A label shipping options are grouped under, e.g. Standard or Express.

- Permission: `settings.read`
- Tools: `shipping_option_type_list`, `shipping_option_type_get`
- Sorts: `created_at`, `label`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string |  |  |
| `code` | string |  |  |

### `shipping_profile` [#shipping_profile]

A group of products that ship the same way; every shipping option belongs to one profile.

- Permission: `settings.read`
- Tools: `shipping_profile_list`, `shipping_profile_get`
- Sorts: `created_at`, `name`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string |  |  |
| `type` | string |  |  |

## Actions [#actions]

### `shipping_option_create` [#shipping_option_create]

Add a delivery or return method to a service zone.

provider_id is the id of a courier from courier_list that is connected to the location of the zone, and data is {"id": <one of its services>}; service_zone_id from shipping_option_list or fulfillment_set_list. Give type_id of an existing shipping option type or a new type, not both. A rule enabled_in_store eq "true" shows it at checkout; is_return eq "true" makes it a return method.

- Action key: `shipping_option.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 |
| --- | --- | --- | --- |
| `name` | string | yes | at least 1 characters |
| `service_zone_id` | string | yes |  |
| `shipping_profile_id` | string | yes |  |
| `provider_id` | string | yes |  |
| `price_type` | string | yes | one of "flat", "calculated" |
| `prices` | list of object, one shape of: | yes | Flat prices per currency or region; empty for calculated |
| `type_id` | string |  |  |
| `type` | object |  |  |
| `type.label` | string | yes |  |
| `type.code` | string | yes |  |
| `type.description` | string |  |  |
| `rules` | list of object |  |  |
| `rules[].attribute` | string | yes | e.g. enabled_in_store or is_return |
| `rules[].operator` | string | yes | one of "in", "eq", "ne", "gt", "gte", "lt", "lte", "nin" |
| `rules[].value` | string or list of string | yes |  |
| `data` | map of string or number or boolean or list of any value or map of any value or null |  | The provider option chosen |

Example input:

```json
{
  "name": "Home delivery",
  "service_zone_id": "019bb6f0-e6c3-7b49-9df3-11f85d8b1249",
  "shipping_profile_id": "019bb73d-bcc5-7993-83c9-5c9a9f7ada5a",
  "provider_id": "manual_manual",
  "price_type": "flat",
  "prices": [
    {
      "currency_code": "huf",
      "amount": 1490
    }
  ],
  "type_id": "019bb738-31cf-70f8-a14c-805d6a641a07",
  "rules": [
    {
      "attribute": "enabled_in_store",
      "operator": "eq",
      "value": "true"
    }
  ]
}
```

### `shipping_option_delete` [#shipping_option_delete]

Delete a shipping option; customers can no longer pick it.

- Action key: `shipping_option.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 |
| --- | --- | --- | --- |
| `shipping_option_id` | string | yes | Shipping option ID (so_…) |

Example input:

```json
{
  "shipping_option_id": "019bb70f-16d0-75b7-bdb6-d22f3f99c289"
}
```

### `shipping_option_rules_delete` [#shipping_option_rules_delete]

Delete rules of a shipping option, which can offer it to more customers.

Read the rule ids with shipping_option_get.

- Action key: `shipping_option_rules.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 |
| --- | --- | --- | --- |
| `shipping_option_id` | string | yes | Shipping option ID (so_…) |
| `rule_ids` | list of string | yes | at least 1 items |

Example input:

```json
{
  "shipping_option_id": "019bb70f-16d0-75b7-bdb6-d22f3f99c289",
  "rule_ids": [
    "019bb72d-35a9-7cb6-a1fe-3572dae8ee66"
  ]
}
```

### `shipping_option_type_create` [#shipping_option_type_create]

Add a label to group shipping options under, e.g. Express.

- Action key: `shipping_option_type.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 |
| --- | --- | --- | --- |
| `label` | string | yes |  |
| `code` | string | yes |  |
| `description` | string |  |  |

Example input:

```json
{
  "label": "Express",
  "code": "express"
}
```

### `shipping_option_type_delete` [#shipping_option_type_delete]

Delete a shipping option type no shipping option uses.

- Action key: `shipping_option_type.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 |
| --- | --- | --- | --- |
| `shipping_option_type_id` | string | yes | Shipping option type ID |

Example input:

```json
{
  "shipping_option_type_id": "019bb738-31cf-70f8-a14c-805d6a641a07"
}
```

### `shipping_option_type_update` [#shipping_option_type_update]

Change a shipping option type's label, code or description.

- Action key: `shipping_option_type.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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipping_option_type_id` | string | yes | Shipping option type ID |
| `label` | string |  |  |
| `code` | string |  |  |
| `description` | string |  |  |

Example input:

```json
{
  "shipping_option_type_id": "019bb738-31cf-70f8-a14c-805d6a641a07",
  "label": "Next day"
}
```

### `shipping_option_update` [#shipping_option_update]

Change a shipping option's name, prices, profile, type or rules.

prices replaces the price list; pass a price id to keep and change one. rules adds and updates (by id) rules; shipping_option_rules_delete removes them.

- Action key: `shipping_option.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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipping_option_id` | string | yes | Shipping option ID (so_…) |
| `name` | string |  | at least 1 characters |
| `shipping_profile_id` | string |  |  |
| `price_type` | string |  | one of "flat", "calculated" |
| `prices` | list of object |  |  |
| `prices[].id` | string |  |  |
| `prices[].currency_code` | string |  |  |
| `prices[].region_id` | string |  |  |
| `prices[].amount` | number |  | at least 0 |
| `type_id` | string |  |  |
| `rules` | object |  |  |
| `rules.create` | list of object |  |  |
| `rules.create[].attribute` | string | yes | e.g. enabled_in_store or is_return |
| `rules.create[].operator` | string | yes | one of "in", "eq", "ne", "gt", "gte", "lt", "lte", "nin" |
| `rules.create[].value` | string or list of string | yes |  |
| `rules.update` | list of object |  |  |
| `rules.update[].attribute` | string | yes | e.g. enabled_in_store or is_return |
| `rules.update[].operator` | string | yes | one of "in", "eq", "ne", "gt", "gte", "lt", "lte", "nin" |
| `rules.update[].value` | string or list of string | yes |  |
| `rules.update[].id` | string | yes |  |

Example input:

```json
{
  "shipping_option_id": "019bb70f-16d0-75b7-bdb6-d22f3f99c289",
  "prices": [
    {
      "currency_code": "huf",
      "amount": 1990
    }
  ]
}
```

### `shipping_profile_create` [#shipping_profile_create]

Add a group for products that ship the same way, e.g. bulky items.

- Action key: `shipping_profile.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 |
| --- | --- | --- | --- |
| `name` | string | yes | at least 1 characters |
| `type` | string | yes | e.g. default or bulky. at least 1 characters |

Example input:

```json
{
  "name": "Bulky items",
  "type": "bulky"
}
```

### `shipping_profile_delete` [#shipping_profile_delete]

Delete a shipping profile that no product or shipping option uses.

- Action key: `shipping_profile.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 |
| --- | --- | --- | --- |
| `shipping_profile_id` | string | yes | Shipping profile ID (sp_…) |

Example input:

```json
{
  "shipping_profile_id": "019bb73d-bcc5-7993-83c9-5c9a9f7ada5a"
}
```

### `shipping_profile_update` [#shipping_profile_update]

Rename a shipping profile or change its type.

- Action key: `shipping_profile.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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipping_profile_id` | string | yes | Shipping profile ID (sp_…) |
| `name` | string |  | at least 1 characters |
| `type` | string |  | at least 1 characters |

Example input:

```json
{
  "shipping_profile_id": "019bb73d-bcc5-7993-83c9-5c9a9f7ada5a",
  "name": "Furniture"
}
```