chore(docs): Updated API Reference (v2) (#9148)

Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>
2024-09-18 07:13:51 +00:00
1 parent a63f6910d0
commit 56ee4d6aad
@@ -0,0 +1,2 @@
 curl -X POST '{backend_url}/auth/token/refresh' \
 -H 'Authorization: Bearer {token}'
@@ -1 +1 @@
-curl -X POST '{backend_url}/auth/user/{auth_provider}'
+curl -X POST '{backend_url}/auth/user/github'
@@ -1 +1 @@
-curl -X POST '{backend_url}/auth/user/{auth_provider}/callback'
+curl -X POST '{backend_url}/auth/user/github/callback?code=123'
@@ -1 +1,6 @@
-curl -X POST '{backend_url}/auth/user/{auth_provider}/register'
+curl -X POST '{backend_url}/auth/user/emailpass/register' \
 -H 'Content-Type: application/json' \
 --data-raw '{
  "email": "admin@medusa-test.com",
  "password": "supersecret"
 }'
@@ -1,5 +1,5 @@
 type: object
-description: The api key's details.
+description: The API key's details.
 x-schemaName: AdminApiKey
 required:
  - id
@@ -24,37 +24,44 @@ properties:
  redacted:
    type: string
    title: redacted
-    description: The api key's redacted.
+    description: >-
      The redacted form of the API key's token. This is useful when showing
      portion of the token.
    example: sk_...123
  title:
    type: string
    title: title
    description: The api key's title.
  type:
    type: string
-    description: The api key's type.
+    description: >-
      The api key's type. `secret` is used for a user's API key, whereas
      `publishable` is used for Publishable API keys.
    enum:
      - secret
      - publishable
  last_used_at:
    type: string
    title: last_used_at
-    description: The api key's last used at.
+    description: The date and time the API key was last used.
    format: date-time
  created_by:
    type: string
    title: created_by
-    description: The api key's created by.
+    description: The ID of the user that created the API key, if available.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The api key's created at.
+    description: The date and time the API key was created.
  revoked_by:
    type: string
    title: revoked_by
-    description: The api key's revoked by.
+    description: The ID of the user that revoked the API key, if available.
  revoked_at:
    type: string
    title: revoked_at
-    description: The api key's revoked at.
+    description: >-
      The date and time the API key was revoked. The API key is considered
      revoked when this property is set.
    format: date-time
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The API key's details.
 x-schemaName: AdminApiKeyResponse
 required:
  - api_key
@@ -1,21 +1,21 @@
 type: object
-description: SUMMARY
+description: The products to create, update, or delete.
 x-schemaName: AdminBatchProductRequest
 properties:
  create:
    type: array
-    description: The product's create.
+    description: The products to create.
    items:
      $ref: ./AdminCreateProduct.yaml
  update:
    type: array
-    description: The product's update.
+    description: The products to update.
    items:
      $ref: ./AdminUpdateProduct.yaml
  delete:
    type: array
-    description: The product's delete.
+    description: The products to delete.
    items:
      type: string
      title: delete
-      description: The delete's details.
+      description: A product's ID.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the products created, updated, or deleted.
 x-schemaName: AdminBatchProductResponse
 required:
  - created
@@ -8,17 +8,17 @@ required:
 properties:
  created:
    type: array
-    description: The product's created.
+    description: The created products
    items:
      $ref: ./AdminProduct.yaml
  updated:
    type: array
-    description: The product's updated.
+    description: The updated products.
    items:
      $ref: ./AdminProduct.yaml
  deleted:
    type: object
-    description: SUMMARY
+    description: The deleted products' details.
    required:
      - ids
      - object
@@ -26,16 +26,17 @@ properties:
    properties:
      ids:
        type: array
-        description: The deleted's ids.
+        description: The IDs of deleted products.
        items:
          type: string
          title: ids
-          description: The id's ids.
+          description: The ID of a deleted product.
      object:
        type: string
        title: object
-        description: SUMMARY
+        description: The name of the deleted objects.
        default: product
      deleted:
        type: boolean
        title: deleted
-        description: SUMMARY
+        description: Whether the products were deleted.
@@ -1,21 +1,21 @@
 type: object
-description: SUMMARY
+description: The product variants to create, update, or delete.
 x-schemaName: AdminBatchProductVariantRequest
 properties:
  create:
    type: array
-    description: The product's create.
+    description: The product variants to create.
    items:
      $ref: ./AdminCreateProductVariant.yaml
  update:
    type: array
-    description: The product's update.
+    description: The product variants to update.
    items:
      $ref: ./AdminUpdateProductVariant.yaml
  delete:
    type: array
-    description: The product's delete.
+    description: The product variants to delete.
    items:
      type: string
      title: delete
-      description: The delete's details.
+      description: A product variant's ID.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the product variants created, updated, or deleted.
 x-schemaName: AdminBatchProductVariantResponse
 required:
  - created
@@ -8,17 +8,17 @@ required:
 properties:
  created:
    type: array
-    description: The product's created.
+    description: The created product variants.
    items:
      $ref: ./AdminProductVariant.yaml
  updated:
    type: array
-    description: The product's updated.
+    description: The updated product variants.
    items:
      $ref: ./AdminProductVariant.yaml
  deleted:
    type: object
-    description: SUMMARY
+    description: The details of the deleted product variants.
    required:
      - ids
      - object
@@ -26,16 +26,17 @@ properties:
    properties:
      ids:
        type: array
-        description: The deleted's ids.
+        description: The IDs of the deleted product variants.
        items:
          type: string
          title: ids
-          description: The id's ids.
+          description: The ID of a deleted variant.
      object:
        type: string
        title: object
-        description: SUMMARY
+        description: The name of the deleted objects.
        default: variant
      deleted:
        type: boolean
        title: deleted
-        description: SUMMARY
+        description: Whether the product variants were deleted.
@@ -30,15 +30,15 @@ properties:
  campaign_identifier:
    type: string
    title: campaign_identifier
-    description: The campaign's campaign identifier.
+    description: The campaign's identifier.
  starts_at:
    type: string
    title: starts_at
-    description: The campaign's starts at.
+    description: The date and time that the campaign starts.
  ends_at:
    type: string
    title: ends_at
-    description: The campaign's ends at.
+    description: The date and time that the campaign ends.
  budget:
    type: object
    description: The campaign's budget.
@@ -55,7 +55,11 @@ properties:
        description: The budget's ID.
      type:
        type: string
-        description: The budget's type.
+        description: >
          The budget's type. `spend` means the limit is set on the total amount
          discounted by the campaign's promotions; `usage` means the limit is
          set on the total number of times the campaign's promotions can be
          used.
        enum:
          - spend
          - usage
@@ -70,4 +74,8 @@ properties:
      used:
        type: number
        title: used
-        description: The budget's used.
+        description: >
          How much of the budget has been used. If the limit is `spend`, this
          property holds the total amount discounted so far. If the limit is
          `usage`, it holds the number of times the campaign's promotions have
          been used so far.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The campaign's details.
 x-schemaName: AdminCampaignResponse
 required:
  - campaign
@@ -1,3 +0,0 @@
 type: object
 description: SUMMARY
 x-schemaName: AdminCancelFulfillment
@@ -41,62 +41,63 @@ required:
  - original_shipping_subtotal
  - original_shipping_tax_total
 properties:
  id:
    type: string
    title: id
    description: The claim's ID.
  order_id:
    type: string
    title: order_id
-    description: The claim's order id.
+    description: The ID of the order associated with the claim.
  claim_items:
    type: array
-    description: The claim's claim items.
+    description: The order items targetted by the claim.
    items:
      $ref: ./BaseClaimItem.yaml
  additional_items:
    type: array
-    description: The claim's additional items.
+    description: The outbound or new items of the claim.
-    items: {}
+    items:
      $ref: ./BaseClaimItem.yaml
  return:
    $ref: ./Return.yaml
  return_id:
    type: string
    title: return_id
-    description: The claim's return id.
+    description: The ID of the associated return.
  no_notification:
    type: boolean
    title: no_notification
-    description: The claim's no notification.
+    description: Whether the customer should be notified about changes in the claim.
  refund_amount:
    type: number
    title: refund_amount
-    description: The claim's refund amount.
+    description: The amount to be refunded.
  currency_code:
    type: string
    title: currency_code
    description: The claim's currency code.
  id:
    type: string
    title: id
    description: The claim's ID.
  region_id:
    type: string
    title: region_id
-    description: The claim's region id.
+    description: The ID of the region associated with the claim.
  customer_id:
    type: string
    title: customer_id
-    description: The claim's customer id.
+    description: The ID of the customer associated with the claim's order.
  sales_channel_id:
    type: string
    title: sales_channel_id
-    description: The claim's sales channel id.
+    description: The ID of the sales channel the claim's order is created in.
  email:
    type: string
    title: email
-    description: The claim's email.
+    description: The email associated with the claim's order.
    format: email
  display_id:
    type: number
    title: display_id
-    description: The claim's display id.
+    description: The claim's display ID.
  shipping_address:
    $ref: ./BaseOrderAddress.yaml
  billing_address:
@@ -145,63 +146,67 @@ properties:
  transactions:
    type: array
    description: The claim's transactions.
    externalDocs:
      url: >-
        https://docs.medusajs.com/v2/resources/commerce-modules/order/transactions
      description: Learn more about transactions of orders and associated models.
    items:
      $ref: ./BaseOrderTransaction.yaml
  summary:
    $ref: ./BaseOrderSummary.yaml
  metadata:
    type: object
-    description: The claim's metadata.
+    description: The claim's metadata, used to store custom key-value pairs.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The claim's created at.
+    description: The claim's creation date.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The claim's updated at.
+    description: The claim's update date.
  original_item_total:
    type: number
    title: original_item_total
-    description: The claim's original item total.
+    description: The total of the original items in the associated order.
  original_item_subtotal:
    type: number
    title: original_item_subtotal
-    description: The claim's original item subtotal.
+    description: The subtotal of the original items in the associated order.
  original_item_tax_total:
    type: number
    title: original_item_tax_total
-    description: The claim's original item tax total.
+    description: The tax total of the original items in the associated order.
  item_total:
    type: number
    title: item_total
-    description: The claim's item total.
+    description: The total of the claim's items.
  item_subtotal:
    type: number
    title: item_subtotal
-    description: The claim's item subtotal.
+    description: The subtotal of the claim's items.
  item_tax_total:
    type: number
    title: item_tax_total
-    description: The claim's item tax total.
+    description: The tax total of the claim's items.
  original_total:
    type: number
    title: original_total
-    description: The claim's original total.
+    description: The associated order's original total.
  original_subtotal:
    type: number
    title: original_subtotal
-    description: The claim's original subtotal.
+    description: The associated order's original subtotal.
  original_tax_total:
    type: number
    title: original_tax_total
-    description: The claim's original tax total.
+    description: The associated order's original tax total.
  total:
    type: number
    title: total
-    description: The claim's total.
+    description: The associated order's total.
  subtotal:
    type: number
    title: subtotal
