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

* docs: clarify ISO format for province codes * regenerate
2025-04-24 15:44:35 +03:00
parent cb16f79b8f
commit 97daa5a41c
39 changed files with 14830 additions and 14654 deletions
@@ -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
@@ -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)
 ---
@@ -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>
@@ -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",
@@ -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.
@@ -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
@@ -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:
@@ -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": {}
@@ -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
@@ -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
@@ -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
@@ -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.
@@ -79,7 +79,7 @@
 *           "address_2": "{value}",
 *           "city": "{value}",
 *           "country_code": "{value}",
- *           "province": "{value}",
+ *           "province": "us-ca",
 *           "postal_code": "{value}",
 *           "metadata": {}
 *         },
@@ -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": {}
 *       }'
@@ -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
@@ -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.
@@ -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}"
 *       }'
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
@@ -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
@@ -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
@@ -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
@@ -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.
@@ -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
 * 
 */
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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