chore(docs): Generated API Reference (#5601)

Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com>

www/apps/api-reference/specs/admin/paths/admin_customer-groups.yaml

@@ -165,7 +165,7 @@ get:
 post:
   operationId: PostCustomerGroups
   summary: Create a Customer Group
-  description: Creates a Customer Group.
+  description: Create a Customer Group.
   x-authenticated: true
   requestBody:
     content:

www/apps/api-reference/specs/admin/paths/admin_customers.yaml

@@ -79,7 +79,7 @@ get:
 post:
   operationId: PostCustomers
   summary: Create a Customer
-  description: Allow admins to create a customer.
+  description: Create a customer as an admin.
   x-authenticated: true
   requestBody:
     content:

www/apps/api-reference/specs/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}.yaml

@@ -153,7 +153,7 @@ delete:
   operationId: DeleteDiscountsDiscountConditionsCondition
   summary: Delete a Condition
   description: >-
-    Deletes a Discount Condition. This does not delete resources associated to
+    Delete a Discount Condition. This does not delete resources associated to
     the discount condition.
   x-authenticated: true
   parameters:

www/apps/api-reference/specs/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}_batch.yaml

@@ -82,7 +82,7 @@ delete:
   summary: Remove Batch Resources
   description: >-
     Remove a batch of resources from a discount condition. This will only remove
-    the association between the resource and the discount condition, but not the
+    the association between the resource and the discount condition, not the
     resource itself.
   x-authenticated: true
   parameters:

www/apps/api-reference/specs/admin/paths/admin_discounts_{id}.yaml

@@ -1,7 +1,7 @@
 get:
   operationId: GetDiscountsDiscount
   summary: Get a Discount
-  description: Retrieves a Discount
+  description: Retrieve a Discount.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}.yaml

@@ -102,7 +102,7 @@ post:
 delete:
   operationId: DeleteDraftOrdersDraftOrder
   summary: Delete a Draft Order
-  description: Delete a Draft Order
+  description: Delete a Draft Order.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_draft-orders_{id}_line-items_{line_id}.yaml

@@ -1,7 +1,7 @@
 post:
   operationId: PostDraftOrdersDraftOrderLineItemsItem
   summary: Update a Line Item
-  description: Update a Line Item in a Draft Order
+  description: Update a Line Item in a Draft Order.
   x-authenticated: true
   parameters:
     - in: path
@@ -63,7 +63,7 @@ post:
 delete:
   operationId: DeleteDraftOrdersDraftOrderLineItemsItem
   summary: Delete a Line Item
-  description: Deletes a Line Item from a Draft Order.
+  description: Delete a Line Item from a Draft Order.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_inventory-items_{id}_location-levels.yaml

@@ -3,8 +3,7 @@ get:
   summary: List Inventory Level
   description: >-
     Retrieve a list of inventory levels of an inventory item. The inventory
-    levels can be filtered by fields such as `location_id`. The inventory levels
-    can also be paginated.
+    levels can be filtered by fields such as `location_id`.
   x-authenticated: true
   parameters:
     - in: path
@@ -77,8 +76,8 @@ get:
       $ref: ../components/responses/500_error.yaml
 post:
   operationId: PostInventoryItemsInventoryItemLocationLevels
-  summary: Create an Location Level
-  description: Create an Location Level for a given Inventory Item.
+  summary: Create a Location Level
+  description: Create a Location Level for a given Inventory Item.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_notes_{id}.yaml

@@ -50,7 +50,7 @@ post:
   operationId: PostNotesNote
   summary: Update a Note
   x-authenticated: true
-  description: Update a Note's details.'
+  description: Update a Note's details.
   parameters:
     - in: path
       name: id

www/apps/api-reference/specs/admin/paths/admin_order-edits_{id}.yaml

@@ -64,7 +64,7 @@ get:
 post:
   operationId: PostOrderEditsOrderEdit
   summary: Update an Order Edit
-  description: Updates an Order Edit's details.
+  description: Update an Order Edit's details.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_order-edits_{id}_cancel.yaml

@@ -1,7 +1,7 @@
 post:
   operationId: PostOrderEditsOrderEditCancel
   summary: Cancel an Order Edit
-  description: Cancel an OrderEdit.
+  description: Cancel an Order Edit.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments.yaml

@@ -1,7 +1,11 @@
 post:
   operationId: PostOrdersOrderClaimsClaimFulfillments
   summary: Create a Claim Fulfillment
