> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WooCommerce shipping zones and tax rate configuration

> Manage WooCommerce shipping zones, regions, and methods, and create or update tax rates by country and state using Maxi AI Core Pro abilities.

Shipping and tax rate abilities let your AI agent configure the logistics side of your WooCommerce store — creating shipping zones with geographic region restrictions, adding flat rate, free shipping, or local pickup methods to those zones, and managing country- and state-level tax rates. All abilities in this group require an active **Pro** plan, **WooCommerce** to be installed and active, and the `manage_woocommerce` capability on the connected WordPress user.

<Info>
  All WooCommerce shipping and tax abilities require WooCommerce to be active and a **Pro** plan license. The connected WordPress user must have the `manage_woocommerce` capability — typically assigned to the **Shop Manager** or **Administrator** role.
</Info>

## Shipping abilities

| Ability                       | Description                                                                | Capability           | Plan |
| ----------------------------- | -------------------------------------------------------------------------- | -------------------- | ---- |
| `maxi/list-shipping-zones`    | List all shipping zones with regions, methods, and full instance settings. | `manage_woocommerce` | Pro  |
| `maxi/create-shipping-zone`   | Create a shipping zone with region restrictions.                           | `manage_woocommerce` | Pro  |
| `maxi/add-shipping-method`    | Add a shipping method to a zone.                                           | `manage_woocommerce` | Pro  |
| `maxi/update-shipping-method` | Update an existing shipping method instance.                               | `manage_woocommerce` | Pro  |

## Tax rate abilities

| Ability                | Description                                              | Capability           | Plan |
| ---------------------- | -------------------------------------------------------- | -------------------- | ---- |
| `maxi/create-tax-rate` | Create a tax rate for a country or state.                | `manage_woocommerce` | Pro  |
| `maxi/list-tax-rates`  | List tax rates with optional filters.                    | `manage_woocommerce` | Pro  |
| `maxi/update-tax-rate` | Update an existing tax rate. Send only fields to change. | `manage_woocommerce` | Pro  |
| `maxi/delete-tax-rate` | Delete a tax rate permanently.                           | `manage_woocommerce` | Pro  |

## Shipping zone examples

### maxi/list-shipping-zones

Returns every shipping zone on your site, including each zone's regions and its configured shipping methods. Each method's full instance settings — cost, tax status, title, minimum order amount, and so on — are included in the response. Read this first before calling `maxi/update-shipping-method` so you have the correct `zone_id` and `instance_id` values.

```json theme={null}
{}
```

### maxi/create-shipping-zone

Create a new shipping zone. Provide a name and an array of region codes (ISO 3166-1 alpha-2 country codes, or country + state codes like `"US:CA"` for California).

```json theme={null}
{
  "name": "North America",
  "regions": [
    {"code": "US", "type": "country"},
    {"code": "CA", "type": "country"},
    {"code": "MX", "type": "country"}
  ]
}
```

### maxi/add-shipping-method

Add a shipping method to an existing zone. WooCommerce supports three built-in method IDs:

| Method ID       | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| `flat_rate`     | Fixed cost per shipment, with optional formula support       |
| `free_shipping` | Free delivery — can require a coupon or minimum order amount |
| `local_pickup`  | In-store or local pickup option                              |

```json theme={null}
{"zone_id": 1, "method_type": "flat_rate"}
```

### maxi/update-shipping-method

Update the settings of an existing shipping method instance. The `settings` object is a partial merge — keys you omit are left unchanged. Call `maxi/list-shipping-zones` first to confirm the current settings and get the correct `instance_id`.

```json theme={null}
{"instance_id": 2, "settings": {"cost": "14.99"}}
```

<Note>
  Available setting keys vary by method type. `flat_rate` supports `cost`, `title`, and `tax_status`. `free_shipping` supports `title`, `min_amount`, and `requires`. `local_pickup` supports `title`, `cost`, and `tax_status`. Read the current settings via `maxi/list-shipping-zones` before updating to avoid overwriting unknown fields.
</Note>

<Steps>
  <Step title="Read existing zones and methods">
    Call `maxi/list-shipping-zones` with an empty input. Review the returned zones, their region codes, and each method's `instance_id` and current settings.
  </Step>

  <Step title="Create or update zones">
    Use `maxi/create-shipping-zone` to add a new zone, or update regions on an existing zone.
  </Step>

  <Step title="Add or update shipping methods">
    Use `maxi/add-shipping-method` to attach a method to a zone, or `maxi/update-shipping-method` to change settings on an existing method instance.
  </Step>
</Steps>

## Tax rate examples

### maxi/create-tax-rate

Create a tax rate for a specific country and state. Set `compound` to `true` if this rate should be calculated on top of other taxes already applied.

```json theme={null}
{
  "country": "US",
  "state": "CA",
  "rate": "8.25",
  "name": "California State Tax",
  "compound": false
}
```

### maxi/list-tax-rates

List all tax rates on your store, with optional filters. Filter by country to narrow down results for a specific region.

```json theme={null}
{ "country": "US" }
```

### maxi/update-tax-rate

Update an existing tax rate. Send only the fields you want to change. Boolean fields such as `compound` and `shipping` can be set to `false` to disable them.

```json theme={null}
{
  "tax_rate_id": 5, 
  "rate": "8.50"
}
```

### maxi/delete-tax-rate

Delete a tax rate permanently by its numeric ID.

<Warning>
  `maxi/delete-tax-rate` removes the tax rate immediately and permanently. Customers checking out after deletion will no longer have that rate applied to their orders.
</Warning>