---
title: "Create shipping zone (V2)"
method: POST
path: "/api/sites/multiscreen/{site_name}/ecommerce/shipping-zones-v2"
tags: ["Shipping Zones V2"]
---

# Create shipping zone (V2)

`POST /api/sites/multiscreen/{site_name}/ecommerce/shipping-zones-v2`

## Request

- Base URL: `https://api.duda.co`
- URL: `https://api.duda.co/api/sites/multiscreen/{site_name}/ecommerce/shipping-zones-v2`
- Auth: HTTP basic

Creates a v2 shipping zone for the site from the given name, locations, subzones, and pickup locations, plus an optional Easyship automated shipping flag. An empty locations list makes the zone the account's international catch-all; postal code scoping and shipping methods live in each subzone rather than on the zone itself, so a zone with no postal scoping states that as a single subzone with no patterns. Returns the created zone.

## Path parameters

- `site_name` string, required

## Request body

- ExternalCreateShippingZoneV2RequestDto: The whole content of a v2 shipping zone. Unlike Snipcart.Api.Web.External.Dtos.Requests.Shipping.ExternalCreateShippingZoneRequestDto, postal code scoping and shipping methods live in subzones rather than on the zone itself, so a zone that does not scope by postal code states that as a single subzone with no patterns.
  - `name` string, required: Merchant-facing internal name of the shipping zone.
  - `locations` ExternalCreateShippingZoneLocationRequestDto[], required: Locations where the shipping zone applies. Required: an explicitly empty list makes the zone the account's international catch-all, of which an account can hold only one, so omitting the property is rejected rather than read as that.
    - `country` string, required: ISO 3166-2 country code where the shipping zone applies
    - `region` string, nullable: ISO 3166-2 region code where the shipping zone applies. Can be left empty to apply to the whole country.
  - `subzones` ExternalCreateShippingSubzoneRequestDto[], required: Subzones scoping postal code patterns and the shipping methods they own. At least one is required.
    - `postal_codes_patterns` string[], required: Postal codes, and partial postal code patterns ending with '*', scoped to this subzone. Empty means the subzone applies to every postal code its zone covers.
    - `shipping_methods` ExternalCreateShippingMethodV2RequestDto[], required: Shipping methods offered by this subzone. A subzone with no method offers no way to ship, which is how a merchant excludes the postal codes it scopes.
      - `name` string, required: Display name for the method at checkout.
      - `type` 'UNKNOWN' | 'FREE' | 'FLAT_RATE' | 'CART_PRICE_BASED' | 'CART_WEIGHT_BASED', required
      - `rates` ExternalShippingMethodRateRequestDto[], required: Array of rates. Min one required except for type FREE (none). Max one for type FLAT_RATE.
        - `price` number, double, required: String decimal value of the price the customer must pay for shipping. Must be 0 or above.
        - `min_cart_weight` integer, nullable: Minimum weight in grams of a cart for the rate to be valid. Required when type is CART_WEIGHT_BASED.
        - `max_cart_weight` integer, nullable: Maximum weight in grams of a cart for the rate to be valid. Optional; empty on last rate catches all above defined weight.
        - `min_cart_value` number, double, nullable: Minimum value of the cart's subtotal for the rate to be valid. Required when type is CART_PRICE_BASED.
        - `max_cart_value` number, double, nullable: Maximum value of the cart's subtotal for the rate to be valid. Optional.
      - `min_delivery_time_in_days` integer, nullable: Customer facing minimum delivery time in days. Optional.
      - `max_delivery_time_in_days` integer, nullable: Customer facing maximum delivery time in days. Optional. Cannot be 0 or lower or equal to min. Can be set when min is null.
      - `shipping_group_id` string, nullable: Shipping group this method is offered for. Null or blank, the default, offers it for every product belonging to no group. Anything else must be an existing shipping group id.
  - `has_automated_shipping` boolean: Enables live rates by Easyship for this shipping zone if the store is already configured with Easyship.
  - `pickup_locations` ExternalCreateShippingZonePickupLocationRequestDto[], required: Pickup locations this shipping zone offers at checkout.
    - `name` string, required: Display name of the pickup location.
    - `sync_to_business_address` boolean: Whether the location follows the store's business address. When true, Snipcart.Api.Web.External.Dtos.Requests.Shipping.ExternalCreateShippingZonePickupLocationRequestDto.Address is ignored.
    - `address` BusinessAddressInputDto
      - `address_1` string, required: Number and Street, concatenated
      - `address_2` string, nullable: Address complement (apt #, office #, floor level, etc.)
      - `city` string, required: City name
      - `sub_locality` string, nullable: Neighbourhood
      - `region` string, nullable: The administrative region (depending on country, this can be a state, province, department, etc.)
      - `country` string, required: ISO 3166 2-letters ISO country code. Ref: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes
      - `postal_code` string, nullable: Postal code
      - `phone` string, nullable: Phone number
    - `instructions` string, nullable: Pickup instructions shown to the customer at this location.
    - `scheduling` ExternalPickupSchedulingRequestDto
      - `is_enabled` boolean, required: False turns scheduling off and keeps the rest of the configuration.
      - `weekly_schedule` ExternalPickupDayScheduleRequestDto[], required
        - `day` 'SUNDAY' | 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY', required
        - `is_enabled` boolean
        - `time_windows` ExternalPickupTimeWindowRequestDto[], nullable
          - `start` string, required: 24-hour `HH:mm` time.
          - `end` string, required
      - `date_overrides` ExternalPickupDateOverrideRequestDto[], nullable
        - `start_date` string, date, required: A date in the store time zone, in the `yyyy-MM-dd` format.
        - `end_date` string, date, required: A date in the store time zone, in the `yyyy-MM-dd` format. Inclusive.
        - `time_windows` ExternalPickupTimeWindowRequestDto[], nullable: Null or empty means pickup is unavailable for the whole range.
          - `start` string, required: 24-hour `HH:mm` time.
          - `end` string, required
      - `preparation_time` ExternalPickupSchedulingDurationRequestDto
        - `amount` integer, required
        - `unit` 'HOURS' | 'DAYS' | 'WEEKS' | 'MONTHS', required
      - `max_advance_time` ExternalPickupSchedulingDurationRequestDto
        - `amount` integer, required
        - `unit` 'HOURS' | 'DAYS' | 'WEEKS' | 'MONTHS', required

## Response `201`

Created

- ExternalShippingZoneV2ResponseDto: A v2 shipping zone. Unlike Snipcart.Api.Web.External.Dtos.Responses.Shipping.ExternalShippingZoneResponseDto, both postal code scoping and shipping methods live in subzones rather than on the zone itself; there is always at least one subzone.
  - `id` string: Identifier of the shipping zone. Prefixed with szv2_
  - `name` string: Merchant-facing internal name of the shipping zone.
  - `locations` ExternalShippingZoneLocationResponseDto[]: Locations where the shipping zone applies. Empty means the zone is the international catch-all.
    - `country` string: ISO 3166-2 country code where the shipping zone applies
    - `region` string, nullable: ISO 3166-2 region code where the shipping zone applies. Can be left empty to apply to the whole country.
  - `subzones` ExternalShippingSubzoneResponseDto[]: Subzones scoping postal code patterns and the shipping methods they own. Always at least one.
    - `id` string: Identifier of the subzone. Prefixed with subz_
    - `postal_codes_patterns` string[]: Postal codes, and partial postal code patterns, scoped to this subzone. Empty means the subzone applies to every postal code its zone covers.
    - `shipping_methods` ExternalShippingMethodV2ResponseDto[]: Shipping methods offered by this subzone.
      - `id` string: System identifier generated by duda native ecommerce. Prefixed with sm_.
      - `name` string: Display name for the method at checkout.
      - `type` 'UNKNOWN' | 'FREE' | 'FLAT_RATE' | 'CART_PRICE_BASED' | 'CART_WEIGHT_BASED'
      - `min_delivery_time_in_days` integer, nullable: Customer facing minimum delivery time in days.
      - `max_delivery_time_in_days` integer, nullable: Customer facing maximum delivery time in days.
      - `rates` ExternalShippingMethodRateResponseDto[]: Rates quoted by this method. Empty for a FREE method, which quotes no rate of its own.
        - `price` number, double: String decimal value of the price the customer must pay for shipping.
        - `min_cart_weight` integer, nullable: Minimum weight in grams of a cart for the rate to be valid.
        - `max_cart_weight` integer, nullable: Maximum weight in grams of a cart for the rate to be valid.
        - `min_cart_value` number, double, nullable: Minimum value of the cart's subtotal for the rate to be valid.
        - `max_cart_value` number, double, nullable: Maximum value of the cart's subtotal for the rate to be valid.
      - `shipping_group_id` string, nullable: Shipping group this method is offered for. Null means every product belonging to no group.
  - `has_automated_shipping` boolean: Whether live rates by Easyship are enabled for this shipping zone.
  - `pickup_locations` ExternalShippingZonePickupLocationResponseDto[]: Pickup locations offered by this shipping zone.
    - `id` string: Identifier of the pickup location. Prefixed with pl_
    - `name` string: Display name of the pickup location.
    - `sync_to_business_address` boolean: Whether the location follows the store's business address.
    - `address` BusinessAddressOutputDto
      - `address_1` string, nullable: Number and Street, concatenated
      - `address_2` string, nullable: Address complement (apt #, office #, floor level, etc.)
      - `city` string, nullable: City name
      - `sub_locality` string, nullable
      - `region` string, nullable: The administrative region (depending on country, this can be a state, province, department, etc.)
      - `country` string, nullable: ISO 3166 2-letters ISO country code. Ref: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes
      - `postal_code` string, nullable: Postal code
      - `phone` string, nullable: Phone number of the business
    - `instructions` string, nullable: Pickup instructions shown to the customer at this location.
    - `scheduling` ExternalPickupSchedulingResponseDto
      - `is_enabled` boolean
      - `weekly_schedule` ExternalPickupDayScheduleResponseDto[]
        - `day` 'SUNDAY' | 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY'
        - `is_enabled` boolean
        - `time_windows` ExternalPickupTimeWindowResponseDto[]
          - `start` string
          - `end` string
      - `date_overrides` ExternalPickupDateOverrideResponseDto[]
        - `start_date` string, date
        - `end_date` string, date
        - `time_windows` ExternalPickupTimeWindowResponseDto[]
          - `start` string
          - `end` string
      - `preparation_time` ExternalPickupSchedulingDurationResponseDto
        - `amount` integer
        - `unit` 'HOURS' | 'DAYS' | 'WEEKS' | 'MONTHS'
      - `max_advance_time` ExternalPickupSchedulingDurationResponseDto
        - `amount` integer
        - `unit` 'HOURS' | 'DAYS' | 'WEEKS' | 'MONTHS'
  - `is_catch_all` boolean: Whether this zone applies to every destination not covered by another zone.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Content
- `429`: Too many requests. The rate limit was exceeded.

---

[API](https://skmtc.dev/duda/apis/duda-partner-api.md) - [All operations](https://skmtc.dev/duda/apis/duda-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/duda/apis/duda-partner-api/revisions/52be4d41cb12?raw)