-  description: Create a Fulfillment for a Claim.
+  description: >-
+    Create a Fulfillment for a Claim, and change its fulfillment status to
+    `partially_fulfilled` or `fulfilled` depending on whether all the items were
+    fulfilled. It may also change the status to `requires_action` if any actions
+    are required.
   x-authenticated: true
   externalDocs:
     description: Fulfill a claim

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel.yaml

@@ -1,7 +1,9 @@
 post:
   operationId: PostOrdersClaimFulfillmentsCancel
   summary: Cancel Claim's Fulfillment
-  description: Cancel a claim's fulfillment and change its status.
+  description: >-
+    Cancel a claim's fulfillment and change its fulfillment status to
+    `canceled`.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_claims_{claim_id}_shipments.yaml

@@ -2,9 +2,9 @@ post:
   operationId: PostOrdersOrderClaimsClaimShipments
   summary: Ship a Claim's Fulfillment
   description: >-
-    Mark a claim's fulfillment as shipped. This changes the claim's fulfillment
-    status to either `shipped` or `partially_shipped`, depending on whether all
-    the items were shipped.
+    Create a shipment for the claim and mark its fulfillment as shipped. This
+    changes the claim's fulfillment status to either `partially_shipped` or
+    `shipped`, depending on whether all the items were shipped.
   x-authenticated: true
   externalDocs:
     description: Fulfill a claim

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_fulfillment.yaml

@@ -1,7 +1,10 @@
 post:
   operationId: PostOrdersOrderFulfillments
   summary: Create a Fulfillment
-  description: Create a Fulfillment of an Order using the fulfillment provider.
+  description: >-
+    Create a Fulfillment of an Order using the fulfillment provider, and change
+    the order's fulfillment status to either `partially_fulfilled` or
+    `fulfilled`, depending on whether all the items were fulfilled.
   x-authenticated: true
   externalDocs:
     description: Fulfillments of orders

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel.yaml

@@ -1,7 +1,9 @@
 post:
   operationId: PostOrdersOrderFulfillmentsCancel
   summary: Cancel a Fulfilmment
-  description: Cancel an order's fulfillment and change its status.
+  description: >-
+    Cancel an order's fulfillment and change its fulfillment status to
+    `canceled`.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_shipment.yaml

@@ -2,9 +2,9 @@ post:
   operationId: PostOrdersOrderShipment
   summary: Ship a Fulfillment
   description: >-
-    Mark a fulfillment as shipped. This changes the order's fulfillment status
-    to either `shipped` or `partially_shipped`, depending on whether all the
-    items were shipped.
+    Create a shipment and mark a fulfillment as shipped. This changes the
+    order's fulfillment status to either `partially_shipped` or `shipped`,
+    depending on whether all the items were shipped.
   x-authenticated: true
   externalDocs:
     description: Fulfillments of orders

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_shipping-methods.yaml

@@ -2,7 +2,7 @@ post:
   operationId: PostOrdersOrderShippingMethods
   summary: Add a Shipping Method
   description: >-
-    Adds a Shipping Method to an Order. If another Shipping Method exists with
+    Add a Shipping Method to an Order. If another Shipping Method exists with
     the same Shipping Profile, the previous Shipping Method will be replaced.
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments.yaml

@@ -1,7 +1,10 @@
 post:
   operationId: PostOrdersOrderSwapsSwapFulfillments
   summary: Create a Swap Fulfillment
-  description: Create a Fulfillment for a Swap.
+  description: >-
+    Create a Fulfillment for a Swap and change its fulfillment status to
+    `fulfilled`. If it requires any additional actions, its fulfillment status
+    may change to `requires_action`.
   x-authenticated: true
   externalDocs:
     description: Handling a swap's fulfillment

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel.yaml

@@ -1,7 +1,7 @@
 post:
   operationId: PostOrdersSwapFulfillmentsCancel
   summary: Cancel Swap's Fulfilmment
-  description: Cancel a swap's fulfillment and change its status.
+  description: Cancel a swap's fulfillment and change its fulfillment status to `canceled`.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_orders_{id}_swaps_{swap_id}_shipments.yaml

@@ -2,9 +2,9 @@ post:
   operationId: PostOrdersOrderSwapsSwapShipments
   summary: Ship a Swap's Fulfillment
   description: >-
-    RMark a swap's fulfillment as shipped. This changes the swap's fulfillment
-    status to either `shipped` or `partially_shipped`, depending on whether all
-    the items were shipped.
+    Create a shipment for a swap and mark its fulfillment as shipped. This
+    changes the swap's fulfillment status to either `partially_shipped` or
+    `shipped`, depending on whether all the items were shipped.
   x-authenticated: true
   externalDocs:
     description: Handling swap fulfillments