@@ -241,12 +246,12 @@ properties:
  original_shipping_total:
    type: number
    title: original_shipping_total
-    description: The claim's original shipping total.
+    description: The associated order's original shipping total.
  original_shipping_subtotal:
    type: number
    title: original_shipping_subtotal
-    description: The claim's original shipping subtotal.
+    description: The associated order's original shipping subtotal.
  original_shipping_tax_total:
    type: number
    title: original_shipping_tax_total
-    description: The claim's original shipping tax total.
+    description: The associated order's original shipping tax total.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the deleted claim.
 x-schemaName: AdminClaimDeleteResponse
 required:
  - id
@@ -18,4 +18,4 @@ properties:
  deleted:
    type: boolean
    title: deleted
-    description: Whether the Claim was deleted.
+    description: Whether the claim was deleted.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The paginated list of claims.
 x-schemaName: AdminClaimListResponse
 required:
  - limit
@@ -10,17 +10,17 @@ properties:
  limit:
    type: number
    title: limit
-    description: The claim's limit.
+    description: The maximum number of items returned.
  offset:
    type: number
    title: offset
-    description: The claim's offset.
+    description: The number of items skipped before retrieving the returned items.
  count:
    type: number
    title: count
-    description: The claim's count.
+    description: The total number of items.
  claims:
    type: array
-    description: The claim's claims.
+    description: The list of claims.
    items:
      $ref: ./AdminClaim.yaml
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The created claim's details.
 x-schemaName: AdminClaimOrderResponse
 required:
  - order
@@ -1,5 +1,7 @@
 type: object
-description: SUMMARY
+description: >-
  The details of the claim, as well as a preview of the order when the claim is
  applied.
 x-schemaName: AdminClaimPreviewResponse
 required:
  - order_preview
@@ -1,5 +1,7 @@
 type: object
-description: SUMMARY
+description: >-
  The details of the claim, its return, and a preview of the order when the
  claim is applied.
 x-schemaName: AdminClaimRequestResponse
 required:
  - return
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The claim's details.
 x-schemaName: AdminClaimResponse
 required:
  - claim
@@ -1,5 +1,7 @@
 type: object
-description: SUMMARY
+description: >-
  The details of the claim's return, with a preview of the order when the
  claim's return is applied.
 x-schemaName: AdminClaimReturnPreviewResponse
 required:
  - order_preview
@@ -1,5 +1,5 @@
 type: object
-description: The parent's collection.
+description: The product collection's details.
 x-schemaName: AdminCollection
 required:
  - id
@@ -26,17 +26,17 @@ properties:
    type: string
    format: date-time
    title: created_at
-    description: The collection's created at.
+    description: The collection's creation date.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The collection's updated at.
+    description: The collection's update date.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
-    description: The collection's deleted at.
+    description: The collection's deletion date.
  products:
    type: array
    description: The collection's products.
@@ -44,4 +44,4 @@ properties:
      type: object
  metadata:
    type: object
-    description: The collection's metadata.
+    description: The collection's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the deleted collection.
 x-schemaName: AdminCollectionDeleteResponse
 required:
  - id
@@ -18,4 +18,4 @@ properties:
  deleted:
    type: boolean
    title: deleted
-    description: Whether the Collection was deleted.
+    description: Whether the collection was deleted.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The paginated list of product collections.
 x-schemaName: AdminCollectionListResponse
 required:
  - limit
@@ -10,17 +10,17 @@ properties:
  limit:
    type: number
    title: limit
-    description: The collection's limit.
+    description: The maximum number of items returned.
  offset:
    type: number
    title: offset
-    description: The collection's offset.
+    description: The number of items skipped before retrieving the returned results.
  count:
    type: number
    title: count
-    description: The collection's count.
+    description: The total number of items.
  collections:
    type: array
-    description: The collection's collections.
+    description: The list of product collections.
    items:
      $ref: ./AdminCollection.yaml
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The collection's details.
 x-schemaName: AdminCollectionResponse
 required:
  - collection
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The API key's details.
 x-schemaName: AdminCreateApiKey
 required:
  - title
@@ -8,10 +8,12 @@ properties:
  title:
    type: string
    title: title
-    description: The api key's title.
+    description: The API key's title.
  type:
    type: string
-    description: The api key's type.
+    description: >-
      The API key's type. Use `secret` for a user's API key; Use `publishable`
      for Publishable API keys.
    enum:
      - publishable
      - secret
@@ -1,5 +1,5 @@
 type: object
-description: The promotion's application method.
+description: The application method's details.
 x-schemaName: AdminCreateApplicationMethod
 required:
  - value
@@ -13,7 +13,9 @@ properties:
  value:
    type: number
    title: value
-    description: The application method's value.
+    description: >-
      The discounted amount applied by the associated promotion based on the
      `type`.
  currency_code:
    type: string
    title: currency_code
@@ -21,23 +23,32 @@ properties:
  max_quantity:
    type: number
    title: max_quantity
-    description: The application method's max quantity.
+    description: >-
      The max quantity allowed in the cart for the associated promotion to be
      applied.
  type:
    type: string
-    description: The application method's type.
+    description: >-
      The type of the application method indicating how the associated promotion
      is applied.
    enum:
      - fixed
      - percentage
  target_type:
    type: string
-    description: The application method's target type.
+    description: >-
      The target type of the application method indicating whether the
      associated promotion is applied to the cart's items, shipping methods, or
      the whole order.
    enum:
      - items
      - shipping_methods
      - order
  allocation:
    type: string
-    description: The application method's allocation.
+    description: >-
      The allocation value that indicates whether the associated promotion is
      applied on each item in a cart or split between the items in the cart.
    enum:
      - each
      - across
@@ -54,8 +65,14 @@ properties:
  apply_to_quantity:
    type: number
    title: apply_to_quantity
-    description: The application method's apply to quantity.
+    description: >-
      The quantity that results from matching the `buyget` promotion's
      condition. For example, if the promotion is a "Buy 2 shirts get 1 free",
      the value f this attribute is `1`.
  buy_rules_min_quantity:
    type: number
    title: buy_rules_min_quantity
-    description: The application method's buy rules min quantity.
+    description: >-
      The minimum quantity required for a `buyget` promotion to be applied. For
      example, if the promotion is a "Buy 2 shirts get 1 free", the value of
      this attribute is `2`.
@@ -1,48 +0,0 @@
 type: object
 description: The promotion's campaign.
 x-schemaName: AdminCreateCampaign
 properties:
  name:
    type: string
    title: name
    description: The campaign's name.
  description:
    type: string
    title: description
    description: The campaign's description.
  currency:
    type: string
    title: currency
    description: The campaign's currency.
  campaign_identifier:
    type: string
    title: campaign_identifier
    description: The campaign's campaign identifier.
  starts_at:
    type: string
    title: starts_at
    description: The campaign's starts at.
    format: date-time
  ends_at:
    type: string
    title: ends_at
    description: The campaign's ends at.
    format: date-time
  budget:
    type: object
    description: The campaign's budget.
    properties:
      type:
        type: string
        description: The budget's type.
        enum:
          - spend
          - usage
      currency_code:
        type: string
        title: currency_code
        description: The budget's currency code.
      limit:
        type: number
        title: limit
        description: The budget's limit.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: the product collection's details.
 x-schemaName: AdminCreateCollection
 required:
  - title
@@ -14,4 +14,4 @@ properties:
    description: The collection's handle.
  metadata:
    type: object
-    description: The collection's metadata.
+    description: The collection's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The customer group's details.
 x-schemaName: AdminCreateCustomerGroup
 required:
  - name
@@ -10,4 +10,4 @@ properties:
    description: The customer group's name.
  metadata:
    type: object
-    description: The customer group's metadata.
+    description: The customer group's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The filfillment's details.
 x-schemaName: AdminCreateFulfillment
 required:
  - location_id
@@ -15,27 +15,27 @@ properties:
  location_id:
    type: string
    title: location_id
-    description: The fulfillment's location id.
+    description: The ID of the location the items are fulfilled from.
  provider_id:
    type: string
    title: provider_id
-    description: The fulfillment's provider id.
+    description: The ID of the provider handling this fulfillment.
  delivery_address:
    type: object
-    description: The fulfillment's delivery address.
+    description: The address to deliver the items to.
    properties:
      first_name:
        type: string
        title: first_name
-        description: The delivery address's first name.
+        description: The customer's first name.
      last_name:
        type: string
        title: last_name
-        description: The delivery address's last name.
+        description: The customer's last name.
      phone:
        type: string
        title: phone
-        description: The delivery address's phone.
+        description: The customer's phone.
      company:
        type: string
        title: company
@@ -43,11 +43,11 @@ properties:
      address_1:
        type: string
        title: address_1
-        description: The delivery address's address 1.
+        description: The delivery address's first line.
      address_2:
        type: string
        title: address_2
-        description: The delivery address's address 2.
+        description: The delivery address's second line.
      city:
        type: string
        title: city
@@ -66,13 +66,13 @@ properties:
        description: The delivery address's postal code.
      metadata:
        type: object
-        description: The delivery address's metadata.
+        description: The delivery address's metadata, used to store custom key-value pairs.
  items:
    type: array
-    description: The fulfillment's items.
+    description: The items to fulfill.
    items:
      type: object
-      description: The item's items.
+      description: An item to fulfill.
      required:
        - title
        - sku
@@ -86,11 +86,11 @@ properties:
        sku:
          type: string
          title: sku
-          description: The item's sku.
+          description: The item's SKU.
        quantity:
          type: number
          title: quantity
-          description: The item's quantity.
+          description: The quantity to fulfill of the item.
        barcode:
          type: string
          title: barcode
@@ -98,17 +98,17 @@ properties:
        line_item_id:
          type: string
          title: line_item_id
-          description: The item's line item id.
+          description: The ID of the associated line item.
        inventory_item_id:
          type: string
          title: inventory_item_id
-          description: The item's inventory item id.
+          description: The ID of the inventory item associated with the underlying variant.
  labels:
    type: array
-    description: The fulfillment's labels.
+    description: The labels for the fulfillment's shipments.
    items:
      type: object
-      description: The label's labels.
+      description: A shipment's label.
      required:
        - tracking_number
        - tracking_url
@@ -121,45 +121,46 @@ properties:
        tracking_url:
          type: string
          title: tracking_url
-          description: The label's tracking url.
+          description: The label's tracking URL.
        label_url:
          type: string
          title: label_url
-          description: The label's label url.
+          description: The label's URL.
  order:
    type: object
    description: The fulfillment's order.
  order_id:
    type: string
    title: order_id
-    description: The fulfillment's order id.
+    description: The ID of the order this fulfillment is created for.
  shipping_option_id:
    type: string
    title: shipping_option_id
-    description: The fulfillment's shipping option id.
+    description: The ID of the shipping option used in the order.
  data:
    type: object
