# Update a shipping method

URL: https://docs.sparklayer.io/developers/api/shipping/update-a-shipping-method
Operation: `PATCH /api/v2/shipping-methods/{id}` (operationId `updateShippingMethod`)
OpenAPI spec: https://docs.sparklayer.io/openapi/shipping.yaml

Updates a shipping method and returns it. Fields you omit keep their current values, fields that are set are treated as the source of truth. For instance, sending an empty bands list will delete all current bands, while not sending a locations object will keep current location mappings. Returns `404` if the shipping method doesn't exist.

`PATCH /api/v2/shipping-methods/{id}`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X PATCH "https://app.sparklayer.io/api/v2/shipping-methods/2ca21c1b-2135-4f3e-8cfb-0ff43261a11a" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "slug_001",
  "title": "Standard Shipping",
  "priority": 0,
  "locations": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "requirement": {
        "type": "weight",
        "min_grams": 0,
        "max_grams": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Shipping Method UUID. Example: `2ca21c1b-2135-4f3e-8cfb-0ff43261a11a` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | | **Deprecated.** Shipping slug. Length: max 50. |
| `title` | string | | Shiping Method Name shown at checkout. Length: max 50. |
| `priority` | integer | | Shown by order (lower first). Default: `0`. Min 0, max 127. |
| `locations` | object | | Locations covered by this shipping method Keys are country codes (ISO 3166-1 alpha-2) Values are lists of region codes. If the list is empty, all regions are allowed |
| `groups` | string[] | | Customer groups covered by this shipping method (use "default" to cover all groups) |
| `bands` | object[] | | |
| `bands[].name` | string | | Internal Band Name. Length: max 50. |
| `bands[].priority` | integer | | Order of precedence (lower first). Default: `0`. Min 0, max 127. |
| `bands[].requirement` | ShippingMethod.Requirement.Weight \| ShippingMethod.Requirement.NetTotal \| ShippingMethod.Requirement.None | | The band is selected based on the requirement. |
| `bands[].cost` | ShippingMethod.Cost.Free \| ShippingMethod.Cost.FixedCost \| ShippingMethod.Cost.PercentNetTotal \| ShippingMethod.Cost.Custom | | |

```json
{
  "slug": "slug_001",
  "title": "Standard Shipping",
  "priority": 0,
  "locations": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "requirement": {
        "type": "weight",
        "min_grams": 0,
        "max_grams": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}
```

### Responses

#### 200: Successful response

The `ShippingMethod` object: the request body's fields, plus:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | | Shipping Method UUID |
| `created_at` | string (date-time) | | Created At |
| `updated_at` | string (date-time) | | Updated At |

```json
{
  "id": "2ca21c1b-2135-4f3e-8cfb-0ff43261a11a",
  "created_at": "2026-01-31T09:00:00Z",
  "updated_at": "2026-01-31T09:00:00Z",
  "slug": "slug_001",
  "title": "Standard Shipping",
  "priority": 0,
  "locations": {},
  "groups": [
    "default"
  ],
  "bands": [
    {
      "name": "Band 1",
      "priority": 0,
      "requirement": {
        "type": "weight",
        "min_grams": 0,
        "max_grams": 0
      },
      "cost": {
        "type": "free"
      }
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```