Create a shipping option (shipping cost)

Adds a shipping option to the table. See ShippingOptionInput for how rate_mode decides the price.

POST/shipping_tables/{shipping_table_id}/shipping_options

Authorization

AuthorizationBearer token (JWT) · headerrequired

Path parameters

shipping_table_idintegerrequired

Request body

requiredapplication/json

namestring

Name shown to buyers at checkout. Required on create.

rate_modestring

Required on create.

Allowed:flatby-weightby-stretchby-distanceby-weight-step

activeboolean

default: true

courierstring | null

exclusiveboolean

When true, buyers in this option's regions/localities don't see broader options. Only for region or locality zones, and not overlapping another exclusive option of the table.

price_list_idinteger | null

Only for orders with this price list. -1 any price list, -2 orders without a price list, null all orders.

base_rateinteger

rate_per_kminteger | null

rate_per_weight_stepinteger | null

weight_step_in_grinteger | null

over_weight_amount_per_kginteger

Amount per extra kg over max_allowed_weight_in_gr (or the last rate). -1 means heavier orders can't use this option.

default: -1

max_allowed_weight_in_grinteger | null

min_days_to_deliveryinteger | null

Business days. Must be lower than max_days_to_delivery.

max_days_to_deliveryinteger | null

cutoff_timestring | null

availability_schedule_idinteger | null

Must belong to the seller.

delivery_window_schedule_idinteger | null

Must belong to the seller.

polygon_set_idinteger | null

Polygon set limiting the zone. Must belong to the seller.

polygons_exclude_modeboolean

Exclude (instead of include) the polygon set area.

shipping_zonesShippingZone[]

Zones covered, all at the same level: country (only country_code), region (country_code + region_code, one country) or locality (all three, one country and region). Required on create; on update it replaces the zones.

Show properties

Array of ShippingZone

country_codestringrequired

ISO 3166 alpha-2 country code (upcased on input)

region_codestring | null

Region code within the country. Set it on every zone for a region-level option.

locality_idinteger | null

Locality (comuna) ID. Set it on every zone for a locality-level option.

shipping_ratesShippingRate[]

Only for by-weight and by-stretch (required for them on create, or when switching to them). On update it replaces all rates.

Show properties

Array of ShippingRate

tonumberrequired

Upper bound of the range, in grams (by-weight) or km (by-stretch). Ranges start at 0 or at the previous to.

amountintegerrequired

Amount charged for the range, in the seller's currency.

Examples

{
  "name": "Envío a Santiago",
  "rate_mode": "flat",
  "base_rate": 3990,
  "courier": "Starken",
  "min_days_to_delivery": 1,
  "max_days_to_delivery": 3,
  "shipping_zones": [
    {
      "country_code": "CL",
      "region_code": "RM"
    }
  ]
}

{
  "name": "Envío por peso",
  "rate_mode": "by-weight",
  "shipping_zones": [
    {
      "country_code": "CL",
      "region_code": "RM",
      "locality_id": 13101
    },
    {
      "country_code": "CL",
      "region_code": "RM",
      "locality_id": 13114
    }
  ],
  "shipping_rates": [
    {
      "to": 1000,
      "amount": 2500
    },
    {
      "to": 5000,
      "amount": 4500
    }
  ]
}

Responses

201

Shipping option created

namestring

Name shown to buyers at checkout. Required on create.

rate_modestring

Required on create.

Allowed:flatby-weightby-stretchby-distanceby-weight-step

activeboolean

default: true

courierstring | null

exclusiveboolean

When true, buyers in this option's regions/localities don't see broader options. Only for region or locality zones, and not overlapping another exclusive option of the table.

price_list_idinteger | null

Only for orders with this price list. -1 any price list, -2 orders without a price list, null all orders.

base_rateinteger

rate_per_kminteger | null

rate_per_weight_stepinteger | null

weight_step_in_grinteger | null

over_weight_amount_per_kginteger

Amount per extra kg over max_allowed_weight_in_gr (or the last rate). -1 means heavier orders can't use this option.

default: -1

max_allowed_weight_in_grinteger | null

min_days_to_deliveryinteger | null

Business days. Must be lower than max_days_to_delivery.

max_days_to_deliveryinteger | null

cutoff_timestring | null

availability_schedule_idinteger | null

Must belong to the seller.

delivery_window_schedule_idinteger | null

Must belong to the seller.

polygon_set_idinteger | null

Polygon set limiting the zone. Must belong to the seller.

polygons_exclude_modeboolean

Exclude (instead of include) the polygon set area.

shipping_zonesShippingZone[]

Show properties

Array of ShippingZone

idinteger

country_codestringrequired

ISO 3166 alpha-2 country code (upcased on input)

region_codestring | null

Region code within the country. Set it on every zone for a region-level option.

locality_idinteger | null

Locality (comuna) ID. Set it on every zone for a locality-level option.

shipping_ratesShippingRate[]