-    description: The fulfillment's data.
+    description: Any data useful for the fulfillment provider to handle the fulfillment.
    externalDocs:
      url: >-
        https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
      description: Learn more about the data property.
  packed_at:
    type: string
    title: packed_at
-    description: The fulfillment's packed at.
+    description: The date and time the fulfillment was packed.
    format: date-time
  shipped_at:
    type: string
    title: shipped_at
-    description: The fulfillment's shipped at.
+    description: The date and time the fulfillment was shipped.
    format: date-time
  delivered_at:
    type: string
    title: delivered_at
-    description: The fulfillment's delivered at.
+    description: The date and time the fulfillment was delivered.
    format: date-time
  canceled_at:
    type: string
    title: canceled_at
-    description: The fulfillment's canceled at.
+    description: The date and time the fulfillment was canceled.
    format: date-time
  metadata:
    type: object
-    description: The fulfillment's metadata.
+    description: The fulfillment's metadata, used to store custom key-value pairs.
@@ -1,15 +1,15 @@
 type: object
-description: SUMMARY
+description: The inventory item's details.
 x-schemaName: AdminCreateInventoryItem
 properties:
  sku:
    type: string
    title: sku
-    description: The inventory item's sku.
+    description: The inventory item's SKU.
  hs_code:
    type: string
    title: hs_code
-    description: The inventory item's hs code.
+    description: The inventory item's HS code.
  weight:
    type: number
    title: weight
@@ -45,15 +45,15 @@ properties:
  description:
    type: string
    title: description
-    description: The inventory item's description.
+    description: The description of the variant associated with the inventory item.
  requires_shipping:
    type: boolean
    title: requires_shipping
-    description: The inventory item's requires shipping.
+    description: Whether the item requires shipping.
  thumbnail:
    type: string
    title: thumbnail
    description: The inventory item's thumbnail.
  metadata:
    type: object
-    description: The inventory item's metadata.
+    description: The inventory item's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The price list's details.
 x-schemaName: AdminCreatePriceList
 required:
  - title
@@ -16,11 +16,13 @@ properties:
  starts_at:
    type: string
    title: starts_at
-    description: The price list's starts at.
+    description: The date and time the price list starts at.
    format: date-time
  ends_at:
    type: string
    title: ends_at
-    description: The price list's ends at.
+    description: The date and time the price list ends at.
    format: date-time
  status:
    type: string
    description: The price list's status.
@@ -36,12 +38,14 @@ properties:
  rules:
    type: object
    description: The price list's rules.
    example:
      product_category_id: pcat_123
  prices:
    type: array
    description: The price list's prices.
    items:
      type: object
-      description: The price's prices.
+      description: A price's details.
      required:
        - currency_code
        - amount
@@ -58,15 +62,21 @@ properties:
        variant_id:
          type: string
          title: variant_id
-          description: The price's variant id.
+          description: The ID of the product variant this price is for.
        min_quantity:
          type: number
          title: min_quantity
-          description: The price's min quantity.
+          description: >-
            The minimum quantity required in the cart for this price to be
            applied.
        max_quantity:
          type: number
          title: max_quantity
-          description: The price's max quantity.
+          description: >-
            The maximum quantity in the cart that shouldn't be crossed for this
            price to be applied.
        rules:
          type: object
          description: The price's rules.
          example:
            region_id: reg_123
@@ -1,16 +1,20 @@
 type: object
-description: SUMMARY
+description: The price preference's details.
 x-schemaName: AdminCreatePricePreference
 properties:
  attribute:
    type: string
    title: attribute
-    description: The price preference's attribute.
+    description: The name of the attribute the price preference applies on.
    example: currency_code
  value:
    type: string
    title: value
-    description: The price preference's value.
+    description: The attribute's value.
    example: usd
  is_tax_inclusive:
    type: boolean
    title: is_tax_inclusive
-    description: The price preference's is tax inclusive.
+    description: >-
      Whether the price is tax inclusive if the value of the specified attribute
      matches the specified value.
@@ -1,5 +1,5 @@
 type: object
-description: The create's details.
+description: The product's details.
 x-schemaName: AdminCreateProduct
 required:
  - title
@@ -7,47 +7,47 @@ properties:
  title:
    type: string
    title: title
-    description: The create's title.
+    description: The product's title.
  subtitle:
    type: string
    title: subtitle
-    description: The create's subtitle.
+    description: The product's subtitle.
  description:
    type: string
    title: description
-    description: The create's description.
+    description: The product's description.
  is_giftcard:
    type: boolean
    title: is_giftcard
-    description: The create's is giftcard.
+    description: Whether the product is a gift card.
  discountable:
    type: boolean
    title: discountable
-    description: The create's discountable.
+    description: Whether the product is discountable.
  images:
    type: array
-    description: The create's images.
+    description: The product's images.
    items:
      type: object
-      description: The image's images.
+      description: A product's image details.
      required:
        - url
      properties:
        url:
          type: string
          title: url
-          description: The image's url.
+          description: The image's URL.
  thumbnail:
    type: string
    title: thumbnail
-    description: The create's thumbnail.
+    description: The URL of the product's thumbnail.
  handle:
    type: string
    title: handle
-    description: The create's handle.
+    description: The product's handle.
  status:
    type: string
-    description: The create's status.
+    description: The product's status.
    enum:
      - draft
      - proposed
@@ -56,17 +56,17 @@ properties:
  type_id:
    type: string
    title: type_id
-    description: The create's type id.
+    description: The ID of the type the product belongs to.
  collection_id:
    type: string
    title: collection_id
-    description: The create's collection id.
+    description: The ID of the collection the product belongs to.
  categories:
    type: array
-    description: The create's categories.
+    description: The categories the product belongs to.
    items:
      type: object
-      description: The category's categories.
+      description: A category's details.
      required:
        - id
      properties:
@@ -76,10 +76,10 @@ properties:
          description: The category's ID.
  tags:
    type: array
-    description: The create's tags.
+    description: The product's tags.
    items:
      type: object
-      description: The tag's tags.
+      description: A tag's details.
      required:
        - id
      properties:
@@ -89,20 +89,20 @@ properties:
          description: The tag's ID.
  options:
    type: array
-    description: The create's options.
+    description: The product's options.
    items:
      $ref: ./AdminCreateProductOption.yaml
  variants:
    type: array
-    description: The create's variants.
+    description: The product's variants.
    items:
      $ref: ./AdminCreateProductVariant.yaml
  sales_channels:
    type: array
-    description: The create's sales channels.
+    description: The sales channels the product is available in.
    items:
      type: object
-      description: The sales channel's sales channels.
+      description: A sales channel's details.
      required:
        - id
      properties:
@@ -113,35 +113,35 @@ properties:
  weight:
    type: number
    title: weight
-    description: The create's weight.
+    description: The product's weight.
  length:
    type: number
    title: length
-    description: The create's length.
+    description: The product's length.
  height:
    type: number
    title: height
-    description: The create's height.
+    description: The product's height.
  width:
    type: number
    title: width
-    description: The create's width.
+    description: The product's width.
  hs_code:
    type: string
    title: hs_code
-    description: The create's hs code.
+    description: The product's HS code.
  mid_code:
    type: string
    title: mid_code
-    description: The create's mid code.
+    description: The product's MID code.
  origin_country:
    type: string
    title: origin_country
-    description: The create's origin country.
+    description: The product's origin country.
  material:
    type: string
    title: material
-    description: The create's material.
+    description: The product's material.
  metadata:
    type: object
-    description: The create's metadata.
+    description: The product's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The product category's details.
 x-schemaName: AdminCreateProductCategory
 required:
  - name
@@ -19,19 +19,19 @@ properties:
  is_internal:
    type: boolean
    title: is_internal
-    description: The product category's is internal.
+    description: Whether the product category is only used and seen by admin users.
  is_active:
    type: boolean
    title: is_active
-    description: The product category's is active.
+    description: Whether the product category is active.
  parent_category_id:
    type: string
    title: parent_category_id
-    description: The product category's parent category id.
+    description: The ID of a category that's the parent of this one.
  rank:
    type: number
    title: rank
-    description: The product category's rank.
+    description: The sorting order of the product category among sibling categories.
  metadata:
    type: object
-    description: The product category's metadata.
+    description: The product category's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The product option's details.
 x-schemaName: AdminCreateProductOption
 required:
  - title
@@ -8,11 +8,11 @@ properties:
  title:
    type: string
    title: title
-    description: The product's title.
+    description: The product option's title.
  values:
    type: array
-    description: The product's values.
+    description: The product option's values.
    items:
      type: string
      title: values
-      description: The value's values.
+      description: A value.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The product tag's details.
 x-schemaName: AdminCreateProductTag
 required:
  - value
@@ -10,4 +10,4 @@ properties:
    description: The product tag's value.
  metadata:
    type: object
-    description: The product tag's metadata.
+    description: The product tag's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: The create's details.
+description: The product variant's details.
 x-schemaName: AdminCreateProductVariant
 required:
  - title
@@ -8,75 +8,81 @@ properties:
  title:
    type: string
    title: title
-    description: The create's title.
+    description: The variant's title.
  sku:
    type: string
    title: sku
-    description: The create's sku.
+    description: The variant's SKU.
  ean:
    type: string
    title: ean
-    description: The create's ean.
+    description: The variant's EAN.
  upc:
    type: string
    title: upc
-    description: The create's upc.
+    description: The variant's UPC.
  barcode:
    type: string
    title: barcode
-    description: The create's barcode.
+    description: The variant's barcode.
  hs_code:
    type: string
    title: hs_code
-    description: The create's hs code.
+    description: The variant's HS code.
  mid_code:
    type: string
    title: mid_code
-    description: The create's mid code.
+    description: The variant's MID code.
  allow_backorder:
    type: boolean
    title: allow_backorder
-    description: The create's allow backorder.
+    description: Whether it's allowed to order this variant when it's out of stock.
  manage_inventory:
    type: boolean
    title: manage_inventory
-    description: The create's manage inventory.
+    description: >-
      Whether Medusa manages the variant's inventory quantity. If disabled, the
      product variant is always considered in stock.
  variant_rank:
    type: number
    title: variant_rank
-    description: The create's variant rank.
+    description: The sorting order of the variant among other variants in the product.
  weight:
    type: number
    title: weight
-    description: The create's weight.
+    description: The variant's weight.
  length:
    type: number
    title: length
-    description: The create's length.
+    description: The variant's length.
  height:
    type: number
    title: height
-    description: The create's height.
+    description: The variant's height.
  width:
    type: number
    title: width
-    description: The create's width.
+    description: The variant's width.
  origin_country:
    type: string
    title: origin_country
-    description: The create's origin country.
+    description: The variant's origin country.
  material:
    type: string
    title: material
-    description: The create's material.
+    description: The variant's material.
  metadata:
    type: object
-    description: The create's metadata.
+    description: The variant's metadata, used to store custom key-value pairs.
  prices:
    type: array
-    description: The create's prices.
+    description: The variant's prices.
    items:
      $ref: ./AdminCreateProductVariantPrice.yaml
  options:
    type: object
