# Create a shipping method

URL: https://docs.sparklayer.io/developers/api/shipping/create-a-shipping-method
Operation: `POST /api/v2/shipping-methods` (operationId `createShippingMethod`)
OpenAPI spec: https://docs.sparklayer.io/openapi/shipping.yaml

Creates a shipping method, including its bands, and returns it with its UUID.

`POST /api/v2/shipping-methods`

**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 POST "https://app.sparklayer.io/api/v2/shipping-methods" \
  -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`.

### 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 | Yes | Shiping Method Name shown at checkout. Length: max 50. |
| `priority` | integer | | Shown by order (lower first). Default: `0`. Min 0, max 127. |
| `locations` | object | Yes | 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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | | Shipping Method UUID |
| `created_at` | string (date-time) | | Created At |
| `updated_at` | string (date-time) | | Updated At |
| `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
{
  "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"
}
```