Only for by-weight and by-stretch (required for them on create, or when switching to them). On update it replaces all rates.

Show properties

Array of ShippingRate

idinteger

tonumberrequired

Upper bound of the range, in grams (by-weight) or km (by-stretch). Ranges start at 0 or at the previous to.

amountintegerrequired

Amount charged for the range, in the seller's currency.

_linksHalLinks

idinteger

shipping_table_idinteger

created_atstring<date-time>

updated_atstring<date-time>

_embeddedobject

Show properties

shipping_zonesShippingZone[]

Show properties

Array of ShippingZone

idinteger

country_codestringrequired

ISO 3166 alpha-2 country code (upcased on input)

region_codestring | null

Region code within the country. Set it on every zone for a region-level option.

locality_idinteger | null

Locality (comuna) ID. Set it on every zone for a locality-level option.

shipping_ratesShippingRate[]

Show properties

Array of ShippingRate

idinteger

tonumberrequired

Upper bound of the range, in grams (by-weight) or km (by-stretch). Ranges start at 0 or at the previous to.

amountintegerrequired

Amount charged for the range, in the seller's currency.

403

Access denied

422

Validation errors, e.g. missing shipping_zones, zones at mixed levels, shipping_rates missing for by-weight/by-stretch (or sent for another mode), base_rate 0 on a flat option, or a price_list_id/schedule/polygon set of another seller.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Parameters

shipping_table_idpath*

Bodyapplication/json

Request body

Request

curl -X POST 'https://api.onbolder.com/v2/shipping_tables/0/shipping_options' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Envío a Santiago",
  "rate_mode": "flat",
  "base_rate": 3990,
  "courier": "Starken",
  "min_days_to_delivery": 1,
  "max_days_to_delivery": 3,
  "shipping_zones": [
    {
      "country_code": "CL",
      "region_code": "RM"
    }
  ]
}'

const response = await fetch("https://api.onbolder.com/v2/shipping_tables/0/shipping_options", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"name\": \"Envío a Santiago\",\n  \"rate_mode\": \"flat\",\n  \"base_rate\": 3990,\n  \"courier\": \"Starken\",\n  \"min_days_to_delivery\": 1,\n  \"max_days_to_delivery\": 3,\n  \"shipping_zones\": [\n    {\n      \"country_code\": \"CL\",\n      \"region_code\": \"RM\"\n    }\n  ]\n}"
});

import requests

response = requests.post(
    "https://api.onbolder.com/v2/shipping_tables/0/shipping_options",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"name\": \"Envío a Santiago\",\n  \"rate_mode\": \"flat\",\n  \"base_rate\": 3990,\n  \"courier\": \"Starken\",\n  \"min_days_to_delivery\": 1,\n  \"max_days_to_delivery\": 3,\n  \"shipping_zones\": [\n    {\n      \"country_code\": \"CL\",\n      \"region_code\": \"RM\"\n    }\n  ]\n}",
)

Response

{
  "_class": [
    "shippingOption"
  ],
  "_links": {
    "self": {
      "href": "https://api.onbolder.com/v2/shipping_options/1"
    },
    "shops:show_shipping_table": {
      "href": "https://api.onbolder.com/v2/shipping_tables/2"
    },
    "shops:update_shipping_option": {
      "href": "https://api.onbolder.com/v2/shipping_options/1",
      "method": "put"
    },
    "shops:delete_shipping_option": {
      "href": "https://api.onbolder.com/v2/shipping_options/1",
      "method": "delete"
    }
  },
  "id": 1,
  "name": "Por peso a Santiago",
  "active": true,
  "courier": "Starken",
  "exclusive": false,
  "price_list_id": null,
  "rate_mode": "by-weight",
  "base_rate": 0,
  "rate_per_km": null,
  "rate_per_weight_step": null,
  "weight_step_in_gr": null,
  "over_weight_amount_per_kg": -1,
  "max_allowed_weight_in_gr": null,
  "min_days_to_delivery": null,
  "max_days_to_delivery": null,
  "cutoff_time": null,
  "availability_schedule_id": null,
  "delivery_window_schedule_id": null,
  "shipping_table_id": 2,
  "polygon_set_id": null,
  "polygons_exclude_mode": false,
  "created_at": "2026-10-20T13:47:28.000Z",
  "updated_at": "2026-10-20T13:47:28.000Z",
  "_embedded": {
    "shipping_zones": [
      {
        "_class": [
          "shippingZone"
        ],
        "id": 1,
        "locality_id": null,
        "region_code": "RM",
        "country_code": "CL"
      }
    ],
    "shipping_rates": [
      {
        "_class": [
          "shippingRate"
        ],
        "id": 1,
        "to": 1000,
        "amount": 2500
      },
      {
        "_class": [
          "shippingRate"
        ],
        "id": 2,
        "to": 5000,
        "amount": 4500
      }
    ]
  }
}