-    description: The create's options.
+    description: >-
      The variant's options, where the key is an option's name, and the value is
      the option's value.
    example:
      Color: Black
@@ -1,5 +1,5 @@
 type: object
-description: The price's prices.
+description: The details of a variant's price.
 x-schemaName: AdminCreateProductVariantPrice
 required:
  - currency_code
@@ -16,11 +16,17 @@ properties:
  min_quantity:
    type: number
    title: min_quantity
-    description: The price's min quantity.
+    description: >-
      The minimum quantity that must be available in the cart for this price to
      apply.
  max_quantity:
    type: number
    title: max_quantity
-    description: The price's max quantity.
+    description: >-
      The maximum quantity that must not be surpassed in the cart for this price
      to apply.
  rules:
    type: object
    description: The price's rules.
    example:
      region_id: reg_123
@@ -1,5 +1,5 @@
 type: object
-description: The rule's rules.
+description: The promotion rule's details.
 x-schemaName: AdminCreatePromotionRule
 required:
  - operator
@@ -8,7 +8,10 @@ required:
 properties:
  operator:
    type: string
-    description: The rule's operator.
+    description: >-
      The operator used to check whether the buy rule applies on a cart. For
      example, `eq` means that the cart's value for the specified attribute must
      match the specified value.
    enum:
      - gt
      - lt
@@ -24,15 +27,20 @@ properties:
  attribute:
    type: string
    title: attribute
-    description: The rule's attribute.
+    description: >-
      The attribute to compare against when checking whether a promotion can be
      applied on a cart.
    example: item.product.id
  values:
    oneOf:
      - type: string
        title: values
-        description: The rule's values.
+        description: The attribute's value.
        example: prod_123
      - type: array
-        description: The rule's values.
+        description: The allowed attribute values.
        items:
          type: string
          title: values
-          description: The value's values.
+          description: An attribute value.
          example: prod_123
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The refund reason's details.
 x-schemaName: AdminCreateRefundReason
 required:
  - label
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The region's details.
 x-schemaName: AdminCreateRegion
 required:
  - name
@@ -13,28 +13,31 @@ properties:
    type: string
    title: currency_code
    description: The region's currency code.
    example: usd
  countries:
    type: array
    description: The region's countries.
    items:
      type: string
      title: countries
-      description: The country's countries.
+      description: A country code.
      example: us
  automatic_taxes:
    type: boolean
    title: automatic_taxes
-    description: The region's automatic taxes.
+    description: Whether taxes are calculated automatically during checkout in this region.
  is_tax_inclusive:
    type: boolean
    title: is_tax_inclusive
-    description: The region's is tax inclusive.
+    description: Whether prices in this region are tax inclusive.
  payment_providers:
    type: array
-    description: The region's payment providers.
+    description: The payment providers enabled in this region.
    items:
      type: string
      title: payment_providers
-      description: The payment provider's payment providers.
+      description: A payment provider's ID.
      example: pp_stripe_stripe
  metadata:
    type: object
-    description: The region's metadata.
+    description: The region's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The reservation's details.
 x-schemaName: AdminCreateReservation
 required:
  - location_id
@@ -9,23 +9,23 @@ properties:
  line_item_id:
    type: string
    title: line_item_id
-    description: The reservation's line item id.
+    description: The ID of the line item this reservation is created for.
  location_id:
    type: string
    title: location_id
-    description: The reservation's location id.
+    description: The ID of the location the quantity is reserved from.
  inventory_item_id:
    type: string
    title: inventory_item_id
-    description: The reservation's inventory item id.
+    description: The ID of the inventory item associated with the line item's variant.
  quantity:
    type: number
    title: quantity
-    description: The reservation's quantity.
+    description: The reserved quantity.
  description:
    type: string
    title: description
    description: The reservation's description.
  metadata:
    type: object
-    description: The reservation's metadata.
+    description: The reservation's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The sales channel's details.
 x-schemaName: AdminCreateSalesChannel
 required:
  - name
@@ -15,7 +15,7 @@ properties:
  is_disabled:
    type: boolean
    title: is_disabled
-    description: The sales channel's is disabled.
+    description: Whether the sales channel is disabled.
  metadata:
    type: object
-    description: The sales channel's metadata.
+    description: The sales channel's metadata, used to store custom key-value pairs.
@@ -1,15 +1,15 @@
 type: object
-description: SUMMARY
+description: The shipment's details.
 x-schemaName: AdminCreateShipment
 required:
  - labels
 properties:
  labels:
    type: array
-    description: The fulfillment's labels.
+    description: The shipment's labels.
    items:
      type: object
-      description: The label's labels.
+      description: A shipment label's details.
      required:
        - tracking_number
        - tracking_url
@@ -22,8 +22,8 @@ properties:
        tracking_url:
          type: string
          title: tracking_url
-          description: The label's tracking url.
+          description: The label's tracking URL.
        label_url:
          type: string
          title: label_url
-          description: The label's label url.
+          description: The label's URL.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The shipping option's details.
 x-schemaName: AdminCreateShippingOption
 required:
  - name
@@ -17,33 +17,46 @@ properties:
  service_zone_id:
    type: string
    title: service_zone_id
-    description: The shipping option's service zone id.
+    description: The ID of the service zone this shipping option belongs to.
  shipping_profile_id:
    type: string
    title: shipping_profile_id
-    description: The shipping option's shipping profile id.
+    description: The ID of the shipping profile this shipping option belongs to.
  data:
    type: object
-    description: The shipping option's data.
+    description: >-
      Any data necessary for fulfillment providers to handle shipping methods
      and fulfillments of this shipping option.
    externalDocs:
      url: >-
        https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
      description: Learn more about the data property.
  price_type:
    type: string
-    description: The shipping option's price type.
+    description: >
      The shipping option price's type. If `flat`, it means the option has a
      fixed price set in the `prices` property. `calculated` means that the
      shipping option's price is calculated during checkout.
    enum:
      - flat
      - calculated
  provider_id:
    type: string
    title: provider_id
-    description: The shipping option's provider id.
+    description: >-
      The ID of the fulfillment provider used to handle this shipping option and
      its associated methods and fulfillments.
  type:
    type: object
  prices:
    type: array
-    description: The shipping option's prices.
+    description: >-
      The shipping option's prices. If `price_type` is `calculated`, pass an
      empty array for this property.
    items:
      oneOf:
        - type: object
-          description: The price's prices.
+          description: The price for a currency code.
          x-schemaName: AdminCreateShippingOptionPriceWithCurrency
          required:
            - currency_code
@@ -58,7 +71,7 @@ properties:
              title: amount
              description: The price's amount.
        - type: object
-          description: The price's prices.
+          description: The price in a region.
          x-schemaName: AdminCreateShippingOptionPriceWithRegion
          required:
            - region_id
@@ -67,7 +80,7 @@ properties:
            region_id:
              type: string
              title: region_id
-              description: The price's region id.
+              description: The ID of the region this price is used in.
            amount:
              type: number
              title: amount
@@ -1,5 +1,5 @@
 type: object
-description: The rule's rules.
+description: The details of the shipping option rule.
 x-schemaName: AdminCreateShippingOptionRule
 required:
  - operator
@@ -8,7 +8,7 @@ required:
 properties:
  operator:
    type: string
-    description: The rule's operator.
+    description: The operator used to check whether a rule applies.
    enum:
      - gt
      - lt
@@ -21,15 +21,18 @@ properties:
  attribute:
    type: string
    title: attribute
-    description: The rule's attribute.
+    description: The name of a property or table that the rule applies to.
    example: customer_group
  value:
    oneOf:
      - type: string
        title: value
-        description: The rule's value.
+        description: A value of the attribute that enables this rule.
        example: cusgroup_123
      - type: array
-        description: The rule's value.
+        description: Values of the attribute that enable this rule.
        items:
          type: string
          title: value
-          description: The value's details.
+          description: A value of the attribute that enables this rule.
          example: cusgroup_123
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The shipping profile's details.
 x-schemaName: AdminCreateShippingProfile
 required:
  - name
@@ -15,4 +15,4 @@ properties:
    description: The shipping profile's type.
  metadata:
    type: object
-    description: The shipping profile's metadata.
+    description: The shipping profile's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The stock location's details.
 x-schemaName: AdminCreateStockLocation
 required:
  - name
@@ -11,9 +11,9 @@ properties:
  address_id:
    type: string
    title: address_id
-    description: The stock location's address id.
+    description: The ID of the stock location's address.
  address:
    $ref: ./AdminUpsertStockLocationAddress.yaml
  metadata:
    type: object
-    description: The stock location's metadata.
+    description: The stock location's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The tax rate's details.
 x-schemaName: AdminCreateTaxRate
 required:
  - name
@@ -9,18 +9,20 @@ properties:
    type: string
    title: name
    description: The tax rate's name.
    example: VAT
  tax_region_id:
    type: string
    title: tax_region_id
-    description: The tax rate's tax region id.
+    description: The ID of the tax region this rate belongs to.
  rate:
    type: number
    title: rate
-    description: The tax rate's rate.
+    description: The rate to charge.
    example: 10
  code:
    type: string
    title: code
-    description: The tax rate's code.
+    description: The code the tax rate is identified by.
  rules:
    type: array
    description: The tax rate's rules.
@@ -29,11 +31,14 @@ properties:
  is_default:
    type: boolean
    title: is_default
-    description: The tax rate's is default.
+    description: Whether the tax rate is the default in its tax region.
  is_combinable:
    type: boolean
    title: is_combinable
-    description: The tax rate's is combinable.
+    description: Whether the tax rate should be combined with parent rates.
    externalDocs:
      url: >-
        https://docs.medusajs.com/v2/resources/commerce-modules/tax/tax-rates-and-rules#combinable-tax-rates
  metadata:
    type: object
-    description: The tax rate's metadata.
+    description: The tax rate's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The tax rate rule's details.
 x-schemaName: AdminCreateTaxRateRule
 required:
  - reference
@@ -8,8 +8,10 @@ properties:
  reference:
    type: string
    title: reference
-    description: The tax rate's reference.
+    description: The name of a table in the database that this rule points to.
    example: product_type
  reference_id:
    type: string
    title: reference_id
-    description: The tax rate's reference id.
+    description: The ID of a record in the table specified in reference.
    example: ptype_123
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The tax region's details.
 x-schemaName: AdminCreateTaxRegion
 required:
  - country_code
@@ -8,6 +8,7 @@ properties:
    type: string
    title: country_code
    description: The tax region's country code.
    example: us
  province_code:
    type: string
    title: province_code
@@ -15,7 +16,7 @@ properties:
  parent_id:
    type: string
    title: parent_id
-    description: The tax region's parent id.
+    description: The ID of the parent tax region.
  default_tax_rate:
    type: object
    description: The tax region's default tax rate.
@@ -25,22 +26,26 @@ properties:
      rate:
        type: number
        title: rate
-        description: The default tax rate's rate.
+        description: The rate to charge.
        example: 10
      code:
        type: string
        title: code
