docs: generate OAS with events (#12394)

* docs: generate OAS with events

* small change

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"]

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"

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: [
       {

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",

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)
+})

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": {}

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": {}
   },

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": {}
 }'

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

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

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

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

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

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

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

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.

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

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

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

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.

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

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

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

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

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

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

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

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

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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

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

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: []

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: []

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: []

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: []

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

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

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: []

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: []

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: []

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: []

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

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

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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: []

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

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

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

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