docs: clarify ISO format for province codes (#12282)

* docs: clarify ISO format for province codes

* regenerate
This commit is contained in:
Shahed Nasser
2025-04-24 15:44:35 +03:00
committed by GitHub
parent cb16f79b8f
commit 97daa5a41c
39 changed files with 14830 additions and 14654 deletions

File diff suppressed because it is too large Load Diff

View File

@@ -39,6 +39,12 @@ A service zone is represented by the [ServiceZone data model](/references/fulfil
A service zone can have multiple geographical zones, each represented by the [GeoZone data model](/references/fulfillment/models/GeoZone). It holds location-related details to narrow down supported areas, such as country, city, or province code.
<Note title="Tip">
The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
</Note>
---
## Shipping Profile

View File

@@ -26,6 +26,12 @@ For example, a fulfillment provider may have a shipping option that can be used
Service zones can be more restrictive, such as restricting to certain cities or province codes.
<Note title="Tip">
The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
</Note>
![A diagram showcasing the relation between shipping options, service zones, and geo zones](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331186/Medusa%20Resources/shipping-option-service-zone-city_m5sxod.jpg)
---

View File

@@ -56,7 +56,7 @@ You also must pass at least one of the following query parameters to retrieve an
`province`
</Table.Cell>
<Table.Cell>
The province, which can be taken from a customer's address. This parameter helps further narrowing down the taxes applied on a the product variant's prices.
The lower-case [ISO 3166-2 province code](https://en.wikipedia.org/wiki/ISO_3166-2), which can be taken from a customer's address. This parameter helps further narrowing down the taxes applied on a the product variant's prices.
</Table.Cell>
</Table.Row>
<Table.Row>

View File

@@ -20,11 +20,11 @@ export const generatedEditDates = {
"app/commerce-modules/customer/page.mdx": "2025-04-17T08:48:31.918Z",
"app/commerce-modules/fulfillment/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/fulfillment/_events/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/fulfillment/concepts/page.mdx": "2024-06-19T13:02:16+00:00",
"app/commerce-modules/fulfillment/concepts/page.mdx": "2025-04-24T09:21:37.616Z",
"app/commerce-modules/fulfillment/fulfillment-provider/page.mdx": "2025-02-26T11:21:56.242Z",
"app/commerce-modules/fulfillment/item-fulfillment/page.mdx": "2024-10-08T14:38:15.496Z",
"app/commerce-modules/fulfillment/module-options/page.mdx": "2024-10-15T12:51:56.118Z",
"app/commerce-modules/fulfillment/shipping-option/page.mdx": "2025-04-17T13:51:40.980Z",
"app/commerce-modules/fulfillment/shipping-option/page.mdx": "2025-04-24T09:21:52.540Z",
"app/commerce-modules/fulfillment/page.mdx": "2025-04-17T08:48:19.367Z",
"app/commerce-modules/inventory/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/inventory/_events/page.mdx": "2024-07-03T19:27:13+03:00",
@@ -168,7 +168,7 @@ export const generatedEditDates = {
"app/storefront-development/products/price/examples/sale-price/page.mdx": "2025-03-27T14:47:14.308Z",
"app/storefront-development/products/price/examples/show-price/page.mdx": "2025-03-27T14:47:14.292Z",
"app/storefront-development/products/price/examples/tax-price/page.mdx": "2025-03-27T14:47:14.292Z",
"app/storefront-development/products/price/page.mdx": "2025-03-26T12:08:16.029Z",
"app/storefront-development/products/price/page.mdx": "2025-04-24T09:25:43.094Z",
"app/storefront-development/products/retrieve/page.mdx": "2025-03-27T14:46:51.433Z",
"app/storefront-development/products/variants/page.mdx": "2025-03-27T14:46:51.576Z",
"app/storefront-development/products/page.mdx": "2024-06-11T19:55:56+02:00",

View File

@@ -150,7 +150,7 @@ To create a sublevel tax region in a tax region:
2. In the "Sublevels" section or its equivalent (such as States, Province, or Cantons), click the "Create" button.
3. In the form that opens:
- If the country supports a sublevel by default, you'll find an input to select a state, province, or canton.
- If the country doesn't support a sublevel by default, you'll find an input to enter the ISO 3166-2 code of the sublevel.
- If the country doesn't support a sublevel by default, you'll find an input to enter the lower-case [ISO 3166-2 code](https://en.wikipedia.org/wiki/ISO_3166-2) of the sublevel.
- Under the "Default tax rate" section, you can optionally enter a name, tax rate, and tax code in their respective fields.
- If the tax region's rates should be combined with the parent's rates, enable the "Combinable" toggle.
4. Once you're done, click the Save button.

View File

@@ -110,13 +110,21 @@
* oneOf:
* - type: string
* title: province
* description: Filter by a province.
* description: Filter by an ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* - type: array
* description: Filter by provinces.
* description: Filter by ISO 3166-2 provinces.
* items:
* type: string
* title: province
* description: A province code.
* description: A ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* - name: postal_code
* in: query
* required: false

View File

@@ -133,13 +133,21 @@
* oneOf:
* - type: string
* title: province_code
* description: Filter by a province code.
* description: Filter by a ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* - type: array
* description: Filter by province codes.
* description: Filter by ISO 3166-2 province codes.
* items:
* type: string
* title: province_code
* description: A province code.
* description: A ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* - type: object
* description: Apply filters on the province code.
* properties:

View File

@@ -94,7 +94,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code
@@ -151,7 +155,7 @@
* "address_2": "{value}",
* "city": "{value}",
* "country_code": "{value}",
* "province": "{value}",
* "province": "us-ca",
* "postal_code": "{value}",
* "phone": "{value}",
* "metadata": {}

View File

@@ -100,7 +100,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -107,7 +107,11 @@
* province:
* type: string
* title: province
* description: The billing address's province.
* description: The billing address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code
@@ -166,7 +170,11 @@
* province:
* type: string
* title: province
* description: The shipping address's province.
* description: The shipping address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -88,7 +88,11 @@
* province_code:
* type: string
* title: province_code
* description: The geo zone's province code.
* description: The geo zone's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* - type: object
* description: A city geo zone
* required:
@@ -113,7 +117,11 @@
* province_code:
* type: string
* title: province_code
* description: The geo zone's province code.
* description: The geo zone's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* city:
* type: string
* title: city
@@ -143,7 +151,11 @@
* province_code:
* type: string
* title: province_code
* description: The geo zone's province code.
* description: The geo zone's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* city:
* type: string
* title: city

View File

@@ -96,7 +96,11 @@
* province_code:
* type: string
* title: province_code
* description: The geo zone's province code.
* description: The geo zone's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* id:
* type: string
* title: id
@@ -129,7 +133,11 @@
* province_code:
* type: string
* title: province_code
* description: The geo zone's province code.
* description: The geo zone's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* id:
* type: string
* title: id
@@ -163,7 +171,11 @@
* province_code:
* type: string
* title: province_code
* description: The geo zone's province code.
* description: The geo zone's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_expression:
* type: object
* description: The geo zone's postal expression or ZIP code.

View File

@@ -79,7 +79,7 @@
* "address_2": "{value}",
* "city": "{value}",
* "country_code": "{value}",
* "province": "{value}",
* "province": "us-ca",
* "postal_code": "{value}",
* "metadata": {}
* },

View File

@@ -42,7 +42,7 @@
*
* sdk.admin.taxRegion.create({
* country_code: "us",
* province_code: "ca",
* province_code: "us-ca",
* default_tax_rate: {
* code: "VAT",
* name: "VAT",
@@ -61,7 +61,7 @@
* -H 'Content-Type: application/json' \
* --data-raw '{
* "country_code": "{value}",
* "province_code": "{value}",
* "province_code": "us-ca",
* "parent_id": "{value}",
* "metadata": {}
* }'

View File

@@ -654,12 +654,16 @@
* description: "Storefront guide: How to show product variants' prices with taxes."
* - name: province
* in: query
* description: The province the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
* description: The lower-case ISO 3166-2 province code the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
* required: false
* schema:
* type: string
* title: province
* description: The province the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
* description: The lower-case ISO 3166-2 province code the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* - name: sales_channel_id
* in: query
* required: false

View File

@@ -55,12 +55,16 @@
* description: The country code the product is being viewed from. This is required if you're retrieving product variant prices with taxes.
* - name: province
* in: query
* description: The province the product is being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
* description: The lower-case ISO 3166-2 province code the product is being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
* required: false
* schema:
* type: string
* title: province
* description: The province the product is being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
* description: The lower-case ISO 3166-2 province code the product is being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* - name: cart_id
* in: query
* description: The ID of the customer's cart. If set, the cart's region and shipping address's country code and province are used instead of the `region_id`, `country_code`, and `province` properties.

View File

@@ -76,7 +76,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code
@@ -137,7 +141,7 @@
* "address_2": "{value}",
* "city": "{value}",
* "country_code": "{value}",
* "province": "{value}",
* "province": "us-ca",
* "postal_code": "{value}",
* "address_name": "{value}"
* }'

View File

@@ -82,7 +82,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -60,7 +60,11 @@
* province:
* type: string
* title: province
* description: The delivery address's province.
* description: The delivery address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -14,7 +14,11 @@
* province_code:
* type: string
* title: province_code
* description: The tax region's province code.
* description: The tax region's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* parent_id:
* type: string
* title: parent_id

View File

@@ -75,7 +75,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -60,7 +60,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -33,7 +33,11 @@
* province_code:
* type: string
* title: province_code
* description: The geo zone's province code.
* description: The geo zone's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* city:
* type: string
* title: city

View File

@@ -55,7 +55,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -40,7 +40,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* required:
* - id
* - address_1

View File

@@ -29,7 +29,11 @@
* province_code:
* type: string
* title: province_code
* description: The tax region's province code.
* description: The tax region's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* metadata:
* type: object
* description: The tax region's metadata, can hold custom key-value pairs.

View File

@@ -49,7 +49,11 @@
* province:
* type: string
* title: province
* description: The shipping address's province.
* description: The shipping address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code
@@ -97,7 +101,11 @@
* province:
* type: string
* title: province
* description: The billing address's province.
* description: The billing address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -49,7 +49,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code
@@ -97,7 +101,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -47,7 +47,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* address_id:
* type: string
* title: address_id

View File

@@ -7,7 +7,11 @@
* province_code:
* type: string
* title: province_code
* description: The tax region's province code.
* description: The tax region's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* metadata:
* type: object
* description: The tax region's metadata, can hold custom key-value pairs.

View File

@@ -39,7 +39,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
*
*/

View File

@@ -53,7 +53,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's lower-case ISO 3166-2 province code.
* example: "US-CA"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -40,7 +40,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -52,7 +52,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -52,7 +52,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -75,7 +75,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -55,7 +55,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's lower-case ISO 3166-2 province code.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code

View File

@@ -46,7 +46,11 @@
* province:
* type: string
* title: province
* description: The address's province.
* description: The address's ISO 3166-2 province code. Must be lower-case.
* example: "us-ca"
* externalDocs:
* url: https://en.wikipedia.org/wiki/ISO_3166-2
* description: Learn more about ISO 3166-2
* postal_code:
* type: string
* title: postal_code