-        description: The default tax rate's code.
+        description: The code the tax rate is identified by
      name:
        type: string
        title: name
        description: The default tax rate's name.
        example: VAT
      is_combinable:
        type: boolean
-        title: is_combinable
+        description: Whether the tax rate should be combined with parent rates.
-        description: The default tax rate's is combinable.
+        externalDocs:
          url: >-
            https://docs.medusajs.com/v2/resources/commerce-modules/tax/tax-rates-and-rules#combinable-tax-rates
      metadata:
        type: object
-        description: The default tax rate's metadata.
+        description: The default tax rate's metadata, used to store custom key-value pairs.
  metadata:
    type: object
-    description: The tax region's metadata.
+    description: The tax region's metadata, used to store custom key-value pairs.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the variant-inventory item association.
 x-schemaName: AdminCreateVariantInventoryItem
 required:
  - required_quantity
@@ -8,8 +8,8 @@ properties:
  required_quantity:
    type: number
    title: required_quantity
-    description: The product's required quantity.
+    description: The quantity of the variant in the inventory item.
  inventory_item_id:
    type: string
    title: inventory_item_id
-    description: The product's inventory item id.
+    description: The inventory item's ID.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of changing a workflow execution's step status.
 x-schemaName: AdminCreateWorkflowsAsyncResponse
 required:
  - transaction_id
@@ -8,16 +8,18 @@ properties:
  transaction_id:
    type: string
    title: transaction_id
-    description: The workflows execution's transaction id.
+    description: The workflows execution's transaction ID.
  step_id:
    type: string
    title: step_id
-    description: The workflows execution's step id.
+    description: The ID of the step whose status was changed.
-  response: {}
+  response:
-  compensate_input: {}
+    description: Sets the step's response. It accepts any type.
  compensate_input:
    description: Sets the compensation function's input. It accepts any response.
  action:
    type: string
-    description: The workflows execution's action.
+    description: Whether to invoke or compensate the step.
    enum:
      - invoke
      - compensate
@@ -1,9 +1,10 @@
 type: object
-description: SUMMARY
+description: The details of the workflow to execute.
 x-schemaName: AdminCreateWorkflowsRun
 properties:
-  input: {}
+  input:
    description: The input to pass to the workflow. Can be of any type.
  transaction_id:
    type: string
    title: transaction_id
-    description: The workflows execution's transaction id.
+    description: The ID of the workflow execution's transaction.
@@ -1,3 +1,57 @@
 type: object
-description: The supported currency's currency.
+description: The currency's currencies.
 x-schemaName: AdminCurrency
 required:
  - code
  - symbol
  - symbol_native
  - name
  - decimal_digits
  - rounding
  - raw_rounding
  - created_at
  - updated_at
  - deleted_at
 properties:
  code:
    type: string
    title: code
    description: The currency's code.
    example: usd
  symbol:
    type: string
    title: symbol
    description: The currency's symbol.
    example: $
  symbol_native:
    type: string
    title: symbol_native
    description: The currency's native symbol, if different than the symbol.
    example: $
  name:
    type: string
    title: name
    description: The currency's name.
  decimal_digits:
    type: number
    title: decimal_digits
    description: The number of digits after the decimal for prices in this currency.
  rounding:
    type: number
    title: rounding
    description: The rounding percision applied on prices in this currency.
  created_at:
    type: string
    format: date-time
    title: created_at
    description: The currency's creation date.
  updated_at:
    type: string
    format: date-time
    title: updated_at
    description: The currency's update date.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
    description: The currency's deletion date.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The paginated list of currencies.
 x-schemaName: AdminCurrencyListResponse
 required:
  - limit
@@ -10,17 +10,17 @@ properties:
  limit:
    type: number
    title: limit
-    description: The currency's limit.
+    description: The maximum number of items returned.
  offset:
    type: number
    title: offset
-    description: The currency's offset.
+    description: The number of items skipped before retrieving the returned items.
  count:
    type: number
    title: count
-    description: The currency's count.
+    description: The total number of items.
  currencies:
    type: array
-    description: The currency's currencies.
+    description: The list of currencies.
    items:
      $ref: ./AdminCurrency.yaml
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The currency's details.
 x-schemaName: AdminCurrencyResponse
 required:
  - currency
@@ -1,5 +1,5 @@
 type: object
-description: The order's customer.
+description: The customer's details.
 x-schemaName: AdminCustomer
 required:
  - has_account
@@ -12,19 +12,19 @@ required:
  - last_name
  - addresses
 properties:
  id:
    type: string
    title: id
    description: The customer's ID.
  has_account:
    type: boolean
    title: has_account
-    description: The customer's has account.
+    description: Whether the customer is registered.
  groups:
    type: array
    description: The customer's groups.
    items:
      $ref: ./AdminCustomerGroup.yaml
  id:
    type: string
    title: id
    description: The customer's ID.
  email:
    type: string
    title: email
@@ -33,11 +33,11 @@ properties:
  default_billing_address_id:
    type: string
    title: default_billing_address_id
-    description: The customer's default billing address id.
+    description: The ID of the address used as the default billing address.
  default_shipping_address_id:
    type: string
    title: default_shipping_address_id
-    description: The customer's default shipping address id.
+    description: The ID of the address used as the default shipping address.
  company_name:
    type: string
    title: company_name
@@ -61,23 +61,23 @@ properties:
    description: The customer's phone.
  metadata:
    type: object
-    description: The customer's metadata.
+    description: The customer's metadata, used to store custom key-value pairs.
  created_by:
    type: string
    title: created_by
-    description: The customer's created by.
+    description: The ID of the user that created this customer, if available.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
    description: The customer's deleted at.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The customer's created at.
+    description: The customer's creation date.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The customer's updated at.
+    description: The customer's update date.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
    description: The customer's deletion date.
@@ -28,39 +28,39 @@ properties:
  address_name:
    type: string
    title: address_name
-    description: The address's address name.
+    description: The address's name.
  is_default_shipping:
    type: boolean
    title: is_default_shipping
-    description: The address's is default shipping.
+    description: Whether the address is the default shipping address.
  is_default_billing:
    type: boolean
    title: is_default_billing
-    description: The address's is default billing.
+    description: Whether the address is the default billing address.
  customer_id:
    type: string
    title: customer_id
-    description: The address's customer id.
+    description: The ID of the customer that this address belongs to.
  company:
    type: string
    title: company
-    description: The address's company.
+    description: The customer's company.
  first_name:
    type: string
    title: first_name
-    description: The address's first name.
+    description: The customer's first name.
  last_name:
    type: string
    title: last_name
-    description: The address's last name.
+    description: The customer's last name.
  address_1:
    type: string
    title: address_1
-    description: The address's address 1.
+    description: The address's first line.
  address_2:
    type: string
    title: address_2
-    description: The address's address 2.
+    description: The address's second line.
  city:
    type: string
    title: city
@@ -69,6 +69,7 @@ properties:
    type: string
    title: country_code
    description: The address's country code.
    example: us
  province:
    type: string
    title: province
@@ -83,14 +84,14 @@ properties:
    description: The address's phone.
  metadata:
    type: object
-    description: The address's metadata.
+    description: The address's metadata, used to store custom key-value pairs.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The address's created at.
+    description: The address's creation date.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The address's updated at.
+    description: The address's update date.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The address's details.
 x-schemaName: AdminCustomerAddressResponse
 required:
  - address
@@ -1,3 +1,37 @@
 type: object
-description: The group's groups.
+description: The customer group's details.
 x-schemaName: AdminCustomerGroup
 required:
  - id
  - name
  - customers
  - metadata
  - created_at
  - updated_at
 properties:
  id:
    type: string
    title: id
    description: The customer group's ID.
  name:
    type: string
    title: name
    description: The customer group's name.
  customers:
    type: array
    description: The customer group's customers.
    items:
      $ref: ./BaseCustomer.yaml
  metadata:
    type: object
    description: The customer group's metadata, used to store custom key-value pairs.
  created_at:
    type: string
    format: date-time
    title: created_at
    description: The customer group's creation date.
  updated_at:
    type: string
    format: date-time
    title: updated_at
    description: The customer group's update date.
@@ -1,33 +1,33 @@
 type: object
-description: The customer group's customers.
+description: Filters to apply on customers to retrieve their groups.
 x-schemaName: AdminCustomerInGroupFilters
 properties:
  id:
    oneOf:
      - type: string
        title: id
-        description: The customer's ID.
+        description: Filter by a customer's ID.
      - type: array
-        description: The customer's ID.
+        description: Filter by customer IDs.
        items:
          type: string
          title: id
-          description: The id's ID.
+          description: A customer's ID.
  email:
    oneOf:
      - type: string
        title: email
-        description: The customer's email.
+        description: Filter by a customer's email.
        format: email
      - type: array
-        description: The customer's email.
+        description: Filter by customer emails.
        items:
          type: string
          title: email
-          description: The email's details.
+          description: A customer's email.
          format: email
      - type: object
-        description: The customer's email.
+        description: Apply filters on the customer's email.
        properties:
          $and:
            type: array
@@ -51,7 +51,7 @@ properties:
                title: $eq
                description: Filter by an exact match.
              - type: array
-                description: Filter by an exact match.
+                description: Filter by exact matches
                items:
                  type: string
                  title: $eq
@@ -164,71 +164,75 @@ properties:
    oneOf:
      - type: string
        title: default_billing_address_id
-        description: The customer's default billing address id.
+        description: Filter by the ID of a customer's default billing address.
      - type: array
-        description: The customer's default billing address id.
+        description: Filter by the IDs of a customers' default billing address.
        items:
          type: string
          title: default_billing_address_id
-          description: The default billing address id's details.
+          description: The ID of a customer's default billing address.
  default_shipping_address_id:
    oneOf:
      - type: string
        title: default_shipping_address_id
-        description: The customer's default shipping address id.
+        description: Filter by the ID of a customer's default shipping address.
      - type: array
-        description: The customer's default shipping address id.
+        description: Filter by the IDs of a customers' default shipping address.
        items:
          type: string
          title: default_shipping_address_id
-          description: The default shipping address id's details.
+          description: The ID of a customer's default shipping address.
  company_name:
    oneOf:
      - type: string
        title: company_name
-        description: The customer's company name.
+        description: Filter by a customer's company name.
      - type: array
-        description: The customer's company name.
+        description: Filter by customers' company names.
        items:
          type: string
          title: company_name
-          description: The company name's details.
+          description: A company name.
  first_name:
    oneOf:
      - type: string
        title: first_name
-        description: The customer's first name.
+        description: Filter by a customer's first name.
      - type: array
-        description: The customer's first name.
+        description: Filter by customers' first names.
        items:
          type: string
          title: first_name
-          description: The first name's details.
+          description: A first name.
  last_name:
    oneOf:
      - type: string
        title: last_name
-        description: The customer's last name.
+        description: Filter by a customer's last name.
      - type: array