www/apps/api-reference/specs/admin/paths/admin_price-lists_{id}_prices_batch.yaml

@@ -1,7 +1,7 @@
 post:
   operationId: PostPriceListsPriceListPricesBatch
   summary: Add or Update Prices
-  description: Add or update a list of prices in a Price List
+  description: Add or update a list of prices in a Price List.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_price-lists_{id}_variants_{variant_id}_prices.yaml

@@ -1,7 +1,7 @@
 delete:
   operationId: DeletePriceListsPriceListVariantsVariantPrices
   summary: Delete a Variant's Prices
-  description: Delete all the prices related to a specific variant in a price list
+  description: Delete all the prices related to a specific variant in a price list.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_publishable-api-keys.yaml

@@ -80,7 +80,7 @@ get:
 post:
   operationId: PostPublishableApiKeys
   summary: Create Publishable API Key
-  description: Creates a Publishable API Key.
+  description: Create a Publishable API Key.
   requestBody:
     content:
       application/json:

www/apps/api-reference/specs/admin/paths/admin_publishable-api-keys_{id}_sales-channels_batch.yaml

@@ -1,7 +1,7 @@
 post:
   operationId: PostPublishableApiKeySalesChannelsChannelsBatch
   summary: Add Sales Channels
-  description: Assign a list of sales channels to a publishable API key.
+  description: Add a list of sales channels to a publishable API key.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_regions.yaml

@@ -3,7 +3,7 @@ get:
   summary: List Regions
   description: >-
     Retrieve a list of Regions. The regions can be filtered by fields such as
-    `created_at`. The regions can also be paginated
+    `created_at`. The regions can also be paginated.
   x-authenticated: true
   parameters:
     - in: query

www/apps/api-reference/specs/admin/paths/admin_regions_{id}_countries.yaml

@@ -1,7 +1,7 @@
 post:
   operationId: PostRegionsRegionCountries
   summary: Add Country
-  description: Add a Country to the list of Countries in a Region
+  description: Add a Country to the list of Countries in a Region.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_reservations_{id}.yaml

@@ -1,7 +1,7 @@
 get:
   operationId: GetReservationsReservation
   summary: Get a Reservation
-  description: Retrieve a reservation's details.'
+  description: Retrieve a reservation's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -47,7 +47,7 @@ get:
 post:
   operationId: PostReservationsReservation
   summary: Update a Reservation
-  description: Update a Reservation's details.'
+  description: Update a Reservation's details.
   x-authenticated: true
   parameters:
     - in: path

www/apps/api-reference/specs/admin/paths/admin_tax-rates_{id}_product-types_batch.yaml

@@ -1,7 +1,7 @@
 post:
   operationId: PostTaxRatesTaxRateProductTypes
   summary: Add to Product Types
-  description: Associates a Tax Rate with a list of Product Types
+  description: Add Product Types to a Tax Rate.
   parameters:
     - in: path
       name: id

www/apps/api-reference/specs/admin/paths/admin_tax-rates_{id}_products_batch.yaml

@@ -1,7 +1,7 @@
 post:
   operationId: PostTaxRatesTaxRateProducts
   summary: Add to Products
-  description: Associates a Tax Rate with a list of Products.
+  description: Add products to a tax rate.
   parameters:
     - in: path
       name: id

www/apps/api-reference/specs/admin/paths/admin_tax-rates_{id}_shipping-options_batch.yaml

@@ -1,7 +1,7 @@
 post:
   operationId: PostTaxRatesTaxRateShippingOptions
   summary: Add to Shipping Options
-  description: Associates a Tax Rate with a list of Shipping Options.
+  description: Add Shipping Options to a Tax Rate.
   parameters:
     - in: path
       name: id

www/apps/api-reference/specs/admin/paths/admin_users_password-token.yaml

@@ -1,7 +1,15 @@
 post:
   operationId: PostUsersUserPasswordToken
   summary: Request Password Reset
-  description: Generate a password token for an admin user with a given email.
+  description: >-
+    Generate a password token for an admin user with a given email. This also
+    triggers the `user.password_reset` event. So, if you have a Notification
+    Service installed that can handle this event, a notification, such as an
+    email, will be sent to the user. The token is triggered as part of the
+    `user.password_reset` event's payload. That token must be used later to
+    reset the password using the [Reset
+    Password](https://docs.medusajs.com/api/admin#users_postusersuserpassword)
+    API Route.
   externalDocs:
     description: How to reset a user's password
     url: >-