docs: generate OAS with events (#12394)

* docs: generate OAS with events * small change
2025-05-07 14:57:03 +03:00
parent 262064fe96
commit a3bdb3e383
515 changed files with 3808 additions and 189 deletions
--- a/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_products_{id}_options/post.js
+++ b/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_products_{id}_options/post.js
@@ -9,7 +9,7 @@ export const sdk = new Medusa({
 })

 sdk.admin.product.createOption(
-  "prod_123", 
+  "prod_123",
  {
    title: "Color",
    values: ["Green", "Blue"]
--- a/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/post.js
+++ b/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/post.js
@@ -9,7 +9,7 @@ export const sdk = new Medusa({
 })

 sdk.admin.product.updateOption(
-  "prod_123", 
+  "prod_123",
  "prodopt_123",
  {
    title: "Color"
--- a/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_products_{id}_variants_inventory-items_batch/post.js
+++ b/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_products_{id}_variants_inventory-items_batch/post.js
@@ -9,7 +9,7 @@ export const sdk = new Medusa({
 })

 sdk.admin.product.batchVariantInventoryItems(
-  "prod_123", 
+  "prod_123",
  {
    create: [
      {
--- a/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/post.js
+++ b/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/post.js
@@ -9,7 +9,7 @@ export const sdk = new Medusa({
 })

 sdk.admin.product.updateVariant(
-  "prod_123", 
+  "prod_123",
  "variant_123",
    {
    title: "Blue Shirt",
--- a/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_tax-regions_{id}/post.js
+++ b/www/apps/api-reference/specs/admin/code_samples/JavaScript/admin_tax-regions_{id}/post.js
@@ -0,0 +1,16 @@
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
+  debug: import.meta.env.DEV,
+  auth: {
+    type: "session",
+  },
+})
+
+sdk.admin.taxRegion.update("txreg_123", {
+  province_code: "ca",
+})
+.then(({ tax_region }) => {
+  console.log(tax_region)
+})
--- a/www/apps/api-reference/specs/admin/code_samples/Shell/admin_customers_{id}_addresses/post.sh
+++ b/www/apps/api-reference/specs/admin/code_samples/Shell/admin_customers_{id}_addresses/post.sh
@@ -10,7 +10,7 @@ curl -X POST '{backend_url}/admin/customers/{id}/addresses' \
  "address_2": "{value}",
  "city": "{value}",
  "country_code": "{value}",
-  "province": "{value}",
+  "province": "us-ca",
  "postal_code": "{value}",
  "phone": "{value}",
  "metadata": {}
--- a/www/apps/api-reference/specs/admin/code_samples/Shell/admin_fulfillments/post.sh
+++ b/www/apps/api-reference/specs/admin/code_samples/Shell/admin_fulfillments/post.sh
@@ -13,7 +13,7 @@ curl -X POST '{backend_url}/admin/fulfillments' \
    "address_2": "{value}",
    "city": "{value}",
    "country_code": "{value}",
-    "province": "{value}",
+    "province": "us-ca",
    "postal_code": "{value}",
    "metadata": {}
  },
--- a/www/apps/api-reference/specs/admin/code_samples/Shell/admin_tax-regions/post.sh
+++ b/www/apps/api-reference/specs/admin/code_samples/Shell/admin_tax-regions/post.sh
@@ -3,7 +3,7 @@ curl -X POST '{backend_url}/admin/tax-regions' \
 -H 'Content-Type: application/json' \
 --data-raw '{
  "country_code": "{value}",
-  "province_code": "{value}",
+  "province_code": "us-ca",
  "parent_id": "{value}",
  "metadata": {}
 }'
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminCreateFulfillment.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminCreateFulfillment.yaml
@@ -58,7 +58,11 @@ properties:
      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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminCreateTaxRegion.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminCreateTaxRegion.yaml
@@ -12,7 +12,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminCustomerAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminCustomerAddress.yaml
@@ -73,7 +73,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminFulfillmentAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminFulfillmentAddress.yaml
@@ -58,7 +58,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminGeoZone.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminGeoZone.yaml
@@ -31,7 +31,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminOrderAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminOrderAddress.yaml
@@ -53,7 +53,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminStockLocationAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminStockLocationAddress.yaml
@@ -38,7 +38,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminTaxRegion.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminTaxRegion.yaml
@@ -27,7 +27,11 @@ properties:
  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.
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminUpdateDraftOrder.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminUpdateDraftOrder.yaml
@@ -47,7 +47,11 @@ properties:
      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
@@ -95,7 +99,11 @@ properties:
      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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminUpdateOrder.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminUpdateOrder.yaml
@@ -47,7 +47,11 @@ properties:
      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
@@ -95,7 +99,11 @@ properties:
      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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminUpdateStockLocation.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminUpdateStockLocation.yaml
@@ -47,7 +47,11 @@ properties:
      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
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminUpdateTaxRegion.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminUpdateTaxRegion.yaml
@@ -5,7 +5,11 @@ properties:
  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.
--- a/www/apps/api-reference/specs/admin/components/schemas/AdminUpsertStockLocationAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/AdminUpsertStockLocationAddress.yaml
@@ -37,4 +37,8 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/BaseOrderAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/BaseOrderAddress.yaml
@@ -51,7 +51,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/CreateAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/CreateAddress.yaml
@@ -38,7 +38,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/OrderAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/OrderAddress.yaml
@@ -50,7 +50,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/StoreCartAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/StoreCartAddress.yaml
@@ -50,7 +50,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/StoreCustomerAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/StoreCustomerAddress.yaml
@@ -73,7 +73,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/StoreOrderAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/StoreOrderAddress.yaml
@@ -53,7 +53,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/components/schemas/UpdateAddress.yaml
+++ b/www/apps/api-reference/specs/admin/components/schemas/UpdateAddress.yaml
@@ -44,7 +44,11 @@ properties:
  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
--- a/www/apps/api-reference/specs/admin/openapi.full.yaml
+++ b/www/apps/api-reference/specs/admin/openapi.full.yaml
--- a/www/apps/api-reference/specs/admin/paths/admin_api-keys.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_api-keys.yaml
@@ -1337,3 +1337,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createApiKeysWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_api-keys_{id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_api-keys_{id}.yaml
@@ -134,6 +134,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateApiKeysWorkflow
+  x-events: []
 delete:
  operationId: DeleteApiKeysId
  summary: Delete an Api Key
@@ -201,3 +202,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: deleteApiKeysWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_api-keys_{id}_revoke.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_api-keys_{id}_revoke.yaml
@@ -71,3 +71,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: revokeApiKeysWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_api-keys_{id}_sales-channels.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_api-keys_{id}_sales-channels.yaml
@@ -87,3 +87,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: linkSalesChannelsToApiKeyWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_campaigns.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_campaigns.yaml
@@ -271,3 +271,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createCampaignsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_campaigns_{id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_campaigns_{id}.yaml
@@ -196,6 +196,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateCampaignsWorkflow
+  x-events: []
 delete:
  operationId: DeleteCampaignsId
  summary: Delete a Campaign
@@ -264,3 +265,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: deleteCampaignsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_campaigns_{id}_promotions.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_campaigns_{id}_promotions.yaml
@@ -87,3 +87,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: addOrRemoveCampaignPromotionsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims.yaml
@@ -1084,3 +1084,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: beginClaimOrderWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_cancel.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_cancel.yaml
@@ -50,3 +50,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: cancelOrderClaimWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_claim-items.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_claim-items.yaml
@@ -71,3 +71,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: orderClaimItemWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_claim-items_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_claim-items_{action_id}.yaml
@@ -83,6 +83,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateClaimItemWorkflow
+  x-events: []
 delete:
  operationId: DeleteClaimsIdClaimItemsAction_id
  summary: Remove a Claim Item from a Claim
@@ -164,3 +165,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeItemClaimActionWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_inbound_items.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_inbound_items.yaml
@@ -53,3 +53,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: orderClaimRequestItemReturnWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_inbound_items_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_inbound_items_{action_id}.yaml
@@ -67,6 +67,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateRequestItemReturnWorkflow
+  x-events: []
 delete:
  operationId: DeleteClaimsIdInboundItemsAction_id
  summary: Remove an Inbound Item from Claim
@@ -130,3 +131,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeItemReturnActionWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_inbound_shipping-method.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_inbound_shipping-method.yaml
@@ -55,3 +55,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createClaimShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_inbound_shipping-method_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_inbound_shipping-method_{action_id}.yaml
@@ -84,6 +84,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateReturnShippingMethodWorkflow
+  x-events: []
 delete:
  operationId: DeleteClaimsIdInboundShippingMethodAction_id
  summary: Remove Inbound Shipping Method from Claim
@@ -147,3 +148,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeClaimShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_outbound_items.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_outbound_items.yaml
@@ -71,3 +71,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: orderClaimAddNewItemWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_outbound_items_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_outbound_items_{action_id}.yaml
@@ -84,6 +84,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateClaimAddItemWorkflow
+  x-events: []
 delete:
  operationId: DeleteClaimsIdOutboundItemsAction_id
  summary: Remove an Outbound Item from Claim
@@ -165,3 +166,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeAddItemClaimActionWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_outbound_shipping-method.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_outbound_shipping-method.yaml
@@ -73,3 +73,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createClaimShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_outbound_shipping-method_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_outbound_shipping-method_{action_id}.yaml
@@ -84,6 +84,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateClaimShippingMethodWorkflow
+  x-events: []
 delete:
  operationId: DeleteClaimsIdOutboundShippingMethodAction_id
  summary: Remove Outbound Shipping Method from Claim
@@ -165,3 +166,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeClaimShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_request.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_claims_{id}_request.yaml
@@ -64,6 +64,17 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: confirmClaimRequestWorkflow
+  x-events:
+    - name: order.claim_created
+      payload: |-
+        ```ts
+        {
+          order_id, // The ID of the order
+          claim_id, // The ID of the claim
+        }
+        ```
+      description: Emitted when a claim is created for an order.
+      deprecated: false
 delete:
  operationId: DeleteClaimsIdRequest
  summary: Cancel Claim Request
@@ -111,3 +122,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: cancelBeginOrderClaimWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_collections.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_collections.yaml
@@ -1040,3 +1040,13 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createCollectionsWorkflow
+  x-events:
+    - name: product-collection.created
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the product collection
+        }]
+        ```
+      description: Emitted when product collections are created.
+      deprecated: false
--- a/www/apps/api-reference/specs/admin/paths/admin_collections_{id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_collections_{id}.yaml
@@ -134,6 +134,16 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateCollectionsWorkflow
+  x-events:
+    - name: product-collection.updated
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the product collection
+        }]
+        ```
+      description: Emitted when product collections are updated.
+      deprecated: false
 delete:
  operationId: DeleteCollectionsId
  summary: Delete a Collection
@@ -181,3 +191,13 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: deleteCollectionsWorkflow
+  x-events:
+    - name: product-collection.deleted
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the product collection
+        }]
+        ```
+      description: Emitted when product collections are deleted.
+      deprecated: false
--- a/www/apps/api-reference/specs/admin/paths/admin_collections_{id}_products.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_collections_{id}_products.yaml
@@ -87,3 +87,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: batchLinkProductsToCollectionWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_customer-groups.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_customer-groups.yaml
@@ -1090,3 +1090,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createCustomerGroupsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_customer-groups_{id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_customer-groups_{id}.yaml
@@ -134,6 +134,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateCustomerGroupsWorkflow
+  x-events: []
 delete:
  operationId: DeleteCustomerGroupsId
  summary: Delete a Customer Group
@@ -200,3 +201,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: deleteCustomerGroupsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_customer-groups_{id}_customers.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_customer-groups_{id}_customers.yaml
@@ -86,3 +86,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: linkCustomersToCustomerGroupWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_customers.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_customers.yaml
@@ -4337,3 +4337,13 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createCustomersWorkflow
+  x-events:
+    - name: customer.created
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the customer
+        }]
+        ```
+      description: Emitted when a customer is created.
+      deprecated: false
--- a/www/apps/api-reference/specs/admin/paths/admin_customers_{id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_customers_{id}.yaml
@@ -194,6 +194,16 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateCustomersWorkflow
+  x-events:
+    - name: customer.updated
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the customer
+        }]
+        ```
+      description: Emitted when a customer is updated.
+      deprecated: false
 delete:
  operationId: DeleteCustomersId
  summary: Delete a Customer
@@ -259,3 +269,13 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeCustomerAccountWorkflow
+  x-events:
+    - name: customer.deleted
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the customer
+        }]
+        ```
+      description: Emitted when a customer is deleted.
+      deprecated: false
--- a/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_addresses.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_addresses.yaml
@@ -128,13 +128,21 @@ get:
        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
@@ -353,7 +361,11 @@ post:
                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
@@ -406,3 +418,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createCustomerAddressesWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_addresses_{address_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_addresses_{address_id}.yaml
@@ -197,7 +197,11 @@ post:
                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
@@ -252,6 +256,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateCustomerAddressesWorkflow
+  x-events: []
 delete:
  operationId: DeleteCustomersIdAddressesAddress_id
  summary: Remove an Address from Customer
@@ -358,3 +363,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: deleteCustomerAddressesWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_customer-groups.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_customers_{id}_customer-groups.yaml
@@ -100,3 +100,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: linkCustomerGroupsToCustomerWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders.yaml
@@ -1780,6 +1780,7 @@ get:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: getOrdersListWorkflow
+  x-events: []
 post:
  operationId: PostDraftOrders
  summary: Create Draft Order
@@ -1896,7 +1897,13 @@ post:
                    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
@@ -1955,7 +1962,13 @@ post:
                    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
@@ -2141,3 +2154,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createOrderWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}.yaml
@@ -67,6 +67,7 @@ get:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: getOrderDetailWorkflow
+  x-events: []
 post:
  operationId: PostDraftOrdersId
  summary: Update a Draft Order
@@ -142,3 +143,15 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateDraftOrderWorkflow
+  x-events:
+    - name: order.updated
+      payload: |-
+        ```ts
+        {
+          id, // The ID of the order
+        }
+        ```
+      description: |-
+        Emitted when the details of an order or draft order is updated. This
+        doesn't include updates made by an edit.
+      deprecated: false
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_convert-to-order.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_convert-to-order.yaml
@@ -65,3 +65,17 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: convertDraftOrderWorkflow
+  x-events:
+    - name: order.placed
+      payload: |-
+        ```ts
+        {
+          id, // The ID of the order
+        }
+        ```
+      description: >-
+        Emitted when an order is placed, or when a draft order is converted to
+        an
+
+        order.
+      deprecated: false
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit.yaml
@@ -46,6 +46,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: beginDraftOrderEditWorkflow
+  x-events: []
 delete:
  operationId: DeleteDraftOrdersIdEdit
  summary: Cancel Edit on Draft Order
@@ -90,3 +91,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: cancelDraftOrderEditWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_confirm.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_confirm.yaml
@@ -45,3 +45,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: confirmDraftOrderEditWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_items.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_items.yaml
@@ -47,3 +47,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: addDraftOrderItemsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_items_item_{item_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_items_item_{item_id}.yaml
@@ -55,3 +55,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateDraftOrderItemWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_items_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_items_{action_id}.yaml
@@ -62,6 +62,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateDraftOrderActionItemWorkflow
+  x-events: []
 delete:
  operationId: DeleteDraftOrdersIdEditItemsAction_id
  summary: Remove Item from Draft Order Edit
@@ -121,3 +122,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeDraftOrderActionItemWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_promotions.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_promotions.yaml
@@ -52,6 +52,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: addDraftOrderPromotionWorkflow
+  x-events: []
 delete:
  operationId: DeleteDraftOrdersIdEditPromotions
  summary: Remove Promotions from Draft Order Edit
@@ -107,3 +108,4 @@ delete:
      application/json:
        schema:
          $ref: ../components/schemas/AdminRemoveDraftOrderPromotions.yaml
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_request.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_request.yaml
@@ -45,3 +45,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: requestDraftOrderEditWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_shipping-methods.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_shipping-methods.yaml
@@ -49,3 +49,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: addDraftOrderShippingMethodsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_shipping-methods_method_{method_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_shipping-methods_method_{method_id}.yaml
@@ -55,6 +55,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateDraftOrderShippingMethodWorkflow
+  x-events: []
 delete:
  operationId: DeleteDraftOrdersIdEditShippingMethodsMethodMethod_id
  summary: Remove Shipping Method from Draft Order Edit
@@ -107,3 +108,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeDraftOrderShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_shipping-methods_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_edit_shipping-methods_{action_id}.yaml
@@ -62,6 +62,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateDraftOrderActionShippingMethodWorkflow
+  x-events: []
 delete:
  operationId: DeleteDraftOrdersIdEditShippingMethodsAction_id
  summary: Remove New Shipping Method from Draft Order
@@ -121,3 +122,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeDraftOrderActionShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges.yaml
@@ -1037,3 +1037,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: beginExchangeOrderWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_cancel.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_cancel.yaml
@@ -50,3 +50,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: cancelOrderExchangeWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_inbound_items.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_inbound_items.yaml
@@ -54,3 +54,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: orderExchangeRequestItemReturnWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_inbound_items_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_inbound_items_{action_id}.yaml
@@ -67,6 +67,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateRequestItemReturnWorkflow
+  x-events: []
 delete:
  operationId: DeleteExchangesIdInboundItemsAction_id
  summary: Remove Inbound Item from Exchange
@@ -130,3 +131,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeItemReturnActionWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_inbound_shipping-method.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_inbound_shipping-method.yaml
@@ -55,3 +55,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createExchangeShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_inbound_shipping-method_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_inbound_shipping-method_{action_id}.yaml
@@ -84,6 +84,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateReturnShippingMethodWorkflow
+  x-events: []
 delete:
  operationId: DeleteExchangesIdInboundShippingMethodAction_id
  summary: Remove Inbound Shipping Method from Exchange
@@ -147,3 +148,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeReturnShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_outbound_items.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_outbound_items.yaml
@@ -70,3 +70,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: orderExchangeAddNewItemWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_outbound_items_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_outbound_items_{action_id}.yaml
@@ -84,6 +84,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateExchangeAddItemWorkflow
+  x-events: []
 delete:
  operationId: DeleteExchangesIdOutboundItemsAction_id
  summary: Remove Outbound Item from Exchange
@@ -165,3 +166,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeItemExchangeActionWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_outbound_shipping-method.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_outbound_shipping-method.yaml
@@ -73,3 +73,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createExchangeShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_outbound_shipping-method_{action_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_outbound_shipping-method_{action_id}.yaml
@@ -84,6 +84,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateExchangeShippingMethodWorkflow
+  x-events: []
 delete:
  operationId: DeleteExchangesIdOutboundShippingMethodAction_id
  summary: Remove Outbound Shipping Method from Exchange
@@ -165,3 +166,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: removeExchangeShippingMethodWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_request.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_exchanges_{id}_request.yaml
@@ -63,6 +63,17 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: confirmExchangeRequestWorkflow
+  x-events:
+    - name: order.exchange_created
+      payload: |-
+        ```ts
+        {
+          order_id, // The ID of the order
+          exchange_id, // The ID of the exchange
+        }
+        ```
+      description: Emitted when an exchange is created for an order.
+      deprecated: false
 delete:
  operationId: DeleteExchangesIdRequest
  summary: Cancel Exchange Request
@@ -110,3 +121,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: cancelBeginOrderExchangeWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_fulfillment-sets_{id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_fulfillment-sets_{id}.yaml
@@ -45,3 +45,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: deleteFulfillmentSetsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_fulfillment-sets_{id}_service-zones.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_fulfillment-sets_{id}_service-zones.yaml
@@ -93,7 +93,13 @@ post:
                      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:
@@ -118,7 +124,13 @@ post:
                      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
@@ -148,7 +160,13 @@ post:
                      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
@@ -189,3 +207,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createServiceZonesWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_fulfillment-sets_{id}_service-zones_{zone_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_fulfillment-sets_{id}_service-zones_{zone_id}.yaml
@@ -174,7 +174,13 @@ post:
                      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
@@ -207,7 +213,13 @@ post:
                      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
@@ -241,7 +253,13 @@ post:
                      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.
@@ -282,6 +300,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateServiceZonesWorkflow
+  x-events: []
 delete:
  operationId: DeleteFulfillmentSetsIdServiceZonesZone_id
  summary: Remove a Service Zone from Fulfillment Set
@@ -338,3 +357,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: deleteServiceZonesWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_fulfillments.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_fulfillments.yaml
@@ -62,3 +62,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createFulfillmentWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_fulfillments_{id}_cancel.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_fulfillments_{id}_cancel.yaml
@@ -68,3 +68,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: cancelFulfillmentWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_fulfillments_{id}_shipment.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_fulfillments_{id}_shipment.yaml
@@ -71,3 +71,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createShipmentWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_inventory-items.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_inventory-items.yaml
@@ -559,3 +559,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createInventoryItemsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_inventory-items_location-levels_batch.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_inventory-items_location-levels_batch.yaml
@@ -46,3 +46,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: batchInventoryItemLevelsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_inventory-items_{id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_inventory-items_{id}.yaml
@@ -196,6 +196,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateInventoryItemsWorkflow
+  x-events: []
 delete:
  operationId: DeleteInventoryItemsId
  summary: Delete Inventory Item
@@ -262,3 +263,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: deleteInventoryItemWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_inventory-items_{id}_location-levels.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_inventory-items_{id}_location-levels.yaml
@@ -237,3 +237,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: createInventoryLevelsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_inventory-items_{id}_location-levels_batch.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_inventory-items_{id}_location-levels_batch.yaml
@@ -49,3 +49,4 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: batchInventoryItemLevelsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_inventory-items_{id}_location-levels_{location_id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_inventory-items_{id}_location-levels_{location_id}.yaml
@@ -89,6 +89,7 @@ post:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: updateInventoryLevelsWorkflow
+  x-events: []
 delete:
  operationId: DeleteInventoryItemsIdLocationLevelsLocation_id
  summary: Remove Inventory Level of Inventory Item
@@ -193,3 +194,4 @@ delete:
    '500':
      $ref: ../components/responses/500_error.yaml
  x-workflow: deleteInventoryLevelsWorkflow
+  x-events: []
--- a/www/apps/api-reference/specs/admin/paths/admin_invites.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_invites.yaml
@@ -673,3 +673,15 @@ post:
    - api_token: []
    - cookie_auth: []
    - jwt_token: []
+  x-events:
+    - name: invite.created
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the invite
+        }]
+        ```
+      description: |-
+        Emitted when invites are created. You can listen to this event
+        to send an email to the invited users, for example.
+      deprecated: false
--- a/www/apps/api-reference/specs/admin/paths/admin_invites_accept.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_invites_accept.yaml
@@ -79,3 +79,22 @@ post:
  security:
    - cookie_auth: []
    - jwt_token: []
+  x-events:
+    - name: user.created
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the user
+        }]
+        ```
+      description: Emitted when users are created.
+      deprecated: false
+    - name: invite.accepted
+      payload: |-
+        ```ts
+        {
+          id, // The ID of the invite
+        }
+        ```
+      description: Emitted when an invite is accepted.
+      deprecated: false
--- a/www/apps/api-reference/specs/admin/paths/admin_invites_{id}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_invites_{id}.yaml
@@ -130,3 +130,13 @@ delete:
    - api_token: []
    - cookie_auth: []
    - jwt_token: []
+  x-events:
+    - name: invite.deleted
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the invite
+        }]
+        ```
+      description: Emitted when invites are deleted.
+      deprecated: false
--- a/www/apps/api-reference/specs/admin/paths/admin_invites_{id}_resend.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_invites_{id}_resend.yaml
@@ -63,3 +63,19 @@ post:
    - api_token: []
    - cookie_auth: []
    - jwt_token: []
+  x-events:
+    - name: invite.resent
+      payload: |-
+        ```ts
+        [{
+          id, // The ID of the invite
+        }]
+        ```
+      description: >-
+        Emitted when invites should be resent because their token was
+
+        refreshed. You can listen to this event to send an email to the invited
+        users,
+
+        for example.
+      deprecated: false
--- a/Show More
+++ b/Show More