-        description: The customer's last name.
+        description: Filter by customers' last names.
        items:
          type: string
          title: last_name
-          description: The last name's details.
+          description: A last name.
  created_by:
    oneOf:
      - type: string
        title: created_by
-        description: The customer's created by.
+        description: >-
          Filter by the ID of a user to retrieve the groups of the customers
          they created.
      - type: array
-        description: The customer's created by.
+        description: >-
          Filter by the ID of users to retrieve the groups of the customers they
          created.
        items:
          type: string
          title: created_by
-          description: The created by's details.
+          description: A user's ID.
  created_at:
    type: object
-    description: The customer's created at.
+    description: Filter the customer's creation date.
    properties:
      $and:
        type: array
@@ -252,7 +256,7 @@ properties:
            title: $eq
            description: Filter by an exact match.
          - type: array
-            description: Filter by an exact match.
+            description: Filter by exact matches
            items:
              type: string
              title: $eq
@@ -355,7 +359,7 @@ properties:
        description: Filter by whether a value for this parameter exists (not `null`).
  updated_at:
    type: object
-    description: The customer's updated at.
+    description: Filter the customer's update date.
    properties:
      $and:
        type: array
@@ -482,7 +486,7 @@ properties:
        description: Filter by whether a value for this parameter exists (not `null`).
  deleted_at:
    type: object
-    description: The customer's deleted at.
+    description: Filter the customer's deletion date.
    properties:
      $and:
        type: array
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The result of deleting the payment collection.
 x-schemaName: AdminDeletePaymentCollectionResponse
 required:
  - id
@@ -13,9 +13,9 @@ properties:
  object:
    type: string
    title: object
-    description: SUMMARY
+    description: The name of the object that was deleted.
    default: payment-collection
  deleted:
    type: boolean
    title: deleted
-    description: SUMMARY
+    description: Whether the object was deleted.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The draft order's details.
 x-schemaName: AdminDraftOrderResponse
 required:
  - draft_order
@@ -44,31 +44,35 @@ properties:
  order_id:
    type: string
    title: order_id
-    description: The exchange's order id.
+    description: The ID of the order the exchange is created for.
  return_items:
    type: array
-    description: The exchange's return items.
+    description: The items returned (inbound) by the exchange.
    items:
      $ref: ./AdminReturnItem.yaml
  additional_items:
    type: array
-    description: The exchange's additional items.
+    description: The new items (outbound) sent by the exchange.
    items:
      $ref: ./BaseExchangeItem.yaml
  no_notification:
    type: boolean
    title: no_notification
-    description: The exchange's no notification.
+    description: Whether to send the customer notifications when the exchange is updated.
  difference_due:
    type: number
    title: difference_due
-    description: The exchange's difference due.
+    description: >-
      The amount to be exchanged or refunded. If the amount is negative, it must
      be refunded. If positive, additional payment is required from the
      customer.
  return:
    description: the return associated with the exchange.
    $ref: ./AdminReturn.yaml
  return_id:
    type: string
    title: return_id
-    description: The exchange's return id.
+    description: The ID of the associated exchange.
  currency_code:
    type: string
    title: currency_code
@@ -80,31 +84,33 @@ properties:
  region_id:
    type: string
    title: region_id
-    description: The exchange's region id.
+    description: The ID of the associated order's region.
  customer_id:
    type: string
    title: customer_id
-    description: The exchange's customer id.
+    description: The ID of the customer that placed the order.
  sales_channel_id:
    type: string
    title: sales_channel_id
-    description: The exchange's sales channel id.
+    description: The ID of the sales channel the associated order belongs to.
  email:
    type: string
    title: email
-    description: The exchange's email.
+    description: The email used when placing the order.
    format: email
  display_id:
    type: number
    title: display_id
-    description: The exchange's display id.
+    description: The exchange's display ID.
  shipping_address:
    description: The shipping address to send new items to.
    $ref: ./BaseOrderAddress.yaml
  billing_address:
    description: The customer's billing address.
    $ref: ./BaseOrderAddress.yaml
  shipping_methods:
    type: array
-    description: The exchange's shipping methods.
+    description: The shipping methods used to send the new (outbound) items.
    items:
      $ref: ./BaseOrderShippingMethod.yaml
  payment_collections:
@@ -128,7 +134,7 @@ properties:
      - requires_action
  fulfillments:
    type: array
-    description: The exchange's fulfillments.
+    description: The exchange's fulfillments of new (outbound) items.
    items:
      $ref: ./BaseOrderFulfillment.yaml
  fulfillment_status:
@@ -146,87 +152,91 @@ properties:
  transactions:
    type: array
    description: The exchange's transactions.
    externalDocs:
      url: >-
        https://docs.medusajs.com/v2/resources/commerce-modules/order/transactions
    items:
      $ref: ./BaseOrderTransaction.yaml
  summary:
    description: The totals summary of the exchange.
    $ref: ./BaseOrderSummary.yaml
  metadata:
    type: object
-    description: The exchange's metadata.
+    description: The exchange's metadata, can hold custom key-value pairs.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The exchange's created at.
+    description: The date that the exchange was created.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The exchange's updated at.
+    description: The date that the exchange was updated.
  original_item_total:
    type: number
    title: original_item_total
-    description: The exchange's original item total.
+    description: The total of the original items in the order.
  original_item_subtotal:
    type: number
    title: original_item_subtotal
-    description: The exchange's original item subtotal.
+    description: The subtotal of the original items in the order.
  original_item_tax_total:
    type: number
    title: original_item_tax_total
-    description: The exchange's original item tax total.
+    description: The total tax of the original items in the order.
  item_total:
    type: number
    title: item_total
-    description: The exchange's item total.
+    description: The total of the exchange's new items.
  item_subtotal:
    type: number
    title: item_subtotal
-    description: The exchange's item subtotal.
+    description: The subtotal of the exchange's new items.
  item_tax_total:
    type: number
    title: item_tax_total
-    description: The exchange's item tax total.
+    description: The tax total of the exchange's new items.
  original_total:
    type: number
    title: original_total
-    description: The exchange's original total.
+    description: The total of the order.
  original_subtotal:
    type: number
    title: original_subtotal
-    description: The exchange's original subtotal.
+    description: The subtotal of the order.
  original_tax_total:
    type: number
    title: original_tax_total
-    description: The exchange's original tax total.
+    description: The tax total of the order.
  total:
    type: number
    title: total
-    description: The exchange's total.
+    description: The total of the exchange.
  subtotal:
    type: number
    title: subtotal
-    description: The exchange's subtotal.
+    description: The subtotal of the exchange.
  tax_total:
    type: number
    title: tax_total
-    description: The exchange's tax total.
+    description: The tax total of the exchange.
  discount_total:
    type: number
    title: discount_total
-    description: The exchange's discount total.
+    description: The discount total of the exchange.
  discount_tax_total:
    type: number
    title: discount_tax_total
-    description: The exchange's discount tax total.
+    description: The total taxes on discount of the exchange.
  gift_card_total:
    type: number
    title: gift_card_total
-    description: The exchange's gift card total.
+    description: The gift cards total of the exchange.
  gift_card_tax_total:
    type: number
    title: gift_card_tax_total
-    description: The exchange's gift card tax total.
+    description: The total taxes on the gift card of the exchange.
  shipping_total:
    type: number
    title: shipping_total
@@ -242,12 +252,12 @@ properties:
  original_shipping_total:
    type: number
    title: original_shipping_total
-    description: The exchange's original shipping total.
+    description: The order's shipping total.
  original_shipping_subtotal:
    type: number
    title: original_shipping_subtotal
-    description: The exchange's original shipping subtotal.
+    description: The order's shipping subtotal.
  original_shipping_tax_total:
    type: number
    title: original_shipping_tax_total
-    description: The exchange's original shipping tax total.
+    description: The order's shipping tax total.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of deleting an exchange.
 x-schemaName: AdminExchangeDeleteResponse
 required:
  - id
@@ -18,4 +18,4 @@ properties:
  deleted:
    type: boolean
    title: deleted
-    description: Whether the Exchange was deleted.
+    description: Whether the exchange was deleted.
@@ -1,11 +1,12 @@
 type: object
-description: SUMMARY
+description: The exchange's details.
 x-schemaName: AdminExchangeOrderResponse
 required:
  - order
  - exchange
 properties:
  order:
    description: The details of the associated order.
    $ref: ./Order.yaml
  exchange:
    $ref: ./AdminExchange.yaml
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: A preview of the order once the exchange is applied.
 x-schemaName: AdminExchangePreviewResponse
 required:
  - order_preview
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of a requested exchange.
 x-schemaName: AdminExchangeRequestResponse
 required:
  - return
@@ -7,8 +7,10 @@ required:
  - exchange
 properties:
  return:
    description: The associated return's details.
    $ref: ./AdminReturn.yaml
  order_preview:
    description: A preview of the order once the exchange is applied.
    $ref: ./OrderPreview.yaml
  exchange:
    $ref: ./AdminExchange.yaml
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The exchange's details.
 x-schemaName: AdminExchangeResponse
 required:
  - exchange
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of an exchange's return.
 x-schemaName: AdminExchangeReturnResponse
 required:
  - order_preview
@@ -1,3 +0,0 @@
 type: object
 description: SUMMARY
 x-schemaName: AdminExportProductRequest
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the product export.
 x-schemaName: AdminExportProductResponse
 required:
  - transaction_id
@@ -7,4 +7,7 @@ properties:
  transaction_id:
    type: string
    title: transaction_id
-    description: The product's transaction id.
+    description: >-
      The ID of the workflow execution's transaction. Use it to check the status
      of the export by sending a GET request to
      `/admin/workflows-executions/export-products/:transaction-id`
@@ -1,5 +1,5 @@
 type: object
-description: The upload's file.
+description: A file's details.
 x-schemaName: AdminFile
 required:
  - id
@@ -12,4 +12,4 @@ properties:
  url:
    type: string
    title: url
-    description: The file's url.
+    description: The file's URL.
@@ -1,11 +1,11 @@
 type: object
-description: SUMMARY
+description: The list of uploaded files.
 x-schemaName: AdminFileListResponse
 required:
  - files
 properties:
  files:
    type: array
-    description: The upload's files.
+    description: The list of uploaded files.
    items:
      $ref: ./AdminFile.yaml
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: A file's details.
 x-schemaName: AdminFileResponse
 required:
  - file
@@ -27,18 +27,20 @@ properties:
  location_id:
    type: string
    title: location_id
-    description: The fulfillment's location id.
+    description: The ID of the location the fulfillment's items are shipped from.
  provider_id:
    type: string
    title: provider_id
-    description: The fulfillment's provider id.
+    description: The ID of the fulfillment provider handling this fulfillment.
  shipping_option_id:
    type: string
    title: shipping_option_id
-    description: The fulfillment's shipping option id.
+    description: The ID of the shipping option this fulfillment is created for.
  provider:
    description: The details of the fulfillment provider using to handle this fulfillment.
    $ref: ./AdminFulfillmentProvider.yaml
  delivery_address:
    description: The address to deliver the item to.
    $ref: ./AdminFulfillmentAddress.yaml
  items:
    type: array
@@ -47,43 +49,48 @@ properties:
      $ref: ./AdminFulfillmentItem.yaml
  labels:
    type: array
-    description: The fulfillment's labels.
+    description: The fulfillment's shipment labels.
    items:
      $ref: ./AdminFulfillmentLabel.yaml
  packed_at:
    type: string
    title: packed_at
-    description: The fulfillment's packed at.
+    description: The date the fulfillment was packed at.
  shipped_at:
    type: string
    title: shipped_at
-    description: The fulfillment's shipped at.
+    description: The date the fulfillment was shipped at.
  delivered_at:
    type: string
    title: delivered_at
-    description: The fulfillment's delivered at.
+    description: The date the fulfillment was delivered at.
  canceled_at:
    type: string
    title: canceled_at
-    description: The fulfillment's canceled at.
+    description: The date the fulfillment was canceled at.
  data:
    type: object
-    description: The fulfillment's data.
+    description: >-
      The fulfillment's data, useful for the third-party provider handling the
      fulfillment.
    externalDocs:
      url: >-
        https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
  metadata:
    type: object
-    description: The fulfillment's metadata.
+    description: The fulfillment's metadata, can hold custom key-value pairs.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The fulfillment's created at.
+    description: The date the fulfillment was created at.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The fulfillment's updated at.
+    description: The date the fulfillment was updated at.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
-    description: The fulfillment's deleted at.
+    description: The date the fulfillment was deleted at.
@@ -1,5 +1,5 @@
 type: object
-description: The fulfillment's delivery address.
+description: An address's details.
 x-schemaName: AdminFulfillmentAddress
 required:
  - id
@@ -22,66 +22,66 @@ properties:
  id:
    type: string
    title: id
-    description: The delivery address's ID.
+    description: The address's ID.
  fulfillment_id:
    type: string
    title: fulfillment_id
-    description: The delivery address's fulfillment id.
+    description: The ID of the fulfillment that the address belongs to.
  company:
    type: string
    title: company
-    description: The delivery address's company.
+    description: The address's company.
  first_name:
    type: string
    title: first_name
-    description: The delivery address's first name.
+    description: The address's first name.
  last_name:
    type: string
    title: last_name
-    description: The delivery address's last name.
+    description: The address's last name.
  address_1:
    type: string
    title: address_1
-    description: The delivery address's address 1.
+    description: The address's first line.
  address_2:
    type: string
    title: address_2
-    description: The delivery address's address 2.
+    description: The address's second line.
  city:
    type: string
    title: city
-    description: The delivery address's city.
+    description: The address's city.
  country_code:
    type: string
    title: country_code
-    description: The delivery address's country code.
+    description: The address's country code.
  province:
    type: string
    title: province
-    description: The delivery address's province.
+    description: The address's province.
  postal_code:
    type: string
    title: postal_code
-    description: The delivery address's postal code.
+    description: The address's postal code.
  phone:
    type: string
    title: phone
-    description: The delivery address's phone.
+    description: The address's phone.
  metadata:
    type: object
-    description: The delivery address's metadata.
+    description: The address's metadata, can hold custom key-value pairs.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The delivery address's created at.
+    description: The date the address was created.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The delivery address's updated at.
+    description: The date the address was updated.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
-    description: The delivery address's deleted at.
+    description: The date the address was deleted.
@@ -1,5 +1,5 @@
 type: object
-description: The item's items.
+description: The details of a fulfillment's item.
 x-schemaName: AdminFulfillmentItem
 required:
  - id
@@ -25,11 +25,11 @@ properties:
  quantity:
    type: number
    title: quantity
-    description: The item's quantity.
+    description: The item's quantity to be fulfilled.
  sku:
    type: string
    title: sku
-    description: The item's sku.
+    description: The item's SKU.
  barcode:
    type: string
    title: barcode
@@ -37,27 +37,27 @@ properties:
  line_item_id:
    type: string
    title: line_item_id
-    description: The item's line item id.
+    description: The ID of the order's line item to be fulfilled.
  inventory_item_id:
    type: string
    title: inventory_item_id
-    description: The item's inventory item id.
+    description: The ID of the inventory item of the underlying product variant.
  fulfillment_id:
    type: string
    title: fulfillment_id
-    description: The item's fulfillment id.
+    description: The ID of the fulfillment the item belongs to.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The item's created at.
+    description: The date the item was created.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The item's updated at.
+    description: The date the item was updated.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
-    description: The item's deleted at.
+    description: The date the item was deleted.
@@ -1,5 +1,5 @@
 type: object
-description: The label's labels.
+description: The details of a fulfillmet's shipment label.
 x-schemaName: AdminFulfillmentLabel
 required:
  - id
@@ -22,27 +22,27 @@ properties:
  tracking_url:
    type: string
    title: tracking_url
-    description: The label's tracking url.
+    description: The label's tracking URL.
  label_url:
    type: string
    title: label_url
-    description: The label's label url.
+    description: The label's URL.
  fulfillment_id:
    type: string
    title: fulfillment_id
-    description: The label's fulfillment id.
+    description: The ID of the fulfillment the label is associated with.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The label's created at.
+    description: The date the label was created.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The label's updated at.
+    description: The date the label was updated.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
-    description: The label's deleted at.
+    description: The date the label was deleted.
@@ -1,3 +1,3 @@
 type: object
-description: The fulfillment provider's fulfillment providers.
+description: The shipping option's provider.
 x-schemaName: AdminFulfillmentProvider
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The paginated list of fulfillment providers.
 x-schemaName: AdminFulfillmentProviderListResponse
 required:
  - limit
@@ -10,17 +10,17 @@ properties:
  limit:
    type: number
    title: limit
-    description: The fulfillment provider's limit.
+    description: The maximum number of items returned.
  offset:
    type: number
    title: offset
-    description: The fulfillment provider's offset.
+    description: The number of items skipped before retrieving the returned items.
  count:
    type: number
    title: count
-    description: The fulfillment provider's count.
+    description: The total count of items.
  fulfillment_providers:
    type: array
-    description: The fulfillment provider's fulfillment providers.
+    description: The list of fulfillment providers.
    items:
      $ref: ./AdminFulfillmentProvider.yaml
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: A fulfillment's details.
 x-schemaName: AdminFulfillmentResponse
 required:
  - fulfillment
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The deletion details.
 x-schemaName: AdminFulfillmentSetDeleteResponse
 required:
  - id
@@ -18,4 +18,4 @@ properties:
  deleted:
    type: boolean
    title: deleted
-    description: Whether the Fulfillment Set was deleted.
+    description: Whether the fulfillment set was deleted.
@@ -1,3 +1,56 @@
 type: object
-description: The geo zone's geo zones.
+description: The geo zone's details.
 x-schemaName: AdminGeoZone
 required:
  - id
  - type
  - country_code
  - province_code
  - city
  - postal_expression
  - created_at
  - updated_at
  - deleted_at
 properties:
  id:
    type: string
    title: id
    description: The geo zone's ID.
  type:
    type: string
    description: The geo zone's type.
    enum:
      - country
      - province
      - city
      - zip
  country_code:
    type: string
    title: country_code
    description: The geo zone's country code.
  province_code:
    type: string
    title: province_code
    description: The geo zone's province code.
  city:
    type: string
    title: city
    description: The geo zone's city.
  postal_expression:
    type: object
    description: The geo zone's postal expression.
  created_at:
    type: string
    format: date-time
    title: created_at
    description: The date the geo zone was created.
  updated_at:
    type: string
    format: date-time
    title: updated_at
    description: The date the geo zone was update.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
    description: The date the geo zone was deleted.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The import's details.
 x-schemaName: AdminImportProductRequest
 required:
  - file
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The import process's details.
 x-schemaName: AdminImportProductResponse
 required:
  - transaction_id
@@ -8,10 +8,12 @@ properties:
  transaction_id:
    type: string
    title: transaction_id
-    description: The product's transaction id.
+    description: >-
      The ID of the workflow execution's transaction. This is useful to confirm
      the import using the `/admin/products/:transaction-id/import` API route.
  summary:
    type: object
-    description: The product's summary.
+    description: The import's summary.
    required:
      - toCreate
      - toUpdate
@@ -19,8 +21,8 @@ properties:
      toCreate:
        type: number
        title: toCreate
-        description: The summary's tocreate.
+        description: The number of products that will be created by this import.
      toUpdate:
        type: number
        title: toUpdate
-        description: The summary's toupdate.
+        description: The number of products that will be updated by this import.
@@ -12,7 +12,7 @@ properties:
  sku:
    type: string
    title: sku
-    description: The inventory item's sku.
+    description: The inventory item's SKU.
  origin_country:
    type: string
    title: origin_country
@@ -20,15 +20,15 @@ properties:
  hs_code:
    type: string
    title: hs_code
-    description: The inventory item's hs code.
+    description: The inventory item's HS code.
  requires_shipping:
    type: boolean
    title: requires_shipping
-    description: The inventory item's requires shipping.
+    description: Whether the inventory item requires shipping.
  mid_code:
    type: string
    title: mid_code
-    description: The inventory item's mid code.
+    description: The inventory item's MID code.
  material:
    type: string
    title: material
@@ -60,12 +60,12 @@ properties:
  thumbnail:
    type: string
    title: thumbnail
-    description: The inventory item's thumbnail.
+    description: The URL of the inventory item's thumbnail.
  metadata:
    type: object
-    description: The inventory item's metadata.
+    description: The inventory item's metadata, can hold custom key-value pairs.
  location_levels:
    type: array
-    description: The inventory item's location levels.
+    description: The inventory item's associated inventory levels.
    items:
      $ref: ./AdminInventoryLevel.yaml
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The inventory item's details.
 x-schemaName: AdminInventoryItemResponse
 required:
  - inventory_item
@@ -1,5 +1,5 @@
 type: object
-description: The location level's location levels.
+description: The inventory level's details.
 x-schemaName: AdminInventoryLevel
 required:
  - id
@@ -20,57 +20,56 @@ properties:
  id:
    type: string
    title: id
-    description: The location level's ID.
+    description: The inventory level's ID.
  created_at:
    type: string
    format: date-time
    title: created_at
    description: The location level's created at.
  updated_at:
    type: string
    format: date-time
    title: updated_at
    description: The location level's updated at.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
    description: The location level's deleted at.
  inventory_item_id:
    type: string
    title: inventory_item_id
-    description: The location level's inventory item id.
+    description: The ID of the inventory item this level belongs to.
  location_id:
    type: string
    title: location_id
-    description: The location level's location id.
+    description: The ID of the stock location this level belongs to.
  stocked_quantity:
    type: number
    title: stocked_quantity
-    description: The location level's stocked quantity.
+    description: >-
-  raw_stocked_quantity:
+      The quantity of the associated inventory item stocked in the associated
-    type: object
+      stock location.
    description: The location level's raw stocked quantity.
  reserved_quantity:
    type: number
    title: reserved_quantity
-    description: The location level's reserved quantity.
+    description: >-
-  raw_reserved_quantity:
+      The reserved quantity of the associated inventory item stocked in the
-    type: object
+      associated stock location.
    description: The location level's raw reserved quantity.
  incoming_quantity:
    type: number
    title: incoming_quantity
-    description: The location level's incoming quantity.
+    description: >-
-  raw_incoming_quantity:
+      The incoming quantity of the associated inventory item stocked in the
-    type: object
+      associated stock location.
    description: The location level's raw incoming quantity.
  metadata:
    type: object
-    description: The location level's metadata.
+    description: The location level's metadata, can hold custom key-value pairs.
  inventory_item:
    type: object
  available_quantity:
    type: number
    title: available_quantity
-    description: The location level's available quantity.
+    description: >-
      The quantity available for order of the associated inventory item in the
      associated stock location.
  created_at:
    type: string
    format: date-time
    title: created_at
    description: The date the inventory level was created.
  updated_at:
    type: string
    format: date-time
    title: updated_at
    description: The date the inventory level was updated.
  deleted_at:
    type: string
    format: date-time
    title: deleted_at
    description: The date the inventory level was deleted.
@@ -19,7 +19,7 @@ properties:
  accepted:
    type: boolean
    title: accepted
-    description: The invite's accepted.
+    description: Whether the invite has been accepted.
  token:
    type: string
    title: token
@@ -27,18 +27,18 @@ properties:
  expires_at:
    type: string
    title: expires_at
-    description: The invite's expires at.
+    description: The invite's expiry date.
    format: date-time
  metadata:
    type: object
-    description: The invite's metadata.
+    description: The invite's metadata, can hold custom key-value pairs.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The invite's created at.
+    description: The date the invite was created.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The invite's updated at.
+    description: The date the invite was updated.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The invite's details.
 x-schemaName: AdminInviteResponse
 required:
  - invite
@@ -1,5 +1,5 @@
 type: object
-description: The removal details.
+description: The products removal details.
 properties:
  remove:
    type: array
@@ -16,48 +16,57 @@ properties:
  to:
    type: string
    title: to
-    description: The notification's to.
+    description: >-
      Where to send the notification to. For example, if `channel` is `email`,
      this can be an email number.
  channel:
    type: string
    title: channel
-    description: The notification's channel.
+    description: Through which channel is the notification sent through.
    example: email
  template:
    type: string
    title: template
-    description: The notification's template.
+    description: >-
      The ID of the template in a third-party service used as the notification's
      shape.
  data:
    type: object
-    description: The notification's data.
+    description: Data payload to send with the notification.
  trigger_type:
    type: string
    title: trigger_type
-    description: The notification's trigger type.
+    description: What triggered this notification.
    example: order.created
  resource_id:
    type: string
    title: resource_id
-    description: The notification's resource id.
+    description: >-
      The ID of the associated resource. For example, if the notification was
      triggered because an order was created, this would be the ID of the order.
  resource_type:
    type: string
    title: resource_type
-    description: The notification's resource type.
+    description: The type of the resource that triggered the notification.
    example: order
  receiver_id:
    type: string
    title: receiver_id
-    description: The notification's receiver id.
+    description: The ID of the user or customer that's receiving this notification.
  original_notification_id:
    type: string
    title: original_notification_id
-    description: The notification's original notification id.
+    description: The ID of the original notification, if this notification is resent.
  external_id:
    type: string
    title: external_id
-    description: The notification's external id.
+    description: The ID of the notification in an external or third-party system.
  provider_id:
    type: string
    title: provider_id
-    description: The notification's provider id.
+    description: The ID of the provider used to send the notification.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The notification's created at.
+    description: The date the notification was created.
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The paginated list of notifications.
 x-schemaName: AdminNotificationListResponse
 required:
  - limit
@@ -10,17 +10,17 @@ properties:
  limit:
    type: number
    title: limit
-    description: The notification's limit.
+    description: The maximum number of items returned.
  offset:
    type: number
    title: offset
-    description: The notification's offset.
+    description: The number of items skipped before retrieving the returned items.
  count:
    type: number
    title: count
-    description: The notification's count.
+    description: The total count of items.
  notifications:
    type: array
-    description: The notification's notifications.
+    description: The list of notifications.
    items:
      $ref: ./AdminNotification.yaml
@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The notification's details.
 x-schemaName: AdminNotificationResponse
 required:
  - notification
@@ -70,19 +70,19 @@ properties:
  region_id:
    type: string
    title: region_id
-    description: The order's region id.
+    description: The ID of the region associated with the order.
  customer_id:
    type: string
    title: customer_id
-    description: The order's customer id.
+    description: The ID of the customer that placed the order.
  sales_channel_id:
    type: string
    title: sales_channel_id
-    description: The order's sales channel id.
+    description: The ID of the sales channel the order is placed in.
  email:
    type: string
    title: email
-    description: The order's email.
+    description: The email of the customer that placed the order.
    format: email
  currency_code:
    type: string
@@ -91,7 +91,7 @@ properties:
  display_id:
    type: number
    title: display_id
-    description: The order's display id.
+    description: The order's display ID.
  items:
    type: array
    description: The order's items.
@@ -137,73 +137,73 @@ properties:
    $ref: ./BaseOrderSummary.yaml
  metadata:
    type: object
-    description: The order's metadata.
+    description: The order's metadata, can hold custom key-value pairs.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The order's created at.
+    description: The date the order was created.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The order's updated at.
+    description: The date the order was updated.
  original_item_total:
    type: number
    title: original_item_total
-    description: The order's original item total.
+    description: The total of the order's items including taxes, excluding promotions.
  original_item_subtotal:
    type: number
    title: original_item_subtotal
-    description: The order's original item subtotal.
+    description: The total of the order's items excluding taxes, including promotions.
  original_item_tax_total:
    type: number
    title: original_item_tax_total
-    description: The order's original item tax total.
+    description: The tax total of the order's items excluding promotions.
  item_total:
    type: number
    title: item_total
-    description: The order's item total.
+    description: The total of the order's items including taxes and promotions.
  item_subtotal:
    type: number
    title: item_subtotal
-    description: The order's item subtotal.
+    description: The total of the order's items excluding taxes, including promotions.
  item_tax_total:
    type: number
    title: item_tax_total
-    description: The order's item tax total.
+    description: The tax total of the order's items including promotions.
  original_total:
    type: number
    title: original_total
-    description: The order's original total.
+    description: The order's total excluding promotions, including taxes.
  original_subtotal:
    type: number
    title: original_subtotal
-    description: The order's original subtotal.
+    description: The order's total excluding taxes, including promotions.
  original_tax_total:
    type: number
    title: original_tax_total
-    description: The order's original tax total.
+    description: The order's tax total, excluding promotions.
  total:
    type: number
    title: total
-    description: The order's total.
+    description: The order's total including taxes and promotions.
  subtotal:
    type: number
    title: subtotal
-    description: The order's subtotal.
+    description: The order's total excluding taxes, including promotions.
  tax_total:
    type: number
    title: tax_total
-    description: The order's tax total.
+    description: The order's tax total including promotions.
  discount_total:
    type: number
    title: discount_total
-    description: The order's discount total.
+    description: The order's discount or promotions total.
  discount_tax_total:
    type: number
    title: discount_tax_total
-    description: The order's discount tax total.
+    description: The tax total of order's discount or promotion.
  gift_card_total:
    type: number
    title: gift_card_total
@@ -211,28 +211,28 @@ properties:
  gift_card_tax_total:
    type: number
    title: gift_card_tax_total
-    description: The order's gift card tax total.
+    description: The tax total of the order's gift card.
  shipping_total:
    type: number
    title: shipping_total
-    description: The order's shipping total.
+    description: The order's shipping total including taxes and promotions.
  shipping_subtotal:
    type: number
    title: shipping_subtotal
-    description: The order's shipping subtotal.
+    description: The order's shipping total excluding taxes, including promotions.
  shipping_tax_total:
    type: number
    title: shipping_tax_total
-    description: The order's shipping tax total.
+    description: The tax total of the order's shipping.
  original_shipping_total:
    type: number
    title: original_shipping_total
-    description: The order's original shipping total.
+    description: The order's shipping total including taxes, excluding promotions.
  original_shipping_subtotal:
    type: number
    title: original_shipping_subtotal
-    description: The order's original shipping subtotal.
+    description: The order's shipping total excluding taxes, including promotions.
  original_shipping_tax_total:
    type: number
    title: original_shipping_tax_total
-    description: The order's original shipping tax total.
+    description: The tax total of the order's shipping excluding promotions.
@@ -1,5 +1,5 @@
 type: object
-description: The order's billing address.
+description: An order address.
 x-schemaName: AdminOrderAddress
 required:
  - id
@@ -7,66 +7,67 @@ required:
  - created_at
  - updated_at
 properties:
  country:
    $ref: ./AdminRegionCountry.yaml
  id:
    type: string
    title: id
-    description: The billing address's ID.
+    description: The address's ID.
  customer_id:
    type: string
    title: customer_id
-    description: The billing address's customer id.
+    description: The ID of the customer this address belongs to.
  first_name:
    type: string
    title: first_name
-    description: The billing address's first name.
+    description: The address's first name.
  last_name:
    type: string
    title: last_name
-    description: The billing address's last name.
+    description: The address's last name.
  phone:
    type: string
    title: phone
-    description: The billing address's phone.
+    description: The address's phone.
  company:
    type: string
    title: company
-    description: The billing address's company.
+    description: The address's company.
  address_1:
    type: string
    title: address_1
-    description: The billing address's address 1.
+    description: The address's first line.
  address_2:
    type: string
    title: address_2
-    description: The billing address's address 2.
+    description: The address's second line.
  city:
    type: string
    title: city
-    description: The billing address's city.
+    description: The address's city.
  country_code:
    type: string
    title: country_code
-    description: The billing address's country code.
+    description: The address's country code.
    example: us
  country:
    $ref: ./AdminRegionCountry.yaml
  province:
    type: string
    title: province
-    description: The billing address's province.
+    description: The address's province.
  postal_code:
    type: string
    title: postal_code
-    description: The billing address's postal code.
+    description: The address's postal code.
  metadata:
    type: object
-    description: The billing address's metadata.
+    description: The address's metadata, can hold custom key-value pairs.
  created_at:
    type: string
    format: date-time
    title: created_at
-    description: The billing address's created at.
+    description: The date the address was created.
  updated_at:
    type: string
    format: date-time
    title: updated_at
-    description: The billing address's updated at.
+    description: The date the address was updated.
		`@@ -0,0 +1,2 @@`
							`curl -X POST '{backend_url}/auth/token/refresh' \`
							`-H 'Authorization: Bearer {token}'`
		`@@ -1 +1 @@`
			`curl -X POST '{backend_url}/auth/user/{auth_provider}'`				`curl -X POST '{backend_url}/auth/user/github'`