From 658339767be30f839e7247d804ac5593af39e2b7 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Mon, 7 Aug 2023 16:54:48 +0300
Subject: [PATCH] chore(docs): Generated API Reference (#4706)

Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com>
Co-authored-by: Shahed Nasser <shahednasser@gmail.com>
---
 docs/api/admin.oas.json                       | 5463 ++++++++++-------
 .../JavaScript/admin_auth/delete.js           |    2 +-
 .../JavaScript/admin_auth/post.js             |    4 +-
 .../JavaScript/admin_batch-jobs/get.js        |    4 +-
 .../JavaScript/admin_batch-jobs_{id}/get.js   |    2 +-
 .../admin_batch-jobs_{id}_cancel/post.js      |    2 +-
 .../admin_batch-jobs_{id}_confirm/post.js     |    2 +-
 .../JavaScript/admin_collections/post.js      |    2 +-
 .../admin_collections_{id}/delete.js          |    2 +-
 .../JavaScript/admin_collections_{id}/get.js  |    2 +-
 .../JavaScript/admin_collections_{id}/post.js |    4 +-
 .../delete.js                                 |   12 +
 .../post.js                                   |   12 +
 .../JavaScript/admin_customer-groups/post.js  |    2 +-
 .../admin_customer-groups_{id}/delete.js      |    2 +-
 .../admin_customer-groups_{id}/get.js         |    2 +-
 .../admin_customer-groups_{id}/post.js        |    4 +-
 .../get.js                                    |    2 +-
 .../delete.js                                 |    4 +-
 .../post.js                                   |    4 +-
 .../JavaScript/admin_customers/post.js        |    8 +-
 .../JavaScript/admin_customers_{id}/get.js    |    2 +-
 .../JavaScript/admin_customers_{id}/post.js   |    4 +-
 .../JavaScript/admin_discounts/post.js        |    2 +-
 .../post.js                                   |    2 +-
 .../delete.js                                 |    2 +-
 .../get.js                                    |    2 +-
 .../post.js                                   |    4 +-
 .../delete.js                                 |    4 +-
 .../post.js                                   |    4 +-
 .../JavaScript/admin_discounts_{id}/delete.js |    2 +-
 .../JavaScript/admin_discounts_{id}/get.js    |    2 +-
 .../JavaScript/admin_discounts_{id}/post.js   |    4 +-
 .../post.js                                   |    4 +-
 .../delete.js                                 |    2 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    2 +-
 .../JavaScript/admin_draft-orders/post.js     |    2 +-
 .../admin_draft-orders_{id}/delete.js         |    2 +-
 .../JavaScript/admin_draft-orders_{id}/get.js |    2 +-
 .../admin_draft-orders_{id}/post.js           |    2 +-
 .../post.js                                   |    2 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    2 +-
 .../admin_draft-orders_{id}_pay/post.js       |    2 +-
 .../admin_gift-cards_{id}/delete.js           |    2 +-
 .../JavaScript/admin_gift-cards_{id}/get.js   |    2 +-
 .../JavaScript/admin_gift-cards_{id}/post.js  |    2 +-
 .../JavaScript/admin_inventory-items/post.js  |    2 +-
 .../post.js                                   |    2 +-
 .../JavaScript/admin_invites_accept/post.js   |    6 +-
 .../admin_invites_{invite_id}/delete.js       |    2 +-
 .../admin_invites_{invite_id}_resend/post.js  |    2 +-
 .../JavaScript/admin_notes/post.js            |    4 +-
 .../JavaScript/admin_notes_{id}/delete.js     |    2 +-
 .../JavaScript/admin_notes_{id}/get.js        |    2 +-
 .../JavaScript/admin_notes_{id}/post.js       |    4 +-
 .../admin_notifications_{id}_resend/post.js   |    2 +-
 .../JavaScript/admin_order-edits/post.js      |    2 +-
 .../admin_order-edits_{id}/delete.js          |    2 +-
 .../JavaScript/admin_order-edits_{id}/post.js |    2 +-
 .../admin_order-edits_{id}_cancel/post.js     |    2 +-
 .../delete.js                                 |    2 +-
 .../admin_order-edits_{id}_confirm/post.js    |    2 +-
 .../admin_order-edits_{id}_items/post.js      |    2 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    2 +-
 .../admin_order-edits_{id}_request/post.js    |    2 +-
 .../JavaScript/admin_orders_{id}/get.js       |    2 +-
 .../JavaScript/admin_orders_{id}/post.js      |    4 +-
 .../admin_orders_{id}_archive/post.js         |    2 +-
 .../admin_orders_{id}_cancel/post.js          |    2 +-
 .../admin_orders_{id}_capture/post.js         |    2 +-
 .../admin_orders_{id}_claims/post.js          |    2 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../admin_orders_{id}_complete/post.js        |    2 +-
 .../admin_orders_{id}_fulfillment/post.js     |    2 +-
 .../post.js                                   |    2 +-
 .../admin_orders_{id}_refund/post.js          |    4 +-
 .../admin_orders_{id}_return/post.js          |    2 +-
 .../post.js                                   |    2 +-
 .../admin_orders_{id}_swaps/post.js           |    2 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../admin_payment-collections_{id}/delete.js  |    2 +-
 .../admin_payment-collections_{id}/post.js    |    4 +-
 .../post.js                                   |    2 +-
 .../JavaScript/admin_payments_{id}/get.js     |    2 +-
 .../admin_payments_{id}_capture/post.js       |    2 +-
 .../admin_payments_{id}_refund/post.js        |    6 +-
 .../JavaScript/admin_price-lists/post.js      |    6 +-
 .../admin_price-lists_{id}/delete.js          |    2 +-
 .../JavaScript/admin_price-lists_{id}/get.js  |    2 +-
 .../JavaScript/admin_price-lists_{id}/post.js |    4 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    4 +-
 .../admin_price-lists_{id}_products/get.js    |    2 +-
 .../delete.js                                 |    2 +-
 .../delete.js                                 |    2 +-
 .../JavaScript/admin_products/post.js         |    2 +-
 .../JavaScript/admin_products_{id}/delete.js  |    2 +-
 .../JavaScript/admin_products_{id}/get.js     |    2 +-
 .../JavaScript/admin_products_{id}/post.js    |    5 +-
 .../admin_products_{id}_metadata/post.js      |    6 +-
 .../admin_products_{id}_options/post.js       |    4 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    4 +-
 .../admin_products_{id}_variants/post.js      |    8 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    6 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    2 +-
 .../JavaScript/admin_regions/post.js          |   10 +-
 .../JavaScript/admin_regions_{id}/delete.js   |    2 +-
 .../JavaScript/admin_regions_{id}/get.js      |    2 +-
 .../JavaScript/admin_regions_{id}/post.js     |    4 +-
 .../admin_regions_{id}_countries/post.js      |    4 +-
 .../delete.js                                 |    2 +-
 .../get.js                                    |    2 +-
 .../post.js                                   |    4 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    4 +-
 .../delete.js                                 |    2 +-
 .../JavaScript/admin_reservations/post.js     |    6 +-
 .../JavaScript/admin_return-reasons/post.js   |    4 +-
 .../admin_return-reasons_{id}/delete.js       |    2 +-
 .../admin_return-reasons_{id}/get.js          |    2 +-
 .../admin_return-reasons_{id}/post.js         |    4 +-
 .../admin_returns_{id}_cancel/post.js         |    2 +-
 .../admin_returns_{id}_receive/post.js        |    2 +-
 .../JavaScript/admin_sales-channels/post.js   |    4 +-
 .../admin_sales-channels_{id}/delete.js       |    2 +-
 .../admin_sales-channels_{id}/get.js          |    2 +-
 .../admin_sales-channels_{id}/post.js         |    4 +-
 .../delete.js                                 |    4 +-
 .../post.js                                   |    4 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    2 +-
 .../JavaScript/admin_shipping-options/post.js |    8 +-
 .../admin_shipping-options_{id}/delete.js     |    2 +-
 .../admin_shipping-options_{id}/get.js        |    2 +-
 .../admin_shipping-options_{id}/post.js       |    6 +-
 .../admin_shipping-profiles/post.js           |    2 +-
 .../admin_shipping-profiles_{id}/delete.js    |    2 +-
 .../admin_shipping-profiles_{id}/get.js       |    2 +-
 .../admin_shipping-profiles_{id}/post.js      |    2 +-
 .../JavaScript/admin_stock-locations/post.js  |    2 +-
 .../admin_stock-locations_{id}/delete.js      |    2 +-
 .../JavaScript/admin_store/post.js            |    2 +-
 .../admin_store_currencies_{code}/delete.js   |    2 +-
 .../admin_store_currencies_{code}/post.js     |    2 +-
 .../JavaScript/admin_swaps_{id}/get.js        |    2 +-
 .../JavaScript/admin_tax-rates/post.js        |    4 +-
 .../JavaScript/admin_tax-rates_{id}/delete.js |    2 +-
 .../JavaScript/admin_tax-rates_{id}/get.js    |    2 +-
 .../JavaScript/admin_tax-rates_{id}/post.js   |    4 +-
 .../delete.js                                 |    4 +-
 .../post.js                                   |    4 +-
 .../delete.js                                 |    4 +-
 .../post.js                                   |    4 +-
 .../delete.js                                 |    4 +-
 .../post.js                                   |    4 +-
 .../JavaScript/admin_users/post.js            |    4 +-
 .../admin_users_password-token/post.js        |    2 +-
 .../admin_users_reset-password/post.js        |    4 +-
 .../JavaScript/admin_users_{id}/delete.js     |    2 +-
 .../JavaScript/admin_users_{id}/get.js        |    2 +-
 .../JavaScript/admin_users_{id}/post.js       |    4 +-
 .../JavaScript/admin_variants_{id}/get.js     |    6 +-
 .../admin_variants_{id}_inventory/get.js      |    6 +-
 .../code_samples/Shell/admin_apps/get.sh      |    4 +-
 .../Shell/admin_apps_authorizations/post.sh   |    6 +-
 .../code_samples/Shell/admin_auth/delete.sh   |    4 +-
 .../code_samples/Shell/admin_auth/get.sh      |    4 +-
 .../code_samples/Shell/admin_auth/post.sh     |    4 +-
 .../Shell/admin_batch-jobs/get.sh             |    4 +-
 .../Shell/admin_batch-jobs/post.sh            |    6 +-
 .../Shell/admin_batch-jobs_{id}/get.sh        |    4 +-
 .../admin_batch-jobs_{id}_cancel/post.sh      |    4 +-
 .../admin_batch-jobs_{id}_confirm/post.sh     |    4 +-
 .../Shell/admin_collections/get.sh            |    4 +-
 .../Shell/admin_collections/post.sh           |    6 +-
 .../Shell/admin_collections_{id}/delete.sh    |    4 +-
 .../Shell/admin_collections_{id}/get.sh       |    4 +-
 .../Shell/admin_collections_{id}/post.sh      |    6 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../Shell/admin_currencies/get.sh             |    4 +-
 .../Shell/admin_currencies_{code}/post.sh     |    6 +-
 .../Shell/admin_customer-groups/get.sh        |    4 +-
 .../Shell/admin_customer-groups/post.sh       |    6 +-
 .../admin_customer-groups_{id}/delete.sh      |    4 +-
 .../Shell/admin_customer-groups_{id}/get.sh   |    4 +-
 .../Shell/admin_customer-groups_{id}/post.sh  |    6 +-
 .../get.sh                                    |    4 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../code_samples/Shell/admin_customers/get.sh |    4 +-
 .../Shell/admin_customers/post.sh             |    6 +-
 .../Shell/admin_customers_{id}/get.sh         |    4 +-
 .../Shell/admin_customers_{id}/post.sh        |    6 +-
 .../code_samples/Shell/admin_discounts/get.sh |    4 +-
 .../Shell/admin_discounts/post.sh             |    6 +-
 .../Shell/admin_discounts_code_{code}/get.sh  |    4 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    4 +-
 .../get.sh                                    |    4 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../Shell/admin_discounts_{id}/delete.sh      |    4 +-
 .../Shell/admin_discounts_{id}/get.sh         |    4 +-
 .../Shell/admin_discounts_{id}/post.sh        |    6 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    4 +-
 .../delete.sh                                 |    4 +-
 .../post.sh                                   |    4 +-
 .../Shell/admin_draft-orders/get.sh           |    4 +-
 .../Shell/admin_draft-orders/post.sh          |    6 +-
 .../Shell/admin_draft-orders_{id}/delete.sh   |    4 +-
 .../Shell/admin_draft-orders_{id}/get.sh      |    4 +-
 .../Shell/admin_draft-orders_{id}/post.sh     |    6 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    4 +-
 .../post.sh                                   |    6 +-
 .../Shell/admin_draft-orders_{id}_pay/post.sh |    4 +-
 .../Shell/admin_gift-cards/get.sh             |    4 +-
 .../Shell/admin_gift-cards/post.sh            |    6 +-
 .../Shell/admin_gift-cards_{id}/delete.sh     |    4 +-
 .../Shell/admin_gift-cards_{id}/get.sh        |    4 +-
 .../Shell/admin_gift-cards_{id}/post.sh       |    6 +-
 .../Shell/admin_inventory-items/get.sh        |    4 +-
 .../Shell/admin_inventory-items/post.sh       |    6 +-
 .../admin_inventory-items_{id}/delete.sh      |    4 +-
 .../Shell/admin_inventory-items_{id}/get.sh   |    4 +-
 .../Shell/admin_inventory-items_{id}/post.sh  |    6 +-
 .../get.sh                                    |    4 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    4 +-
 .../post.sh                                   |    6 +-
 .../code_samples/Shell/admin_invites/get.sh   |    4 +-
 .../code_samples/Shell/admin_invites/post.sh  |    6 +-
 .../Shell/admin_invites_accept/post.sh        |    6 +-
 .../Shell/admin_invites_{invite_id}/delete.sh |    4 +-
 .../admin_invites_{invite_id}_resend/post.sh  |    4 +-
 .../code_samples/Shell/admin_notes/get.sh     |    4 +-
 .../code_samples/Shell/admin_notes/post.sh    |    6 +-
 .../Shell/admin_notes_{id}/delete.sh          |    4 +-
 .../Shell/admin_notes_{id}/get.sh             |    4 +-
 .../Shell/admin_notes_{id}/post.sh            |    6 +-
 .../Shell/admin_notifications/get.sh          |    4 +-
 .../admin_notifications_{id}_resend/post.sh   |    4 +-
 .../Shell/admin_order-edits/get.sh            |    4 +-
 .../Shell/admin_order-edits/post.sh           |    6 +-
 .../Shell/admin_order-edits_{id}/delete.sh    |    4 +-
 .../Shell/admin_order-edits_{id}/get.sh       |    4 +-
 .../Shell/admin_order-edits_{id}/post.sh      |    6 +-
 .../admin_order-edits_{id}_cancel/post.sh     |    4 +-
 .../delete.sh                                 |    4 +-
 .../admin_order-edits_{id}_confirm/post.sh    |    4 +-
 .../admin_order-edits_{id}_items/post.sh      |    6 +-
 .../delete.sh                                 |    4 +-
 .../post.sh                                   |    6 +-
 .../admin_order-edits_{id}_request/post.sh    |    4 +-
 .../code_samples/Shell/admin_orders/get.sh    |    4 +-
 .../Shell/admin_orders_{id}/get.sh            |    4 +-
 .../Shell/admin_orders_{id}/post.sh           |    6 +-
 .../Shell/admin_orders_{id}_archive/post.sh   |    4 +-
 .../Shell/admin_orders_{id}_cancel/post.sh    |    4 +-
 .../Shell/admin_orders_{id}_capture/post.sh   |    4 +-
 .../Shell/admin_orders_{id}_claims/post.sh    |    6 +-
 .../post.sh                                   |    6 +-
 .../post.sh                                   |    4 +-
 .../post.sh                                   |    4 +-
 .../post.sh                                   |    4 +-
 .../post.sh                                   |    6 +-
 .../Shell/admin_orders_{id}_complete/post.sh  |    4 +-
 .../admin_orders_{id}_fulfillment/post.sh     |    6 +-
 .../post.sh                                   |    4 +-
 .../post.sh                                   |    6 +-
 .../Shell/admin_orders_{id}_refund/post.sh    |    6 +-
 .../admin_orders_{id}_reservations/get.sh     |    4 +-
 .../Shell/admin_orders_{id}_return/post.sh    |    6 +-
 .../Shell/admin_orders_{id}_shipment/post.sh  |    6 +-
 .../post.sh                                   |    6 +-
 .../Shell/admin_orders_{id}_swaps/post.sh     |    6 +-
 .../post.sh                                   |    4 +-
 .../post.sh                                   |    4 +-
 .../post.sh                                   |    4 +-
 .../post.sh                                   |    4 +-
 .../post.sh                                   |    6 +-
 .../admin_payment-collections_{id}/delete.sh  |    4 +-
 .../admin_payment-collections_{id}/get.sh     |    4 +-
 .../admin_payment-collections_{id}/post.sh    |    8 +-
 .../post.sh                                   |    4 +-
 .../Shell/admin_payments_{id}/get.sh          |    4 +-
 .../Shell/admin_payments_{id}_capture/post.sh |    4 +-
 .../Shell/admin_payments_{id}_refund/post.sh  |    6 +-
 .../Shell/admin_price-lists/get.sh            |    4 +-
 .../Shell/admin_price-lists/post.sh           |    6 +-
 .../Shell/admin_price-lists_{id}/delete.sh    |    4 +-
 .../Shell/admin_price-lists_{id}/get.sh       |    4 +-
 .../Shell/admin_price-lists_{id}/post.sh      |    6 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../admin_price-lists_{id}_products/get.sh    |    4 +-
 .../delete.sh                                 |    4 +-
 .../delete.sh                                 |    4 +-
 .../Shell/admin_product-categories/get.sh     |    4 +-
 .../Shell/admin_product-categories/post.sh    |    6 +-
 .../admin_product-categories_{id}/delete.sh   |    4 +-
 .../admin_product-categories_{id}/get.sh      |    4 +-
 .../admin_product-categories_{id}/post.sh     |    6 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    7 +-
 .../Shell/admin_product-tags/get.sh           |    4 +-
 .../Shell/admin_product-types/get.sh          |    4 +-
 .../code_samples/Shell/admin_products/get.sh  |    4 +-
 .../code_samples/Shell/admin_products/post.sh |    6 +-
 .../Shell/admin_products_tag-usage/get.sh     |    4 +-
 .../Shell/admin_products_types/get.sh         |    4 +-
 .../Shell/admin_products_{id}/delete.sh       |    4 +-
 .../Shell/admin_products_{id}/get.sh          |    4 +-
 .../Shell/admin_products_{id}/post.sh         |    6 +-
 .../admin_products_{id}_metadata/post.sh      |    6 +-
 .../Shell/admin_products_{id}_options/post.sh |    6 +-
 .../delete.sh                                 |    4 +-
 .../post.sh                                   |    6 +-
 .../Shell/admin_products_{id}_variants/get.sh |    4 +-
 .../admin_products_{id}_variants/post.sh      |    6 +-
 .../delete.sh                                 |    4 +-
 .../post.sh                                   |    6 +-
 .../admin_publishable-api-key_{id}/post.sh    |    6 +-
 .../Shell/admin_publishable-api-keys/get.sh   |    4 +-
 .../Shell/admin_publishable-api-keys/post.sh  |    6 +-
 .../admin_publishable-api-keys_{id}/delete.sh |    4 +-
 .../admin_publishable-api-keys_{id}/get.sh    |    4 +-
 .../post.sh                                   |    4 +-
 .../get.sh                                    |    4 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../code_samples/Shell/admin_regions/get.sh   |    4 +-
 .../code_samples/Shell/admin_regions/post.sh  |    6 +-
 .../Shell/admin_regions_{id}/delete.sh        |    4 +-
 .../Shell/admin_regions_{id}/get.sh           |    4 +-
 .../Shell/admin_regions_{id}/post.sh          |    6 +-
 .../admin_regions_{id}_countries/post.sh      |    6 +-
 .../delete.sh                                 |    4 +-
 .../get.sh                                    |    4 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    4 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    4 +-
 .../Shell/admin_reservations/get.sh           |    4 +-
 .../Shell/admin_reservations/post.sh          |    6 +-
 .../Shell/admin_reservations_{id}/delete.sh   |    4 +-
 .../Shell/admin_reservations_{id}/get.sh      |    4 +-
 .../Shell/admin_reservations_{id}/post.sh     |    6 +-
 .../Shell/admin_return-reasons/get.sh         |    4 +-
 .../Shell/admin_return-reasons/post.sh        |    6 +-
 .../Shell/admin_return-reasons_{id}/delete.sh |    4 +-
 .../Shell/admin_return-reasons_{id}/get.sh    |    4 +-
 .../Shell/admin_return-reasons_{id}/post.sh   |    6 +-
 .../code_samples/Shell/admin_returns/get.sh   |    4 +-
 .../Shell/admin_returns_{id}_cancel/post.sh   |    4 +-
 .../Shell/admin_returns_{id}_receive/post.sh  |    6 +-
 .../Shell/admin_sales-channels/get.sh         |    4 +-
 .../Shell/admin_sales-channels/post.sh        |    6 +-
 .../Shell/admin_sales-channels_{id}/delete.sh |    4 +-
 .../Shell/admin_sales-channels_{id}/get.sh    |    4 +-
 .../Shell/admin_sales-channels_{id}/post.sh   |    6 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../Shell/admin_shipping-options/get.sh       |    4 +-
 .../Shell/admin_shipping-options/post.sh      |    6 +-
 .../admin_shipping-options_{id}/delete.sh     |    4 +-
 .../Shell/admin_shipping-options_{id}/get.sh  |    4 +-
 .../Shell/admin_shipping-options_{id}/post.sh |    6 +-
 .../Shell/admin_shipping-profiles/get.sh      |    4 +-
 .../Shell/admin_shipping-profiles/post.sh     |    6 +-
 .../admin_shipping-profiles_{id}/delete.sh    |    4 +-
 .../Shell/admin_shipping-profiles_{id}/get.sh |    4 +-
 .../admin_shipping-profiles_{id}/post.sh      |    6 +-
 .../Shell/admin_stock-locations/get.sh        |    4 +-
 .../Shell/admin_stock-locations/post.sh       |    6 +-
 .../admin_stock-locations_{id}/delete.sh      |    4 +-
 .../Shell/admin_stock-locations_{id}/get.sh   |    4 +-
 .../Shell/admin_stock-locations_{id}/post.sh  |    6 +-
 .../code_samples/Shell/admin_store/get.sh     |    4 +-
 .../code_samples/Shell/admin_store/post.sh    |    6 +-
 .../admin_store_currencies_{code}/delete.sh   |    4 +-
 .../admin_store_currencies_{code}/post.sh     |    4 +-
 .../admin_store_payment-providers/get.sh      |    4 +-
 .../Shell/admin_store_tax-providers/get.sh    |    4 +-
 .../code_samples/Shell/admin_swaps/get.sh     |    4 +-
 .../Shell/admin_swaps_{id}/get.sh             |    4 +-
 .../code_samples/Shell/admin_tax-rates/get.sh |    4 +-
 .../Shell/admin_tax-rates/post.sh             |    6 +-
 .../Shell/admin_tax-rates_{id}/delete.sh      |    4 +-
 .../Shell/admin_tax-rates_{id}/get.sh         |    4 +-
 .../Shell/admin_tax-rates_{id}/post.sh        |    6 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../delete.sh                                 |    6 +-
 .../post.sh                                   |    6 +-
 .../Shell/admin_uploads/delete.sh             |    6 +-
 .../code_samples/Shell/admin_uploads/post.sh  |    6 +-
 .../Shell/admin_uploads_download-url/post.sh  |    6 +-
 .../Shell/admin_uploads_protected/post.sh     |    6 +-
 .../code_samples/Shell/admin_users/get.sh     |    4 +-
 .../code_samples/Shell/admin_users/post.sh    |    6 +-
 .../Shell/admin_users_password-token/post.sh  |    6 +-
 .../Shell/admin_users_reset-password/post.sh  |    6 +-
 .../Shell/admin_users_{id}/delete.sh          |    4 +-
 .../Shell/admin_users_{id}/get.sh             |    4 +-
 .../Shell/admin_users_{id}/post.sh            |    6 +-
 .../code_samples/Shell/admin_variants/get.sh  |    4 +-
 .../Shell/admin_variants_{id}/get.sh          |    4 +-
 .../admin_variants_{id}_inventory/get.sh      |    4 +-
 .../api/admin/components/schemas/Address.yaml |   12 +-
 .../components/schemas/AdminAppsListRes.yaml  |    1 +
 .../components/schemas/AdminAppsRes.yaml      |    1 +
 .../components/schemas/AdminAuthRes.yaml      |    1 +
 .../schemas/AdminBatchJobListRes.yaml         |    3 +-
 .../components/schemas/AdminBatchJobRes.yaml  |    1 +
 .../schemas/AdminCollectionsListRes.yaml      |    5 +-
 .../schemas/AdminCollectionsRes.yaml          |    1 +
 .../schemas/AdminCreateUserRequest.yaml       |   12 +-
 .../schemas/AdminCurrenciesListRes.yaml       |    3 +-
 .../schemas/AdminCurrenciesRes.yaml           |    1 +
 .../schemas/AdminCustomerGroupsListRes.yaml   |    3 +-
 .../schemas/AdminCustomerGroupsRes.yaml       |    1 +
 .../schemas/AdminCustomersListRes.yaml        |    3 +-
 .../components/schemas/AdminCustomersRes.yaml |    1 +
 ...tsDiscountConditionsConditionBatchReq.yaml |    2 +-
 .../AdminDeletePriceListPricesPricesReq.yaml  |    2 +-
 .../AdminDeleteProductsFromCollectionRes.yaml |    2 +-
 ...ublishableApiKeySalesChannelsBatchReq.yaml |    2 +-
 ...eSalesChannelsChannelProductsBatchReq.yaml |    2 +-
 ...nDeleteTaxRatesTaxRateProductTypesReq.yaml |    4 +-
 ...AdminDeleteTaxRatesTaxRateProductsReq.yaml |    2 +-
 ...leteTaxRatesTaxRateShippingOptionsReq.yaml |    4 +-
 .../AdminDiscountConditionsDeleteRes.yaml     |    6 +-
 .../schemas/AdminDiscountConditionsRes.yaml   |    1 +
 .../schemas/AdminDiscountsDeleteRes.yaml      |    2 +-
 .../schemas/AdminDiscountsListRes.yaml        |    2 +-
 .../components/schemas/AdminDiscountsRes.yaml |    1 +
 .../schemas/AdminDraftOrdersDeleteRes.yaml    |    2 +-
 .../schemas/AdminDraftOrdersListRes.yaml      |    3 +-
 .../schemas/AdminDraftOrdersRes.yaml          |    2 +
 .../schemas/AdminExtendedStoresRes.yaml       |    1 +
 ...GetRegionsRegionFulfillmentOptionsRes.yaml |    1 +
 .../AdminGetVariantsVariantInventoryRes.yaml  |    1 +
 .../schemas/AdminGiftCardsDeleteRes.yaml      |    2 +-
 .../schemas/AdminGiftCardsListRes.yaml        |    2 +-
 .../components/schemas/AdminGiftCardsRes.yaml |    1 +
 .../schemas/AdminInventoryItemsListRes.yaml   |    3 +-
 ...sListWithVariantsAndLocationLevelsRes.yaml |    3 +-
 .../schemas/AdminInventoryItemsRes.yaml       |    1 +
 .../schemas/AdminInviteDeleteRes.yaml         |    2 +-
 .../schemas/AdminListInvitesRes.yaml          |    1 +
 .../components/schemas/AdminNotesListRes.yaml |    3 +-
 .../components/schemas/AdminNotesRes.yaml     |    1 +
 .../schemas/AdminNotificationsListRes.yaml    |    3 +-
 .../schemas/AdminNotificationsRes.yaml        |    1 +
 .../schemas/AdminOrderEditsListRes.yaml       |    3 +-
 .../schemas/AdminOrderEditsRes.yaml           |    1 +
 .../schemas/AdminOrdersListRes.yaml           |    4 +-
 ...dminOrdersOrderLineItemReservationReq.yaml |    2 +-
 .../components/schemas/AdminOrdersRes.yaml    |    2 +
 .../schemas/AdminPaymentCollectionsRes.yaml   |    1 +
 .../schemas/AdminPaymentProvidersList.yaml    |    1 +
 .../components/schemas/AdminPaymentRes.yaml   |    1 +
 .../components/schemas/AdminPostAppsReq.yaml  |    2 +-
 .../components/schemas/AdminPostAuthReq.yaml  |    4 +-
 .../schemas/AdminPostBatchesReq.yaml          |    8 +-
 .../AdminPostCollectionsCollectionReq.yaml    |   10 +-
 .../schemas/AdminPostCollectionsReq.yaml      |   10 +-
 .../AdminPostCurrenciesCurrencyReq.yaml       |    3 +-
 .../AdminPostCustomerGroupsGroupReq.yaml      |    6 +-
 .../schemas/AdminPostCustomerGroupsReq.yaml   |    6 +-
 .../AdminPostCustomersCustomerReq.yaml        |    6 +-
 .../schemas/AdminPostCustomersReq.yaml        |    4 +
 .../AdminPostDiscountsDiscountConditions.yaml |   17 +-
 ...tDiscountsDiscountConditionsCondition.yaml |   12 +-
 ...nPostDiscountsDiscountDynamicCodesReq.yaml |    6 +-
 .../AdminPostDiscountsDiscountReq.yaml        |   61 +-
 .../schemas/AdminPostDiscountsReq.yaml        |   72 +-
 ...DraftOrdersDraftOrderLineItemsItemReq.yaml |   12 +-
 ...PostDraftOrdersDraftOrderLineItemsReq.yaml |   16 +-
 ...aftOrdersDraftOrderRegisterPaymentRes.yaml |    1 +
 .../AdminPostDraftOrdersDraftOrderReq.yaml    |   10 +-
 .../schemas/AdminPostDraftOrdersReq.yaml      |   44 +-
 .../AdminPostGiftCardsGiftCardReq.yaml        |   10 +-
 .../schemas/AdminPostGiftCardsReq.yaml        |   10 +-
 ...stInventoryItemsItemLocationLevelsReq.yaml |    6 +-
 .../schemas/AdminPostInventoryItemsReq.yaml   |   48 +-
 .../AdminPostInvitesInviteAcceptReq.yaml      |    8 +-
 .../schemas/AdminPostInvitesReq.yaml          |    8 +-
 .../schemas/AdminPostNotesNoteReq.yaml        |    2 +-
 .../components/schemas/AdminPostNotesReq.yaml |    6 +-
 ...ostNotificationsNotificationResendReq.yaml |    4 +-
 .../AdminPostOrderEditsEditLineItemsReq.yaml  |    8 +-
 .../AdminPostOrderEditsOrderEditReq.yaml      |    2 +-
 .../schemas/AdminPostOrderEditsReq.yaml       |    2 +-
 ...OrdersOrderClaimsClaimFulfillmentsReq.yaml |    8 +-
 .../AdminPostOrdersOrderClaimsClaimReq.yaml   |   10 +
 ...ostOrdersOrderClaimsClaimShipmentsReq.yaml |    2 +-
 .../AdminPostOrdersOrderClaimsReq.yaml        |   29 +-
 .../AdminPostOrdersOrderFulfillmentsReq.yaml  |   10 +-
 .../AdminPostOrdersOrderRefundsReq.yaml       |    8 +-
 .../schemas/AdminPostOrdersOrderReq.yaml      |   26 +-
 .../AdminPostOrdersOrderReturnsReq.yaml       |    6 +-
 ...dminPostOrdersOrderShippingMethodsReq.yaml |    2 +-
 .../schemas/AdminPostOrdersOrderSwapsReq.yaml |   22 +-
 ...stOrdersOrderSwapsSwapFulfillmentsReq.yaml |    8 +-
 .../AdminPostPriceListPricesPricesReq.yaml    |   10 +-
 ...inPostPriceListsPriceListPriceListReq.yaml |   17 +-
 .../AdminPostPriceListsPriceListReq.yaml      |   19 +-
 .../AdminPostProductCategoriesReq.yaml        |   15 +-
 .../AdminPostProductsProductOptionsReq.yaml   |    3 +-
 .../schemas/AdminPostProductsProductReq.yaml  |  134 +-
 .../AdminPostProductsProductVariantsReq.yaml  |   71 +-
 ...PostProductsProductVariantsVariantReq.yaml |   68 +-
 .../schemas/AdminPostProductsReq.yaml         |  114 +-
 ...ublishableApiKeySalesChannelsBatchReq.yaml |    2 +-
 ...ublishableApiKeysPublishableApiKeyReq.yaml |    2 +-
 .../AdminPostPublishableApiKeysReq.yaml       |    2 +-
 ...tRegionsRegionFulfillmentProvidersReq.yaml |    2 +-
 ...nPostRegionsRegionPaymentProvidersReq.yaml |    2 +-
 .../schemas/AdminPostRegionsRegionReq.yaml    |   31 +-
 .../schemas/AdminPostRegionsReq.yaml          |   15 +-
 .../schemas/AdminPostReservationsReq.yaml     |   12 +-
 .../AdminPostReservationsReservationReq.yaml  |    8 +-
 .../AdminPostReturnReasonsReasonReq.yaml      |    8 +-
 .../schemas/AdminPostReturnReasonsReq.yaml    |    8 +-
 .../schemas/AdminPostSalesChannelsReq.yaml    |    2 +-
 ...AdminPostSalesChannelsSalesChannelReq.yaml |    6 +-
 .../AdminPostShippingOptionsOptionReq.yaml    |   20 +-
 .../schemas/AdminPostShippingOptionsReq.yaml  |   22 +-
 .../AdminPostShippingProfilesProfileReq.yaml  |   10 +-
 .../AdminPostStockLocationsLocationReq.yaml   |    4 +
 .../schemas/AdminPostStockLocationsReq.yaml   |   11 +-
 .../AdminPostStockLocationsReqAddress.yaml    |   39 +
 .../components/schemas/AdminPostStoreReq.yaml |   22 +-
 .../schemas/AdminPostTaxRatesReq.yaml         |   10 +-
 .../schemas/AdminPostTaxRatesTaxRateReq.yaml  |   10 +-
 .../schemas/AdminPriceListDeleteBatchRes.yaml |    6 +-
 .../AdminPriceListDeleteProductPricesRes.yaml |    6 +-
 .../AdminPriceListDeleteVariantPricesRes.yaml |    6 +-
 .../components/schemas/AdminPriceListRes.yaml |    1 +
 .../schemas/AdminPriceListsListRes.yaml       |    3 +-
 .../AdminPriceListsProductsListRes.yaml       |    3 +-
 .../AdminProductCategoriesCategoryRes.yaml    |    1 +
 .../AdminProductCategoriesListRes.yaml        |    5 +-
 .../schemas/AdminProductTagsListRes.yaml      |    3 +-
 .../schemas/AdminProductTypesListRes.yaml     |    3 +-
 .../schemas/AdminProductsDeleteOptionRes.yaml |    1 +
 .../AdminProductsDeleteVariantRes.yaml        |    1 +
 .../schemas/AdminProductsListRes.yaml         |    3 +-
 .../schemas/AdminProductsListTagsRes.yaml     |    1 +
 .../schemas/AdminProductsListTypesRes.yaml    |    1 +
 .../schemas/AdminProductsListVariantsRes.yaml |    5 +-
 .../components/schemas/AdminProductsRes.yaml  |    1 +
 .../AdminPublishableApiKeyDeleteRes.yaml      |    4 +-
 .../AdminPublishableApiKeysListRes.yaml       |    5 +-
 ...ublishableApiKeysListSalesChannelsRes.yaml |    1 +
 .../schemas/AdminPublishableApiKeysRes.yaml   |    1 +
 .../components/schemas/AdminRefundRes.yaml    |    1 +
 .../schemas/AdminRegionsListRes.yaml          |    3 +-
 .../components/schemas/AdminRegionsRes.yaml   |    1 +
 .../schemas/AdminReservationsListRes.yaml     |    3 +-
 .../schemas/AdminReservationsRes.yaml         |    1 +
 .../schemas/AdminResetPasswordRequest.yaml    |    6 +-
 .../AdminResetPasswordTokenRequest.yaml       |    2 +-
 .../schemas/AdminReturnsCancelRes.yaml        |    1 +
 .../schemas/AdminReturnsListRes.yaml          |    3 +-
 .../components/schemas/AdminReturnsRes.yaml   |    1 +
 .../schemas/AdminSalesChannelsListRes.yaml    |    3 +-
 .../schemas/AdminSalesChannelsRes.yaml        |    1 +
 .../schemas/AdminShippingOptionsListRes.yaml  |    5 +-
 .../schemas/AdminShippingOptionsRes.yaml      |    1 +
 .../schemas/AdminShippingProfilesListRes.yaml |    1 +
 .../schemas/AdminShippingProfilesRes.yaml     |    1 +
 .../schemas/AdminStockLocationsListRes.yaml   |    2 +-
 .../schemas/AdminStockLocationsRes.yaml       |    1 +
 .../components/schemas/AdminStoresRes.yaml    |    1 +
 .../components/schemas/AdminSwapsListRes.yaml |    3 +-
 .../components/schemas/AdminSwapsRes.yaml     |    1 +
 .../schemas/AdminTaxProvidersList.yaml        |    1 +
 .../schemas/AdminTaxRatesListRes.yaml         |    3 +-
 .../components/schemas/AdminTaxRatesRes.yaml  |    1 +
 .../AdminUpdatePaymentCollectionsReq.yaml     |    8 +-
 .../schemas/AdminUpdateUserRequest.yaml       |   14 +-
 .../components/schemas/AdminUploadsRes.yaml   |    1 +
 .../components/schemas/AdminUserRes.yaml      |    1 +
 .../components/schemas/AdminUsersListRes.yaml |    1 +
 .../schemas/AdminVariantsListRes.yaml         |    5 +-
 .../components/schemas/AdminVariantsRes.yaml  |    1 +
 .../admin/components/schemas/BatchJob.yaml    |    7 +-
 docs/api/admin/components/schemas/Cart.yaml   |   46 +-
 .../admin/components/schemas/ClaimImage.yaml  |    9 +-
 .../admin/components/schemas/ClaimItem.yaml   |   29 +-
 .../admin/components/schemas/ClaimOrder.yaml  |   35 +-
 .../admin/components/schemas/ClaimTag.yaml    |    4 +
 .../api/admin/components/schemas/Country.yaml |    3 +-
 .../admin/components/schemas/Currency.yaml    |    3 +-
 .../schemas/CustomShippingOption.yaml         |   18 +-
 .../admin/components/schemas/Customer.yaml    |   20 +-
 .../components/schemas/CustomerGroup.yaml     |   18 +-
 .../schemas/DecoratedInventoryItemDTO.yaml    |    2 +
 .../admin/components/schemas/Discount.yaml    |   23 +-
 .../components/schemas/DiscountCondition.yaml |   44 +-
 .../DiscountConditionCustomerGroup.yaml       |    4 +
 .../schemas/DiscountConditionProduct.yaml     |   12 +-
 .../DiscountConditionProductCollection.yaml   |   14 +-
 .../schemas/DiscountConditionProductTag.yaml  |   12 +-
 .../schemas/DiscountConditionProductType.yaml |   14 +-
 .../components/schemas/DiscountRule.yaml      |   13 +-
 .../admin/components/schemas/DraftOrder.yaml  |   25 +-
 .../schemas/ExtendedReservationItem.yaml      |    4 +-
 .../admin/components/schemas/Fulfillment.yaml |   50 +-
 .../components/schemas/FulfillmentItem.yaml   |   14 +-
 .../schemas/FulfillmentProvider.yaml          |   13 +-
 .../admin/components/schemas/GiftCard.yaml    |   14 +-
 .../schemas/GiftCardTransaction.yaml          |   10 +-
 docs/api/admin/components/schemas/Image.yaml  |    8 +-
 docs/api/admin/components/schemas/Invite.yaml |   10 +-
 .../admin/components/schemas/LineItem.yaml    |   61 +-
 .../schemas/LineItemAdjustment.yaml           |   12 +-
 .../components/schemas/LineItemTaxLine.yaml   |    9 +-
 .../admin/components/schemas/MoneyAmount.yaml |   31 +-
 docs/api/admin/components/schemas/Note.yaml   |   10 +-
 .../components/schemas/Notification.yaml      |   28 +-
 .../schemas/NotificationProvider.yaml         |   13 +-
 docs/api/admin/components/schemas/OAuth.yaml  |    4 +-
 docs/api/admin/components/schemas/Order.yaml  |  106 +-
 .../admin/components/schemas/OrderEdit.yaml   |   22 +-
 .../components/schemas/OrderItemChange.yaml   |   18 +-
 .../api/admin/components/schemas/Payment.yaml |   34 +-
 .../components/schemas/PaymentCollection.yaml |   29 +-
 .../components/schemas/PaymentProvider.yaml   |   13 +-
 .../components/schemas/PaymentSession.yaml    |   16 +-
 .../admin/components/schemas/PriceList.yaml   |   15 +-
 .../api/admin/components/schemas/Product.yaml |   74 +-
 .../components/schemas/ProductCategory.yaml   |   20 +-
 .../components/schemas/ProductCollection.yaml |   14 +-
 .../components/schemas/ProductOption.yaml     |   20 +-
 .../schemas/ProductOptionValue.yaml           |   26 +-
 .../admin/components/schemas/ProductTag.yaml  |    6 +-
 .../components/schemas/ProductTaxRate.yaml    |   14 +-
 .../admin/components/schemas/ProductType.yaml |    6 +-
 .../schemas/ProductTypeTaxRate.yaml           |   14 +-
 .../components/schemas/ProductVariant.yaml    |   31 +-
 .../schemas/ProductVariantInventoryItem.yaml  |   11 +-
 .../components/schemas/PublishableApiKey.yaml |    9 +-
 .../PublishableApiKeySalesChannel.yaml        |    6 +-
 docs/api/admin/components/schemas/Refund.yaml |   18 +-
 docs/api/admin/components/schemas/Region.yaml |   39 +-
 .../schemas/ResponseInventoryItem.yaml        |   17 +-
 docs/api/admin/components/schemas/Return.yaml |   39 +-
 .../admin/components/schemas/ReturnItem.yaml  |   23 +-
 .../components/schemas/ReturnReason.yaml      |   14 +-
 .../components/schemas/SalesChannel.yaml      |   20 +-
 .../schemas/SalesChannelLocation.yaml         |   11 +-
 .../components/schemas/ShippingMethod.yaml    |   45 +-
 .../schemas/ShippingMethodTaxLine.yaml        |   11 +-
 .../components/schemas/ShippingOption.yaml    |   39 +-
 .../schemas/ShippingOptionRequirement.yaml    |   11 +-
 .../components/schemas/ShippingProfile.yaml   |   22 +-
 .../components/schemas/ShippingTaxRate.yaml   |   18 +-
 docs/api/admin/components/schemas/Store.yaml  |   24 +-
 docs/api/admin/components/schemas/Swap.yaml   |   62 +-
 .../api/admin/components/schemas/TaxLine.yaml |    6 +-
 .../admin/components/schemas/TaxProvider.yaml |   11 +-
 .../api/admin/components/schemas/TaxRate.yaml |   28 +-
 .../components/schemas/TrackingLink.yaml      |   14 +-
 docs/api/admin/components/schemas/User.yaml   |    8 +-
 .../components/schemas/VariantInventory.yaml  |   40 +-
 docs/api/admin/openapi.yaml                   |  344 +-
 docs/api/admin/paths/admin_apps.yaml          |    4 +-
 .../paths/admin_apps_authorizations.yaml      |    6 +-
 docs/api/admin/paths/admin_auth.yaml          |   27 +-
 docs/api/admin/paths/admin_batch-jobs.yaml    |   54 +-
 .../admin/paths/admin_batch-jobs_{id}.yaml    |    2 +-
 .../paths/admin_batch-jobs_{id}_cancel.yaml   |    4 +-
 .../paths/admin_batch-jobs_{id}_confirm.yaml  |    5 +-
 docs/api/admin/paths/admin_collections.yaml   |   27 +-
 .../admin/paths/admin_collections_{id}.yaml   |   14 +-
 ...admin_collections_{id}_products_batch.yaml |   28 +-
 docs/api/admin/paths/admin_currencies.yaml    |   15 +-
 .../admin/paths/admin_currencies_{code}.yaml  |    2 +-
 .../admin/paths/admin_customer-groups.yaml    |   31 +-
 .../paths/admin_customer-groups_{id}.yaml     |   18 +-
 .../admin_customer-groups_{id}_customers.yaml |   14 +-
 ..._customer-groups_{id}_customers_batch.yaml |   10 +-
 docs/api/admin/paths/admin_customers.yaml     |   25 +-
 .../api/admin/paths/admin_customers_{id}.yaml |   18 +-
 docs/api/admin/paths/admin_discounts.yaml     |   43 +-
 .../paths/admin_discounts_code_{code}.yaml    |    8 +-
 ...in_discounts_{discount_id}_conditions.yaml |   16 +-
 ...iscount_id}_conditions_{condition_id}.yaml |   42 +-
 ...t_id}_conditions_{condition_id}_batch.yaml |   37 +-
 .../api/admin/paths/admin_discounts_{id}.yaml |   22 +-
 .../admin_discounts_{id}_dynamic-codes.yaml   |    7 +-
 ...n_discounts_{id}_dynamic-codes_{code}.yaml |    4 +-
 ...in_discounts_{id}_regions_{region_id}.yaml |    9 +-
 docs/api/admin/paths/admin_draft-orders.yaml  |   16 +-
 .../admin/paths/admin_draft-orders_{id}.yaml  |    6 +-
 .../admin_draft-orders_{id}_line-items.yaml   |    2 +-
 ...raft-orders_{id}_line-items_{line_id}.yaml |    6 +-
 .../paths/admin_draft-orders_{id}_pay.yaml    |   11 +-
 docs/api/admin/paths/admin_gift-cards.yaml    |   12 +-
 .../admin/paths/admin_gift-cards_{id}.yaml    |    8 +-
 .../admin/paths/admin_inventory-items.yaml    |   63 +-
 .../paths/admin_inventory-items_{id}.yaml     |   24 +-
 ..._inventory-items_{id}_location-levels.yaml |   29 +-
 ...ms_{id}_location-levels_{location_id}.yaml |   14 +-
 docs/api/admin/paths/admin_invites.yaml       |    8 +-
 .../api/admin/paths/admin_invites_accept.yaml |    6 +-
 .../paths/admin_invites_{invite_id}.yaml      |    2 +-
 .../admin_invites_{invite_id}_resend.yaml     |    7 +-
 docs/api/admin/paths/admin_notes.yaml         |   14 +-
 docs/api/admin/paths/admin_notes_{id}.yaml    |   10 +-
 docs/api/admin/paths/admin_notifications.yaml |   32 +-
 .../admin_notifications_{id}_resend.yaml      |    4 +-
 docs/api/admin/paths/admin_order-edits.yaml   |   24 +-
 .../admin/paths/admin_order-edits_{id}.yaml   |   20 +-
 .../paths/admin_order-edits_{id}_cancel.yaml  |    4 +-
 ..._order-edits_{id}_changes_{change_id}.yaml |    8 +-
 .../paths/admin_order-edits_{id}_confirm.yaml |    6 +-
 .../paths/admin_order-edits_{id}_items.yaml   |    5 +-
 ...dmin_order-edits_{id}_items_{item_id}.yaml |   21 +-
 .../paths/admin_order-edits_{id}_request.yaml |    7 +-
 docs/api/admin/paths/admin_orders.yaml        |   48 +-
 docs/api/admin/paths/admin_orders_{id}.yaml   |   12 +-
 .../paths/admin_orders_{id}_archive.yaml      |    6 +-
 .../admin/paths/admin_orders_{id}_cancel.yaml |    8 +-
 .../paths/admin_orders_{id}_capture.yaml      |   10 +-
 .../admin/paths/admin_orders_{id}_claims.yaml |   12 +-
 .../admin_orders_{id}_claims_{claim_id}.yaml  |    8 +-
 ..._orders_{id}_claims_{claim_id}_cancel.yaml |   14 +-
 ...s_{id}_claims_{claim_id}_fulfillments.yaml |   13 +-
 ..._fulfillments_{fulfillment_id}_cancel.yaml |   14 +-
 ...ders_{id}_claims_{claim_id}_shipments.yaml |   16 +-
 .../paths/admin_orders_{id}_complete.yaml     |    8 +-
 .../paths/admin_orders_{id}_fulfillment.yaml  |   11 +-
 ..._fulfillments_{fulfillment_id}_cancel.yaml |   12 +-
 ...id}_line-items_{line_item_id}_reserve.yaml |    6 +-
 .../admin/paths/admin_orders_{id}_refund.yaml |    8 +-
 .../paths/admin_orders_{id}_reservations.yaml |    6 +-
 .../admin/paths/admin_orders_{id}_return.yaml |   11 +-
 .../paths/admin_orders_{id}_shipment.yaml     |   14 +-
 .../admin_orders_{id}_shipping-methods.yaml   |    4 +-
 .../admin/paths/admin_orders_{id}_swaps.yaml  |   15 +-
 ...in_orders_{id}_swaps_{swap_id}_cancel.yaml |   13 +-
 ...ers_{id}_swaps_{swap_id}_fulfillments.yaml |   13 +-
 ..._fulfillments_{fulfillment_id}_cancel.yaml |   12 +-
 ..._{id}_swaps_{swap_id}_process-payment.yaml |   20 +-
 ...orders_{id}_swaps_{swap_id}_shipments.yaml |   14 +-
 .../paths/admin_payment-collections_{id}.yaml |   28 +-
 ...in_payment-collections_{id}_authorize.yaml |    6 +-
 docs/api/admin/paths/admin_payments_{id}.yaml |    2 +-
 .../paths/admin_payments_{id}_capture.yaml    |    2 +-
 .../paths/admin_payments_{id}_refund.yaml     |    4 +-
 docs/api/admin/paths/admin_price-lists.yaml   |   43 +-
 .../admin/paths/admin_price-lists_{id}.yaml   |    8 +-
 .../admin_price-lists_{id}_prices_batch.yaml  |   12 +-
 .../admin_price-lists_{id}_products.yaml      |   48 +-
 ...sts_{id}_products_{product_id}_prices.yaml |   10 +-
 ...sts_{id}_variants_{variant_id}_prices.yaml |    8 +-
 .../admin/paths/admin_product-categories.yaml |   43 +-
 .../paths/admin_product-categories_{id}.yaml  |   15 +-
 ...roduct-categories_{id}_products_batch.yaml |   20 +-
 docs/api/admin/paths/admin_product-tags.yaml  |   24 +-
 docs/api/admin/paths/admin_product-types.yaml |   25 +-
 docs/api/admin/paths/admin_products.yaml      |   78 +-
 .../admin/paths/admin_products_tag-usage.yaml |    4 +-
 .../api/admin/paths/admin_products_types.yaml |    2 +-
 docs/api/admin/paths/admin_products_{id}.yaml |    6 +-
 .../paths/admin_products_{id}_metadata.yaml   |    9 +-
 .../paths/admin_products_{id}_options.yaml    |    2 +-
 ...min_products_{id}_options_{option_id}.yaml |    7 +-
 .../paths/admin_products_{id}_variants.yaml   |   24 +-
 ...n_products_{id}_variants_{variant_id}.yaml |    4 +-
 .../paths/admin_publishable-api-key_{id}.yaml |    6 +-
 .../paths/admin_publishable-api-keys.yaml     |   27 +-
 .../admin_publishable-api-keys_{id}.yaml      |   14 +-
 ...dmin_publishable-api-keys_{id}_revoke.yaml |    8 +-
 ...lishable-api-keys_{id}_sales-channels.yaml |   10 +-
 ...le-api-keys_{id}_sales-channels_batch.yaml |   13 +-
 docs/api/admin/paths/admin_regions.yaml       |   79 +-
 docs/api/admin/paths/admin_regions_{id}.yaml  |    8 +-
 .../paths/admin_regions_{id}_countries.yaml   |    2 +-
 ...regions_{id}_countries_{country_code}.yaml |    6 +-
 ...dmin_regions_{id}_fulfillment-options.yaml |    2 +-
 ...in_regions_{id}_fulfillment-providers.yaml |    2 +-
 ...}_fulfillment-providers_{provider_id}.yaml |    6 +-
 .../admin_regions_{id}_payment-providers.yaml |    2 +-
 ..._{id}_payment-providers_{provider_id}.yaml |    6 +-
 docs/api/admin/paths/admin_reservations.yaml  |   31 +-
 .../admin/paths/admin_reservations_{id}.yaml  |   12 +-
 .../api/admin/paths/admin_return-reasons.yaml |    4 +-
 .../paths/admin_return-reasons_{id}.yaml      |    6 +-
 docs/api/admin/paths/admin_returns.yaml       |    6 +-
 .../paths/admin_returns_{id}_cancel.yaml      |    4 +-
 .../paths/admin_returns_{id}_receive.yaml     |    4 +-
 .../api/admin/paths/admin_sales-channels.yaml |   33 +-
 .../paths/admin_sales-channels_{id}.yaml      |    8 +-
 ...in_sales-channels_{id}_products_batch.yaml |   11 +-
 ...n_sales-channels_{id}_stock-locations.yaml |    9 +-
 .../admin/paths/admin_shipping-options.yaml   |   12 +-
 .../paths/admin_shipping-options_{id}.yaml    |   10 +-
 .../admin/paths/admin_shipping-profiles.yaml  |    4 +-
 .../paths/admin_shipping-profiles_{id}.yaml   |    6 +-
 .../admin/paths/admin_stock-locations.yaml    |   39 +-
 .../paths/admin_stock-locations_{id}.yaml     |   38 +-
 docs/api/admin/paths/admin_store.yaml         |    4 +-
 .../paths/admin_store_currencies_{code}.yaml  |   13 +-
 .../paths/admin_store_payment-providers.yaml  |    2 +-
 .../paths/admin_store_tax-providers.yaml      |    2 +-
 docs/api/admin/paths/admin_swaps.yaml         |    6 +-
 docs/api/admin/paths/admin_swaps_{id}.yaml    |    2 +-
 docs/api/admin/paths/admin_tax-rates.yaml     |   26 +-
 .../api/admin/paths/admin_tax-rates_{id}.yaml |   20 +-
 ...in_tax-rates_{id}_product-types_batch.yaml |   19 +-
 .../admin_tax-rates_{id}_products_batch.yaml  |   20 +-
 ...tax-rates_{id}_shipping-options_batch.yaml |   21 +-
 docs/api/admin/paths/admin_uploads.yaml       |   10 +-
 .../paths/admin_uploads_download-url.yaml     |    4 +-
 .../admin/paths/admin_uploads_protected.yaml  |    4 +-
 docs/api/admin/paths/admin_users.yaml         |    7 +-
 .../paths/admin_users_password-token.yaml     |    7 +-
 .../paths/admin_users_reset-password.yaml     |   10 +-
 docs/api/admin/paths/admin_users_{id}.yaml    |    8 +-
 docs/api/admin/paths/admin_variants.yaml      |   77 +-
 docs/api/admin/paths/admin_variants_{id}.yaml |   14 +-
 .../paths/admin_variants_{id}_inventory.yaml  |    8 +-
 docs/api/store.oas.json                       | 2321 ++++---
 .../JavaScript/store_auth/post.js             |    4 +-
 .../JavaScript/store_auth_{email}/get.js      |    2 +-
 .../JavaScript/store_carts_{id}/get.js        |    2 +-
 .../JavaScript/store_carts_{id}/post.js       |    4 +-
 .../store_carts_{id}_complete/post.js         |    2 +-
 .../delete.js                                 |    2 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    2 +-
 .../store_carts_{id}_payment-session/post.js  |    4 +-
 .../store_carts_{id}_payment-sessions/post.js |    2 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../store_carts_{id}_shipping-methods/post.js |    2 +-
 .../JavaScript/store_collections_{id}/get.js  |    2 +-
 .../JavaScript/store_customers/post.js        |    8 +-
 .../JavaScript/store_customers_me/post.js     |    2 +-
 .../store_customers_me_addresses/post.js      |   20 +-
 .../delete.js                                 |    2 +-
 .../post.js                                   |    4 +-
 .../store_customers_password-reset/post.js    |    6 +-
 .../store_customers_password-token/post.js    |    2 +-
 .../JavaScript/store_order-edits_{id}/get.js  |    2 +-
 .../store_order-edits_{id}_complete/post.js   |    2 +-
 .../store_order-edits_{id}_decline/post.js    |    2 +-
 .../JavaScript/store_orders/get.js            |    2 +-
 .../store_orders_batch_customer_token/post.js |    4 +-
 .../store_orders_cart_{cart_id}/get.js        |    2 +-
 .../JavaScript/store_orders_{id}/get.js       |    2 +-
 .../post.js                                   |    4 -
 .../post.js                                   |   42 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../post.js                                   |    2 +-
 .../store_product-categories_{id}/get.js      |    2 +-
 .../JavaScript/store_products_search/post.js  |    2 +-
 .../JavaScript/store_products_{id}/get.js     |    2 +-
 .../JavaScript/store_regions_{id}/get.js      |    2 +-
 .../store_return-reasons_{id}/get.js          |    2 +-
 .../store_shipping-options_{cart_id}/get.js   |    2 +-
 .../JavaScript/store_swaps_{cart_id}/get.js   |    2 +-
 .../code_samples/Shell/store_auth/delete.sh   |    4 +-
 .../code_samples/Shell/store_auth/get.sh      |    4 +-
 .../code_samples/Shell/store_auth/post.sh     |    4 +-
 .../Shell/store_auth_{email}/get.sh           |    3 +-
 .../code_samples/Shell/store_carts/post.sh    |    2 +-
 .../Shell/store_carts_{id}/get.sh             |    2 +-
 .../Shell/store_carts_{id}/post.sh            |    4 +-
 .../Shell/store_carts_{id}_complete/post.sh   |    2 +-
 .../delete.sh                                 |    2 +-
 .../Shell/store_carts_{id}_line-items/post.sh |    4 +-
 .../delete.sh                                 |    2 +-
 .../post.sh                                   |    4 +-
 .../store_carts_{id}_payment-session/post.sh  |    4 +-
 .../store_carts_{id}_payment-sessions/post.sh |    2 +-
 .../delete.sh                                 |    2 +-
 .../post.sh                                   |    4 +-
 .../post.sh                                   |    2 +-
 .../store_carts_{id}_shipping-methods/post.sh |    4 +-
 .../Shell/store_carts_{id}_taxes/post.sh      |    2 +-
 .../Shell/store_collections/get.sh            |    2 +-
 .../Shell/store_collections_{id}/get.sh       |    2 +-
 .../Shell/store_customers/post.sh             |    4 +-
 .../Shell/store_customers_me/get.sh           |    4 +-
 .../Shell/store_customers_me/post.sh          |    6 +-
 .../store_customers_me_addresses/post.sh      |    6 +-
 .../delete.sh                                 |    4 +-
 .../post.sh                                   |    6 +-
 .../Shell/store_customers_me_orders/get.sh    |    4 +-
 .../store_customers_me_payment-methods/get.sh |    4 +-
 .../store_customers_password-reset/post.sh    |    4 +-
 .../store_customers_password-token/post.sh    |    4 +-
 .../Shell/store_gift-cards_{code}/get.sh      |    2 +-
 .../Shell/store_order-edits_{id}/get.sh       |    2 +-
 .../store_order-edits_{id}_complete/post.sh   |    2 +-
 .../store_order-edits_{id}_decline/post.sh    |    2 +-
 .../code_samples/Shell/store_orders/get.sh    |    2 +-
 .../store_orders_batch_customer_token/post.sh |    6 +-
 .../Shell/store_orders_cart_{cart_id}/get.sh  |    2 +-
 .../store_orders_customer_confirm/post.sh     |    4 +-
 .../Shell/store_orders_{id}/get.sh            |    2 +-
 .../store_payment-collections_{id}/get.sh     |    2 +-
 .../post.sh                                   |    6 +-
 .../post.sh                                   |   15 +-
 .../post.sh                                   |    2 +-
 .../post.sh                                   |    2 +-
 .../post.sh                                   |    2 +-
 .../Shell/store_product-categories/get.sh     |    4 +-
 .../store_product-categories_{id}/get.sh      |    4 +-
 .../Shell/store_product-tags/get.sh           |    2 +-
 .../Shell/store_product-types/get.sh          |    3 +-
 .../code_samples/Shell/store_products/get.sh  |    2 +-
 .../Shell/store_products_search/post.sh       |    4 +-
 .../Shell/store_products_{id}/get.sh          |    2 +-
 .../code_samples/Shell/store_regions/get.sh   |    2 +-
 .../Shell/store_regions_{id}/get.sh           |    2 +-
 .../Shell/store_return-reasons/get.sh         |    2 +-
 .../Shell/store_return-reasons_{id}/get.sh    |    2 +-
 .../code_samples/Shell/store_returns/post.sh  |    4 +-
 .../Shell/store_shipping-options/get.sh       |    2 +-
 .../store_shipping-options_{cart_id}/get.sh   |    2 +-
 .../code_samples/Shell/store_swaps/post.sh    |   10 +-
 .../Shell/store_swaps_{cart_id}/get.sh        |    2 +-
 .../code_samples/Shell/store_variants/get.sh  |    2 +-
 .../Shell/store_variants_{id}/get.sh          |    1 +
 .../Shell/store_variants_{variant_id}/get.sh  |    1 -
 .../api/store/components/schemas/Address.yaml |   12 +-
 .../store/components/schemas/BatchJob.yaml    |    7 +-
 docs/api/store/components/schemas/Cart.yaml   |   46 +-
 .../store/components/schemas/ClaimImage.yaml  |    9 +-
 .../store/components/schemas/ClaimItem.yaml   |   29 +-
 .../store/components/schemas/ClaimOrder.yaml  |   35 +-
 .../store/components/schemas/ClaimTag.yaml    |    4 +
 .../api/store/components/schemas/Country.yaml |    3 +-
 .../store/components/schemas/Currency.yaml    |    3 +-
 .../schemas/CustomShippingOption.yaml         |   18 +-
 .../store/components/schemas/Customer.yaml    |   20 +-
 .../components/schemas/CustomerGroup.yaml     |   18 +-
 .../store/components/schemas/Discount.yaml    |   23 +-
 .../components/schemas/DiscountCondition.yaml |   44 +-
 .../DiscountConditionCustomerGroup.yaml       |    4 +
 .../schemas/DiscountConditionProduct.yaml     |   12 +-
 .../DiscountConditionProductCollection.yaml   |   14 +-
 .../schemas/DiscountConditionProductTag.yaml  |   12 +-
 .../schemas/DiscountConditionProductType.yaml |   14 +-
 .../components/schemas/DiscountRule.yaml      |   13 +-
 .../store/components/schemas/DraftOrder.yaml  |   25 +-
 .../store/components/schemas/Fulfillment.yaml |   50 +-
 .../components/schemas/FulfillmentItem.yaml   |   14 +-
 .../schemas/FulfillmentProvider.yaml          |   13 +-
 .../store/components/schemas/GiftCard.yaml    |   14 +-
 .../schemas/GiftCardTransaction.yaml          |   10 +-
 docs/api/store/components/schemas/Image.yaml  |    8 +-
 docs/api/store/components/schemas/Invite.yaml |   10 +-
 .../store/components/schemas/LineItem.yaml    |   61 +-
 .../schemas/LineItemAdjustment.yaml           |   12 +-
 .../components/schemas/LineItemTaxLine.yaml   |    9 +-
 .../store/components/schemas/MoneyAmount.yaml |   31 +-
 docs/api/store/components/schemas/Note.yaml   |   10 +-
 .../components/schemas/Notification.yaml      |   28 +-
 .../schemas/NotificationProvider.yaml         |   13 +-
 docs/api/store/components/schemas/OAuth.yaml  |    4 +-
 docs/api/store/components/schemas/Order.yaml  |  106 +-
 .../store/components/schemas/OrderEdit.yaml   |   22 +-
 .../components/schemas/OrderItemChange.yaml   |   18 +-
 .../api/store/components/schemas/Payment.yaml |   34 +-
 .../components/schemas/PaymentCollection.yaml |   29 +-
 .../components/schemas/PaymentProvider.yaml   |   13 +-
 .../components/schemas/PaymentSession.yaml    |   16 +-
 .../store/components/schemas/PriceList.yaml   |   15 +-
 .../api/store/components/schemas/Product.yaml |   74 +-
 .../components/schemas/ProductCategory.yaml   |   20 +-
 .../components/schemas/ProductCollection.yaml |   14 +-
 .../components/schemas/ProductOption.yaml     |   20 +-
 .../schemas/ProductOptionValue.yaml           |   26 +-
 .../store/components/schemas/ProductTag.yaml  |    6 +-
 .../components/schemas/ProductTaxRate.yaml    |   14 +-
 .../store/components/schemas/ProductType.yaml |    6 +-
 .../schemas/ProductTypeTaxRate.yaml           |   14 +-
 .../components/schemas/ProductVariant.yaml    |   31 +-
 .../schemas/ProductVariantInventoryItem.yaml  |   11 +-
 .../components/schemas/PublishableApiKey.yaml |    9 +-
 .../PublishableApiKeySalesChannel.yaml        |    6 +-
 docs/api/store/components/schemas/Refund.yaml |   18 +-
 docs/api/store/components/schemas/Region.yaml |   39 +-
 docs/api/store/components/schemas/Return.yaml |   39 +-
 .../store/components/schemas/ReturnItem.yaml  |   23 +-
 .../components/schemas/ReturnReason.yaml      |   14 +-
 .../components/schemas/SalesChannel.yaml      |   20 +-
 .../schemas/SalesChannelLocation.yaml         |   11 +-
 .../components/schemas/ShippingMethod.yaml    |   45 +-
 .../schemas/ShippingMethodTaxLine.yaml        |   11 +-
 .../components/schemas/ShippingOption.yaml    |   39 +-
 .../schemas/ShippingOptionRequirement.yaml    |   11 +-
 .../components/schemas/ShippingProfile.yaml   |   22 +-
 .../components/schemas/ShippingTaxRate.yaml   |   18 +-
 docs/api/store/components/schemas/Store.yaml  |   24 +-
 .../components/schemas/StoreAuthRes.yaml      |    1 +
 .../StoreCartShippingOptionsListRes.yaml      |    1 +
 .../components/schemas/StoreCartsRes.yaml     |    2 +
 .../schemas/StoreCollectionsListRes.yaml      |    5 +-
 .../schemas/StoreCollectionsRes.yaml          |    1 +
 .../schemas/StoreCompleteCartRes.yaml         |   12 +-
 .../schemas/StoreCustomersListOrdersRes.yaml  |    4 +-
 .../StoreCustomersListPaymentMethodsRes.yaml  |    3 +-
 .../components/schemas/StoreCustomersRes.yaml |    1 +
 .../StoreCustomersResetPasswordRes.yaml       |    1 +
 .../StoreGetProductCategoriesCategoryRes.yaml |    1 +
 .../schemas/StoreGetProductCategoriesRes.yaml |    5 +-
 .../components/schemas/StoreGiftCardsRes.yaml |    1 +
 .../schemas/StoreOrderEditsRes.yaml           |    1 +
 .../components/schemas/StoreOrdersRes.yaml    |    2 +
 .../schemas/StorePaymentCollectionsRes.yaml   |    1 +
 .../StorePaymentCollectionsSessionRes.yaml    |    1 +
 .../components/schemas/StorePostCartReq.yaml  |   34 +-
 .../StorePostCartsCartLineItemsItemReq.yaml   |    6 +-
 .../StorePostCartsCartLineItemsReq.yaml       |    4 +
 .../schemas/StorePostCartsCartReq.yaml        |   26 +-
 .../StorePostCartsCartShippingMethodReq.yaml  |    6 +-
 ...rePostCustomersCustomerAcceptClaimReq.yaml |    2 +-
 ...torePostCustomersCustomerAddressesReq.yaml |    2 +-
 ...orePostCustomersCustomerOrderClaimReq.yaml |    2 +-
 ...PostCustomersCustomerPasswordTokenReq.yaml |    2 +-
 .../StorePostCustomersCustomerReq.yaml        |   18 +-
 .../schemas/StorePostCustomersReq.yaml        |   10 +-
 .../StorePostCustomersResetPasswordReq.yaml   |    4 +-
 .../StorePostOrderEditsOrderEditDecline.yaml  |    2 +-
 ...ostPaymentCollectionsBatchSessionsReq.yaml |   11 +-
 .../schemas/StorePostReturnsReq.yaml          |   15 +-
 .../schemas/StorePostSearchReq.yaml           |    6 +-
 .../schemas/StorePostSearchRes.yaml           |    4 +-
 .../components/schemas/StorePostSwapsReq.yaml |   14 +-
 .../schemas/StoreProductTagsListRes.yaml      |    3 +-
 .../schemas/StoreProductTypesListRes.yaml     |    3 +-
 .../schemas/StoreProductsListRes.yaml         |    3 +-
 .../components/schemas/StoreProductsRes.yaml  |    1 +
 .../schemas/StoreRegionsListRes.yaml          |    3 +-
 .../components/schemas/StoreRegionsRes.yaml   |    1 +
 .../schemas/StoreReturnReasonsListRes.yaml    |    1 +
 .../schemas/StoreReturnReasonsRes.yaml        |    1 +
 .../components/schemas/StoreReturnsRes.yaml   |    1 +
 .../schemas/StoreShippingOptionsListRes.yaml  |    1 +
 .../components/schemas/StoreSwapsRes.yaml     |    1 +
 .../schemas/StoreVariantsListRes.yaml         |    1 +
 .../components/schemas/StoreVariantsRes.yaml  |    1 +
 docs/api/store/components/schemas/Swap.yaml   |   62 +-
 .../api/store/components/schemas/TaxLine.yaml |    6 +-
 .../store/components/schemas/TaxProvider.yaml |   11 +-
 .../api/store/components/schemas/TaxRate.yaml |   28 +-
 .../components/schemas/TrackingLink.yaml      |   14 +-
 docs/api/store/components/schemas/User.yaml   |    8 +-
 docs/api/store/openapi.yaml                   |  153 +-
 docs/api/store/paths/store_auth.yaml          |   10 +-
 docs/api/store/paths/store_auth_{email}.yaml  |    6 +-
 docs/api/store/paths/store_carts.yaml         |   18 +-
 docs/api/store/paths/store_carts_{id}.yaml    |   11 +-
 .../paths/store_carts_{id}_complete.yaml      |   38 +-
 .../store_carts_{id}_discounts_{code}.yaml    |    9 +-
 ...store_carts_{id}_line-items_{line_id}.yaml |   14 +-
 .../store_carts_{id}_payment-session.yaml     |    5 +-
 .../store_carts_{id}_payment-sessions.yaml    |    8 +-
 ...s_{id}_payment-sessions_{provider_id}.yaml |   17 +-
 ...ayment-sessions_{provider_id}_refresh.yaml |    8 +-
 .../store_carts_{id}_shipping-methods.yaml    |    6 +-
 .../store/paths/store_carts_{id}_taxes.yaml   |   11 +-
 docs/api/store/paths/store_collections.yaml   |   19 +-
 .../store/paths/store_collections_{id}.yaml   |    4 +-
 docs/api/store/paths/store_customers.yaml     |    7 +-
 docs/api/store/paths/store_customers_me.yaml  |    6 +-
 .../paths/store_customers_me_addresses.yaml   |    2 +-
 ...e_customers_me_addresses_{address_id}.yaml |    6 +-
 .../paths/store_customers_me_orders.yaml      |   72 +-
 .../store_customers_me_payment-methods.yaml   |   11 +-
 .../paths/store_customers_password-reset.yaml |    9 +-
 .../paths/store_customers_password-token.yaml |   12 +-
 .../store/paths/store_gift-cards_{code}.yaml  |    2 +-
 .../store/paths/store_order-edits_{id}.yaml   |    4 +-
 .../store_order-edits_{id}_complete.yaml      |   10 +-
 .../paths/store_order-edits_{id}_decline.yaml |    4 +-
 docs/api/store/paths/store_orders.yaml        |   14 +-
 .../store_orders_batch_customer_token.yaml    |   15 +-
 .../paths/store_orders_cart_{cart_id}.yaml    |    4 +-
 .../paths/store_orders_customer_confirm.yaml  |    9 +-
 docs/api/store/paths/store_orders_{id}.yaml   |    8 +-
 .../paths/store_payment-collections_{id}.yaml |   14 +-
 ...ore_payment-collections_{id}_sessions.yaml |    4 +-
 ...yment-collections_{id}_sessions_batch.yaml |    5 +-
 ...ections_{id}_sessions_batch_authorize.yaml |    2 +-
 ...ollections_{id}_sessions_{session_id}.yaml |    4 +-
 ..._{id}_sessions_{session_id}_authorize.yaml |    2 +-
 .../store/paths/store_product-categories.yaml |   40 +-
 .../paths/store_product-categories_{id}.yaml  |   14 +-
 docs/api/store/paths/store_product-tags.yaml  |   24 +-
 docs/api/store/paths/store_product-types.yaml |   25 +-
 docs/api/store/paths/store_products.yaml      |  100 +-
 .../store/paths/store_products_search.yaml    |    5 +-
 docs/api/store/paths/store_products_{id}.yaml |   48 +-
 docs/api/store/paths/store_regions.yaml       |   15 +-
 docs/api/store/paths/store_regions_{id}.yaml  |    4 +-
 .../api/store/paths/store_return-reasons.yaml |    4 +-
 .../paths/store_return-reasons_{id}.yaml      |    2 +-
 docs/api/store/paths/store_returns.yaml       |    7 +-
 .../store/paths/store_shipping-options.yaml   |   15 +-
 .../store_shipping-options_{cart_id}.yaml     |    8 +-
 docs/api/store/paths/store_swaps.yaml         |   23 +-
 .../store/paths/store_swaps_{cart_id}.yaml    |    2 +-
 docs/api/store/paths/store_variants.yaml      |   99 +-
 docs/api/store/paths/store_variants_{id}.yaml |   87 +
 .../paths/store_variants_{variant_id}.yaml    |   63 -
 1138 files changed, 11740 insertions(+), 7043 deletions(-)
 create mode 100644 docs/api/admin/code_samples/JavaScript/admin_collections_{id}_products_batch/delete.js
 create mode 100644 docs/api/admin/code_samples/JavaScript/admin_collections_{id}_products_batch/post.js
 create mode 100644 docs/api/admin/components/schemas/AdminPostStockLocationsReqAddress.yaml
 create mode 100644 docs/api/store/code_samples/Shell/store_variants_{id}/get.sh
 delete mode 100644 docs/api/store/code_samples/Shell/store_variants_{variant_id}/get.sh
 create mode 100644 docs/api/store/paths/store_variants_{id}.yaml
 delete mode 100644 docs/api/store/paths/store_variants_{variant_id}.yaml

diff --git a/docs/api/admin.oas.json b/docs/api/admin.oas.json
index d025a0139f..3b0bbbea65 100644
--- a/docs/api/admin.oas.json
+++ b/docs/api/admin.oas.json
@@ -11,120 +11,268 @@
   },
   "tags": [
     {
-      "name": "Auth",
-      "description": "Auth endpoints that allow authorization of admin Users and manages their sessions."
+      "name": "Apps Oauth",
+      "description": "Some plugins may require to authenticate with third-party services and store authentication details, such as the authentication token. To do that, they can create an Oauth provider within the plugin that handles the authentication.\nThe Apps Oauth endpoints allows admins to manage and generate token for an app using its oauth provider.\n"
     },
     {
-      "name": "Apps",
-      "description": "App endpoints that allow handling apps in Medusa."
+      "name": "Auth",
+      "description": "Authentication endpoints allow admin users to manage their session, such as login or log out.\nWhen an admin user is logged in, the cookie header is set indicating the admin's login session.\n",
+      "externalDocs": {
+        "description": "How to implement user profiles",
+        "url": "https://docs.medusajs.com/modules/users/admin/manage-profile"
+      }
     },
     {
       "name": "Batch Jobs",
-      "description": "Batch Job endpoints that allow handling batch jobs in Medusa."
+      "description": "A batch job is a task that is performed by the Medusa backend asynchronusly. For example, the Import Product feature is implemented using batch jobs.\nBatch Job endpoints allows admins to manage the batch jobs and their state.\n",
+      "externalDocs": {
+        "description": "How to import products",
+        "url": "https://docs.medusajs.com/modules/products/admin/import-products"
+      }
     },
     {
-      "name": "Collections",
-      "description": "Collection endpoints that allow handling collections in Medusa."
+      "name": "Currencies",
+      "description": "A store can use unlimited currencies, and each region must be associated with at least one currency.\nCurrencies are defined within the Medusa backend. Currency endpoints allow admins to list and update currencies.\n",
+      "externalDocs": {
+        "description": "How to manage currencies",
+        "url": "https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-currencies"
+      }
     },
     {
       "name": "Customers",
-      "description": "Customer endpoints that allow handling customers in Medusa."
+      "description": "Customers can either be created when they register through the Store APIs, or created by the admin using the Admin APIs.\n",
+      "externalDocs": {
+        "description": "How to manage customers",
+        "url": "https://docs.medusajs.com/modules/customers/admin/manage-customers"
+      }
     },
     {
       "name": "Customer Groups",
-      "description": "Customer Group endpoints that allow handling customer groups in Medusa."
+      "description": "Customer Groups can be used to organize customers that share similar data or attributes into dedicated groups.\nThis can be useful for different purposes such as setting a different price for a specific customer group.\n",
+      "externalDocs": {
+        "description": "How to manage customer groups",
+        "url": "https://docs.medusajs.com/modules/customers/admin/manage-customer-groups"
+      }
     },
     {
       "name": "Discounts",
-      "description": "Discount endpoints that allow handling discounts in Medusa."
+      "description": "Admins can create discounts with conditions and rules, providing them with advanced settings for variety of cases.\nThe Discount endpoints can be used to manage discounts, their conditions, resources, and more.\n",
+      "externalDocs": {
+        "description": "How to manage discounts",
+        "url": "https://docs.medusajs.com/modules/discounts/admin/manage-discounts"
+      }
     },
     {
       "name": "Draft Orders",
-      "description": "Draft Order endpoints that allow handling draft orders in Medusa."
+      "description": "A draft order is an order created manually by the admin. It allows admins to create orders without direct involvement from the customer.\n",
+      "externalDocs": {
+        "description": "How to manage draft orders",
+        "url": "https://docs.medusajs.com/modules/orders/admin/manage-draft-orders"
+      }
     },
     {
       "name": "Gift Cards",
-      "description": "Gift Card endpoints that allow handling gift cards in Medusa."
+      "description": "Admins can create gift cards and send them directly to customers, specifying options like their balance, region, and more.\nThese gift cards are different than the saleable gift cards in a store, which are created and managed through Product endpoints.\n",
+      "externalDocs": {
+        "description": "How to manage gift cards",
+        "url": "https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-custom-gift-cards"
+      }
+    },
+    {
+      "name": "Inventory Items",
+      "description": "Inventory items, provided by the [Inventory Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module), can be used to manage the inventory of saleable items in your store.\n",
+      "externalDocs": {
+        "description": "How to manage inventory items",
+        "url": "https://docs.medusajs.com/modules/multiwarehouse/admin/manage-inventory-items"
+      }
     },
     {
       "name": "Invites",
-      "description": "Invite endpoints that allow handling invites in Medusa."
+      "description": "An admin can invite new users to manage their team. This would allow new users to authenticate as admins and perform admin functionalities.\n",
+      "externalDocs": {
+        "description": "How to manage invites",
+        "url": "https://docs.medusajs.com/modules/users/admin/manage-invites"
+      }
     },
     {
       "name": "Notes",
-      "description": "Note endpoints that allow handling notes in Medusa."
+      "description": "Notes are created by admins and can be associated with any resource. For example, an admin can add a note to an order for additional details or remarks.\n"
     },
     {
       "name": "Notifications",
-      "description": "Notification endpoints that allow handling notifications in Medusa."
+      "description": "Notifications are sent to customers to inform them of new updates. For example, a notification can be sent to the customer when their order is place or its state is updated.\nThe notification's type, such as an email or SMS, is determined by the notification provider installed on the Medusa backend.\n"
     },
     {
       "name": "Orders",
-      "description": "Order endpoints that allow handling orders in Medusa."
+      "description": "Orders are purchases made by customers, typically through a storefront using the Store API. Draft orders created by the admin are also transformed to an Order once the payment is captured.\nManaging orders include managing fulfillment, payment, claims, reservations, and more.\n",
+      "externalDocs": {
+        "description": "How to manage orders",
+        "url": "https://docs.medusajs.com/modules/orders/admin/manage-orders"
+      }
+    },
+    {
+      "name": "Order Edits",
+      "description": "An admin can edit an order to remove, add, or update an item's quantity. When an admin edits an order, they're stored as an `OrderEdit`.\n",
+      "externalDocs": {
+        "description": "How to edit an order",
+        "url": "https://docs.medusajs.com/modules/orders/admin/edit-order"
+      }
+    },
+    {
+      "name": "Payment Collections",
+      "description": "A payment collection is useful for managing additional payments, such as for Order Edits, or installment payments.\n"
     },
     {
       "name": "Price Lists",
-      "description": "Price List endpoints that allow handling price lists in Medusa."
+      "description": "A price list are special prices applied to products based on a set of conditions, such as customer group.\n",
+      "externalDocs": {
+        "description": "How to manage price lists",
+        "url": "https://docs.medusajs.com/modules/price-lists/admin/manage-price-lists"
+      }
     },
     {
       "name": "Products",
-      "description": "Product endpoints that allow handling products in Medusa."
+      "description": "Products are saleable items in a store. This also includes [saleable gift cards](https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-gift-card-product) in a store.\n",
+      "externalDocs": {
+        "description": "How to manage products",
+        "url": "https://docs.medusajs.com/modules/products/admin/manage-products"
+      }
+    },
+    {
+      "name": "Product Categories",
+      "description": "Products can be categoriezed into categories. A product can be added into more than one category.\n",
+      "externalDocs": {
+        "description": "How to manage product categories",
+        "url": "https://docs.medusajs.com/modules/products/admin/manage-categories"
+      }
+    },
+    {
+      "name": "Product Collections",
+      "description": "A product collection is used to organize products for different purposes such as marketing or discount purposes. For example, you can create a Summer Collection.\n"
     },
     {
       "name": "Product Tags",
-      "description": "Product Tag endpoints that allow handling product tags in Medusa."
+      "description": "Product tags are string values created when you create or update a product with a new tag.\nProducts can have more than one tag, and products can share tags. This allows admins to associate products to similar tags that can be used to filter products.\n"
     },
     {
       "name": "Product Types",
-      "description": "Product Types endpoints that allow handling product types in Medusa."
+      "description": "Product types are string values created when you create or update a product with a new type.\nProducts can have one type, and products can share types. This allows admins to associate products with a type that can be used to filter products.\n"
+    },
+    {
+      "name": "Product Variants",
+      "description": "Product variants are the actual salable item in your store. Each variant is a combination of the different option values available on the product.\nProduct variants can be managed through the Products endpoints.\n",
+      "externalDocs": {
+        "description": "How to manage product variants",
+        "url": "https://docs.medusajs.com/modules/products/admin/manage-products#manage-product-variants"
+      }
+    },
+    {
+      "name": "Publishable API Keys",
+      "description": "Publishable API Keys can be used to scope Store API calls with an API key, determining what resources are retrieved when querying the API.\nFor example, a publishable API key can be associated with one or more sales channels. When it is passed in the header of a request to the List Product store endpoint,\nthe sales channels are inferred from the key and only products associated with those sales channels are retrieved.\nAdmins can manage publishable API keys and their associated resources. Currently, only Sales Channels are supported as a resource.\n",
+      "externalDocs": {
+        "description": "How to manage publishable API keys",
+        "url": "https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys"
+      }
+    },
+    {
+      "name": "Reservations",
+      "description": "Reservations, provided by the [Inventory Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module), are quantities of an item that are reserved, typically when an order is placed but not yet fulfilled.\nReservations can be associated with any resources, but commonly with line items of an order.\n",
+      "externalDocs": {
+        "description": "How to manage item allocations in orders",
+        "url": "https://docs.medusajs.com/modules/multiwarehouse/admin/manage-item-allocations-in-orders"
+      }
     },
     {
       "name": "Regions",
-      "description": "Region endpoints that allow handling regions in Medusa."
+      "description": "Regions are different countries or geographical regions that the commerce store serves customers in.\nAdmins can manage these regions, their providers, and more.\n",
+      "externalDocs": {
+        "description": "How to manage regions",
+        "url": "https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-regions"
+      }
     },
     {
       "name": "Return Reasons",
-      "description": "Return Reason endpoints that allow handling return reasons in Medusa."
+      "description": "Return reasons are key-value pairs that are used to specify why an order return is being created.\nAdmins can manage available return reasons, and they can be used by both admins and customers when creating a return.\n",
+      "externalDocs": {
+        "description": "How to manage return reasons",
+        "url": "https://docs.medusajs.com/modules/orders/admin/manage-returns#manage-return-reasons"
+      }
     },
     {
       "name": "Returns",
-      "description": "Return endpoints that allow handling returns in Medusa."
+      "description": "A return can be created by a customer or an admin to return items in an order.\nAdmins can manage these returns and change their state.\n",
+      "externalDocs": {
+        "description": "How to manage returns",
+        "url": "https://docs.medusajs.com/modules/orders/admin/manage-returns"
+      }
     },
     {
       "name": "Sales Channels",
-      "description": "Sales Channel endpoints that allow handling sales channels in Medusa."
+      "description": "A sales channel indicates a channel where products can be sold in. For example, a webshop or a mobile app.\nAdmins can manage sales channels and the products available in them.\n",
+      "externalDocs": {
+        "description": "How to manage sales channels",
+        "url": "https://docs.medusajs.com/modules/sales-channels/admin/manage"
+      }
     },
     {
       "name": "Shipping Options",
-      "description": "Shipping Option endpoints that allow handling shipping options in Medusa."
+      "description": "A shipping option is used to define the available shipping methods during checkout or when creating a return.\nAdmins can create an unlimited number of shipping options, each associated with a shipping profile and fulfillment provider, among other resources.\n",
+      "externalDocs": {
+        "description": "Shipping Option architecture",
+        "url": "https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option"
+      }
     },
     {
       "name": "Shipping Profiles",
-      "description": "Shipping Profile endpoints that allow handling shipping profiles in Medusa."
+      "description": "A shipping profile is used to group products that can be shipped in the same manner.\nThey are created by the admin and they're not associated with a fulfillment provider.\n",
+      "externalDocs": {
+        "description": "Shipping Option architecture",
+        "url": "https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-profile"
+      }
+    },
+    {
+      "name": "Stock Locations",
+      "description": "A stock location, provided by the [Stock Location module](https://docs.medusajs.com/modules/multiwarehouse/stock-location-module), indicates a physical address that stock-kept items, such as physical products, can be stored in.\nAn admin can create and manage available stock locations.\n",
+      "externalDocs": {
+        "description": "How to manage stock locations.",
+        "url": "https://docs.medusajs.com/modules/multiwarehouse/admin/manage-stock-locations"
+      }
     },
     {
       "name": "Store",
-      "description": "Store endpoints that allow handling stores in Medusa."
+      "description": "A store indicates the general configurations and details about the commerce store. By default, there's only one store in the Medusa backend.\nAdmins can manage the store and its details or configurations.\n"
     },
     {
       "name": "Swaps",
-      "description": "Swap endpoints that allow handling swaps in Medusa."
+      "description": "A swap is created by a customer or an admin to exchange an item with a new one.\nCreating a swap implicitely includes creating a return for the item being exchanged.\n",
+      "externalDocs": {
+        "description": "How to manage swaps",
+        "url": "https://docs.medusajs.com/modules/orders/admin/manage-swaps"
+      }
     },
     {
       "name": "Tax Rates",
-      "description": "Tax Rate endpoints that allow handling tax rates in Medusa."
+      "description": "Each region has at least a default tax rate. Admins can create and manage additional tax rates that can be applied for certain conditions, such as for specific product types.\n",
+      "externalDocs": {
+        "description": "How to manage tax rates",
+        "url": "https://docs.medusajs.com/modules/taxes/admin/manage-tax-rates"
+      }
     },
     {
       "name": "Uploads",
-      "description": "Upload endpoints that allow handling uploads in Medusa."
+      "description": "The upload endpoints are used to upload any type of resources. For example, they can be used to upload CSV files that are used to import products into the store.\n",
+      "externalDocs": {
+        "description": "How to upload CSV file when importing a product.",
+        "url": "https://docs.medusajs.com/modules/products/admin/import-products#1-upload-csv-file"
+      }
     },
     {
       "name": "Users",
-      "description": "User endpoints that allow handling users in Medusa."
-    },
-    {
-      "name": "Variants",
-      "description": "Product Variant endpoints that allow handling product variants in Medusa."
+      "description": "A store can have more than one user, each having the same privileges. Admins can manage users, their passwords, and more.\n",
+      "externalDocs": {
+        "description": "How to manage users",
+        "url": "https://docs.medusajs.com/modules/users/admin/manage-users"
+      }
     }
   ],
   "servers": [
@@ -137,7 +285,7 @@
       "get": {
         "operationId": "GetApps",
         "summary": "List Applications",
-        "description": "Retrieve a list of applications.",
+        "description": "Retrieve a list of applications registered in the Medusa backend.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "list"
@@ -146,7 +294,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/apps' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/apps' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -158,7 +306,7 @@
           }
         ],
         "tags": [
-          "Apps"
+          "Apps Oauth"
         ],
         "responses": {
           "200": {
@@ -196,7 +344,7 @@
       "post": {
         "operationId": "PostApps",
         "summary": "Generate Token for App",
-        "description": "Generates a token for an application.",
+        "description": "Use an app's Oauth provider to generate and store a new token for authentication.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -214,7 +362,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/apps/authorizations' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"application_name\": \"example\",\n    \"state\": \"ready\",\n    \"code\": \"token\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/apps/authorizations' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"application_name\": \"example\",\n    \"state\": \"ready\",\n    \"code\": \"token\"\n}'\n"
           }
         ],
         "security": [
@@ -226,7 +374,7 @@
           }
         ],
         "tags": [
-          "Apps"
+          "Apps Oauth"
         ],
         "responses": {
           "200": {
@@ -265,7 +413,7 @@
         "operationId": "GetAuth",
         "summary": "Get Current User",
         "x-authenticated": true,
-        "description": "Gets the currently logged in User.",
+        "description": "Get the currently logged in user's details.",
         "x-codegen": {
           "method": "getSession"
         },
@@ -278,7 +426,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/auth' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/auth' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -327,27 +475,12 @@
         "operationId": "PostAuth",
         "summary": "User Login",
         "x-authenticated": false,
-        "description": "Logs a User in and authorizes them to manage Store settings.",
-        "parameters": [],
+        "description": "Log a User in and includes the Cookie session in the response header. The cookie session can be used in subsequent requests to authorize the user to perform admin functionalities. When using Medusa's JS or Medusa React clients, the cookie is automatically attached to subsequent requests.",
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "type": "object",
-                "required": [
-                  "email",
-                  "password"
-                ],
-                "properties": {
-                  "email": {
-                    "type": "string",
-                    "description": "The User's email."
-                  },
-                  "password": {
-                    "type": "string",
-                    "description": "The User's password."
-                  }
-                }
+                "$ref": "#/components/schemas/AdminPostAuthReq"
               }
             }
           }
@@ -359,12 +492,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.admin.auth.createSession({\n  email: 'user@example.com',\n  password: 'supersecret'\n})\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.admin.auth.createSession({\n  email: \"user@example.com\",\n  password: \"supersecret\"\n})\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/auth' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n  \"email\": \"user@example.com\",\n  \"password\": \"supersecret\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/auth' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"email\": \"user@example.com\",\n  \"password\": \"supersecret\"\n}'\n"
           }
         ],
         "tags": [
@@ -405,7 +538,7 @@
         "operationId": "DeleteAuth",
         "summary": "User Logout",
         "x-authenticated": true,
-        "description": "Deletes the current session for the logged in user.",
+        "description": "Delete the current session for the logged in user. This will only work if you're using Cookie session for authentication. If the API token is still passed in the header, the user is still authorized to perform admin functionalities in other endpoints.",
         "x-codegen": {
           "method": "deleteSession"
         },
@@ -413,12 +546,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.auth.deleteSession()\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in\nmedusa.admin.auth.deleteSession()\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/auth' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/auth' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -461,13 +594,13 @@
       "get": {
         "operationId": "GetBatchJobs",
         "summary": "List Batch Jobs",
-        "description": "Retrieve a list of Batch Jobs.",
+        "description": "Retrieve a list of Batch Jobs. The batch jobs can be filtered by fields such as `type` or `confirmed_at`. The batch jobs can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of batch jobs to return.",
+            "description": "Limit the number of batch jobs returned.",
             "schema": {
               "type": "integer",
               "default": 10
@@ -476,7 +609,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of batch jobs to skip before results.",
+            "description": "The number of batch jobs to skip when retrieving the batch jobs.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -522,7 +655,7 @@
             "name": "confirmed_at",
             "style": "form",
             "explode": false,
-            "description": "Date comparison for when resulting collections was confirmed, i.e. less than, greater than etc.",
+            "description": "Filter by a confirmation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -554,7 +687,7 @@
             "name": "pre_processed_at",
             "style": "form",
             "explode": false,
-            "description": "Date comparison for when resulting collections was pre processed, i.e. less than, greater than etc.",
+            "description": "Filter by a pre-processing date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -586,7 +719,7 @@
             "name": "completed_at",
             "style": "form",
             "explode": false,
-            "description": "Date comparison for when resulting collections was completed, i.e. less than, greater than etc.",
+            "description": "Filter by a completion date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -618,7 +751,7 @@
             "name": "failed_at",
             "style": "form",
             "explode": false,
-            "description": "Date comparison for when resulting collections was failed, i.e. less than, greater than etc.",
+            "description": "Filter by a failure date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -650,7 +783,7 @@
             "name": "canceled_at",
             "style": "form",
             "explode": false,
-            "description": "Date comparison for when resulting collections was canceled, i.e. less than, greater than etc.",
+            "description": "Filter by a cancelation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -680,7 +813,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "Field used to order retrieved batch jobs",
+            "description": "A batch-job field to sort-order the retrieved batch jobs by.",
             "schema": {
               "type": "string"
             }
@@ -688,7 +821,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each order of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned batch jobs.",
             "schema": {
               "type": "string"
             }
@@ -696,7 +829,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each order of the result.",
+            "description": "Comma-separated fields that should be included in the returned batch jobs.",
             "schema": {
               "type": "string"
             }
@@ -706,7 +839,7 @@
             "name": "created_at",
             "style": "form",
             "explode": false,
-            "description": "Date comparison for when resulting collections was created, i.e. less than, greater than etc.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -738,7 +871,7 @@
             "name": "updated_at",
             "style": "form",
             "explode": false,
-            "description": "Date comparison for when resulting collections was updated, i.e. less than, greater than etc.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -774,12 +907,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.batchJobs.list()\n.then(({ batch_jobs, limit, offset, count }) => {\n  console.log(batch_jobs.length);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.batchJobs.list()\n.then(({ batch_jobs, limit, offset, count }) => {\n  console.log(batch_jobs.length)\n})\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/batch-jobs' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/batch-jobs' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -827,7 +960,11 @@
       "post": {
         "operationId": "PostBatchJobs",
         "summary": "Create a Batch Job",
-        "description": "Creates a Batch Job.",
+        "description": "Create a Batch Job to be executed asynchronously in the Medusa backend. If `dry_run` is set to `true`, the batch job will not be executed until the it is confirmed, which can be done using the Confirm Batch Job endpoint.",
+        "externalDocs": {
+          "description": "How to create a batch job",
+          "url": "https://docs.medusajs.com/development/batch-jobs/create#create-batch-job"
+        },
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -850,7 +987,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/batch-jobs' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer {api_token}' \\\n--data-raw '{\n    \"type\": \"product-export\",\n    \"context\": { }\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/batch-jobs' \\\n-H 'Content-Type: application/json' \\\n-H 'Authorization: Bearer {api_token}' \\\n--data-raw '{\n    \"type\": \"product-export\",\n    \"context\": { }\n}'\n"
           }
         ],
         "security": [
@@ -900,7 +1037,7 @@
       "get": {
         "operationId": "GetBatchJobsBatchJob",
         "summary": "Get a Batch Job",
-        "description": "Retrieves a Batch Job.",
+        "description": "Retrieve the details of a batch job.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -920,12 +1057,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.batchJobs.retrieve(batch_job_id)\n.then(({ batch_job }) => {\n  console.log(batch_job.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.batchJobs.retrieve(batchJobId)\n.then(({ batch_job }) => {\n  console.log(batch_job.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/batch-jobs/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/batch-jobs/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -975,7 +1112,7 @@
       "post": {
         "operationId": "PostBatchJobsBatchJobCancel",
         "summary": "Cancel a Batch Job",
-        "description": "Marks a batch job as canceled",
+        "description": "Mark a batch job as canceled. When a batch job is canceled, the processing of the batch job doesn’t automatically stop.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -995,12 +1132,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.batchJobs.cancel(batch_job_id)\n.then(({ batch_job }) => {\n  console.log(batch_job.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.batchJobs.cancel(batchJobId)\n.then(({ batch_job }) => {\n  console.log(batch_job.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/cancel' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/batch-jobs/{id}/cancel' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -1050,7 +1187,7 @@
       "post": {
         "operationId": "PostBatchJobsBatchJobConfirmProcessing",
         "summary": "Confirm a Batch Job",
-        "description": "Confirms that a previously requested batch job should be executed.",
+        "description": "When a batch job is created, it is not executed automatically if `dry_run` is set to `true`. This endpoint confirms that the batch job should be executed.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -1070,12 +1207,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.batchJobs.confirm(batch_job_id)\n.then(({ batch_job }) => {\n  console.log(batch_job.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.batchJobs.confirm(batchJobId)\n.then(({ batch_job }) => {\n  console.log(batch_job.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/confirm' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/batch-jobs/{id}/confirm' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -1125,7 +1262,7 @@
       "get": {
         "operationId": "GetCollections",
         "summary": "List Collections",
-        "description": "Retrieve a list of Product Collection.",
+        "description": "Retrieve a list of Product Collection. The product collections can be filtered by fields such as `handle` or `title`. The collections can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -1140,7 +1277,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of collections to skip before the results.",
+            "description": "The number of collections to skip when retrieving the collections.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -1149,7 +1286,7 @@
           {
             "in": "query",
             "name": "title",
-            "description": "The title of collections to return.",
+            "description": "Filter collections by their title.",
             "schema": {
               "type": "string"
             }
@@ -1157,7 +1294,7 @@
           {
             "in": "query",
             "name": "handle",
-            "description": "The handle of collections to return.",
+            "description": "Filter collections by their handle.",
             "schema": {
               "type": "string"
             }
@@ -1165,7 +1302,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "a search term to search titles and handles.",
+            "description": "a term to search collections by their title or handle.",
             "schema": {
               "type": "string"
             }
@@ -1173,7 +1310,7 @@
           {
             "in": "query",
             "name": "discount_condition_id",
-            "description": "The discount condition id on which to filter the product collections.",
+            "description": "Filter collections by a discount condition ID associated with them.",
             "schema": {
               "type": "string"
             }
@@ -1181,7 +1318,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting collections were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -1211,7 +1348,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting collections were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -1241,7 +1378,7 @@
           {
             "in": "query",
             "name": "deleted_at",
-            "description": "Date comparison for when resulting collections were deleted.",
+            "description": "Filter by a deletion date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -1282,7 +1419,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/collections' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/collections' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -1294,7 +1431,7 @@
           }
         ],
         "tags": [
-          "Collections"
+          "Product Collections"
         ],
         "responses": {
           "200": {
@@ -1330,7 +1467,7 @@
       "post": {
         "operationId": "PostCollections",
         "summary": "Create a Collection",
-        "description": "Creates a Product Collection.",
+        "description": "Create a Product Collection.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -1348,12 +1485,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.create({\n  title: 'New Collection'\n})\n.then(({ collection }) => {\n  console.log(collection.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.create({\n  title: \"New Collection\"\n})\n.then(({ collection }) => {\n  console.log(collection.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/collections' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"New Collection\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/collections' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"New Collection\"\n}'\n"
           }
         ],
         "security": [
@@ -1365,7 +1502,7 @@
           }
         ],
         "tags": [
-          "Collections"
+          "Product Collections"
         ],
         "responses": {
           "200": {
@@ -1403,7 +1540,7 @@
       "get": {
         "operationId": "GetCollectionsCollection",
         "summary": "Get a Collection",
-        "description": "Retrieves a Product Collection.",
+        "description": "Retrieve a Product Collection by its ID. The products associated with it are expanded and returned as well.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -1423,12 +1560,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.retrieve(collection_id)\n.then(({ collection }) => {\n  console.log(collection.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.retrieve(collectionId)\n.then(({ collection }) => {\n  console.log(collection.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/collections/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/collections/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -1440,7 +1577,7 @@
           }
         ],
         "tags": [
-          "Collections"
+          "Product Collections"
         ],
         "responses": {
           "200": {
@@ -1476,7 +1613,7 @@
       "post": {
         "operationId": "PostCollectionsCollection",
         "summary": "Update a Collection",
-        "description": "Updates a Product Collection.",
+        "description": "Update a Product Collection's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -1505,12 +1642,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.update(collection_id, {\n  title: 'New Collection'\n})\n.then(({ collection }) => {\n  console.log(collection.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.update(collectionId, {\n  title: \"New Collection\"\n})\n.then(({ collection }) => {\n  console.log(collection.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/collections/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"New Collection\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/collections/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"New Collection\"\n}'\n"
           }
         ],
         "security": [
@@ -1522,7 +1659,7 @@
           }
         ],
         "tags": [
-          "Collections"
+          "Product Collections"
         ],
         "responses": {
           "200": {
@@ -1558,7 +1695,7 @@
       "delete": {
         "operationId": "DeleteCollectionsCollection",
         "summary": "Delete a Collection",
-        "description": "Deletes a Product Collection.",
+        "description": "Delete a Product Collection. This does not delete associated products.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -1578,12 +1715,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.delete(collection_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.delete(collectionId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/collections/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -1595,7 +1732,7 @@
           }
         ],
         "tags": [
-          "Collections"
+          "Product Collections"
         ],
         "responses": {
           "200": {
@@ -1632,15 +1769,15 @@
     "/admin/collections/{id}/products/batch": {
       "post": {
         "operationId": "PostProductsToCollection",
-        "summary": "Update Products",
-        "description": "Updates products associated with a Product Collection",
+        "summary": "Add Products to Collection",
+        "description": "Add products to a product collection.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Collection.",
+            "description": "The ID of the product collection.",
             "schema": {
               "type": "string"
             }
@@ -1659,10 +1796,15 @@
           "method": "addProducts"
         },
         "x-codeSamples": [
+          {
+            "lang": "JavaScript",
+            "label": "JS Client",
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.addProducts(collectionId, {\n  product_ids: [\n    productId1,\n    productId2\n  ]\n})\n.then(({ collection }) => {\n  console.log(collection.products)\n})\n"
+          },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/collections/{id}/products/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n        \"prod_01G1G5V2MBA328390B5AXJ610F\"\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/collections/{id}/products/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n        \"prod_01G1G5V2MBA328390B5AXJ610F\"\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -1674,7 +1816,7 @@
           }
         ],
         "tags": [
-          "Collections"
+          "Product Collections"
         ],
         "responses": {
           "200": {
@@ -1709,15 +1851,15 @@
       },
       "delete": {
         "operationId": "DeleteProductsFromCollection",
-        "summary": "Remove Product",
-        "description": "Removes products associated with a Product Collection",
+        "summary": "Remove Products from Collection",
+        "description": "Remove a list of products from a collection. This would not delete the product, only the association between the product and the collection.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Collection.",
+            "description": "The ID of the Product Collection.",
             "schema": {
               "type": "string"
             }
@@ -1736,10 +1878,15 @@
           "method": "removeProducts"
         },
         "x-codeSamples": [
+          {
+            "lang": "JavaScript",
+            "label": "JS Client",
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.collections.removeProducts(collectionId, {\n  product_ids: [\n    productId1,\n    productId2\n  ]\n})\n.then(({ id, object, removed_products }) => {\n  console.log(removed_products)\n})\n"
+          },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}/products/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n        \"prod_01G1G5V2MBA328390B5AXJ610F\"\n    ]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/collections/{id}/products/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n        \"prod_01G1G5V2MBA328390B5AXJ610F\"\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -1751,7 +1898,7 @@
           }
         ],
         "tags": [
-          "Collections"
+          "Product Collections"
         ],
         "responses": {
           "200": {
@@ -1789,13 +1936,13 @@
       "get": {
         "operationId": "GetCurrencies",
         "summary": "List Currency",
-        "description": "Retrieves a list of Currency",
+        "description": "Retrieve a list of currencies. The currencies can be filtered by fields such as `code`. The currencies can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "code",
-            "description": "Code of the currency to search for.",
+            "description": "filter by currency code.",
             "schema": {
               "type": "string"
             }
@@ -1803,15 +1950,16 @@
           {
             "in": "query",
             "name": "includes_tax",
-            "description": "Search for tax inclusive currencies.",
+            "description": "filter currencies by whether they include taxes or not.",
             "schema": {
-              "type": "boolean"
+              "type": "boolean",
+              "x-featureFlag": "tax_inclusive_pricing"
             }
           },
           {
             "in": "query",
             "name": "order",
-            "description": "order to retrieve products in.",
+            "description": "A field to sort order the retrieved currencies by.",
             "schema": {
               "type": "string"
             }
@@ -1819,7 +1967,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many products to skip in the result.",
+            "description": "The number of currencies to skip when retrieving the currencies.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -1828,7 +1976,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "Limit the number of products returned.",
+            "description": "The number of currencies to return.",
             "schema": {
               "type": "number",
               "default": "20"
@@ -1848,7 +1996,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/currencies' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/currencies' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "tags": [
@@ -1872,7 +2020,7 @@
       "post": {
         "operationId": "PostCurrenciesCurrency",
         "summary": "Update a Currency",
-        "description": "Update a Currency",
+        "description": "Update a Currency's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -1906,7 +2054,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/currencies/{code}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"includes_tax\": true\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/currencies/{code}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"includes_tax\": true\n}'\n"
           }
         ],
         "tags": [
@@ -1930,13 +2078,13 @@
       "get": {
         "operationId": "GetCustomerGroups",
         "summary": "List Customer Groups",
-        "description": "Retrieve a list of customer groups.",
+        "description": "Retrieve a list of customer groups. The customer groups can be filtered by fields such as `name` or `id. The customer groups can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching customer group names.",
+            "description": "term to search customer groups by name.",
             "schema": {
               "type": "string"
             }
@@ -1944,7 +2092,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many groups to skip in the result.",
+            "description": "The number of customer groups to skip when retrieving the customer groups.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -1953,7 +2101,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "the field used to order the customer groups.",
+            "description": "A field to sort order the retrieved customer groups by.",
             "schema": {
               "type": "string"
             }
@@ -1961,7 +2109,7 @@
           {
             "in": "query",
             "name": "discount_condition_id",
-            "description": "The discount condition id on which to filter the customer groups.",
+            "description": "Filter by discount condition ID.",
             "schema": {
               "type": "string"
             }
@@ -1980,7 +2128,7 @@
                 },
                 {
                   "type": "array",
-                  "description": "multiple customer group IDs",
+                  "description": "an array of customer group IDs",
                   "items": {
                     "type": "string"
                   }
@@ -2017,7 +2165,7 @@
             "description": "Filter by the customer group name",
             "schema": {
               "type": "array",
-              "description": "multiple customer group names",
+              "description": "an array of customer group names",
               "items": {
                 "type": "string",
                 "description": "customer group name"
@@ -2027,7 +2175,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting customer groups were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -2057,7 +2205,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting customer groups were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -2087,7 +2235,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "Limit the number of customer groups returned.",
+            "description": "The number of customer groups to return.",
             "schema": {
               "type": "integer",
               "default": 10
@@ -2096,7 +2244,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each customer groups of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned customer groups.",
             "schema": {
               "type": "string"
             }
@@ -2115,7 +2263,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/customer-groups' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/customer-groups' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -2163,7 +2311,7 @@
       "post": {
         "operationId": "PostCustomerGroups",
         "summary": "Create a Customer Group",
-        "description": "Creates a CustomerGroup.",
+        "description": "Creates a Customer Group.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -2181,12 +2329,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.create({\n  name: 'VIP'\n})\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.create({\n  name: \"VIP\"\n})\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/customer-groups' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"VIP\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/customer-groups' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"VIP\"\n}'\n"
           }
         ],
         "security": [
@@ -2236,7 +2384,7 @@
       "get": {
         "operationId": "GetCustomerGroupsGroup",
         "summary": "Get a Customer Group",
-        "description": "Retrieves a Customer Group.",
+        "description": "Retrieve a Customer Group by its ID. You can expand the customer group's relations or select the fields that should be returned.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -2251,7 +2399,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in the customer group.",
+            "description": "Comma-separated relations that should be expanded in the returned customer group.",
             "schema": {
               "type": "string"
             }
@@ -2259,7 +2407,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in the customer group.",
+            "description": "Comma-separated fields that should be included in the returned customer group.",
             "schema": {
               "type": "string"
             }
@@ -2273,12 +2421,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.retrieve(customer_group_id)\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.retrieve(customerGroupId)\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/customer-groups/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -2326,7 +2474,7 @@
       "post": {
         "operationId": "PostCustomerGroupsGroup",
         "summary": "Update a Customer Group",
-        "description": "Update a CustomerGroup.",
+        "description": "Update a Customer Group's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -2355,12 +2503,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.update(customer_group_id, {\n  name: 'VIP'\n})\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.update(customerGroupId, {\n  name: \"VIP\"\n})\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"VIP\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/customer-groups/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"VIP\"\n}'\n"
           }
         ],
         "security": [
@@ -2408,7 +2556,7 @@
       "delete": {
         "operationId": "DeleteCustomerGroupsCustomerGroup",
         "summary": "Delete a Customer Group",
-        "description": "Deletes a CustomerGroup.",
+        "description": "Delete a customer group. This doesn't delete the customers associated with the customer group.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -2428,12 +2576,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.delete(customer_group_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.delete(customerGroupId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/customer-groups/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -2483,7 +2631,7 @@
       "get": {
         "operationId": "GetCustomerGroupsGroupCustomers",
         "summary": "List Customers",
-        "description": "Retrieves a list of customers in a customer group",
+        "description": "Retrieve a list of customers in a customer group. The customers can be filtered by the `q` field. The customers can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -2498,7 +2646,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of items to return.",
+            "description": "The number of customers to return.",
             "schema": {
               "type": "integer",
               "default": 50
@@ -2507,7 +2655,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The items to skip before result.",
+            "description": "The number of customers to skip when retrieving the customers.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -2516,7 +2664,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each customer.",
+            "description": "Comma-separated relations that should be expanded in the returned customers.",
             "schema": {
               "type": "string"
             }
@@ -2524,7 +2672,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "a search term to search email, first_name, and last_name.",
+            "description": "a term to search customers by email, first_name, and last_name.",
             "schema": {
               "type": "string"
             }
@@ -2538,12 +2686,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.listCustomers(customer_group_id)\n.then(({ customers }) => {\n  console.log(customers.length);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.listCustomers(customerGroupId)\n.then(({ customers }) => {\n  console.log(customers.length);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}/customers' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/customer-groups/{id}/customers' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -2592,8 +2740,8 @@
     "/admin/customer-groups/{id}/customers/batch": {
       "post": {
         "operationId": "PostCustomerGroupsGroupCustomersBatch",
-        "summary": "Add Customers",
-        "description": "Adds a list of customers, represented by id's, to a customer group.",
+        "summary": "Add Customers to Group",
+        "description": "Add a list of customers to a customer group.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -2622,12 +2770,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.addCustomers(customer_group_id, {\n  customer_ids: [\n    {\n      id: customer_id\n    }\n  ]\n})\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.addCustomers(customerGroupId, {\n  customer_ids: [\n    {\n      id: customerId\n    }\n  ]\n})\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"customer_ids\": [\n        {\n            \"id\": \"cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2\"\n        }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"customer_ids\": [\n        {\n            \"id\": \"cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2\"\n        }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -2674,8 +2822,8 @@
       },
       "delete": {
         "operationId": "DeleteCustomerGroupsGroupCustomerBatch",
-        "summary": "Remove Customers",
-        "description": "Removes a list of customers, represented by id's, from a customer group.",
+        "summary": "Remove Customers from Group",
+        "description": "Remove a list of customers from a customer group. This doesn't delete the customer, only the association between the customer and the customer group.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -2704,12 +2852,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.removeCustomers(customer_group_id, {\n  customer_ids: [\n    {\n      id: customer_id\n    }\n  ]\n})\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customerGroups.removeCustomers(customerGroupId, {\n  customer_ids: [\n    {\n      id: customerId\n    }\n  ]\n})\n.then(({ customer_group }) => {\n  console.log(customer_group.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"customer_ids\": [\n        {\n            \"id\": \"cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2\"\n        }\n    ]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"customer_ids\": [\n        {\n            \"id\": \"cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2\"\n        }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -2759,13 +2907,13 @@
       "get": {
         "operationId": "GetCustomers",
         "summary": "List Customers",
-        "description": "Retrieves a list of Customers.",
+        "description": "Retrieve a list of Customers. The customers can be filtered by fields such as `q` or `groups`. The customers can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of items to return.",
+            "description": "The number of customers to return.",
             "schema": {
               "type": "integer",
               "default": 50
@@ -2774,7 +2922,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The items to skip before result.",
+            "description": "The number of customers to skip when retrieving the customers.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -2783,7 +2931,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each customer.",
+            "description": "Comma-separated relations that should be expanded in the returned customer.",
             "schema": {
               "type": "string"
             }
@@ -2791,10 +2939,23 @@
           {
             "in": "query",
             "name": "q",
-            "description": "a search term to search email, first_name, and last_name.",
+            "description": "term to search customers' email, first_name, and last_name fields.",
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "in": "query",
+            "name": "groups",
+            "style": "form",
+            "explode": false,
+            "description": "Filter by customer group IDs.",
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           }
         ],
         "x-codegen": {
@@ -2810,7 +2971,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/customers' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/customers' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -2858,7 +3019,7 @@
       "post": {
         "operationId": "PostCustomers",
         "summary": "Create a Customer",
-        "description": "Creates a Customer.",
+        "description": "Allow admins to create a customer.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -2876,12 +3037,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customers.create({\n  email: 'user@example.com',\n  first_name: 'Caterina',\n  last_name: 'Yost',\n  password: 'supersecret'\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customers.create({\n  email: \"user@example.com\",\n  first_name: \"Caterina\",\n  last_name: \"Yost\",\n  password: \"supersecret\"\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/customers' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"first_name\": \"Caterina\",\n    \"last_name\": \"Yost\",\n    \"password\": \"supersecret\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/customers' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"first_name\": \"Caterina\",\n    \"last_name\": \"Yost\",\n    \"password\": \"supersecret\"\n}'\n"
           }
         ],
         "security": [
@@ -2931,7 +3092,7 @@
       "get": {
         "operationId": "GetCustomersCustomer",
         "summary": "Get a Customer",
-        "description": "Retrieves a Customer.",
+        "description": "Retrieve the details of a customer.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -2946,7 +3107,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in the customer.",
+            "description": "Comma-separated relations that should be expanded in the returned customer.",
             "schema": {
               "type": "string"
             }
@@ -2954,7 +3115,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in the customer.",
+            "description": "Comma-separated fields that should be included in the returned customer.",
             "schema": {
               "type": "string"
             }
@@ -2967,12 +3128,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customers.retrieve(customer_id)\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customers.retrieve(customerId)\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/customers/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/customers/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -3020,7 +3181,7 @@
       "post": {
         "operationId": "PostCustomersCustomer",
         "summary": "Update a Customer",
-        "description": "Updates a Customer.",
+        "description": "Update a Customer's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -3035,7 +3196,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each customer.",
+            "description": "Comma-separated relations that should be expanded in the returned customer.",
             "schema": {
               "type": "string"
             }
@@ -3043,7 +3204,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be retrieved in each customer.",
+            "description": "Comma-separated fields that should be retrieved in the returned customer.",
             "schema": {
               "type": "string"
             }
@@ -3065,12 +3226,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customers.update(customer_id, {\n  first_name: 'Dolly'\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.customers.update(customerId, {\n  first_name: \"Dolly\"\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/customers/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Dolly\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/customers/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Dolly\"\n}'\n"
           }
         ],
         "security": [
@@ -3121,12 +3282,12 @@
         "operationId": "GetDiscounts",
         "summary": "List Discounts",
         "x-authenticated": true,
-        "description": "Retrieves a list of Discounts",
+        "description": "Retrieve a list of Discounts. The discounts can be filtered by fields such as `rule` or `is_dynamic`. The discounts can also be paginated.",
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Search query applied on the code field.",
+            "description": "term to search discounts' code field.",
             "schema": {
               "type": "string"
             }
@@ -3134,7 +3295,7 @@
           {
             "in": "query",
             "name": "rule",
-            "description": "Discount Rules filters to apply on the search",
+            "description": "Filter discounts by rule fields.",
             "schema": {
               "type": "object",
               "properties": {
@@ -3145,7 +3306,7 @@
                     "percentage",
                     "free_shipping"
                   ],
-                  "description": "The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers."
+                  "description": "Filter discounts by type."
                 },
                 "allocation": {
                   "type": "string",
@@ -3153,7 +3314,7 @@
                     "total",
                     "item"
                   ],
-                  "description": "The value that the discount represents; this will depend on the type of the discount"
+                  "description": "Filter discounts by allocation type."
                 }
               }
             }
@@ -3161,7 +3322,7 @@
           {
             "in": "query",
             "name": "is_dynamic",
-            "description": "Return only dynamic discounts.",
+            "description": "Filter discounts by whether they're dynamic or not.",
             "schema": {
               "type": "boolean"
             }
@@ -3169,7 +3330,7 @@
           {
             "in": "query",
             "name": "is_disabled",
-            "description": "Return only disabled discounts.",
+            "description": "Filter discounts by whether they're disabled or not.",
             "schema": {
               "type": "boolean"
             }
@@ -3177,7 +3338,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of items in the response",
+            "description": "The number of discounts to return",
             "schema": {
               "type": "number",
               "default": "20"
@@ -3186,7 +3347,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The offset of items in response",
+            "description": "The number of discounts to skip when retrieving the discounts.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -3195,7 +3356,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in each returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3214,7 +3375,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/discounts' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/discounts' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -3261,14 +3422,14 @@
       },
       "post": {
         "operationId": "PostDiscounts",
-        "summary": "Creates a Discount",
+        "summary": "Create a Discount",
         "x-authenticated": true,
-        "description": "Creates a Discount with a given set of rules that define how the Discount behaves.",
+        "description": "Create a Discount with a given set of rules that defines how the Discount is applied.",
         "parameters": [
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3276,7 +3437,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be retrieved in the results.",
+            "description": "Comma-separated fields that should be retrieved in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3299,12 +3460,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nimport { AllocationType, DiscountRuleType } from \"@medusajs/medusa\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.create({\n  code: 'TEST',\n  rule: {\n    type: DiscountRuleType.FIXED,\n    value: 10,\n    allocation: AllocationType.ITEM\n  },\n  regions: [\"reg_XXXXXXXX\"],\n  is_dynamic: false,\n  is_disabled: false\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nimport { AllocationType, DiscountRuleType } from \"@medusajs/medusa\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.create({\n  code: \"TEST\",\n  rule: {\n    type: DiscountRuleType.FIXED,\n    value: 10,\n    allocation: AllocationType.ITEM\n  },\n  regions: [\"reg_XXXXXXXX\"],\n  is_dynamic: false,\n  is_disabled: false\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/discounts' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"code\": \"TEST\",\n    \"rule\": {\n       \"type\": \"fixed\",\n       \"value\": 10,\n       \"allocation\": \"item\"\n    },\n    \"regions\": [\"reg_XXXXXXXX\"]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/discounts' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"code\": \"TEST\",\n    \"rule\": {\n       \"type\": \"fixed\",\n       \"value\": 10,\n       \"allocation\": \"item\"\n    },\n    \"regions\": [\"reg_XXXXXXXX\"]\n}'\n"
           }
         ],
         "security": [
@@ -3354,7 +3515,7 @@
       "get": {
         "operationId": "GetDiscountsDiscountCode",
         "summary": "Get Discount by Code",
-        "description": "Retrieves a Discount by its discount code",
+        "description": "Retrieve a Discount's details by its discount code",
         "x-authenticated": true,
         "parameters": [
           {
@@ -3369,7 +3530,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3377,7 +3538,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3396,7 +3557,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/discounts/code/{code}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/discounts/code/{code}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -3446,14 +3607,14 @@
       "post": {
         "operationId": "PostDiscountsDiscountConditions",
         "summary": "Create a Condition",
-        "description": "Creates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided.",
+        "description": "Create a Discount Condition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided, based on the type of discount condition. For example, if the discount condition's type is `products`, the `products` field should be provided in the request body.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "discount_id",
             "required": true,
-            "description": "The ID of the Product.",
+            "description": "The ID of the discount.",
             "schema": {
               "type": "string"
             }
@@ -3461,7 +3622,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each product of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3469,7 +3630,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each product of the result.",
+            "description": "Comma-separated fields that should be included in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3492,12 +3653,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nimport { DiscountConditionOperator } from \"@medusajs/medusa\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.createCondition(discount_id, {\n  operator: DiscountConditionOperator.IN\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nimport { DiscountConditionOperator } from \"@medusajs/medusa\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.createCondition(discountId, {\n  operator: DiscountConditionOperator.IN\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"operator\": \"in\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/discounts/{id}/conditions' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"operator\": \"in\"\n}'\n"
           }
         ],
         "security": [
@@ -3547,7 +3708,7 @@
       "get": {
         "operationId": "GetDiscountsDiscountConditionsCondition",
         "summary": "Get a Condition",
-        "description": "Gets a DiscountCondition",
+        "description": "Retrieve a Discount Condition's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -3563,7 +3724,7 @@
             "in": "path",
             "name": "condition_id",
             "required": true,
-            "description": "The ID of the DiscountCondition.",
+            "description": "The ID of the Discount Condition.",
             "schema": {
               "type": "string"
             }
@@ -3571,7 +3732,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned discount condition.",
             "schema": {
               "type": "string"
             }
@@ -3579,7 +3740,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned discount condition.",
             "schema": {
               "type": "string"
             }
@@ -3593,12 +3754,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.getCondition(discount_id, condition_id)\n.then(({ discount_condition }) => {\n  console.log(discount_condition.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.getCondition(discountId, conditionId)\n.then(({ discount_condition }) => {\n  console.log(discount_condition.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -3646,14 +3807,14 @@
       "post": {
         "operationId": "PostDiscountsDiscountConditionsCondition",
         "summary": "Update a Condition",
-        "description": "Updates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided.",
+        "description": "Update a Discount Condition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided, based on the type of discount condition. For example, if the discount condition's type is `products`, the `products` field should be provided in the request body.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "discount_id",
             "required": true,
-            "description": "The ID of the Product.",
+            "description": "The ID of the Discount.",
             "schema": {
               "type": "string"
             }
@@ -3662,7 +3823,7 @@
             "in": "path",
             "name": "condition_id",
             "required": true,
-            "description": "The ID of the DiscountCondition.",
+            "description": "The ID of the Discount Condition.",
             "schema": {
               "type": "string"
             }
@@ -3670,7 +3831,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each item of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3678,7 +3839,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each item of the result.",
+            "description": "Comma-separated fields that should be included in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3701,12 +3862,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.updateCondition(discount_id, condition_id, {\n  products: [\n    product_id\n  ]\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.updateCondition(discountId, conditionId, {\n  products: [\n    productId\n  ]\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"products\": [\n       \"prod_01G1G5V2MBA328390B5AXJ610F\"\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"products\": [\n       \"prod_01G1G5V2MBA328390B5AXJ610F\"\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -3754,7 +3915,7 @@
       "delete": {
         "operationId": "DeleteDiscountsDiscountConditionsCondition",
         "summary": "Delete a Condition",
-        "description": "Deletes a DiscountCondition",
+        "description": "Deletes a Discount Condition. This does not delete resources associated to the discount condition.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -3770,7 +3931,7 @@
             "in": "path",
             "name": "condition_id",
             "required": true,
-            "description": "The ID of the DiscountCondition",
+            "description": "The ID of the Discount Condition",
             "schema": {
               "type": "string"
             }
@@ -3778,7 +3939,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3786,7 +3947,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3800,12 +3961,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.deleteCondition(discount_id, condition_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.deleteCondition(discountId, conditionId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -3855,14 +4016,14 @@
       "post": {
         "operationId": "PostDiscountsDiscountConditionsConditionBatch",
         "summary": "Add Batch Resources",
-        "description": "Add a batch of resources to a discount condition.",
+        "description": "Add a batch of resources to a discount condition. The type of resource depends on the type of discount condition. For example, if the discount condition's type is `products`, the resources being added should be products.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "discount_id",
             "required": true,
-            "description": "The ID of the Product.",
+            "description": "The ID of the discount the condition belongs to.",
             "schema": {
               "type": "string"
             }
@@ -3871,7 +4032,7 @@
             "in": "path",
             "name": "condition_id",
             "required": true,
-            "description": "The ID of the condition on which to add the item.",
+            "description": "The ID of the discount condition on which to add the item.",
             "schema": {
               "type": "string"
             }
@@ -3879,7 +4040,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which relations should be expanded in each discount of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3887,7 +4048,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each discount of the result.",
+            "description": "Comma-separated fields that should be included in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3910,12 +4071,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.addConditionResourceBatch(discount_id, condition_id, {\n  resources: [{ id: item_id }]\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.addConditionResourceBatch(discountId, conditionId, {\n  resources: [{ id: itemId }]\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"resources\": [{ \"id\": \"item_id\" }]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"resources\": [{ \"id\": \"item_id\" }]\n}'\n"
           }
         ],
         "security": [
@@ -3962,15 +4123,15 @@
       },
       "delete": {
         "operationId": "DeleteDiscountsDiscountConditionsConditionBatch",
-        "summary": "Delete Batch Resources",
-        "description": "Delete a batch of resources from a discount condition.",
+        "summary": "Remove Batch Resources",
+        "description": "Remove a batch of resources from a discount condition. This will only remove the association between the resource and the discount condition, but not the resource itself.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "discount_id",
             "required": true,
-            "description": "The ID of the Product.",
+            "description": "The ID of the discount.",
             "schema": {
               "type": "string"
             }
@@ -3979,7 +4140,7 @@
             "in": "path",
             "name": "condition_id",
             "required": true,
-            "description": "The ID of the condition on which to add the item.",
+            "description": "The ID of the condition to remove the resources from.",
             "schema": {
               "type": "string"
             }
@@ -3987,7 +4148,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which relations should be expanded in each discount of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -3995,7 +4156,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each discount of the result.",
+            "description": "Comma-separated fields that should be included in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -4017,12 +4178,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.deleteConditionResourceBatch(discount_id, condition_id, {\n  resources: [{ id: item_id }]\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.deleteConditionResourceBatch(discountId, conditionId, {\n  resources: [{ id: itemId }]\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"resources\": [{ \"id\": \"item_id\" }]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"resources\": [{ \"id\": \"item_id\" }]\n}'\n"
           }
         ],
         "security": [
@@ -4087,7 +4248,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -4095,7 +4256,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -4109,12 +4270,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.retrieve(discount_id)\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.retrieve(discountId)\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/discounts/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -4162,7 +4323,7 @@
       "post": {
         "operationId": "PostDiscountsDiscount",
         "summary": "Update a Discount",
-        "description": "Updates a Discount with a given set of rules that define how the Discount behaves.",
+        "description": "Update a Discount with a given set of rules that define how the Discount is applied.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -4177,7 +4338,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each item of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -4185,7 +4346,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each item of the result.",
+            "description": "Comma-separated fields that should be retrieved in the returned discount.",
             "schema": {
               "type": "string"
             }
@@ -4208,12 +4369,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.update(discount_id, {\n  code: 'TEST'\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.update(discountId, {\n  code: \"TEST\"\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"code\": \"TEST\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/discounts/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"code\": \"TEST\"\n}'\n"
           }
         ],
         "security": [
@@ -4261,7 +4422,7 @@
       "delete": {
         "operationId": "DeleteDiscountsDiscount",
         "summary": "Delete a Discount",
-        "description": "Deletes a Discount.",
+        "description": "Delete a Discount. Deleting the discount will make it unavailable for customers to use.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -4281,12 +4442,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.delete(discount_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.delete(discountId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -4336,14 +4497,14 @@
       "post": {
         "operationId": "PostDiscountsDiscountDynamicCodes",
         "summary": "Create a Dynamic Code",
-        "description": "Creates a dynamic unique code that can map to a parent Discount. This is useful if you want to automatically generate codes with the same behaviour.",
+        "description": "Create a dynamic unique code that can map to a parent Discount. This is useful if you want to automatically generate codes with the same rules and conditions.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Discount to create the dynamic code from.\"",
+            "description": "The ID of the Discount to create the dynamic code for.\"",
             "schema": {
               "type": "string"
             }
@@ -4365,12 +4526,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.createDynamicCode(discount_id, {\n  code: 'TEST',\n  usage_limit: 1\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.createDynamicCode(discountId, {\n  code: \"TEST\",\n  usage_limit: 1\n})\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"code\": \"TEST\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"code\": \"TEST\"\n}'\n"
           }
         ],
         "security": [
@@ -4420,7 +4581,7 @@
       "delete": {
         "operationId": "DeleteDiscountsDiscountDynamicCodesCode",
         "summary": "Delete a Dynamic Code",
-        "description": "Deletes a dynamic code from a Discount.",
+        "description": "Delete a dynamic code from a Discount.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -4436,7 +4597,7 @@
             "in": "path",
             "name": "code",
             "required": true,
-            "description": "The ID of the Discount",
+            "description": "The dynamic code to delete",
             "schema": {
               "type": "string"
             }
@@ -4449,12 +4610,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.deleteDynamicCode(discount_id, code)\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.deleteDynamicCode(discountId, code)\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes/{code}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes/{code}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -4503,8 +4664,8 @@
     "/admin/discounts/{id}/regions/{region_id}": {
       "post": {
         "operationId": "PostDiscountsDiscountRegionsRegion",
-        "summary": "Add Region",
-        "description": "Adds a Region to the list of Regions that a Discount can be used in.",
+        "summary": "Add Region to Discount",
+        "description": "Add a Region to the list of Regions a Discount can be used in.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -4533,12 +4694,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.addRegion(discount_id, region_id)\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.addRegion(discountId, regionId)\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -4587,7 +4748,7 @@
         "operationId": "DeleteDiscountsDiscountRegionsRegion",
         "summary": "Remove Region",
         "x-authenticated": true,
-        "description": "Removes a Region from the list of Regions that a Discount can be used in.",
+        "description": "Remove a Region from the list of Regions that a Discount can be used in. This does not delete a region, only the association between it and the discount.",
         "parameters": [
           {
             "in": "path",
@@ -4615,12 +4776,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.removeRegion(discount_id, region_id)\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.discounts.removeRegion(discountId, regionId)\n.then(({ discount }) => {\n  console.log(discount.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -4670,13 +4831,13 @@
       "get": {
         "operationId": "GetDraftOrders",
         "summary": "List Draft Orders",
-        "description": "Retrieves an list of Draft Orders",
+        "description": "Retrieve an list of Draft Orders. The draft orders can be filtered by fields such as `q`. The draft orders can also paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of items to skip before the results.",
+            "description": "The number of draft orders to skip when retrieving the draft orders.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -4685,7 +4846,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "Limit the number of items returned.",
+            "description": "Limit the number of draft orders returned.",
             "schema": {
               "type": "number",
               "default": "50"
@@ -4694,7 +4855,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "a search term to search emails in carts associated with draft orders and display IDs of draft orders",
+            "description": "a term to search draft orders' display IDs and emails in the draft order's cart",
             "schema": {
               "type": "string"
             }
@@ -4713,7 +4874,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/draft-orders' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/draft-orders' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -4761,7 +4922,7 @@
       "post": {
         "operationId": "PostDraftOrders",
         "summary": "Create a Draft Order",
-        "description": "Creates a Draft Order",
+        "description": "Create a Draft Order. A draft order is not transformed into an order until payment is captured.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -4779,12 +4940,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.create({\n  email: 'user@example.com',\n  region_id,\n  items: [\n    {\n      quantity: 1\n    }\n  ],\n  shipping_methods: [\n    {\n      option_id\n    }\n  ],\n})\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.create({\n  email: \"user@example.com\",\n  region_id,\n  items: [\n    {\n      quantity: 1\n    }\n  ],\n  shipping_methods: [\n    {\n      option_id\n    }\n  ],\n})\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/draft-orders' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"region_id\": \"{region_id}\"\n    \"items\": [\n       {\n         \"quantity\": 1\n       }\n    ],\n    \"shipping_methods\": [\n       {\n         \"option_id\": \"{option_id}\"\n       }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/draft-orders' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"region_id\": \"{region_id}\"\n    \"items\": [\n       {\n         \"quantity\": 1\n       }\n    ],\n    \"shipping_methods\": [\n       {\n         \"option_id\": \"{option_id}\"\n       }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -4834,7 +4995,7 @@
       "get": {
         "operationId": "GetDraftOrdersDraftOrder",
         "summary": "Get a Draft Order",
-        "description": "Retrieves a Draft Order.",
+        "description": "Retrieve a Draft Order's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -4854,12 +5015,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.retrieve(draft_order_id)\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.retrieve(draftOrderId)\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/draft-orders/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/draft-orders/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -4907,7 +5068,7 @@
       "post": {
         "operationId": "PostDraftOrdersDraftOrder",
         "summary": "Update a Draft Order",
-        "description": "Updates a Draft Order.",
+        "description": "Update a Draft Order's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -4936,12 +5097,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.update(draft_order_id, {\n  email: \"user@example.com\"\n})\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.update(draftOrderId, {\n  email: \"user@example.com\"\n})\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
           }
         ],
         "security": [
@@ -4989,7 +5150,7 @@
       "delete": {
         "operationId": "DeleteDraftOrdersDraftOrder",
         "summary": "Delete a Draft Order",
-        "description": "Deletes a Draft Order",
+        "description": "Delete a Draft Order",
         "x-authenticated": true,
         "parameters": [
           {
@@ -5009,12 +5170,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.delete(draft_order_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.delete(draftOrderId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/draft-orders/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -5064,7 +5225,7 @@
       "post": {
         "operationId": "PostDraftOrdersDraftOrderLineItems",
         "summary": "Create a Line Item",
-        "description": "Creates a Line Item for the Draft Order",
+        "description": "Create a Line Item in the Draft Order.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -5093,12 +5254,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.addLineItem(draft_order_id, {\n  quantity: 1\n})\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.addLineItem(draftOrderId, {\n  quantity: 1\n})\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"quantity\": 1\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"quantity\": 1\n}'\n"
           }
         ],
         "security": [
@@ -5148,7 +5309,7 @@
       "post": {
         "operationId": "PostDraftOrdersDraftOrderLineItemsItem",
         "summary": "Update a Line Item",
-        "description": "Updates a Line Item for a Draft Order",
+        "description": "Update a Line Item in a Draft Order",
         "x-authenticated": true,
         "parameters": [
           {
@@ -5186,12 +5347,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.updateLineItem(draft_order_id, line_id, {\n  quantity: 1\n})\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.updateLineItem(draftOrderId, lineId, {\n  quantity: 1\n})\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"quantity\": 1\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"quantity\": 1\n}'\n"
           }
         ],
         "security": [
@@ -5239,7 +5400,7 @@
       "delete": {
         "operationId": "DeleteDraftOrdersDraftOrderLineItemsItem",
         "summary": "Delete a Line Item",
-        "description": "Removes a Line Item from a Draft Order.",
+        "description": "Deletes a Line Item from a Draft Order.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -5255,7 +5416,7 @@
             "in": "path",
             "name": "line_id",
             "required": true,
-            "description": "The ID of the Draft Order.",
+            "description": "The ID of the line item.",
             "schema": {
               "type": "string"
             }
@@ -5268,12 +5429,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.removeLineItem(draft_order_id, item_id)\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.removeLineItem(draftOrderId, itemId)\n.then(({ draft_order }) => {\n  console.log(draft_order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -5321,16 +5482,16 @@
     },
     "/admin/draft-orders/{id}/pay": {
       "post": {
-        "summary": "Registers a Payment",
+        "summary": "Mark Paid",
         "operationId": "PostDraftOrdersDraftOrderRegisterPayment",
-        "description": "Registers a payment for a Draft Order.",
+        "description": "Capture the draft order's payment. This will also set the draft order's status to `completed` and create an Order from the draft order. The payment is captured through Medusa's system payment, which is manual payment that isn't integrated with any third-party payment provider. It is assumed that the payment capturing is handled manually by the admin.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The Draft Order id.",
+            "description": "The Draft Order ID.",
             "schema": {
               "type": "string"
             }
@@ -5343,12 +5504,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.markPaid(draft_order_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.draftOrders.markPaid(draftOrderId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/pay' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}/pay' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -5398,13 +5559,13 @@
       "get": {
         "operationId": "GetGiftCards",
         "summary": "List Gift Cards",
-        "description": "Retrieves a list of Gift Cards.",
+        "description": "Retrieve a list of Gift Cards. The gift cards can be filtered by fields such as `q`. The gift cards can also paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of items to skip before the results.",
+            "description": "The number of gift cards to skip when retrieving the gift cards.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -5413,7 +5574,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "Limit the number of items returned.",
+            "description": "Limit the number of gift cards returned.",
             "schema": {
               "type": "number",
               "default": "50"
@@ -5422,7 +5583,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "a search term to search by code or display ID",
+            "description": "a term to search gift cards' code or display ID",
             "schema": {
               "type": "string"
             }
@@ -5441,7 +5602,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/gift-cards' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/gift-cards' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -5489,7 +5650,7 @@
       "post": {
         "operationId": "PostGiftCards",
         "summary": "Create a Gift Card",
-        "description": "Creates a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region.",
+        "description": "Create a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -5512,7 +5673,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/gift-cards' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"region_id\": \"{region_id}\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/gift-cards' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"region_id\": \"{region_id}\"\n}'\n"
           }
         ],
         "security": [
@@ -5562,7 +5723,7 @@
       "get": {
         "operationId": "GetGiftCardsGiftCard",
         "summary": "Get a Gift Card",
-        "description": "Retrieves a Gift Card.",
+        "description": "Retrieve a Gift Card's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -5582,12 +5743,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.giftCards.retrieve(gift_card_id)\n.then(({ gift_card }) => {\n  console.log(gift_card.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.giftCards.retrieve(giftCardId)\n.then(({ gift_card }) => {\n  console.log(gift_card.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/gift-cards/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/gift-cards/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -5635,7 +5796,7 @@
       "post": {
         "operationId": "PostGiftCardsGiftCard",
         "summary": "Update a Gift Card",
-        "description": "Update a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region.",
+        "description": "Update a Gift Card's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -5664,12 +5825,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.giftCards.update(gift_card_id, {\n  region_id\n})\n.then(({ gift_card }) => {\n  console.log(gift_card.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.giftCards.update(giftCardId, {\n  region_id\n})\n.then(({ gift_card }) => {\n  console.log(gift_card.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/gift-cards/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"region_id\": \"{region_id}\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/gift-cards/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"region_id\": \"{region_id}\"\n}'\n"
           }
         ],
         "security": [
@@ -5717,7 +5878,7 @@
       "delete": {
         "operationId": "DeleteGiftCardsGiftCard",
         "summary": "Delete a Gift Card",
-        "description": "Deletes a Gift Card",
+        "description": "Delete a Gift Card. Once deleted, it can't be used by customers.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -5737,12 +5898,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.giftCards.delete(gift_card_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.giftCards.delete(giftCardId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/gift-cards/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/gift-cards/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -5792,13 +5953,13 @@
       "get": {
         "operationId": "GetInventoryItems",
         "summary": "List Inventory Items",
-        "description": "Lists inventory items with the ability to apply filters or search queries on them.",
+        "description": "Retrieve a list of inventory items. The inventory items can be filtered by fields such as `q` or `location_id`. The inventory items can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "offset",
-            "description": "How many inventory items to skip in the result.",
+            "description": "The number of inventory items to skip when retrieving the inventory items.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -5816,7 +5977,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in each returned inventory item.",
             "schema": {
               "type": "string"
             }
@@ -5824,7 +5985,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned inventory item.",
             "schema": {
               "type": "string"
             }
@@ -5832,7 +5993,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching product inventory items and their properties.",
+            "description": "term to search inventory item's sku, title, and description.",
             "schema": {
               "type": "string"
             }
@@ -5842,7 +6003,7 @@
             "name": "location_id",
             "style": "form",
             "explode": false,
-            "description": "Locations ids to search for.",
+            "description": "Filter by location IDs.",
             "schema": {
               "type": "array",
               "items": {
@@ -5853,15 +6014,29 @@
           {
             "in": "query",
             "name": "id",
-            "description": "id to search for.",
+            "style": "form",
+            "explode": false,
+            "description": "Filter by the inventory ID",
             "schema": {
-              "type": "string"
+              "oneOf": [
+                {
+                  "type": "string",
+                  "description": "inventory ID"
+                },
+                {
+                  "type": "array",
+                  "description": "an array of inventory IDs",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
             }
           },
           {
             "in": "query",
             "name": "sku",
-            "description": "sku to search for.",
+            "description": "Filter by SKU",
             "schema": {
               "type": "string"
             }
@@ -5869,7 +6044,7 @@
           {
             "in": "query",
             "name": "origin_country",
-            "description": "origin_country to search for.",
+            "description": "Filter by origin country",
             "schema": {
               "type": "string"
             }
@@ -5877,7 +6052,7 @@
           {
             "in": "query",
             "name": "mid_code",
-            "description": "mid_code to search for.",
+            "description": "Filter by MID code",
             "schema": {
               "type": "string"
             }
@@ -5885,7 +6060,7 @@
           {
             "in": "query",
             "name": "material",
-            "description": "material to search for.",
+            "description": "Filter by material",
             "schema": {
               "type": "string"
             }
@@ -5893,7 +6068,7 @@
           {
             "in": "query",
             "name": "hs_code",
-            "description": "hs_code to search for.",
+            "description": "Filter by HS Code",
             "schema": {
               "type": "string"
             }
@@ -5901,7 +6076,7 @@
           {
             "in": "query",
             "name": "weight",
-            "description": "weight to search for.",
+            "description": "Filter by weight",
             "schema": {
               "type": "string"
             }
@@ -5909,7 +6084,7 @@
           {
             "in": "query",
             "name": "length",
-            "description": "length to search for.",
+            "description": "Filter by length",
             "schema": {
               "type": "string"
             }
@@ -5917,7 +6092,7 @@
           {
             "in": "query",
             "name": "height",
-            "description": "height to search for.",
+            "description": "Filter by height",
             "schema": {
               "type": "string"
             }
@@ -5925,7 +6100,7 @@
           {
             "in": "query",
             "name": "width",
-            "description": "width to search for.",
+            "description": "Filter by width",
             "schema": {
               "type": "string"
             }
@@ -5933,7 +6108,7 @@
           {
             "in": "query",
             "name": "requires_shipping",
-            "description": "requires_shipping to search for.",
+            "description": "Filter by whether the item requires shipping",
             "schema": {
               "type": "string"
             }
@@ -5952,7 +6127,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/inventory-items' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/inventory-items' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -6000,13 +6175,13 @@
       "post": {
         "operationId": "PostInventoryItems",
         "summary": "Create an Inventory Item",
-        "description": "Creates an Inventory Item.",
+        "description": "Create an Inventory Item.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned inventory item.",
             "schema": {
               "type": "string"
             }
@@ -6014,7 +6189,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned inventory item.",
             "schema": {
               "type": "string"
             }
@@ -6037,12 +6212,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.inventoryItems.create({\n  variant_id: 'variant_123',\n})\n.then(({ inventory_item }) => {\n  console.log(inventory_item.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.inventoryItems.create({\n  variant_id: \"variant_123\",\n})\n.then(({ inventory_item }) => {\n  console.log(inventory_item.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/inventory-items' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"variant_id\": \"variant_123\",\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/inventory-items' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"variant_id\": \"variant_123\",\n}'\n"
           }
         ],
         "security": [
@@ -6092,7 +6267,7 @@
       "get": {
         "operationId": "GetInventoryItemsInventoryItem",
         "summary": "Get an Inventory Item",
-        "description": "Retrieves an Inventory Item.",
+        "description": "Retrieve an Inventory Item's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -6107,7 +6282,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned inventory item.",
             "schema": {
               "type": "string"
             }
@@ -6115,7 +6290,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned inventory item.",
             "schema": {
               "type": "string"
             }
@@ -6134,7 +6309,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/inventory-items/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/inventory-items/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -6182,7 +6357,7 @@
       "post": {
         "operationId": "PostInventoryItemsInventoryItem",
         "summary": "Update an Inventory Item",
-        "description": "Updates an Inventory Item.",
+        "description": "Update an Inventory Item's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -6197,7 +6372,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned inventory level.",
             "schema": {
               "type": "string"
             }
@@ -6205,7 +6380,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned inventory level.",
             "schema": {
               "type": "string"
             }
@@ -6233,7 +6408,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/inventory-items/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"origin_country\": \"US\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/inventory-items/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"origin_country\": \"US\"\n}'\n"
           }
         ],
         "security": [
@@ -6281,7 +6456,7 @@
       "delete": {
         "operationId": "DeleteInventoryItemsInventoryItem",
         "summary": "Delete an Inventory Item",
-        "description": "Delete an Inventory Item",
+        "description": "Delete an Inventory Item. This does not delete the associated product variant.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -6306,7 +6481,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/inventory-items/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/inventory-items/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -6340,15 +6515,15 @@
     "/admin/inventory-items/{id}/location-levels": {
       "get": {
         "operationId": "GetInventoryItemsInventoryItemLocationLevels",
-        "summary": "List Inventory Levels",
-        "description": "Lists inventory levels of an inventory item.",
+        "summary": "List Inventory Level",
+        "description": "Retrieve a list of inventory levels of an inventory item. The inventory levels can be filtered by fields such as `location_id`. The inventory levels can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Inventory Item.",
+            "description": "The ID of the Inventory Item the locations are associated with.",
             "schema": {
               "type": "string"
             }
@@ -6358,7 +6533,7 @@
             "name": "location_id",
             "style": "form",
             "explode": false,
-            "description": "Locations ids to search for.",
+            "description": "Filter by location IDs.",
             "schema": {
               "type": "array",
               "items": {
@@ -6369,7 +6544,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned inventory levels.",
             "schema": {
               "type": "string"
             }
@@ -6377,7 +6552,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned inventory levels.",
             "schema": {
               "type": "string"
             }
@@ -6396,7 +6571,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -6444,7 +6619,7 @@
       "post": {
         "operationId": "PostInventoryItemsInventoryItemLocationLevels",
         "summary": "Create an Inventory Level",
-        "description": "Creates an Inventory Level for a given Inventory Item.",
+        "description": "Create an Inventory Level for a given Inventory Item.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -6459,7 +6634,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned inventory item.",
             "schema": {
               "type": "string"
             }
@@ -6467,7 +6642,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned inventory item.",
             "schema": {
               "type": "string"
             }
@@ -6490,12 +6665,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.inventoryItems.createLocationLevel(inventoryItemId, {\n  location_id: 'sloc_123',\n  stocked_quantity: 10,\n})\n.then(({ inventory_item }) => {\n  console.log(inventory_item.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.inventoryItems.createLocationLevel(inventoryItemId, {\n  location_id: \"sloc_123\",\n  stocked_quantity: 10,\n})\n.then(({ inventory_item }) => {\n  console.log(inventory_item.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"location_id\": \"sloc_123\",\n    \"stocked_quantity\": 10\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"location_id\": \"sloc_123\",\n    \"stocked_quantity\": 10\n}'\n"
           }
         ],
         "security": [
@@ -6545,14 +6720,14 @@
       "post": {
         "operationId": "PostInventoryItemsInventoryItemLocationLevelsLocationLevel",
         "summary": "Update an Inventory Level",
-        "description": "Updates an Inventory Level for a given Inventory Item.",
+        "description": "Update an Inventory Level's details for a given Inventory Item.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Inventory Item.",
+            "description": "The ID of the Inventory Item that the location is associated with.",
             "schema": {
               "type": "string"
             }
@@ -6561,7 +6736,7 @@
             "in": "path",
             "name": "location_id",
             "required": true,
-            "description": "The ID of the Location.",
+            "description": "The ID of the Location to update.",
             "schema": {
               "type": "string"
             }
@@ -6569,7 +6744,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned inventory level.",
             "schema": {
               "type": "string"
             }
@@ -6577,7 +6752,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned inventory level.",
             "schema": {
               "type": "string"
             }
@@ -6605,7 +6780,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"stocked_quantity\": 15\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"stocked_quantity\": 15\n}'\n"
           }
         ],
         "security": [
@@ -6687,7 +6862,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -6737,7 +6912,7 @@
       "get": {
         "operationId": "GetInvites",
         "summary": "Lists Invites",
-        "description": "Lists all Invites",
+        "description": "Retrieve a list of invites.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "list"
@@ -6751,7 +6926,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/invites' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/invites' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -6799,7 +6974,7 @@
       "post": {
         "operationId": "PostInvites",
         "summary": "Create an Invite",
-        "description": "Creates an Invite and triggers an 'invite' created event",
+        "description": "Create an Invite. This will generate a token associated with the invite and trigger an `invite.created` event. If you have a Notification Provider installed that handles this event, a notification should be sent to the email associated with the invite to allow them to accept the invite.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -6822,7 +6997,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/invites' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"user\": \"user@example.com\",\n    \"role\": \"admin\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/invites' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"user\": \"user@example.com\",\n    \"role\": \"admin\"\n}'\n"
           }
         ],
         "security": [
@@ -6865,7 +7040,7 @@
       "post": {
         "operationId": "PostInvitesInviteAccept",
         "summary": "Accept an Invite",
-        "description": "Accepts an Invite and creates a corresponding user",
+        "description": "Accept an Invite. This will also delete the invite and create a new user that can log in and perform admin functionalities. The user will have the email associated with the invite, and the password provided in the request body.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -6882,12 +7057,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.invites.accept({\n  token,\n  user: {\n    first_name: 'Brigitte',\n    last_name: 'Collier',\n    password: 'supersecret'\n  }\n})\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // an error occurred\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.invites.accept({\n  token,\n  user: {\n    first_name: \"Brigitte\",\n    last_name: \"Collier\",\n    password: \"supersecret\"\n  }\n})\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // an error occurred\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/invites/accept' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"token\": \"{token}\",\n    \"user\": {\n      \"first_name\": \"Brigitte\",\n      \"last_name\": \"Collier\",\n      \"password\": \"supersecret\"\n    }\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/invites/accept' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"token\": \"{token}\",\n    \"user\": {\n      \"first_name\": \"Brigitte\",\n      \"last_name\": \"Collier\",\n      \"password\": \"supersecret\"\n    }\n}'\n"
           }
         ],
         "security": [
@@ -6930,7 +7105,7 @@
       "delete": {
         "operationId": "DeleteInvitesInvite",
         "summary": "Delete an Invite",
-        "description": "Deletes an Invite",
+        "description": "Delete an Invite. Only invites that weren't accepted can be deleted.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -6950,12 +7125,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.invites.delete(invite_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.invites.delete(inviteId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/invites/{invite_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/invites/{invite_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -7005,7 +7180,7 @@
       "post": {
         "operationId": "PostInvitesInviteResend",
         "summary": "Resend an Invite",
-        "description": "Resends an Invite by triggering the 'invite' created event again",
+        "description": "Resend an Invite. This renews the expiry date by 7 days and generates a new token for the invite. It also triggers the `invite.created` event, so if you have a Notification Provider installed that handles this event, a notification should be sent to the email associated with the invite to allow them to accept the invite.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -7025,12 +7200,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.invites.resend(invite_id)\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // an error occurred\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.invites.resend(inviteId)\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // an error occurred\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/invites/{invite_id}/resend' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/invites/{invite_id}/resend' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -7074,12 +7249,12 @@
         "operationId": "GetNotes",
         "summary": "List Notes",
         "x-authenticated": true,
-        "description": "Retrieves a list of notes",
+        "description": "Retrieve a list of notes. The notes can be filtered by fields such as `resource_id`. The notes can also be paginated.",
         "parameters": [
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of notes to get",
+            "description": "Limit the number of notes returned.",
             "schema": {
               "type": "number",
               "default": "50"
@@ -7088,7 +7263,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The offset at which to get notes",
+            "description": "The number of notes to skip when retrieving the notes.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -7097,7 +7272,7 @@
           {
             "in": "query",
             "name": "resource_id",
-            "description": "The ID which the notes belongs to",
+            "description": "Filter by resource ID",
             "schema": {
               "type": "string"
             }
@@ -7116,7 +7291,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/notes' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/notes' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -7163,8 +7338,8 @@
       },
       "post": {
         "operationId": "PostNotes",
-        "summary": "Creates a Note",
-        "description": "Creates a Note which can be associated with any resource as required.",
+        "summary": "Create a Note",
+        "description": "Create a Note which can be associated with any resource.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -7182,12 +7357,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notes.create({\n  resource_id,\n  resource_type: 'order',\n  value: 'We delivered this order'\n})\n.then(({ note }) => {\n  console.log(note.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notes.create({\n  resource_id,\n  resource_type: \"order\",\n  value: \"We delivered this order\"\n})\n.then(({ note }) => {\n  console.log(note.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/notes' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"resource_id\": \"{resource_id}\",\n    \"resource_type\": \"order\",\n    \"value\": \"We delivered this order\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/notes' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"resource_id\": \"{resource_id}\",\n    \"resource_type\": \"order\",\n    \"value\": \"We delivered this order\"\n}'\n"
           }
         ],
         "security": [
@@ -7237,14 +7412,14 @@
       "get": {
         "operationId": "GetNotesNote",
         "summary": "Get a Note",
-        "description": "Retrieves a single note using its id",
+        "description": "Retrieve a note's details.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the note to retrieve.",
+            "description": "The ID of the note.",
             "schema": {
               "type": "string"
             }
@@ -7257,12 +7432,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notes.retrieve(note_id)\n.then(({ note }) => {\n  console.log(note.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notes.retrieve(noteId)\n.then(({ note }) => {\n  console.log(note.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/notes/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/notes/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -7311,13 +7486,13 @@
         "operationId": "PostNotesNote",
         "summary": "Update a Note",
         "x-authenticated": true,
-        "description": "Updates a Note associated with some resource",
+        "description": "Update a Note's details.'",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Note to update",
+            "description": "The ID of the Note",
             "schema": {
               "type": "string"
             }
@@ -7339,12 +7514,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notes.update(note_id, {\n value: 'We delivered this order'\n})\n.then(({ note }) => {\n  console.log(note.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notes.update(noteId, {\n value: \"We delivered this order\"\n})\n.then(({ note }) => {\n  console.log(note.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/notes/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"value\": \"We delivered this order\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/notes/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"value\": \"We delivered this order\"\n}'\n"
           }
         ],
         "security": [
@@ -7392,7 +7567,7 @@
       "delete": {
         "operationId": "DeleteNotesNote",
         "summary": "Delete a Note",
-        "description": "Deletes a Note.",
+        "description": "Delete a Note.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -7412,12 +7587,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notes.delete(note_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notes.delete(noteId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/notes/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/notes/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -7467,13 +7642,13 @@
       "get": {
         "operationId": "GetNotifications",
         "summary": "List Notifications",
-        "description": "Retrieves a list of Notifications.",
+        "description": "Retrieve a list of notifications. The notifications can be filtered by fields such as `event_name` or `resource_type`. The notifications can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of notifications to skip before starting to collect the notifications set",
+            "description": "The number of inventory items to skip when retrieving the inventory items.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -7482,7 +7657,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of notifications to return",
+            "description": "Limit the number of notifications returned.",
             "schema": {
               "type": "integer",
               "default": 50
@@ -7491,7 +7666,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated fields to include in the result set",
+            "description": "Comma-separated fields that should be included in each returned notification.",
             "schema": {
               "type": "string"
             }
@@ -7499,7 +7674,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated fields to populate",
+            "description": "Comma-separated relations that should be expanded in each returned notification.",
             "schema": {
               "type": "string"
             }
@@ -7507,7 +7682,7 @@
           {
             "in": "query",
             "name": "event_name",
-            "description": "The name of the event that the notification was sent for.",
+            "description": "Filter by the name of the event that triggered sending this notification.",
             "schema": {
               "type": "string"
             }
@@ -7515,7 +7690,7 @@
           {
             "in": "query",
             "name": "resource_type",
-            "description": "The type of resource that the Notification refers to.",
+            "description": "Filter by the resource type.",
             "schema": {
               "type": "string"
             }
@@ -7523,7 +7698,7 @@
           {
             "in": "query",
             "name": "resource_id",
-            "description": "The ID of the resource that the Notification refers to.",
+            "description": "Filter by the resource ID.",
             "schema": {
               "type": "string"
             }
@@ -7531,7 +7706,7 @@
           {
             "in": "query",
             "name": "to",
-            "description": "The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id",
+            "description": "Filter by the address that the Notification was sent to. This will usually be an email address, but it can also represent other addresses such as a chat bot user id.",
             "schema": {
               "type": "string"
             }
@@ -7558,7 +7733,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/notifications' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/notifications' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -7608,7 +7783,7 @@
       "post": {
         "operationId": "PostNotificationsNotificationResend",
         "summary": "Resend Notification",
-        "description": "Resends a previously sent notifications, with the same data but optionally to a different address",
+        "description": "Resend a previously sent notifications, with the same data but optionally to a different address.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -7637,12 +7812,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notifications.resend(notification_id)\n.then(({ notification }) => {\n  console.log(notification.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.notifications.resend(notificationId)\n.then(({ notification }) => {\n  console.log(notification.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/notifications/{id}/resend' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/notifications/{id}/resend' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -7691,14 +7866,14 @@
     "/admin/order-edits": {
       "get": {
         "operationId": "GetOrderEdits",
-        "summary": "List OrderEdits",
-        "description": "List OrderEdits.",
+        "summary": "List Order Edits",
+        "description": "Retrieve a list of order edits. The order edits can be filtered by fields such as `q` or `order_id`. The order edits can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching order edit internal note.",
+            "description": "term to search order edits' internal note.",
             "schema": {
               "type": "string"
             }
@@ -7706,7 +7881,7 @@
           {
             "in": "query",
             "name": "order_id",
-            "description": "List order edits by order id.",
+            "description": "Filter by order ID",
             "schema": {
               "type": "string"
             }
@@ -7714,7 +7889,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of items in the response",
+            "description": "Limit the number of order edits returned.",
             "schema": {
               "type": "number",
               "default": "20"
@@ -7723,7 +7898,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The offset of items in response",
+            "description": "The number of order edits to skip when retrieving the order edits.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -7732,7 +7907,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in each returned order edit.",
             "schema": {
               "type": "string"
             }
@@ -7740,7 +7915,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in each returned order edit.",
             "schema": {
               "type": "string"
             }
@@ -7759,7 +7934,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/order-edits' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/order-edits' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -7807,7 +7982,7 @@
       "post": {
         "operationId": "PostOrderEdits",
         "summary": "Create an OrderEdit",
-        "description": "Creates an OrderEdit.",
+        "description": "Create an Order Edit.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -7825,12 +8000,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.create({ order_id })\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.create({ orderId })\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/order-edits' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{ \"order_id\": \"my_order_id\", \"internal_note\": \"my_optional_note\" }'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/order-edits' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{ \"order_id\": \"my_order_id\", \"internal_note\": \"my_optional_note\" }'\n"
           }
         ],
         "security": [
@@ -7879,8 +8054,8 @@
     "/admin/order-edits/{id}": {
       "get": {
         "operationId": "GetOrderEditsOrderEdit",
-        "summary": "Get an OrderEdit",
-        "description": "Retrieves a OrderEdit.",
+        "summary": "Get an Order Edit",
+        "description": "Retrieve an Order Edit's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -7895,7 +8070,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in each returned order edit.",
             "schema": {
               "type": "string"
             }
@@ -7903,7 +8078,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned order edit.",
             "schema": {
               "type": "string"
             }
@@ -7922,7 +8097,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/order-edits/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/order-edits/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -7969,8 +8144,8 @@
       },
       "post": {
         "operationId": "PostOrderEditsOrderEdit",
-        "summary": "Update an OrderEdit",
-        "description": "Updates a OrderEdit.",
+        "summary": "Update an Order Edit",
+        "description": "Updates an Order Edit's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -7999,12 +8174,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.update(order_edit_id, {\n  internal_note: \"internal reason XY\"\n})\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.update(orderEditId, {\n  internal_note: \"internal reason XY\"\n})\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"internal_note\": \"internal reason XY\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/order-edits/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"internal_note\": \"internal reason XY\"\n}'\n"
           }
         ],
         "security": [
@@ -8052,7 +8227,7 @@
       "delete": {
         "operationId": "DeleteOrderEditsOrderEdit",
         "summary": "Delete an Order Edit",
-        "description": "Delete an Order Edit",
+        "description": "Delete an Order Edit. Only order edits that have the status `created` can be deleted.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -8072,12 +8247,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.delete(order_edit_id)\n  .then(({ id, object, deleted }) => {\n    console.log(id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.delete(orderEditId)\n  .then(({ id, object, deleted }) => {\n    console.log(id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/order-edits/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/order-edits/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -8111,8 +8286,8 @@
     "/admin/order-edits/{id}/cancel": {
       "post": {
         "operationId": "PostOrderEditsOrderEditCancel",
-        "summary": "Cancel an OrderEdit",
-        "description": "Cancels an OrderEdit.",
+        "summary": "Cancel an Order Edit",
+        "description": "Cancel an OrderEdit.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -8132,12 +8307,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.cancel(order_edit_id)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.cancel(orderEditId)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/cancel' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/cancel' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -8181,14 +8356,14 @@
       "delete": {
         "operationId": "DeleteOrderEditsOrderEditItemChange",
         "summary": "Delete a Line Item Change",
-        "description": "Deletes an Order Edit Item Change",
+        "description": "Delete a line item change that indicates the addition, deletion, or update of a line item in the original order.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order Edit to delete.",
+            "description": "The ID of the Order Edit.",
             "schema": {
               "type": "string"
             }
@@ -8197,7 +8372,7 @@
             "in": "path",
             "name": "change_id",
             "required": true,
-            "description": "The ID of the Order Edit Item Change to delete.",
+            "description": "The ID of the Line Item Change to delete.",
             "schema": {
               "type": "string"
             }
@@ -8210,12 +8385,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.deleteItemChange(order_edit_id, item_change_id)\n  .then(({ id, object, deleted }) => {\n    console.log(id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.deleteItemChange(orderEdit_id, itemChangeId)\n  .then(({ id, object, deleted }) => {\n    console.log(id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/order-edits/{id}/changes/{change_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/order-edits/{id}/changes/{change_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -8249,8 +8424,8 @@
     "/admin/order-edits/{id}/confirm": {
       "post": {
         "operationId": "PostOrderEditsOrderEditConfirm",
-        "summary": "Confirms an OrderEdit",
-        "description": "Confirms an OrderEdit.",
+        "summary": "Confirm an OrderEdit",
+        "description": "Confirm an Order Edit. This will reflect the changes in the order edit on the associated order.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -8270,12 +8445,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.confirm(order_edit_id)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.confirm(orderEditId)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/confirm' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/confirm' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -8319,7 +8494,7 @@
       "post": {
         "operationId": "PostOrderEditsEditLineItems",
         "summary": "Add a Line Item",
-        "description": "Create an OrderEdit LineItem.",
+        "description": "Create a line item change in the order edit that indicates adding an item in the original order. The item will not be added to the original order until the order edit is confirmed.",
         "parameters": [
           {
             "in": "path",
@@ -8348,12 +8523,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.addLineItem(order_edit_id, {\n  variant_id,\n  quantity\n})\n.then(({ order_edit }) => {\n   console.log(order_edit.id)\n})\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.addLineItem(orderEditId, {\n  variant_id,\n  quantity\n})\n.then(({ order_edit }) => {\n   console.log(order_edit.id)\n})\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{ \"variant_id\": \"variant_01G1G5V2MRX2V3PVSR2WXYPFB6\", \"quantity\": 3 }'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/items' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{ \"variant_id\": \"variant_01G1G5V2MRX2V3PVSR2WXYPFB6\", \"quantity\": 3 }'\n"
           }
         ],
         "security": [
@@ -8403,14 +8578,14 @@
       "post": {
         "operationId": "PostOrderEditsEditLineItemsLineItem",
         "summary": "Upsert Line Item Change",
-        "description": "Create or update the order edit change holding the line item changes",
+        "description": "Create or update a line item change in the order edit that indicates addition, deletion, or update of a line item into an original order. Line item changes are only reflected on the original order after the order edit is confirmed.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order Edit to update.",
+            "description": "The ID of the Order Edit.",
             "schema": {
               "type": "string"
             }
@@ -8419,7 +8594,7 @@
             "in": "path",
             "name": "item_id",
             "required": true,
-            "description": "The ID of the order edit item to update.",
+            "description": "The ID of the line item in the original order.",
             "schema": {
               "type": "string"
             }
@@ -8441,12 +8616,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.updateLineItem(order_edit_id, line_item_id, {\n    quantity: 5\n  })\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.updateLineItem(orderEditId, lineItemId, {\n    quantity: 5\n  })\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{ \"quantity\": 5 }'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{ \"quantity\": 5 }'\n"
           }
         ],
         "security": [
@@ -8493,15 +8668,15 @@
       },
       "delete": {
         "operationId": "DeleteOrderEditsOrderEditLineItemsLineItem",
-        "summary": "Delete a Line Item",
-        "description": "Delete line items from an order edit and create change item",
+        "summary": "Delete Line Item",
+        "description": "Create a line item change in the order edit that indicates deleting an item in the original order. The item in the original order will not be deleted until the order edit is confirmed.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order Edit to delete from.",
+            "description": "The ID of the Order Edit.",
             "schema": {
               "type": "string"
             }
@@ -8510,7 +8685,7 @@
             "in": "path",
             "name": "item_id",
             "required": true,
-            "description": "The ID of the order edit item to delete from order.",
+            "description": "The ID of line item in the original order.",
             "schema": {
               "type": "string"
             }
@@ -8523,12 +8698,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.removeLineItem(order_edit_id, line_item_id)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.removeLineItem(orderEditId, lineItemId)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -8578,14 +8753,14 @@
       "post": {
         "operationId": "PostOrderEditsOrderEditRequest",
         "summary": "Request Confirmation",
-        "description": "Request customer confirmation of an Order Edit",
+        "description": "Request customer confirmation of an Order Edit. This would emit the event `order-edit.requested` which Notification Providers listen to and send a notification to the customer about the order edit.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order Edit to request confirmation from.",
+            "description": "The ID of the Order Edit.",
             "schema": {
               "type": "string"
             }
@@ -8598,12 +8773,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.requestConfirmation(order_edit_id)\n  .then({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orderEdits.requestConfirmation(orderEditId)\n  .then({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/request' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/request' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -8647,13 +8822,13 @@
       "get": {
         "operationId": "GetOrders",
         "summary": "List Orders",
-        "description": "Retrieves a list of Orders",
+        "description": "Retrieve a list of Orders. The orders can be filtered by fields such as `status` or `display_id`. The order can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching orders by shipping address first name, orders' email, and orders' display ID",
+            "description": "term to search orders' shipping address, first name, email, and display ID",
             "schema": {
               "type": "string"
             }
@@ -8661,7 +8836,7 @@
           {
             "in": "query",
             "name": "id",
-            "description": "ID of the order to search for.",
+            "description": "Filter by ID.",
             "schema": {
               "type": "string"
             }
@@ -8671,7 +8846,7 @@
             "name": "status",
             "style": "form",
             "explode": false,
-            "description": "Status to search for",
+            "description": "Filter by status",
             "schema": {
               "type": "array",
               "items": {
@@ -8691,7 +8866,7 @@
             "name": "fulfillment_status",
             "style": "form",
             "explode": false,
-            "description": "Fulfillment status to search for.",
+            "description": "Filter by fulfillment status",
             "schema": {
               "type": "array",
               "items": {
@@ -8715,7 +8890,7 @@
             "name": "payment_status",
             "style": "form",
             "explode": false,
-            "description": "Payment status to search for.",
+            "description": "Filter by payment status",
             "schema": {
               "type": "array",
               "items": {
@@ -8735,7 +8910,7 @@
           {
             "in": "query",
             "name": "display_id",
-            "description": "Display ID to search for.",
+            "description": "Filter by display ID",
             "schema": {
               "type": "string"
             }
@@ -8743,7 +8918,7 @@
           {
             "in": "query",
             "name": "cart_id",
-            "description": "to search for.",
+            "description": "Filter by cart ID",
             "schema": {
               "type": "string"
             }
@@ -8751,7 +8926,7 @@
           {
             "in": "query",
             "name": "customer_id",
-            "description": "to search for.",
+            "description": "Filter by customer ID",
             "schema": {
               "type": "string"
             }
@@ -8759,7 +8934,7 @@
           {
             "in": "query",
             "name": "email",
-            "description": "to search for.",
+            "description": "Filter by email",
             "schema": {
               "type": "string"
             }
@@ -8769,7 +8944,7 @@
             "name": "region_id",
             "style": "form",
             "explode": false,
-            "description": "Regions to search orders by",
+            "description": "Filter by region IDs.",
             "schema": {
               "oneOf": [
                 {
@@ -8791,7 +8966,7 @@
             "name": "currency_code",
             "style": "form",
             "explode": false,
-            "description": "Currency code to search for",
+            "description": "Filter by currency codes.",
             "schema": {
               "type": "string",
               "externalDocs": {
@@ -8803,7 +8978,7 @@
           {
             "in": "query",
             "name": "tax_rate",
-            "description": "to search for.",
+            "description": "Filter by tax rate.",
             "schema": {
               "type": "string"
             }
@@ -8811,7 +8986,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting orders were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -8841,7 +9016,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting orders were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -8871,7 +9046,7 @@
           {
             "in": "query",
             "name": "canceled_at",
-            "description": "Date comparison for when resulting orders were canceled.",
+            "description": "Filter by a cancelation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -8903,7 +9078,7 @@
             "name": "sales_channel_id",
             "style": "form",
             "explode": false,
-            "description": "Filter by Sales Channels",
+            "description": "Filter by Sales Channel IDs",
             "schema": {
               "type": "array",
               "items": {
@@ -8915,7 +9090,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many orders to skip before the results.",
+            "description": "The number of orders to skip when retrieving the orders.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -8933,7 +9108,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each order of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -8941,7 +9116,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each order of the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -8960,7 +9135,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/orders' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/orders' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -9010,7 +9185,7 @@
       "get": {
         "operationId": "GetOrdersOrder",
         "summary": "Get an Order",
-        "description": "Retrieves an Order",
+        "description": "Retrieve an Order's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -9025,7 +9200,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9033,7 +9208,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9047,12 +9222,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.retrieve(order_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.retrieve(orderId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/orders/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/orders/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -9100,7 +9275,7 @@
       "post": {
         "operationId": "PostOrdersOrder",
         "summary": "Update an Order",
-        "description": "Updates and order",
+        "description": "Update and order's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -9115,7 +9290,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9123,7 +9298,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9146,12 +9321,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.update(order_id, {\n  email: 'user@example.com'\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.update(orderId, {\n  email: \"user@example.com\"\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/adasda' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/adasda' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
           }
         ],
         "security": [
@@ -9201,7 +9376,7 @@
       "post": {
         "operationId": "PostOrdersOrderArchive",
         "summary": "Archive Order",
-        "description": "Archives the order with the given id.",
+        "description": "Archive an order and change its status.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -9216,7 +9391,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9224,7 +9399,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9238,12 +9413,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.archive(order_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.archive(orderId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/archive' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/archive' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -9293,7 +9468,7 @@
       "post": {
         "operationId": "PostOrdersOrderCancel",
         "summary": "Cancel an Order",
-        "description": "Registers an Order as canceled. This triggers a flow that will cancel any created Fulfillments and Payments, may fail if the Payment or Fulfillment Provider is unable to cancel the Payment/Fulfillment.",
+        "description": "Cancel an order and change its status. This will also cancel any associated Fulfillments and Payments, and it may fail if the Payment or Fulfillment Provider is unable to cancel the Payment/Fulfillment.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -9308,7 +9483,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9316,7 +9491,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9330,12 +9505,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancel(order_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancel(orderId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/cancel' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/cancel' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -9384,8 +9559,8 @@
     "/admin/orders/{id}/capture": {
       "post": {
         "operationId": "PostOrdersOrderCapture",
-        "summary": "Capture Order's Payment",
-        "description": "Captures all the Payments associated with an Order.",
+        "summary": "Capture an Order's Payments",
+        "description": "Capture all the Payments associated with an Order. The payment of canceled orders can't be captured.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -9400,7 +9575,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9408,7 +9583,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9422,12 +9597,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.capturePayment(order_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.capturePayment(orderId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/capture' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/capture' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -9477,7 +9652,11 @@
       "post": {
         "operationId": "PostOrdersOrderClaims",
         "summary": "Create a Claim",
-        "description": "Creates a Claim.",
+        "description": "Create a Claim for an order. If a return shipping method is specified, a return will also be created and associated with the claim. If the claim's type is `refund`, the refund is processed as well.",
+        "externalDocs": {
+          "description": "How are claims created",
+          "url": "https://docs.medusajs.com/modules/orders/claims#how-are-claims-created"
+        },
         "x-authenticated": true,
         "parameters": [
           {
@@ -9492,7 +9671,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9500,7 +9679,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9523,12 +9702,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.createClaim(order_id, {\n  type: 'refund',\n  claim_items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.createClaim(orderId, {\n  type: 'refund',\n  claim_items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"type\": \"refund\",\n    \"claim_items\": [\n      {\n        \"item_id\": \"asdsd\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"type\": \"refund\",\n    \"claim_items\": [\n      {\n        \"item_id\": \"asdsd\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -9578,14 +9757,14 @@
       "post": {
         "operationId": "PostOrdersOrderClaimsClaim",
         "summary": "Update a Claim",
-        "description": "Updates a Claim.",
+        "description": "Update a Claim's details.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order.",
+            "description": "The ID of the Order associated with the claim.",
             "schema": {
               "type": "string"
             }
@@ -9602,7 +9781,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9610,7 +9789,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9633,12 +9812,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.updateClaim(order_id, claim_id, {\n  no_notification: true\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.updateClaim(orderId, claimId, {\n  no_notification: true\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"no_notification\": true\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"no_notification\": true\n}'\n"
           }
         ],
         "security": [
@@ -9688,14 +9867,18 @@
       "post": {
         "operationId": "PostOrdersClaimCancel",
         "summary": "Cancel a Claim",
-        "description": "Cancels a Claim",
+        "description": "Cancel a Claim and change its status. A claim can't be canceled if it has a refund, if its fulfillments haven't been canceled, of if its associated return hasn't been canceled.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Canceling a claim",
+          "url": "https://docs.medusajs.com/modules/orders/claims#cancel-a-claim"
+        },
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order.",
+            "description": "The ID of the order the claim is associated with.",
             "schema": {
               "type": "string"
             }
@@ -9712,7 +9895,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9720,7 +9903,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9734,12 +9917,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelClaim(order_id, claim_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelClaim(orderId, claimId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/cancel' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/cancel' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -9788,15 +9971,19 @@
     "/admin/orders/{id}/claims/{claim_id}/fulfillments": {
       "post": {
         "operationId": "PostOrdersOrderClaimsClaimFulfillments",
-        "summary": "Create Claim Fulfillment",
-        "description": "Creates a Fulfillment for a Claim.",
+        "summary": "Create a Claim Fulfillment",
+        "description": "Create a Fulfillment for a Claim.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Fulfill a claim",
+          "url": "https://docs.medusajs.com/modules/orders/claims#fulfill-a-claim"
+        },
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order.",
+            "description": "The ID of the Order the claim is associated with.",
             "schema": {
               "type": "string"
             }
@@ -9813,7 +10000,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9821,7 +10008,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9844,12 +10031,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.fulfillClaim(order_id, claim_id, {\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.fulfillClaim(orderId, claimId, {\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -9898,15 +10085,15 @@
     "/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel": {
       "post": {
         "operationId": "PostOrdersClaimFulfillmentsCancel",
-        "summary": "Cancel Claim Fulfillment",
-        "description": "Registers a claim's fulfillment as canceled.",
+        "summary": "Cancel Claim's Fulfillment",
+        "description": "Cancel a claim's fulfillment and change its status.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order which the Claim relates to.",
+            "description": "The ID of the order the claim is associated with.",
             "schema": {
               "type": "string"
             }
@@ -9915,7 +10102,7 @@
             "in": "path",
             "name": "claim_id",
             "required": true,
-            "description": "The ID of the Claim which the Fulfillment relates to.",
+            "description": "The ID of the claim.",
             "schema": {
               "type": "string"
             }
@@ -9924,7 +10111,7 @@
             "in": "path",
             "name": "fulfillment_id",
             "required": true,
-            "description": "The ID of the Fulfillment.",
+            "description": "The ID of the fulfillment.",
             "schema": {
               "type": "string"
             }
@@ -9932,7 +10119,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9940,7 +10127,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -9954,12 +10141,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelClaimFulfillment(order_id, claim_id, fulfillment_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelClaimFulfillment(orderId, claimId, fulfillmentId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -10008,15 +10195,19 @@
     "/admin/orders/{id}/claims/{claim_id}/shipments": {
       "post": {
         "operationId": "PostOrdersOrderClaimsClaimShipments",
-        "summary": "Create Claim Shipment",
-        "description": "Registers a Claim Fulfillment as shipped.",
+        "summary": "Ship a Claim's Fulfillment",
+        "description": "Mark a claim's fulfillment as shipped. This changes the claim's fulfillment status to either `shipped` or `partially_shipped`, depending on whether all the items were shipped.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Fulfill a claim",
+          "url": "https://docs.medusajs.com/modules/orders/claims#fulfill-a-claim"
+        },
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order.",
+            "description": "The ID of the Order the claim is associated with.",
             "schema": {
               "type": "string"
             }
@@ -10033,7 +10224,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10041,7 +10232,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10064,12 +10255,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.createClaimShipment(order_id, claim_id, {\n  fulfillment_id\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.createClaimShipment(orderId, claimId, {\n  fulfillment_id\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/shipments' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"fulfillment_id\": \"{fulfillment_id}\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/shipments' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"fulfillment_id\": \"{fulfillment_id}\"\n}'\n"
           }
         ],
         "security": [
@@ -10119,7 +10310,7 @@
       "post": {
         "operationId": "PostOrdersOrderComplete",
         "summary": "Complete an Order",
-        "description": "Completes an Order",
+        "description": "Complete an Order and change its status. A canceled order can't be completed.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -10134,7 +10325,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10142,7 +10333,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10156,12 +10347,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.complete(order_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.complete(orderId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/complete' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/complete' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -10211,8 +10402,12 @@
       "post": {
         "operationId": "PostOrdersOrderFulfillments",
         "summary": "Create a Fulfillment",
-        "description": "Creates a Fulfillment of an Order - will notify Fulfillment Providers to prepare a shipment.",
+        "description": "Create a Fulfillment of an Order using the fulfillment provider.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Fulfillments of orders",
+          "url": "https://docs.medusajs.com/modules/orders/#fulfillments-in-orders"
+        },
         "parameters": [
           {
             "in": "path",
@@ -10226,7 +10421,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10234,7 +10429,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10257,12 +10452,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.createFulfillment(order_id, {\n  items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.createFulfillment(orderId, {\n  items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/fulfillment' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"items\": [\n      {\n        \"item_id\": \"{item_id}\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/fulfillment' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"items\": [\n      {\n        \"item_id\": \"{item_id}\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -10311,15 +10506,15 @@
     "/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel": {
       "post": {
         "operationId": "PostOrdersOrderFulfillmentsCancel",
-        "summary": "Cancels a Fulfilmment",
-        "description": "Registers a Fulfillment as canceled.",
+        "summary": "Cancel a Fulfilmment",
+        "description": "Cancel an order's fulfillment and change its status.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order which the Fulfillment relates to.",
+            "description": "The ID of the Order.",
             "schema": {
               "type": "string"
             }
@@ -10328,7 +10523,7 @@
             "in": "path",
             "name": "fulfillment_id",
             "required": true,
-            "description": "The ID of the Fulfillment",
+            "description": "The ID of the Fulfillment.",
             "schema": {
               "type": "string"
             }
@@ -10336,7 +10531,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10344,7 +10539,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10358,12 +10553,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelFulfillment(order_id, fulfillment_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelFulfillment(orderId, fulfillmentId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -10412,8 +10607,8 @@
     "/admin/orders/{id}/line-items/{line_item_id}/reserve": {
       "post": {
         "operationId": "PostOrdersOrderLineItemReservations",
-        "summary": "Create a Reservation for a line item",
-        "description": "Creates a Reservation for a line item at a specified location, optionally for a partial quantity.",
+        "summary": "Create a Reservation",
+        "description": "Create a Reservation for a line item at a specified location, optionally for a partial quantity.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -10448,7 +10643,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/line-items/{line_item_id}/reserve' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"location_id\": \"loc_1\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/line-items/{line_item_id}/reserve' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"location_id\": \"loc_1\"\n}'\n"
           }
         ],
         "security": [
@@ -10498,7 +10693,7 @@
       "post": {
         "operationId": "PostOrdersOrderRefunds",
         "summary": "Create a Refund",
-        "description": "Issues a Refund.",
+        "description": "Refund an amount for an order. The amount must be less than or equal the `refundable_amount` of the order.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -10513,7 +10708,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10521,7 +10716,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10544,12 +10739,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.refundPayment(order_id, {\n  amount: 1000,\n  reason: 'Do not like it'\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.refundPayment(orderId, {\n  amount: 1000,\n  reason: \"Do not like it\"\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/adasda/refund' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"amount\": 1000,\n    \"reason\": \"Do not like it\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/adasda/refund' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"amount\": 1000,\n    \"reason\": \"Do not like it\"\n}'\n"
           }
         ],
         "security": [
@@ -10598,8 +10793,8 @@
     "/admin/orders/{id}/reservations": {
       "get": {
         "operationId": "GetOrdersOrderReservations",
-        "summary": "Get reservations of an Order",
-        "description": "Retrieves reservations of an Order",
+        "summary": "Get Order Reservations",
+        "description": "Retrieve the list of reservations of an Order",
         "x-authenticated": true,
         "parameters": [
           {
@@ -10614,7 +10809,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many reservations to skip before the results.",
+            "description": "The number of reservations to skip when retrieving the reservations.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -10634,7 +10829,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/orders/{id}/reservations' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/orders/{id}/reservations' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -10684,8 +10879,12 @@
       "post": {
         "operationId": "PostOrdersOrderReturns",
         "summary": "Request a Return",
-        "description": "Requests a Return. If applicable a return label will be created and other plugins notified.",
+        "description": "Request and create a Return for items in an order. If the return shipping method is specified, it will be automatically fulfilled.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Return creation process",
+          "url": "https://docs.medusajs.com/modules/orders/returns#returns-process"
+        },
         "parameters": [
           {
             "in": "path",
@@ -10699,7 +10898,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10707,7 +10906,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10730,12 +10929,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.requestReturn(order_id, {\n  items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.requestReturn(orderId, {\n  items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/return' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"items\": [\n      {\n        \"item_id\": \"{item_id}\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/return' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"items\": [\n      {\n        \"item_id\": \"{item_id}\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -10784,9 +10983,13 @@
     "/admin/orders/{id}/shipment": {
       "post": {
         "operationId": "PostOrdersOrderShipment",
-        "summary": "Create a Shipment",
-        "description": "Registers a Fulfillment as shipped.",
+        "summary": "Ship a Fulfillment",
+        "description": "Mark a fulfillment as shipped. This changes the order's fulfillment status to either `shipped` or `partially_shipped`, depending on whether all the items were shipped.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Fulfillments of orders",
+          "url": "https://docs.medusajs.com/modules/orders/#fulfillments-in-orders"
+        },
         "parameters": [
           {
             "in": "path",
@@ -10800,7 +11003,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10808,7 +11011,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10836,7 +11039,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/shipment' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"fulfillment_id\": \"{fulfillment_id}\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/shipment' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"fulfillment_id\": \"{fulfillment_id}\"\n}'\n"
           }
         ],
         "security": [
@@ -10900,7 +11103,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10908,7 +11111,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -10932,12 +11135,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.addShippingMethod(order_id, {\n  price: 1000,\n  option_id\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.addShippingMethod(orderId, {\n  price: 1000,\n  option_id\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/shipping-methods' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"price\": 1000,\n    \"option_id\": \"{option_id}\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/shipping-methods' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"price\": 1000,\n    \"option_id\": \"{option_id}\"\n}'\n"
           }
         ],
         "security": [
@@ -10987,8 +11190,12 @@
       "post": {
         "operationId": "PostOrdersOrderSwaps",
         "summary": "Create a Swap",
-        "description": "Creates a Swap. Swaps are used to handle Return of previously purchased goods and Fulfillment of replacements simultaneously.",
+        "description": "Create a Swap. This includes creating a return that is associated with the swap.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "How are swaps created",
+          "url": "https://docs.medusajs.com/modules/orders/swaps#how-are-swaps-created"
+        },
         "parameters": [
           {
             "in": "path",
@@ -11002,7 +11209,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded the order of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11010,7 +11217,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included the order of the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11033,12 +11240,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.createSwap(order_id, {\n  return_items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.createSwap(orderId, {\n  return_items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"return_items\": [\n      {\n        \"item_id\": \"asfasf\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"return_items\": [\n      {\n        \"item_id\": \"asfasf\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -11087,15 +11294,19 @@
     "/admin/orders/{id}/swaps/{swap_id}/cancel": {
       "post": {
         "operationId": "PostOrdersSwapCancel",
-        "summary": "Cancels a Swap",
-        "description": "Cancels a Swap",
+        "summary": "Cancel a Swap",
+        "description": "Cancel a Swap and change its status.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Canceling a swap",
+          "url": "https://docs.medusajs.com/modules/orders/swaps#canceling-a-swap"
+        },
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order.",
+            "description": "The ID of the Order the swap is associated with.",
             "schema": {
               "type": "string"
             }
@@ -11112,7 +11323,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11120,7 +11331,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11134,12 +11345,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelSwap(order_id, swap_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelSwap(orderId, swapId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{order_id}/swaps/{swap_id}/cancel' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{order_id}/swaps/{swap_id}/cancel' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -11188,15 +11399,19 @@
     "/admin/orders/{id}/swaps/{swap_id}/fulfillments": {
       "post": {
         "operationId": "PostOrdersOrderSwapsSwapFulfillments",
-        "summary": "Create Swap Fulfillment",
-        "description": "Creates a Fulfillment for a Swap.",
+        "summary": "Create a Swap Fulfillment",
+        "description": "Create a Fulfillment for a Swap.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Handling a swap's fulfillment",
+          "url": "https://docs.medusajs.com/modules/orders/swaps#handling-swap-fulfillment"
+        },
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order.",
+            "description": "The ID of the Order the swap is associated with.",
             "schema": {
               "type": "string"
             }
@@ -11213,7 +11428,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11221,7 +11436,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11244,12 +11459,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.fulfillSwap(order_id, swap_id, {\n\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.fulfillSwap(orderId, swapId, {\n\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -11299,14 +11514,14 @@
       "post": {
         "operationId": "PostOrdersSwapFulfillmentsCancel",
         "summary": "Cancel Swap's Fulfilmment",
-        "description": "Registers a Swap's Fulfillment as canceled.",
+        "description": "Cancel a swap's fulfillment and change its status.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order which the Swap relates to.",
+            "description": "The ID of the order the swap is associated with.",
             "schema": {
               "type": "string"
             }
@@ -11315,7 +11530,7 @@
             "in": "path",
             "name": "swap_id",
             "required": true,
-            "description": "The ID of the Swap which the Fulfillment relates to.",
+            "description": "The ID of the swap.",
             "schema": {
               "type": "string"
             }
@@ -11324,7 +11539,7 @@
             "in": "path",
             "name": "fulfillment_id",
             "required": true,
-            "description": "The ID of the Fulfillment.",
+            "description": "The ID of the fulfillment.",
             "schema": {
               "type": "string"
             }
@@ -11332,7 +11547,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11340,7 +11555,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11354,12 +11569,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelSwapFulfillment(order_id, swap_id, fulfillment_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.cancelSwapFulfillment(orderId, swapId, fulfillmentId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -11408,15 +11623,19 @@
     "/admin/orders/{id}/swaps/{swap_id}/process-payment": {
       "post": {
         "operationId": "PostOrdersOrderSwapsSwapProcessPayment",
-        "summary": "Process Swap Payment",
-        "description": "When there are differences between the returned and shipped Products in a Swap, the difference must be processed. Either a Refund will be issued or a Payment will be captured.",
+        "summary": "Process a Swap Payment",
+        "description": "Process a swap's payment either by refunding or issuing a payment. This depends on the `difference_due` of the swap. If `difference_due` is negative, the amount is refunded. If `difference_due` is positive, the amount is captured.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Handling a swap's payment",
+          "url": "https://docs.medusajs.com/modules/orders/swaps#handling-swap-payment"
+        },
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Order.",
+            "description": "The ID of the order the swap is associated with.",
             "schema": {
               "type": "string"
             }
@@ -11425,7 +11644,7 @@
             "in": "path",
             "name": "swap_id",
             "required": true,
-            "description": "The ID of the Swap.",
+            "description": "The ID of the swap.",
             "schema": {
               "type": "string"
             }
@@ -11433,7 +11652,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11441,7 +11660,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11455,12 +11674,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.processSwapPayment(order_id, swap_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.orders.processSwapPayment(orderId, swapId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/process-payment' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/process-payment' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -11509,9 +11728,13 @@
     "/admin/orders/{id}/swaps/{swap_id}/shipments": {
       "post": {
         "operationId": "PostOrdersOrderSwapsSwapShipments",
-        "summary": "Create Swap Shipment",
-        "description": "Registers a Swap Fulfillment as shipped.",
+        "summary": "Ship a Swap's Fulfillment",
+        "description": "RMark a swap's fulfillment as shipped. This changes the swap's fulfillment status to either `shipped` or `partially_shipped`, depending on whether all the items were shipped.",
         "x-authenticated": true,
+        "externalDocs": {
+          "description": "Handling swap fulfillments",
+          "url": "https://docs.medusajs.com/modules/orders/swaps#handling-swap-fulfillment"
+        },
         "parameters": [
           {
             "in": "path",
@@ -11534,7 +11757,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11542,7 +11765,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the result.",
+            "description": "Comma-separated fields that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -11570,7 +11793,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/shipments' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"fulfillment_id\": \"{fulfillment_id}\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/shipments' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"fulfillment_id\": \"{fulfillment_id}\"\n}'\n"
           }
         ],
         "security": [
@@ -11619,15 +11842,15 @@
     "/admin/payment-collections/{id}": {
       "get": {
         "operationId": "GetPaymentCollectionsPaymentCollection",
-        "summary": "Get a PaymentCollection",
-        "description": "Retrieves a PaymentCollection.",
+        "summary": "Get a Payment Collection",
+        "description": "Retrieve a Payment Collection's details.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the PaymentCollection.",
+            "description": "The ID of the Payment Collection.",
             "schema": {
               "type": "string"
             }
@@ -11635,7 +11858,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned payment collection.",
             "schema": {
               "type": "string"
             }
@@ -11643,7 +11866,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned payment collection.",
             "schema": {
               "type": "string"
             }
@@ -11662,7 +11885,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/payment-collections/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/payment-collections/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -11709,15 +11932,15 @@
       },
       "post": {
         "operationId": "PostPaymentCollectionsPaymentCollection",
-        "summary": "Update PaymentCollection",
-        "description": "Updates a PaymentCollection.",
+        "summary": "Update Payment Collection",
+        "description": "Update a Payment Collection's details.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the PaymentCollection.",
+            "description": "The ID of the Payment Collection.",
             "schema": {
               "type": "string"
             }
@@ -11739,12 +11962,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.paymentCollections.update(payment_collection_id, {\n  description: \"Description of payCol\"\n})\n  .then(({ payment_collection }) => {\n    console.log(payment_collection.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.paymentCollections.update(paymentCollectionId, {\n  description\n})\n  .then(({ payment_collection }) => {\n    console.log(payment_collection.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/payment-collections/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"description\": \"Description of payCol\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/payment-collections/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"description\": \"Description of payment collection\"\n}'\n"
           }
         ],
         "security": [
@@ -11791,15 +12014,15 @@
       },
       "delete": {
         "operationId": "DeletePaymentCollectionsPaymentCollection",
-        "summary": "Del a PaymentCollection",
-        "description": "Deletes a Payment Collection",
+        "summary": "Delete a Payment Collection",
+        "description": "Delete a Payment Collection. Only payment collections with the statuses `canceled` or `not_paid` can be deleted.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Payment Collection to delete.",
+            "description": "The ID of the Payment Collection.",
             "schema": {
               "type": "string"
             }
@@ -11812,12 +12035,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.paymentCollections.delete(payment_collection_id)\n  .then(({ id, object, deleted }) => {\n    console.log(id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.paymentCollections.delete(paymentCollectionId)\n  .then(({ id, object, deleted }) => {\n    console.log(id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/payment-collections/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/payment-collections/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -11855,14 +12078,14 @@
       "post": {
         "operationId": "PostPaymentCollectionsPaymentCollectionAuthorize",
         "summary": "Mark Authorized",
-        "description": "Sets the status of PaymentCollection as Authorized.",
+        "description": "Set the status of a Payment Collection as `authorized`. This will also change the `authorized_amount` of the payment collection.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the PaymentCollection.",
+            "description": "The ID of the Payment Collection.",
             "schema": {
               "type": "string"
             }
@@ -11875,12 +12098,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.paymentCollections.markAsAuthorized(payment_collection_id)\n  .then(({ payment_collection }) => {\n    console.log(payment_collection.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.paymentCollections.markAsAuthorized(paymentCollectionId)\n  .then(({ payment_collection }) => {\n    console.log(payment_collection.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/payment-collections/{id}/authorize' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/payment-collections/{id}/authorize' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -11930,7 +12153,7 @@
       "get": {
         "operationId": "GetPaymentsPayment",
         "summary": "Get Payment details",
-        "description": "Retrieves the Payment details",
+        "description": "Retrieve a Payment's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -11951,12 +12174,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.payments.retrieve(payment_id)\n.then(({ payment }) => {\n  console.log(payment.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.payments.retrieve(paymentId)\n.then(({ payment }) => {\n  console.log(payment.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/payments/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/payments/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -12006,7 +12229,7 @@
       "post": {
         "operationId": "PostPaymentsPaymentCapture",
         "summary": "Capture a Payment",
-        "description": "Captures a Payment.",
+        "description": "Capture a Payment.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -12026,12 +12249,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.payments.capturePayment(payment_id)\n.then(({ payment }) => {\n  console.log(payment.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.payments.capturePayment(paymentId)\n.then(({ payment }) => {\n  console.log(payment.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/payments/{id}/capture' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/payments/{id}/capture' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -12080,8 +12303,8 @@
     "/admin/payments/{id}/refund": {
       "post": {
         "operationId": "PostPaymentsPaymentRefunds",
-        "summary": "Create a Refund",
-        "description": "Issues a Refund.",
+        "summary": "Refund Payment",
+        "description": "Refund a payment. The payment must be captured first.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -12110,12 +12333,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.payments.refundPayment(payment_id, {\n  amount: 1000,\n  reason: 'return',\n  note: 'Do not like it',\n})\n.then(({ payment }) => {\n  console.log(payment.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.payments.refundPayment(paymentId, {\n  amount: 1000,\n  reason: \"return\",\n  note: \"Do not like it\",\n})\n.then(({ payment }) => {\n  console.log(payment.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/payments/pay_123/refund' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"amount\": 1000,\n    \"reason\": \"return\",\n    \"note\": \"Do not like it\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/payments/pay_123/refund' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"amount\": 1000,\n    \"reason\": \"return\",\n    \"note\": \"Do not like it\"\n}'\n"
           }
         ],
         "security": [
@@ -12165,13 +12388,13 @@
       "get": {
         "operationId": "GetPriceLists",
         "summary": "List Price Lists",
-        "description": "Retrieves a list of Price Lists.",
+        "description": "Retrieve a list of price lists. The price lists can be filtered by fields such as `q` or `status`. The price lists can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of items to get",
+            "description": "Limit the number of price lists returned.",
             "schema": {
               "type": "number",
               "default": "10"
@@ -12180,7 +12403,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The offset at which to get items",
+            "description": "The number of price lists to skip when retrieving the price lists.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -12189,7 +12412,15 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each item of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned price lists.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "fields",
+            "description": "Comma-separated fields that should be included in the returned price lists.",
             "schema": {
               "type": "string"
             }
@@ -12197,7 +12428,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "field to order results by.",
+            "description": "A price-list field to sort-order the retrieved price lists by.",
             "schema": {
               "type": "string"
             }
@@ -12205,7 +12436,7 @@
           {
             "in": "query",
             "name": "id",
-            "description": "ID to search for.",
+            "description": "Filter by ID",
             "schema": {
               "type": "string"
             }
@@ -12213,7 +12444,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "query to search in price list description, price list name, and customer group name fields.",
+            "description": "term to search price lists' description, name, and customer group's name.",
             "schema": {
               "type": "string"
             }
@@ -12223,7 +12454,7 @@
             "name": "status",
             "style": "form",
             "explode": false,
-            "description": "Status to search for.",
+            "description": "Filter by status.",
             "schema": {
               "type": "array",
               "items": {
@@ -12238,7 +12469,7 @@
           {
             "in": "query",
             "name": "name",
-            "description": "price list name to search for.",
+            "description": "Filter by name",
             "schema": {
               "type": "string"
             }
@@ -12248,7 +12479,7 @@
             "name": "customer_groups",
             "style": "form",
             "explode": false,
-            "description": "Customer Group IDs to search for.",
+            "description": "Filter by customer-group IDs.",
             "schema": {
               "type": "array",
               "items": {
@@ -12261,7 +12492,7 @@
             "name": "type",
             "style": "form",
             "explode": false,
-            "description": "Type to search for.",
+            "description": "Filter by type.",
             "schema": {
               "type": "array",
               "items": {
@@ -12276,7 +12507,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting price lists were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -12306,7 +12537,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting price lists were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -12336,7 +12567,7 @@
           {
             "in": "query",
             "name": "deleted_at",
-            "description": "Date comparison for when resulting price lists were deleted.",
+            "description": "Filter by a deletion date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -12377,7 +12608,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/price-lists' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/price-lists' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -12425,7 +12656,7 @@
       "post": {
         "operationId": "PostPriceListsPriceList",
         "summary": "Create a Price List",
-        "description": "Creates a Price List",
+        "description": "Create a Price List.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -12443,12 +12674,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nimport { PriceListType } from \"@medusajs/medusa\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.create({\n  name: 'New Price List',\n  description: 'A new price list',\n  type: PriceListType.SALE,\n  prices: [\n    {\n      amount: 1000,\n      variant_id,\n      currency_code: 'eur'\n    }\n  ]\n})\n.then(({ price_list }) => {\n  console.log(price_list.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nimport { PriceListType } from \"@medusajs/medusa\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.create({\n  name: \"New Price List\",\n  description: \"A new price list\",\n  type: PriceListType.SALE,\n  prices: [\n    {\n      amount: 1000,\n      variant_id,\n      currency_code: \"eur\"\n    }\n  ]\n})\n.then(({ price_list }) => {\n  console.log(price_list.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/price-lists' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"New Price List\",\n    \"description\": \"A new price list\",\n    \"type\": \"sale\",\n    \"prices\": [\n      {\n        \"amount\": 1000,\n        \"variant_id\": \"afafa\",\n        \"currency_code\": \"eur\"\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/price-lists' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"New Price List\",\n    \"description\": \"A new price list\",\n    \"type\": \"sale\",\n    \"prices\": [\n      {\n        \"amount\": 1000,\n        \"variant_id\": \"afafa\",\n        \"currency_code\": \"eur\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -12498,7 +12729,7 @@
       "get": {
         "operationId": "GetPriceListsPriceList",
         "summary": "Get a Price List",
-        "description": "Retrieves a Price List.",
+        "description": "Retrieve a Price List's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -12518,12 +12749,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.retrieve(price_list_id)\n.then(({ price_list }) => {\n  console.log(price_list.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.retrieve(priceListId)\n.then(({ price_list }) => {\n  console.log(price_list.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/price-lists/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/price-lists/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -12571,7 +12802,7 @@
       "post": {
         "operationId": "PostPriceListsPriceListPriceList",
         "summary": "Update a Price List",
-        "description": "Updates a Price List",
+        "description": "Update a Price List's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -12600,12 +12831,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.update(price_list_id, {\n  name: 'New Price List'\n})\n.then(({ price_list }) => {\n  console.log(price_list.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.update(priceListId, {\n  name: \"New Price List\"\n})\n.then(({ price_list }) => {\n  console.log(price_list.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/price-lists/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"New Price List\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/price-lists/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"New Price List\"\n}'\n"
           }
         ],
         "security": [
@@ -12653,14 +12884,14 @@
       "delete": {
         "operationId": "DeletePriceListsPriceList",
         "summary": "Delete a Price List",
-        "description": "Deletes a Price List",
+        "description": "Delete a Price List and its associated prices.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Price List to delete.",
+            "description": "The ID of the Price List.",
             "schema": {
               "type": "string"
             }
@@ -12673,12 +12904,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.delete(price_list_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.delete(priceListId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/price-lists/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -12727,15 +12958,15 @@
     "/admin/price-lists/{id}/prices/batch": {
       "post": {
         "operationId": "PostPriceListsPriceListPricesBatch",
-        "summary": "Update Prices",
-        "description": "Batch update prices for a Price List",
+        "summary": "Add or Update Prices",
+        "description": "Add or update a list of prices in a Price List",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Price List to update prices for.",
+            "description": "The ID of the Price List.",
             "schema": {
               "type": "string"
             }
@@ -12757,12 +12988,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.addPrices(price_list_id, {\n  prices: [\n    {\n      amount: 1000,\n      variant_id,\n      currency_code: 'eur'\n    }\n  ]\n})\n.then(({ price_list }) => {\n  console.log(price_list.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.addPrices(priceListId, {\n  prices: [\n    {\n      amount: 1000,\n      variant_id,\n      currency_code: \"eur\"\n    }\n  ]\n})\n.then(({ price_list }) => {\n  console.log(price_list.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"prices\": [\n      {\n        \"amount\": 100,\n        \"variant_id\": \"afasfa\",\n        \"currency_code\": \"eur\"\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"prices\": [\n      {\n        \"amount\": 100,\n        \"variant_id\": \"afasfa\",\n        \"currency_code\": \"eur\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -12810,14 +13041,14 @@
       "delete": {
         "operationId": "DeletePriceListsPriceListPricesBatch",
         "summary": "Delete Prices",
-        "description": "Batch delete prices that belong to a Price List",
+        "description": "Delete a list of prices in a Price List",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Price List that the Money Amounts (Prices) that will be deleted belongs to.",
+            "description": "The ID of the Price List",
             "schema": {
               "type": "string"
             }
@@ -12839,12 +13070,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.deletePrices(price_list_id, {\n  price_ids: [\n    price_id\n  ]\n})\n.then(({ ids, object, deleted }) => {\n  console.log(ids.length);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.deletePrices(priceListId, {\n  price_ids: [\n    price_id\n  ]\n})\n.then(({ ids, object, deleted }) => {\n  console.log(ids.length);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"price_ids\": [\n      \"adasfa\"\n    ]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"price_ids\": [\n      \"adasfa\"\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -12894,7 +13125,7 @@
       "get": {
         "operationId": "GetPriceListsPriceListProducts",
         "summary": "List Products",
-        "description": "Retrieves a list of Product that are part of a Price List",
+        "description": "Retrieve a price list's products. The products can be filtered by fields such as `q` or `status`. The products can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -12909,7 +13140,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching product title and description, variant title and sku, and collection title.",
+            "description": "term used to search products' title, description, product variant's title and sku, and product collection's title.",
             "schema": {
               "type": "string"
             }
@@ -12917,7 +13148,7 @@
           {
             "in": "query",
             "name": "id",
-            "description": "ID of the product to search for.",
+            "description": "Filter by product ID",
             "schema": {
               "type": "string"
             }
@@ -12925,7 +13156,7 @@
           {
             "in": "query",
             "name": "status",
-            "description": "Product status to search for",
+            "description": "Filter by product status",
             "style": "form",
             "explode": false,
             "schema": {
@@ -12944,7 +13175,7 @@
           {
             "in": "query",
             "name": "collection_id",
-            "description": "Collection IDs to search for",
+            "description": "Filter by product collection ID. Only products in the specified collections are retrieved.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -12957,7 +13188,7 @@
           {
             "in": "query",
             "name": "tags",
-            "description": "Tag IDs to search for",
+            "description": "Filter by tag IDs. Only products having the specified tags are retrieved.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -12970,7 +13201,7 @@
           {
             "in": "query",
             "name": "title",
-            "description": "product title to search for.",
+            "description": "Filter by title",
             "schema": {
               "type": "string"
             }
@@ -12978,7 +13209,7 @@
           {
             "in": "query",
             "name": "description",
-            "description": "product description to search for.",
+            "description": "Filter by description",
             "schema": {
               "type": "string"
             }
@@ -12986,7 +13217,7 @@
           {
             "in": "query",
             "name": "handle",
-            "description": "product handle to search for.",
+            "description": "Filter by handle",
             "schema": {
               "type": "string"
             }
@@ -12994,7 +13225,7 @@
           {
             "in": "query",
             "name": "is_giftcard",
-            "description": "Search for giftcards using is_giftcard=true.",
+            "description": "A boolean value to filter by whether the product is a gift card or not.",
             "schema": {
               "type": "string"
             }
@@ -13002,7 +13233,7 @@
           {
             "in": "query",
             "name": "type",
-            "description": "to search for.",
+            "description": "Filter product type.",
             "schema": {
               "type": "string"
             }
@@ -13010,7 +13241,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "field to sort results by.",
+            "description": "A product field to sort-order the retrieved products by.",
             "schema": {
               "type": "string"
             }
@@ -13018,7 +13249,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting products were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -13048,7 +13279,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting products were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -13078,7 +13309,7 @@
           {
             "in": "query",
             "name": "deleted_at",
-            "description": "Date comparison for when resulting products were deleted.",
+            "description": "Filter by a deletion date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -13108,7 +13339,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many products to skip in the result.",
+            "description": "The number of products to skip when retrieving the products.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -13126,7 +13357,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each product of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned products.",
             "schema": {
               "type": "string"
             }
@@ -13134,7 +13365,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each product of the result.",
+            "description": "Comma-separated fields that should be included in the returned products.",
             "schema": {
               "type": "string"
             }
@@ -13148,12 +13379,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.listProducts(price_list_id)\n.then(({ products, limit, offset, count }) => {\n  console.log(products.length);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.listProducts(priceListId)\n.then(({ products, limit, offset, count }) => {\n  console.log(products.length);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/price-lists/{id}/products' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/price-lists/{id}/products' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -13202,15 +13433,15 @@
     "/admin/price-lists/{id}/products/{product_id}/prices": {
       "delete": {
         "operationId": "DeletePriceListsPriceListProductsProductPrices",
-        "summary": "Delete Product's Prices",
-        "description": "Delete all the prices related to a specific product in a price list",
+        "summary": "Delete a Product's Prices",
+        "description": "Delete all the prices related to a specific product in a price list.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Price List that the Money Amounts that will be deleted belongs to.",
+            "description": "The ID of the Price List.",
             "schema": {
               "type": "string"
             }
@@ -13219,7 +13450,7 @@
             "in": "path",
             "name": "product_id",
             "required": true,
-            "description": "The ID of the product from which the money amount will be deleted.",
+            "description": "The ID of the product from which the prices will be deleted.",
             "schema": {
               "type": "string"
             }
@@ -13232,12 +13463,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.deleteProductPrices(price_list_id, product_id)\n.then(({ ids, object, deleted }) => {\n  console.log(ids.length);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.deleteProductPrices(priceListId, productId)\n.then(({ ids, object, deleted }) => {\n  console.log(ids.length);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}/products/{product_id}/prices' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/price-lists/{id}/products/{product_id}/prices' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -13286,7 +13517,7 @@
     "/admin/price-lists/{id}/variants/{variant_id}/prices": {
       "delete": {
         "operationId": "DeletePriceListsPriceListVariantsVariantPrices",
-        "summary": "Delete Variant's Prices",
+        "summary": "Delete a Variant's Prices",
         "description": "Delete all the prices related to a specific variant in a price list",
         "x-authenticated": true,
         "parameters": [
@@ -13294,7 +13525,7 @@
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Price List that the Money Amounts that will be deleted belongs to.",
+            "description": "The ID of the Price List.",
             "schema": {
               "type": "string"
             }
@@ -13303,7 +13534,7 @@
             "in": "path",
             "name": "variant_id",
             "required": true,
-            "description": "The ID of the variant from which the money amount will be deleted.",
+            "description": "The ID of the variant.",
             "schema": {
               "type": "string"
             }
@@ -13316,12 +13547,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.deleteVariantPrices(price_list_id, variant_id)\n.then(({ ids, object, deleted }) => {\n  console.log(ids);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.priceLists.deleteVariantPrices(priceListId, variantId)\n.then(({ ids, object, deleted }) => {\n  console.log(ids);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}/variants/{variant_id}/prices' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/price-lists/{id}/variants/{variant_id}/prices' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -13371,13 +13602,14 @@
       "get": {
         "operationId": "GetProductCategories",
         "summary": "List Product Categories",
-        "description": "Retrieve a list of product categories.",
+        "description": "Retrieve a list of product categories. The product categories can be filtered by fields such as `q` or `handle`. The product categories can also be paginated.",
         "x-authenticated": true,
+        "x-featureFlag": "product_categories",
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching product category names or handles.",
+            "description": "term to search product categories' names and handles.",
             "schema": {
               "type": "string"
             }
@@ -13385,7 +13617,7 @@
           {
             "in": "query",
             "name": "handle",
-            "description": "Query used for searching product category by handle.",
+            "description": "Filter by handle.",
             "schema": {
               "type": "string"
             }
@@ -13393,7 +13625,7 @@
           {
             "in": "query",
             "name": "is_internal",
-            "description": "Search for only internal categories.",
+            "description": "Filter by whether the category is internal or not.",
             "schema": {
               "type": "boolean"
             }
@@ -13401,7 +13633,7 @@
           {
             "in": "query",
             "name": "is_active",
-            "description": "Search for only active categories",
+            "description": "Filter by whether the category is active or not.",
             "schema": {
               "type": "boolean"
             }
@@ -13409,7 +13641,7 @@
           {
             "in": "query",
             "name": "include_descendants_tree",
-            "description": "Include all nested descendants of category",
+            "description": "If set to `true`, all nested descendants of a category are included in the response.",
             "schema": {
               "type": "boolean"
             }
@@ -13417,7 +13649,7 @@
           {
             "in": "query",
             "name": "parent_category_id",
-            "description": "Returns categories scoped by parent",
+            "description": "Filter by the ID of a parent category.",
             "schema": {
               "type": "string"
             }
@@ -13425,7 +13657,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many product categories to skip in the result.",
+            "description": "The number of product categories to skip when retrieving the product categories.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -13443,7 +13675,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in the product category.",
+            "description": "Comma-separated relations that should be expanded in the returned product categories.",
             "schema": {
               "type": "string"
             }
@@ -13451,7 +13683,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in the product category.",
+            "description": "Comma-separated fields that should be included in the returned product categories.",
             "schema": {
               "type": "string"
             }
@@ -13470,7 +13702,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/product-categories' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/product-categories' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -13518,13 +13750,14 @@
       "post": {
         "operationId": "PostProductCategories",
         "summary": "Create a Product Category",
-        "description": "Creates a Product Category.",
+        "description": "Create a Product Category.",
         "x-authenticated": true,
+        "x-featureFlag": "product_categories",
         "parameters": [
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned product category.",
             "schema": {
               "type": "string"
             }
@@ -13532,7 +13765,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be retrieved in the results.",
+            "description": "Comma-separated fields that should be included in the returned product category.",
             "schema": {
               "type": "string"
             }
@@ -13560,7 +13793,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/product-categories' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Skinny Jeans\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/product-categories' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Skinny Jeans\"\n}'\n"
           }
         ],
         "security": [
@@ -13610,8 +13843,9 @@
       "get": {
         "operationId": "GetProductCategoriesCategory",
         "summary": "Get a Product Category",
-        "description": "Retrieves a Product Category.",
+        "description": "Retrieve a Product Category's details.",
         "x-authenticated": true,
+        "x-featureFlag": "product_categories",
         "parameters": [
           {
             "in": "path",
@@ -13625,7 +13859,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned product category.",
             "schema": {
               "type": "string"
             }
@@ -13633,7 +13867,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in the results.",
+            "description": "Comma-separated fields that should be included in the returned product category.",
             "schema": {
               "type": "string"
             }
@@ -13652,7 +13886,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/product-categories/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/product-categories/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -13702,6 +13936,7 @@
         "summary": "Update a Product Category",
         "description": "Updates a Product Category.",
         "x-authenticated": true,
+        "x-featureFlag": "product_categories",
         "parameters": [
           {
             "in": "path",
@@ -13751,7 +13986,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/product-categories/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Skinny Jeans\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/product-categories/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Skinny Jeans\"\n}'\n"
           }
         ],
         "security": [
@@ -13799,8 +14034,9 @@
       "delete": {
         "operationId": "DeleteProductCategoriesCategory",
         "summary": "Delete a Product Category",
-        "description": "Deletes a Product Category.",
+        "description": "Delete a Product Category. This does not delete associated products.",
         "x-authenticated": true,
+        "x-featureFlag": "product_categories",
         "parameters": [
           {
             "in": "path",
@@ -13824,7 +14060,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/product-categories/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/product-categories/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -13874,8 +14110,9 @@
       "post": {
         "operationId": "PostProductCategoriesCategoryProductsBatch",
         "summary": "Add Products to a Category",
-        "description": "Assign a batch of products to a product category.",
+        "description": "Add a list of products to a product category.",
         "x-authenticated": true,
+        "x-featureFlag": "product_categories",
         "parameters": [
           {
             "in": "path",
@@ -13889,7 +14126,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Category fields to be expanded in the response.",
+            "description": "Comma-separated relations that should be expanded in the returned product category.",
             "schema": {
               "type": "string"
             }
@@ -13897,7 +14134,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Category fields to be retrieved in the response.",
+            "description": "Comma-separated fields that should be included in the returned product category.",
             "schema": {
               "type": "string"
             }
@@ -13925,7 +14162,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location \\\n--request POST 'https://medusa-url.com/admin/product-categories/{id}/products/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n      {\n        \"id\": \"{product_id}\"\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/product-categories/{id}/products/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n      {\n        \"id\": \"{product_id}\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -13975,6 +14212,7 @@
         "summary": "Remove Products from Category",
         "description": "Remove a list of products from a product category.",
         "x-authenticated": true,
+        "x-featureFlag": "product_categories",
         "parameters": [
           {
             "in": "path",
@@ -13988,7 +14226,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Category fields to be expanded in the response.",
+            "description": "Comma-separated relations that should be expanded in the returned product category.",
             "schema": {
               "type": "string"
             }
@@ -13996,7 +14234,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Category fields to be retrieved in the response.",
+            "description": "Comma-separated fields that should be included in the returned product category.",
             "schema": {
               "type": "string"
             }
@@ -14024,7 +14262,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/product-categories/{id}/products/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n      {\n        \"id\": \"{product_id}\"\n      }\n    ]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/product-categories/{id}/products/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n      {\n        \"id\": \"{product_id}\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -14074,13 +14312,13 @@
       "get": {
         "operationId": "GetProductTags",
         "summary": "List Product Tags",
-        "description": "Retrieve a list of Product Tags.",
+        "description": "Retrieve a list of product tags. The product tags can be filtered by fields such as `q` or `value`. The product tags can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of tags to return.",
+            "description": "Limit the number of product tags returned.",
             "schema": {
               "type": "integer",
               "default": 10
@@ -14089,7 +14327,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of items to skip before the results.",
+            "description": "The number of product tags to skip when retrieving the product tags.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -14098,7 +14336,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "The field to sort items by.",
+            "description": "A product tag field to sort-order the retrieved product tags by.",
             "schema": {
               "type": "string"
             }
@@ -14106,7 +14344,7 @@
           {
             "in": "query",
             "name": "discount_condition_id",
-            "description": "The discount condition id on which to filter the tags.",
+            "description": "Filter by the ID of a discount condition. Only product tags that this discount condition is applied to will be retrieved.",
             "schema": {
               "type": "string"
             }
@@ -14116,7 +14354,7 @@
             "name": "value",
             "style": "form",
             "explode": false,
-            "description": "The tag values to search for",
+            "description": "Filter by tag value.",
             "schema": {
               "type": "array",
               "items": {
@@ -14127,7 +14365,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "A query string to search values for",
+            "description": "term to search product tags' values.",
             "schema": {
               "type": "string"
             }
@@ -14137,7 +14375,7 @@
             "name": "id",
             "style": "form",
             "explode": false,
-            "description": "The tag IDs to search for",
+            "description": "Filter by tag IDs.",
             "schema": {
               "type": "array",
               "items": {
@@ -14148,7 +14386,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting product tags were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -14178,7 +14416,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting product tags were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -14219,7 +14457,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/product-tags' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/product-tags' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -14269,13 +14507,13 @@
       "get": {
         "operationId": "GetProductTypes",
         "summary": "List Product Types",
-        "description": "Retrieve a list of Product Types.",
+        "description": "Retrieve a list of product types. The product types can be filtered by fields such as `q` or `value`. The product types can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of types to return.",
+            "description": "Limit the number of product types returned.",
             "schema": {
               "type": "integer",
               "default": 20
@@ -14284,7 +14522,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of items to skip before the results.",
+            "description": "The number of product types to skip when retrieving the product types.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -14293,7 +14531,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "The field to sort items by.",
+            "description": "A product type field to sort-order the retrieved product types by.",
             "schema": {
               "type": "string"
             }
@@ -14301,7 +14539,7 @@
           {
             "in": "query",
             "name": "discount_condition_id",
-            "description": "The discount condition id on which to filter the product types.",
+            "description": "Filter by the ID of a discount condition. Only product types that this discount condition is applied to will be retrieved.",
             "schema": {
               "type": "string"
             }
@@ -14311,7 +14549,7 @@
             "name": "value",
             "style": "form",
             "explode": false,
-            "description": "The type values to search for",
+            "description": "Filter by value.",
             "schema": {
               "type": "array",
               "items": {
@@ -14324,7 +14562,7 @@
             "name": "id",
             "style": "form",
             "explode": false,
-            "description": "The type IDs to search for",
+            "description": "Filter by product type IDs.",
             "schema": {
               "type": "array",
               "items": {
@@ -14335,7 +14573,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "A query string to search values for",
+            "description": "term to search product types' values.",
             "schema": {
               "type": "string"
             }
@@ -14343,7 +14581,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting product types were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -14373,7 +14611,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting product types were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -14414,7 +14652,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/product-types' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/product-types' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -14464,13 +14702,13 @@
       "get": {
         "operationId": "GetProducts",
         "summary": "List Products",
-        "description": "Retrieves a list of Product",
+        "description": "Retrieve a list of products. The products can be filtered by fields such as `q` or `status`. The products can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching product title and description, variant title and sku, and collection title.",
+            "description": "term to search products' title, description, variants' title and sku, and collections' title.",
             "schema": {
               "type": "string"
             }
@@ -14478,7 +14716,7 @@
           {
             "in": "query",
             "name": "discount_condition_id",
-            "description": "The discount condition id on which to filter the product.",
+            "description": "Filter by the ID of a discount condition. Only products that this discount condition is applied to will be retrieved.",
             "schema": {
               "type": "string"
             }
@@ -14493,7 +14731,7 @@
               "oneOf": [
                 {
                   "type": "string",
-                  "description": "ID of the product to search for."
+                  "description": "ID of the product."
                 },
                 {
                   "type": "array",
@@ -14510,7 +14748,7 @@
             "name": "status",
             "style": "form",
             "explode": false,
-            "description": "Status to search for",
+            "description": "Filter by status.",
             "schema": {
               "type": "array",
               "items": {
@@ -14529,7 +14767,7 @@
             "name": "collection_id",
             "style": "form",
             "explode": false,
-            "description": "Collection ids to search for.",
+            "description": "Filter by product collection IDs. Only products that are associated with the specified collections will be retrieved.",
             "schema": {
               "type": "array",
               "items": {
@@ -14542,7 +14780,7 @@
             "name": "tags",
             "style": "form",
             "explode": false,
-            "description": "Tag IDs to search for",
+            "description": "Filter by product tag IDs. Only products that are associated with the specified tags will be retrieved.",
             "schema": {
               "type": "array",
               "items": {
@@ -14555,7 +14793,7 @@
             "name": "price_list_id",
             "style": "form",
             "explode": false,
-            "description": "Price List IDs to search for",
+            "description": "Filter by IDs of price lists. Only products that these price lists are applied to will be retrieved.",
             "schema": {
               "type": "array",
               "items": {
@@ -14568,7 +14806,7 @@
             "name": "sales_channel_id",
             "style": "form",
             "explode": false,
-            "description": "Sales Channel IDs to filter products by",
+            "description": "Filter by sales channel IDs. Only products that are available in the specified sales channels will be retrieved.",
             "schema": {
               "type": "array",
               "items": {
@@ -14581,7 +14819,7 @@
             "name": "type_id",
             "style": "form",
             "explode": false,
-            "description": "Type IDs to filter products by",
+            "description": "Filter by product type IDs. Only products that are associated with the specified types will be retrieved.",
             "schema": {
               "type": "array",
               "items": {
@@ -14594,9 +14832,10 @@
             "name": "category_id",
             "style": "form",
             "explode": false,
-            "description": "Category IDs to filter products by",
+            "description": "Filter by product category IDs. Only products that are associated with the specified categories will be retrieved.",
             "schema": {
               "type": "array",
+              "x-featureFlag": "product_categories",
               "items": {
                 "type": "string"
               }
@@ -14605,15 +14844,18 @@
           {
             "in": "query",
             "name": "include_category_children",
-            "description": "Include category children when filtering by category_id",
+            "style": "form",
+            "explode": false,
+            "description": "whether to include product category children when filtering by `category_id`",
             "schema": {
-              "type": "boolean"
+              "type": "boolean",
+              "x-featureFlag": "product_categories"
             }
           },
           {
             "in": "query",
             "name": "title",
-            "description": "title to search for.",
+            "description": "Filter by title.",
             "schema": {
               "type": "string"
             }
@@ -14621,7 +14863,7 @@
           {
             "in": "query",
             "name": "description",
-            "description": "description to search for.",
+            "description": "Filter by description.",
             "schema": {
               "type": "string"
             }
@@ -14629,7 +14871,7 @@
           {
             "in": "query",
             "name": "handle",
-            "description": "handle to search for.",
+            "description": "Filter by handle.",
             "schema": {
               "type": "string"
             }
@@ -14637,7 +14879,7 @@
           {
             "in": "query",
             "name": "is_giftcard",
-            "description": "Search for giftcards using is_giftcard=true.",
+            "description": "Whether to retrieve gift cards or regular products.",
             "schema": {
               "type": "boolean"
             }
@@ -14645,7 +14887,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting products were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -14675,7 +14917,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting products were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -14705,7 +14947,7 @@
           {
             "in": "query",
             "name": "deleted_at",
-            "description": "Date comparison for when resulting products were deleted.",
+            "description": "Filter by a deletion date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -14735,7 +14977,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many products to skip in the result.",
+            "description": "The number of products to skip when retrieving the products.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -14753,7 +14995,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each product of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned products.",
             "schema": {
               "type": "string"
             }
@@ -14761,7 +15003,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each product of the result.",
+            "description": "Comma-separated fields that should be included in the returned products.",
             "schema": {
               "type": "string"
             }
@@ -14769,7 +15011,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "the field used to order the products.",
+            "description": "A product field to sort-order the retrieved products by.",
             "schema": {
               "type": "string"
             }
@@ -14788,7 +15030,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/products' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/products' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -14837,7 +15079,7 @@
         "operationId": "PostProducts",
         "summary": "Create a Product",
         "x-authenticated": true,
-        "description": "Creates a Product",
+        "description": "Create a new Product. This endpoint can also be used to create a gift card if the `is_giftcard` field is set to `true`.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -14854,12 +15096,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.create({\n  title: 'Shirt',\n  is_giftcard: false,\n  discountable: true\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.create({\n  title: \"Shirt\",\n  is_giftcard: false,\n  discountable: true\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/products' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Shirt\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/products' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Shirt\"\n}'\n"
           }
         ],
         "security": [
@@ -14909,7 +15151,7 @@
       "get": {
         "operationId": "GetProductsTagUsage",
         "summary": "List Tags Usage Number",
-        "description": "Retrieves a list of Product Tags with how many times each is used.",
+        "description": "Retrieve a list of Product Tags with how many times each is used in products.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "listTags"
@@ -14923,7 +15165,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/products/tag-usage' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/products/tag-usage' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -14974,7 +15216,7 @@
         "deprecated": true,
         "operationId": "GetProductsTypes",
         "summary": "List Product Types",
-        "description": "Retrieves a list of Product Types.",
+        "description": "Retrieve a list of Product Types.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "listTypes"
@@ -14988,7 +15230,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/products/types' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/products/types' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -15038,7 +15280,7 @@
       "get": {
         "operationId": "GetProductsProduct",
         "summary": "Get a Product",
-        "description": "Retrieves a Product.",
+        "description": "Retrieve a Product's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -15058,12 +15300,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.retrieve(product_id)\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.retrieve(productId)\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/products/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/products/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -15111,7 +15353,7 @@
       "post": {
         "operationId": "PostProductsProduct",
         "summary": "Update a Product",
-        "description": "Updates a Product",
+        "description": "Update a Product's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -15140,12 +15382,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.update(product_id, {\n  title: 'Shirt',\n  images: []\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.update(productId, {\n  title: \"Shirt\",\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/products/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Size\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/products/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Size\"\n}'\n"
           }
         ],
         "security": [
@@ -15193,7 +15435,7 @@
       "delete": {
         "operationId": "DeleteProductsProduct",
         "summary": "Delete a Product",
-        "description": "Deletes a Product and it's associated Product Variants.",
+        "description": "Delete a Product and its associated product variants and options.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -15213,12 +15455,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.delete(product_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.delete(productId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/products/asfsaf' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/products/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -15267,8 +15509,12 @@
     "/admin/products/{id}/metadata": {
       "post": {
         "operationId": "PostProductsProductMetadata",
-        "summary": "Set Product Metadata",
-        "description": "Set metadata key/value pair for Product",
+        "summary": "Set Metadata",
+        "description": "Set the metadata of a Product. It can be any key-value pair, which allows adding custom data to a product.",
+        "externalDocs": {
+          "description": "Learn about the metadata attribute, and how to delete and update it.",
+          "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+        },
         "x-authenticated": true,
         "parameters": [
           {
@@ -15297,12 +15543,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.setMetadata(product_id, {\nkey: 'test',\n  value: 'true'\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.setMetadata(productId, {\n  key: \"test\",\n  value: \"true\"\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/products/{id}/metadata' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"key\": \"test\",\n    \"value\": \"true\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/products/{id}/metadata' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"key\": \"test\",\n    \"value\": \"true\"\n}'\n"
           }
         ],
         "security": [
@@ -15352,8 +15598,8 @@
       "post": {
         "operationId": "PostProductsProductOptions",
         "summary": "Add a Product Option",
+        "description": "Add a Product Option to a Product.",
         "x-authenticated": true,
-        "description": "Adds a Product Option to a Product",
         "parameters": [
           {
             "in": "path",
@@ -15381,12 +15627,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.addOption(product_id, {\n  title: 'Size'\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.addOption(productId, {\n  title: \"Size\"\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/products/{id}/options' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Size\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/products/{id}/options' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Size\"\n}'\n"
           }
         ],
         "security": [
@@ -15436,7 +15682,7 @@
       "post": {
         "operationId": "PostProductsProductOptionsOption",
         "summary": "Update a Product Option",
-        "description": "Updates a Product Option",
+        "description": "Update a Product Option's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -15474,12 +15720,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.updateOption(product_id, option_id, {\n  title: 'Size'\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.updateOption(productId, optionId, {\n  title: \"Size\"\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Size\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Size\"\n}'\n"
           }
         ],
         "security": [
@@ -15527,7 +15773,7 @@
       "delete": {
         "operationId": "DeleteProductsProductOptionsOption",
         "summary": "Delete a Product Option",
-        "description": "Deletes a Product Option. Before a Product Option can be deleted all Option Values for the Product Option must be the same. You may, for example, have to delete some of your variants prior to deleting the Product Option",
+        "description": "Delete a Product Option. If there are product variants that use this product option, they must be deleted before deleting the product option.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -15556,12 +15802,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.deleteOption(product_id, option_id)\n.then(({ option_id, object, deleted, product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.deleteOption(productId, optionId)\n.then(({ option_id, object, deleted, product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -15611,14 +15857,14 @@
       "get": {
         "operationId": "GetProductsProductVariants",
         "summary": "List a Product's Variants",
-        "description": "Retrieves a list of the Product Variants associated with a Product.",
+        "description": "Retrieve a list of Product Variants associated with a Product. The variants can be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "ID of the product to search for the variants.",
+            "description": "ID of the product.",
             "schema": {
               "type": "string"
             }
@@ -15626,7 +15872,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated string of the column to select.",
+            "description": "Comma-separated fields that should be included in the returned product variants.",
             "schema": {
               "type": "string"
             }
@@ -15634,7 +15880,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated string of the relations to include.",
+            "description": "Comma-separated relations that should be expanded in the returned product variants.",
             "schema": {
               "type": "string"
             }
@@ -15642,7 +15888,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many items to skip before the results.",
+            "description": "The number of product variants to skip when retrieving the product variants.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -15651,7 +15897,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "Limit the number of items returned.",
+            "description": "Limit the number of product variants returned.",
             "schema": {
               "type": "integer",
               "default": 100
@@ -15666,7 +15912,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/products/{id}/variants' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/products/{id}/variants' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -15714,7 +15960,7 @@
       "post": {
         "operationId": "PostProductsProductVariants",
         "summary": "Create a Product Variant",
-        "description": "Creates a Product Variant. Each Product Variant must have a unique combination of Product Option Values.",
+        "description": "Create a Product Variant associated with a Product. Each product variant must have a unique combination of Product Option values.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -15743,12 +15989,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.createVariant(product_id, {\n  title: 'Color',\n  prices: [\n    {\n      amount: 1000,\n      currency_code: \"eur\"\n    }\n  ],\n  options: [\n    {\n      option_id,\n      value: 'S'\n    }\n  ],\n  inventory_quantity: 100\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.createVariant(productId, {\n  title: \"Color\",\n  prices: [\n    {\n      amount: 1000,\n      currency_code: \"eur\"\n    }\n  ],\n  options: [\n    {\n      option_id,\n      value: \"S\"\n    }\n  ],\n  inventory_quantity: 100\n})\n.then(({ product }) => {\n  console.log(product.id);\n})\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/products/{id}/variants' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Color\",\n    \"prices\": [\n      {\n        \"amount\": 1000,\n        \"currency_code\": \"eur\"\n      }\n    ],\n    \"options\": [\n      {\n        \"option_id\": \"asdasf\",\n        \"value\": \"S\"\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/products/{id}/variants' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Color\",\n    \"prices\": [\n      {\n        \"amount\": 1000,\n        \"currency_code\": \"eur\"\n      }\n    ],\n    \"options\": [\n      {\n        \"option_id\": \"asdasf\",\n        \"value\": \"S\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -15798,7 +16044,7 @@
       "post": {
         "operationId": "PostProductsProductVariantsVariant",
         "summary": "Update a Product Variant",
-        "description": "Update a Product Variant.",
+        "description": "Update a Product Variant's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -15836,12 +16082,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.updateVariant(product_id, variant_id, {\n  title: 'Color',\n  prices: [\n    {\n      amount: 1000,\n      currency_code: \"eur\"\n    }\n  ],\n  options: [\n    {\n      option_id,\n      value: 'S'\n    }\n  ],\n  inventory_quantity: 100\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.updateVariant(productId, variantId, {\n  title: \"Color\",\n  prices: [\n    {\n      amount: 1000,\n      currency_code: \"eur\"\n    }\n  ],\n  options: [\n    {\n      option_id,\n      value: \"S\"\n    }\n  ],\n  inventory_quantity: 100\n})\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/products/asfsaf/variants/saaga' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Color\",\n    \"prices\": [\n      {\n        \"amount\": 1000,\n        \"currency_code\": \"eur\"\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/products/{id}/variants/{variant_id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Color\",\n    \"prices\": [\n      {\n        \"amount\": 1000,\n        \"currency_code\": \"eur\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -15889,7 +16135,7 @@
       "delete": {
         "operationId": "DeleteProductsProductVariantsVariant",
         "summary": "Delete a Product Variant",
-        "description": "Deletes a Product Variant.",
+        "description": "Delete a Product Variant.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -15918,12 +16164,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.deleteVariant(product_id, variant_id)\n.then(({ variant_id, object, deleted, product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.products.deleteVariant(productId, variantId)\n.then(({ variant_id, object, deleted, product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/products/{id}/variants/{variant_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/products/{id}/variants/{variant_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -15972,15 +16218,15 @@
     "/admin/publishable-api-key/{id}": {
       "post": {
         "operationId": "PostPublishableApiKysPublishableApiKey",
-        "summary": "Update PublishableApiKey",
-        "description": "Updates a PublishableApiKey.",
+        "summary": "Update Publishable API Key",
+        "description": "Update a Publishable API Key's details.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the PublishableApiKey.",
+            "description": "The ID of the Publishable API Key.",
             "schema": {
               "type": "string"
             }
@@ -16007,7 +16253,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/publishable-api-key/{pka_id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"new title\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/publishable-api-key/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"new title\"\n}'\n"
           }
         ],
         "security": [
@@ -16056,14 +16302,14 @@
     "/admin/publishable-api-keys": {
       "get": {
         "operationId": "GetPublishableApiKeys",
-        "summary": "List PublishableApiKeys",
-        "description": "List PublishableApiKeys.",
+        "summary": "List Publishable API keys",
+        "description": "Retrieve a list of publishable API keys. The publishable API keys can be filtered by fields such as `q`. The publishable API keys can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching publishable api keys by title.",
+            "description": "term to search publishable API keys' titles.",
             "schema": {
               "type": "string"
             }
@@ -16071,7 +16317,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of items in the response",
+            "description": "Limit the number of publishable API keys returned.",
             "schema": {
               "type": "number",
               "default": "20"
@@ -16080,7 +16326,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The offset of items in response",
+            "description": "The number of publishable API keys to skip when retrieving the publishable API keys.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -16089,7 +16335,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned publishable API keys.",
             "schema": {
               "type": "string"
             }
@@ -16097,7 +16343,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned publishable API keys.",
             "schema": {
               "type": "string"
             }
@@ -16116,7 +16362,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/publishable-api-keys' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/publishable-api-keys' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -16163,8 +16409,8 @@
       },
       "post": {
         "operationId": "PostPublishableApiKeys",
-        "summary": "Create PublishableApiKey",
-        "description": "Creates a PublishableApiKey.",
+        "summary": "Create Publishable API Key",
+        "description": "Creates a Publishable API Key.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -16187,7 +16433,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/publishable-api-keys' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Web API Key\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/publishable-api-keys' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"title\": \"Web API Key\"\n}'\n"
           }
         ],
         "security": [
@@ -16236,14 +16482,14 @@
     "/admin/publishable-api-keys/{id}": {
       "get": {
         "operationId": "GetPublishableApiKeysPublishableApiKey",
-        "summary": "Get a PublishableApiKey",
-        "description": "Retrieve the Publishable Api Key.",
+        "summary": "Get a Publishable API Key",
+        "description": "Retrieve a publishable API key's details.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the PublishableApiKey.",
+            "description": "The ID of the Publishable API Key.",
             "schema": {
               "type": "string"
             }
@@ -16262,7 +16508,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/publishable-api-keys/{pka_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/publishable-api-keys/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -16309,15 +16555,15 @@
       },
       "delete": {
         "operationId": "DeletePublishableApiKeysPublishableApiKey",
-        "summary": "Delete PublishableApiKey",
-        "description": "Deletes a PublishableApiKeys",
+        "summary": "Delete Publishable API Key",
+        "description": "Delete a Publishable API Key. Associated resources, such as sales channels, are not deleted.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the PublishableApiKeys to delete.",
+            "description": "The ID of the Publishable API Key to delete.",
             "schema": {
               "type": "string"
             }
@@ -16335,7 +16581,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/publishable-api-key/{pka_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/publishable-api-key/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -16369,14 +16615,14 @@
     "/admin/publishable-api-keys/{id}/revoke": {
       "post": {
         "operationId": "PostPublishableApiKeysPublishableApiKeyRevoke",
-        "summary": "Revoke PublishableApiKey",
-        "description": "Revokes a PublishableApiKey.",
+        "summary": "Revoke a Publishable API Key",
+        "description": "Revoke a Publishable API Key. Revoking the publishable API Key can't be undone, and the key can't be used in future requests.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the PublishableApiKey.",
+            "description": "The ID of the Publishable API Key.",
             "schema": {
               "type": "string"
             }
@@ -16395,7 +16641,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/publishable-api-keys/{pka_id}/revoke' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/publishable-api-keys/{id}/revoke' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -16444,15 +16690,15 @@
     "/admin/publishable-api-keys/{id}/sales-channels": {
       "get": {
         "operationId": "GetPublishableApiKeySalesChannels",
-        "summary": "List SalesChannels",
-        "description": "List PublishableApiKey's SalesChannels",
+        "summary": "List Sales Channels",
+        "description": "List the sales channels associated with a publishable API key. The sales channels can be filtered by fields such as `q`.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Publishable Api Key.",
+            "description": "The ID of the publishable API key.",
             "schema": {
               "type": "string"
             }
@@ -16460,7 +16706,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching sales channels' names and descriptions.",
+            "description": "query to search sales channels' names and descriptions.",
             "schema": {
               "type": "string"
             }
@@ -16479,7 +16725,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/publishable-api-keys/{pka_id}/sales-channels' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/publishable-api-keys/{id}/sales-channels' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -16528,8 +16774,8 @@
     "/admin/publishable-api-keys/{id}/sales-channels/batch": {
       "post": {
         "operationId": "PostPublishableApiKeySalesChannelsChannelsBatch",
-        "summary": "Add SalesChannels",
-        "description": "Assign a batch of sales channels to a publishable api key.",
+        "summary": "Add Sales Channels",
+        "description": "Assign a list of sales channels to a publishable API key.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -16558,12 +16804,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.publishableApiKeys.addSalesChannelsBatch(publishableApiKeyId, {\n  sales_channel_ids: [\n    {\n      id: channel_id\n    }\n  ]\n})\n.then(({ publishable_api_key }) => {\n  console.log(publishable_api_key.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.publishableApiKeys.addSalesChannelsBatch(publishableApiKeyId, {\n  sales_channel_ids: [\n    {\n      id: channelId\n    }\n  ]\n})\n.then(({ publishable_api_key }) => {\n  console.log(publishable_api_key.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/publishable-api-keys/{pak_id}/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"sales_channel_ids\": [\n      {\n        \"id\": \"{sales_channel_id}\"\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/publishable-api-keys/{pak_id}/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"sales_channel_ids\": [\n      {\n        \"id\": \"{sales_channel_id}\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -16610,15 +16856,15 @@
       },
       "delete": {
         "operationId": "DeletePublishableApiKeySalesChannelsChannelsBatch",
-        "summary": "Delete SalesChannels",
-        "description": "Remove a batch of sales channels from a publishable api key.",
+        "summary": "Remove Sales Channels",
+        "description": "Remove a list of sales channels from a publishable API key. This doesn't delete the sales channels and only removes the association between them and the publishable API key.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Publishable Api Key.",
+            "description": "The ID of the Publishable API Key.",
             "schema": {
               "type": "string"
             }
@@ -16640,12 +16886,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.publishableApiKeys.deleteSalesChannelsBatch(publishableApiKeyId, {\n  sales_channel_ids: [\n    {\n      id: channel_id\n    }\n  ]\n})\n.then(({ publishable_api_key }) => {\n  console.log(publishable_api_key.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.publishableApiKeys.deleteSalesChannelsBatch(publishableApiKeyId, {\n  sales_channel_ids: [\n    {\n      id: channelId\n    }\n  ]\n})\n.then(({ publishable_api_key }) => {\n  console.log(publishable_api_key.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/publishable-api-keys/{pka_id}/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"sales_channel_ids\": [\n      {\n        \"id\": \"{sales_channel_id}\"\n      }\n    ]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/publishable-api-keys/{id}/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"sales_channel_ids\": [\n      {\n        \"id\": \"{sales_channel_id}\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -16695,7 +16941,7 @@
       "get": {
         "operationId": "GetRegions",
         "summary": "List Regions",
-        "description": "Retrieves a list of Regions.",
+        "description": "Retrieve a list of Regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated",
         "x-authenticated": true,
         "parameters": [
           {
@@ -16706,7 +16952,7 @@
               "default": 50
             },
             "required": false,
-            "description": "limit the number of regions in response"
+            "description": "Limit the number of regions returned."
           },
           {
             "in": "query",
@@ -16716,34 +16962,100 @@
               "default": 0
             },
             "required": false,
-            "description": "Offset of regions in response (used for pagination)"
+            "description": "The number of regions to skip when retrieving the regions."
           },
           {
             "in": "query",
             "name": "created_at",
-            "schema": {
-              "type": "object"
-            },
             "required": false,
-            "description": "Date comparison for when resulting region was created, i.e. less than, greater than etc."
+            "description": "Filter by a creation date range.",
+            "schema": {
+              "type": "object",
+              "properties": {
+                "lt": {
+                  "type": "string",
+                  "description": "filter by dates less than this date",
+                  "format": "date"
+                },
+                "gt": {
+                  "type": "string",
+                  "description": "filter by dates greater than this date",
+                  "format": "date"
+                },
+                "lte": {
+                  "type": "string",
+                  "description": "filter by dates less than or equal to this date",
+                  "format": "date"
+                },
+                "gte": {
+                  "type": "string",
+                  "description": "filter by dates greater than or equal to this date",
+                  "format": "date"
+                }
+              }
+            }
           },
           {
             "in": "query",
             "name": "updated_at",
-            "schema": {
-              "type": "object"
-            },
             "required": false,
-            "description": "Date comparison for when resulting region was updated, i.e. less than, greater than etc."
+            "description": "Filter by an update date range.",
+            "schema": {
+              "type": "object",
+              "properties": {
+                "lt": {
+                  "type": "string",
+                  "description": "filter by dates less than this date",
+                  "format": "date"
+                },
+                "gt": {
+                  "type": "string",
+                  "description": "filter by dates greater than this date",
+                  "format": "date"
+                },
+                "lte": {
+                  "type": "string",
+                  "description": "filter by dates less than or equal to this date",
+                  "format": "date"
+                },
+                "gte": {
+                  "type": "string",
+                  "description": "filter by dates greater than or equal to this date",
+                  "format": "date"
+                }
+              }
+            }
           },
           {
             "in": "query",
             "name": "deleted_at",
-            "schema": {
-              "type": "object"
-            },
             "required": false,
-            "description": "Date comparison for when resulting region was deleted, i.e. less than, greater than etc."
+            "description": "Filter by a deletion date range.",
+            "schema": {
+              "type": "object",
+              "properties": {
+                "lt": {
+                  "type": "string",
+                  "description": "filter by dates less than this date",
+                  "format": "date"
+                },
+                "gt": {
+                  "type": "string",
+                  "description": "filter by dates greater than this date",
+                  "format": "date"
+                },
+                "lte": {
+                  "type": "string",
+                  "description": "filter by dates less than or equal to this date",
+                  "format": "date"
+                },
+                "gte": {
+                  "type": "string",
+                  "description": "filter by dates greater than or equal to this date",
+                  "format": "date"
+                }
+              }
+            }
           }
         ],
         "x-codegen": {
@@ -16759,7 +17071,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/regions' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/regions' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -16807,7 +17119,7 @@
       "post": {
         "operationId": "PostRegions",
         "summary": "Create a Region",
-        "description": "Creates a Region",
+        "description": "Create a Region.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -16825,12 +17137,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.create({\n  name: 'Europe',\n  currency_code: 'eur',\n  tax_rate: 0,\n  payment_providers: [\n    'manual'\n  ],\n  fulfillment_providers: [\n    'manual'\n  ],\n  countries: [\n    'DK'\n  ]\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.create({\n  name: \"Europe\",\n  currency_code: \"eur\",\n  tax_rate: 0,\n  payment_providers: [\n    \"manual\"\n  ],\n  fulfillment_providers: [\n    \"manual\"\n  ],\n  countries: [\n    \"DK\"\n  ]\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/regions' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Europe\",\n    \"currency_code\": \"eur\",\n    \"tax_rate\": 0,\n    \"payment_providers\": [\n      \"manual\"\n    ],\n    \"fulfillment_providers\": [\n      \"manual\"\n    ],\n    \"countries\": [\n      \"DK\"\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/regions' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Europe\",\n    \"currency_code\": \"eur\",\n    \"tax_rate\": 0,\n    \"payment_providers\": [\n      \"manual\"\n    ],\n    \"fulfillment_providers\": [\n      \"manual\"\n    ],\n    \"countries\": [\n      \"DK\"\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -16880,7 +17192,7 @@
       "get": {
         "operationId": "GetRegionsRegion",
         "summary": "Get a Region",
-        "description": "Retrieves a Region.",
+        "description": "Retrieve a Region's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -16900,12 +17212,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.retrieve(region_id)\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.retrieve(regionId)\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/regions/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/regions/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -16953,7 +17265,7 @@
       "post": {
         "operationId": "PostRegionsRegion",
         "summary": "Update a Region",
-        "description": "Updates a Region",
+        "description": "Update a Region's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -16982,12 +17294,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.update(region_id, {\n  name: 'Europe'\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.update(regionId, {\n  name: \"Europe\"\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/regions/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Europe\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/regions/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Europe\"\n}'\n"
           }
         ],
         "security": [
@@ -17035,7 +17347,7 @@
       "delete": {
         "operationId": "DeleteRegionsRegion",
         "summary": "Delete a Region",
-        "description": "Deletes a Region.",
+        "description": "Delete a Region. Associated resources, such as providers or currencies are not deleted. Associated tax rates are deleted.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -17055,12 +17367,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.delete(region_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.delete(regionId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/regions/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -17110,7 +17422,7 @@
       "post": {
         "operationId": "PostRegionsRegionCountries",
         "summary": "Add Country",
-        "description": "Adds a Country to the list of Countries in a Region",
+        "description": "Add a Country to the list of Countries in a Region",
         "x-authenticated": true,
         "parameters": [
           {
@@ -17139,12 +17451,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.addCountry(region_id, {\n  country_code: 'dk'\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.addCountry(regionId, {\n  country_code: \"dk\"\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/regions/{region_id}/countries' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"country_code\": \"dk\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/regions/{region_id}/countries' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"country_code\": \"dk\"\n}'\n"
           }
         ],
         "security": [
@@ -17193,9 +17505,9 @@
     "/admin/regions/{id}/countries/{country_code}": {
       "delete": {
         "operationId": "PostRegionsRegionCountriesCountry",
-        "summary": "Delete Country",
+        "summary": "Remove Country",
         "x-authenticated": true,
-        "description": "Removes a Country from the list of Countries in a Region",
+        "description": "Remove a Country from the list of Countries in a Region. The country will still be available in the system, and it can be used in other regions.",
         "parameters": [
           {
             "in": "path",
@@ -17227,12 +17539,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.deleteCountry(region_id, 'dk')\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.deleteCountry(regionId, \"dk\")\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}/countries/dk' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/regions/{id}/countries/{country_code}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -17282,7 +17594,7 @@
       "get": {
         "operationId": "GetRegionsRegionFulfillmentOptions",
         "summary": "List Fulfillment Options",
-        "description": "Gathers all the fulfillment options available to in the Region.",
+        "description": "Retrieve a list of fulfillment options available in a Region.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -17302,12 +17614,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.retrieveFulfillmentOptions(region_id)\n.then(({ fulfillment_options }) => {\n  console.log(fulfillment_options.length);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.retrieveFulfillmentOptions(regionId)\n.then(({ fulfillment_options }) => {\n  console.log(fulfillment_options.length);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/regions/{id}/fulfillment-options' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/regions/{id}/fulfillment-options' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -17357,7 +17669,7 @@
       "post": {
         "operationId": "PostRegionsRegionFulfillmentProviders",
         "summary": "Add Fulfillment Provider",
-        "description": "Adds a Fulfillment Provider to a Region",
+        "description": "Add a Fulfillment Provider to the list of fulfullment providers in a Region.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -17386,12 +17698,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.addFulfillmentProvider(region_id, {\n  provider_id: 'manual'\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.addFulfillmentProvider(regionId, {\n  provider_id: \"manual\"\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"provider_id\": \"manual\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"provider_id\": \"manual\"\n}'\n"
           }
         ],
         "security": [
@@ -17440,8 +17752,8 @@
     "/admin/regions/{id}/fulfillment-providers/{provider_id}": {
       "delete": {
         "operationId": "PostRegionsRegionFulfillmentProvidersProvider",
-        "summary": "Del. Fulfillment Provider",
-        "description": "Removes a Fulfillment Provider.",
+        "summary": "Remove Fulfillment Provider",
+        "description": "Remove a Fulfillment Provider from a Region. The fulfillment provider will still be available for usage in other regions.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -17470,12 +17782,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.deleteFulfillmentProvider(region_id, 'manual')\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.deleteFulfillmentProvider(regionId, \"manual\")\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers/manual' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers/{provider_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -17525,7 +17837,7 @@
       "post": {
         "operationId": "PostRegionsRegionPaymentProviders",
         "summary": "Add Payment Provider",
-        "description": "Adds a Payment Provider to a Region",
+        "description": "Add a Payment Provider to the list of payment providers in a Region.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -17554,12 +17866,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.addPaymentProvider(region_id, {\n  provider_id: 'manual'\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.addPaymentProvider(regionId, {\n  provider_id: \"manual\"\n})\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/regions/{id}/payment-providers' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"provider_id\": \"manual\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/regions/{id}/payment-providers' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"provider_id\": \"manual\"\n}'\n"
           }
         ],
         "security": [
@@ -17608,8 +17920,8 @@
     "/admin/regions/{id}/payment-providers/{provider_id}": {
       "delete": {
         "operationId": "PostRegionsRegionPaymentProvidersProvider",
-        "summary": "Delete Payment Provider",
-        "description": "Removes a Payment Provider.",
+        "summary": "Remove Payment Provider",
+        "description": "Remove a Payment Provider from a Region. The payment provider will still be available for usage in other regions.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -17638,12 +17950,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.deletePaymentProvider(region_id, 'manual')\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.regions.deletePaymentProvider(regionId, \"manual\")\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}/payment-providers/manual' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/regions/{id}/payment-providers/{provider_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -17693,7 +18005,7 @@
       "get": {
         "operationId": "GetReservations",
         "summary": "List Reservations",
-        "description": "Retrieve a list of Reservations.",
+        "description": "Retrieve a list of Reservations. The reservations can be filtered by fields such as `location_id` or `quantity`. The reservations can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -17701,7 +18013,7 @@
             "name": "location_id",
             "style": "form",
             "explode": false,
-            "description": "Location ids to search for.",
+            "description": "Filter by location ID",
             "schema": {
               "type": "array",
               "items": {
@@ -17714,7 +18026,7 @@
             "name": "inventory_item_id",
             "style": "form",
             "explode": false,
-            "description": "Inventory Item ids to search for.",
+            "description": "Filter by inventory item ID.",
             "schema": {
               "type": "array",
               "items": {
@@ -17727,7 +18039,7 @@
             "name": "line_item_id",
             "style": "form",
             "explode": false,
-            "description": "Line Item ids to search for.",
+            "description": "Filter by line item ID.",
             "schema": {
               "type": "array",
               "items": {
@@ -17764,11 +18076,12 @@
           {
             "in": "query",
             "name": "description",
-            "description": "A param for search reservation descriptions",
+            "description": "Filter by description.",
             "schema": {
               "oneOf": [
                 {
-                  "type": "string"
+                  "type": "string",
+                  "description": "description value to filter by."
                 },
                 {
                   "type": "object",
@@ -17793,7 +18106,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting reservations were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -17823,7 +18136,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many Reservations to skip in the result.",
+            "description": "The number of reservations to skip when retrieving the reservations.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -17832,7 +18145,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "Limit the number of Reservations returned.",
+            "description": "Limit the number of reservations returned.",
             "schema": {
               "type": "integer",
               "default": 20
@@ -17841,7 +18154,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in the product category.",
+            "description": "Comma-separated relations that should be expanded in the returned reservations.",
             "schema": {
               "type": "string"
             }
@@ -17849,7 +18162,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in the product category.",
+            "description": "Comma-separated fields that should be included in the returned reservations.",
             "schema": {
               "type": "string"
             }
@@ -17868,7 +18181,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/product-categories' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/product-categories' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -17916,7 +18229,7 @@
       "post": {
         "operationId": "PostReservations",
         "summary": "Create a Reservation",
-        "description": "Create a Reservation which can be associated with any resource as required.",
+        "description": "Create a Reservation which can be associated with any resource, such as an order's line item.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -17931,12 +18244,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.reservations.create({\n  line_item_id: 'item_123',\n  location_id: 'loc_123',\n  inventory_item_id: 'iitem_123',\n  quantity: 1\n})\n.then(({ reservation }) => {\n  console.log(reservation.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.reservations.create({\n  line_item_id: \"item_123\",\n  location_id: \"loc_123\",\n  inventory_item_id: \"iitem_123\",\n  quantity: 1\n})\n.then(({ reservation }) => {\n  console.log(reservation.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/reservations' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"line_item_id\": \"item_123\",\n    \"location_id\": \"loc_123\",\n    \"inventory_item_id\": \"iitem_123\",\n    \"quantity\": 1\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/reservations' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"line_item_id\": \"item_123\",\n    \"location_id\": \"loc_123\",\n    \"inventory_item_id\": \"iitem_123\",\n    \"quantity\": 1\n}'\n"
           }
         ],
         "security": [
@@ -17986,14 +18299,14 @@
       "get": {
         "operationId": "GetReservationsReservation",
         "summary": "Get a Reservation",
-        "description": "Retrieves a single reservation using its ID",
+        "description": "Retrieve a reservation's details.'",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the reservation to retrieve.",
+            "description": "The ID of the reservation.",
             "schema": {
               "type": "string"
             }
@@ -18008,7 +18321,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/reservations/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/reservations/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -18056,14 +18369,14 @@
       "post": {
         "operationId": "PostReservationsReservation",
         "summary": "Update a Reservation",
-        "description": "Updates a Reservation which can be associated with any resource as required.",
+        "description": "Update a Reservation's details.'",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Reservation to update.",
+            "description": "The ID of the Reservation.",
             "schema": {
               "type": "string"
             }
@@ -18087,7 +18400,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/reservations/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n   \"quantity\": 3,\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/reservations/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n   \"quantity\": 3,\n}'\n"
           }
         ],
         "security": [
@@ -18135,7 +18448,7 @@
       "delete": {
         "operationId": "DeleteReservationsReservation",
         "summary": "Delete a Reservation",
-        "description": "Deletes a Reservation.",
+        "description": "Delete a Reservation. Associated resources, such as the line item, will not be deleted.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -18160,7 +18473,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/reservations/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/reservations/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -18210,7 +18523,7 @@
       "get": {
         "operationId": "GetReturnReasons",
         "summary": "List Return Reasons",
-        "description": "Retrieves a list of Return Reasons.",
+        "description": "Retrieve a list of Return Reasons.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "list"
@@ -18224,7 +18537,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/return-reasons' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/return-reasons' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -18272,7 +18585,7 @@
       "post": {
         "operationId": "PostReturnReasons",
         "summary": "Create a Return Reason",
-        "description": "Creates a Return Reason",
+        "description": "Create a Return Reason.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -18290,12 +18603,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returnReasons.create({\n  label: 'Damaged',\n  value: 'damaged'\n})\n.then(({ return_reason }) => {\n  console.log(return_reason.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returnReasons.create({\n  label: \"Damaged\",\n  value: \"damaged\"\n})\n.then(({ return_reason }) => {\n  console.log(return_reason.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/return-reasons' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"label\": \"Damaged\",\n    \"value\": \"damaged\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/return-reasons' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"label\": \"Damaged\",\n    \"value\": \"damaged\"\n}'\n"
           }
         ],
         "security": [
@@ -18345,7 +18658,7 @@
       "get": {
         "operationId": "GetReturnReasonsReason",
         "summary": "Get a Return Reason",
-        "description": "Retrieves a Return Reason.",
+        "description": "Retrieve a Return Reason's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -18365,12 +18678,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returnReasons.retrieve(return_reason_id)\n.then(({ return_reason }) => {\n  console.log(return_reason.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returnReasons.retrieve(returnReasonId)\n.then(({ return_reason }) => {\n  console.log(return_reason.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/return-reasons/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/return-reasons/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -18418,7 +18731,7 @@
       "post": {
         "operationId": "PostReturnReasonsReason",
         "summary": "Update a Return Reason",
-        "description": "Updates a Return Reason",
+        "description": "Update a Return Reason's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -18447,12 +18760,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returnReasons.update(return_reason_id, {\n  label: 'Damaged'\n})\n.then(({ return_reason }) => {\n  console.log(return_reason.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returnReasons.update(returnReasonId, {\n  label: \"Damaged\"\n})\n.then(({ return_reason }) => {\n  console.log(return_reason.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/return-reasons/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"label\": \"Damaged\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/return-reasons/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"label\": \"Damaged\"\n}'\n"
           }
         ],
         "security": [
@@ -18500,7 +18813,7 @@
       "delete": {
         "operationId": "DeleteReturnReason",
         "summary": "Delete a Return Reason",
-        "description": "Deletes a return reason.",
+        "description": "Delete a return reason.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -18520,12 +18833,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returnReasons.delete(return_reason_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returnReasons.delete(returnReasonId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/return-reasons/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/return-reasons/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -18575,12 +18888,12 @@
       "get": {
         "operationId": "GetReturns",
         "summary": "List Returns",
-        "description": "Retrieves a list of Returns",
+        "description": "Retrieve a list of Returns. The returns can be paginated.",
         "parameters": [
           {
             "in": "query",
             "name": "limit",
-            "description": "The upper limit for the amount of responses returned.",
+            "description": "Limit the number of Returns returned.",
             "schema": {
               "type": "number",
               "default": "50"
@@ -18589,7 +18902,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The offset of the list returned.",
+            "description": "The number of Returns to skip when retrieving the Returns.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -18609,7 +18922,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/returns' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/returns' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -18659,7 +18972,7 @@
       "post": {
         "operationId": "PostReturnsReturnCancel",
         "summary": "Cancel a Return",
-        "description": "Registers a Return as canceled.",
+        "description": "Registers a Return as canceled. The return can be associated with an order, claim, or swap.",
         "parameters": [
           {
             "in": "path",
@@ -18678,12 +18991,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returns.cancel(return_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returns.cancel(returnId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/returns/{id}/cancel' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/returns/{id}/cancel' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -18733,7 +19046,7 @@
       "post": {
         "operationId": "PostReturnsReturnReceive",
         "summary": "Receive a Return",
-        "description": "Registers a Return as received. Updates statuses on Orders and Swaps accordingly.",
+        "description": "Mark a Return as received. This also updates the status of associated order, claim, or swap accordingly.",
         "parameters": [
           {
             "in": "path",
@@ -18761,12 +19074,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returns.receive(return_id, {\n  items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then((data) => {\n  console.log(data.return.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.returns.receive(returnId, {\n  items: [\n    {\n      item_id,\n      quantity: 1\n    }\n  ]\n})\n.then((data) => {\n  console.log(data.return.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/returns/{id}/receive' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"items\": [\n      {\n        \"item_id\": \"asafg\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/returns/{id}/receive' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"items\": [\n      {\n        \"item_id\": \"asafg\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -18816,13 +19129,13 @@
       "get": {
         "operationId": "GetSalesChannels",
         "summary": "List Sales Channels",
-        "description": "Retrieves a list of sales channels",
+        "description": "Retrieve a list of sales channels. The sales channels can be filtered by fields such as `q` or `name`. The sales channels can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "id",
-            "description": "ID of the sales channel",
+            "description": "Filter by a sales channel ID.",
             "schema": {
               "type": "string"
             }
@@ -18830,7 +19143,7 @@
           {
             "in": "query",
             "name": "name",
-            "description": "Name of the sales channel",
+            "description": "Filter by name.",
             "schema": {
               "type": "string"
             }
@@ -18838,7 +19151,7 @@
           {
             "in": "query",
             "name": "description",
-            "description": "Description of the sales channel",
+            "description": "Filter by description.",
             "schema": {
               "type": "string"
             }
@@ -18846,7 +19159,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching sales channels' names and descriptions.",
+            "description": "term used to search sales channels' names and descriptions.",
             "schema": {
               "type": "string"
             }
@@ -18854,7 +19167,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "The field to order the results by.",
+            "description": "A sales-channel field to sort-order the retrieved sales channels by.",
             "schema": {
               "type": "string"
             }
@@ -18862,7 +19175,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting collections were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -18892,7 +19205,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting collections were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -18922,7 +19235,7 @@
           {
             "in": "query",
             "name": "deleted_at",
-            "description": "Date comparison for when resulting collections were deleted.",
+            "description": "Filter by a deletion date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -18952,7 +19265,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many sales channels to skip in the result.",
+            "description": "The number of sales channels to skip when retrieving the sales channels.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -18970,7 +19283,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each sales channel of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned sales channels.",
             "schema": {
               "type": "string"
             }
@@ -18978,7 +19291,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each sales channel of the result.",
+            "description": "Comma-separated fields that should be included in the returned sales channels.",
             "schema": {
               "type": "string"
             }
@@ -18997,7 +19310,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/sales-channels' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/sales-channels' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -19045,7 +19358,7 @@
       "post": {
         "operationId": "PostSalesChannels",
         "summary": "Create a Sales Channel",
-        "description": "Creates a Sales Channel.",
+        "description": "Create a Sales Channel.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -19063,12 +19376,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.create({\n  name: 'App',\n  description: 'Mobile app'\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.create({\n  name: \"App\",\n  description: \"Mobile app\"\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/sales-channels' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"App\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/sales-channels' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"App\"\n}'\n"
           }
         ],
         "security": [
@@ -19118,7 +19431,7 @@
       "get": {
         "operationId": "GetSalesChannelsSalesChannel",
         "summary": "Get a Sales Channel",
-        "description": "Retrieves the sales channel.",
+        "description": "Retrieve a sales channel's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19138,12 +19451,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.retrieve(sales_channel_id)\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.retrieve(salesChannelId)\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/sales-channels/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/sales-channels/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -19191,7 +19504,7 @@
       "post": {
         "operationId": "PostSalesChannelsSalesChannel",
         "summary": "Update a Sales Channel",
-        "description": "Updates a Sales Channel.",
+        "description": "Update a Sales Channel's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19220,12 +19533,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.update(sales_channel_id, {\n  name: 'App'\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.update(salesChannelId, {\n  name: \"App\"\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/sales-channels/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"App\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/sales-channels/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"App\"\n}'\n"
           }
         ],
         "security": [
@@ -19273,7 +19586,7 @@
       "delete": {
         "operationId": "DeleteSalesChannelsSalesChannel",
         "summary": "Delete a Sales Channel",
-        "description": "Deletes the sales channel.",
+        "description": "Delete a sales channel. Associated products, stock locations, and other resources are not deleted.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19293,12 +19606,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.delete(sales_channel_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.delete(salesChannelId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/sales-channels/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/sales-channels/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -19347,8 +19660,8 @@
     "/admin/sales-channels/{id}/products/batch": {
       "post": {
         "operationId": "PostSalesChannelsChannelProductsBatch",
-        "summary": "Add Products",
-        "description": "Assign a batch of product to a sales channel.",
+        "summary": "Add Products to Sales Channel",
+        "description": "Add a list of products to a sales channel.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19377,12 +19690,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.addProducts(sales_channel_id, {\n  product_ids: [\n    {\n      id: product_id\n    }\n  ]\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.addProducts(salesChannelId, {\n  product_ids: [\n    {\n      id: productId\n    }\n  ]\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/sales-channels/afasf/products/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n      {\n        \"id\": \"{product_id}\"\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/sales-channels/{id}/products/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n      {\n        \"id\": \"{product_id}\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -19429,8 +19742,8 @@
       },
       "delete": {
         "operationId": "DeleteSalesChannelsChannelProductsBatch",
-        "summary": "Delete Products",
-        "description": "Remove a list of products from a sales channel.",
+        "summary": "Remove Products from Sales Channel",
+        "description": "Remove a list of products from a sales channel. This does not delete the product. It only removes the association between the product and the sales channel.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19459,12 +19772,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.removeProducts(sales_channel_id, {\n  product_ids: [\n    {\n      id: product_id\n    }\n  ]\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.removeProducts(salesChannelId, {\n  product_ids: [\n    {\n      id: productId\n    }\n  ]\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/sales-channels/{id}/products/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n      {\n        \"id\": \"{product_id}\"\n      }\n    ]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/sales-channels/{id}/products/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"product_ids\": [\n      {\n        \"id\": \"{product_id}\"\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -19514,7 +19827,7 @@
       "post": {
         "operationId": "PostSalesChannelsSalesChannelStockLocation",
         "summary": "Associate a Stock Location",
-        "description": "Associates a stock location with a Sales Channel.",
+        "description": "Associate a stock location with a Sales Channel.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19543,12 +19856,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.addLocation(salesChannelId, {\n  location_id: 'loc_123'\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.addLocation(salesChannelId, {\n  location_id: \"loc_123\"\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/sales-channels/{id}/stock-locations' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"locaton_id\": \"loc_123\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/sales-channels/{id}/stock-locations' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"locaton_id\": \"loc_123\"\n}'\n"
           }
         ],
         "security": [
@@ -19595,8 +19908,8 @@
       },
       "delete": {
         "operationId": "DeleteSalesChannelsSalesChannelStockLocation",
-        "summary": "Remove a Stock Location Association",
-        "description": "Removes a stock location from a Sales Channel.",
+        "summary": "Remove Stock Location from Sales Channels.",
+        "description": "Remove a stock location from a Sales Channel. This only removes the association between the stock location and the sales channel. It does not delete the stock location.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19625,12 +19938,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.removeLocation(salesChannelId, {\n  location_id: 'loc_id'\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.salesChannels.removeLocation(salesChannelId, {\n  location_id: \"loc_id\"\n})\n.then(({ sales_channel }) => {\n  console.log(sales_channel.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/sales-channels/{id}/stock-locations' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"locaton_id\": \"loc_id\"\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/sales-channels/{id}/stock-locations' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"locaton_id\": \"loc_id\"\n}'\n"
           }
         ],
         "security": [
@@ -19680,7 +19993,7 @@
       "get": {
         "operationId": "GetShippingOptions",
         "summary": "List Shipping Options",
-        "description": "Retrieves a list of Shipping Options.",
+        "description": "Retrieve a list of Shipping Options. The shipping options can be filtered by fields such as `region_id` or `is_return`.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19689,15 +20002,15 @@
             "schema": {
               "type": "string"
             },
-            "description": "Region ID to fetch options from"
+            "description": "Filter by a region ID."
           },
           {
             "in": "query",
             "name": "is_return",
+            "description": "Filter by whether the shipping option is used for returns or orders.",
             "schema": {
               "type": "boolean"
-            },
-            "description": "Flag for fetching return options only"
+            }
           },
           {
             "in": "query",
@@ -19705,7 +20018,7 @@
             "schema": {
               "type": "boolean"
             },
-            "description": "Flag for fetching admin specific options"
+            "description": "Filter by whether the shipping option is used only by admins or not."
           }
         ],
         "x-codegen": {
@@ -19721,7 +20034,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/shipping-options' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/shipping-options' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -19769,7 +20082,7 @@
       "post": {
         "operationId": "PostShippingOptions",
         "summary": "Create Shipping Option",
-        "description": "Creates a Shipping Option",
+        "description": "Create a Shipping Option.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -19787,12 +20100,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingOptions.create({\n  name: 'PostFake',\n  region_id: \"saasf\",\n  provider_id: \"manual\",\n  data: {\n  },\n  price_type: 'flat_rate'\n})\n.then(({ shipping_option }) => {\n  console.log(shipping_option.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingOptions.create({\n  name: \"PostFake\",\n  region_id,\n  provider_id,\n  data: {\n  },\n  price_type: \"flat_rate\"\n})\n.then(({ shipping_option }) => {\n  console.log(shipping_option.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/shipping-options' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"PostFake\",\n    \"region_id\": \"afasf\",\n    \"provider_id\": \"manual\",\n    \"data\": {},\n    \"price_type\": \"flat_rate\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/shipping-options' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"PostFake\",\n    \"region_id\": \"afasf\",\n    \"provider_id\": \"manual\",\n    \"data\": {},\n    \"price_type\": \"flat_rate\"\n}'\n"
           }
         ],
         "security": [
@@ -19842,7 +20155,7 @@
       "get": {
         "operationId": "GetShippingOptionsOption",
         "summary": "Get a Shipping Option",
-        "description": "Retrieves a Shipping Option.",
+        "description": "Retrieve a Shipping Option's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19862,12 +20175,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingOptions.retrieve(option_id)\n.then(({ shipping_option }) => {\n  console.log(shipping_option.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingOptions.retrieve(optionId)\n.then(({ shipping_option }) => {\n  console.log(shipping_option.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/shipping-options/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/shipping-options/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -19915,7 +20228,7 @@
       "post": {
         "operationId": "PostShippingOptionsOption",
         "summary": "Update Shipping Option",
-        "description": "Updates a Shipping Option",
+        "description": "Update a Shipping Option's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -19944,12 +20257,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingOptions.update(option_id, {\n  name: 'PostFake',\n  requirements: [\n    {\n      id,\n      type: 'max_subtotal',\n      amount: 1000\n    }\n  ]\n})\n.then(({ shipping_option }) => {\n  console.log(shipping_option.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingOptions.update(optionId, {\n  name: \"PostFake\",\n  requirements: [\n    {\n      id,\n      type: \"max_subtotal\",\n      amount: 1000\n    }\n  ]\n})\n.then(({ shipping_option }) => {\n  console.log(shipping_option.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/shipping-options/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"requirements\": [\n      {\n        \"type\": \"max_subtotal\",\n        \"amount\": 1000\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/shipping-options/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"requirements\": [\n      {\n        \"type\": \"max_subtotal\",\n        \"amount\": 1000\n      }\n    ]\n}'\n"
           }
         ],
         "security": [
@@ -19996,8 +20309,8 @@
       },
       "delete": {
         "operationId": "DeleteShippingOptionsOption",
-        "summary": "Delete a Shipping Option",
-        "description": "Deletes a Shipping Option.",
+        "summary": "Delete Shipping Option",
+        "description": "Delete a Shipping Option. Once deleted, it can't be used when creating orders or returns.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -20017,12 +20330,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingOptions.delete(option_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingOptions.delete(optionId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/shipping-options/{option_id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/shipping-options/{option_id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -20072,7 +20385,7 @@
       "get": {
         "operationId": "GetShippingProfiles",
         "summary": "List Shipping Profiles",
-        "description": "Retrieves a list of Shipping Profile.",
+        "description": "Retrieve a list of Shipping Profiles.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "list"
@@ -20086,7 +20399,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/shipping-profiles' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/shipping-profiles' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -20134,7 +20447,7 @@
       "post": {
         "operationId": "PostShippingProfiles",
         "summary": "Create a Shipping Profile",
-        "description": "Creates a Shipping Profile",
+        "description": "Create a Shipping Profile.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -20152,12 +20465,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingProfiles.create({\n  name: 'Large Products'\n})\n.then(({ shipping_profile }) => {\n  console.log(shipping_profile.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingProfiles.create({\n  name: \"Large Products\"\n})\n.then(({ shipping_profile }) => {\n  console.log(shipping_profile.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/shipping-profiles' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Large Products\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/shipping-profiles' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Large Products\"\n}'\n"
           }
         ],
         "security": [
@@ -20207,7 +20520,7 @@
       "get": {
         "operationId": "GetShippingProfilesProfile",
         "summary": "Get a Shipping Profile",
-        "description": "Retrieves a Shipping Profile.",
+        "description": "Retrieve a Shipping Profile's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -20227,12 +20540,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingProfiles.retrieve(profile_id)\n.then(({ shipping_profile }) => {\n  console.log(shipping_profile.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingProfiles.retrieve(profileId)\n.then(({ shipping_profile }) => {\n  console.log(shipping_profile.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/shipping-profiles/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/shipping-profiles/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -20280,7 +20593,7 @@
       "post": {
         "operationId": "PostShippingProfilesProfile",
         "summary": "Update a Shipping Profile",
-        "description": "Updates a Shipping Profile",
+        "description": "Update a Shipping Profile's details.",
         "parameters": [
           {
             "in": "path",
@@ -20308,12 +20621,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingProfiles.update(shipping_profile_id, {\n  name: 'Large Products'\n})\n.then(({ shipping_profile }) => {\n  console.log(shipping_profile.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingProfiles.update(shippingProfileId, {\n  name: 'Large Products'\n})\n.then(({ shipping_profile }) => {\n  console.log(shipping_profile.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/shipping-profiles/{id} \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Large Products\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/shipping-profiles/{id} \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Large Products\"\n}'\n"
           }
         ],
         "security": [
@@ -20361,7 +20674,7 @@
       "delete": {
         "operationId": "DeleteShippingProfilesProfile",
         "summary": "Delete a Shipping Profile",
-        "description": "Deletes a Shipping Profile.",
+        "description": "Delete a Shipping Profile. Associated shipping options are deleted as well.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -20381,12 +20694,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingProfiles.delete(profile_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.shippingProfiles.delete(profileId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/shipping-profiles/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/shipping-profiles/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -20436,13 +20749,13 @@
       "get": {
         "operationId": "GetStockLocations",
         "summary": "List Stock Locations",
-        "description": "Retrieves a list of stock locations",
+        "description": "Retrieve a list of stock locations. The stock locations can be filtered by fields such as `name` or `created_at`. The stock locations can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "id",
-            "description": "ID of the stock location",
+            "description": "Filter by ID.",
             "schema": {
               "type": "string"
             }
@@ -20450,7 +20763,7 @@
           {
             "in": "query",
             "name": "name",
-            "description": "Name of the stock location",
+            "description": "Filter by name.",
             "schema": {
               "type": "string"
             }
@@ -20458,7 +20771,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "The field to order the results by.",
+            "description": "A stock-location field to sort-order the retrieved stock locations by.",
             "schema": {
               "type": "string"
             }
@@ -20466,7 +20779,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting collections were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -20496,7 +20809,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting collections were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -20526,7 +20839,7 @@
           {
             "in": "query",
             "name": "deleted_at",
-            "description": "Date comparison for when resulting collections were deleted.",
+            "description": "Filter by a deletion date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -20556,7 +20869,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many stock locations to skip in the result.",
+            "description": "The number of stock locations to skip when retrieving the stock locations.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -20574,7 +20887,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each stock location of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned stock locations.",
             "schema": {
               "type": "string"
             }
@@ -20582,7 +20895,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each stock location of the result.",
+            "description": "Comma-separated fields that should be included in the returned stock locations.",
             "schema": {
               "type": "string"
             }
@@ -20601,7 +20914,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/stock-locations' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/stock-locations' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -20649,13 +20962,13 @@
       "post": {
         "operationId": "PostStockLocations",
         "summary": "Create a Stock Location",
-        "description": "Creates a Stock Location.",
+        "description": "Create a Stock Location.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned stock location.",
             "schema": {
               "type": "string"
             }
@@ -20663,7 +20976,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned stock location.",
             "schema": {
               "type": "string"
             }
@@ -20685,12 +20998,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.stockLocations.create({\n  name: 'Main Warehouse',\n})\n.then(({ stock_location }) => {\n  console.log(stock_location.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.stockLocations.create({\n  name: \"Main Warehouse\",\n})\n.then(({ stock_location }) => {\n  console.log(stock_location.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/stock-locations' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"App\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/stock-locations' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"App\"\n}'\n"
           }
         ],
         "security": [
@@ -20740,7 +21053,7 @@
       "get": {
         "operationId": "GetStockLocationsStockLocation",
         "summary": "Get a Stock Location",
-        "description": "Retrieves the Stock Location.",
+        "description": "Retrieve a Stock Location's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -20755,7 +21068,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned stock location.",
             "schema": {
               "type": "string"
             }
@@ -20763,7 +21076,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned stock location.",
             "schema": {
               "type": "string"
             }
@@ -20782,7 +21095,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/stock-locations/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n"
+            "source": "curl 'https://medusa-url.com/admin/stock-locations/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n"
           }
         ],
         "security": [
@@ -20812,7 +21125,7 @@
       "post": {
         "operationId": "PostStockLocationsStockLocation",
         "summary": "Update a Stock Location",
-        "description": "Updates a Stock Location.",
+        "description": "Update a Stock Location's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -20827,7 +21140,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "description": "Comma-separated relations that should be expanded in the returned stock location.",
             "schema": {
               "type": "string"
             }
@@ -20835,7 +21148,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "description": "Comma-separated fields that should be included in the returned stock location.",
             "schema": {
               "type": "string"
             }
@@ -20862,7 +21175,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/stock-locations/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Main Warehouse\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/stock-locations/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Main Warehouse\"\n}'\n"
           }
         ],
         "security": [
@@ -20910,14 +21223,14 @@
       "delete": {
         "operationId": "DeleteStockLocationsStockLocation",
         "summary": "Delete a Stock Location",
-        "description": "Delete a Stock Location",
+        "description": "Delete a Stock Location.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the Stock Location to delete.",
+            "description": "The ID of the Stock Location.",
             "schema": {
               "type": "string"
             }
@@ -20927,12 +21240,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.stockLocations.delete(stock_location_id)\n.then(({ id, object, deleted }) => {\n  console.log(id)\n})\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.stockLocations.delete(stockLocationId)\n.then(({ id, object, deleted }) => {\n  console.log(id)\n})\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/stock-locations/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/stock-locations/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -20952,23 +21265,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "properties": {
-                    "id": {
-                      "type": "string",
-                      "description": "The ID of the deleted Stock Location."
-                    },
-                    "object": {
-                      "type": "string",
-                      "description": "The type of the object that was deleted.",
-                      "format": "stock_location"
-                    },
-                    "deleted": {
-                      "type": "boolean",
-                      "description": "Whether or not the Stock Location was deleted.",
-                      "default": true
-                    }
-                  }
+                  "$ref": "#/components/schemas/AdminStockLocationsDeleteRes"
                 }
               }
             }
@@ -20983,7 +21280,7 @@
       "get": {
         "operationId": "GetStore",
         "summary": "Get Store details",
-        "description": "Retrieves the Store details",
+        "description": "Retrieve the Store's details.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "retrieve"
@@ -20997,7 +21294,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/store' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/store' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -21045,7 +21342,7 @@
       "post": {
         "operationId": "PostStore",
         "summary": "Update Store Details",
-        "description": "Updates the Store details",
+        "description": "Update the Store's details.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -21063,12 +21360,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.store.update({\n  name: 'Medusa Store'\n})\n.then(({ store }) => {\n  console.log(store.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.store.update({\n  name: \"Medusa Store\"\n})\n.then(({ store }) => {\n  console.log(store.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/store' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Medusa Store\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/store' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"Medusa Store\"\n}'\n"
           }
         ],
         "security": [
@@ -21118,7 +21415,7 @@
       "post": {
         "operationId": "PostStoreCurrenciesCode",
         "summary": "Add a Currency Code",
-        "description": "Adds a Currency Code to the available currencies.",
+        "description": "Add a Currency Code to the available currencies in a store. This does not create new currencies, as currencies are defined within the Medusa backend. To create a currency, you can create a migration that inserts the currency into the database.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -21142,12 +21439,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.store.addCurrency('eur')\n.then(({ store }) => {\n  console.log(store.currencies);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.store.addCurrency(\"eur\")\n.then(({ store }) => {\n  console.log(store.currencies);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/store/currencies/eur' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/store/currencies/{currency_code}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -21194,8 +21491,8 @@
       },
       "delete": {
         "operationId": "DeleteStoreCurrenciesCode",
-        "summary": "Delete a Currency Code",
-        "description": "Removes a Currency Code from the available currencies.",
+        "summary": "Remove a Currency",
+        "description": "Remove a Currency Code from the available currencies in a store. This does not completely delete the currency and it can be added again later to the store.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -21219,12 +21516,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.store.deleteCurrency('eur')\n.then(({ store }) => {\n  console.log(store.currencies);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.store.deleteCurrency(\"eur\")\n.then(({ store }) => {\n  console.log(store.currencies);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/store/currencies/eur' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/store/currencies/{currency_code}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -21274,7 +21571,7 @@
       "get": {
         "operationId": "GetStorePaymentProviders",
         "summary": "List Payment Providers",
-        "description": "Retrieves the configured Payment Providers",
+        "description": "Retrieve a list of available Payment Providers in a store.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "listPaymentProviders"
@@ -21288,7 +21585,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/store/payment-providers' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/store/payment-providers' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -21338,7 +21635,7 @@
       "get": {
         "operationId": "GetStoreTaxProviders",
         "summary": "List Tax Providers",
-        "description": "Retrieves the configured Tax Providers",
+        "description": "Retrieve a list of available Tax Providers in a store.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "listTaxProviders"
@@ -21352,7 +21649,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/store/tax-providers' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/store/tax-providers' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -21402,12 +21699,12 @@
       "get": {
         "operationId": "GetSwaps",
         "summary": "List Swaps",
-        "description": "Retrieves a list of Swaps.",
+        "description": "Retrieve a list of Swaps. The swaps can be paginated.",
         "parameters": [
           {
             "in": "query",
             "name": "limit",
-            "description": "The upper limit for the amount of responses returned.",
+            "description": "Limit the number of swaps returned.",
             "schema": {
               "type": "number",
               "default": "50"
@@ -21416,7 +21713,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The offset of the list returned.",
+            "description": "The number of swaps to skip when retrieving the swaps.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -21437,7 +21734,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/swaps' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/swaps' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -21487,7 +21784,7 @@
       "get": {
         "operationId": "GetSwapsSwap",
         "summary": "Get a Swap",
-        "description": "Retrieves a Swap.",
+        "description": "Retrieve a Swap's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -21507,12 +21804,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.swaps.retrieve(swap_id)\n.then(({ swap }) => {\n  console.log(swap.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.swaps.retrieve(swapId)\n.then(({ swap }) => {\n  console.log(swap.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/swaps/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/swaps/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -21562,13 +21859,13 @@
       "get": {
         "operationId": "GetTaxRates",
         "summary": "List Tax Rates",
-        "description": "Retrieves a list of TaxRates",
+        "description": "Retrieve a list of Tax Rates. The tax rates can be filtered by fields such as `name` or `rate`. The tax rates can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "name",
-            "description": "Name of tax rate to retrieve",
+            "description": "Filter by name.",
             "schema": {
               "type": "string"
             }
@@ -21578,7 +21875,7 @@
             "name": "region_id",
             "style": "form",
             "explode": false,
-            "description": "Filter by Region ID",
+            "description": "Filter by Region IDs",
             "schema": {
               "oneOf": [
                 {
@@ -21596,7 +21893,7 @@
           {
             "in": "query",
             "name": "code",
-            "description": "code to search for.",
+            "description": "Filter by code.",
             "schema": {
               "type": "string"
             }
@@ -21639,7 +21936,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many tax rates to skip before retrieving the result.",
+            "description": "The number of tax rates to skip when retrieving the tax rates.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -21657,7 +21954,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in each item.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -21670,7 +21967,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved for each item.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -21694,7 +21991,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/tax-rates' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/tax-rates' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -21742,12 +22039,12 @@
       "post": {
         "operationId": "PostTaxRates",
         "summary": "Create a Tax Rate",
-        "description": "Creates a Tax Rate",
+        "description": "Create a Tax Rate.",
         "parameters": [
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -21760,7 +22057,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -21789,12 +22086,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.create({\n  code: 'TEST',\n  name: 'New Tax Rate',\n  region_id\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.create({\n  code: \"TEST\",\n  name: \"New Tax Rate\",\n  region_id\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/tax-rates' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"code\": \"TEST\",\n    \"name\": \"New Tax Rate\",\n    \"region_id\": \"{region_id}\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/tax-rates' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"code\": \"TEST\",\n    \"name\": \"New Tax Rate\",\n    \"region_id\": \"{region_id}\"\n}'\n"
           }
         ],
         "security": [
@@ -21844,7 +22141,7 @@
       "get": {
         "operationId": "GetTaxRatesTaxRate",
         "summary": "Get a Tax Rate",
-        "description": "Retrieves a TaxRate",
+        "description": "Retrieve a Tax Rate's details.",
         "parameters": [
           {
             "in": "path",
@@ -21858,7 +22155,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -21871,7 +22168,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -21891,12 +22188,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.retrieve(tax_rate_id)\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.retrieve(taxRateId)\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/tax-rates/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/tax-rates/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -21944,7 +22241,7 @@
       "post": {
         "operationId": "PostTaxRatesTaxRate",
         "summary": "Update a Tax Rate",
-        "description": "Updates a Tax Rate",
+        "description": "Update a Tax Rate's details.",
         "parameters": [
           {
             "in": "path",
@@ -21958,7 +22255,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -21971,7 +22268,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22000,12 +22297,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.update(tax_rate_id, {\n  name: 'New Tax Rate'\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.update(taxRateId, {\n  name: \"New Tax Rate\"\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"New Tax Rate\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/tax-rates/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"name\": \"New Tax Rate\"\n}'\n"
           }
         ],
         "security": [
@@ -22053,7 +22350,7 @@
       "delete": {
         "operationId": "DeleteTaxRatesTaxRate",
         "summary": "Delete a Tax Rate",
-        "description": "Deletes a Tax Rate",
+        "description": "Delete a Tax Rate. Resources associated with the tax rate, such as products or product types, are not deleted.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -22073,12 +22370,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.delete(tax_rate_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.delete(taxRateId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/tax-rates/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -22142,7 +22439,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22155,7 +22452,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22184,12 +22481,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.addProductTypes(tax_rate_id, {\n  product_types: [\n    product_type_id\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.addProductTypes(taxRateId, {\n  product_types: [\n    productTypeId\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n   \"product_types\": [\n     \"{product_type_id}\"\n   ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n   \"product_types\": [\n     \"{product_type_id}\"\n   ]\n}'\n"
           }
         ],
         "security": [
@@ -22236,8 +22533,8 @@
       },
       "delete": {
         "operationId": "DeleteTaxRatesTaxRateProductTypes",
-        "summary": "Delete from Product Types",
-        "description": "Removes a Tax Rate from a list of Product Types",
+        "summary": "Remove Product Types from Rate",
+        "description": "Remove product types from a tax rate. This only removes the association between the product types and the tax rate. It does not delete the product types.",
         "parameters": [
           {
             "in": "path",
@@ -22251,7 +22548,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22264,7 +22561,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22293,12 +22590,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.removeProductTypes(tax_rate_id, {\n  product_types: [\n    product_type_id\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.removeProductTypes(taxRateId, {\n  product_types: [\n    productTypeId\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n   \"product_types\": [\n     \"{product_type_id}\"\n   ]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n   \"product_types\": [\n     \"{product_type_id}\"\n   ]\n}'\n"
           }
         ],
         "security": [
@@ -22348,7 +22645,7 @@
       "post": {
         "operationId": "PostTaxRatesTaxRateProducts",
         "summary": "Add to Products",
-        "description": "Associates a Tax Rate with a list of Products",
+        "description": "Associates a Tax Rate with a list of Products.",
         "parameters": [
           {
             "in": "path",
@@ -22362,7 +22659,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22375,7 +22672,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22404,12 +22701,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.addProducts(tax_rate_id, {\n  products: [\n    product_id\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.addProducts(taxRateId, {\n  products: [\n    productId\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n   \"products\": [\n     \"{product_id}\"\n   ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n   \"products\": [\n     \"{product_id}\"\n   ]\n}'\n"
           }
         ],
         "security": [
@@ -22456,8 +22753,8 @@
       },
       "delete": {
         "operationId": "DeleteTaxRatesTaxRateProducts",
-        "summary": "Delete from Products",
-        "description": "Removes a Tax Rate from a list of Products",
+        "summary": "Remove Products from Rate",
+        "description": "Remove products from a tax rate. This only removes the association between the products and the tax rate. It does not delete the products.",
         "parameters": [
           {
             "in": "path",
@@ -22471,7 +22768,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22484,7 +22781,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22513,12 +22810,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.removeProducts(tax_rate_id, {\n  products: [\n    product_id\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.removeProducts(taxRateId, {\n  products: [\n    productId\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n   \"products\": [\n     \"{product_id}\"\n   ]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n   \"products\": [\n     \"{product_id}\"\n   ]\n}'\n"
           }
         ],
         "security": [
@@ -22568,7 +22865,7 @@
       "post": {
         "operationId": "PostTaxRatesTaxRateShippingOptions",
         "summary": "Add to Shipping Options",
-        "description": "Associates a Tax Rate with a list of Shipping Options",
+        "description": "Associates a Tax Rate with a list of Shipping Options.",
         "parameters": [
           {
             "in": "path",
@@ -22582,7 +22879,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22595,7 +22892,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22624,12 +22921,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.addShippingOptions(tax_rate_id, {\n  shipping_options: [\n    shipping_option_id\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.addShippingOptions(taxRateId, {\n  shipping_options: [\n    shippingOptionId\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n   \"shipping_options\": [\n     \"{shipping_option_id}\"\n   ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n   \"shipping_options\": [\n     \"{shipping_option_id}\"\n   ]\n}'\n"
           }
         ],
         "security": [
@@ -22676,8 +22973,8 @@
       },
       "delete": {
         "operationId": "DeleteTaxRatesTaxRateShippingOptions",
-        "summary": "Del. for Shipping Options",
-        "description": "Removes a Tax Rate from a list of Shipping Options",
+        "summary": "Remove Shipping Options from Rate",
+        "description": "Remove shipping options from a tax rate. This only removes the association between the shipping options and the tax rate. It does not delete the shipping options.",
         "parameters": [
           {
             "in": "path",
@@ -22691,7 +22988,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be included in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22704,7 +23001,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "Which fields should be expanded and retrieved in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned tax rate.",
             "style": "form",
             "explode": false,
             "schema": {
@@ -22733,12 +23030,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.removeShippingOptions(tax_rate_id, {\n  shipping_options: [\n    shipping_option_id\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.taxRates.removeShippingOptions(taxRateId, {\n  shipping_options: [\n    shippingOptionId\n  ]\n})\n.then(({ tax_rate }) => {\n  console.log(tax_rate.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n   \"shipping_options\": [\n     \"{shipping_option_id}\"\n   ]\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n   \"shipping_options\": [\n     \"{shipping_option_id}\"\n   ]\n}'\n"
           }
         ],
         "security": [
@@ -22787,8 +23084,8 @@
     "/admin/uploads": {
       "post": {
         "operationId": "PostUploads",
-        "summary": "Upload files",
-        "description": "Uploads at least one file to the specific fileservice that is installed in Medusa.",
+        "summary": "Upload Files",
+        "description": "Upload at least one file to a public bucket or storage. The file upload is handled by the file service installed on the Medusa backend.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -22814,7 +23111,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/uploads' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: image/jpeg' \\\n--form 'files=@\"<FILE_PATH_1>\"' \\\n--form 'files=@\"<FILE_PATH_1>\"'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/uploads' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: image/jpeg' \\\n--form 'files=@\"<FILE_PATH_1>\"' \\\n--form 'files=@\"<FILE_PATH_1>\"'\n"
           }
         ],
         "security": [
@@ -22862,7 +23159,7 @@
       "delete": {
         "operationId": "DeleteUploads",
         "summary": "Delete an Uploaded File",
-        "description": "Removes an uploaded file using the installed fileservice",
+        "description": "Delete an uploaded file from storage. The file is deleted using the installed file service on the Medusa backend.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -22882,7 +23179,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/uploads' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"file_key\": \"{file_key}\"\n}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/uploads' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"file_key\": \"{file_key}\"\n}'\n"
           }
         ],
         "security": [
@@ -22932,7 +23229,7 @@
       "post": {
         "operationId": "PostUploadsDownloadUrl",
         "summary": "Get a File's Download URL",
-        "description": "Creates a presigned download url for a file",
+        "description": "Create and retrieve a presigned or public download URL for a file. The URL creation is handled by the file service installed on the Medusa backend.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -22952,7 +23249,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/uploads/download-url' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"file_key\": \"{file_key}\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/uploads/download-url' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"file_key\": \"{file_key}\"\n}'\n"
           }
         ],
         "security": [
@@ -23002,7 +23299,7 @@
       "post": {
         "operationId": "PostUploadsProtected",
         "summary": "Protected File Upload",
-        "description": "Uploads at least one file with ACL or a non-public bucket to the specific fileservice that is installed in Medusa.",
+        "description": "Upload at least one file to an ACL or a non-public bucket. The file upload is handled by the file service installed on the Medusa backend.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -23028,7 +23325,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/uploads/protected' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: image/jpeg' \\\n--form 'files=@\"<FILE_PATH_1>\"' \\\n--form 'files=@\"<FILE_PATH_1>\"'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/uploads/protected' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: image/jpeg' \\\n--form 'files=@\"<FILE_PATH_1>\"' \\\n--form 'files=@\"<FILE_PATH_1>\"'\n"
           }
         ],
         "security": [
@@ -23078,7 +23375,7 @@
       "get": {
         "operationId": "GetUsers",
         "summary": "List Users",
-        "description": "Retrieves all users.",
+        "description": "Retrieve all admin users.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "list"
@@ -23092,7 +23389,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/users' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/users' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -23140,7 +23437,7 @@
       "post": {
         "operationId": "PostUsers",
         "summary": "Create a User",
-        "description": "Creates a User",
+        "description": "Create an admin User. The user has the same privileges as all admin users, and will be able to authenticate and perform admin functionalities right after creation.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -23158,12 +23455,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.create({\n  email: 'user@example.com',\n  password: 'supersecret'\n})\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.create({\n  email: \"user@example.com\",\n  password: \"supersecret\"\n})\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/users' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"password\": \"supersecret\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/users' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"password\": \"supersecret\"\n}'\n"
           }
         ],
         "security": [
@@ -23213,8 +23510,11 @@
       "post": {
         "operationId": "PostUsersUserPasswordToken",
         "summary": "Request Password Reset",
-        "description": "Generates a password token for a User with a given email.",
-        "x-authenticated": true,
+        "description": "Generate a password token for an admin user with a given email.",
+        "externalDocs": {
+          "description": "How to reset a user's password",
+          "url": "https://docs.medusajs.com/modules/users/admin/manage-profile#reset-password"
+        },
         "requestBody": {
           "content": {
             "application/json": {
@@ -23231,12 +23531,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.sendResetPasswordToken({\n  email: 'user@example.com'\n})\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // error occurred\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.sendResetPasswordToken({\n  email: \"user@example.com\"\n})\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // error occurred\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/users/password-token' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/users/password-token' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
           }
         ],
         "security": [
@@ -23279,8 +23579,11 @@
       "post": {
         "operationId": "PostUsersUserPassword",
         "summary": "Reset Password",
-        "description": "Sets the password for a User given the correct token.",
-        "x-authenticated": true,
+        "description": "Reset the password of an admin User using their reset password token. A user must request to reset their password first before attempting to reset their password with this request.",
+        "externalDocs": {
+          "description": "How to reset a user's password",
+          "url": "https://docs.medusajs.com/modules/users/admin/manage-profile#reset-password"
+        },
         "requestBody": {
           "content": {
             "application/json": {
@@ -23297,12 +23600,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.resetPassword({\n  token: 'supersecrettoken',\n  password: 'supersecret'\n})\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.resetPassword({\n  token: \"supersecrettoken\",\n  password: \"supersecret\"\n})\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/users/reset-password' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"token\": \"supersecrettoken\",\n    \"password\": \"supersecret\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/users/reset-password' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"token\": \"supersecrettoken\",\n    \"password\": \"supersecret\"\n}'\n"
           }
         ],
         "security": [
@@ -23352,7 +23655,7 @@
       "get": {
         "operationId": "GetUsersUser",
         "summary": "Get a User",
-        "description": "Retrieves a User.",
+        "description": "Retrieve an admin user's details.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -23372,12 +23675,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.retrieve(user_id)\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.retrieve(userId)\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/users/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/users/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -23425,7 +23728,7 @@
       "post": {
         "operationId": "PostUsersUser",
         "summary": "Update a User",
-        "description": "Updates a User",
+        "description": "Update an admin user's details.",
         "parameters": [
           {
             "in": "path",
@@ -23454,12 +23757,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.update(user_id, {\n  first_name: 'Marcellus'\n})\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.update(userId, {\n  first_name: \"Marcellus\"\n})\n.then(({ user }) => {\n  console.log(user.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/admin/users/{id}' \\\n--header 'Authorization: Bearer {api_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Marcellus\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/admin/users/{id}' \\\n-H 'Authorization: Bearer {api_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Marcellus\"\n}'\n"
           }
         ],
         "security": [
@@ -23507,7 +23810,7 @@
       "delete": {
         "operationId": "DeleteUsersUser",
         "summary": "Delete a User",
-        "description": "Deletes a User",
+        "description": "Delete a User. Once deleted, the user will not be able to authenticate or perform admin functionalities.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -23527,12 +23830,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.delete(user_id)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.users.delete(userId)\n.then(({ id, object, deleted }) => {\n  console.log(id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/admin/users/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/admin/users/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -23582,29 +23885,35 @@
       "get": {
         "operationId": "GetVariants",
         "summary": "List Product Variants",
-        "description": "Retrieves a list of Product Variants",
+        "description": "Retrieve a list of Product Variants. The product variant can be filtered by fields such as `id` or `title`. The product variant can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "id",
-            "description": "A Product Variant id to filter by.",
+            "style": "form",
+            "explode": false,
+            "description": "Filter by product variant IDs.",
             "schema": {
-              "type": "string"
-            }
-          },
-          {
-            "in": "query",
-            "name": "ids",
-            "description": "A comma separated list of Product Variant ids to filter by.",
-            "schema": {
-              "type": "string"
+              "oneOf": [
+                {
+                  "type": "string",
+                  "description": "A product variant ID."
+                },
+                {
+                  "type": "array",
+                  "description": "An array of product variant IDs.",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
             }
           },
           {
             "in": "query",
             "name": "expand",
-            "description": "A comma separated list of Product Variant relations to load.",
+            "description": "\"Comma-separated relations that should be expanded in the returned product variants.\"",
             "schema": {
               "type": "string"
             }
@@ -23612,7 +23921,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "A comma separated list of Product Variant fields to include.",
+            "description": "\"Comma-separated fields that should be included in the returned product variants.\"",
             "schema": {
               "type": "string"
             }
@@ -23620,7 +23929,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many product variants to skip in the result.",
+            "description": "The number of product variants to skip when retrieving the product variants.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -23629,7 +23938,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "Maximum number of Product Variants to return.",
+            "description": "Limit the number of product variants returned.",
             "schema": {
               "type": "number",
               "default": "100"
@@ -23638,7 +23947,9 @@
           {
             "in": "query",
             "name": "cart_id",
-            "description": "The id of the cart to use for price selection.",
+            "style": "form",
+            "explode": false,
+            "description": "The ID of the cart to use for the price selection context.",
             "schema": {
               "type": "string"
             }
@@ -23646,25 +23957,43 @@
           {
             "in": "query",
             "name": "region_id",
-            "description": "The id of the region to use for price selection.",
+            "style": "form",
+            "explode": false,
+            "description": "The ID of the region to use for the price selection context.",
             "schema": {
-              "type": "string"
+              "type": "string",
+              "externalDocs": {
+                "description": "Price selection context overview",
+                "url": "https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object"
+              }
             }
           },
           {
             "in": "query",
             "name": "currency_code",
-            "description": "The currency code to use for price selection.",
+            "style": "form",
+            "explode": false,
+            "description": "The 3 character ISO currency code to use for the price selection context.",
             "schema": {
-              "type": "string"
+              "type": "string",
+              "externalDocs": {
+                "description": "Price selection context overview",
+                "url": "https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object"
+              }
             }
           },
           {
             "in": "query",
             "name": "customer_id",
-            "description": "The id of the customer to use for price selection.",
+            "style": "form",
+            "explode": false,
+            "description": "The ID of the customer to use for the price selection context.",
             "schema": {
-              "type": "string"
+              "type": "string",
+              "externalDocs": {
+                "description": "Price selection context overview",
+                "url": "https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object"
+              }
             }
           },
           {
@@ -23672,16 +24001,16 @@
             "name": "title",
             "style": "form",
             "explode": false,
-            "description": "product variant title to search for.",
+            "description": "Filter by title.",
             "schema": {
               "oneOf": [
                 {
                   "type": "string",
-                  "description": "a single title to search by"
+                  "description": "a single title to filter by"
                 },
                 {
                   "type": "array",
-                  "description": "multiple titles to search by",
+                  "description": "multiple titles to filter by",
                   "items": {
                     "type": "string"
                   }
@@ -23697,11 +24026,11 @@
               "oneOf": [
                 {
                   "type": "number",
-                  "description": "a specific number to search by."
+                  "description": "a specific number to filter by."
                 },
                 {
                   "type": "object",
-                  "description": "search using less and greater than comparisons.",
+                  "description": "filter using less and greater than comparisons.",
                   "properties": {
                     "lt": {
                       "type": "number",
@@ -23738,7 +24067,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/variants' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/variants' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -23750,7 +24079,7 @@
           }
         ],
         "tags": [
-          "Variants"
+          "Product Variants"
         ],
         "responses": {
           "200": {
@@ -23788,14 +24117,14 @@
       "get": {
         "operationId": "GetVariantsVariant",
         "summary": "Get a Product variant",
-        "description": "Retrieves a Product variant.",
+        "description": "Retrieve a product variant's details.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The ID of the variant.",
+            "description": "The ID of the product variant.",
             "schema": {
               "type": "string"
             }
@@ -23803,7 +24132,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded the order of the result.",
+            "description": "\"Comma-separated relations that should be expanded in the returned product variant.\"",
             "schema": {
               "type": "string"
             }
@@ -23811,7 +24140,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included the order of the result.",
+            "description": "\"Comma-separated fields that should be included in the returned product variant.\"",
             "schema": {
               "type": "string"
             }
@@ -23825,12 +24154,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.variants.retrieve(product_id)\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.variants.retrieve(variantId)\n.then(({ variant }) => {\n  console.log(variant.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/variants/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/variants/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -23842,7 +24171,7 @@
           }
         ],
         "tags": [
-          "Products"
+          "Product Variants"
         ],
         "responses": {
           "200": {
@@ -23879,15 +24208,15 @@
     "/admin/variants/{id}/inventory": {
       "get": {
         "operationId": "GetVariantsVariantInventory",
-        "summary": "Get inventory of Variant.",
-        "description": "Returns the available inventory of a Variant.",
+        "summary": "Get Variant's Inventory",
+        "description": "Retrieve the available inventory of a Product Variant.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The Product Variant id to get inventory for.",
+            "description": "The Product Variant ID.",
             "schema": {
               "type": "string"
             }
@@ -23900,12 +24229,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.variants.list()\n  .then(({ variants, limit, offset, count }) => {\n    console.log(variants.length)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.admin.variants.list()\n.then(({ variants, limit, offset, count }) => {\n  console.log(variants.length)\n})\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/admin/variants' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/admin/variants' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -23917,7 +24246,7 @@
           }
         ],
         "tags": [
-          "Variants"
+          "Product Variants"
         ],
         "responses": {
           "200": {
@@ -24176,7 +24505,7 @@
     "schemas": {
       "Address": {
         "title": "Address",
-        "description": "An address.",
+        "description": "An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.",
         "type": "object",
         "required": [
           "address_1",
@@ -24260,7 +24589,8 @@
             "example": "st"
           },
           "country": {
-            "description": "A country object. Available if the relation `country` is expanded.",
+            "description": "A country object.",
+            "x-expandable": "country",
             "nullable": true,
             "$ref": "#/components/schemas/Country"
           },
@@ -24304,6 +24634,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -24454,6 +24788,7 @@
         "properties": {
           "apps": {
             "type": "array",
+            "description": "An array of app details.",
             "items": {
               "$ref": "#/components/schemas/OAuth"
             }
@@ -24467,6 +24802,7 @@
         ],
         "properties": {
           "apps": {
+            "description": "App details.",
             "$ref": "#/components/schemas/OAuth"
           }
         }
@@ -24478,6 +24814,7 @@
         ],
         "properties": {
           "user": {
+            "description": "User details.",
             "$ref": "#/components/schemas/User"
           }
         }
@@ -24493,6 +24830,7 @@
         "properties": {
           "batch_jobs": {
             "type": "array",
+            "description": "An array of batch job details.",
             "items": {
               "$ref": "#/components/schemas/BatchJob"
             }
@@ -24503,7 +24841,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of batch jobs skipped when retrieving the batch jobs."
           },
           "limit": {
             "type": "integer",
@@ -24518,6 +24856,7 @@
         ],
         "properties": {
           "batch_job": {
+            "description": "Batch job details.",
             "$ref": "#/components/schemas/BatchJob"
           }
         }
@@ -24557,6 +24896,7 @@
         "properties": {
           "collections": {
             "type": "array",
+            "description": "an array of collection details",
             "items": {
               "$ref": "#/components/schemas/ProductCollection"
             }
@@ -24567,7 +24907,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product collections skipped when retrieving the product collections."
           },
           "limit": {
             "type": "integer",
@@ -24588,6 +24928,7 @@
         ],
         "properties": {
           "collection": {
+            "type": "Product Collection details.",
             "$ref": "#/components/schemas/ProductCollection"
           }
         }
@@ -24600,20 +24941,20 @@
         ],
         "properties": {
           "email": {
-            "description": "The Users email.",
+            "description": "The User's email.",
             "type": "string",
             "format": "email"
           },
           "first_name": {
-            "description": "The name of the User.",
+            "description": "The first name of the User.",
             "type": "string"
           },
           "last_name": {
-            "description": "The name of the User.",
+            "description": "The last name of the User.",
             "type": "string"
           },
           "role": {
-            "description": "Userrole assigned to the user.",
+            "description": "The role assigned to the user. These roles don't provide any different privileges.",
             "type": "string",
             "enum": [
               "admin",
@@ -24622,7 +24963,7 @@
             ]
           },
           "password": {
-            "description": "The Users password.",
+            "description": "The User's password.",
             "type": "string",
             "format": "password"
           }
@@ -24639,6 +24980,7 @@
         "properties": {
           "currencies": {
             "type": "array",
+            "description": "An array of currency details.",
             "items": {
               "$ref": "#/components/schemas/Currency"
             }
@@ -24649,7 +24991,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of currencies skipped when retrieving the currencies."
           },
           "limit": {
             "type": "integer",
@@ -24664,6 +25006,7 @@
         ],
         "properties": {
           "currency": {
+            "description": "Currency details.",
             "$ref": "#/components/schemas/Currency"
           }
         }
@@ -24703,6 +25046,7 @@
         "properties": {
           "customer_groups": {
             "type": "array",
+            "description": "An array of customer group details.",
             "items": {
               "$ref": "#/components/schemas/CustomerGroup"
             }
@@ -24713,7 +25057,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of customer groups skipped when retrieving the customer groups."
           },
           "limit": {
             "type": "integer",
@@ -24728,6 +25072,7 @@
         ],
         "properties": {
           "customer_group": {
+            "description": "Customer group details.",
             "$ref": "#/components/schemas/CustomerGroup"
           }
         }
@@ -24743,6 +25088,7 @@
         "properties": {
           "customers": {
             "type": "array",
+            "description": "An array of customer details.",
             "items": {
               "$ref": "#/components/schemas/Customer"
             }
@@ -24753,7 +25099,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of customers skipped when retrieving the customers."
           },
           "limit": {
             "type": "integer",
@@ -24775,6 +25121,7 @@
         ],
         "properties": {
           "customer": {
+            "description": "Customer details.",
             "$ref": "#/components/schemas/Customer"
           }
         }
@@ -24810,7 +25157,7 @@
         ],
         "properties": {
           "resources": {
-            "description": "The resources to be deleted from the discount condition",
+            "description": "The resources to be removed from the discount condition",
             "type": "array",
             "items": {
               "type": "object",
@@ -24831,7 +25178,7 @@
         "type": "object",
         "properties": {
           "price_ids": {
-            "description": "The price id's of the Money Amounts to delete.",
+            "description": "The price IDs of the Money Amounts to delete.",
             "type": "array",
             "items": {
               "type": "string"
@@ -24900,7 +25247,7 @@
             "description": "The IDs of the products removed from the collection",
             "type": "array",
             "items": {
-              "description": "The ID of a Product to add to the Product Collection.",
+              "description": "The ID of the Product removed from the Product Collection.",
               "type": "string"
             }
           }
@@ -24913,7 +25260,7 @@
         ],
         "properties": {
           "sales_channel_ids": {
-            "description": "The IDs of the sales channels to delete from the publishable api key",
+            "description": "The IDs of the sales channels to remove from the publishable API key",
             "type": "array",
             "items": {
               "type": "object",
@@ -24937,7 +25284,7 @@
         ],
         "properties": {
           "product_ids": {
-            "description": "The IDs of the products to delete from the Sales Channel.",
+            "description": "The IDs of the products to remove from the Sales Channel.",
             "type": "array",
             "items": {
               "type": "object",
@@ -24998,7 +25345,7 @@
         "properties": {
           "product_types": {
             "type": "array",
-            "description": "The IDs of the types of products to remove association with this tax rate",
+            "description": "The IDs of the product types to remove their association with this tax rate.",
             "items": {
               "type": "string"
             }
@@ -25013,7 +25360,7 @@
         "properties": {
           "products": {
             "type": "array",
-            "description": "The IDs of the products to remove association with this tax rate",
+            "description": "The IDs of the products to remove their association with this tax rate.",
             "items": {
               "type": "string"
             }
@@ -25028,7 +25375,7 @@
         "properties": {
           "shipping_options": {
             "type": "array",
-            "description": "The IDs of the shipping options to remove association with this tax rate",
+            "description": "The IDs of the shipping options to remove their association with this tax rate.",
             "items": {
               "type": "string"
             }
@@ -25106,7 +25453,7 @@
         "properties": {
           "id": {
             "type": "string",
-            "description": "The ID of the deleted DiscountCondition"
+            "description": "The ID of the deleted Discount Condition"
           },
           "object": {
             "type": "string",
@@ -25115,11 +25462,11 @@
           },
           "deleted": {
             "type": "boolean",
-            "description": "Whether the discount condition was deleted successfully or not.",
+            "description": "Whether the discount condition was deleted successfully.",
             "default": true
           },
           "discount": {
-            "description": "The Discount to which the condition used to belong",
+            "description": "The Discount to which the condition used to belong to.",
             "$ref": "#/components/schemas/Discount"
           }
         }
@@ -25137,6 +25484,7 @@
         ],
         "properties": {
           "discount_condition": {
+            "description": "Discount condition details.",
             "$ref": "#/components/schemas/DiscountCondition"
           }
         }
@@ -25160,7 +25508,7 @@
           },
           "deleted": {
             "type": "boolean",
-            "description": "Whether the discount was deleted successfully or not.",
+            "description": "Whether the discount was deleted successfully.",
             "default": true
           }
         }
@@ -25195,7 +25543,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of discounts skipped when retrieving the discounts."
           },
           "limit": {
             "type": "integer",
@@ -25223,6 +25571,7 @@
         ],
         "properties": {
           "discount": {
+            "description": "Discount details.",
             "$ref": "#/components/schemas/Discount"
           }
         }
@@ -25246,7 +25595,7 @@
           },
           "deleted": {
             "type": "boolean",
-            "description": "Whether the draft order was deleted successfully or not.",
+            "description": "Whether the draft order was deleted successfully.",
             "default": true
           }
         }
@@ -25271,6 +25620,7 @@
         "properties": {
           "draft_orders": {
             "type": "array",
+            "description": "An array of draft order's details.",
             "items": {
               "$ref": "#/components/schemas/DraftOrder"
             }
@@ -25281,7 +25631,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of draft orders skipped when retrieving the draft orders."
           },
           "limit": {
             "type": "integer",
@@ -25326,6 +25676,7 @@
             "cart.items.tax_lines",
             "cart.items.variant",
             "cart.items.variant.product",
+            "cart.items.variant.product.profiles",
             "cart.region",
             "cart.region.tax_rates",
             "cart.shipping_address",
@@ -25359,6 +25710,7 @@
         ],
         "properties": {
           "draft_order": {
+            "description": "Draft order's details.",
             "$ref": "#/components/schemas/DraftOrder"
           }
         }
@@ -25377,6 +25729,7 @@
         ],
         "properties": {
           "store": {
+            "description": "Store details.",
             "$ref": "#/components/schemas/ExtendedStoreDTO"
           }
         }
@@ -25389,6 +25742,7 @@
         "properties": {
           "fulfillment_options": {
             "type": "array",
+            "description": "Fulfillment providers details.",
             "items": {
               "type": "object",
               "required": [
@@ -25426,6 +25780,7 @@
         "properties": {
           "variant": {
             "type": "object",
+            "description": "The product variant's.",
             "$ref": "#/components/schemas/VariantInventory"
           }
         }
@@ -25449,7 +25804,7 @@
           },
           "deleted": {
             "type": "boolean",
-            "description": "Whether the gift card was deleted successfully or not.",
+            "description": "Whether the gift card was deleted successfully.",
             "default": true
           }
         }
@@ -25486,7 +25841,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of gift cards skipped when retrieving the gift cards."
           },
           "limit": {
             "type": "integer",
@@ -25512,6 +25867,7 @@
         ],
         "properties": {
           "gift_card": {
+            "description": "A gift card's details.",
             "$ref": "#/components/schemas/GiftCard"
           }
         }
@@ -25551,6 +25907,7 @@
         "properties": {
           "inventory_items": {
             "type": "array",
+            "description": "an array of Inventory Item details",
             "items": {
               "$ref": "#/components/schemas/InventoryItemDTO"
             }
@@ -25561,7 +25918,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of inventory items skipped when retrieving the inventory items."
           },
           "limit": {
             "type": "integer",
@@ -25580,6 +25937,7 @@
         "properties": {
           "inventory_items": {
             "type": "array",
+            "description": "an array of Inventory Item details",
             "items": {
               "$ref": "#/components/schemas/DecoratedInventoryItemDTO"
             }
@@ -25590,7 +25948,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of inventory items skipped when retrieving the inventory items."
           },
           "limit": {
             "type": "integer",
@@ -25632,6 +25990,7 @@
         ],
         "properties": {
           "inventory_item": {
+            "description": "Inventory Item details",
             "$ref": "#/components/schemas/InventoryItemDTO"
           }
         }
@@ -25655,7 +26014,7 @@
           },
           "deleted": {
             "type": "boolean",
-            "description": "Whether or not the Invite was deleted.",
+            "description": "Whether or not the invite was deleted.",
             "default": true
           }
         }
@@ -25668,6 +26027,7 @@
         "properties": {
           "invites": {
             "type": "array",
+            "description": "An array of invites",
             "items": {
               "$ref": "#/components/schemas/Invite"
             }
@@ -25709,6 +26069,7 @@
         "properties": {
           "notes": {
             "type": "array",
+            "description": "An array of notes",
             "items": {
               "$ref": "#/components/schemas/Note"
             }
@@ -25719,7 +26080,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of notes skipped when retrieving the notes."
           },
           "limit": {
             "type": "integer",
@@ -25734,6 +26095,7 @@
         ],
         "properties": {
           "note": {
+            "description": "Note details.",
             "$ref": "#/components/schemas/Note"
           }
         }
@@ -25752,6 +26114,7 @@
         "properties": {
           "notifications": {
             "type": "array",
+            "description": "an array of notifications",
             "items": {
               "$ref": "#/components/schemas/Notification"
             }
@@ -25762,7 +26125,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of notifications skipped before these notifications"
+            "description": "The number of notifications skipped when retrieving the notifications."
           },
           "limit": {
             "type": "integer",
@@ -25783,6 +26146,7 @@
         ],
         "properties": {
           "notification": {
+            "description": "Notification details",
             "$ref": "#/components/schemas/Notification"
           }
         }
@@ -25885,6 +26249,7 @@
         "properties": {
           "order_edits": {
             "type": "array",
+            "description": "An array of order edit details",
             "items": {
               "$ref": "#/components/schemas/OrderEdit"
             }
@@ -25895,7 +26260,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of order edits skipped when retrieving the order edits."
           },
           "limit": {
             "type": "integer",
@@ -25949,6 +26314,7 @@
         ],
         "properties": {
           "order_edit": {
+            "description": "Order edit details",
             "$ref": "#/components/schemas/OrderEdit"
           }
         }
@@ -26016,6 +26382,7 @@
             "items.tax_lines",
             "items.variant",
             "items.variant.product",
+            "items.variant.product.profiles",
             "refunds",
             "region",
             "shipping_methods",
@@ -26072,6 +26439,7 @@
         "properties": {
           "orders": {
             "type": "array",
+            "description": "An array of order details.",
             "items": {
               "$ref": "#/components/schemas/Order"
             }
@@ -26082,7 +26450,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of orders skipped when retrieving the orders."
           },
           "limit": {
             "type": "integer",
@@ -26097,7 +26465,7 @@
         ],
         "properties": {
           "location_id": {
-            "description": "The id of the location of the reservation",
+            "description": "The ID of the location of the reservation",
             "type": "string"
           },
           "quantity": {
@@ -26169,6 +26537,7 @@
             "items.tax_lines",
             "items.variant",
             "items.variant.product",
+            "items.variant.product.profiles",
             "refunds",
             "region",
             "shipping_methods",
@@ -26221,6 +26590,7 @@
         ],
         "properties": {
           "order": {
+            "description": "Order details.",
             "$ref": "#/components/schemas/Order"
           }
         }
@@ -26268,6 +26638,7 @@
         ],
         "properties": {
           "payment_collection": {
+            "description": "Payment Collection details.",
             "$ref": "#/components/schemas/PaymentCollection"
           }
         }
@@ -26280,6 +26651,7 @@
         "properties": {
           "payment_providers": {
             "type": "array",
+            "description": "An array of payment providers details.",
             "items": {
               "$ref": "#/components/schemas/PaymentProvider"
             }
@@ -26293,6 +26665,7 @@
         ],
         "properties": {
           "payment": {
+            "description": "Payment details",
             "$ref": "#/components/schemas/Payment"
           }
         }
@@ -26307,7 +26680,7 @@
         "properties": {
           "application_name": {
             "type": "string",
-            "description": "Name of the application for the token to be generated for."
+            "description": "Name of the application for to generate the token for."
           },
           "state": {
             "type": "string",
@@ -26328,12 +26701,12 @@
         "properties": {
           "email": {
             "type": "string",
-            "description": "The User's email.",
+            "description": "The user's email.",
             "format": "email"
           },
           "password": {
             "type": "string",
-            "description": "The User's password.",
+            "description": "The user's password.",
             "format": "password"
           }
         }
@@ -26347,7 +26720,7 @@
         "properties": {
           "type": {
             "type": "string",
-            "description": "The type of batch job to start.",
+            "description": "The type of batch job to start, which is defined by the `batchType` property of the associated batch job strategy.",
             "example": "product-export"
           },
           "context": {
@@ -26380,7 +26753,7 @@
           },
           "dry_run": {
             "type": "boolean",
-            "description": "Set a batch job in dry_run mode to get some information on what will be done without applying any modifications.",
+            "description": "Set a batch job in dry_run mode, which would delay executing the batch job until it's confirmed.",
             "default": false
           }
         }
@@ -26390,15 +26763,19 @@
         "properties": {
           "title": {
             "type": "string",
-            "description": "The title to identify the Collection by."
+            "description": "The title of the collection."
           },
           "handle": {
             "type": "string",
-            "description": "An optional handle to be used in slugs, if none is provided we will kebab-case the title."
+            "description": "An optional handle to be used in slugs. If none is provided, the kebab-case version of the title will be used."
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -26410,15 +26787,19 @@
         "properties": {
           "title": {
             "type": "string",
-            "description": "The title to identify the Collection by."
+            "description": "The title of the collection."
           },
           "handle": {
             "type": "string",
-            "description": "An optional handle to be used in slugs, if none is provided we will kebab-case the title."
+            "description": "An optional handle to be used in slugs. If none is provided, the kebab-case version of the title will be used."
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -26427,7 +26808,8 @@
         "properties": {
           "includes_tax": {
             "type": "boolean",
-            "description": "[EXPERIMENTAL] Tax included in prices of currency."
+            "x-featureFlag": "tax_inclusive_pricing",
+            "description": "Tax included in prices of currency."
           }
         }
       },
@@ -26463,8 +26845,12 @@
             "type": "string"
           },
           "metadata": {
-            "description": "Metadata for the customer.",
-            "type": "object"
+            "description": "Metadata of the customer group.",
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -26480,7 +26866,11 @@
           },
           "metadata": {
             "type": "object",
-            "description": "Metadata for the customer."
+            "description": "Metadata of the customer group.",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -26511,6 +26901,7 @@
           },
           "groups": {
             "type": "array",
+            "description": "A list of customer groups to which the customer belongs.",
             "items": {
               "type": "object",
               "required": [
@@ -26522,12 +26913,15 @@
                   "type": "string"
                 }
               }
-            },
-            "description": "A list of customer groups to which the customer belongs."
+            }
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -26564,7 +26958,11 @@
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -26575,7 +26973,7 @@
         ],
         "properties": {
           "operator": {
-            "description": "Operator of the condition",
+            "description": "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that discountable resources are everything but the specified resources.",
             "type": "string",
             "enum": [
               "in",
@@ -26584,35 +26982,35 @@
           },
           "products": {
             "type": "array",
-            "description": "list of product IDs if the condition is applied on products.",
+            "description": "list of product IDs if the condition's type is `products`.",
             "items": {
               "type": "string"
             }
           },
           "product_types": {
             "type": "array",
-            "description": "list of product type IDs if the condition is applied on product types.",
+            "description": "list of product type IDs if the condition's type is `product_types`.",
             "items": {
               "type": "string"
             }
           },
           "product_collections": {
             "type": "array",
-            "description": "list of product collection IDs if the condition is applied on product collections.",
+            "description": "list of product collection IDs if the condition's type is `product_collections`.",
             "items": {
               "type": "string"
             }
           },
           "product_tags": {
             "type": "array",
-            "description": "list of product tag IDs if the condition is applied on product tags.",
+            "description": "list of product tag IDs if the condition's type is `product_tags`.",
             "items": {
               "type": "string"
             }
           },
           "customer_groups": {
             "type": "array",
-            "description": "list of customer group IDs if the condition is applied on customer groups.",
+            "description": "list of customer group IDs if the condition's type is `customer_groups`.",
             "items": {
               "type": "string"
             }
@@ -26624,35 +27022,35 @@
         "properties": {
           "products": {
             "type": "array",
-            "description": "list of product IDs if the condition is applied on products.",
+            "description": "list of product IDs if the condition's type is `products`.",
             "items": {
               "type": "string"
             }
           },
           "product_types": {
             "type": "array",
-            "description": "list of product type IDs if the condition is applied on product types.",
+            "description": "list of product type IDs if the condition's type is `product_types`.",
             "items": {
               "type": "string"
             }
           },
           "product_collections": {
             "type": "array",
-            "description": "list of product collection IDs if the condition is applied on product collections.",
+            "description": "list of product collection IDs if the condition's type is `product_collections`.",
             "items": {
               "type": "string"
             }
           },
           "product_tags": {
             "type": "array",
-            "description": "list of product tag IDs if the condition is applied on product tags.",
+            "description": "list of product tag IDs if the condition's type is `product_tags`",
             "items": {
               "type": "string"
             }
           },
           "customer_groups": {
             "type": "array",
-            "description": "list of customer group IDs if the condition is applied on customer groups.",
+            "description": "list of customer group IDs if the condition's type is `customer_groups`.",
             "items": {
               "type": "string"
             }
@@ -26695,12 +27093,16 @@
           },
           "usage_limit": {
             "type": "number",
-            "description": "Maximum times the discount can be used",
+            "description": "Maximum number of times the discount code can be used",
             "default": 1
           },
           "metadata": {
             "type": "object",
-            "description": "An optional set of key-value pairs to hold additional information."
+            "description": "An optional set of key-value pairs to hold additional information.",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -26709,10 +27111,10 @@
         "properties": {
           "code": {
             "type": "string",
-            "description": "A unique code that will be used to redeem the Discount"
+            "description": "A unique code that will be used to redeem the discount"
           },
           "rule": {
-            "description": "The Discount Rule that defines how Discounts are calculated",
+            "description": "The discount rule that defines how discounts are calculated",
             "type": "object",
             "required": [
               "id"
@@ -26728,11 +27130,11 @@
               },
               "value": {
                 "type": "number",
-                "description": "The value that the discount represents; this will depend on the type of the discount"
+                "description": "The value that the discount represents. This will depend on the type of the discount."
               },
               "allocation": {
                 "type": "string",
-                "description": "The scope that the discount should apply to.",
+                "description": "The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart.",
                 "enum": [
                   "total",
                   "item"
@@ -26740,7 +27142,7 @@
               },
               "conditions": {
                 "type": "array",
-                "description": "A set of conditions that can be used to limit when the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided.",
+                "description": "A set of conditions that can be used to limit when the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided based on the discount condition's type.",
                 "items": {
                   "type": "object",
                   "required": [
@@ -26749,11 +27151,11 @@
                   "properties": {
                     "id": {
                       "type": "string",
-                      "description": "The ID of the Rule"
+                      "description": "The ID of the condition"
                     },
                     "operator": {
                       "type": "string",
-                      "description": "Operator of the condition",
+                      "description": "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that discountable resources are everything but the specified resources.",
                       "enum": [
                         "in",
                         "not_in"
@@ -26761,35 +27163,35 @@
                     },
                     "products": {
                       "type": "array",
-                      "description": "list of product IDs if the condition is applied on products.",
+                      "description": "list of product IDs if the condition's type is `products`.",
                       "items": {
                         "type": "string"
                       }
                     },
                     "product_types": {
                       "type": "array",
-                      "description": "list of product type IDs if the condition is applied on product types.",
+                      "description": "list of product type IDs if the condition's type is `product_types`.",
                       "items": {
                         "type": "string"
                       }
                     },
                     "product_collections": {
                       "type": "array",
-                      "description": "list of product collection IDs if the condition is applied on product collections.",
+                      "description": "list of product collection IDs if the condition's type is `product_collections`.",
                       "items": {
                         "type": "string"
                       }
                     },
                     "product_tags": {
                       "type": "array",
-                      "description": "list of product tag IDs if the condition is applied on product tags.",
+                      "description": "list of product tag IDs if the condition's type is `product_tags`.",
                       "items": {
                         "type": "string"
                       }
                     },
                     "customer_groups": {
                       "type": "array",
-                      "description": "list of customer group IDs if the condition is applied on customer groups.",
+                      "description": "list of customer group IDs if the condition's type is `customer_groups`.",
                       "items": {
                         "type": "string"
                       }
@@ -26801,29 +27203,29 @@
           },
           "is_disabled": {
             "type": "boolean",
-            "description": "Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers."
+            "description": "Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers."
           },
           "starts_at": {
             "type": "string",
             "format": "date-time",
-            "description": "The time at which the Discount should be available."
+            "description": "The date and time at which the discount should be available."
           },
           "ends_at": {
             "type": "string",
             "format": "date-time",
-            "description": "The time at which the Discount should no longer be available."
+            "description": "The date and time at which the discount should no longer be available."
           },
           "valid_duration": {
             "type": "string",
-            "description": "Duration the discount runs between",
+            "description": "The duration the discount runs between",
             "example": "P3Y6M4DT12H30M5S"
           },
           "usage_limit": {
             "type": "number",
-            "description": "Maximum times the discount can be used"
+            "description": "Maximum number of times the discount can be used"
           },
           "regions": {
-            "description": "A list of Region ids representing the Regions in which the Discount can be used.",
+            "description": "A list of region IDs representing the Regions in which the Discount can be used.",
             "type": "array",
             "items": {
               "type": "string"
@@ -26831,7 +27233,11 @@
           },
           "metadata": {
             "description": "An object containing metadata of the discount",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -26845,15 +27251,15 @@
         "properties": {
           "code": {
             "type": "string",
-            "description": "A unique code that will be used to redeem the Discount"
+            "description": "A unique code that will be used to redeem the discount"
           },
           "is_dynamic": {
             "type": "boolean",
-            "description": "Whether the Discount should have multiple instances of itself, each with a different code. This can be useful for automatically generated codes that all have to follow a common set of rules.",
+            "description": "Whether the discount should have multiple instances of itself, each with a different code. This can be useful for automatically generated discount codes that all have to follow a common set of rules.",
             "default": false
           },
           "rule": {
-            "description": "The Discount Rule that defines how Discounts are calculated",
+            "description": "The discount rule that defines how discounts are calculated",
             "type": "object",
             "required": [
               "type",
@@ -26867,7 +27273,7 @@
               },
               "type": {
                 "type": "string",
-                "description": "The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers.",
+                "description": "The type of the discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers.",
                 "enum": [
                   "fixed",
                   "percentage",
@@ -26876,11 +27282,11 @@
               },
               "value": {
                 "type": "number",
-                "description": "The value that the discount represents; this will depend on the type of the discount"
+                "description": "The value that the discount represents. This will depend on the type of the discount."
               },
               "allocation": {
                 "type": "string",
-                "description": "The scope that the discount should apply to.",
+                "description": "The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart.",
                 "enum": [
                   "total",
                   "item"
@@ -26888,7 +27294,7 @@
               },
               "conditions": {
                 "type": "array",
-                "description": "A set of conditions that can be used to limit when  the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided.",
+                "description": "A set of conditions that can be used to limit when the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided based on the discount condition's type.",
                 "items": {
                   "type": "object",
                   "required": [
@@ -26897,7 +27303,7 @@
                   "properties": {
                     "operator": {
                       "type": "string",
-                      "description": "Operator of the condition",
+                      "description": "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that discountable resources are everything but the specified resources.",
                       "enum": [
                         "in",
                         "not_in"
@@ -26905,35 +27311,35 @@
                     },
                     "products": {
                       "type": "array",
-                      "description": "list of product IDs if the condition is applied on products.",
+                      "description": "list of product IDs if the condition's type is `products`.",
                       "items": {
                         "type": "string"
                       }
                     },
                     "product_types": {
                       "type": "array",
-                      "description": "list of product type IDs if the condition is applied on product types.",
+                      "description": "list of product type IDs if the condition's type is `product_types`.",
                       "items": {
                         "type": "string"
                       }
                     },
                     "product_collections": {
                       "type": "array",
-                      "description": "list of product collection IDs if the condition is applied on product collections.",
+                      "description": "list of product collection IDs if the condition's type is `product_collections`.",
                       "items": {
                         "type": "string"
                       }
                     },
                     "product_tags": {
                       "type": "array",
-                      "description": "list of product tag IDs if the condition is applied on product tags.",
+                      "description": "list of product tag IDs if the condition's type is `product_tags`.",
                       "items": {
                         "type": "string"
                       }
                     },
                     "customer_groups": {
                       "type": "array",
-                      "description": "list of customer group IDs if the condition is applied on customer groups.",
+                      "description": "list of customer group IDs if the condition's type is `customer_groups`.",
                       "items": {
                         "type": "string"
                       }
@@ -26945,26 +27351,26 @@
           },
           "is_disabled": {
             "type": "boolean",
-            "description": "Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers.",
+            "description": "Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers.",
             "default": false
           },
           "starts_at": {
             "type": "string",
             "format": "date-time",
-            "description": "The time at which the Discount should be available."
+            "description": "The date and time at which the discount should be available."
           },
           "ends_at": {
             "type": "string",
             "format": "date-time",
-            "description": "The time at which the Discount should no longer be available."
+            "description": "The date and time at which the discount should no longer be available."
           },
           "valid_duration": {
             "type": "string",
-            "description": "Duration the discount runs between",
+            "description": "The duration the discount runs between",
             "example": "P3Y6M4DT12H30M5S"
           },
           "regions": {
-            "description": "A list of Region ids representing the Regions in which the Discount can be used.",
+            "description": "A list of region IDs representing the Regions in which the Discount can be used.",
             "type": "array",
             "items": {
               "type": "string"
@@ -26972,11 +27378,15 @@
           },
           "usage_limit": {
             "type": "number",
-            "description": "Maximum times the discount can be used"
+            "description": "Maximum number of times the discount can be used"
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -26984,20 +27394,24 @@
         "type": "object",
         "properties": {
           "unit_price": {
-            "description": "The potential custom price of the item.",
+            "description": "The custom price of the line item. If a `variant_id` is supplied, the price provided here will override the variant's price.",
             "type": "integer"
           },
           "title": {
-            "description": "The potential custom title of the item.",
+            "description": "The title of the line item if `variant_id` is not provided.",
             "type": "string"
           },
           "quantity": {
-            "description": "The quantity of the Line Item.",
+            "description": "The quantity of the line item.",
             "type": "integer"
           },
           "metadata": {
             "description": "The optional key-value map with additional details about the Line Item.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27008,25 +27422,29 @@
         ],
         "properties": {
           "variant_id": {
-            "description": "The ID of the Product Variant to generate the Line Item from.",
+            "description": "The ID of the Product Variant associated with the line item. If the line item is custom, the `variant_id` should be omitted.",
             "type": "string"
           },
           "unit_price": {
-            "description": "The potential custom price of the item.",
+            "description": "The custom price of the line item. If a `variant_id` is supplied, the price provided here will override the variant's price.",
             "type": "integer"
           },
           "title": {
-            "description": "The potential custom title of the item.",
+            "description": "The title of the line item if `variant_id` is not provided.",
             "type": "string",
             "default": "Custom item"
           },
           "quantity": {
-            "description": "The quantity of the Line Item.",
+            "description": "The quantity of the line item.",
             "type": "integer"
           },
           "metadata": {
             "description": "The optional key-value map with additional details about the Line Item.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27037,6 +27455,7 @@
         ],
         "properties": {
           "order": {
+            "description": "Order's details.",
             "$ref": "#/components/schemas/Order"
           }
         }
@@ -27058,7 +27477,7 @@
           },
           "email": {
             "type": "string",
-            "description": "An email to be used on the Draft Order.",
+            "description": "An email to be used in the Draft Order.",
             "format": "email"
           },
           "billing_address": {
@@ -27073,7 +27492,7 @@
             ]
           },
           "shipping_address": {
-            "description": "The Address to be used for shipping.",
+            "description": "The Address to be used for shipping purposes.",
             "anyOf": [
               {
                 "$ref": "#/components/schemas/AddressPayload"
@@ -27100,11 +27519,11 @@
             }
           },
           "no_notification_order": {
-            "description": "An optional flag passed to the resulting order to determine use of notifications.",
+            "description": "An optional flag passed to the resulting order that indicates whether the customer should receive notifications about order updates.",
             "type": "boolean"
           },
           "customer_id": {
-            "description": "The ID of the Customer to associate the Draft Order with.",
+            "description": "The ID of the customer this draft order is associated with.",
             "type": "string"
           }
         }
@@ -27118,7 +27537,7 @@
         ],
         "properties": {
           "status": {
-            "description": "The status of the draft order",
+            "description": "The status of the draft order. The draft order's default status is `open`. It's changed to `completed` when its payment is marked as paid.",
             "type": "string",
             "enum": [
               "open",
@@ -27142,7 +27561,7 @@
             ]
           },
           "shipping_address": {
-            "description": "The Address to be used for shipping.",
+            "description": "The Address to be used for shipping purposes.",
             "anyOf": [
               {
                 "$ref": "#/components/schemas/AddressPayload"
@@ -27153,7 +27572,7 @@
             ]
           },
           "items": {
-            "description": "The Line Items that have been received.",
+            "description": "The draft order's line items.",
             "type": "array",
             "items": {
               "type": "object",
@@ -27162,24 +27581,28 @@
               ],
               "properties": {
                 "variant_id": {
-                  "description": "The ID of the Product Variant to generate the Line Item from.",
+                  "description": "The ID of the Product Variant associated with the line item. If the line item is custom, the `variant_id` should be omitted.",
                   "type": "string"
                 },
                 "unit_price": {
-                  "description": "The potential custom price of the item.",
+                  "description": "The custom price of the line item. If a `variant_id` is supplied, the price provided here will override the variant's price.",
                   "type": "integer"
                 },
                 "title": {
-                  "description": "The potential custom title of the item.",
+                  "description": "The title of the line item if `variant_id` is not provided.",
                   "type": "string"
                 },
                 "quantity": {
-                  "description": "The quantity of the Line Item.",
+                  "description": "The quantity of the line item.",
                   "type": "integer"
                 },
                 "metadata": {
-                  "description": "The optional key-value map with additional details about the Line Item.",
-                  "type": "object"
+                  "description": "The optional key-value map with additional details about the line item.",
+                  "type": "object",
+                  "externalDocs": {
+                    "description": "Learn about the metadata attribute, and how to delete and update it.",
+                    "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+                  }
                 }
               }
             }
@@ -27189,7 +27612,7 @@
             "type": "string"
           },
           "discounts": {
-            "description": "The discounts to add on the draft order",
+            "description": "The discounts to add to the draft order",
             "type": "array",
             "items": {
               "type": "object",
@@ -27205,11 +27628,11 @@
             }
           },
           "customer_id": {
-            "description": "The ID of the customer to add on the draft order",
+            "description": "The ID of the customer this draft order is associated with.",
             "type": "string"
           },
           "no_notification_order": {
-            "description": "An optional flag passed to the resulting order to determine use of notifications.",
+            "description": "An optional flag passed to the resulting order that indicates whether the customer should receive notifications about order updates.",
             "type": "boolean"
           },
           "shipping_methods": {
@@ -27230,7 +27653,7 @@
                   "type": "object"
                 },
                 "price": {
-                  "description": "The potential custom price of the shipping",
+                  "description": "The price of the shipping method.",
                   "type": "integer"
                 }
               }
@@ -27238,7 +27661,11 @@
           },
           "metadata": {
             "description": "The optional key-value map with additional details about the Draft Order.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27251,12 +27678,12 @@
           },
           "is_disabled": {
             "type": "boolean",
-            "description": "Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers."
+            "description": "Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers."
           },
           "ends_at": {
             "type": "string",
             "format": "date-time",
-            "description": "The time at which the Gift Card should no longer be available."
+            "description": "The date and time at which the Gift Card should no longer be available."
           },
           "region_id": {
             "description": "The ID of the Region in which the Gift Card can be used.",
@@ -27264,7 +27691,11 @@
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27280,12 +27711,12 @@
           },
           "is_disabled": {
             "type": "boolean",
-            "description": "Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers."
+            "description": "Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers."
           },
           "ends_at": {
             "type": "string",
             "format": "date-time",
-            "description": "The time at which the Gift Card should no longer be available."
+            "description": "The date and time at which the Gift Card should no longer be available."
           },
           "region_id": {
             "description": "The ID of the Region in which the Gift Card can be used.",
@@ -27293,7 +27724,11 @@
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27359,15 +27794,15 @@
         ],
         "properties": {
           "location_id": {
-            "description": "the item location ID",
+            "description": "the ID of the stock location",
             "type": "string"
           },
           "stocked_quantity": {
-            "description": "the stock quantity of an inventory item at the given location ID",
+            "description": "the stock quantity of the inventory item at this location",
             "type": "number"
           },
           "incoming_quantity": {
-            "description": "the incoming stock quantity of an inventory item at the given location ID",
+            "description": "the incoming stock quantity of the inventory item at this location",
             "type": "number"
           }
         }
@@ -27376,7 +27811,7 @@
         "type": "object",
         "properties": {
           "sku": {
-            "description": "The unique SKU for the Product Variant.",
+            "description": "The unique SKU of the associated Product Variant.",
             "type": "string"
           },
           "ean": {
@@ -27392,54 +27827,58 @@
             "type": "string"
           },
           "hs_code": {
-            "description": "The Harmonized System code for the Product Variant.",
+            "description": "The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.",
             "type": "string"
           },
           "inventory_quantity": {
-            "description": "The amount of stock kept for the Product Variant.",
+            "description": "The amount of stock kept of the associated Product Variant.",
             "type": "integer",
             "default": 0
           },
           "allow_backorder": {
-            "description": "Whether the Product Variant can be purchased when out of stock.",
+            "description": "Whether the associated Product Variant can be purchased when out of stock.",
             "type": "boolean"
           },
           "manage_inventory": {
-            "description": "Whether Medusa should keep track of the inventory for this Product Variant.",
+            "description": "Whether Medusa should keep track of the inventory for the associated Product Variant.",
             "type": "boolean",
             "default": true
           },
           "weight": {
-            "description": "The wieght of the Product Variant.",
+            "description": "The weight of the Inventory Item. May be used in shipping rate calculations.",
             "type": "number"
           },
           "length": {
-            "description": "The length of the Product Variant.",
+            "description": "The length of the Inventory Item. May be used in shipping rate calculations.",
             "type": "number"
           },
           "height": {
-            "description": "The height of the Product Variant.",
+            "description": "The height of the Inventory Item. May be used in shipping rate calculations.",
             "type": "number"
           },
           "width": {
-            "description": "The width of the Product Variant.",
+            "description": "The width of the Inventory Item. May be used in shipping rate calculations.",
             "type": "number"
           },
           "origin_country": {
-            "description": "The country of origin of the Product Variant.",
+            "description": "The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.",
             "type": "string"
           },
           "mid_code": {
-            "description": "The Manufacturer Identification code for the Product Variant.",
+            "description": "The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.",
             "type": "string"
           },
           "material": {
-            "description": "The material composition of the Product Variant.",
+            "description": "The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.",
             "type": "string"
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27451,11 +27890,11 @@
         ],
         "properties": {
           "token": {
-            "description": "The invite token provided by the admin.",
+            "description": "The token of the invite to accept. This is a unique token generated when the invite was created or resent.",
             "type": "string"
           },
           "user": {
-            "description": "The User to create.",
+            "description": "The details of the user to create.",
             "type": "object",
             "required": [
               "first_name",
@@ -27472,7 +27911,7 @@
                 "description": "the last name of the User"
               },
               "password": {
-                "description": "The desired password for the User",
+                "description": "The password for the User",
                 "type": "string",
                 "format": "password"
               }
@@ -27488,12 +27927,12 @@
         ],
         "properties": {
           "user": {
-            "description": "The email for the user to be created.",
+            "description": "The email associated with the invite. Once the invite is accepted, the email will be associated with the created user.",
             "type": "string",
             "format": "email"
           },
           "role": {
-            "description": "The role of the user to be created.",
+            "description": "The role of the user to be created. This does not actually change the privileges of the user that is eventually created.",
             "type": "string",
             "enum": [
               "admin",
@@ -27511,7 +27950,7 @@
         "properties": {
           "value": {
             "type": "string",
-            "description": "The updated description of the Note."
+            "description": "The description of the Note."
           }
         }
       },
@@ -27525,11 +27964,11 @@
         "properties": {
           "resource_id": {
             "type": "string",
-            "description": "The ID of the resource which the Note relates to."
+            "description": "The ID of the resource which the Note relates to. For example, an order ID."
           },
           "resource_type": {
             "type": "string",
-            "description": "The type of resource which the Note relates to."
+            "description": "The type of resource which the Note relates to. For example, `order`."
           },
           "value": {
             "type": "string",
@@ -27541,7 +27980,7 @@
         "type": "object",
         "properties": {
           "to": {
-            "description": "A new address or user identifier that the Notification should be sent to",
+            "description": "A new address or user identifier that the Notification should be sent to. If not provided, the previous `to` field of the notification will be used.",
             "type": "string"
           }
         }
@@ -27566,16 +28005,20 @@
         ],
         "properties": {
           "variant_id": {
-            "description": "The ID of the variant ID to add",
+            "description": "The ID of the product variant associated with the item.",
             "type": "string"
           },
           "quantity": {
-            "description": "The quantity to add",
+            "description": "The quantity of the item.",
             "type": "number"
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27583,7 +28026,7 @@
         "type": "object",
         "properties": {
           "internal_note": {
-            "description": "An optional note to create or update for the order edit.",
+            "description": "An optional note to create or update in the order edit.",
             "type": "string"
           }
         }
@@ -27599,7 +28042,7 @@
             "type": "string"
           },
           "internal_note": {
-            "description": "An optional note to create for the order edit.",
+            "description": "An optional note to associate with the order edit.",
             "type": "string"
           }
         }
@@ -27609,10 +28052,14 @@
         "properties": {
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           },
           "no_notification": {
-            "description": "If set to true no notification will be send related to this Claim.",
+            "description": "If set to `true`, no notification will be sent to the customer related to this Claim.",
             "type": "boolean"
           }
         }
@@ -27693,7 +28140,11 @@
                 },
                 "metadata": {
                   "description": "An optional set of key-value pairs to hold additional information.",
-                  "type": "object"
+                  "type": "object",
+                  "externalDocs": {
+                    "description": "Learn about the metadata attribute, and how to delete and update it.",
+                    "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+                  }
                 }
               }
             }
@@ -27729,7 +28180,11 @@
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27744,7 +28199,7 @@
             "type": "string"
           },
           "tracking_numbers": {
-            "description": "The tracking numbers for the shipment.",
+            "description": "An array of tracking numbers for the shipment.",
             "type": "array",
             "items": {
               "type": "string"
@@ -27800,7 +28255,7 @@
                   ]
                 },
                 "tags": {
-                  "description": "A list o tags to add to the Claim Item",
+                  "description": "A list of tags to add to the Claim Item",
                   "type": "array",
                   "items": {
                     "type": "string"
@@ -27816,7 +28271,7 @@
             }
           },
           "return_shipping": {
-            "description": "Optional details for the Return Shipping Method, if the items are to be sent back.",
+            "description": "Optional details for the Return Shipping Method, if the items are to be sent back. Providing this field will result in a return being created and associated with the claim.",
             "type": "object",
             "properties": {
               "option_id": {
@@ -27830,7 +28285,7 @@
             }
           },
           "additional_items": {
-            "description": "The new items to send to the Customer when the Claim type is Replace.",
+            "description": "The new items to send to the Customer. This is only used if the claim's type is `replace`.",
             "type": "array",
             "items": {
               "type": "object",
@@ -27840,18 +28295,18 @@
               ],
               "properties": {
                 "variant_id": {
-                  "description": "The ID of the Product Variant to ship.",
+                  "description": "The ID of the Product Variant.",
                   "type": "string"
                 },
                 "quantity": {
-                  "description": "The quantity of the Product Variant to ship.",
+                  "description": "The quantity of the Product Variant.",
                   "type": "integer"
                 }
               }
             }
           },
           "shipping_methods": {
-            "description": "The Shipping Methods to send the additional Line Items with.",
+            "description": "The Shipping Methods to send the additional Line Items with. This is only used if the claim's type is `replace`.",
             "type": "array",
             "items": {
               "type": "object",
@@ -27876,11 +28331,11 @@
             }
           },
           "shipping_address": {
-            "description": "An optional shipping address to send the claim to. Defaults to the parent order's shipping address",
+            "description": "An optional shipping address to send the claimed items to. If not provided, the parent order's shipping address will be used.",
             "$ref": "#/components/schemas/AddressPayload"
           },
           "refund_amount": {
-            "description": "The amount to refund the Customer when the Claim type is `refund`.",
+            "description": "The amount to refund the customer. This is used when the claim's type is `refund`.",
             "type": "integer"
           },
           "no_notification": {
@@ -27889,7 +28344,11 @@
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27910,7 +28369,7 @@
               ],
               "properties": {
                 "item_id": {
-                  "description": "The ID of Line Item to fulfill.",
+                  "description": "The ID of the Line Item to fulfill.",
                   "type": "string"
                 },
                 "quantity": {
@@ -27921,12 +28380,16 @@
             }
           },
           "no_notification": {
-            "description": "If set to true no notification will be send related to this Swap.",
+            "description": "If set to `true`, no notification will be sent to the customer related to this fulfillment.",
             "type": "boolean"
           },
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -27938,7 +28401,7 @@
         ],
         "properties": {
           "amount": {
-            "description": "The amount to refund.",
+            "description": "The amount to refund. It should be less than or equal the `refundable_amount` of the order.",
             "type": "integer"
           },
           "reason": {
@@ -27950,7 +28413,7 @@
             "type": "string"
           },
           "no_notification": {
-            "description": "If set to true no notification will be send related to this Refund.",
+            "description": "If set to `true`, no notification will be sent to the customer related to this Refund.",
             "type": "boolean"
           }
         }
@@ -27959,49 +28422,49 @@
         "type": "object",
         "properties": {
           "email": {
-            "description": "the email for the order",
+            "description": "the email associated with the order",
             "type": "string"
           },
           "billing_address": {
-            "description": "Billing address",
+            "description": "The order's billing address",
             "$ref": "#/components/schemas/AddressPayload"
           },
           "shipping_address": {
-            "description": "Shipping address",
+            "description": "The order's shipping address",
             "$ref": "#/components/schemas/AddressPayload"
           },
           "items": {
-            "description": "The Line Items for the order",
+            "description": "The line items of the order",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
           },
           "region": {
-            "description": "ID of the region where the order belongs",
+            "description": "ID of the region that the order is associated with.",
             "type": "string"
           },
           "discounts": {
-            "description": "Discounts applied to the order",
+            "description": "The discounts applied to the order",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/Discount"
             }
           },
           "customer_id": {
-            "description": "ID of the customer",
+            "description": "The ID of the customer associated with the order.",
             "type": "string"
           },
           "payment_method": {
-            "description": "payment method chosen for the order",
+            "description": "The payment method chosen for the order.",
             "type": "object",
             "properties": {
               "provider_id": {
                 "type": "string",
-                "description": "ID of the payment provider"
+                "description": "The ID of the payment provider."
               },
               "data": {
-                "description": "Data relevant for the given payment method",
+                "description": "Any data relevant for the given payment method.",
                 "type": "object"
               }
             }
@@ -28024,7 +28487,7 @@
               },
               "data": {
                 "type": "object",
-                "description": "Data relevant to the specific shipping method."
+                "description": "Any data relevant to the specific shipping method."
               },
               "items": {
                 "type": "array",
@@ -28036,7 +28499,7 @@
             }
           },
           "no_notification": {
-            "description": "A flag to indicate if no notifications should be emitted related to the updated order.",
+            "description": "If set to `true`, no notification will be sent to the customer related to this order.",
             "type": "boolean"
           }
         }
@@ -28048,7 +28511,7 @@
         ],
         "properties": {
           "items": {
-            "description": "The Line Items that will be returned.",
+            "description": "The line items that will be returned.",
             "type": "array",
             "items": {
               "type": "object",
@@ -28100,7 +28563,7 @@
             "default": false
           },
           "no_notification": {
-            "description": "A flag to indicate if no notifications should be emitted related to the requested Return.",
+            "description": "If set to `true`, no notification will be sent to the customer related to this Return.",
             "type": "boolean"
           },
           "refund": {
@@ -28149,7 +28612,7 @@
           },
           "date": {
             "type": "object",
-            "description": "The data required for the Shipping Option to create a Shipping Method. This will depend on the Fulfillment Provider."
+            "description": "The data required for the Shipping Option to create a Shipping Method. This depends on the Fulfillment Provider."
           }
         }
       },
@@ -28160,7 +28623,7 @@
         ],
         "properties": {
           "return_items": {
-            "description": "The Line Items to return as part of the Swap.",
+            "description": "The Line Items to associate with the swap's return.",
             "type": "array",
             "items": {
               "type": "object",
@@ -28170,7 +28633,7 @@
               ],
               "properties": {
                 "item_id": {
-                  "description": "The ID of the Line Item that will be claimed.",
+                  "description": "The ID of the Line Item that will be returned.",
                   "type": "string"
                 },
                 "quantity": {
@@ -28189,7 +28652,7 @@
             }
           },
           "return_shipping": {
-            "description": "How the Swap will be returned.",
+            "description": "The shipping method associated with the swap's return.",
             "type": "object",
             "required": [
               "option_id"
@@ -28216,18 +28679,18 @@
               ],
               "properties": {
                 "variant_id": {
-                  "description": "The ID of the Product Variant to ship.",
+                  "description": "The ID of the Product Variant.",
                   "type": "string"
                 },
                 "quantity": {
-                  "description": "The quantity of the Product Variant to ship.",
+                  "description": "The quantity of the Product Variant.",
                   "type": "integer"
                 }
               }
             }
           },
           "custom_shipping_options": {
-            "description": "The custom shipping options to potentially create a Shipping Method from.",
+            "description": "An array of custom shipping options to potentially create a Shipping Method from to send the additional items.",
             "type": "array",
             "items": {
               "type": "object",
@@ -28237,7 +28700,7 @@
               ],
               "properties": {
                 "option_id": {
-                  "description": "The ID of the Shipping Option to override with a custom price.",
+                  "description": "The ID of the Shipping Option.",
                   "type": "string"
                 },
                 "price": {
@@ -28248,11 +28711,11 @@
             }
           },
           "no_notification": {
-            "description": "If set to true no notification will be send related to this Swap.",
+            "description": "If set to `true`, no notification will be sent to the customer related to this Swap.",
             "type": "boolean"
           },
           "allow_backorder": {
-            "description": "If true, swaps can be completed with items out of stock",
+            "description": "If set to `true`, swaps can be completed with items out of stock",
             "type": "boolean",
             "default": true
           }
@@ -28263,10 +28726,14 @@
         "properties": {
           "metadata": {
             "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           },
           "no_notification": {
-            "description": "If set to true no notification will be send related to this Claim.",
+            "description": "If set to `true`, no notification will be sent to the customer related to this swap.",
             "type": "boolean"
           }
         }
@@ -28333,11 +28800,11 @@
                   "type": "string"
                 },
                 "region_id": {
-                  "description": "The ID of the Region for which the price is used. Only required if currecny_code is not provided.",
+                  "description": "The ID of the Region for which the price is used. This is only required if `currecny_code` is not provided.",
                   "type": "string"
                 },
                 "currency_code": {
-                  "description": "The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.",
+                  "description": "The 3 character ISO currency code for which the price will be used. This is only required if `region_id` is not provided.",
                   "type": "string",
                   "externalDocs": {
                     "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -28364,7 +28831,7 @@
             }
           },
           "override": {
-            "description": "If true the prices will replace all existing prices associated with the Price List.",
+            "description": "If set to `true`, the prices will replace all existing prices associated with the Price List.",
             "type": "boolean"
           }
         }
@@ -28377,7 +28844,7 @@
             "type": "string"
           },
           "description": {
-            "description": "A description of the Price List.",
+            "description": "The description of the Price List.",
             "type": "string"
           },
           "starts_at": {
@@ -28399,7 +28866,7 @@
             ]
           },
           "status": {
-            "description": "The status of the Price List.",
+            "description": "The status of the Price List. If the status is set to `draft`, the prices created in the price list will not be available of the customer.",
             "type": "string",
             "enum": [
               "active",
@@ -28421,11 +28888,11 @@
                   "type": "string"
                 },
                 "region_id": {
-                  "description": "The ID of the Region for which the price is used. Only required if currecny_code is not provided.",
+                  "description": "The ID of the Region for which the price is used. This is only required if `currecny_code` is not provided.",
                   "type": "string"
                 },
                 "currency_code": {
-                  "description": "The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.",
+                  "description": "The 3 character ISO currency code for which the price will be used. This is only required if `region_id` is not provided.",
                   "type": "string",
                   "externalDocs": {
                     "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -28453,7 +28920,7 @@
           },
           "customer_groups": {
             "type": "array",
-            "description": "A list of customer groups that the Price List applies to.",
+            "description": "An array of customer groups that the Price List applies to.",
             "items": {
               "type": "object",
               "required": [
@@ -28468,7 +28935,8 @@
             }
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Tax included in prices of price list",
+            "description": "Tax included in prices of price list",
+            "x-featureFlag": "tax_inclusive_pricing",
             "type": "boolean"
           }
         }
@@ -28483,11 +28951,11 @@
         ],
         "properties": {
           "name": {
-            "description": "The name of the Price List",
+            "description": "The name of the Price List.",
             "type": "string"
           },
           "description": {
-            "description": "A description of the Price List.",
+            "description": "The description of the Price List.",
             "type": "string"
           },
           "starts_at": {
@@ -28509,7 +28977,7 @@
             ]
           },
           "status": {
-            "description": "The status of the Price List.",
+            "description": "The status of the Price List. If the status is set to `draft`, the prices created in the price list will not be available of the customer.",
             "type": "string",
             "enum": [
               "active",
@@ -28527,11 +28995,11 @@
               ],
               "properties": {
                 "region_id": {
-                  "description": "The ID of the Region for which the price is used. Only required if currecny_code is not provided.",
+                  "description": "The ID of the Region for which the price is used. This is only required if `currecny_code` is not provided.",
                   "type": "string"
                 },
                 "currency_code": {
-                  "description": "The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.",
+                  "description": "The 3 character ISO currency code for which the price will be used. This is only required if `region_id` is not provided.",
                   "type": "string",
                   "externalDocs": {
                     "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -28559,7 +29027,7 @@
           },
           "customer_groups": {
             "type": "array",
-            "description": "A list of customer groups that the Price List applies to.",
+            "description": "An array of customer groups that the Price List applies to.",
             "items": {
               "type": "object",
               "required": [
@@ -28574,7 +29042,8 @@
             }
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Tax included in prices of price list",
+            "description": "Tax included in prices of price list",
+            "x-featureFlag": "tax_inclusive_pricing",
             "type": "boolean"
           }
         }
@@ -28644,23 +29113,23 @@
         "properties": {
           "name": {
             "type": "string",
-            "description": "The name to identify the Product Category by."
+            "description": "The name of the product category"
           },
           "description": {
             "type": "string",
-            "description": "An optional text field to describe the Product Category by."
+            "description": "The description of the product category."
           },
           "handle": {
             "type": "string",
-            "description": "An optional handle to be used in slugs, if none is provided we will kebab-case the title."
+            "description": "The handle of the product category. If none is provided, the kebab-case version of the name will be used. This field can be used as a slug in URLs."
           },
           "is_internal": {
             "type": "boolean",
-            "description": "A flag to make product category an internal category for admins"
+            "description": "If set to `true`, the product category will only be available to admins."
           },
           "is_active": {
             "type": "boolean",
-            "description": "A flag to make product category visible/hidden in the store front"
+            "description": "If set to `false`, the product category will not be available in the storefront."
           },
           "parent_category_id": {
             "type": "string",
@@ -28704,8 +29173,9 @@
         ],
         "properties": {
           "title": {
-            "description": "The title the Product Option will be identified by i.e. \"Size\"",
-            "type": "string"
+            "description": "The title the Product Option.",
+            "type": "string",
+            "example": "Size"
           }
         }
       },
@@ -28721,30 +29191,30 @@
             "type": "string"
           },
           "description": {
-            "description": "A description of the Product.",
+            "description": "The description of the Product.",
             "type": "string"
           },
           "discountable": {
-            "description": "A flag to indicate if discounts can be applied to the LineItems generated from this Product",
+            "description": "A flag to indicate if discounts can be applied to the Line Items generated from this Product",
             "type": "boolean"
           },
           "images": {
-            "description": "Images of the Product.",
+            "description": "An array of images of the Product. Each value in the array is a URL to the image. You can use the upload endpoints to upload the image and obtain a URL.",
             "type": "array",
             "items": {
               "type": "string"
             }
           },
           "thumbnail": {
-            "description": "The thumbnail to use for the Product.",
+            "description": "The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload endpoints to upload the thumbnail and obtain a URL.",
             "type": "string"
           },
           "handle": {
-            "description": "A unique handle to identify the Product by.",
+            "description": "A unique handle to identify the Product by. If not provided, the kebab-case version of the product title will be used. This can be used as a slug in URLs.",
             "type": "string"
           },
           "status": {
-            "description": "The status of the product.",
+            "description": "The status of the product. The product is shown to the customer only if its status is `published`.",
             "type": "string",
             "enum": [
               "draft",
@@ -28761,7 +29231,7 @@
             ],
             "properties": {
               "id": {
-                "description": "The ID of the Product Type.",
+                "description": "The ID of an existing Product Type. If not provided, a new product type will be created.",
                 "type": "string"
               },
               "value": {
@@ -28771,11 +29241,11 @@
             }
           },
           "collection_id": {
-            "description": "The ID of the Collection the Product should belong to.",
+            "description": "The ID of the Product Collection the Product belongs to.",
             "type": "string"
           },
           "tags": {
-            "description": "Tags to associate the Product with.",
+            "description": "Product Tags to associate the Product with.",
             "type": "array",
             "items": {
               "type": "object",
@@ -28784,18 +29254,18 @@
               ],
               "properties": {
                 "id": {
-                  "description": "The ID of an existing Tag.",
+                  "description": "The ID of an existing Product Tag. If not provided, a new product tag will be created.",
                   "type": "string"
                 },
                 "value": {
-                  "description": "The value of the Tag, these will be upserted.",
+                  "description": "The value of the Tag. If the `id` is provided, the value of the existing tag will be updated.",
                   "type": "string"
                 }
               }
             }
           },
           "sales_channels": {
-            "description": "[EXPERIMENTAL] Sales channels to associate the Product with.",
+            "description": "Sales channels to associate the Product with.",
             "type": "array",
             "items": {
               "type": "object",
@@ -28811,7 +29281,8 @@
             }
           },
           "categories": {
-            "description": "Categories to add the Product to.",
+            "description": "Product categories to add the Product to.",
+            "x-featureFlag": "product_categories",
             "type": "array",
             "items": {
               "required": [
@@ -28826,85 +29297,94 @@
             }
           },
           "variants": {
-            "description": "A list of Product Variants to create with the Product.",
+            "description": "An array of Product Variants to create with the Product. Each product variant must have a unique combination of Product Option values.",
             "type": "array",
             "items": {
               "type": "object",
               "properties": {
                 "id": {
-                  "description": "The ID of the Product Variant.",
+                  "description": "The id of an existing product variant. If provided, the details of the product variant will be updated. If not, a new product variant will be created.",
                   "type": "string"
                 },
                 "title": {
-                  "description": "The title to identify the Product Variant by.",
+                  "description": "The title of the product variant.",
                   "type": "string"
                 },
                 "sku": {
-                  "description": "The unique SKU for the Product Variant.",
+                  "description": "The unique SKU of the product variant.",
                   "type": "string"
                 },
                 "ean": {
-                  "description": "The EAN number of the item.",
+                  "description": "The EAN number of the product variant.",
                   "type": "string"
                 },
                 "upc": {
-                  "description": "The UPC number of the item.",
+                  "description": "The UPC number of the product variant.",
                   "type": "string"
                 },
                 "barcode": {
-                  "description": "A generic GTIN field for the Product Variant.",
+                  "description": "A generic GTIN field of the product variant.",
                   "type": "string"
                 },
                 "hs_code": {
-                  "description": "The Harmonized System code for the Product Variant.",
+                  "description": "The Harmonized System code of the product variant.",
                   "type": "string"
                 },
                 "inventory_quantity": {
-                  "description": "The amount of stock kept for the Product Variant.",
+                  "description": "The amount of stock kept of the product variant.",
                   "type": "integer"
                 },
                 "allow_backorder": {
-                  "description": "Whether the Product Variant can be purchased when out of stock.",
+                  "description": "Whether the product variant can be purchased when out of stock.",
                   "type": "boolean"
                 },
                 "manage_inventory": {
-                  "description": "Whether Medusa should keep track of the inventory for this Product Variant.",
+                  "description": "Whether Medusa should keep track of the inventory of this product variant.",
                   "type": "boolean"
                 },
                 "weight": {
-                  "description": "The wieght of the Product Variant.",
+                  "description": "The weight of the product variant.",
                   "type": "number"
                 },
                 "length": {
-                  "description": "The length of the Product Variant.",
+                  "description": "The length of the product variant.",
                   "type": "number"
                 },
                 "height": {
-                  "description": "The height of the Product Variant.",
+                  "description": "The height of the product variant.",
                   "type": "number"
                 },
                 "width": {
-                  "description": "The width of the Product Variant.",
+                  "description": "The width of the product variant.",
                   "type": "number"
                 },
                 "origin_country": {
-                  "description": "The country of origin of the Product Variant.",
+                  "description": "The country of origin of the product variant.",
                   "type": "string"
                 },
                 "mid_code": {
-                  "description": "The Manufacturer Identification code for the Product Variant.",
+                  "description": "The Manufacturer Identification code of the product variant.",
                   "type": "string"
                 },
                 "material": {
-                  "description": "The material composition of the Product Variant.",
+                  "description": "The material composition of the product variant.",
                   "type": "string"
                 },
                 "metadata": {
                   "description": "An optional set of key-value pairs with additional information.",
-                  "type": "object"
+                  "type": "object",
+                  "externalDocs": {
+                    "description": "Learn about the metadata attribute, and how to delete and update it.",
+                    "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+                  }
                 },
                 "prices": {
                   "type": "array",
+                  "description": "An array of product variant prices. A product variant can have different prices for each region or currency code.",
+                  "externalDocs": {
+                    "url": "https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices",
+                    "description": "Product variant pricing."
+                  },
                   "items": {
                     "type": "object",
                     "required": [
@@ -28912,15 +29392,15 @@
                     ],
                     "properties": {
                       "id": {
-                        "description": "The ID of the Price.",
+                        "description": "The ID of the Price. If provided, the existing price will be updated. Otherwise, a new price will be created.",
                         "type": "string"
                       },
                       "region_id": {
-                        "description": "The ID of the Region for which the price is used. Only required if currency_code is not provided.",
+                        "description": "The ID of the Region the price will be used in. This is only required if `currency_code` is not provided.",
                         "type": "string"
                       },
                       "currency_code": {
-                        "description": "The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.",
+                        "description": "The 3 character ISO currency code the price will be used in. This is only required if `region_id` is not provided.",
                         "type": "string",
                         "externalDocs": {
                           "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -28928,15 +29408,15 @@
                         }
                       },
                       "amount": {
-                        "description": "The amount to charge for the Product Variant.",
+                        "description": "The price amount.",
                         "type": "integer"
                       },
                       "min_quantity": {
-                        "description": "The minimum quantity for which the price will be used.",
+                        "description": "The minimum quantity required to be added to the cart for the price to be used.",
                         "type": "integer"
                       },
                       "max_quantity": {
-                        "description": "The maximum quantity for which the price will be used.",
+                        "description": "The maximum quantity required to be added to the cart for the price to be used.",
                         "type": "integer"
                       }
                     }
@@ -28944,6 +29424,7 @@
                 },
                 "options": {
                   "type": "array",
+                  "description": "An array of Product Option values that the variant corresponds to.",
                   "items": {
                     "type": "object",
                     "required": [
@@ -28956,7 +29437,7 @@
                         "type": "string"
                       },
                       "value": {
-                        "description": "The value to give for the Product Option at the same index in the Product's `options` field.",
+                        "description": "The value of the Product Option.",
                         "type": "string"
                       }
                     }
@@ -28966,7 +29447,7 @@
             }
           },
           "weight": {
-            "description": "The wieght of the Product.",
+            "description": "The weight of the Product.",
             "type": "number"
           },
           "length": {
@@ -28986,7 +29467,7 @@
             "type": "string"
           },
           "mid_code": {
-            "description": "The Manufacturer Identification code for the Product.",
+            "description": "The Manufacturer Identification code of the Product.",
             "type": "string"
           },
           "material": {
@@ -28995,7 +29476,11 @@
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -29008,93 +29493,98 @@
         ],
         "properties": {
           "title": {
-            "description": "The title to identify the Product Variant by.",
+            "description": "The title of the product variant.",
             "type": "string"
           },
           "sku": {
-            "description": "The unique SKU for the Product Variant.",
+            "description": "The unique SKU of the product variant.",
             "type": "string"
           },
           "ean": {
-            "description": "The EAN number of the item.",
+            "description": "The EAN number of the product variant.",
             "type": "string"
           },
           "upc": {
-            "description": "The UPC number of the item.",
+            "description": "The UPC number of the product variant.",
             "type": "string"
           },
           "barcode": {
-            "description": "A generic GTIN field for the Product Variant.",
+            "description": "A generic GTIN field of the product variant.",
             "type": "string"
           },
           "hs_code": {
-            "description": "The Harmonized System code for the Product Variant.",
+            "description": "The Harmonized System code of the product variant.",
             "type": "string"
           },
           "inventory_quantity": {
-            "description": "The amount of stock kept for the Product Variant.",
+            "description": "The amount of stock kept of the product variant.",
             "type": "integer",
             "default": 0
           },
           "allow_backorder": {
-            "description": "Whether the Product Variant can be purchased when out of stock.",
+            "description": "Whether the product variant can be purchased when out of stock.",
             "type": "boolean"
           },
           "manage_inventory": {
-            "description": "Whether Medusa should keep track of the inventory for this Product Variant.",
+            "description": "Whether Medusa should keep track of the inventory of this product variant.",
             "type": "boolean",
             "default": true
           },
           "weight": {
-            "description": "The wieght of the Product Variant.",
+            "description": "The wieght of the product variant.",
             "type": "number"
           },
           "length": {
-            "description": "The length of the Product Variant.",
+            "description": "The length of the product variant.",
             "type": "number"
           },
           "height": {
-            "description": "The height of the Product Variant.",
+            "description": "The height of the product variant.",
             "type": "number"
           },
           "width": {
-            "description": "The width of the Product Variant.",
+            "description": "The width of the product variant.",
             "type": "number"
           },
           "origin_country": {
-            "description": "The country of origin of the Product Variant.",
+            "description": "The country of origin of the product variant.",
             "type": "string"
           },
           "mid_code": {
-            "description": "The Manufacturer Identification code for the Product Variant.",
+            "description": "The Manufacturer Identification code of the product variant.",
             "type": "string"
           },
           "material": {
-            "description": "The material composition of the Product Variant.",
+            "description": "The material composition of the product variant.",
             "type": "string"
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           },
           "prices": {
             "type": "array",
+            "description": "An array of product variant prices. A product variant can have different prices for each region or currency code.",
+            "externalDocs": {
+              "url": "https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices",
+              "description": "Product variant pricing."
+            },
             "items": {
               "type": "object",
               "required": [
                 "amount"
               ],
               "properties": {
-                "id": {
-                  "description": "The ID of the price.",
-                  "type": "string"
-                },
                 "region_id": {
-                  "description": "The ID of the Region for which the price is used. Only required if currency_code is not provided.",
+                  "description": "The ID of the Region the price will be used in. This is only required if `currency_code` is not provided.",
                   "type": "string"
                 },
                 "currency_code": {
-                  "description": "The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.",
+                  "description": "The 3 character ISO currency code the price will be used in. This is only required if `region_id` is not provided.",
                   "type": "string",
                   "externalDocs": {
                     "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -29102,15 +29592,15 @@
                   }
                 },
                 "amount": {
-                  "description": "The amount to charge for the Product Variant.",
+                  "description": "The price amount.",
                   "type": "integer"
                 },
                 "min_quantity": {
-                  "description": "The minimum quantity for which the price will be used.",
+                  "description": "The minimum quantity required to be added to the cart for the price to be used.",
                   "type": "integer"
                 },
                 "max_quantity": {
-                  "description": "The maximum quantity for which the price will be used.",
+                  "description": "The maximum quantity required to be added to the cart for the price to be used.",
                   "type": "integer"
                 }
               }
@@ -29118,6 +29608,7 @@
           },
           "options": {
             "type": "array",
+            "description": "An array of Product Option values that the variant corresponds to.",
             "items": {
               "type": "object",
               "required": [
@@ -29126,11 +29617,11 @@
               ],
               "properties": {
                 "option_id": {
-                  "description": "The ID of the Product Option to set the value for.",
+                  "description": "The ID of the Product Option.",
                   "type": "string"
                 },
                 "value": {
-                  "description": "The value to give for the Product Option.",
+                  "description": "A value to give to the Product Option.",
                   "type": "string"
                 }
               }
@@ -29142,11 +29633,11 @@
         "type": "object",
         "properties": {
           "title": {
-            "description": "The title to identify the Product Variant by.",
+            "description": "The title of the product variant.",
             "type": "string"
           },
           "sku": {
-            "description": "The unique SKU for the Product Variant.",
+            "description": "The unique SKU of the product variant.",
             "type": "string"
           },
           "ean": {
@@ -29158,59 +29649,68 @@
             "type": "string"
           },
           "barcode": {
-            "description": "A generic GTIN field for the Product Variant.",
+            "description": "A generic GTIN field of the product variant.",
             "type": "string"
           },
           "hs_code": {
-            "description": "The Harmonized System code for the Product Variant.",
+            "description": "The Harmonized System code of the product variant.",
             "type": "string"
           },
           "inventory_quantity": {
-            "description": "The amount of stock kept for the Product Variant.",
+            "description": "The amount of stock kept of the product variant.",
             "type": "integer"
           },
           "allow_backorder": {
-            "description": "Whether the Product Variant can be purchased when out of stock.",
+            "description": "Whether the product variant can be purchased when out of stock.",
             "type": "boolean"
           },
           "manage_inventory": {
-            "description": "Whether Medusa should keep track of the inventory for this Product Variant.",
+            "description": "Whether Medusa should keep track of the inventory of this product variant.",
             "type": "boolean"
           },
           "weight": {
-            "description": "The weight of the Product Variant.",
+            "description": "The weight of the product variant.",
             "type": "number"
           },
           "length": {
-            "description": "The length of the Product Variant.",
+            "description": "The length of the product variant.",
             "type": "number"
           },
           "height": {
-            "description": "The height of the Product Variant.",
+            "description": "The height of the product variant.",
             "type": "number"
           },
           "width": {
-            "description": "The width of the Product Variant.",
+            "description": "The width of the product variant.",
             "type": "number"
           },
           "origin_country": {
-            "description": "The country of origin of the Product Variant.",
+            "description": "The country of origin of the product variant.",
             "type": "string"
           },
           "mid_code": {
-            "description": "The Manufacturer Identification code for the Product Variant.",
+            "description": "The Manufacturer Identification code of the product variant.",
             "type": "string"
           },
           "material": {
-            "description": "The material composition of the Product Variant.",
+            "description": "The material composition of the product variant.",
             "type": "string"
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           },
           "prices": {
             "type": "array",
+            "description": "An array of product variant prices. A product variant can have different prices for each region or currency code.",
+            "externalDocs": {
+              "url": "https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices",
+              "description": "Product variant pricing."
+            },
             "items": {
               "type": "object",
               "required": [
@@ -29218,15 +29718,15 @@
               ],
               "properties": {
                 "id": {
-                  "description": "The ID of the price.",
+                  "description": "The ID of the price. If provided, the existing price will be updated. Otherwise, a new price will be created.",
                   "type": "string"
                 },
                 "region_id": {
-                  "description": "The ID of the Region for which the price is used. Only required if currency_code is not provided.",
+                  "description": "The ID of the Region the price will be used in. This is only required if `currency_code` is not provided.",
                   "type": "string"
                 },
                 "currency_code": {
-                  "description": "The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.",
+                  "description": "The 3 character ISO currency code the price will be used in. This is only required if `region_id` is not provided.",
                   "type": "string",
                   "externalDocs": {
                     "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -29234,15 +29734,15 @@
                   }
                 },
                 "amount": {
-                  "description": "The amount to charge for the Product Variant.",
+                  "description": "The price amount.",
                   "type": "integer"
                 },
                 "min_quantity": {
-                  "description": "The minimum quantity for which the price will be used.",
+                  "description": "The minimum quantity required to be added to the cart for the price to be used.",
                   "type": "integer"
                 },
                 "max_quantity": {
-                  "description": "The maximum quantity for which the price will be used.",
+                  "description": "The maximum quantity required to be added to the cart for the price to be used.",
                   "type": "integer"
                 }
               }
@@ -29250,6 +29750,7 @@
           },
           "options": {
             "type": "array",
+            "description": "An array of Product Option values that the variant corresponds to.",
             "items": {
               "type": "object",
               "required": [
@@ -29258,11 +29759,11 @@
               ],
               "properties": {
                 "option_id": {
-                  "description": "The ID of the Product Option to set the value for.",
+                  "description": "The ID of the Product Option.",
                   "type": "string"
                 },
                 "value": {
-                  "description": "The value to give for the Product Option.",
+                  "description": "The value of the Product Option.",
                   "type": "string"
                 }
               }
@@ -29285,7 +29786,7 @@
             "type": "string"
           },
           "description": {
-            "description": "A description of the Product.",
+            "description": "The description of the Product.",
             "type": "string"
           },
           "is_giftcard": {
@@ -29294,27 +29795,27 @@
             "default": false
           },
           "discountable": {
-            "description": "A flag to indicate if discounts can be applied to the LineItems generated from this Product",
+            "description": "A flag to indicate if discounts can be applied to the Line Items generated from this Product",
             "type": "boolean",
             "default": true
           },
           "images": {
-            "description": "Images of the Product.",
+            "description": "An array of images of the Product. Each value in the array is a URL to the image. You can use the upload endpoints to upload the image and obtain a URL.",
             "type": "array",
             "items": {
               "type": "string"
             }
           },
           "thumbnail": {
-            "description": "The thumbnail to use for the Product.",
+            "description": "The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload endpoints to upload the thumbnail and obtain a URL.",
             "type": "string"
           },
           "handle": {
-            "description": "A unique handle to identify the Product by.",
+            "description": "A unique handle to identify the Product by. If not provided, the kebab-case version of the product title will be used. This can be used as a slug in URLs.",
             "type": "string"
           },
           "status": {
-            "description": "The status of the product.",
+            "description": "The status of the product. The product is shown to the customer only if its status is `published`.",
             "type": "string",
             "enum": [
               "draft",
@@ -29332,7 +29833,7 @@
             ],
             "properties": {
               "id": {
-                "description": "The ID of the Product Type.",
+                "description": "The ID of an existing Product Type. If not provided, a new product type will be created.",
                 "type": "string"
               },
               "value": {
@@ -29342,11 +29843,11 @@
             }
           },
           "collection_id": {
-            "description": "The ID of the Collection the Product should belong to.",
+            "description": "The ID of the Product Collection the Product belongs to.",
             "type": "string"
           },
           "tags": {
-            "description": "Tags to associate the Product with.",
+            "description": "Product Tags to associate the Product with.",
             "type": "array",
             "items": {
               "type": "object",
@@ -29355,18 +29856,18 @@
               ],
               "properties": {
                 "id": {
-                  "description": "The ID of an existing Tag.",
+                  "description": "The ID of an existing Product Tag. If not provided, a new product tag will be created.",
                   "type": "string"
                 },
                 "value": {
-                  "description": "The value of the Tag, these will be upserted.",
+                  "description": "The value of the Tag. If the `id` is provided, the value of the existing tag will be updated.",
                   "type": "string"
                 }
               }
             }
           },
           "sales_channels": {
-            "description": "[EXPERIMENTAL] Sales channels to associate the Product with.",
+            "description": "Sales channels to associate the Product with.",
             "type": "array",
             "items": {
               "type": "object",
@@ -29382,7 +29883,8 @@
             }
           },
           "categories": {
-            "description": "Categories to add the Product to.",
+            "description": "Product categories to add the Product to.",
+            "x-featureFlag": "product_categories",
             "type": "array",
             "items": {
               "required": [
@@ -29397,7 +29899,7 @@
             }
           },
           "options": {
-            "description": "The Options that the Product should have. These define on which properties the Product's Product Variants will differ.",
+            "description": "The Options that the Product should have. A new product option will be created for every item in the array.",
             "type": "array",
             "items": {
               "type": "object",
@@ -29406,14 +29908,14 @@
               ],
               "properties": {
                 "title": {
-                  "description": "The title to identify the Product Option by.",
+                  "description": "The title of the Product Option.",
                   "type": "string"
                 }
               }
             }
           },
           "variants": {
-            "description": "A list of Product Variants to create with the Product.",
+            "description": "An array of Product Variants to create with the Product. Each product variant must have a unique combination of Product Option values.",
             "type": "array",
             "items": {
               "type": "object",
@@ -29422,11 +29924,11 @@
               ],
               "properties": {
                 "title": {
-                  "description": "The title to identify the Product Variant by.",
+                  "description": "The title of the Product Variant.",
                   "type": "string"
                 },
                 "sku": {
-                  "description": "The unique SKU for the Product Variant.",
+                  "description": "The unique SKU of the Product Variant.",
                   "type": "string"
                 },
                 "ean": {
@@ -29438,15 +29940,15 @@
                   "type": "string"
                 },
                 "barcode": {
-                  "description": "A generic GTIN field for the Product Variant.",
+                  "description": "A generic GTIN field of the Product Variant.",
                   "type": "string"
                 },
                 "hs_code": {
-                  "description": "The Harmonized System code for the Product Variant.",
+                  "description": "The Harmonized System code of the Product Variant.",
                   "type": "string"
                 },
                 "inventory_quantity": {
-                  "description": "The amount of stock kept for the Product Variant.",
+                  "description": "The amount of stock kept of the Product Variant.",
                   "type": "integer",
                   "default": 0
                 },
@@ -29455,7 +29957,7 @@
                   "type": "boolean"
                 },
                 "manage_inventory": {
-                  "description": "Whether Medusa should keep track of the inventory for this Product Variant.",
+                  "description": "Whether Medusa should keep track of the inventory of this Product Variant.",
                   "type": "boolean"
                 },
                 "weight": {
@@ -29479,7 +29981,7 @@
                   "type": "string"
                 },
                 "mid_code": {
-                  "description": "The Manufacturer Identification code for the Product Variant.",
+                  "description": "The Manufacturer Identification code of the Product Variant.",
                   "type": "string"
                 },
                 "material": {
@@ -29488,10 +29990,19 @@
                 },
                 "metadata": {
                   "description": "An optional set of key-value pairs with additional information.",
-                  "type": "object"
+                  "type": "object",
+                  "externalDocs": {
+                    "description": "Learn about the metadata attribute, and how to delete and update it.",
+                    "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+                  }
                 },
                 "prices": {
                   "type": "array",
+                  "description": "An array of product variant prices. A product variant can have different prices for each region or currency code.",
+                  "externalDocs": {
+                    "url": "https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices",
+                    "description": "Product variant pricing."
+                  },
                   "items": {
                     "type": "object",
                     "required": [
@@ -29499,11 +30010,11 @@
                     ],
                     "properties": {
                       "region_id": {
-                        "description": "The ID of the Region for which the price is used. Only required if currency_code is not provided.",
+                        "description": "The ID of the Region the price will be used in. This is only required if `currency_code` is not provided.",
                         "type": "string"
                       },
                       "currency_code": {
-                        "description": "The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.",
+                        "description": "The 3 character ISO currency code the price will be used in. This is only required if `region_id` is not provided.",
                         "type": "string",
                         "externalDocs": {
                           "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -29511,15 +30022,15 @@
                         }
                       },
                       "amount": {
-                        "description": "The amount to charge for the Product Variant.",
+                        "description": "The price amount.",
                         "type": "integer"
                       },
                       "min_quantity": {
-                        "description": "The minimum quantity for which the price will be used.",
+                        "description": "The minimum quantity required to be added to the cart for the price to be used.",
                         "type": "integer"
                       },
                       "max_quantity": {
-                        "description": "The maximum quantity for which the price will be used.",
+                        "description": "The maximum quantity required to be added to the cart for the price to be used.",
                         "type": "integer"
                       }
                     }
@@ -29527,6 +30038,11 @@
                 },
                 "options": {
                   "type": "array",
+                  "description": "An array of Product Option values that the variant corresponds to. The option values should be added into the array in the same index as in the `options` field of the product.",
+                  "externalDocs": {
+                    "url": "https://docs.medusajs.com/modules/products/admin/manage-products#create-a-product",
+                    "description": "Example of how to create a product with options and variants"
+                  },
                   "items": {
                     "type": "object",
                     "required": [
@@ -29560,7 +30076,7 @@
             "type": "number"
           },
           "hs_code": {
-            "description": "The Harmonized System code for the Product Variant.",
+            "description": "The Harmonized System code of the Product.",
             "type": "string"
           },
           "origin_country": {
@@ -29568,7 +30084,7 @@
             "type": "string"
           },
           "mid_code": {
-            "description": "The Manufacturer Identification code for the Product.",
+            "description": "The Manufacturer Identification code of the Product.",
             "type": "string"
           },
           "material": {
@@ -29577,7 +30093,11 @@
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -29604,7 +30124,7 @@
         ],
         "properties": {
           "sales_channel_ids": {
-            "description": "The IDs of the sales channels to add to the publishable api key",
+            "description": "The IDs of the sales channels to add to the publishable API key",
             "type": "array",
             "items": {
               "type": "object",
@@ -29625,7 +30145,7 @@
         "type": "object",
         "properties": {
           "title": {
-            "description": "A title to update for the key.",
+            "description": "The title of the Publishable API Key.",
             "type": "string"
           }
         }
@@ -29637,7 +30157,7 @@
         ],
         "properties": {
           "title": {
-            "description": "A title for the publishable api key",
+            "description": "The title of the publishable API key",
             "type": "string"
           }
         }
@@ -29665,7 +30185,7 @@
         ],
         "properties": {
           "provider_id": {
-            "description": "The ID of the Fulfillment Provider to add.",
+            "description": "The ID of the Fulfillment Provider.",
             "type": "string"
           }
         }
@@ -29677,7 +30197,7 @@
         ],
         "properties": {
           "provider_id": {
-            "description": "The ID of the Payment Provider to add.",
+            "description": "The ID of the Payment Provider.",
             "type": "string"
           }
         }
@@ -29690,7 +30210,7 @@
             "type": "string"
           },
           "currency_code": {
-            "description": "The 3 character ISO currency code to use for the Region.",
+            "description": "The 3 character ISO currency code to use in the Region.",
             "type": "string",
             "externalDocs": {
               "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -29698,45 +30218,50 @@
             }
           },
           "automatic_taxes": {
-            "description": "If true Medusa will automatically calculate taxes for carts in this region. If false you have to manually call POST /carts/:id/taxes.",
+            "description": "If set to `true`, the Medusa backend will automatically calculate taxes for carts in this region. If set to `false`, the taxes must be calculated manually.",
+            "externalDocs": {
+              "url": "https://docs.medusajs.com/modules/taxes/storefront/manual-calculation",
+              "description": "How to calculate taxes in a storefront."
+            },
             "type": "boolean"
           },
           "gift_cards_taxable": {
-            "description": "Whether gift cards in this region should be applied sales tax when purchasing a gift card",
+            "description": "If set to `true`, taxes will be applied on gift cards.",
             "type": "boolean"
           },
           "tax_provider_id": {
-            "description": "The ID of the tax provider to use; if null the system tax provider is used",
+            "description": "The ID of the tax provider to use. If none provided, the system tax provider is used.",
             "type": "string"
           },
           "tax_code": {
-            "description": "An optional tax code the Region.",
+            "description": "The tax code of the Region.",
             "type": "string"
           },
           "tax_rate": {
-            "description": "The tax rate to use on Orders in the Region.",
+            "description": "The tax rate to use in the Region.",
             "type": "number"
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Tax included in prices of region",
+            "x-featureFlag": "tax_inclusive_pricing",
+            "description": "Whether taxes are included in the prices of the region.",
             "type": "boolean"
           },
           "payment_providers": {
-            "description": "A list of Payment Provider IDs that should be enabled for the Region",
+            "description": "A list of Payment Provider IDs that can be used in the Region",
             "type": "array",
             "items": {
               "type": "string"
             }
           },
           "fulfillment_providers": {
-            "description": "A list of Fulfillment Provider IDs that should be enabled for the Region",
+            "description": "A list of Fulfillment Provider IDs that can be used in the Region",
             "type": "array",
             "items": {
               "type": "string"
             }
           },
           "countries": {
-            "description": "A list of countries' 2 ISO Characters that should be included in the Region.",
+            "description": "A list of countries' 2 ISO characters that should be included in the Region.",
             "type": "array",
             "items": {
               "type": "string"
@@ -29760,7 +30285,7 @@
             "type": "string"
           },
           "currency_code": {
-            "description": "The 3 character ISO currency code to use for the Region.",
+            "description": "The 3 character ISO currency code to use in the Region.",
             "type": "string",
             "externalDocs": {
               "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -29768,29 +30293,29 @@
             }
           },
           "tax_code": {
-            "description": "An optional tax code the Region.",
+            "description": "The tax code of the Region.",
             "type": "string"
           },
           "tax_rate": {
-            "description": "The tax rate to use on Orders in the Region.",
+            "description": "The tax rate to use in the Region.",
             "type": "number"
           },
           "payment_providers": {
-            "description": "A list of Payment Provider IDs that should be enabled for the Region",
+            "description": "A list of Payment Provider IDs that can be used in the Region",
             "type": "array",
             "items": {
               "type": "string"
             }
           },
           "fulfillment_providers": {
-            "description": "A list of Fulfillment Provider IDs that should be enabled for the Region",
+            "description": "A list of Fulfillment Provider IDs that can be used in the Region",
             "type": "array",
             "items": {
               "type": "string"
             }
           },
           "countries": {
-            "description": "A list of countries' 2 ISO Characters that should be included in the Region.",
+            "description": "A list of countries' 2 ISO characters that should be included in the Region.",
             "example": [
               "US"
             ],
@@ -29800,7 +30325,8 @@
             }
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Tax included in prices of region",
+            "x-featureFlag": "tax_inclusive_pricing",
+            "description": "Whether taxes are included in the prices of the region.",
             "type": "boolean"
           }
         }
@@ -29814,24 +30340,28 @@
         ],
         "properties": {
           "line_item_id": {
-            "description": "The id of the location of the reservation",
+            "description": "The ID of the line item of the reservation.",
             "type": "string"
           },
           "location_id": {
-            "description": "The id of the location of the reservation",
+            "description": "The ID of the location of the reservation.",
             "type": "string"
           },
           "inventory_item_id": {
-            "description": "The id of the inventory item the reservation relates to",
+            "description": "The ID of the inventory item the reservation is associated with.",
             "type": "string"
           },
           "quantity": {
-            "description": "The id of the reservation item",
+            "description": "The quantity to reserve.",
             "type": "number"
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -29839,16 +30369,20 @@
         "type": "object",
         "properties": {
           "location_id": {
-            "description": "The id of the location of the reservation",
+            "description": "The ID of the location associated with the reservation.",
             "type": "string"
           },
           "quantity": {
-            "description": "The id of the reservation item",
+            "description": "The quantity to reserve.",
             "type": "number"
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -29860,16 +30394,20 @@
             "type": "string"
           },
           "value": {
-            "description": "The value that the Return Reason will be identified by. Must be unique.",
+            "description": "A unique value of the return reason.",
             "type": "string"
           },
           "description": {
-            "description": "An optional description to for the Reason.",
+            "description": "The description of the Reason.",
             "type": "string"
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -29885,7 +30423,7 @@
             "type": "string"
           },
           "value": {
-            "description": "The value that the Return Reason will be identified by. Must be unique.",
+            "description": "A unique value of the return reason.",
             "type": "string"
           },
           "parent_return_reason_id": {
@@ -29893,12 +30431,16 @@
             "type": "string"
           },
           "description": {
-            "description": "An optional description to for the Reason.",
+            "description": "The description of the Reason.",
             "type": "string"
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -29986,7 +30528,7 @@
             "type": "string"
           },
           "is_disabled": {
-            "description": "Whether the Sales Channel is disabled or not.",
+            "description": "Whether the Sales Channel is disabled.",
             "type": "boolean"
           }
         }
@@ -29996,15 +30538,15 @@
         "properties": {
           "name": {
             "type": "string",
-            "description": "Name of the sales channel."
+            "description": "The name of the sales channel"
           },
           "description": {
             "type": "string",
-            "description": "Sales Channel description."
+            "description": "The description of the sales channel."
           },
           "is_disabled": {
             "type": "boolean",
-            "description": "Indication of if the sales channel is active."
+            "description": "Whether the Sales Channel is disabled."
           }
         }
       },
@@ -30019,16 +30561,20 @@
             "type": "string"
           },
           "amount": {
-            "description": "The amount to charge for the Shipping Option.",
+            "description": "The amount to charge for the Shipping Option. If the `price_type` of the shipping option is `calculated`, this amount will not actually be used.",
             "type": "integer"
           },
           "admin_only": {
-            "description": "If true, the option can be used for draft orders",
+            "description": "If set to `true`, the shipping option can only be used when creating draft orders.",
             "type": "boolean"
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           },
           "requirements": {
             "description": "The requirements that must be satisfied for the Shipping Option to be available.",
@@ -30041,7 +30587,7 @@
               ],
               "properties": {
                 "id": {
-                  "description": "The ID of the requirement",
+                  "description": "The ID of an existing requirement. If an ID is passed, the existing requirement's details are updated. Otherwise, a new requirement is created.",
                   "type": "string"
                 },
                 "type": {
@@ -30060,7 +30606,8 @@
             }
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Tax included in prices of shipping option",
+            "description": "Tax included in prices of shipping option",
+            "x-featureFlag": "tax_inclusive_pricing",
             "type": "boolean"
           }
         }
@@ -30096,7 +30643,7 @@
             "type": "object"
           },
           "price_type": {
-            "description": "The type of the Shipping Option price.",
+            "description": "The type of the Shipping Option price. `flat_rate` indicates fixed pricing, whereas `calculated` indicates that the price will be calculated each time by the fulfillment provider.",
             "type": "string",
             "enum": [
               "flat_rate",
@@ -30104,7 +30651,7 @@
             ]
           },
           "amount": {
-            "description": "The amount to charge for the Shipping Option.",
+            "description": "The amount to charge for the Shipping Option. If the `price_type` is set to `calculated`, this amount will not actually be used.",
             "type": "integer"
           },
           "requirements": {
@@ -30133,21 +30680,26 @@
             }
           },
           "is_return": {
-            "description": "Whether the Shipping Option defines a return shipment.",
+            "description": "Whether the Shipping Option can be used for returns or during checkout.",
             "type": "boolean",
             "default": false
           },
           "admin_only": {
-            "description": "If true, the option can be used for draft orders",
+            "description": "If set to `true`, the shipping option can only be used when creating draft orders.",
             "type": "boolean",
             "default": false
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Tax included in prices of shipping option",
+            "description": "Tax included in prices of shipping option",
+            "x-featureFlag": "tax_inclusive_pricing",
             "type": "boolean"
           }
         }
@@ -30161,7 +30713,11 @@
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           },
           "type": {
             "description": "The type of the Shipping Profile",
@@ -30173,11 +30729,11 @@
             ]
           },
           "products": {
-            "description": "An optional array of product ids to associate with the Shipping Profile",
+            "description": "product IDs to associate with the Shipping Profile",
             "type": "array"
           },
           "shipping_options": {
-            "description": "An optional array of shipping option ids to associate with the Shipping Profile",
+            "description": "Shipping option IDs to associate with the Shipping Profile",
             "type": "array"
           }
         }
@@ -30220,6 +30776,10 @@
             "description": "An optional key-value map with additional details",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           },
           "address": {
@@ -30238,7 +30798,7 @@
             "type": "string"
           },
           "address_id": {
-            "description": "the stock location address ID",
+            "description": "the ID of an existing stock location address to associate with the stock location. Only required if `address` is not provided.",
             "type": "string"
           },
           "metadata": {
@@ -30246,13 +30806,69 @@
             "description": "An optional key-value map with additional details",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           },
           "address": {
+            "description": "A new stock location address to create and associate with the stock location. Only required if `address_id` is not provided.",
             "$ref": "#/components/schemas/StockLocationAddressInput"
           }
         }
       },
+      "AdminPostStockLocationsReqAddress": {
+        "type": "object",
+        "required": [
+          "address_1",
+          "country_code"
+        ],
+        "properties": {
+          "address_1": {
+            "type": "string",
+            "description": "Stock location address",
+            "example": "35, Jhon Doe Ave"
+          },
+          "address_2": {
+            "type": "string",
+            "description": "Stock location address' complement",
+            "example": "apartment 4432"
+          },
+          "company": {
+            "type": "string",
+            "description": "Stock location address' company"
+          },
+          "city": {
+            "type": "string",
+            "description": "Stock location address' city",
+            "example": "Mexico city"
+          },
+          "country_code": {
+            "description": "The 2 character ISO code for the country.",
+            "type": "string",
+            "externalDocs": {
+              "url": "https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements",
+              "description": "See a list of codes."
+            }
+          },
+          "phone": {
+            "type": "string",
+            "description": "Stock location address' phone number",
+            "example": "+1 555 61646"
+          },
+          "postal_code": {
+            "type": "string",
+            "description": "Stock location address' postal code",
+            "example": "HD3-1G8"
+          },
+          "province": {
+            "type": "string",
+            "description": "Stock location address' province",
+            "example": "Sinaloa"
+          }
+        }
+      },
       "AdminPostStoreReq": {
         "type": "object",
         "properties": {
@@ -30261,19 +30877,22 @@
             "type": "string"
           },
           "swap_link_template": {
-            "description": "A template for Swap links - use `{{cart_id}}` to insert the Swap Cart id",
-            "type": "string"
+            "description": "A template for Swap links - use `{{cart_id}}` to insert the Swap Cart ID",
+            "type": "string",
+            "example": "http://example.com/swaps/{{cart_id}}"
           },
           "payment_link_template": {
-            "description": "A template for payment links links - use `{{cart_id}}` to insert the Cart id",
+            "description": "A template for payment links - use `{{cart_id}}` to insert the Cart ID",
+            "example": "http://example.com/payments/{{cart_id}}",
             "type": "string"
           },
           "invite_link_template": {
             "description": "A template for invite links - use `{{invite_token}}` to insert the invite token",
+            "example": "http://example.com/invite?token={{invite_token}}",
             "type": "string"
           },
           "default_currency_code": {
-            "description": "The default currency code for the Store.",
+            "description": "The default currency code of the Store.",
             "type": "string",
             "externalDocs": {
               "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
@@ -30281,15 +30900,23 @@
             }
           },
           "currencies": {
-            "description": "Array of currencies in 2 character ISO code format.",
+            "description": "Array of available currencies in the store. Each currency is in 3 character ISO code format.",
             "type": "array",
             "items": {
-              "type": "string"
+              "type": "string",
+              "externalDocs": {
+                "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
+                "description": "See a list of codes."
+              }
             }
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -30303,23 +30930,23 @@
         "properties": {
           "code": {
             "type": "string",
-            "description": "A code to identify the tax type by"
+            "description": "The code of the tax rate."
           },
           "name": {
             "type": "string",
-            "description": "A human friendly name for the tax"
+            "description": "The name of the tax rate."
           },
           "region_id": {
             "type": "string",
-            "description": "The ID of the Region that the rate belongs to"
+            "description": "The ID of the Region that the tax rate belongs to."
           },
           "rate": {
             "type": "number",
-            "description": "The numeric rate to charge"
+            "description": "The numeric rate to charge."
           },
           "products": {
             "type": "array",
-            "description": "The IDs of the products associated with this tax rate",
+            "description": "The IDs of the products associated with this tax rate.",
             "items": {
               "type": "string"
             }
@@ -30375,19 +31002,19 @@
         "properties": {
           "code": {
             "type": "string",
-            "description": "A code to identify the tax type by"
+            "description": "The code of the tax rate."
           },
           "name": {
             "type": "string",
-            "description": "A human friendly name for the tax"
+            "description": "The name of the tax rate."
           },
           "region_id": {
             "type": "string",
-            "description": "The ID of the Region that the rate belongs to"
+            "description": "The ID of the Region that the tax rate belongs to."
           },
           "rate": {
             "type": "number",
-            "description": "The numeric rate to charge"
+            "description": "The numeric rate to charge."
           },
           "products": {
             "type": "array",
@@ -30405,7 +31032,7 @@
           },
           "product_types": {
             "type": "array",
-            "description": "The IDs of the types of products associated with this tax rate",
+            "description": "The IDs of the types of product types associated with this tax rate",
             "items": {
               "type": "string"
             }
@@ -30451,12 +31078,12 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "The IDs of the deleted Money Amounts (Prices)."
+              "description": "The IDs of the deleted prices."
             }
           },
           "object": {
             "type": "string",
-            "description": "The type of the object that was deleted.",
+            "description": "The type of the object that was deleted. A price is also named `money-amount`.",
             "default": "money-amount"
           },
           "deleted": {
@@ -30476,14 +31103,14 @@
         "properties": {
           "ids": {
             "type": "array",
-            "description": "The price ids that have been deleted.",
+            "description": "The IDs of the deleted prices.",
             "items": {
               "type": "string"
             }
           },
           "object": {
             "type": "string",
-            "description": "The type of the object that was deleted.",
+            "description": "The type of the object that was deleted. A price is also named `money-amount`.",
             "default": "money-amount"
           },
           "deleted": {
@@ -30527,14 +31154,14 @@
         "properties": {
           "ids": {
             "type": "array",
-            "description": "The price ids that have been deleted.",
+            "description": "The IDs of the deleted prices.",
             "items": {
               "type": "string"
             }
           },
           "object": {
             "type": "string",
-            "description": "The type of the object that was deleted.",
+            "description": "The type of the object that was deleted. A price is also named `money-amount`.",
             "default": "money-amount"
           },
           "deleted": {
@@ -30558,6 +31185,7 @@
         ],
         "properties": {
           "price_list": {
+            "description": "Price List details.",
             "$ref": "#/components/schemas/PriceList"
           }
         }
@@ -30573,6 +31201,7 @@
         "properties": {
           "price_lists": {
             "type": "array",
+            "description": "An array of price lists details.",
             "items": {
               "$ref": "#/components/schemas/PriceList"
             }
@@ -30583,7 +31212,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of price lists skipped when retrieving the price lists."
           },
           "limit": {
             "type": "integer",
@@ -30615,6 +31244,7 @@
         "properties": {
           "products": {
             "type": "array",
+            "description": "An array of products details.",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
@@ -30625,7 +31255,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of price lists skipped when retrieving the price lists."
           },
           "limit": {
             "type": "integer",
@@ -30671,6 +31301,7 @@
         ],
         "properties": {
           "product_category": {
+            "description": "Product category details.",
             "$ref": "#/components/schemas/ProductCategory"
           }
         }
@@ -30693,6 +31324,7 @@
         "properties": {
           "product_categories": {
             "type": "array",
+            "description": "An array of product category details.",
             "items": {
               "$ref": "#/components/schemas/ProductCategory"
             }
@@ -30703,7 +31335,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product categories skipped when retrieving the product categories."
           },
           "limit": {
             "type": "integer",
@@ -30722,6 +31354,7 @@
         "properties": {
           "product_tags": {
             "type": "array",
+            "description": "An array of product tag details.",
             "items": {
               "$ref": "#/components/schemas/ProductTag"
             }
@@ -30732,7 +31365,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product tags skipped when retrieving the product tags."
           },
           "limit": {
             "type": "integer",
@@ -30751,6 +31384,7 @@
         "properties": {
           "product_types": {
             "type": "array",
+            "description": "An array of product types details.",
             "items": {
               "$ref": "#/components/schemas/ProductType"
             }
@@ -30761,7 +31395,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product types skipped when retrieving the product types."
           },
           "limit": {
             "type": "integer",
@@ -30806,6 +31440,7 @@
             "default": true
           },
           "product": {
+            "description": "Product details.",
             "$ref": "#/components/schemas/PricedProduct"
           }
         }
@@ -30871,6 +31506,7 @@
             "default": true
           },
           "product": {
+            "description": "Product details.",
             "$ref": "#/components/schemas/PricedProduct"
           }
         }
@@ -30902,6 +31538,7 @@
         "properties": {
           "products": {
             "type": "array",
+            "description": "An array of products details.",
             "items": {
               "$ref": "#/components/schemas/PricedProduct"
             }
@@ -30912,7 +31549,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of products skipped when retrieving the products."
           },
           "limit": {
             "type": "integer",
@@ -30927,6 +31564,7 @@
         ],
         "properties": {
           "tags": {
+            "description": "An array of product tags details.",
             "type": "array",
             "items": {
               "type": "object",
@@ -30961,6 +31599,7 @@
         "properties": {
           "types": {
             "type": "array",
+            "description": "An array of product types details.",
             "items": {
               "$ref": "#/components/schemas/ProductType"
             }
@@ -30978,6 +31617,7 @@
         "properties": {
           "variants": {
             "type": "array",
+            "description": "An array of product variants details.",
             "items": {
               "$ref": "#/components/schemas/ProductVariant"
             }
@@ -30988,7 +31628,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product variants skipped when retrieving the product variants."
           },
           "limit": {
             "type": "integer",
@@ -31016,6 +31656,7 @@
         ],
         "properties": {
           "product": {
+            "description": "Product details.",
             "$ref": "#/components/schemas/PricedProduct"
           }
         }
@@ -31030,7 +31671,7 @@
         "properties": {
           "id": {
             "type": "string",
-            "description": "The ID of the deleted PublishableApiKey."
+            "description": "The ID of the deleted publishable API key."
           },
           "object": {
             "type": "string",
@@ -31039,7 +31680,7 @@
           },
           "deleted": {
             "type": "boolean",
-            "description": "Whether the PublishableApiKeys was deleted.",
+            "description": "Whether the publishable API key was deleted.",
             "default": true
           }
         }
@@ -31055,6 +31696,7 @@
         "properties": {
           "publishable_api_keys": {
             "type": "array",
+            "description": "An array of publishable API keys details.",
             "items": {
               "$ref": "#/components/schemas/PublishableApiKey"
             }
@@ -31065,7 +31707,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of publishable API keys skipped when retrieving the publishable API keys."
           },
           "limit": {
             "type": "integer",
@@ -31080,6 +31722,7 @@
         ],
         "properties": {
           "sales_channels": {
+            "description": "An array of sales channels details.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/SalesChannel"
@@ -31094,6 +31737,7 @@
         ],
         "properties": {
           "publishable_api_key": {
+            "description": "Publishable API key details.",
             "$ref": "#/components/schemas/PublishableApiKey"
           }
         }
@@ -31105,6 +31749,7 @@
         ],
         "properties": {
           "refund": {
+            "description": "Refund details",
             "$ref": "#/components/schemas/Refund"
           }
         }
@@ -31156,6 +31801,7 @@
         "properties": {
           "regions": {
             "type": "array",
+            "description": "An array of regions details.",
             "items": {
               "$ref": "#/components/schemas/Region"
             }
@@ -31166,7 +31812,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of regions skipped when retrieving the regions."
           },
           "limit": {
             "type": "integer",
@@ -31193,6 +31839,7 @@
         ],
         "properties": {
           "region": {
+            "description": "Region details.",
             "$ref": "#/components/schemas/Region"
           }
         }
@@ -31232,6 +31879,7 @@
         "properties": {
           "reservations": {
             "type": "array",
+            "description": "An array of reservations details.",
             "items": {
               "$ref": "#/components/schemas/ExtendedReservationItem"
             }
@@ -31242,7 +31890,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of reservations skipped when retrieving the reservations."
           },
           "limit": {
             "type": "integer",
@@ -31257,6 +31905,7 @@
         ],
         "properties": {
           "reservation": {
+            "description": "Reservation details.",
             "$ref": "#/components/schemas/ReservationItemDTO"
           }
         }
@@ -31269,16 +31918,16 @@
         ],
         "properties": {
           "email": {
-            "description": "The Users email.",
+            "description": "The User's email.",
             "type": "string",
             "format": "email"
           },
           "token": {
-            "description": "The token generated from the 'password-token' endpoint.",
+            "description": "The password-reset token generated when the password reset was requested.",
             "type": "string"
           },
           "password": {
-            "description": "The Users new password.",
+            "description": "The User's new password.",
             "type": "string",
             "format": "password"
           }
@@ -31291,7 +31940,7 @@
         ],
         "properties": {
           "email": {
-            "description": "The Users email.",
+            "description": "The User's email.",
             "type": "string",
             "format": "email"
           }
@@ -31417,6 +32066,7 @@
         ],
         "properties": {
           "order": {
+            "description": "Order details.",
             "$ref": "#/components/schemas/Order"
           }
         }
@@ -31439,6 +32089,7 @@
         "properties": {
           "returns": {
             "type": "array",
+            "description": "An array of returns details.",
             "items": {
               "$ref": "#/components/schemas/Return"
             }
@@ -31449,7 +32100,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of returns skipped when retrieving the returns."
           },
           "limit": {
             "type": "integer",
@@ -31470,6 +32121,7 @@
         ],
         "properties": {
           "return": {
+            "description": "Return details.",
             "$ref": "#/components/schemas/Return"
           }
         }
@@ -31533,6 +32185,7 @@
         "properties": {
           "sales_channels": {
             "type": "array",
+            "description": "An array of sales channels details.",
             "items": {
               "$ref": "#/components/schemas/SalesChannel"
             }
@@ -31543,7 +32196,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of items skipped before the returned results"
           },
           "limit": {
             "type": "integer",
@@ -31558,6 +32211,7 @@
         ],
         "properties": {
           "sales_channel": {
+            "description": "Sales Channel's details.",
             "$ref": "#/components/schemas/SalesChannel"
           }
         }
@@ -31609,6 +32263,7 @@
         "properties": {
           "shipping_options": {
             "type": "array",
+            "description": "An array of shipping options details.",
             "items": {
               "$ref": "#/components/schemas/ShippingOption"
             }
@@ -31619,7 +32274,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of shipping options skipped when retrieving the shipping options."
           },
           "limit": {
             "type": "integer",
@@ -31646,6 +32301,7 @@
         ],
         "properties": {
           "shipping_option": {
+            "description": "Shipping option details.",
             "$ref": "#/components/schemas/ShippingOption"
           }
         }
@@ -31658,6 +32314,7 @@
         "properties": {
           "shipping_profiles": {
             "type": "array",
+            "description": "An array of shipping profiles details.",
             "items": {
               "$ref": "#/components/schemas/ShippingProfile"
             }
@@ -31678,6 +32335,7 @@
         ],
         "properties": {
           "shipping_profile": {
+            "description": "Shipping profile details.",
             "$ref": "#/components/schemas/ShippingProfile"
           }
         }
@@ -31727,7 +32385,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of stock locations skipped when retrieving the stock locations."
           },
           "limit": {
             "type": "integer",
@@ -31742,6 +32400,7 @@
         ],
         "properties": {
           "stock_location": {
+            "description": "Stock location details.",
             "$ref": "#/components/schemas/StockLocationExpandedDTO"
           }
         }
@@ -31753,6 +32412,7 @@
         ],
         "properties": {
           "store": {
+            "description": "Store details.",
             "$ref": "#/components/schemas/Store"
           }
         }
@@ -31768,6 +32428,7 @@
         "properties": {
           "swaps": {
             "type": "array",
+            "description": "An array of swaps details.",
             "items": {
               "$ref": "#/components/schemas/Swap"
             }
@@ -31778,7 +32439,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of swaps skipped when retrieving the swaps."
           },
           "limit": {
             "type": "integer",
@@ -31814,6 +32475,7 @@
         ],
         "properties": {
           "swap": {
+            "description": "Swap details.",
             "$ref": "#/components/schemas/Swap"
           }
         }
@@ -31826,6 +32488,7 @@
         "properties": {
           "tax_providers": {
             "type": "array",
+            "description": "An array of tax providers details.",
             "items": {
               "$ref": "#/components/schemas/TaxProvider"
             }
@@ -31867,6 +32530,7 @@
         "properties": {
           "tax_rates": {
             "type": "array",
+            "description": "An array of tax rate details.",
             "items": {
               "$ref": "#/components/schemas/TaxRate"
             }
@@ -31877,7 +32541,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of tax rates to skip when retrieving the tax rates."
           },
           "limit": {
             "type": "integer",
@@ -31892,6 +32556,7 @@
         ],
         "properties": {
           "tax_rate": {
+            "description": "Tax rate details.",
             "$ref": "#/components/schemas/TaxRate"
           }
         }
@@ -31900,12 +32565,16 @@
         "type": "object",
         "properties": {
           "description": {
-            "description": "An optional description to create or update the payment collection.",
+            "description": "A description to create or update the payment collection.",
             "type": "string"
           },
           "metadata": {
-            "description": "An optional set of key-value pairs to hold additional information.",
-            "type": "object"
+            "description": "A set of key-value pairs to hold additional information.",
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -31913,15 +32582,15 @@
         "type": "object",
         "properties": {
           "first_name": {
-            "description": "The name of the User.",
+            "description": "The first name of the User.",
             "type": "string"
           },
           "last_name": {
-            "description": "The name of the User.",
+            "description": "The last name of the User.",
             "type": "string"
           },
           "role": {
-            "description": "Userrole assigned to the user.",
+            "description": "The role assigned to the user. These roles don't provide any different privileges.",
             "type": "string",
             "enum": [
               "admin",
@@ -31930,12 +32599,16 @@
             ]
           },
           "api_token": {
-            "description": "The api token of the User.",
+            "description": "The API token of the User.",
             "type": "string"
           },
           "metadata": {
             "description": "An optional set of key-value pairs with additional information.",
-            "type": "object"
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -31959,6 +32632,7 @@
         "properties": {
           "uploads": {
             "type": "array",
+            "description": "Uploaded files details.",
             "items": {
               "type": "object",
               "required": [
@@ -31982,6 +32656,7 @@
         ],
         "properties": {
           "user": {
+            "description": "User details.",
             "$ref": "#/components/schemas/User"
           }
         }
@@ -31994,6 +32669,7 @@
         "properties": {
           "users": {
             "type": "array",
+            "description": "An array of users details.",
             "items": {
               "$ref": "#/components/schemas/User"
             }
@@ -32022,6 +32698,7 @@
         "properties": {
           "variants": {
             "type": "array",
+            "description": "An array of product variant details.",
             "items": {
               "$ref": "#/components/schemas/PricedVariant"
             }
@@ -32032,7 +32709,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product variants skipped when retrieving the product variants."
           },
           "limit": {
             "type": "integer",
@@ -32055,13 +32732,14 @@
         ],
         "properties": {
           "variant": {
+            "description": "Product variant's details.",
             "$ref": "#/components/schemas/PricedVariant"
           }
         }
       },
       "BatchJob": {
         "title": "Batch Job",
-        "description": "A Batch Job.",
+        "description": "A Batch Job indicates an asynchronus task stored in the Medusa backend. Its status determines whether it has been executed or not.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -32116,7 +32794,8 @@
             "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"
           },
           "created_by_user": {
-            "description": "A user object. Available if the relation `created_by_user` is expanded.",
+            "description": "The details of the user that created the batch job.",
+            "x-expandable": "created_by_user",
             "nullable": true,
             "$ref": "#/components/schemas/User"
           },
@@ -32291,7 +32970,7 @@
       },
       "Cart": {
         "title": "Cart",
-        "description": "Represents a user cart",
+        "description": "A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.",
         "type": "object",
         "required": [
           "billing_address_id",
@@ -32331,7 +33010,8 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "billing_address": {
-            "description": "Available if the relation `billing_address` is expanded.",
+            "description": "The details of the billing address associated with the cart.",
+            "x-expandable": "billing_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
@@ -32342,13 +33022,15 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "shipping_address": {
-            "description": "Available if the relation `shipping_address` is expanded.",
+            "description": "The details of the shipping address associated with the cart.",
+            "x-expandable": "shipping_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "items": {
-            "description": "Available if the relation `items` is expanded.",
+            "description": "The line items added to the cart.",
             "type": "array",
+            "x-expandable": "items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
@@ -32359,20 +33041,23 @@
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region associated with the cart.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "discounts": {
-            "description": "Available if the relation `discounts` is expanded.",
+            "description": "An array of details of all discounts applied to the cart.",
             "type": "array",
+            "x-expandable": "discounts",
             "items": {
               "$ref": "#/components/schemas/Discount"
             }
           },
           "gift_cards": {
-            "description": "Available if the relation `gift_cards` is expanded.",
+            "description": "An array of details of all gift cards applied to the cart.",
             "type": "array",
+            "x-expandable": "gift_cards",
             "items": {
               "$ref": "#/components/schemas/GiftCard"
             }
@@ -32384,18 +33069,21 @@
             "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "customer": {
-            "description": "A customer object. Available if the relation `customer` is expanded.",
+            "description": "The details of the customer the cart belongs to.",
+            "x-expandable": "customer",
             "nullable": true,
             "$ref": "#/components/schemas/Customer"
           },
           "payment_session": {
-            "description": "The selected payment session in the cart.",
+            "description": "The details of the selected payment session in the cart.",
+            "x-expandable": "payment_session",
             "nullable": true,
             "$ref": "#/components/schemas/PaymentSession"
           },
           "payment_sessions": {
-            "description": "The payment sessions created on the cart.",
+            "description": "The details of all payment sessions created on the cart.",
             "type": "array",
+            "x-expandable": "payment_sessions",
             "items": {
               "$ref": "#/components/schemas/PaymentSession"
             }
@@ -32407,13 +33095,15 @@
             "example": "pay_01G8ZCC5W42ZNY842124G7P5R9"
           },
           "payment": {
-            "description": "Available if the relation `payment` is expanded.",
+            "description": "The details of the payment associated with the cart.",
             "nullable": true,
+            "x-expandable": "payment",
             "$ref": "#/components/schemas/Payment"
           },
           "shipping_methods": {
-            "description": "The shipping methods added to the cart.",
+            "description": "The details of the shipping methods added to the cart.",
             "type": "array",
+            "x-expandable": "shipping_methods",
             "items": {
               "$ref": "#/components/schemas/ShippingMethod"
             }
@@ -32467,8 +33157,9 @@
             "example": null
           },
           "sales_channel": {
-            "description": "A sales channel object. Available if the relation `sales_channel` is expanded.",
+            "description": "The details of the sales channel associated with the cart.",
             "nullable": true,
+            "x-expandable": "sales_channel",
             "$ref": "#/components/schemas/SalesChannel"
           },
           "created_at": {
@@ -32493,6 +33184,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           },
           "shipping_total": {
@@ -32559,7 +33254,7 @@
       },
       "ClaimImage": {
         "title": "Claim Image",
-        "description": "Represents photo documentation of a claim.",
+        "description": "The details of an image attached to a claim.",
         "type": "object",
         "required": [
           "claim_item_id",
@@ -32581,8 +33276,9 @@
             "type": "string"
           },
           "claim_item": {
-            "description": "A claim item object. Available if the relation `claim_item` is expanded.",
+            "description": "The details of the claim item this image is associated with.",
             "nullable": true,
+            "x-expandable": "claim_item",
             "$ref": "#/components/schemas/ClaimItem"
           },
           "url": {
@@ -32612,13 +33308,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ClaimItem": {
         "title": "Claim Item",
-        "description": "Represents a claimed item along with information about the reasons for the claim.",
+        "description": "A claim item is an item created as part of a claim. It references an item in the order that should be exchanged or refunded.",
         "type": "object",
         "required": [
           "claim_order_id",
@@ -32640,8 +33340,9 @@
             "example": "citm_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "images": {
-            "description": "Available if the relation `images` is expanded.",
+            "description": "The claim images that are attached to the claim item.",
             "type": "array",
+            "x-expandable": "images",
             "items": {
               "$ref": "#/components/schemas/ClaimImage"
             }
@@ -32651,7 +33352,8 @@
             "type": "string"
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim this item belongs to.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
@@ -32661,7 +33363,8 @@
             "example": "item_01G8ZM25TN49YV9EQBE2NC27KC"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item in the original order that this claim item refers to.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -32671,7 +33374,8 @@
             "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"
           },
           "variant": {
-            "description": "A variant object. Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant to potentially replace the item in the original order.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
@@ -32697,8 +33401,9 @@
             "example": 1
           },
           "tags": {
-            "description": "User defined tags for easy filtering and grouping. Available if the relation 'tags' is expanded.",
+            "description": "User defined tags for easy filtering and grouping.",
             "type": "array",
+            "x-expandable": "tags",
             "items": {
               "$ref": "#/components/schemas/ClaimTag"
             }
@@ -32725,13 +33430,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ClaimOrder": {
-        "title": "Claim Order",
-        "description": "Claim Orders represent a group of faulty or missing items. Each claim order consists of a subset of items associated with an original order, and can contain additional information about fulfillments and returns.",
+        "title": "Claim",
+        "description": "A Claim represents a group of faulty or missing items. It consists of claim items that refer to items in the original order that should be replaced or refunded. It also includes details related to shipping and fulfillment.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -32790,15 +33499,17 @@
             "default": "not_fulfilled"
           },
           "claim_items": {
-            "description": "The items that have been claimed",
+            "description": "The details of the items that should be replaced or refunded.",
             "type": "array",
+            "x-expandable": "claim_items",
             "items": {
               "$ref": "#/components/schemas/ClaimItem"
             }
           },
           "additional_items": {
-            "description": "Refers to the new items to be shipped when the claim order has the type `replace`",
+            "description": "The details of the new items to be shipped when the claim's type is `replace`",
             "type": "array",
+            "x-expandable": "additional_items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
@@ -32809,12 +33520,14 @@
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that this claim was created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "return_order": {
-            "description": "A return object. Holds information about the return if the claim is to be returned. Available if the relation 'return_order' is expanded",
+            "description": "The details of the return associated with the claim if the claim's type is `replace`.",
+            "x-expandable": "return_order",
             "nullable": true,
             "$ref": "#/components/schemas/Return"
           },
@@ -32825,13 +33538,15 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "shipping_address": {
-            "description": "Available if the relation `shipping_address` is expanded.",
+            "description": "The details of the address that new items should be shipped to.",
+            "x-expandable": "shipping_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "shipping_methods": {
-            "description": "The shipping methods that the claim order will be shipped with.",
+            "description": "The details of the shipping methods that the claim order will be shipped with.",
             "type": "array",
+            "x-expandable": "shipping_methods",
             "items": {
               "$ref": "#/components/schemas/ShippingMethod"
             }
@@ -32839,6 +33554,7 @@
           "fulfillments": {
             "description": "The fulfillments of the new items to be shipped",
             "type": "array",
+            "x-expandable": "fulfillments",
             "items": {
               "$ref": "#/components/schemas/Fulfillment"
             }
@@ -32877,6 +33593,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           },
           "no_notification": {
@@ -32941,6 +33661,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -33008,7 +33732,8 @@
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region the country is associated with.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           }
@@ -33086,15 +33811,16 @@
             "example": "US Dollar"
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Does the currency prices include tax",
+            "description": "Whether the currency prices include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           }
         }
       },
       "CustomShippingOption": {
         "title": "Custom Shipping Option",
-        "description": "Custom Shipping Options are 'overriden' Shipping Options. Store managers can attach a Custom Shipping Option to a cart in order to set a custom price for a particular Shipping Option",
+        "description": "Custom Shipping Options are overriden Shipping Options. Admins can attach a Custom Shipping Option to a cart in order to set a custom price for a particular Shipping Option.",
         "type": "object",
         "required": [
           "cart_id",
@@ -33123,7 +33849,8 @@
             "example": "so_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "shipping_option": {
-            "description": "A shipping option object. Available if the relation `shipping_option` is expanded.",
+            "description": "The details of the overriden shipping options.",
+            "x-expandable": "shipping_option",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingOption"
           },
@@ -33134,7 +33861,8 @@
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart this shipping option belongs to.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
@@ -33160,13 +33888,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "Customer": {
         "title": "Customer",
-        "description": "Represents a customer",
+        "description": "A customer can make purchases in your store and manage their profile.",
         "type": "object",
         "required": [
           "billing_address_id",
@@ -33211,13 +33943,15 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "billing_address": {
-            "description": "Available if the relation `billing_address` is expanded.",
+            "description": "The details of the billing address associated with the customer.",
+            "x-expandable": "billing_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "shipping_addresses": {
-            "description": "Available if the relation `shipping_addresses` is expanded.",
+            "description": "The details of the shipping addresses associated with the customer.",
             "type": "array",
+            "x-expandable": "shipping_addresses",
             "items": {
               "$ref": "#/components/schemas/Address"
             }
@@ -33234,15 +33968,17 @@
             "default": false
           },
           "orders": {
-            "description": "Available if the relation `orders` is expanded.",
+            "description": "The details of the orders this customer placed.",
             "type": "array",
+            "x-expandable": "orders",
             "items": {
               "$ref": "#/components/schemas/Order"
             }
           },
           "groups": {
-            "description": "The customer groups the customer belongs to. Available if the relation `groups` is expanded.",
+            "description": "The customer groups the customer belongs to.",
             "type": "array",
+            "x-expandable": "groups",
             "items": {
               "$ref": "#/components/schemas/CustomerGroup"
             }
@@ -33269,13 +34005,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "CustomerGroup": {
         "title": "Customer Group",
-        "description": "Represents a customer group",
+        "description": "A customer group that can be used to organize customers into groups of similar traits.",
         "type": "object",
         "required": [
           "created_at",
@@ -33297,15 +34037,17 @@
             "example": "VIP"
           },
           "customers": {
-            "description": "The customers that belong to the customer group. Available if the relation `customers` is expanded.",
+            "description": "The details of the customers that belong to the customer group.",
             "type": "array",
+            "x-expandable": "customers",
             "items": {
               "$ref": "#/components/schemas/Customer"
             }
           },
           "price_lists": {
-            "description": "The price lists that are associated with the customer group. Available if the relation `price_lists` is expanded.",
+            "description": "The price lists that are associated with the customer group.",
             "type": "array",
+            "x-expandable": "price_lists",
             "items": {
               "$ref": "#/components/schemas/PriceList"
             }
@@ -33332,6 +34074,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -33351,12 +34097,14 @@
             "properties": {
               "location_levels": {
                 "type": "array",
+                "description": "An array of location level details",
                 "items": {
                   "$ref": "#/components/schemas/InventoryLevelDTO"
                 }
               },
               "variants": {
                 "type": "array",
+                "description": "An array of product variant details",
                 "items": {
                   "$ref": "#/components/schemas/ProductVariant"
                 }
@@ -33375,7 +34123,7 @@
       },
       "Discount": {
         "title": "Discount",
-        "description": "Represents a discount that can be applied to a cart for promotional purposes.",
+        "description": "A discount can be applied to a cart for promotional purposes.",
         "type": "object",
         "required": [
           "code",
@@ -33411,13 +34159,14 @@
             "example": false
           },
           "rule_id": {
-            "description": "The Discount Rule that governs the behaviour of the Discount",
+            "description": "The ID of the discount rule that defines how the discount will be applied to a cart.",
             "nullable": true,
             "type": "string",
             "example": "dru_01F0YESMVK96HVX7N419E3CJ7C"
           },
           "rule": {
-            "description": "Available if the relation `rule` is expanded.",
+            "description": "The details of the discount rule that defines how the discount will be applied to a cart..",
+            "x-expandable": "rule",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountRule"
           },
@@ -33433,7 +34182,8 @@
             "example": "disc_01G8ZH853YPY9B94857DY91YGW"
           },
           "parent_discount": {
-            "description": "Available if the relation `parent_discount` is expanded.",
+            "description": "The details of the parent discount that this discount was created from.",
+            "x-expandable": "parent_discount",
             "nullable": true,
             "$ref": "#/components/schemas/Discount"
           },
@@ -33455,8 +34205,9 @@
             "example": "P3Y6M4DT12H30M5S"
           },
           "regions": {
-            "description": "The Regions in which the Discount can be used. Available if the relation `regions` is expanded.",
+            "description": "The details of the regions in which the Discount can be used.",
             "type": "array",
+            "x-expandable": "regions",
             "items": {
               "$ref": "#/components/schemas/Region"
             }
@@ -33495,6 +34246,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -33520,7 +34275,7 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "type": {
-            "description": "The type of the Condition",
+            "description": "The type of the condition. The type affects the available resources associated with the condition. For example, if the type is `products`, that means the `products` relation will hold the products associated with this condition and other relations will be empty.",
             "type": "string",
             "enum": [
               "products",
@@ -33531,7 +34286,7 @@
             ]
           },
           "operator": {
-            "description": "The operator of the Condition",
+            "description": "The operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that discountable resources are everything but the specified resources.",
             "type": "string",
             "enum": [
               "in",
@@ -33544,41 +34299,47 @@
             "example": "dru_01F0YESMVK96HVX7N419E3CJ7C"
           },
           "discount_rule": {
-            "description": "Available if the relation `discount_rule` is expanded.",
+            "description": "The details of the discount rule associated with the condition.",
+            "x-expandable": "discount_rule",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountRule"
           },
           "products": {
-            "description": "products associated with this condition if type = products. Available if the relation `products` is expanded.",
+            "description": "products associated with this condition if `type` is `products`.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
           },
           "product_types": {
-            "description": "Product types associated with this condition if type = product_types. Available if the relation `product_types` is expanded.",
+            "description": "Product types associated with this condition if `type` is `product_types`.",
             "type": "array",
+            "x-expandable": "product_types",
             "items": {
               "$ref": "#/components/schemas/ProductType"
             }
           },
           "product_tags": {
-            "description": "Product tags associated with this condition if type = product_tags. Available if the relation `product_tags` is expanded.",
+            "description": "Product tags associated with this condition if `type` is `product_tags`.",
             "type": "array",
+            "x-expandable": "product_tags",
             "items": {
               "$ref": "#/components/schemas/ProductTag"
             }
           },
           "product_collections": {
-            "description": "Product collections associated with this condition if type = product_collections. Available if the relation `product_collections` is expanded.",
+            "description": "Product collections associated with this condition if `type` is `product_collections`.",
             "type": "array",
+            "x-expandable": "product_collections",
             "items": {
               "$ref": "#/components/schemas/ProductCollection"
             }
           },
           "customer_groups": {
-            "description": "Customer groups associated with this condition if type = customer_groups. Available if the relation `customer_groups` is expanded.",
+            "description": "Customer groups associated with this condition if `type` is `customer_groups`.",
             "type": "array",
+            "x-expandable": "customer_groups",
             "items": {
               "$ref": "#/components/schemas/CustomerGroup"
             }
@@ -33605,6 +34366,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -33657,13 +34422,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountConditionProduct": {
         "title": "Product Discount Condition",
-        "description": "Associates a discount condition with a product",
+        "description": "This represents the association between a discount condition and a product",
         "type": "object",
         "required": [
           "condition_id",
@@ -33684,12 +34453,14 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product": {
-            "description": "Available if the relation `product` is expanded.",
+            "description": "The details of the product.",
+            "x-expandable": "product",
             "nullable": true,
             "$ref": "#/components/schemas/Product"
           },
           "discount_condition": {
-            "description": "Available if the relation `discount_condition` is expanded.",
+            "description": "The details of the discount condition.",
+            "x-expandable": "discount_condition",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountCondition"
           },
@@ -33709,13 +34480,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountConditionProductCollection": {
         "title": "Product Collection Discount Condition",
-        "description": "Associates a discount condition with a product collection",
+        "description": "This represents the association between a discount condition and a product collection",
         "type": "object",
         "required": [
           "condition_id",
@@ -33736,12 +34511,14 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product_collection": {
-            "description": "Available if the relation `product_collection` is expanded.",
+            "description": "The details of the product collection.",
+            "x-expandable": "product_collection",
             "nullable": true,
             "$ref": "#/components/schemas/ProductCollection"
           },
           "discount_condition": {
-            "description": "Available if the relation `discount_condition` is expanded.",
+            "description": "The details of the discount condition.",
+            "x-expandable": "discount_condition",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountCondition"
           },
@@ -33761,13 +34538,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountConditionProductTag": {
         "title": "Product Tag Discount Condition",
-        "description": "Associates a discount condition with a product tag",
+        "description": "This represents the association between a discount condition and a product tag",
         "type": "object",
         "required": [
           "condition_id",
@@ -33788,12 +34569,14 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product_tag": {
-            "description": "Available if the relation `product_tag` is expanded.",
+            "description": "The details of the product tag.",
+            "x-expandable": "product_tag",
             "nullable": true,
             "$ref": "#/components/schemas/ProductTag"
           },
           "discount_condition": {
-            "description": "Available if the relation `discount_condition` is expanded.",
+            "description": "The details of the discount condition.",
+            "x-expandable": "discount_condition",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountCondition"
           },
@@ -33813,13 +34596,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountConditionProductType": {
         "title": "Product Type Discount Condition",
-        "description": "Associates a discount condition with a product type",
+        "description": "This represents the association between a discount condition and a product type",
         "type": "object",
         "required": [
           "condition_id",
@@ -33840,12 +34627,14 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product_type": {
-            "description": "Available if the relation `product_type` is expanded.",
+            "description": "The details of the product type.",
+            "x-expandable": "product_type",
             "nullable": true,
             "$ref": "#/components/schemas/ProductType"
           },
           "discount_condition": {
-            "description": "Available if the relation `discount_condition` is expanded.",
+            "description": "The details of the discount condition.",
+            "x-expandable": "discount_condition",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountCondition"
           },
@@ -33865,13 +34654,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountRule": {
         "title": "Discount Rule",
-        "description": "Holds the rules that governs how a Discount is calculated when applied to a Cart.",
+        "description": "A discount rule defines how a Discount is calculated when applied to a Cart.",
         "type": "object",
         "required": [
           "allocation",
@@ -33922,8 +34715,9 @@
             "example": "total"
           },
           "conditions": {
-            "description": "A set of conditions that can be used to limit when  the discount can be used. Available if the relation `conditions` is expanded.",
+            "description": "The details of the discount conditions associated with the rule. They can be used to limit when the discount can be used.",
             "type": "array",
+            "x-expandable": "conditions",
             "items": {
               "$ref": "#/components/schemas/DiscountCondition"
             }
@@ -33950,13 +34744,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DraftOrder": {
         "title": "DraftOrder",
-        "description": "Represents a draft order",
+        "description": "A draft order is created by an admin without direct involvement of the customer. Once its payment is marked as captured, it is transformed into an order.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -33979,7 +34777,7 @@
             "example": "dorder_01G8TJFKBG38YYFQ035MSVG03C"
           },
           "status": {
-            "description": "The status of the draft order",
+            "description": "The status of the draft order. It's changed to `completed` when it's transformed to an order.",
             "type": "string",
             "enum": [
               "open",
@@ -33999,18 +34797,20 @@
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart associated with the draft order.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "order_id": {
-            "description": "The ID of the order associated with the draft order.",
+            "description": "The ID of the order created from the draft order when its payment is captured.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order created from the draft order when its payment is captured.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
@@ -34057,6 +34857,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -34089,11 +34893,11 @@
             "type": "object",
             "properties": {
               "line_item": {
-                "description": "optional line item",
+                "description": "The line item associated with the reservation.",
                 "$ref": "#/components/schemas/LineItem"
               },
               "inventory_item": {
-                "description": "inventory item from inventory module",
+                "description": "The inventory item associated with the reservation.",
                 "$ref": "#/components/schemas/InventoryItemDTO"
               }
             }
@@ -34152,7 +34956,7 @@
       },
       "Fulfillment": {
         "title": "Fulfillment",
-        "description": "Fulfillments are created once store operators can prepare the purchased goods. Fulfillments will eventually be shipped and hold information about how to track shipments. Fulfillments are created through a provider, which is typically an external shipping aggregator, shipping partner og 3PL, most plugins will have asynchronous communications with these providers through webhooks in order to automatically update and synchronize the state of Fulfillments.",
+        "description": "A Fulfillment is created once an admin can prepare the purchased goods. Fulfillments will eventually be shipped and hold information about how to track shipments. Fulfillments are created through a fulfillment provider, which typically integrates a third-party shipping service. Fulfillments can be associated with orders, claims, swaps, and returns.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -34178,64 +34982,70 @@
             "example": "ful_01G8ZRTMQCA76TXNAT81KPJZRF"
           },
           "claim_order_id": {
-            "description": "The id of the Claim that the Fulfillment belongs to.",
+            "description": "The ID of the Claim that the Fulfillment belongs to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim that the fulfillment may belong to.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
           "swap_id": {
-            "description": "The id of the Swap that the Fulfillment belongs to.",
+            "description": "The ID of the Swap that the Fulfillment belongs to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that the fulfillment may belong to.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "order_id": {
-            "description": "The id of the Order that the Fulfillment belongs to.",
+            "description": "The ID of the Order that the Fulfillment belongs to.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the fulfillment may belong to.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "provider_id": {
-            "description": "The id of the Fulfillment Provider responsible for handling the fulfillment",
+            "description": "The ID of the Fulfillment Provider responsible for handling the fulfillment.",
             "type": "string",
             "example": "manual"
           },
           "provider": {
-            "description": "Available if the relation `provider` is expanded.",
+            "description": "The details of the fulfillment provider responsible for handling the fulfillment.",
+            "x-expandable": "provider",
             "nullable": true,
             "$ref": "#/components/schemas/FulfillmentProvider"
           },
           "location_id": {
-            "description": "The id of the stock location the fulfillment will be shipped from",
+            "description": "The ID of the stock location the fulfillment will be shipped from",
             "nullable": true,
             "type": "string",
             "example": "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "items": {
-            "description": "The Fulfillment Items in the Fulfillment - these hold information about how many of each Line Item has been fulfilled. Available if the relation `items` is expanded.",
+            "description": "The Fulfillment Items in the Fulfillment. These hold information about how many of each Line Item has been fulfilled.",
             "type": "array",
+            "x-expandable": "items",
             "items": {
               "$ref": "#/components/schemas/FulfillmentItem"
             }
           },
           "tracking_links": {
-            "description": "The Tracking Links that can be used to track the status of the Fulfillment, these will usually be provided by the Fulfillment Provider. Available if the relation `tracking_links` is expanded.",
+            "description": "The Tracking Links that can be used to track the status of the Fulfillment. These will usually be provided by the Fulfillment Provider.",
             "type": "array",
+            "x-expandable": "tracking_links",
             "items": {
               "$ref": "#/components/schemas/TrackingLink"
             }
@@ -34296,13 +35106,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "FulfillmentItem": {
         "title": "Fulfillment Item",
-        "description": "Correlates a Line Item with a Fulfillment, keeping track of the quantity of the Line Item.",
+        "description": "This represents the association between a Line Item and a Fulfillment.",
         "type": "object",
         "required": [
           "fulfillment_id",
@@ -34311,22 +35125,24 @@
         ],
         "properties": {
           "fulfillment_id": {
-            "description": "The id of the Fulfillment that the Fulfillment Item belongs to.",
+            "description": "The ID of the Fulfillment that the Fulfillment Item belongs to.",
             "type": "string",
             "example": "ful_01G8ZRTMQCA76TXNAT81KPJZRF"
           },
           "item_id": {
-            "description": "The id of the Line Item that the Fulfillment Item references.",
+            "description": "The ID of the Line Item that the Fulfillment Item references.",
             "type": "string",
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "fulfillment": {
-            "description": "A fulfillment object. Available if the relation `fulfillment` is expanded.",
+            "description": "The details of the fulfillment.",
+            "x-expandable": "fulfillment",
             "nullable": true,
             "$ref": "#/components/schemas/Fulfillment"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -34339,7 +35155,7 @@
       },
       "FulfillmentProvider": {
         "title": "Fulfillment Provider",
-        "description": "Represents a fulfillment provider plugin and holds its installation status.",
+        "description": "A fulfillment provider represents a fulfillment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the fulfillment service's installation status.",
         "type": "object",
         "required": [
           "id",
@@ -34347,12 +35163,12 @@
         ],
         "properties": {
           "id": {
-            "description": "The id of the fulfillment provider as given by the plugin.",
+            "description": "The ID of the fulfillment provider as given by the fulfillment service.",
             "type": "string",
             "example": "manual"
           },
           "is_installed": {
-            "description": "Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`.",
+            "description": "Whether the fulfillment service is installed in the current version. If a fulfillment service is no longer installed, the `is_installed` attribute is set to `false`.",
             "type": "boolean",
             "default": true
           }
@@ -34399,23 +35215,25 @@
             "example": 10
           },
           "region_id": {
-            "description": "The id of the Region in which the Gift Card is available.",
+            "description": "The ID of the region this gift card is available in.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region this gift card is available in.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "order_id": {
-            "description": "The id of the Order that the Gift Card was purchased in.",
+            "description": "The ID of the order that the gift card was purchased in.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the gift card was purchased in.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
@@ -34458,13 +35276,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "GiftCardTransaction": {
         "title": "Gift Card Transaction",
-        "description": "Gift Card Transactions are created once a Customer uses a Gift Card to pay for their Order",
+        "description": "Gift Card Transactions are created once a Customer uses a Gift Card to pay for their Order.",
         "type": "object",
         "required": [
           "amount",
@@ -34487,17 +35309,19 @@
             "example": "gift_01G8XKBPBQY2R7RBET4J7E0XQZ"
           },
           "gift_card": {
-            "description": "A gift card object. Available if the relation `gift_card` is expanded.",
+            "description": "The details of the gift card associated used in this transaction.",
+            "x-expandable": "gift_card",
             "nullable": true,
             "$ref": "#/components/schemas/GiftCard"
           },
           "order_id": {
-            "description": "The ID of the Order that the Gift Card was used to pay for.",
+            "description": "The ID of the order that the gift card was used for payment.",
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the gift card was used for payment.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
@@ -34609,7 +35433,7 @@
       },
       "Image": {
         "title": "Image",
-        "description": "Images holds a reference to a URL at which the image file can be found.",
+        "description": "An Image is used to store details about uploaded images. Images are uploaded by the File Service, and the URL is provided by the File Service.",
         "type": "object",
         "required": [
           "created_at",
@@ -34652,6 +35476,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -34790,7 +35618,7 @@
       },
       "Invite": {
         "title": "Invite",
-        "description": "Represents an invite",
+        "description": "An invite is created when an admin user invites a new user to join the store's team. Once the invite is accepted, it's deleted.",
         "type": "object",
         "required": [
           "accepted",
@@ -34816,7 +35644,7 @@
             "format": "email"
           },
           "role": {
-            "description": "The user's role.",
+            "description": "The user's role. These roles don't change the privileges of the user.",
             "nullable": true,
             "type": "string",
             "enum": [
@@ -34862,13 +35690,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "LineItem": {
         "title": "Line Item",
-        "description": "Line Items represent purchasable units that can be added to a Cart for checkout. When Line Items are purchased they will get copied to the resulting order and can eventually be referenced in Fulfillments and Returns. Line Items may also be created when processing Swaps and Claims.",
+        "description": "Line Items are created when a product is added to a Cart. When Line Items are purchased they will get copied to the resulting order, swap, or claim, and can eventually be referenced in Fulfillments and Returns. Line items may also be used for order edits.",
         "type": "object",
         "required": [
           "allow_discounts",
@@ -34903,80 +35735,87 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "cart_id": {
-            "description": "The ID of the Cart that the Line Item belongs to.",
+            "description": "The ID of the cart that the line item may belongs to.",
             "nullable": true,
             "type": "string",
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the line item may belongs to.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "order_id": {
-            "description": "The ID of the Order that the Line Item belongs to.",
+            "description": "The ID of the order that the line item may belongs to.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the line item may belongs to.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "swap_id": {
-            "description": "The id of the Swap that the Line Item belongs to.",
+            "description": "The ID of the swap that the line item may belong to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that the line item may belong to.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "claim_order_id": {
-            "description": "The id of the Claim that the Line Item belongs to.",
+            "description": "The ID of the claim that the line item may belong to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim that the line item may belong to.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
           "tax_lines": {
-            "description": "Available if the relation `tax_lines` is expanded.",
+            "description": "The details of the item's tax lines.",
+            "x-expandable": "tax_lines",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/LineItemTaxLine"
             }
           },
           "adjustments": {
-            "description": "Available if the relation `adjustments` is expanded.",
+            "description": "The details of the item's adjustments, which are available when a discount is applied on the item.",
+            "x-expandable": "adjustments",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/LineItemAdjustment"
             }
           },
           "original_item_id": {
-            "description": "The id of the original line item",
+            "description": "The ID of the original line item. This is useful if the line item belongs to a resource that references an order, such as a return or an order edit.",
             "nullable": true,
             "type": "string"
           },
           "order_edit_id": {
-            "description": "The ID of the order edit to which a cloned item belongs",
+            "description": "The ID of the order edit that the item may belong to.",
             "nullable": true,
             "type": "string"
           },
           "order_edit": {
-            "description": "The order edit joined. Available if the relation `order_edit` is expanded.",
+            "description": "The details of the order edit.",
+            "x-expandable": "order_edit",
             "nullable": true,
             "$ref": "#/components/schemas/OrderEdit"
           },
           "title": {
-            "description": "The title of the Line Item, this should be easily identifiable by the Customer.",
+            "description": "The title of the Line Item.",
             "type": "string",
             "example": "Medusa Coffee Mug"
           },
@@ -35031,7 +35870,8 @@
             "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"
           },
           "variant": {
-            "description": "A product variant object. The Product Variant contained in the Line Item. Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant that this item was created from.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
@@ -35104,7 +35944,8 @@
             "example": 0
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Indicates if the line item unit_price include tax",
+            "description": "Indicates if the line item unit_price include tax",
+            "x-featureFlag": "tax_inclusive_pricing",
             "type": "boolean",
             "default": false
           },
@@ -35124,13 +35965,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "LineItemAdjustment": {
         "title": "Line Item Adjustment",
-        "description": "Represents a Line Item Adjustment",
+        "description": "A Line Item Adjustment includes details on discounts applied on a line item.",
         "type": "object",
         "required": [
           "amount",
@@ -35152,7 +35997,8 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -35168,7 +36014,8 @@
             "example": "disc_01F0YESMW10MGHWJKZSDDMN0VN"
           },
           "discount": {
-            "description": "Available if the relation `discount` is expanded.",
+            "description": "The details of the discount associated with the adjustment.",
+            "x-expandable": "discount",
             "nullable": true,
             "$ref": "#/components/schemas/Discount"
           },
@@ -35183,13 +36030,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "LineItemTaxLine": {
         "title": "Line Item Tax Line",
-        "description": "Represents a Line Item Tax Line",
+        "description": "A Line Item Tax Line represents the taxes applied on a line item.",
         "type": "object",
         "required": [
           "code",
@@ -35229,7 +36080,8 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -35249,6 +36101,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -35275,7 +36131,7 @@
       },
       "MoneyAmount": {
         "title": "Money Amount",
-        "description": "Money Amounts represents an amount that a given Product Variant can be purcased for. Each Money Amount either has a Currency or Region associated with it to indicate the pricing in a given Currency or, for fully region-based pricing, the given price in a specific Region. If region-based pricing is used the amount will be in the currency defined for the Reigon.",
+        "description": "A Money Amount represent a price amount, for example, a product variant's price or a price in a price list. Each Money Amount either has a Currency or Region associated with it to indicate the pricing in a given Currency or, for fully region-based pricing, the given price in a specific Region. If region-based pricing is used, the amount will be in the currency defined for the Region.",
         "type": "object",
         "required": [
           "amount",
@@ -35297,7 +36153,7 @@
             "example": "ma_01F0YESHRFQNH5S8Q0PK84YYZN"
           },
           "currency_code": {
-            "description": "The 3 character currency code that the Money Amount is given in.",
+            "description": "The 3 character currency code that the money amount may belong to.",
             "type": "string",
             "example": "usd",
             "externalDocs": {
@@ -35306,7 +36162,8 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency that the money amount may belong to.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
@@ -35328,24 +36185,26 @@
             "example": 1
           },
           "price_list_id": {
-            "description": "The ID of the price list associated with the money amount",
+            "description": "The ID of the price list that the money amount may belong to.",
             "nullable": true,
             "type": "string",
             "example": "pl_01G8X3CKJXCG5VXVZ87H9KC09W"
           },
           "price_list": {
-            "description": "Available if the relation `price_list` is expanded.",
+            "description": "The details of the price list that the money amount may belong to.",
+            "x-expandable": "price_list",
             "nullable": true,
             "$ref": "#/components/schemas/PriceList"
           },
           "variant_id": {
-            "description": "The id of the Product Variant contained in the Line Item.",
+            "description": "The ID of the Product Variant contained in the Line Item.",
             "nullable": true,
             "type": "string",
             "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"
           },
           "variant": {
-            "description": "The Product Variant contained in the Line Item. Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant that the money amount may belong to.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
@@ -35356,7 +36215,8 @@
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region that the money amount may belong to.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
@@ -35397,7 +36257,7 @@
       },
       "Note": {
         "title": "Note",
-        "description": "Notes are elements which we can use in association with different resources to allow users to describe additional information in relation to these.",
+        "description": "A Note is an element that can be used in association with different resources to allow admin users to describe additional information. For example, they can be used to add additional information about orders.",
         "type": "object",
         "required": [
           "author_id",
@@ -35432,13 +36292,14 @@
             "example": "This order must be fulfilled on Monday"
           },
           "author_id": {
-            "description": "The ID of the author (user)",
+            "description": "The ID of the user that created the note.",
             "nullable": true,
             "type": "string",
             "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"
           },
           "author": {
-            "description": "Available if the relation `author` is expanded.",
+            "description": "The details of the user that created the note.",
+            "x-expandable": "author",
             "nullable": true,
             "$ref": "#/components/schemas/User"
           },
@@ -35470,7 +36331,7 @@
       },
       "Notification": {
         "title": "Notification",
-        "description": "Notifications a communications sent via Notification Providers as a reaction to internal events such as `order.placed`. Notifications can be used to show a chronological timeline for communications sent to a Customer regarding an Order, and enables resends.",
+        "description": "A notification is an alert sent, typically to customers, using the installed Notification Provider as a reaction to internal events such as `order.placed`. Notifications can be resent.",
         "type": "object",
         "required": [
           "created_at",
@@ -35508,18 +36369,19 @@
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "customer_id": {
-            "description": "The ID of the Customer that the Notification was sent to.",
+            "description": "The ID of the customer that this notification was sent to.",
             "nullable": true,
             "type": "string",
             "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "customer": {
-            "description": "A customer object. Available if the relation `customer` is expanded.",
+            "description": "The details of the customer that this notification was sent to.",
+            "x-expandable": "customer",
             "nullable": true,
             "$ref": "#/components/schemas/Customer"
           },
           "to": {
-            "description": "The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id",
+            "description": "The address that the Notification was sent to. This will usually be an email address, but can represent other addresses such as a chat bot user ID.",
             "type": "string",
             "example": "user@example.com"
           },
@@ -35535,25 +36397,28 @@
             "example": "noti_01G53V9Y6CKMCGBM1P0X7C28RX"
           },
           "parent_notification": {
-            "description": "Available if the relation `parent_notification` is expanded.",
+            "description": "The details of the parent notification.",
+            "x-expandable": "parent_notification",
             "nullable": true,
             "$ref": "#/components/schemas/Notification"
           },
           "resends": {
-            "description": "The resends that have been completed after the original Notification. Available if the relation `resends` is expanded.",
+            "description": "The details of all resends of the notification.",
             "type": "array",
+            "x-expandable": "resends",
             "items": {
               "$ref": "#/components/schemas/Notification"
             }
           },
           "provider_id": {
-            "description": "The id of the Notification Provider that handles the Notification.",
+            "description": "The ID of the notification provider used to send the notification.",
             "nullable": true,
             "type": "string",
             "example": "sengrid"
           },
           "provider": {
-            "description": "Available if the relation `provider` is expanded.",
+            "description": "The notification provider used to send the notification.",
+            "x-expandable": "provider",
             "nullable": true,
             "$ref": "#/components/schemas/NotificationProvider"
           },
@@ -35571,7 +36436,7 @@
       },
       "NotificationProvider": {
         "title": "Notification Provider",
-        "description": "Represents a notification provider plugin and holds its installation status.",
+        "description": "A notification provider represents a notification service installed in the Medusa backend, either through a plugin or backend customizations. It holds the notification service's installation status.",
         "type": "object",
         "required": [
           "id",
@@ -35579,12 +36444,12 @@
         ],
         "properties": {
           "id": {
-            "description": "The id of the notification provider as given by the plugin.",
+            "description": "The ID of the notification provider as given by the notification service.",
             "type": "string",
             "example": "sendgrid"
           },
           "is_installed": {
-            "description": "Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`.",
+            "description": "Whether the notification service is installed in the current version. If a notification service is no longer installed, the `is_installed` attribute is set to `false`.",
             "type": "boolean",
             "default": true
           }
@@ -35592,7 +36457,7 @@
       },
       "OAuth": {
         "title": "OAuth",
-        "description": "Represent an OAuth app",
+        "description": "An Oauth app is typically created by a plugin to handle authentication to third-party services.",
         "type": "object",
         "required": [
           "application_name",
@@ -35640,7 +36505,7 @@
       },
       "Order": {
         "title": "Order",
-        "description": "Represents an order",
+        "description": "An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.",
         "type": "object",
         "required": [
           "billing_address_id",
@@ -35726,7 +36591,8 @@
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart associated with the order.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
@@ -35736,7 +36602,8 @@
             "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "customer": {
-            "description": "A customer object. Available if the relation `customer` is expanded.",
+            "description": "The details of the customer associated with the order.",
+            "x-expandable": "customer",
             "nullable": true,
             "$ref": "#/components/schemas/Customer"
           },
@@ -35752,7 +36619,8 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "billing_address": {
-            "description": "Available if the relation `billing_address` is expanded.",
+            "description": "The details of the billing address associated with the order.",
+            "x-expandable": "billing_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
@@ -35763,17 +36631,19 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "shipping_address": {
-            "description": "Available if the relation `shipping_address` is expanded.",
+            "description": "The details of the shipping address associated with the order.",
+            "x-expandable": "shipping_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "region_id": {
-            "description": "The region's ID",
+            "description": "The ID of the region this order was created in.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region this order was created in.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
@@ -35787,7 +36657,8 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency used in the order.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
@@ -35798,96 +36669,109 @@
             "example": 0
           },
           "discounts": {
-            "description": "The discounts used in the order. Available if the relation `discounts` is expanded.",
+            "description": "The details of the discounts applied on the order.",
             "type": "array",
+            "x-expandable": "discounts",
             "items": {
               "$ref": "#/components/schemas/Discount"
             }
           },
           "gift_cards": {
-            "description": "The gift cards used in the order. Available if the relation `gift_cards` is expanded.",
+            "description": "The details of the gift card used in the order.",
             "type": "array",
+            "x-expandable": "gift_cards",
             "items": {
               "$ref": "#/components/schemas/GiftCard"
             }
           },
           "shipping_methods": {
-            "description": "The shipping methods used in the order. Available if the relation `shipping_methods` is expanded.",
+            "description": "The details of the shipping methods used in the order.",
             "type": "array",
+            "x-expandable": "shipping_methods",
             "items": {
               "$ref": "#/components/schemas/ShippingMethod"
             }
           },
           "payments": {
-            "description": "The payments used in the order. Available if the relation `payments` is expanded.",
+            "description": "The details of the payments used in the order.",
             "type": "array",
+            "x-expandable": "payments",
             "items": {
               "$ref": "#/components/schemas/Payment"
             }
           },
           "fulfillments": {
-            "description": "The fulfillments used in the order. Available if the relation `fulfillments` is expanded.",
+            "description": "The details of the fulfillments created for the order.",
             "type": "array",
+            "x-expandable": "fulfillments",
             "items": {
               "$ref": "#/components/schemas/Fulfillment"
             }
           },
           "returns": {
-            "description": "The returns associated with the order. Available if the relation `returns` is expanded.",
+            "description": "The details of the returns created for the order.",
             "type": "array",
+            "x-expandable": "returns",
             "items": {
               "$ref": "#/components/schemas/Return"
             }
           },
           "claims": {
-            "description": "The claims associated with the order. Available if the relation `claims` is expanded.",
+            "description": "The details of the claims created for the order.",
             "type": "array",
+            "x-expandable": "claims",
             "items": {
               "$ref": "#/components/schemas/ClaimOrder"
             }
           },
           "refunds": {
-            "description": "The refunds associated with the order. Available if the relation `refunds` is expanded.",
+            "description": "The details of the refunds created for the order.",
             "type": "array",
+            "x-expandable": "refunds",
             "items": {
               "$ref": "#/components/schemas/Refund"
             }
           },
           "swaps": {
-            "description": "The swaps associated with the order. Available if the relation `swaps` is expanded.",
+            "description": "The details of the swaps created for the order.",
             "type": "array",
+            "x-expandable": "swaps",
             "items": {
               "$ref": "#/components/schemas/Swap"
             }
           },
           "draft_order_id": {
-            "description": "The ID of the draft order this order is associated with.",
+            "description": "The ID of the draft order this order was created from.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "draft_order": {
-            "description": "A draft order object. Available if the relation `draft_order` is expanded.",
+            "description": "The details of the draft order this order was created from.",
+            "x-expandable": "draft_order",
             "nullable": true,
             "$ref": "#/components/schemas/DraftOrder"
           },
           "items": {
-            "description": "The line items that belong to the order. Available if the relation `items` is expanded.",
+            "description": "The details of the line items that belong to the order.",
+            "x-expandable": "items",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
           },
           "edits": {
-            "description": "Order edits done on the order. Available if the relation `edits` is expanded.",
+            "description": "The details of the order edits done on the order.",
             "type": "array",
+            "x-expandable": "edits",
             "items": {
               "$ref": "#/components/schemas/OrderEdit"
             }
           },
           "gift_card_transactions": {
-            "description": "The gift card transactions used in the order. Available if the relation `gift_card_transactions` is expanded.",
+            "description": "The gift card transactions made in the order.",
             "type": "array",
+            "x-expandable": "gift_card_transactions",
             "items": {
               "$ref": "#/components/schemas/GiftCardTransaction"
             }
@@ -35920,13 +36804,14 @@
             "example": null
           },
           "sales_channel_id": {
-            "description": "The ID of the sales channel this order is associated with.",
+            "description": "The ID of the sales channel this order belongs to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "sales_channel": {
-            "description": "A sales channel object. Available if the relation `sales_channel` is expanded.",
+            "description": "The details of the sales channel this order belongs to.",
+            "x-expandable": "sales_channel",
             "nullable": true,
             "$ref": "#/components/schemas/SalesChannel"
           },
@@ -35986,8 +36871,9 @@
             "example": 0
           },
           "returnable_items": {
-            "description": "The items that are returnable as part of the order, order swaps or order claims",
+            "description": "The details of the line items that are returnable as part of the order, swaps, or claims",
             "type": "array",
+            "x-expandable": "returnable_items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
@@ -36008,13 +36894,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "OrderEdit": {
         "title": "Order Edit",
-        "description": "Order edit keeps track of order items changes.",
+        "description": "Order edit allows modifying items in an order, such as adding, updating, or deleting items from the original order. Once the order edit is confirmed, the changes are reflected on the original order.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -36047,12 +36937,14 @@
             "example": "order_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "order": {
-            "description": "Available if the relation `order` is expanded.",
+            "description": "The details of the order that this order edit was created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "changes": {
-            "description": "Available if the relation `changes` is expanded.",
+            "description": "The details of all the changes on the original order's line items.",
+            "x-expandable": "changes",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/OrderItemChange"
@@ -36169,8 +37061,9 @@
             ]
           },
           "items": {
-            "description": "Available if the relation `items` is expanded.",
+            "description": "The details of the cloned items from the original order with the new changes. Once the order edit is confirmed, these line items are associated with the original order.",
             "type": "array",
+            "x-expandable": "items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
@@ -36182,7 +37075,8 @@
             "example": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "payment_collection": {
-            "description": "Available if the relation `payment_collection` is expanded.",
+            "description": "The details of the payment collection used to authorize additional payment if necessary.",
+            "x-expandable": "payment_collection",
             "nullable": true,
             "$ref": "#/components/schemas/PaymentCollection"
           },
@@ -36200,7 +37094,7 @@
       },
       "OrderItemChange": {
         "title": "Order Item Change",
-        "description": "Represents an order edit item change",
+        "description": "An order item change is a change made within an order edit to an order's items. These changes are not reflected on the original order until the order edit is confirmed.",
         "type": "object",
         "required": [
           "created_at",
@@ -36233,7 +37127,8 @@
             "example": "oe_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "order_edit": {
-            "description": "Available if the relation `order_edit` is expanded.",
+            "description": "The details of the order edit the item change is associated with.",
+            "x-expandable": "order_edit",
             "nullable": true,
             "$ref": "#/components/schemas/OrderEdit"
           },
@@ -36244,7 +37139,8 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "original_line_item": {
-            "description": "Available if the relation `original_line_item` is expanded.",
+            "description": "The details of the original line item this item change references. This is used if the item change updates or deletes the original item.",
+            "x-expandable": "original_line_item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -36255,7 +37151,8 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "line_item": {
-            "description": "Available if the relation `line_item` is expanded.",
+            "description": "The details of the resulting line item after the item change. This line item is then used in the original order once the order edit is confirmed.",
+            "x-expandable": "line_item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -36279,7 +37176,7 @@
       },
       "Payment": {
         "title": "Payment",
-        "description": "Payments represent an amount authorized with a given payment method, Payments can be captured, canceled or refunded.",
+        "description": "A payment is originally created from a payment session. Once a payment session is authorized, the payment is created to represent the authorized amount with a given payment method. Payments can be captured, canceled or refunded. Payments can be made towards orders, swaps, order edits, or other resources.",
         "type": "object",
         "required": [
           "amount",
@@ -36305,34 +37202,37 @@
             "example": "pay_01G2SJNT6DEEWDFNAJ4XWDTHKE"
           },
           "swap_id": {
-            "description": "The ID of the Swap that the Payment is used for.",
+            "description": "The ID of the swap that this payment was potentially created for.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that this payment was potentially created for.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "cart_id": {
-            "description": "The id of the Cart that the Payment Session is created for.",
+            "description": "The ID of the cart that the payment session was potentially created for.",
             "nullable": true,
             "type": "string"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the payment session was potentially created for.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "order_id": {
-            "description": "The ID of the Order that the Payment is used for.",
+            "description": "The ID of the order that the payment session was potentially created for.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the payment session was potentially created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
@@ -36342,7 +37242,7 @@
             "example": 100
           },
           "currency_code": {
-            "description": "The 3 character ISO currency code that the Payment is completed in.",
+            "description": "The 3 character ISO currency code of the payment.",
             "type": "string",
             "example": "usd",
             "externalDocs": {
@@ -36351,7 +37251,8 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency of the payment.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
@@ -36408,13 +37309,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "PaymentCollection": {
         "title": "Payment Collection",
-        "description": "Payment Collection",
+        "description": "A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.",
         "type": "object",
         "required": [
           "amount",
@@ -36470,17 +37375,18 @@
             "type": "integer"
           },
           "region_id": {
-            "description": "The region's ID",
+            "description": "The ID of the region this payment collection is associated with.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "Available if the relation `region` is expanded.",
+            "description": "The details of the region this payment collection is associated with.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "currency_code": {
-            "description": "The 3 character ISO code for the currency.",
+            "description": "The 3 character ISO code for the currency this payment collection is associated with.",
             "type": "string",
             "example": "usd",
             "externalDocs": {
@@ -36489,20 +37395,23 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency this payment collection is associated with.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
           "payment_sessions": {
-            "description": "Available if the relation `payment_sessions` is expanded.",
+            "description": "The details of the payment sessions created as part of the payment collection.",
             "type": "array",
+            "x-expandable": "payment_sessions",
             "items": {
               "$ref": "#/components/schemas/PaymentSession"
             }
           },
           "payments": {
-            "description": "Available if the relation `payments` is expanded.",
+            "description": "The details of the payments created as part of the payment collection.",
             "type": "array",
+            "x-expandable": "payments",
             "items": {
               "$ref": "#/components/schemas/Payment"
             }
@@ -36533,13 +37442,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "PaymentProvider": {
         "title": "Payment Provider",
-        "description": "Represents a Payment Provider plugin and holds its installation status.",
+        "description": "A payment provider represents a payment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the payment service's installation status.",
         "type": "object",
         "required": [
           "id",
@@ -36547,12 +37460,12 @@
         ],
         "properties": {
           "id": {
-            "description": "The id of the payment provider as given by the plugin.",
+            "description": "The ID of the payment provider as given by the payment service.",
             "type": "string",
             "example": "manual"
           },
           "is_installed": {
-            "description": "Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`.",
+            "description": "Whether the payment service is installed in the current version. If a payment service is no longer installed, the `is_installed` attribute is set to `false`.",
             "type": "boolean",
             "default": true
           }
@@ -36560,7 +37473,7 @@
       },
       "PaymentSession": {
         "title": "Payment Session",
-        "description": "Payment Sessions are created when a Customer initilizes the checkout flow, and can be used to hold the state of a payment flow. Each Payment Session is controlled by a Payment Provider, who is responsible for the communication with external payment services. Authorized Payment Sessions will eventually get promoted to Payments to indicate that they are authorized for capture/refunds/etc.",
+        "description": "A Payment Session is created when a Customer initilizes the checkout flow, and can be used to hold the state of a payment flow. Each Payment Session is controlled by a Payment Provider, which is responsible for the communication with external payment services. Authorized Payment Sessions will eventually get promoted to Payments to indicate that they are authorized for payment processing such as capture or refund. Payment sessions can also be used as part of payment collections.",
         "type": "object",
         "required": [
           "amount",
@@ -36583,18 +37496,19 @@
             "example": "ps_01G901XNSRM2YS3ASN9H5KG3FZ"
           },
           "cart_id": {
-            "description": "The id of the Cart that the Payment Session is created for.",
+            "description": "The ID of the cart that the payment session was created for.",
             "nullable": true,
             "type": "string",
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the payment session was created for.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "provider_id": {
-            "description": "The id of the Payment Provider that is responsible for the Payment Session",
+            "description": "The ID of the Payment Provider that is responsible for the Payment Session",
             "type": "string",
             "example": "manual"
           },
@@ -36662,7 +37576,7 @@
       },
       "PriceList": {
         "title": "Price List",
-        "description": "Price Lists represents a set of prices that overrides the default price for one or more product variants.",
+        "description": "A Price List represents a set of prices that override the default price for one or more product variants.",
         "type": "object",
         "required": [
           "created_at",
@@ -36723,22 +37637,25 @@
             "format": "date-time"
           },
           "customer_groups": {
-            "description": "The Customer Groups that the Price List applies to. Available if the relation `customer_groups` is expanded.",
+            "description": "The details of the customer groups that the Price List can apply to.",
             "type": "array",
+            "x-expandable": "customer_groups",
             "items": {
               "$ref": "#/components/schemas/CustomerGroup"
             }
           },
           "prices": {
-            "description": "The Money Amounts that are associated with the Price List. Available if the relation `prices` is expanded.",
+            "description": "The prices that belong to the price list, represented as a Money Amount.",
             "type": "array",
+            "x-expandable": "prices",
             "items": {
               "$ref": "#/components/schemas/MoneyAmount"
             }
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Does the price list prices include tax",
+            "description": "Whether the price list prices include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           },
           "created_at": {
@@ -36883,7 +37800,7 @@
       },
       "Product": {
         "title": "Product",
-        "description": "Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.",
+        "description": "A product is a saleable item that holds general information such as name or description. It must include at least one Product Variant, where each product variant defines different options to purchase the product with (for example, different sizes or colors). The prices and inventory of the product are defined on the variant level.",
         "type": "object",
         "required": [
           "collection_id",
@@ -36957,8 +37874,9 @@
             "default": "draft"
           },
           "images": {
-            "description": "Images of the Product. Available if the relation `images` is expanded.",
+            "description": "The details of the product's images.",
             "type": "array",
+            "x-expandable": "images",
             "items": {
               "$ref": "#/components/schemas/Image"
             }
@@ -36970,36 +37888,49 @@
             "format": "uri"
           },
           "options": {
-            "description": "The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation `options` is expanded.",
+            "description": "The details of the Product Options that are defined for the Product. The product's variants will have a unique combination of values of the product's options.",
             "type": "array",
+            "x-expandable": "options",
             "items": {
               "$ref": "#/components/schemas/ProductOption"
             }
           },
           "variants": {
-            "description": "The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation `variants` is expanded.",
+            "description": "The details of the Product Variants that belong to the Product. Each will have a unique combination of values of the product's options.",
             "type": "array",
+            "x-expandable": "variants",
             "items": {
               "$ref": "#/components/schemas/ProductVariant"
             }
           },
           "categories": {
-            "description": "The product's associated categories. Available if the relation `categories` are expanded.",
+            "description": "The details of the product categories that this product belongs to.",
             "type": "array",
+            "x-expandable": "categories",
+            "x-featureFlag": "product_categories",
             "items": {
               "$ref": "#/components/schemas/ProductCategory"
             }
           },
           "profile_id": {
-            "description": "The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.",
+            "description": "The ID of the shipping profile that the product belongs to. The shipping profile has a set of defined shipping options that can be used to fulfill the product.",
             "type": "string",
             "example": "sp_01G1G5V239ENSZ5MV4JAR737BM"
           },
           "profile": {
-            "description": "Available if the relation `profile` is expanded.",
+            "description": "The details of the shipping profile that the product belongs to. The shipping profile has a set of defined shipping options that can be used to fulfill the product.",
+            "x-expandable": "profile",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingProfile"
           },
+          "profiles": {
+            "description": "Available if the relation `profiles` is expanded.",
+            "nullable": true,
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ShippingProfile"
+            }
+          },
           "weight": {
             "description": "The weight of the Product Variant. May be used in shipping rate calculations.",
             "nullable": true,
@@ -37049,30 +37980,33 @@
             "example": null
           },
           "collection_id": {
-            "description": "The Product Collection that the Product belongs to",
+            "description": "The ID of the product collection that the product belongs to.",
             "nullable": true,
             "type": "string",
             "example": "pcol_01F0YESBFAZ0DV6V831JXWH0BG"
           },
           "collection": {
-            "description": "A product collection object. Available if the relation `collection` is expanded.",
+            "description": "The details of the product collection that the product belongs to.",
+            "x-expandable": "collection",
             "nullable": true,
             "$ref": "#/components/schemas/ProductCollection"
           },
           "type_id": {
-            "description": "The Product type that the Product belongs to",
+            "description": "The ID of the product type that the product belongs to.",
             "nullable": true,
             "type": "string",
             "example": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "type": {
-            "description": "Available if the relation `type` is expanded.",
+            "description": "The details of the product type that the product belongs to.",
+            "x-expandable": "type",
             "nullable": true,
             "$ref": "#/components/schemas/ProductType"
           },
           "tags": {
-            "description": "The Product Tags assigned to the Product. Available if the relation `tags` is expanded.",
+            "description": "The details of the product tags used in this product.",
             "type": "array",
+            "x-expandable": "type",
             "items": {
               "$ref": "#/components/schemas/ProductTag"
             }
@@ -37089,8 +38023,9 @@
             "example": null
           },
           "sales_channels": {
-            "description": "The sales channels the product is associated with. Available if the relation `sales_channels` is expanded.",
+            "description": "The details of the sales channels this product is available in.",
             "type": "array",
+            "x-expandable": "sales_channels",
             "items": {
               "$ref": "#/components/schemas/SalesChannel"
             }
@@ -37117,14 +38052,19 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductCategory": {
-        "title": "ProductCategory",
-        "description": "Represents a product category",
+        "title": "Product Category",
+        "description": "A product category can be used to categorize products into a hierarchy of categories.",
         "x-resourceId": "ProductCategory",
+        "x-featureFlag": "product_categories",
         "type": "object",
         "required": [
           "category_children",
@@ -37176,8 +38116,9 @@
             "default": 0
           },
           "category_children": {
-            "description": "Available if the relation `category_children` are expanded.",
+            "description": "The details of the category's children.",
             "type": "array",
+            "x-expandable": "category_children",
             "items": {
               "$ref": "#/components/schemas/ProductCategory"
             }
@@ -37189,13 +38130,15 @@
             "default": null
           },
           "parent_category": {
-            "description": "A product category object. Available if the relation `parent_category` is expanded.",
+            "description": "The details of the parent of this category.",
+            "x-expandable": "parent_category",
             "nullable": true,
             "$ref": "#/components/schemas/ProductCategory"
           },
           "products": {
-            "description": "Products associated with category. Available if the relation `products` is expanded.",
+            "description": "The details of the products that belong to this category.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
@@ -37214,7 +38157,7 @@
       },
       "ProductCollection": {
         "title": "Product Collection",
-        "description": "Product Collections represents a group of Products that are related.",
+        "description": "A Product Collection allows grouping together products for promotional purposes. For example, an admin can create a Summer collection, add products to it, and showcase it on the storefront.",
         "type": "object",
         "required": [
           "created_at",
@@ -37243,8 +38186,9 @@
             "example": "summer-collection"
           },
           "products": {
-            "description": "The Products contained in the Product Collection. Available if the relation `products` is expanded.",
+            "description": "The details of the products that belong to this product collection.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
@@ -37271,13 +38215,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductOption": {
         "title": "Product Option",
-        "description": "Product Options define properties that may vary between different variants of a Product. Common Product Options are \"Size\" and \"Color\", but Medusa doesn't limit what Product Options that can be defined.",
+        "description": "A Product Option defines properties that may vary between different variants of a Product. Common Product Options are \"Size\" and \"Color\". Admins are free to create any product options.",
         "type": "object",
         "required": [
           "created_at",
@@ -37300,19 +38248,21 @@
             "example": "Size"
           },
           "values": {
-            "description": "The Product Option Values that are defined for the Product Option. Available if the relation `values` is expanded.",
+            "description": "The details of the values of the product option.",
             "type": "array",
+            "x-expandable": "values",
             "items": {
               "$ref": "#/components/schemas/ProductOptionValue"
             }
           },
           "product_id": {
-            "description": "The ID of the Product that the Product Option is defined for.",
+            "description": "The ID of the product that this product option belongs to.",
             "type": "string",
             "example": "prod_01G1G5V2MBA328390B5AXJ610F"
           },
           "product": {
-            "description": "A product object. Available if the relation `product` is expanded.",
+            "description": "The details of the product that this product option belongs to.",
+            "x-expandable": "product",
             "nullable": true,
             "$ref": "#/components/schemas/Product"
           },
@@ -37338,13 +38288,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductOptionValue": {
         "title": "Product Option Value",
-        "description": "A value given to a Product Variant's option set. Product Variant have a Product Option Value for each of the Product Options defined on the Product.",
+        "description": "An option value is one of the possible values of a Product Option. Product Variants specify a unique combination of product option values.",
         "type": "object",
         "required": [
           "created_at",
@@ -37363,27 +38317,29 @@
             "example": "optval_01F0YESHR7S6ECD03RF6W12DSJ"
           },
           "value": {
-            "description": "The value that the Product Variant has defined for the specific Product Option (e.g. if the Product Option is \\\"Size\\\" this value could be `Small`, `Medium` or `Large`).",
+            "description": "The value that the Product Variant has defined for the specific Product Option (e.g. if the Product Option is \"Size\" this value could be `Small`, `Medium` or `Large`).",
             "type": "string",
             "example": "large"
           },
           "option_id": {
-            "description": "The ID of the Product Option that the Product Option Value is defined for.",
+            "description": "The ID of the Product Option that the Product Option Value belongs to.",
             "type": "string",
             "example": "opt_01F0YESHQBZVKCEXJ24BS6PCX3"
           },
           "option": {
-            "description": "Available if the relation `option` is expanded.",
+            "description": "The details of the product option that the Product Option Value belongs to.",
+            "x-expandable": "option",
             "nullable": true,
             "$ref": "#/components/schemas/ProductOption"
           },
           "variant_id": {
-            "description": "The ID of the Product Variant that the Product Option Value is defined for.",
+            "description": "The ID of the product variant that uses this product option value.",
             "type": "string",
             "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"
           },
           "variant": {
-            "description": "Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant that uses this product option value.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
@@ -37409,13 +38365,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductTag": {
         "title": "Product Tag",
-        "description": "Product Tags can be added to Products for easy filtering and grouping.",
+        "description": "A Product Tag can be added to Products for easy filtering and grouping.",
         "type": "object",
         "required": [
           "created_at",
@@ -37458,13 +38418,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductTaxRate": {
         "title": "Product Tax Rate",
-        "description": "Associates a tax rate with a product to indicate that the product is taxed in a certain way",
+        "description": "This represents the association between a tax rate and a product to indicate that the product is taxed in a way different than the default.",
         "type": "object",
         "required": [
           "created_at",
@@ -37480,7 +38444,8 @@
             "example": "prod_01G1G5V2MBA328390B5AXJ610F"
           },
           "product": {
-            "description": "Available if the relation `product` is expanded.",
+            "description": "The details of the product.",
+            "x-expandable": "product",
             "nullable": true,
             "$ref": "#/components/schemas/Product"
           },
@@ -37490,7 +38455,8 @@
             "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR"
           },
           "tax_rate": {
-            "description": "Available if the relation `tax_rate` is expanded.",
+            "description": "The details of the tax rate.",
+            "x-expandable": "tax_rate",
             "nullable": true,
             "$ref": "#/components/schemas/TaxRate"
           },
@@ -37510,13 +38476,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductType": {
         "title": "Product Type",
-        "description": "Product Type can be added to Products for filtering and reporting purposes.",
+        "description": "A Product Type can be added to Products for filtering and reporting purposes.",
         "type": "object",
         "required": [
           "created_at",
@@ -37559,13 +38529,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductTypeTaxRate": {
         "title": "Product Type Tax Rate",
-        "description": "Associates a tax rate with a product type to indicate that the product type is taxed in a certain way",
+        "description": "This represents the association between a tax rate and a product type to indicate that the product type is taxed in a different way than the default.",
         "type": "object",
         "required": [
           "created_at",
@@ -37581,7 +38555,8 @@
             "example": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product_type": {
-            "description": "Available if the relation `product_type` is expanded.",
+            "description": "The details of the product type.",
+            "x-expandable": "product_type",
             "nullable": true,
             "$ref": "#/components/schemas/ProductType"
           },
@@ -37591,7 +38566,8 @@
             "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR"
           },
           "tax_rate": {
-            "description": "Available if the relation `tax_rate` is expanded.",
+            "description": "The details of the tax rate.",
+            "x-expandable": "tax_rate",
             "nullable": true,
             "$ref": "#/components/schemas/TaxRate"
           },
@@ -37611,13 +38587,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductVariant": {
         "title": "Product Variant",
-        "description": "Product Variants represent a Product with a specific set of Product Option configurations. The maximum number of Product Variants that a Product can have is given by the number of available Product Option combinations.",
+        "description": "A Product Variant represents a Product with a specific set of Product Option configurations. The maximum number of Product Variants that a Product can have is given by the number of available Product Option combinations. A product must at least have one product variant.",
         "type": "object",
         "required": [
           "allow_backorder",
@@ -37655,18 +38635,20 @@
             "example": "Small"
           },
           "product_id": {
-            "description": "The ID of the Product that the Product Variant belongs to.",
+            "description": "The ID of the product that the product variant belongs to.",
             "type": "string",
             "example": "prod_01G1G5V2MBA328390B5AXJ610F"
           },
           "product": {
-            "description": "A product object. Available if the relation `product` is expanded.",
+            "description": "The details of the product that the product variant belongs to.",
+            "x-expandable": "product",
             "nullable": true,
             "$ref": "#/components/schemas/Product"
           },
           "prices": {
-            "description": "The Money Amounts defined for the Product Variant. Each Money Amount represents a price in a given currency or a price in a specific Region. Available if the relation `prices` is expanded.",
+            "description": "The details of the prices of the Product Variant, each represented as a Money Amount. Each Money Amount represents a price in a given currency or a specific Region.",
             "type": "array",
+            "x-expandable": "prices",
             "items": {
               "$ref": "#/components/schemas/MoneyAmount"
             }
@@ -37765,15 +38747,17 @@
             "example": null
           },
           "options": {
-            "description": "The Product Option Values specified for the Product Variant. Available if the relation `options` is expanded.",
+            "description": "The details of the product options that this product variant defines values for.",
             "type": "array",
+            "x-expandable": "options",
             "items": {
               "$ref": "#/components/schemas/ProductOptionValue"
             }
           },
           "inventory_items": {
-            "description": "The Inventory Items related to the product variant. Available if the relation `inventory_items` is expanded.",
+            "description": "The details inventory items of the product variant.",
             "type": "array",
+            "x-expandable": "inventory_items",
             "items": {
               "$ref": "#/components/schemas/ProductVariantInventoryItem"
             }
@@ -37800,6 +38784,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           },
           "purchasable": {
@@ -37810,7 +38798,7 @@
       },
       "ProductVariantInventoryItem": {
         "title": "Product Variant Inventory Item",
-        "description": "Product Variant Inventory Items link variants with inventory items and denote the number of inventory items constituting a variant.",
+        "description": "A Product Variant Inventory Item links variants with inventory items and denotes the required quantity of the variant.",
         "type": "object",
         "required": [
           "created_at",
@@ -37836,12 +38824,13 @@
             "type": "string"
           },
           "variant": {
-            "description": "A ProductVariant object. Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
           "required_quantity": {
-            "description": "The quantity of an inventory item required for one quantity of the variant.",
+            "description": "The quantity of an inventory item required for the variant.",
             "type": "integer",
             "default": 1
           },
@@ -37865,7 +38854,7 @@
       },
       "PublishableApiKey": {
         "title": "Publishable API key",
-        "description": "Publishable API key defines scopes (i.e. resources) that are available within a request.",
+        "description": "A Publishable API key defines scopes that resources are available in. Then, it can be used in request to infer the resources without having to directly pass them. For example, a publishable API key can be associated with one or more sales channels. Then, when the publishable API key is passed in the header of a request, it is inferred what sales channel is being used without having to pass the sales channel as a query or body parameter of the request. Publishable API keys can only be used with sales channels, at the moment.",
         "type": "object",
         "required": [
           "created_at",
@@ -37917,8 +38906,8 @@
         }
       },
       "PublishableApiKeySalesChannel": {
-        "title": "Publishable API key sales channel",
-        "description": "Holds mapping between Publishable API keys and Sales Channels",
+        "title": "Publishable API Key Sales Channel",
+        "description": "This represents the association between the Publishable API keys and Sales Channels",
         "type": "object",
         "required": [
           "publishable_key_id",
@@ -37939,7 +38928,7 @@
       },
       "Refund": {
         "title": "Refund",
-        "description": "Refund represent an amount of money transfered back to the Customer for a given reason. Refunds may occur in relation to Returns, Swaps and Claims, but can also be initiated by a store operator.",
+        "description": "A refund represents an amount of money transfered back to the customer for a given reason. Refunds may occur in relation to Returns, Swaps and Claims, but can also be initiated by an admin for an order.",
         "type": "object",
         "required": [
           "amount",
@@ -37960,24 +38949,26 @@
             "example": "ref_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "order_id": {
-            "description": "The id of the Order that the Refund is related to.",
+            "description": "The ID of the order this refund was created for.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order this refund was created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "payment_id": {
-            "description": "The payment's ID if available",
+            "description": "The payment's ID, if available.",
             "nullable": true,
             "type": "string",
             "example": "pay_01G8ZCC5W42ZNY842124G7P5R9"
           },
           "payment": {
-            "description": "Available if the relation `payment` is expanded.",
+            "description": "The details of the payment associated with the refund.",
+            "x-expandable": "payment",
             "nullable": true,
             "$ref": "#/components/schemas/Payment"
           },
@@ -38029,13 +39020,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "Region": {
         "title": "Region",
-        "description": "Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.",
+        "description": "A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.",
         "type": "object",
         "required": [
           "automatic_taxes",
@@ -38063,7 +39058,7 @@
             "example": "EU"
           },
           "currency_code": {
-            "description": "The 3 character currency code that the Region uses.",
+            "description": "The 3 character currency code used in the region.",
             "type": "string",
             "example": "usd",
             "externalDocs": {
@@ -38072,7 +39067,8 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency used in the region.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
@@ -38082,8 +39078,9 @@
             "example": 0
           },
           "tax_rates": {
-            "description": "The tax rates that are included in the Region. Available if the relation `tax_rates` is expanded.",
+            "description": "The details of the tax rates used in the region, aside from the default rate.",
             "type": "array",
+            "x-expandable": "tax_rates",
             "items": {
               "$ref": "#/components/schemas/TaxRate"
             }
@@ -38105,8 +39102,9 @@
             "default": true
           },
           "countries": {
-            "description": "The countries that are included in the Region. Available if the relation `countries` is expanded.",
+            "description": "The details of the countries included in this region.",
             "type": "array",
+            "x-expandable": "countries",
             "items": {
               "$ref": "#/components/schemas/Country"
             }
@@ -38118,27 +39116,31 @@
             "example": null
           },
           "tax_provider": {
-            "description": "Available if the relation `tax_provider` is expanded.",
+            "description": "The details of the tax provider used in the region.",
+            "x-expandable": "tax_provider",
             "nullable": true,
             "$ref": "#/components/schemas/TaxProvider"
           },
           "payment_providers": {
-            "description": "The Payment Providers that can be used to process Payments in the Region. Available if the relation `payment_providers` is expanded.",
+            "description": "The details of the payment providers that can be used to process payments in the region.",
             "type": "array",
+            "x-expandable": "payment_providers",
             "items": {
               "$ref": "#/components/schemas/PaymentProvider"
             }
           },
           "fulfillment_providers": {
-            "description": "The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation `fulfillment_providers` is expanded.",
+            "description": "The details of the fulfillment providers that can be used to fulfill items of orders and similar resources in the region.",
             "type": "array",
+            "x-expandable": "fulfillment_providers",
             "items": {
               "$ref": "#/components/schemas/FulfillmentProvider"
             }
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Does the prices for the region include tax",
+            "description": "Whether the prices for the region include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           },
           "created_at": {
@@ -38163,6 +39165,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -38233,12 +39239,29 @@
           },
           {
             "type": "object",
-            "required": [
-              "available_quantity"
-            ],
             "properties": {
-              "available_quantity": {
-                "type": "number"
+              "location_levels": {
+                "type": "array",
+                "description": "The inventory's location levels.",
+                "items": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/InventoryItemDTO"
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "available_quantity"
+                      ],
+                      "properties": {
+                        "available_quantity": {
+                          "description": "The available quantity in the inventory location.",
+                          "type": "number"
+                        }
+                      }
+                    }
+                  ]
+                }
               }
             }
           }
@@ -38246,7 +39269,7 @@
       },
       "Return": {
         "title": "Return",
-        "description": "Return orders hold information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can be used as part of a Swap.",
+        "description": "A Return holds information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can also be used as part of a Swap or a Claim.",
         "type": "object",
         "required": [
           "claim_order_id",
@@ -38282,47 +39305,52 @@
             "default": "requested"
           },
           "items": {
-            "description": "The Return Items that will be shipped back to the warehouse. Available if the relation `items` is expanded.",
+            "description": "The details of the items that the customer is returning.",
             "type": "array",
+            "x-expandable": "items",
             "items": {
               "$ref": "#/components/schemas/ReturnItem"
             }
           },
           "swap_id": {
-            "description": "The ID of the Swap that the Return is a part of.",
+            "description": "The ID of the swap that the return may belong to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that the return may belong to.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "claim_order_id": {
-            "description": "The ID of the Claim that the Return is a part of.",
+            "description": "The ID of the claim that the return may belong to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim that the return may belong to.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
           "order_id": {
-            "description": "The ID of the Order that the Return is made from.",
+            "description": "The ID of the order that the return was created for.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the return was created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "shipping_method": {
-            "description": "The Shipping Method that will be used to send the Return back. Can be null if the Customer facilitates the return shipment themselves. Available if the relation `shipping_method` is expanded.",
+            "description": "The details of the Shipping Method that will be used to send the Return back. Can be null if the Customer will handle the return shipment themselves.",
+            "x-expandable": "shipping_method",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingMethod"
           },
@@ -38333,7 +39361,7 @@
             "example": {}
           },
           "location_id": {
-            "description": "The id of the stock location the return will be added back.",
+            "description": "The ID of the stock location the return will be added back.",
             "nullable": true,
             "type": "string",
             "example": "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK"
@@ -38380,13 +39408,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ReturnItem": {
         "title": "Return Item",
-        "description": "Correlates a Line Item with a Return, keeping track of the quantity of the Line Item that will be returned.",
+        "description": "A return item represents a line item in an order that is to be returned. It includes details related to the return and the reason behind it.",
         "type": "object",
         "required": [
           "is_requested",
@@ -38401,27 +39433,29 @@
         ],
         "properties": {
           "return_id": {
-            "description": "The id of the Return that the Return Item belongs to.",
+            "description": "The ID of the Return that the Return Item belongs to.",
             "type": "string",
             "example": "ret_01F0YET7XPCMF8RZ0Y151NZV2V"
           },
           "item_id": {
-            "description": "The id of the Line Item that the Return Item references.",
+            "description": "The ID of the Line Item that the Return Item references.",
             "type": "string",
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "return_order": {
-            "description": "Available if the relation `return_order` is expanded.",
+            "description": "Details of the Return that the Return Item belongs to.",
+            "x-expandable": "return_order",
             "nullable": true,
             "$ref": "#/components/schemas/Return"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item in the original order to be returned.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
           "quantity": {
-            "description": "The quantity of the Line Item that is included in the Return.",
+            "description": "The quantity of the Line Item to be returned.",
             "type": "integer",
             "example": 1
           },
@@ -38449,7 +39483,8 @@
             "example": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ"
           },
           "reason": {
-            "description": "Available if the relation `reason` is expanded.",
+            "description": "The details of the reason for returning the item.",
+            "x-expandable": "reason",
             "nullable": true,
             "$ref": "#/components/schemas/ReturnReason"
           },
@@ -38465,13 +39500,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ReturnReason": {
         "title": "Return Reason",
-        "description": "A Reason for why a given product is returned. A Return Reason can be used on Return Items in order to indicate why a Line Item was returned.",
+        "description": "A Return Reason is a value defined by an admin. It can be used on Return Items in order to indicate why a Line Item was returned.",
         "type": "object",
         "required": [
           "created_at",
@@ -38513,12 +39552,14 @@
             "example": null
           },
           "parent_return_reason": {
-            "description": "Available if the relation `parent_return_reason` is expanded.",
+            "description": "The details of the parent reason.",
+            "x-expandable": "parent_return_reason",
             "nullable": true,
             "$ref": "#/components/schemas/ReturnReason"
           },
           "return_reason_children": {
-            "description": "Available if the relation `return_reason_children` is expanded.",
+            "description": "The details of the child reasons.",
+            "x-expandable": "return_reason_children",
             "$ref": "#/components/schemas/ReturnReason"
           },
           "created_at": {
@@ -38543,13 +39584,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "SalesChannel": {
         "title": "Sales Channel",
-        "description": "A Sales Channel",
+        "description": "A Sales Channel is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.",
         "type": "object",
         "required": [
           "created_at",
@@ -38583,8 +39628,9 @@
             "default": false
           },
           "locations": {
-            "description": "The Stock Locations related to the sales channel. Available if the relation `locations` is expanded.",
+            "description": "The details of the stock locations related to the sales channel.",
             "type": "array",
+            "x-expandable": "locations",
             "items": {
               "$ref": "#/components/schemas/SalesChannelLocation"
             }
@@ -38604,12 +39650,24 @@
             "nullable": true,
             "type": "string",
             "format": "date-time"
+          },
+          "metadata": {
+            "description": "An optional key-value map with additional details",
+            "nullable": true,
+            "type": "object",
+            "example": {
+              "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
       "SalesChannelLocation": {
         "title": "Sales Channel Stock Location",
-        "description": "Sales Channel Stock Location link sales channels with stock locations.",
+        "description": "This represents the association between a sales channel and a stock locations.",
         "type": "object",
         "required": [
           "created_at",
@@ -38626,16 +39684,17 @@
             "example": "scloc_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "sales_channel_id": {
-            "description": "The id of the Sales Channel",
+            "description": "The ID of the Sales Channel",
             "type": "string",
             "example": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "location_id": {
-            "description": "The id of the Location Stock.",
+            "description": "The ID of the Location Stock.",
             "type": "string"
           },
           "sales_channel": {
-            "description": "The sales channel the location is associated with. Available if the relation `sales_channel` is expanded.",
+            "description": "The details of the sales channel the location is associated with.",
+            "x-expandable": "sales_channel",
             "nullable": true,
             "$ref": "#/components/schemas/SalesChannel"
           },
@@ -38659,7 +39718,7 @@
       },
       "ShippingMethod": {
         "title": "Shipping Method",
-        "description": "Shipping Methods represent a way in which an Order or Return can be shipped. Shipping Methods are built from a Shipping Option, but may contain additional details, that can be necessary for the Fulfillment Provider to handle the shipment.",
+        "description": "A Shipping Method represents a way in which an Order or Return can be shipped. Shipping Methods are created from a Shipping Option, but may contain additional details that can be necessary for the Fulfillment Provider to handle the shipment. If the shipping method is created for a return, it may be associated with a claim or a swap that the return is part of.",
         "type": "object",
         "required": [
           "cart_id",
@@ -38679,73 +39738,80 @@
             "example": "sm_01F0YET7DR2E7CYVSDHM593QG2"
           },
           "shipping_option_id": {
-            "description": "The id of the Shipping Option that the Shipping Method is built from.",
+            "description": "The ID of the Shipping Option that the Shipping Method is built from.",
             "type": "string",
             "example": "so_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "order_id": {
-            "description": "The id of the Order that the Shipping Method is used on.",
+            "description": "The ID of the order that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the shipping method is used in.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "claim_order_id": {
-            "description": "The id of the Claim that the Shipping Method is used on.",
+            "description": "The ID of the claim that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim that the shipping method is used in.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
           "cart_id": {
-            "description": "The id of the Cart that the Shipping Method is used on.",
+            "description": "The ID of the cart that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the shipping method is used in.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "swap_id": {
-            "description": "The id of the Swap that the Shipping Method is used on.",
+            "description": "The ID of the swap that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that the shipping method is used in.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "return_id": {
-            "description": "The id of the Return that the Shipping Method is used on.",
+            "description": "The ID of the return that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "return_order": {
-            "description": "A return object. Available if the relation `return_order` is expanded.",
+            "description": "The details of the return that the shipping method is used in.",
+            "x-expandable": "return_order",
             "nullable": true,
             "$ref": "#/components/schemas/Return"
           },
           "shipping_option": {
-            "description": "Available if the relation `shipping_option` is expanded.",
+            "description": "The details of the shipping option the method was created from.",
+            "x-expandable": "shipping_option",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingOption"
           },
           "tax_lines": {
-            "description": "Available if the relation `tax_lines` is expanded.",
+            "description": "The details of the tax lines applied on the shipping method.",
             "type": "array",
+            "x-expandable": "tax_lines",
             "items": {
               "$ref": "#/components/schemas/ShippingMethodTaxLine"
             }
@@ -38761,8 +39827,9 @@
             "example": {}
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Indicates if the shipping method price include tax",
+            "description": "Whether the shipping method price include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           },
           "subtotal": {
@@ -38784,7 +39851,7 @@
       },
       "ShippingMethodTaxLine": {
         "title": "Shipping Method Tax Line",
-        "description": "Shipping Method Tax Line",
+        "description": "A Shipping Method Tax Line represents the taxes applied on a shipping method in a cart.",
         "type": "object",
         "required": [
           "code",
@@ -38824,7 +39891,8 @@
             "example": "sm_01F0YET7DR2E7CYVSDHM593QG2"
           },
           "shipping_method": {
-            "description": "Available if the relation `shipping_method` is expanded.",
+            "description": "The details of the associated shipping method.",
+            "x-expandable": "shipping_method",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingMethod"
           },
@@ -38844,13 +39912,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ShippingOption": {
         "title": "Shipping Option",
-        "description": "Shipping Options represent a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information.",
+        "description": "A Shipping Option represents a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information.",
         "type": "object",
         "required": [
           "admin_only",
@@ -38880,32 +39952,35 @@
             "example": "PostFake Standard"
           },
           "region_id": {
-            "description": "The region's ID",
+            "description": "The ID of the region this shipping option can be used in.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region this shipping option can be used in.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "profile_id": {
-            "description": "The ID of the Shipping Profile that the shipping option belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.",
+            "description": "The ID of the Shipping Profile that the shipping option belongs to.",
             "type": "string",
             "example": "sp_01G1G5V239ENSZ5MV4JAR737BM"
           },
           "profile": {
-            "description": "Available if the relation `profile` is expanded.",
+            "description": "The details of the shipping profile that the shipping option belongs to.",
+            "x-expandable": "profile",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingProfile"
           },
           "provider_id": {
-            "description": "The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option.",
+            "description": "The ID of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.",
             "type": "string",
             "example": "manual"
           },
           "provider": {
-            "description": "Available if the relation `provider` is expanded.",
+            "description": "The details of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.",
+            "x-expandable": "provider",
             "nullable": true,
             "$ref": "#/components/schemas/FulfillmentProvider"
           },
@@ -38935,8 +40010,9 @@
             "default": false
           },
           "requirements": {
-            "description": "The requirements that must be satisfied for the Shipping Option to be available for a Cart. Available if the relation `requirements` is expanded.",
+            "description": "The details of the requirements that must be satisfied for the Shipping Option to be available for usage in a Cart.",
             "type": "array",
+            "x-expandable": "requirements",
             "items": {
               "$ref": "#/components/schemas/ShippingOptionRequirement"
             }
@@ -38947,8 +40023,9 @@
             "example": {}
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Does the shipping option price include tax",
+            "description": "Whether the shipping option price include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           },
           "created_at": {
@@ -38973,13 +40050,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ShippingOptionRequirement": {
         "title": "Shipping Option Requirement",
-        "description": "A requirement that a Cart must satisfy for the Shipping Option to be available to the Cart.",
+        "description": "A shipping option requirement defines conditions that a Cart must satisfy for the Shipping Option to be available for usage in the Cart.",
         "type": "object",
         "required": [
           "amount",
@@ -38995,12 +40076,13 @@
             "example": "sor_01G1G5V29AB4CTNDRFSRWSRKWD"
           },
           "shipping_option_id": {
-            "description": "The id of the Shipping Option that the hipping option requirement belongs to",
+            "description": "The ID of the shipping option that the requirements belong to.",
             "type": "string",
             "example": "so_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "shipping_option": {
-            "description": "Available if the relation `shipping_option` is expanded.",
+            "description": "The details of the shipping option that the requirements belong to.",
+            "x-expandable": "shipping_option",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingOption"
           },
@@ -39028,7 +40110,7 @@
       },
       "ShippingProfile": {
         "title": "Shipping Profile",
-        "description": "Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.",
+        "description": "A Shipping Profile has a set of defined Shipping Options that can be used to fulfill a given set of Products. For example, gift cards are shipped differently than physical products, so a shipping profile with the type `gift_card` groups together the shipping options that can only be used for gift cards.",
         "type": "object",
         "required": [
           "created_at",
@@ -39061,15 +40143,17 @@
             "example": "default"
           },
           "products": {
-            "description": "The Products that the Shipping Profile defines Shipping Options for. Available if the relation `products` is expanded.",
+            "description": "The details of the products that the Shipping Profile defines Shipping Options for. Available if the relation `products` is expanded.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
           },
           "shipping_options": {
-            "description": "The Shipping Options that can be used to fulfill the Products in the Shipping Profile. Available if the relation `shipping_options` is expanded.",
+            "description": "The details of the shipping options that can be used to create shipping methods for the Products in the Shipping Profile.",
             "type": "array",
+            "x-expandable": "shipping_options",
             "items": {
               "$ref": "#/components/schemas/ShippingOption"
             }
@@ -39096,13 +40180,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ShippingTaxRate": {
         "title": "Shipping Tax Rate",
-        "description": "Associates a tax rate with a shipping option to indicate that the shipping option is taxed in a certain way",
+        "description": "This represents the tax rates applied on a shipping option.",
         "type": "object",
         "required": [
           "created_at",
@@ -39113,22 +40201,24 @@
         ],
         "properties": {
           "shipping_option_id": {
-            "description": "The ID of the Shipping Option",
+            "description": "The ID of the shipping option.",
             "type": "string",
             "example": "so_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "shipping_option": {
-            "description": "Available if the relation `shipping_option` is expanded.",
+            "description": "The details of the shipping option.",
+            "x-expandable": "shipping_option",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingOption"
           },
           "rate_id": {
-            "description": "The ID of the Tax Rate",
+            "description": "The ID of the associated tax rate.",
             "type": "string",
             "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR"
           },
           "tax_rate": {
-            "description": "Available if the relation `tax_rate` is expanded.",
+            "description": "The details of the associated tax rate.",
+            "x-expandable": "tax_rate",
             "nullable": true,
             "$ref": "#/components/schemas/TaxRate"
           },
@@ -39148,6 +40238,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -39397,7 +40491,7 @@
       },
       "Store": {
         "title": "Store",
-        "description": "Holds settings for the Store, such as name, currencies, etc.",
+        "description": "A store holds the main settings of the commerce shop. By default, only one store is created and used within the Medusa backend. It holds settings related to the name of the store, available currencies, and more.",
         "type": "object",
         "required": [
           "created_at",
@@ -39432,13 +40526,15 @@
             }
           },
           "default_currency": {
-            "description": "Available if the relation `default_currency` is expanded.",
+            "description": "The details of the store's default currency.",
+            "x-expandable": "default_currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
           "currencies": {
-            "description": "The currencies that are enabled for the Store. Available if the relation `currencies` is expanded.",
+            "description": "The details of the enabled currencies in the store.",
             "type": "array",
+            "x-expandable": "currencies",
             "items": {
               "$ref": "#/components/schemas/Currency"
             }
@@ -39468,13 +40564,14 @@
             "example": null
           },
           "default_sales_channel_id": {
-            "description": "The sales channel ID the cart is associated with.",
+            "description": "The ID of the store's default sales channel.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "default_sales_channel": {
-            "description": "A sales channel object. Available if the relation `default_sales_channel` is expanded.",
+            "description": "The details of the store's default sales channel.",
+            "x-expandable": "default_sales_channel",
             "nullable": true,
             "$ref": "#/components/schemas/SalesChannel"
           },
@@ -39494,13 +40591,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "Swap": {
         "title": "Swap",
-        "description": "Swaps can be created when a Customer wishes to exchange Products that they have purchased to different Products. Swaps consist of a Return of previously purchased Products and a Fulfillment of new Products, the amount paid for the Products being returned will be used towards payment for the new Products. In the case where the amount paid for the the Products being returned exceed the amount to be paid for the new Products, a Refund will be issued for the difference.",
+        "description": "A swap can be created when a Customer wishes to exchange Products that they have purchased with different Products. It consists of a Return of previously purchased Products and a Fulfillment of new Products. It also includes information on any additional payment or refund required based on the difference between the exchanged products.",
         "type": "object",
         "required": [
           "allow_backorder",
@@ -39556,41 +40657,46 @@
             "example": "not_paid"
           },
           "order_id": {
-            "description": "The ID of the Order where the Line Items to be returned where purchased.",
+            "description": "The ID of the order that the swap belongs to.",
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the swap belongs to.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "additional_items": {
-            "description": "The new Line Items to ship to the Customer. Available if the relation `additional_items` is expanded.",
+            "description": "The details of the new products to send to the customer, represented as line items.",
             "type": "array",
+            "x-expandable": "additional_items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
           },
           "return_order": {
-            "description": "A return order object. The Return that is issued for the return part of the Swap. Available if the relation `return_order` is expanded.",
+            "description": "The details of the return that belongs to the swap, which holds the details on the items being returned.",
+            "x-expandable": "return_order",
             "nullable": true,
             "$ref": "#/components/schemas/Return"
           },
           "fulfillments": {
-            "description": "The Fulfillments used to send the new Line Items. Available if the relation `fulfillments` is expanded.",
+            "description": "The details of the fulfillments that are used to send the new items to the customer.",
+            "x-expandable": "fulfillments",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/Fulfillment"
             }
           },
           "payment": {
-            "description": "The Payment authorized when the Swap requires an additional amount to be charged from the Customer. Available if the relation `payment` is expanded.",
+            "description": "The details of the additional payment authorized by the customer when `difference_due` is positive.",
+            "x-expandable": "payment",
             "nullable": true,
             "$ref": "#/components/schemas/Payment"
           },
           "difference_due": {
-            "description": "The difference that is paid or refunded as a result of the Swap. May be negative when the amount paid for the returned items exceed the total of the new Products.",
+            "description": "The difference amount between the order’s original total and the new total imposed by the swap. If its value is negative, a refund must be issues to the customer. If it's positive, additional payment must be authorized by the customer. Otherwise, no payment processing is required.",
             "nullable": true,
             "type": "integer",
             "example": 0
@@ -39602,25 +40708,28 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "shipping_address": {
-            "description": "Available if the relation `shipping_address` is expanded.",
+            "description": "The details of the shipping address that the new items should be sent to.",
+            "x-expandable": "shipping_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "shipping_methods": {
-            "description": "The Shipping Methods used to fulfill the additional items purchased. Available if the relation `shipping_methods` is expanded.",
+            "description": "The details of the shipping methods used to fulfill the additional items purchased.",
             "type": "array",
+            "x-expandable": "shipping_methods",
             "items": {
               "$ref": "#/components/schemas/ShippingMethod"
             }
           },
           "cart_id": {
-            "description": "The id of the Cart that the Customer will use to confirm the Swap.",
+            "description": "The ID of the cart that the customer uses to complete the swap.",
             "nullable": true,
             "type": "string",
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the customer uses to complete the swap.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
@@ -39678,13 +40787,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "TaxLine": {
         "title": "Tax Line",
-        "description": "Line item that specifies an amount of tax to add to a line item.",
+        "description": "A tax line represents the taxes amount applied to a line item.",
         "type": "object",
         "required": [
           "code",
@@ -39733,13 +40846,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "TaxProvider": {
         "title": "Tax Provider",
-        "description": "The tax service used to calculate taxes",
+        "description": "A tax provider represents a tax service installed in the Medusa backend, either through a plugin or backend customizations. It holds the tax service's installation status.",
         "type": "object",
         "required": [
           "id",
@@ -39747,12 +40864,12 @@
         ],
         "properties": {
           "id": {
-            "description": "The id of the tax provider as given by the plugin.",
+            "description": "The ID of the tax provider as given by the tax service.",
             "type": "string",
             "example": "manual"
           },
           "is_installed": {
-            "description": "Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`.",
+            "description": "Whether the tax service is installed in the current version. If a tax service is no longer installed, the `is_installed` attribute is set to `false`.",
             "type": "boolean",
             "default": true
           }
@@ -39760,7 +40877,7 @@
       },
       "TaxRate": {
         "title": "Tax Rate",
-        "description": "A Tax Rate can be used to associate a certain rate to charge on products within a given Region",
+        "description": "A Tax Rate can be used to define a custom rate to charge on specified products, product types, and shipping options within a given region.",
         "type": "object",
         "required": [
           "code",
@@ -39796,32 +40913,36 @@
             "example": "Tax Example"
           },
           "region_id": {
-            "description": "The id of the Region that the rate belongs to",
+            "description": "The ID of the region that the rate belongs to.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region that the rate belongs to.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "products": {
-            "description": "The products that belong to this tax rate. Available if the relation `products` is expanded.",
+            "description": "The details of the products that belong to this tax rate.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
           },
           "product_types": {
-            "description": "The product types that belong to this tax rate. Available if the relation `product_types` is expanded.",
+            "description": "The details of the product types that belong to this tax rate.",
             "type": "array",
+            "x-expandable": "product_types",
             "items": {
               "$ref": "#/components/schemas/ProductType"
             }
           },
           "shipping_options": {
+            "description": "The details of the shipping options that belong to this tax rate.",
             "type": "array",
-            "description": "The shipping options that belong to this tax rate. Available if the relation `shipping_options` is expanded.",
+            "x-expandable": "shipping_options",
             "items": {
               "$ref": "#/components/schemas/ShippingOption"
             }
@@ -39857,13 +40978,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "TrackingLink": {
         "title": "Tracking Link",
-        "description": "Tracking Link holds information about tracking numbers for a Fulfillment. Tracking Links can optionally contain a URL that can be visited to see the status of the shipment.",
+        "description": "A tracking link holds information about tracking numbers for a Fulfillment. Tracking Links can optionally contain a URL that can be visited to see the status of the shipment. Typically, the tracking link is provided from the third-party service integrated through the used fulfillment provider.",
         "type": "object",
         "required": [
           "created_at",
@@ -39894,12 +41019,13 @@
             "format": "RH370168054CN"
           },
           "fulfillment_id": {
-            "description": "The id of the Fulfillment that the Tracking Link references.",
+            "description": "The ID of the fulfillment that the tracking link belongs to.",
             "type": "string",
             "example": "ful_01G8ZRTMQCA76TXNAT81KPJZRF"
           },
           "fulfillment": {
-            "description": "Available if the relation `fulfillment` is expanded.",
+            "description": "The details of the fulfillment that the tracking link belongs to.",
+            "x-expandable": "fulfillment",
             "nullable": true,
             "$ref": "#/components/schemas/Fulfillment"
           },
@@ -39934,6 +41060,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -39973,7 +41103,7 @@
       },
       "User": {
         "title": "User",
-        "description": "Represents a User who can manage store settings.",
+        "description": "A User is an administrator who can manage store settings and data.",
         "type": "object",
         "required": [
           "api_token",
@@ -39994,7 +41124,7 @@
             "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"
           },
           "role": {
-            "description": "The user's role",
+            "description": "The user's role. These roles don't provide any different privileges.",
             "type": "string",
             "enum": [
               "admin",
@@ -40048,36 +41178,53 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "VariantInventory": {
         "type": "object",
+        "required": [
+          "id",
+          "inventory",
+          "sales_channel_availability"
+        ],
         "properties": {
           "id": {
-            "description": "the id of the variant",
+            "description": "the ID of the variant",
             "type": "string"
           },
           "inventory": {
-            "description": "the stock location address ID",
+            "description": "The inventory details.",
             "$ref": "#/components/schemas/ResponseInventoryItem"
           },
           "sales_channel_availability": {
-            "type": "object",
-            "description": "An optional key-value map with additional details",
-            "properties": {
-              "channel_name": {
-                "description": "Sales channel name",
-                "type": "string"
-              },
-              "channel_id": {
-                "description": "Sales channel id",
-                "type": "string"
-              },
-              "available_quantity": {
-                "description": "Available quantity in sales channel",
-                "type": "number"
+            "type": "array",
+            "description": "An array of details about the variant's inventory availability in sales channels.",
+            "items": {
+              "type": "object",
+              "required": [
+                "channel_name",
+                "channel_id",
+                "available_quantity"
+              ],
+              "properties": {
+                "channel_name": {
+                  "description": "Sales channel's name",
+                  "type": "string"
+                },
+                "channel_id": {
+                  "description": "Sales channel's ID",
+                  "type": "string"
+                },
+                "available_quantity": {
+                  "description": "Available quantity in the sales channel",
+                  "type": "number"
+                }
               }
             }
           }
diff --git a/docs/api/admin/code_samples/JavaScript/admin_auth/delete.js b/docs/api/admin/code_samples/JavaScript/admin_auth/delete.js
index 5a92642a0a..b4a267c62e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_auth/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_auth/delete.js
@@ -1,4 +1,4 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-// must be previously logged in or use api token
+// must be previously logged in
 medusa.admin.auth.deleteSession()
diff --git a/docs/api/admin/code_samples/JavaScript/admin_auth/post.js b/docs/api/admin/code_samples/JavaScript/admin_auth/post.js
index 8bafacb359..a70d7adddf 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_auth/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_auth/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.admin.auth.createSession({
-  email: 'user@example.com',
-  password: 'supersecret'
+  email: "user@example.com",
+  password: "supersecret"
 })
 .then(({ user }) => {
   console.log(user.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_batch-jobs/get.js b/docs/api/admin/code_samples/JavaScript/admin_batch-jobs/get.js
index 92878e240b..ac5e34da3a 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_batch-jobs/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_batch-jobs/get.js
@@ -3,5 +3,5 @@ const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.batchJobs.list()
 .then(({ batch_jobs, limit, offset, count }) => {
-  console.log(batch_jobs.length);
-});
+  console.log(batch_jobs.length)
+})
diff --git a/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}/get.js
index 3fac0d4306..d6b6f39a38 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.batchJobs.retrieve(batch_job_id)
+medusa.admin.batchJobs.retrieve(batchJobId)
 .then(({ batch_job }) => {
   console.log(batch_job.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}_cancel/post.js b/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}_cancel/post.js
index 97186d0bde..026612e907 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}_cancel/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}_cancel/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.batchJobs.cancel(batch_job_id)
+medusa.admin.batchJobs.cancel(batchJobId)
 .then(({ batch_job }) => {
   console.log(batch_job.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}_confirm/post.js b/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}_confirm/post.js
index 2a31a7350a..58c5968ad1 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}_confirm/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_batch-jobs_{id}_confirm/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.batchJobs.confirm(batch_job_id)
+medusa.admin.batchJobs.confirm(batchJobId)
 .then(({ batch_job }) => {
   console.log(batch_job.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_collections/post.js b/docs/api/admin/code_samples/JavaScript/admin_collections/post.js
index 5503981ffd..76f9551100 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_collections/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_collections/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.collections.create({
-  title: 'New Collection'
+  title: "New Collection"
 })
 .then(({ collection }) => {
   console.log(collection.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/delete.js
index 93a989b833..0f99261cd8 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.collections.delete(collection_id)
+medusa.admin.collections.delete(collectionId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/get.js
index 00e2c3c299..ad52724dbc 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.collections.retrieve(collection_id)
+medusa.admin.collections.retrieve(collectionId)
 .then(({ collection }) => {
   console.log(collection.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/post.js
index fd28ad77e5..d9dd61f35f 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.collections.update(collection_id, {
-  title: 'New Collection'
+medusa.admin.collections.update(collectionId, {
+  title: "New Collection"
 })
 .then(({ collection }) => {
   console.log(collection.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_collections_{id}_products_batch/delete.js b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}_products_batch/delete.js
new file mode 100644
index 0000000000..e8ae833aa6
--- /dev/null
+++ b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}_products_batch/delete.js
@@ -0,0 +1,12 @@
+import Medusa from "@medusajs/medusa-js"
+const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+// must be previously logged in or use api token
+medusa.admin.collections.removeProducts(collectionId, {
+  product_ids: [
+    productId1,
+    productId2
+  ]
+})
+.then(({ id, object, removed_products }) => {
+  console.log(removed_products)
+})
diff --git a/docs/api/admin/code_samples/JavaScript/admin_collections_{id}_products_batch/post.js b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}_products_batch/post.js
new file mode 100644
index 0000000000..a85310862e
--- /dev/null
+++ b/docs/api/admin/code_samples/JavaScript/admin_collections_{id}_products_batch/post.js
@@ -0,0 +1,12 @@
+import Medusa from "@medusajs/medusa-js"
+const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+// must be previously logged in or use api token
+medusa.admin.collections.addProducts(collectionId, {
+  product_ids: [
+    productId1,
+    productId2
+  ]
+})
+.then(({ collection }) => {
+  console.log(collection.products)
+})
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customer-groups/post.js b/docs/api/admin/code_samples/JavaScript/admin_customer-groups/post.js
index 468594dcda..572f5f2ffe 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customer-groups/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customer-groups/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.customerGroups.create({
-  name: 'VIP'
+  name: "VIP"
 })
 .then(({ customer_group }) => {
   console.log(customer_group.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/delete.js
index 18628e749e..b10f7c1a98 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.customerGroups.delete(customer_group_id)
+medusa.admin.customerGroups.delete(customerGroupId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/get.js
index 95fb6f86a1..7c52894d54 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.customerGroups.retrieve(customer_group_id)
+medusa.admin.customerGroups.retrieve(customerGroupId)
 .then(({ customer_group }) => {
   console.log(customer_group.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/post.js
index a8bc37a750..257830d46b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.customerGroups.update(customer_group_id, {
-  name: 'VIP'
+medusa.admin.customerGroups.update(customerGroupId, {
+  name: "VIP"
 })
 .then(({ customer_group }) => {
   console.log(customer_group.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers/get.js b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers/get.js
index d4633c2e36..580f27ccce 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.customerGroups.listCustomers(customer_group_id)
+medusa.admin.customerGroups.listCustomers(customerGroupId)
 .then(({ customers }) => {
   console.log(customers.length);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers_batch/delete.js b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers_batch/delete.js
index 297e4d9ea6..524376cf93 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers_batch/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers_batch/delete.js
@@ -1,10 +1,10 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.customerGroups.removeCustomers(customer_group_id, {
+medusa.admin.customerGroups.removeCustomers(customerGroupId, {
   customer_ids: [
     {
-      id: customer_id
+      id: customerId
     }
   ]
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers_batch/post.js b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers_batch/post.js
index ff786e1b81..703b21786e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers_batch/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customer-groups_{id}_customers_batch/post.js
@@ -1,10 +1,10 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.customerGroups.addCustomers(customer_group_id, {
+medusa.admin.customerGroups.addCustomers(customerGroupId, {
   customer_ids: [
     {
-      id: customer_id
+      id: customerId
     }
   ]
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customers/post.js b/docs/api/admin/code_samples/JavaScript/admin_customers/post.js
index 87eb0ccd89..90e7bf9641 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customers/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customers/post.js
@@ -2,10 +2,10 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.customers.create({
-  email: 'user@example.com',
-  first_name: 'Caterina',
-  last_name: 'Yost',
-  password: 'supersecret'
+  email: "user@example.com",
+  first_name: "Caterina",
+  last_name: "Yost",
+  password: "supersecret"
 })
 .then(({ customer }) => {
   console.log(customer.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customers_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_customers_{id}/get.js
index d50a1c4170..7f459a95d5 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customers_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customers_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.customers.retrieve(customer_id)
+medusa.admin.customers.retrieve(customerId)
 .then(({ customer }) => {
   console.log(customer.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_customers_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_customers_{id}/post.js
index 64e0ac1bb8..a9d5f0964d 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_customers_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_customers_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.customers.update(customer_id, {
-  first_name: 'Dolly'
+medusa.admin.customers.update(customerId, {
+  first_name: "Dolly"
 })
 .then(({ customer }) => {
   console.log(customer.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts/post.js b/docs/api/admin/code_samples/JavaScript/admin_discounts/post.js
index 873666ba15..a5021231b0 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts/post.js
@@ -3,7 +3,7 @@ import { AllocationType, DiscountRuleType } from "@medusajs/medusa"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.discounts.create({
-  code: 'TEST',
+  code: "TEST",
   rule: {
     type: DiscountRuleType.FIXED,
     value: 10,
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions/post.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions/post.js
index 25723b11ef..66e5f47c1b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 import { DiscountConditionOperator } from "@medusajs/medusa"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.createCondition(discount_id, {
+medusa.admin.discounts.createCondition(discountId, {
   operator: DiscountConditionOperator.IN
 })
 .then(({ discount }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/delete.js
index a5998ab76b..71e35a0d4e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.deleteCondition(discount_id, condition_id)
+medusa.admin.discounts.deleteCondition(discountId, conditionId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/get.js
index 3ff5d0ded9..16a9e5697b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.getCondition(discount_id, condition_id)
+medusa.admin.discounts.getCondition(discountId, conditionId)
 .then(({ discount_condition }) => {
   console.log(discount_condition.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/post.js
index 714dfce145..437d5e76cb 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}/post.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.updateCondition(discount_id, condition_id, {
+medusa.admin.discounts.updateCondition(discountId, conditionId, {
   products: [
-    product_id
+    productId
   ]
 })
 .then(({ discount }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}_batch/delete.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}_batch/delete.js
index e2426d3522..4e8b43f008 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}_batch/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}_batch/delete.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.deleteConditionResourceBatch(discount_id, condition_id, {
-  resources: [{ id: item_id }]
+medusa.admin.discounts.deleteConditionResourceBatch(discountId, conditionId, {
+  resources: [{ id: itemId }]
 })
 .then(({ discount }) => {
   console.log(discount.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}_batch/post.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}_batch/post.js
index 573fdcb402..a8ae70ae8d 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}_batch/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{discount_id}_conditions_{condition_id}_batch/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.addConditionResourceBatch(discount_id, condition_id, {
-  resources: [{ id: item_id }]
+medusa.admin.discounts.addConditionResourceBatch(discountId, conditionId, {
+  resources: [{ id: itemId }]
 })
 .then(({ discount }) => {
   console.log(discount.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/delete.js
index 4e278133f4..cfe8b520f4 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.delete(discount_id)
+medusa.admin.discounts.delete(discountId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/get.js
index e594088e8e..098ff1ed4b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.retrieve(discount_id)
+medusa.admin.discounts.retrieve(discountId)
 .then(({ discount }) => {
   console.log(discount.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/post.js
index 1309e5cae1..15cd7af923 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.update(discount_id, {
-  code: 'TEST'
+medusa.admin.discounts.update(discountId, {
+  code: "TEST"
 })
 .then(({ discount }) => {
   console.log(discount.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_dynamic-codes/post.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_dynamic-codes/post.js
index f49260dbcd..236bcdba9a 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_dynamic-codes/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_dynamic-codes/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.createDynamicCode(discount_id, {
-  code: 'TEST',
+medusa.admin.discounts.createDynamicCode(discountId, {
+  code: "TEST",
   usage_limit: 1
 })
 .then(({ discount }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_dynamic-codes_{code}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_dynamic-codes_{code}/delete.js
index d73a1846df..0443c6185a 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_dynamic-codes_{code}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_dynamic-codes_{code}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.deleteDynamicCode(discount_id, code)
+medusa.admin.discounts.deleteDynamicCode(discountId, code)
 .then(({ discount }) => {
   console.log(discount.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_regions_{region_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_regions_{region_id}/delete.js
index 2012145590..bdc32a588e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_regions_{region_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_regions_{region_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.removeRegion(discount_id, region_id)
+medusa.admin.discounts.removeRegion(discountId, regionId)
 .then(({ discount }) => {
   console.log(discount.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_regions_{region_id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_regions_{region_id}/post.js
index 319f32d0e4..7079d51ac9 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_regions_{region_id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_discounts_{id}_regions_{region_id}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.discounts.addRegion(discount_id, region_id)
+medusa.admin.discounts.addRegion(discountId, regionId)
 .then(({ discount }) => {
   console.log(discount.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_draft-orders/post.js b/docs/api/admin/code_samples/JavaScript/admin_draft-orders/post.js
index a4ab1be967..016b974d3f 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_draft-orders/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_draft-orders/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.draftOrders.create({
-  email: 'user@example.com',
+  email: "user@example.com",
   region_id,
   items: [
     {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/delete.js
index 40d50928e6..b0d0566804 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.draftOrders.delete(draft_order_id)
+medusa.admin.draftOrders.delete(draftOrderId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/get.js
index 90f6c1771a..089bb0b91c 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.draftOrders.retrieve(draft_order_id)
+medusa.admin.draftOrders.retrieve(draftOrderId)
 .then(({ draft_order }) => {
   console.log(draft_order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/post.js
index 1afbe020cd..d24a678973 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.draftOrders.update(draft_order_id, {
+medusa.admin.draftOrders.update(draftOrderId, {
   email: "user@example.com"
 })
 .then(({ draft_order }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items/post.js b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items/post.js
index f3bd9ba5c4..ddb3f2a63c 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.draftOrders.addLineItem(draft_order_id, {
+medusa.admin.draftOrders.addLineItem(draftOrderId, {
   quantity: 1
 })
 .then(({ draft_order }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items_{line_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items_{line_id}/delete.js
index bc1cc12b59..0c8c07e725 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items_{line_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items_{line_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.draftOrders.removeLineItem(draft_order_id, item_id)
+medusa.admin.draftOrders.removeLineItem(draftOrderId, itemId)
 .then(({ draft_order }) => {
   console.log(draft_order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items_{line_id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items_{line_id}/post.js
index 8e8089d04f..4a4cd16b1a 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items_{line_id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_line-items_{line_id}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.draftOrders.updateLineItem(draft_order_id, line_id, {
+medusa.admin.draftOrders.updateLineItem(draftOrderId, lineId, {
   quantity: 1
 })
 .then(({ draft_order }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_pay/post.js b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_pay/post.js
index e7edfa2513..fbeb008678 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_pay/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_draft-orders_{id}_pay/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.draftOrders.markPaid(draft_order_id)
+medusa.admin.draftOrders.markPaid(draftOrderId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/delete.js
index 02a810bf19..2b628081b4 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.giftCards.delete(gift_card_id)
+medusa.admin.giftCards.delete(giftCardId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/get.js
index bdded76f95..1b65b58c1d 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.giftCards.retrieve(gift_card_id)
+medusa.admin.giftCards.retrieve(giftCardId)
 .then(({ gift_card }) => {
   console.log(gift_card.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/post.js
index 6db8476684..dbae5ee185 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_gift-cards_{id}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.giftCards.update(gift_card_id, {
+medusa.admin.giftCards.update(giftCardId, {
   region_id
 })
 .then(({ gift_card }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_inventory-items/post.js b/docs/api/admin/code_samples/JavaScript/admin_inventory-items/post.js
index 8d669627e9..e2abbc4bf7 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_inventory-items/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_inventory-items/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.inventoryItems.create({
-  variant_id: 'variant_123',
+  variant_id: "variant_123",
 })
 .then(({ inventory_item }) => {
   console.log(inventory_item.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_inventory-items_{id}_location-levels/post.js b/docs/api/admin/code_samples/JavaScript/admin_inventory-items_{id}_location-levels/post.js
index d9f6a41693..3af95d2f1e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_inventory-items_{id}_location-levels/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_inventory-items_{id}_location-levels/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.inventoryItems.createLocationLevel(inventoryItemId, {
-  location_id: 'sloc_123',
+  location_id: "sloc_123",
   stocked_quantity: 10,
 })
 .then(({ inventory_item }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_invites_accept/post.js b/docs/api/admin/code_samples/JavaScript/admin_invites_accept/post.js
index bdb122722b..b403e85223 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_invites_accept/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_invites_accept/post.js
@@ -4,9 +4,9 @@ const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.admin.invites.accept({
   token,
   user: {
-    first_name: 'Brigitte',
-    last_name: 'Collier',
-    password: 'supersecret'
+    first_name: "Brigitte",
+    last_name: "Collier",
+    password: "supersecret"
   }
 })
 .then(() => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_invites_{invite_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_invites_{invite_id}/delete.js
index c743607bfc..4f542129ab 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_invites_{invite_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_invites_{invite_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.invites.delete(invite_id)
+medusa.admin.invites.delete(inviteId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_invites_{invite_id}_resend/post.js b/docs/api/admin/code_samples/JavaScript/admin_invites_{invite_id}_resend/post.js
index 2c8a380494..c45c6fdb91 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_invites_{invite_id}_resend/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_invites_{invite_id}_resend/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.invites.resend(invite_id)
+medusa.admin.invites.resend(inviteId)
 .then(() => {
   // successful
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_notes/post.js b/docs/api/admin/code_samples/JavaScript/admin_notes/post.js
index 0681f2e88c..aa71e9d303 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_notes/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_notes/post.js
@@ -3,8 +3,8 @@ const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.notes.create({
   resource_id,
-  resource_type: 'order',
-  value: 'We delivered this order'
+  resource_type: "order",
+  value: "We delivered this order"
 })
 .then(({ note }) => {
   console.log(note.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/delete.js
index 5ae7c9f20b..29ae5c215c 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.notes.delete(note_id)
+medusa.admin.notes.delete(noteId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/get.js
index a47a3073ff..38333c2acd 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.notes.retrieve(note_id)
+medusa.admin.notes.retrieve(noteId)
 .then(({ note }) => {
   console.log(note.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/post.js
index d58b21ca01..02b5278dde 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_notes_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.notes.update(note_id, {
- value: 'We delivered this order'
+medusa.admin.notes.update(noteId, {
+ value: "We delivered this order"
 })
 .then(({ note }) => {
   console.log(note.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_notifications_{id}_resend/post.js b/docs/api/admin/code_samples/JavaScript/admin_notifications_{id}_resend/post.js
index 5021dfd6cb..b517d33d81 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_notifications_{id}_resend/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_notifications_{id}_resend/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.notifications.resend(notification_id)
+medusa.admin.notifications.resend(notificationId)
 .then(({ notification }) => {
   console.log(notification.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits/post.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits/post.js
index acbbf8896a..aa94738824 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.create({ order_id })
+medusa.admin.orderEdits.create({ orderId })
   .then(({ order_edit }) => {
     console.log(order_edit.id)
   })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}/delete.js
index 32998e028c..b202ffbe39 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.delete(order_edit_id)
+medusa.admin.orderEdits.delete(orderEditId)
   .then(({ id, object, deleted }) => {
     console.log(id)
   })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}/post.js
index e7d202f12d..c187499c80 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.update(order_edit_id, {
+medusa.admin.orderEdits.update(orderEditId, {
   internal_note: "internal reason XY"
 })
   .then(({ order_edit }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_cancel/post.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_cancel/post.js
index 780aa48167..5d412ff6bb 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_cancel/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_cancel/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.cancel(order_edit_id)
+medusa.admin.orderEdits.cancel(orderEditId)
   .then(({ order_edit }) => {
     console.log(order_edit.id)
   })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_changes_{change_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_changes_{change_id}/delete.js
index f0f9145218..1e99f36203 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_changes_{change_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_changes_{change_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.deleteItemChange(order_edit_id, item_change_id)
+medusa.admin.orderEdits.deleteItemChange(orderEdit_id, itemChangeId)
   .then(({ id, object, deleted }) => {
     console.log(id)
   })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_confirm/post.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_confirm/post.js
index ec39a07a6c..c20d1783ca 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_confirm/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_confirm/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.confirm(order_edit_id)
+medusa.admin.orderEdits.confirm(orderEditId)
   .then(({ order_edit }) => {
     console.log(order_edit.id)
   })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items/post.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items/post.js
index 599fe4aa64..63f12fe826 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.addLineItem(order_edit_id, {
+medusa.admin.orderEdits.addLineItem(orderEditId, {
   variant_id,
   quantity
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items_{item_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items_{item_id}/delete.js
index 2c8990247c..40c3ebb3d1 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items_{item_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items_{item_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.removeLineItem(order_edit_id, line_item_id)
+medusa.admin.orderEdits.removeLineItem(orderEditId, lineItemId)
   .then(({ order_edit }) => {
     console.log(order_edit.id)
   })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items_{item_id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items_{item_id}/post.js
index f4ba4375d8..725fb29075 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items_{item_id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_items_{item_id}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.updateLineItem(order_edit_id, line_item_id, {
+medusa.admin.orderEdits.updateLineItem(orderEditId, lineItemId, {
     quantity: 5
   })
   .then(({ order_edit }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_request/post.js b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_request/post.js
index 0922f8c850..fb04ce9f44 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_request/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_order-edits_{id}_request/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orderEdits.requestConfirmation(order_edit_id)
+medusa.admin.orderEdits.requestConfirmation(orderEditId)
   .then({ order_edit }) => {
     console.log(order_edit.id)
   })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}/get.js
index 820d03223b..f9ec05be45 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.retrieve(order_id)
+medusa.admin.orders.retrieve(orderId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}/post.js
index 79c1fda291..e62b225cb3 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.update(order_id, {
-  email: 'user@example.com'
+medusa.admin.orders.update(orderId, {
+  email: "user@example.com"
 })
 .then(({ order }) => {
   console.log(order.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_archive/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_archive/post.js
index a6ed72f420..f97eeca032 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_archive/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_archive/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.archive(order_id)
+medusa.admin.orders.archive(orderId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_cancel/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_cancel/post.js
index 796f24908c..2b59256d2f 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_cancel/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_cancel/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.cancel(order_id)
+medusa.admin.orders.cancel(orderId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_capture/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_capture/post.js
index 8ed73415f0..4b40b7191b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_capture/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_capture/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.capturePayment(order_id)
+medusa.admin.orders.capturePayment(orderId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims/post.js
index 9a83e45eb8..a124a24258 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.createClaim(order_id, {
+medusa.admin.orders.createClaim(orderId, {
   type: 'refund',
   claim_items: [
     {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}/post.js
index 5a802ab97d..71934dfdac 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.updateClaim(order_id, claim_id, {
+medusa.admin.orders.updateClaim(orderId, claimId, {
   no_notification: true
 })
 .then(({ order }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_cancel/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_cancel/post.js
index c09eb3d6a9..3a30076d5d 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_cancel/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_cancel/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.cancelClaim(order_id, claim_id)
+medusa.admin.orders.cancelClaim(orderId, claimId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_fulfillments/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_fulfillments/post.js
index 69a52c88dd..2dd691171e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_fulfillments/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_fulfillments/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.fulfillClaim(order_id, claim_id, {
+medusa.admin.orders.fulfillClaim(orderId, claimId, {
 })
 .then(({ order }) => {
   console.log(order.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel/post.js
index c0e77a671d..5329b1a2b4 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.cancelClaimFulfillment(order_id, claim_id, fulfillment_id)
+medusa.admin.orders.cancelClaimFulfillment(orderId, claimId, fulfillmentId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_shipments/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_shipments/post.js
index 00dd12d1ee..2dd9beb63d 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_shipments/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_claims_{claim_id}_shipments/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.createClaimShipment(order_id, claim_id, {
+medusa.admin.orders.createClaimShipment(orderId, claimId, {
   fulfillment_id
 })
 .then(({ order }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_complete/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_complete/post.js
index bfdb7d62c1..f6331ddaa9 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_complete/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_complete/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.complete(order_id)
+medusa.admin.orders.complete(orderId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_fulfillment/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_fulfillment/post.js
index 2646960d9b..8c6e3e8c7c 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_fulfillment/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_fulfillment/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.createFulfillment(order_id, {
+medusa.admin.orders.createFulfillment(orderId, {
   items: [
     {
       item_id,
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel/post.js
index 470a79c339..e1bd5b619e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.cancelFulfillment(order_id, fulfillment_id)
+medusa.admin.orders.cancelFulfillment(orderId, fulfillmentId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_refund/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_refund/post.js
index 9cc6f4d469..37dd32dded 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_refund/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_refund/post.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.refundPayment(order_id, {
+medusa.admin.orders.refundPayment(orderId, {
   amount: 1000,
-  reason: 'Do not like it'
+  reason: "Do not like it"
 })
 .then(({ order }) => {
   console.log(order.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_return/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_return/post.js
index 00fbde0ced..ac431f949b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_return/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_return/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.requestReturn(order_id, {
+medusa.admin.orders.requestReturn(orderId, {
   items: [
     {
       item_id,
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_shipping-methods/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_shipping-methods/post.js
index ebe3946ad6..3f4bd0638e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_shipping-methods/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_shipping-methods/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.addShippingMethod(order_id, {
+medusa.admin.orders.addShippingMethod(orderId, {
   price: 1000,
   option_id
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps/post.js
index 7c0628e794..3472f9f4dd 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.createSwap(order_id, {
+medusa.admin.orders.createSwap(orderId, {
   return_items: [
     {
       item_id,
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_cancel/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_cancel/post.js
index 78719f5780..c7210178f1 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_cancel/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_cancel/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.cancelSwap(order_id, swap_id)
+medusa.admin.orders.cancelSwap(orderId, swapId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_fulfillments/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_fulfillments/post.js
index e68da19f99..e367eab89c 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_fulfillments/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_fulfillments/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.fulfillSwap(order_id, swap_id, {
+medusa.admin.orders.fulfillSwap(orderId, swapId, {
 
 })
 .then(({ order }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel/post.js
index a34077987c..4cbe754ff6 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.cancelSwapFulfillment(order_id, swap_id, fulfillment_id)
+medusa.admin.orders.cancelSwapFulfillment(orderId, swapId, fulfillmentId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_process-payment/post.js b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_process-payment/post.js
index e8d1c0b94e..92b82910c2 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_process-payment/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_orders_{id}_swaps_{swap_id}_process-payment/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.orders.processSwapPayment(order_id, swap_id)
+medusa.admin.orders.processSwapPayment(orderId, swapId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}/delete.js
index ea5b7cb00a..e581579649 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.paymentCollections.delete(payment_collection_id)
+medusa.admin.paymentCollections.delete(paymentCollectionId)
   .then(({ id, object, deleted }) => {
     console.log(id)
   })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}/post.js
index d91153b57c..d7309d8263 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.paymentCollections.update(payment_collection_id, {
-  description: "Description of payCol"
+medusa.admin.paymentCollections.update(paymentCollectionId, {
+  description
 })
   .then(({ payment_collection }) => {
     console.log(payment_collection.id)
diff --git a/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}_authorize/post.js b/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}_authorize/post.js
index e485af9bb7..b4a832aa37 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}_authorize/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_payment-collections_{id}_authorize/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.paymentCollections.markAsAuthorized(payment_collection_id)
+medusa.admin.paymentCollections.markAsAuthorized(paymentCollectionId)
   .then(({ payment_collection }) => {
     console.log(payment_collection.id)
   })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_payments_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_payments_{id}/get.js
index cad6523dcc..798a30f01f 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_payments_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_payments_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.payments.retrieve(payment_id)
+medusa.admin.payments.retrieve(paymentId)
 .then(({ payment }) => {
   console.log(payment.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_payments_{id}_capture/post.js b/docs/api/admin/code_samples/JavaScript/admin_payments_{id}_capture/post.js
index 1fa9f7aac8..2329cd773e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_payments_{id}_capture/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_payments_{id}_capture/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.payments.capturePayment(payment_id)
+medusa.admin.payments.capturePayment(paymentId)
 .then(({ payment }) => {
   console.log(payment.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_payments_{id}_refund/post.js b/docs/api/admin/code_samples/JavaScript/admin_payments_{id}_refund/post.js
index ead604e865..3fbf863b8e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_payments_{id}_refund/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_payments_{id}_refund/post.js
@@ -1,10 +1,10 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.payments.refundPayment(payment_id, {
+medusa.admin.payments.refundPayment(paymentId, {
   amount: 1000,
-  reason: 'return',
-  note: 'Do not like it',
+  reason: "return",
+  note: "Do not like it",
 })
 .then(({ payment }) => {
   console.log(payment.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_price-lists/post.js b/docs/api/admin/code_samples/JavaScript/admin_price-lists/post.js
index e287f8c8bd..fe68beaa24 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_price-lists/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_price-lists/post.js
@@ -3,14 +3,14 @@ import { PriceListType } from "@medusajs/medusa"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.priceLists.create({
-  name: 'New Price List',
-  description: 'A new price list',
+  name: "New Price List",
+  description: "A new price list",
   type: PriceListType.SALE,
   prices: [
     {
       amount: 1000,
       variant_id,
-      currency_code: 'eur'
+      currency_code: "eur"
     }
   ]
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/delete.js
index 3978dc3ac8..4570e41d2d 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.priceLists.delete(price_list_id)
+medusa.admin.priceLists.delete(priceListId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/get.js
index d2f3854713..d80c9d18f6 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.priceLists.retrieve(price_list_id)
+medusa.admin.priceLists.retrieve(priceListId)
 .then(({ price_list }) => {
   console.log(price_list.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/post.js
index 8596feb949..3fc44ebe9e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.priceLists.update(price_list_id, {
-  name: 'New Price List'
+medusa.admin.priceLists.update(priceListId, {
+  name: "New Price List"
 })
 .then(({ price_list }) => {
   console.log(price_list.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_prices_batch/delete.js b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_prices_batch/delete.js
index 1a6f952a6d..1584a969d9 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_prices_batch/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_prices_batch/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.priceLists.deletePrices(price_list_id, {
+medusa.admin.priceLists.deletePrices(priceListId, {
   price_ids: [
     price_id
   ]
diff --git a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_prices_batch/post.js b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_prices_batch/post.js
index d2d0b7d737..e4905c86ac 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_prices_batch/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_prices_batch/post.js
@@ -1,12 +1,12 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.priceLists.addPrices(price_list_id, {
+medusa.admin.priceLists.addPrices(priceListId, {
   prices: [
     {
       amount: 1000,
       variant_id,
-      currency_code: 'eur'
+      currency_code: "eur"
     }
   ]
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_products/get.js b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_products/get.js
index a763156022..7b5a1183e5 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_products/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_products/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.priceLists.listProducts(price_list_id)
+medusa.admin.priceLists.listProducts(priceListId)
 .then(({ products, limit, offset, count }) => {
   console.log(products.length);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_products_{product_id}_prices/delete.js b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_products_{product_id}_prices/delete.js
index dd16ac6335..0362af01c5 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_products_{product_id}_prices/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_products_{product_id}_prices/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.priceLists.deleteProductPrices(price_list_id, product_id)
+medusa.admin.priceLists.deleteProductPrices(priceListId, productId)
 .then(({ ids, object, deleted }) => {
   console.log(ids.length);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_variants_{variant_id}_prices/delete.js b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_variants_{variant_id}_prices/delete.js
index fb0087237e..b8732da339 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_variants_{variant_id}_prices/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_price-lists_{id}_variants_{variant_id}_prices/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.priceLists.deleteVariantPrices(price_list_id, variant_id)
+medusa.admin.priceLists.deleteVariantPrices(priceListId, variantId)
 .then(({ ids, object, deleted }) => {
   console.log(ids);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products/post.js b/docs/api/admin/code_samples/JavaScript/admin_products/post.js
index d5a06fc7e4..648c90f2bb 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.products.create({
-  title: 'Shirt',
+  title: "Shirt",
   is_giftcard: false,
   discountable: true
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}/delete.js
index a83476d557..cfb5326ac4 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.delete(product_id)
+medusa.admin.products.delete(productId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}/get.js
index 2cab9835ab..9fc7a2510f 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.retrieve(product_id)
+medusa.admin.products.retrieve(productId)
 .then(({ product }) => {
   console.log(product.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}/post.js
index 0fb28bc7e2..c730be10ca 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}/post.js
@@ -1,9 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.update(product_id, {
-  title: 'Shirt',
-  images: []
+medusa.admin.products.update(productId, {
+  title: "Shirt",
 })
 .then(({ product }) => {
   console.log(product.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_metadata/post.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_metadata/post.js
index fc56b0eda6..fffafe946e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_metadata/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_metadata/post.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.setMetadata(product_id, {
-key: 'test',
-  value: 'true'
+medusa.admin.products.setMetadata(productId, {
+  key: "test",
+  value: "true"
 })
 .then(({ product }) => {
   console.log(product.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options/post.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options/post.js
index ef257a4325..f07b707d5b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.addOption(product_id, {
-  title: 'Size'
+medusa.admin.products.addOption(productId, {
+  title: "Size"
 })
 .then(({ product }) => {
   console.log(product.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/delete.js
index 17e73e72e3..0814e498c6 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.deleteOption(product_id, option_id)
+medusa.admin.products.deleteOption(productId, optionId)
 .then(({ option_id, object, deleted, product }) => {
   console.log(product.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/post.js
index 414f43e789..954401f08d 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_options_{option_id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.updateOption(product_id, option_id, {
-  title: 'Size'
+medusa.admin.products.updateOption(productId, optionId, {
+  title: "Size"
 })
 .then(({ product }) => {
   console.log(product.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants/post.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants/post.js
index 36c1fd4111..927885245a 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.createVariant(product_id, {
-  title: 'Color',
+medusa.admin.products.createVariant(productId, {
+  title: "Color",
   prices: [
     {
       amount: 1000,
@@ -12,11 +12,11 @@ medusa.admin.products.createVariant(product_id, {
   options: [
     {
       option_id,
-      value: 'S'
+      value: "S"
     }
   ],
   inventory_quantity: 100
 })
 .then(({ product }) => {
   console.log(product.id);
-});
+})
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/delete.js
index 2e163a681a..ec99bbc7d0 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.deleteVariant(product_id, variant_id)
+medusa.admin.products.deleteVariant(productId, variantId)
 .then(({ variant_id, object, deleted, product }) => {
   console.log(product.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/post.js
index d7a58d1d2c..5043e8ffaa 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_products_{id}_variants_{variant_id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.products.updateVariant(product_id, variant_id, {
-  title: 'Color',
+medusa.admin.products.updateVariant(productId, variantId, {
+  title: "Color",
   prices: [
     {
       amount: 1000,
@@ -12,7 +12,7 @@ medusa.admin.products.updateVariant(product_id, variant_id, {
   options: [
     {
       option_id,
-      value: 'S'
+      value: "S"
     }
   ],
   inventory_quantity: 100
diff --git a/docs/api/admin/code_samples/JavaScript/admin_publishable-api-keys_{id}_sales-channels_batch/delete.js b/docs/api/admin/code_samples/JavaScript/admin_publishable-api-keys_{id}_sales-channels_batch/delete.js
index e4e422b731..7d0dbee55c 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_publishable-api-keys_{id}_sales-channels_batch/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_publishable-api-keys_{id}_sales-channels_batch/delete.js
@@ -4,7 +4,7 @@ const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.admin.publishableApiKeys.deleteSalesChannelsBatch(publishableApiKeyId, {
   sales_channel_ids: [
     {
-      id: channel_id
+      id: channelId
     }
   ]
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_publishable-api-keys_{id}_sales-channels_batch/post.js b/docs/api/admin/code_samples/JavaScript/admin_publishable-api-keys_{id}_sales-channels_batch/post.js
index 1c882fcc81..94e1d0cfad 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_publishable-api-keys_{id}_sales-channels_batch/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_publishable-api-keys_{id}_sales-channels_batch/post.js
@@ -4,7 +4,7 @@ const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.admin.publishableApiKeys.addSalesChannelsBatch(publishableApiKeyId, {
   sales_channel_ids: [
     {
-      id: channel_id
+      id: channelId
     }
   ]
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions/post.js b/docs/api/admin/code_samples/JavaScript/admin_regions/post.js
index df32a757a2..361f3f7cfe 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions/post.js
@@ -2,17 +2,17 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.regions.create({
-  name: 'Europe',
-  currency_code: 'eur',
+  name: "Europe",
+  currency_code: "eur",
   tax_rate: 0,
   payment_providers: [
-    'manual'
+    "manual"
   ],
   fulfillment_providers: [
-    'manual'
+    "manual"
   ],
   countries: [
-    'DK'
+    "DK"
   ]
 })
 .then(({ region }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/delete.js
index 652e8da1bd..e3cc3dbb0c 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.delete(region_id)
+medusa.admin.regions.delete(regionId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/get.js
index e16dcae311..92a96f0b49 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.retrieve(region_id)
+medusa.admin.regions.retrieve(regionId)
 .then(({ region }) => {
   console.log(region.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/post.js
index e5a408f08c..4315dc3b49 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.update(region_id, {
-  name: 'Europe'
+medusa.admin.regions.update(regionId, {
+  name: "Europe"
 })
 .then(({ region }) => {
   console.log(region.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_countries/post.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_countries/post.js
index 714a9839fb..1e38a75e3c 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_countries/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_countries/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.addCountry(region_id, {
-  country_code: 'dk'
+medusa.admin.regions.addCountry(regionId, {
+  country_code: "dk"
 })
 .then(({ region }) => {
   console.log(region.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_countries_{country_code}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_countries_{country_code}/delete.js
index eb25bae15b..0c5244602a 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_countries_{country_code}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_countries_{country_code}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.deleteCountry(region_id, 'dk')
+medusa.admin.regions.deleteCountry(regionId, "dk")
 .then(({ region }) => {
   console.log(region.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-options/get.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-options/get.js
index 16af32b21d..93e49b798a 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-options/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-options/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.retrieveFulfillmentOptions(region_id)
+medusa.admin.regions.retrieveFulfillmentOptions(regionId)
 .then(({ fulfillment_options }) => {
   console.log(fulfillment_options.length);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-providers/post.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-providers/post.js
index 525df6f5f1..6b82817f8b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-providers/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-providers/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.addFulfillmentProvider(region_id, {
-  provider_id: 'manual'
+medusa.admin.regions.addFulfillmentProvider(regionId, {
+  provider_id: "manual"
 })
 .then(({ region }) => {
   console.log(region.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-providers_{provider_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-providers_{provider_id}/delete.js
index cc4175c3b8..3e8ed63fcb 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-providers_{provider_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_fulfillment-providers_{provider_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.deleteFulfillmentProvider(region_id, 'manual')
+medusa.admin.regions.deleteFulfillmentProvider(regionId, "manual")
 .then(({ region }) => {
   console.log(region.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_payment-providers/post.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_payment-providers/post.js
index 3eebefc244..875db17be0 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_payment-providers/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_payment-providers/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.addPaymentProvider(region_id, {
-  provider_id: 'manual'
+medusa.admin.regions.addPaymentProvider(regionId, {
+  provider_id: "manual"
 })
 .then(({ region }) => {
   console.log(region.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_payment-providers_{provider_id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_payment-providers_{provider_id}/delete.js
index b6d628bdb0..e5d6380cce 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_payment-providers_{provider_id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_regions_{id}_payment-providers_{provider_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.regions.deletePaymentProvider(region_id, 'manual')
+medusa.admin.regions.deletePaymentProvider(regionId, "manual")
 .then(({ region }) => {
   console.log(region.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_reservations/post.js b/docs/api/admin/code_samples/JavaScript/admin_reservations/post.js
index 0b4c16132f..ca31036994 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_reservations/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_reservations/post.js
@@ -2,9 +2,9 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.reservations.create({
-  line_item_id: 'item_123',
-  location_id: 'loc_123',
-  inventory_item_id: 'iitem_123',
+  line_item_id: "item_123",
+  location_id: "loc_123",
+  inventory_item_id: "iitem_123",
   quantity: 1
 })
 .then(({ reservation }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_return-reasons/post.js b/docs/api/admin/code_samples/JavaScript/admin_return-reasons/post.js
index 49fe4c5b3f..42f3c4ca35 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_return-reasons/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_return-reasons/post.js
@@ -2,8 +2,8 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.returnReasons.create({
-  label: 'Damaged',
-  value: 'damaged'
+  label: "Damaged",
+  value: "damaged"
 })
 .then(({ return_reason }) => {
   console.log(return_reason.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/delete.js
index 33ad40e0d5..62e63a2573 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.returnReasons.delete(return_reason_id)
+medusa.admin.returnReasons.delete(returnReasonId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/get.js
index c1ee97d4c0..b2ee78d7d0 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.returnReasons.retrieve(return_reason_id)
+medusa.admin.returnReasons.retrieve(returnReasonId)
 .then(({ return_reason }) => {
   console.log(return_reason.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/post.js
index 2e8dd0d369..987e8cfb2e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_return-reasons_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.returnReasons.update(return_reason_id, {
-  label: 'Damaged'
+medusa.admin.returnReasons.update(returnReasonId, {
+  label: "Damaged"
 })
 .then(({ return_reason }) => {
   console.log(return_reason.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_returns_{id}_cancel/post.js b/docs/api/admin/code_samples/JavaScript/admin_returns_{id}_cancel/post.js
index 1966cc48bb..a692e34c71 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_returns_{id}_cancel/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_returns_{id}_cancel/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.returns.cancel(return_id)
+medusa.admin.returns.cancel(returnId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_returns_{id}_receive/post.js b/docs/api/admin/code_samples/JavaScript/admin_returns_{id}_receive/post.js
index 8d05dfee10..aeff7eb923 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_returns_{id}_receive/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_returns_{id}_receive/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.returns.receive(return_id, {
+medusa.admin.returns.receive(returnId, {
   items: [
     {
       item_id,
diff --git a/docs/api/admin/code_samples/JavaScript/admin_sales-channels/post.js b/docs/api/admin/code_samples/JavaScript/admin_sales-channels/post.js
index 7272e7ebd3..7f955e298b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_sales-channels/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_sales-channels/post.js
@@ -2,8 +2,8 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.salesChannels.create({
-  name: 'App',
-  description: 'Mobile app'
+  name: "App",
+  description: "Mobile app"
 })
 .then(({ sales_channel }) => {
   console.log(sales_channel.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/delete.js
index 69cfc064e6..33335bcafa 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.salesChannels.delete(sales_channel_id)
+medusa.admin.salesChannels.delete(salesChannelId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/get.js
index a80a3790d7..0e25e9344f 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.salesChannels.retrieve(sales_channel_id)
+medusa.admin.salesChannels.retrieve(salesChannelId)
 .then(({ sales_channel }) => {
   console.log(sales_channel.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/post.js
index 8859a4a8a0..30e43a4ebf 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.salesChannels.update(sales_channel_id, {
-  name: 'App'
+medusa.admin.salesChannels.update(salesChannelId, {
+  name: "App"
 })
 .then(({ sales_channel }) => {
   console.log(sales_channel.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_products_batch/delete.js b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_products_batch/delete.js
index 35e9355f55..bc5d1a35db 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_products_batch/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_products_batch/delete.js
@@ -1,10 +1,10 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.salesChannels.removeProducts(sales_channel_id, {
+medusa.admin.salesChannels.removeProducts(salesChannelId, {
   product_ids: [
     {
-      id: product_id
+      id: productId
     }
   ]
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_products_batch/post.js b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_products_batch/post.js
index e2d8c57d61..6e9f86ee21 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_products_batch/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_products_batch/post.js
@@ -1,10 +1,10 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.salesChannels.addProducts(sales_channel_id, {
+medusa.admin.salesChannels.addProducts(salesChannelId, {
   product_ids: [
     {
-      id: product_id
+      id: productId
     }
   ]
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_stock-locations/delete.js b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_stock-locations/delete.js
index f586d778bc..3d965e58e0 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_stock-locations/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_stock-locations/delete.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.salesChannels.removeLocation(salesChannelId, {
-  location_id: 'loc_id'
+  location_id: "loc_id"
 })
 .then(({ sales_channel }) => {
   console.log(sales_channel.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_stock-locations/post.js b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_stock-locations/post.js
index c8a2c42f34..ad1afff74a 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_stock-locations/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_sales-channels_{id}_stock-locations/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.salesChannels.addLocation(salesChannelId, {
-  location_id: 'loc_123'
+  location_id: "loc_123"
 })
 .then(({ sales_channel }) => {
   console.log(sales_channel.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_shipping-options/post.js b/docs/api/admin/code_samples/JavaScript/admin_shipping-options/post.js
index 0559379cfd..aeacf0245e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_shipping-options/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_shipping-options/post.js
@@ -2,12 +2,12 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.shippingOptions.create({
-  name: 'PostFake',
-  region_id: "saasf",
-  provider_id: "manual",
+  name: "PostFake",
+  region_id,
+  provider_id,
   data: {
   },
-  price_type: 'flat_rate'
+  price_type: "flat_rate"
 })
 .then(({ shipping_option }) => {
   console.log(shipping_option.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/delete.js
index 3ffaba5bcf..22085391dd 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.shippingOptions.delete(option_id)
+medusa.admin.shippingOptions.delete(optionId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/get.js
index 35580fb6ed..6a304dbc03 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.shippingOptions.retrieve(option_id)
+medusa.admin.shippingOptions.retrieve(optionId)
 .then(({ shipping_option }) => {
   console.log(shipping_option.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/post.js
index 4dba9b7cc5..f3d2f8285e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_shipping-options_{id}/post.js
@@ -1,12 +1,12 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.shippingOptions.update(option_id, {
-  name: 'PostFake',
+medusa.admin.shippingOptions.update(optionId, {
+  name: "PostFake",
   requirements: [
     {
       id,
-      type: 'max_subtotal',
+      type: "max_subtotal",
       amount: 1000
     }
   ]
diff --git a/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles/post.js b/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles/post.js
index dc7216640c..5d82ba2477 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.shippingProfiles.create({
-  name: 'Large Products'
+  name: "Large Products"
 })
 .then(({ shipping_profile }) => {
   console.log(shipping_profile.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/delete.js
index c29b6cfd85..a1862657a7 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.shippingProfiles.delete(profile_id)
+medusa.admin.shippingProfiles.delete(profileId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/get.js
index 169466b9bd..86ffde5d0e 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.shippingProfiles.retrieve(profile_id)
+medusa.admin.shippingProfiles.retrieve(profileId)
 .then(({ shipping_profile }) => {
   console.log(shipping_profile.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/post.js
index a1d9d7b9b0..03c6b3fc05 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_shipping-profiles_{id}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.shippingProfiles.update(shipping_profile_id, {
+medusa.admin.shippingProfiles.update(shippingProfileId, {
   name: 'Large Products'
 })
 .then(({ shipping_profile }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_stock-locations/post.js b/docs/api/admin/code_samples/JavaScript/admin_stock-locations/post.js
index 65f4a5d3eb..2c6b725808 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_stock-locations/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_stock-locations/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.stockLocations.create({
-  name: 'Main Warehouse',
+  name: "Main Warehouse",
 })
 .then(({ stock_location }) => {
   console.log(stock_location.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_stock-locations_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_stock-locations_{id}/delete.js
index 0de3cba4e0..f49f312bfa 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_stock-locations_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_stock-locations_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.stockLocations.delete(stock_location_id)
+medusa.admin.stockLocations.delete(stockLocationId)
 .then(({ id, object, deleted }) => {
   console.log(id)
 })
diff --git a/docs/api/admin/code_samples/JavaScript/admin_store/post.js b/docs/api/admin/code_samples/JavaScript/admin_store/post.js
index b21747b0ac..f259cd2f01 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_store/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_store/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.store.update({
-  name: 'Medusa Store'
+  name: "Medusa Store"
 })
 .then(({ store }) => {
   console.log(store.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_store_currencies_{code}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_store_currencies_{code}/delete.js
index 60a7f2301e..5f3514aba8 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_store_currencies_{code}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_store_currencies_{code}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.store.deleteCurrency('eur')
+medusa.admin.store.deleteCurrency("eur")
 .then(({ store }) => {
   console.log(store.currencies);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_store_currencies_{code}/post.js b/docs/api/admin/code_samples/JavaScript/admin_store_currencies_{code}/post.js
index 8eb0ea3621..99d96959c3 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_store_currencies_{code}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_store_currencies_{code}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.store.addCurrency('eur')
+medusa.admin.store.addCurrency("eur")
 .then(({ store }) => {
   console.log(store.currencies);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_swaps_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_swaps_{id}/get.js
index de7a6276b4..b7cb2a9632 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_swaps_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_swaps_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.swaps.retrieve(swap_id)
+medusa.admin.swaps.retrieve(swapId)
 .then(({ swap }) => {
   console.log(swap.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates/post.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates/post.js
index 2ca559a25b..6a448583b5 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates/post.js
@@ -2,8 +2,8 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.taxRates.create({
-  code: 'TEST',
-  name: 'New Tax Rate',
+  code: "TEST",
+  name: "New Tax Rate",
   region_id
 })
 .then(({ tax_rate }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/delete.js
index 4ef3395248..f2cca5e1ec 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.taxRates.delete(tax_rate_id)
+medusa.admin.taxRates.delete(taxRateId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/get.js
index 244317ebcf..17b7808207 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.taxRates.retrieve(tax_rate_id)
+medusa.admin.taxRates.retrieve(taxRateId)
 .then(({ tax_rate }) => {
   console.log(tax_rate.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/post.js
index 40ceb0c3c5..95c2798abe 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.taxRates.update(tax_rate_id, {
-  name: 'New Tax Rate'
+medusa.admin.taxRates.update(taxRateId, {
+  name: "New Tax Rate"
 })
 .then(({ tax_rate }) => {
   console.log(tax_rate.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_product-types_batch/delete.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_product-types_batch/delete.js
index 60c7e61b08..9914f85587 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_product-types_batch/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_product-types_batch/delete.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.taxRates.removeProductTypes(tax_rate_id, {
+medusa.admin.taxRates.removeProductTypes(taxRateId, {
   product_types: [
-    product_type_id
+    productTypeId
   ]
 })
 .then(({ tax_rate }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_product-types_batch/post.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_product-types_batch/post.js
index 55da7e8ff1..c25965b9cb 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_product-types_batch/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_product-types_batch/post.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.taxRates.addProductTypes(tax_rate_id, {
+medusa.admin.taxRates.addProductTypes(taxRateId, {
   product_types: [
-    product_type_id
+    productTypeId
   ]
 })
 .then(({ tax_rate }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_products_batch/delete.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_products_batch/delete.js
index fd05e8175f..cb642c610b 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_products_batch/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_products_batch/delete.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.taxRates.removeProducts(tax_rate_id, {
+medusa.admin.taxRates.removeProducts(taxRateId, {
   products: [
-    product_id
+    productId
   ]
 })
 .then(({ tax_rate }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_products_batch/post.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_products_batch/post.js
index 4bbafda08b..50cceed4e2 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_products_batch/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_products_batch/post.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.taxRates.addProducts(tax_rate_id, {
+medusa.admin.taxRates.addProducts(taxRateId, {
   products: [
-    product_id
+    productId
   ]
 })
 .then(({ tax_rate }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_shipping-options_batch/delete.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_shipping-options_batch/delete.js
index fc8dc08e7a..0b427612f7 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_shipping-options_batch/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_shipping-options_batch/delete.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.taxRates.removeShippingOptions(tax_rate_id, {
+medusa.admin.taxRates.removeShippingOptions(taxRateId, {
   shipping_options: [
-    shipping_option_id
+    shippingOptionId
   ]
 })
 .then(({ tax_rate }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_shipping-options_batch/post.js b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_shipping-options_batch/post.js
index 8cf86df693..0a2fd121c6 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_shipping-options_batch/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_tax-rates_{id}_shipping-options_batch/post.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.taxRates.addShippingOptions(tax_rate_id, {
+medusa.admin.taxRates.addShippingOptions(taxRateId, {
   shipping_options: [
-    shipping_option_id
+    shippingOptionId
   ]
 })
 .then(({ tax_rate }) => {
diff --git a/docs/api/admin/code_samples/JavaScript/admin_users/post.js b/docs/api/admin/code_samples/JavaScript/admin_users/post.js
index b842c551bc..94f4bfbe42 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_users/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_users/post.js
@@ -2,8 +2,8 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.users.create({
-  email: 'user@example.com',
-  password: 'supersecret'
+  email: "user@example.com",
+  password: "supersecret"
 })
 .then(({ user }) => {
   console.log(user.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_users_password-token/post.js b/docs/api/admin/code_samples/JavaScript/admin_users_password-token/post.js
index 1bc09ed2c1..dd09a098af 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_users_password-token/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_users_password-token/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.users.sendResetPasswordToken({
-  email: 'user@example.com'
+  email: "user@example.com"
 })
 .then(() => {
   // successful
diff --git a/docs/api/admin/code_samples/JavaScript/admin_users_reset-password/post.js b/docs/api/admin/code_samples/JavaScript/admin_users_reset-password/post.js
index 00f8683c66..56ca075c54 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_users_reset-password/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_users_reset-password/post.js
@@ -2,8 +2,8 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.users.resetPassword({
-  token: 'supersecrettoken',
-  password: 'supersecret'
+  token: "supersecrettoken",
+  password: "supersecret"
 })
 .then(({ user }) => {
   console.log(user.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_users_{id}/delete.js b/docs/api/admin/code_samples/JavaScript/admin_users_{id}/delete.js
index d33f7acd3a..5d90c96bfd 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_users_{id}/delete.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_users_{id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.users.delete(user_id)
+medusa.admin.users.delete(userId)
 .then(({ id, object, deleted }) => {
   console.log(id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_users_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_users_{id}/get.js
index 4b1aacff2d..0f80f02119 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_users_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_users_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.users.retrieve(user_id)
+medusa.admin.users.retrieve(userId)
 .then(({ user }) => {
   console.log(user.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_users_{id}/post.js b/docs/api/admin/code_samples/JavaScript/admin_users_{id}/post.js
index 105e42acea..89c77cca1c 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_users_{id}/post.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_users_{id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.users.update(user_id, {
-  first_name: 'Marcellus'
+medusa.admin.users.update(userId, {
+  first_name: "Marcellus"
 })
 .then(({ user }) => {
   console.log(user.id);
diff --git a/docs/api/admin/code_samples/JavaScript/admin_variants_{id}/get.js b/docs/api/admin/code_samples/JavaScript/admin_variants_{id}/get.js
index dac4466183..b1a38a0e59 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_variants_{id}/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_variants_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.admin.variants.retrieve(product_id)
-.then(({ product }) => {
-  console.log(product.id);
+medusa.admin.variants.retrieve(variantId)
+.then(({ variant }) => {
+  console.log(variant.id);
 });
diff --git a/docs/api/admin/code_samples/JavaScript/admin_variants_{id}_inventory/get.js b/docs/api/admin/code_samples/JavaScript/admin_variants_{id}_inventory/get.js
index c3d1c7018d..13d9326430 100644
--- a/docs/api/admin/code_samples/JavaScript/admin_variants_{id}_inventory/get.js
+++ b/docs/api/admin/code_samples/JavaScript/admin_variants_{id}_inventory/get.js
@@ -2,6 +2,6 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
 medusa.admin.variants.list()
-  .then(({ variants, limit, offset, count }) => {
-    console.log(variants.length)
-  })
+.then(({ variants, limit, offset, count }) => {
+  console.log(variants.length)
+})
diff --git a/docs/api/admin/code_samples/Shell/admin_apps/get.sh b/docs/api/admin/code_samples/Shell/admin_apps/get.sh
index e9f3cbfd4b..03a95f06b6 100644
--- a/docs/api/admin/code_samples/Shell/admin_apps/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_apps/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/apps' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/apps' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_apps_authorizations/post.sh b/docs/api/admin/code_samples/Shell/admin_apps_authorizations/post.sh
index 77b8e41f30..f27049cc3a 100644
--- a/docs/api/admin/code_samples/Shell/admin_apps_authorizations/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_apps_authorizations/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/apps/authorizations' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/apps/authorizations' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "application_name": "example",
     "state": "ready",
diff --git a/docs/api/admin/code_samples/Shell/admin_auth/delete.sh b/docs/api/admin/code_samples/Shell/admin_auth/delete.sh
index 1b7aa8e1af..2e64642cfc 100644
--- a/docs/api/admin/code_samples/Shell/admin_auth/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_auth/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/auth' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/auth' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_auth/get.sh b/docs/api/admin/code_samples/Shell/admin_auth/get.sh
index c396a333ef..f8b8b0636c 100644
--- a/docs/api/admin/code_samples/Shell/admin_auth/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_auth/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/auth' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/auth' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_auth/post.sh b/docs/api/admin/code_samples/Shell/admin_auth/post.sh
index 5a9d09b774..482a1b522a 100644
--- a/docs/api/admin/code_samples/Shell/admin_auth/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_auth/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/admin/auth' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/auth' \
+-H 'Content-Type: application/json' \
 --data-raw '{
   "email": "user@example.com",
   "password": "supersecret"
diff --git a/docs/api/admin/code_samples/Shell/admin_batch-jobs/get.sh b/docs/api/admin/code_samples/Shell/admin_batch-jobs/get.sh
index 6031fa39e2..1b2f505ea5 100644
--- a/docs/api/admin/code_samples/Shell/admin_batch-jobs/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_batch-jobs/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/batch-jobs' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/batch-jobs' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_batch-jobs/post.sh b/docs/api/admin/code_samples/Shell/admin_batch-jobs/post.sh
index e912301db7..7b27a77575 100644
--- a/docs/api/admin/code_samples/Shell/admin_batch-jobs/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_batch-jobs/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/batch-jobs' \
---header 'Content-Type: application/json' \
---header 'Authorization: Bearer {api_token}' \
+curl -X POST 'https://medusa-url.com/admin/batch-jobs' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {api_token}' \
 --data-raw '{
     "type": "product-export",
     "context": { }
diff --git a/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}/get.sh
index bd63e8285b..c9d21e271b 100644
--- a/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/batch-jobs/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/batch-jobs/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}_cancel/post.sh b/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}_cancel/post.sh
index a7441d43d6..b032a2b65c 100644
--- a/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}_cancel/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}_cancel/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/cancel' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/batch-jobs/{id}/cancel' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}_confirm/post.sh b/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}_confirm/post.sh
index 08d4f63cc7..c4ca5ff0bd 100644
--- a/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}_confirm/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_batch-jobs_{id}_confirm/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/confirm' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/batch-jobs/{id}/confirm' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_collections/get.sh b/docs/api/admin/code_samples/Shell/admin_collections/get.sh
index 453d7ac39d..fcc6ad291a 100644
--- a/docs/api/admin/code_samples/Shell/admin_collections/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_collections/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/collections' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/collections' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_collections/post.sh b/docs/api/admin/code_samples/Shell/admin_collections/post.sh
index 5c44e23be9..c8393f8372 100644
--- a/docs/api/admin/code_samples/Shell/admin_collections/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_collections/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/collections' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/collections' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "New Collection"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_collections_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_collections_{id}/delete.sh
index 14a3181174..dea9e74cf1 100644
--- a/docs/api/admin/code_samples/Shell/admin_collections_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_collections_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/collections/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_collections_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_collections_{id}/get.sh
index 5ae08e69c4..45bcff3771 100644
--- a/docs/api/admin/code_samples/Shell/admin_collections_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_collections_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/collections/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/collections/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_collections_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_collections_{id}/post.sh
index c6c54dc726..0f3b445f87 100644
--- a/docs/api/admin/code_samples/Shell/admin_collections_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_collections_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/collections/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/collections/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "New Collection"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_collections_{id}_products_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_collections_{id}_products_batch/delete.sh
index bb535f5d71..4c34781b2d 100644
--- a/docs/api/admin/code_samples/Shell/admin_collections_{id}_products_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_collections_{id}_products_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}/products/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/collections/{id}/products/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "product_ids": [
         "prod_01G1G5V2MBA328390B5AXJ610F"
diff --git a/docs/api/admin/code_samples/Shell/admin_collections_{id}_products_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_collections_{id}_products_batch/post.sh
index 5d72595716..d98b5a3df7 100644
--- a/docs/api/admin/code_samples/Shell/admin_collections_{id}_products_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_collections_{id}_products_batch/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/collections/{id}/products/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/collections/{id}/products/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "product_ids": [
         "prod_01G1G5V2MBA328390B5AXJ610F"
diff --git a/docs/api/admin/code_samples/Shell/admin_currencies/get.sh b/docs/api/admin/code_samples/Shell/admin_currencies/get.sh
index 67225eb265..019bfd02bc 100644
--- a/docs/api/admin/code_samples/Shell/admin_currencies/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_currencies/get.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/currencies' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/currencies' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_currencies_{code}/post.sh b/docs/api/admin/code_samples/Shell/admin_currencies_{code}/post.sh
index bde3b929de..b47efd0e4d 100644
--- a/docs/api/admin/code_samples/Shell/admin_currencies_{code}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_currencies_{code}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/currencies/{code}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/currencies/{code}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "includes_tax": true
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_customer-groups/get.sh b/docs/api/admin/code_samples/Shell/admin_customer-groups/get.sh
index a5048c37cd..5764fe6165 100644
--- a/docs/api/admin/code_samples/Shell/admin_customer-groups/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customer-groups/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/customer-groups' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/customer-groups' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_customer-groups/post.sh b/docs/api/admin/code_samples/Shell/admin_customer-groups/post.sh
index 966d8e3d37..ecf7d68aa2 100644
--- a/docs/api/admin/code_samples/Shell/admin_customer-groups/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customer-groups/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/customer-groups' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/customer-groups' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "VIP"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/delete.sh
index 2c52c84d62..7c449a415b 100644
--- a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/customer-groups/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/get.sh
index a3cf8abe1f..3c23aaff70 100644
--- a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/customer-groups/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/post.sh
index 6f6248f25c..5f8b02652c 100644
--- a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/customer-groups/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "VIP"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers/get.sh b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers/get.sh
index 90cdfe78c5..1ed2716827 100644
--- a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}/customers' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/customer-groups/{id}/customers' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers_batch/delete.sh
index 2236bfc611..6293de6fd2 100644
--- a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "customer_ids": [
         {
diff --git a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers_batch/post.sh
index 29d0e6c579..b53b1de55f 100644
--- a/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customer-groups_{id}_customers_batch/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "customer_ids": [
         {
diff --git a/docs/api/admin/code_samples/Shell/admin_customers/get.sh b/docs/api/admin/code_samples/Shell/admin_customers/get.sh
index 7d881eb71a..745ae27085 100644
--- a/docs/api/admin/code_samples/Shell/admin_customers/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customers/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/customers' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/customers' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_customers/post.sh b/docs/api/admin/code_samples/Shell/admin_customers/post.sh
index f519c48961..71c95b1b62 100644
--- a/docs/api/admin/code_samples/Shell/admin_customers/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customers/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/customers' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/customers' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com",
     "first_name": "Caterina",
diff --git a/docs/api/admin/code_samples/Shell/admin_customers_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_customers_{id}/get.sh
index c512e934e3..10aa929c17 100644
--- a/docs/api/admin/code_samples/Shell/admin_customers_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customers_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/customers/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/customers/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_customers_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_customers_{id}/post.sh
index 8114b453f9..02bb7a6e71 100644
--- a/docs/api/admin/code_samples/Shell/admin_customers_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_customers_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/customers/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/customers/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "first_name": "Dolly"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts/get.sh b/docs/api/admin/code_samples/Shell/admin_discounts/get.sh
index 56ddb9fc0d..3d98f67dec 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/discounts' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/discounts' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts/post.sh b/docs/api/admin/code_samples/Shell/admin_discounts/post.sh
index a651e15ba4..bb9521e8f1 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/discounts' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/discounts' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "code": "TEST",
     "rule": {
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_code_{code}/get.sh b/docs/api/admin/code_samples/Shell/admin_discounts_code_{code}/get.sh
index 303d1d988e..967a57d33e 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_code_{code}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_code_{code}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/discounts/code/{code}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/discounts/code/{code}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions/post.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions/post.sh
index 2f940df020..5efa74c8b5 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/discounts/{id}/conditions' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "operator": "in"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/delete.sh
index 4d93337752..7ec92d390e 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/get.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/get.sh
index e966519363..f7bdf8ec36 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/post.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/post.sh
index 5589b208ad..a3f1fa5efe 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "products": [
        "prod_01G1G5V2MBA328390B5AXJ610F"
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}_batch/delete.sh
index 609609e46b..2402bb52dd 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "resources": [{ "id": "item_id" }]
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}_batch/post.sh
index b64695b1f9..6cf84c102f 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{discount_id}_conditions_{condition_id}_batch/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "resources": [{ "id": "item_id" }]
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{id}/delete.sh
index e3942cdfe5..a6c9d63b35 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{id}/get.sh
index b5fe6fa2f2..6275101ca4 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/discounts/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{id}/post.sh
index 8a2a6f7025..f5944e7ff7 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/discounts/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "code": "TEST"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{id}_dynamic-codes/post.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{id}_dynamic-codes/post.sh
index fdf631bbc2..13782489be 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{id}_dynamic-codes/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{id}_dynamic-codes/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "code": "TEST"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{id}_dynamic-codes_{code}/delete.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{id}_dynamic-codes_{code}/delete.sh
index c24e818ac1..097773358e 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{id}_dynamic-codes_{code}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{id}_dynamic-codes_{code}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes/{code}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes/{code}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{id}_regions_{region_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{id}_regions_{region_id}/delete.sh
index ef471b2353..003c607efc 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{id}_regions_{region_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{id}_regions_{region_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_discounts_{id}_regions_{region_id}/post.sh b/docs/api/admin/code_samples/Shell/admin_discounts_{id}_regions_{region_id}/post.sh
index e3aa97a564..008201368c 100644
--- a/docs/api/admin/code_samples/Shell/admin_discounts_{id}_regions_{region_id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_discounts_{id}_regions_{region_id}/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_draft-orders/get.sh b/docs/api/admin/code_samples/Shell/admin_draft-orders/get.sh
index aa7ed7a4ca..3008745d81 100644
--- a/docs/api/admin/code_samples/Shell/admin_draft-orders/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_draft-orders/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/draft-orders' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/draft-orders' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_draft-orders/post.sh b/docs/api/admin/code_samples/Shell/admin_draft-orders/post.sh
index a332712dbd..4d038c3be0 100644
--- a/docs/api/admin/code_samples/Shell/admin_draft-orders/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_draft-orders/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/draft-orders' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/draft-orders' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com",
     "region_id": "{region_id}"
diff --git a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/delete.sh
index 58b5d78524..f8ab71fc30 100644
--- a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/draft-orders/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/get.sh
index d3d5f473a2..9864599c75 100644
--- a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/draft-orders/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/draft-orders/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/post.sh
index b61a2ff953..ece8a712d7 100644
--- a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items/post.sh b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items/post.sh
index e69f38c203..45a26e4bf6 100644
--- a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "quantity": 1
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items_{line_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items_{line_id}/delete.sh
index 637f1b6445..8eec201e50 100644
--- a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items_{line_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items_{line_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items_{line_id}/post.sh b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items_{line_id}/post.sh
index f27e67dff8..ed345aa420 100644
--- a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items_{line_id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_line-items_{line_id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "quantity": 1
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_pay/post.sh b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_pay/post.sh
index f3a2d6894f..af12944735 100644
--- a/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_pay/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_draft-orders_{id}_pay/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/pay' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/draft-orders/{id}/pay' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_gift-cards/get.sh b/docs/api/admin/code_samples/Shell/admin_gift-cards/get.sh
index 0318549eaa..780bc04d42 100644
--- a/docs/api/admin/code_samples/Shell/admin_gift-cards/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_gift-cards/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/gift-cards' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/gift-cards' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_gift-cards/post.sh b/docs/api/admin/code_samples/Shell/admin_gift-cards/post.sh
index d5994f38b9..4f14fd6752 100644
--- a/docs/api/admin/code_samples/Shell/admin_gift-cards/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_gift-cards/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/gift-cards' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/gift-cards' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "region_id": "{region_id}"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/delete.sh
index ef924b3574..e831f74daf 100644
--- a/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/gift-cards/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/gift-cards/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/get.sh
index 09bcb294b9..9ad494c190 100644
--- a/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/gift-cards/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/gift-cards/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/post.sh
index fbf48d4f9e..c5ba05c8f6 100644
--- a/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_gift-cards_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/gift-cards/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/gift-cards/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "region_id": "{region_id}"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_inventory-items/get.sh b/docs/api/admin/code_samples/Shell/admin_inventory-items/get.sh
index 41c223bd88..517d7bd98a 100644
--- a/docs/api/admin/code_samples/Shell/admin_inventory-items/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_inventory-items/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/inventory-items' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/inventory-items' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_inventory-items/post.sh b/docs/api/admin/code_samples/Shell/admin_inventory-items/post.sh
index 53ad14d589..ed714795bb 100644
--- a/docs/api/admin/code_samples/Shell/admin_inventory-items/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_inventory-items/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/inventory-items' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/inventory-items' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "variant_id": "variant_123",
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/delete.sh
index 128d5f43e4..79621b3a34 100644
--- a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/inventory-items/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/inventory-items/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/get.sh
index 7867b5ca65..dd59e484ae 100644
--- a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/inventory-items/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/inventory-items/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/post.sh
index 8d9f64e103..5b3e306a5e 100644
--- a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/inventory-items/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/inventory-items/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "origin_country": "US"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels/get.sh b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels/get.sh
index c87c428b34..27e2336ebb 100644
--- a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels/post.sh b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels/post.sh
index 9a560ddcb8..f8e573f675 100644
--- a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "location_id": "sloc_123",
     "stocked_quantity": 10
diff --git a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels_{location_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels_{location_id}/delete.sh
index 1c3c778d46..c0a3cc4397 100644
--- a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels_{location_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels_{location_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels_{location_id}/post.sh b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels_{location_id}/post.sh
index cf23deffce..968ca20117 100644
--- a/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels_{location_id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_inventory-items_{id}_location-levels_{location_id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/inventory-items/{id}/location-levels/{location_id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "stocked_quantity": 15
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_invites/get.sh b/docs/api/admin/code_samples/Shell/admin_invites/get.sh
index 6b00b3ff47..5d10afff29 100644
--- a/docs/api/admin/code_samples/Shell/admin_invites/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_invites/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/invites' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/invites' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_invites/post.sh b/docs/api/admin/code_samples/Shell/admin_invites/post.sh
index 8fec9cc475..a8d30d1a0d 100644
--- a/docs/api/admin/code_samples/Shell/admin_invites/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_invites/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/invites' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/invites' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "user": "user@example.com",
     "role": "admin"
diff --git a/docs/api/admin/code_samples/Shell/admin_invites_accept/post.sh b/docs/api/admin/code_samples/Shell/admin_invites_accept/post.sh
index 1f53c0081b..752d5795e3 100644
--- a/docs/api/admin/code_samples/Shell/admin_invites_accept/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_invites_accept/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/invites/accept' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/invites/accept' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "token": "{token}",
     "user": {
diff --git a/docs/api/admin/code_samples/Shell/admin_invites_{invite_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_invites_{invite_id}/delete.sh
index a400c35b0c..a7bdb75f47 100644
--- a/docs/api/admin/code_samples/Shell/admin_invites_{invite_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_invites_{invite_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/invites/{invite_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/invites/{invite_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_invites_{invite_id}_resend/post.sh b/docs/api/admin/code_samples/Shell/admin_invites_{invite_id}_resend/post.sh
index c602788617..fc683879a0 100644
--- a/docs/api/admin/code_samples/Shell/admin_invites_{invite_id}_resend/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_invites_{invite_id}_resend/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/invites/{invite_id}/resend' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/invites/{invite_id}/resend' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_notes/get.sh b/docs/api/admin/code_samples/Shell/admin_notes/get.sh
index b8f342b1c6..50c6195c96 100644
--- a/docs/api/admin/code_samples/Shell/admin_notes/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_notes/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/notes' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/notes' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_notes/post.sh b/docs/api/admin/code_samples/Shell/admin_notes/post.sh
index 941883941e..0e414439a9 100644
--- a/docs/api/admin/code_samples/Shell/admin_notes/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_notes/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/notes' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/notes' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "resource_id": "{resource_id}",
     "resource_type": "order",
diff --git a/docs/api/admin/code_samples/Shell/admin_notes_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_notes_{id}/delete.sh
index 6022941b0b..62dec8cced 100644
--- a/docs/api/admin/code_samples/Shell/admin_notes_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_notes_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/notes/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/notes/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_notes_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_notes_{id}/get.sh
index 8eb3390421..2b9027794a 100644
--- a/docs/api/admin/code_samples/Shell/admin_notes_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_notes_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/notes/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/notes/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_notes_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_notes_{id}/post.sh
index 16b9501595..ae08e59a95 100644
--- a/docs/api/admin/code_samples/Shell/admin_notes_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_notes_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/notes/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/notes/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "value": "We delivered this order"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_notifications/get.sh b/docs/api/admin/code_samples/Shell/admin_notifications/get.sh
index 58da1ac1e8..5a0415ade5 100644
--- a/docs/api/admin/code_samples/Shell/admin_notifications/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_notifications/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/notifications' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/notifications' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_notifications_{id}_resend/post.sh b/docs/api/admin/code_samples/Shell/admin_notifications_{id}_resend/post.sh
index eea4a4fe51..2447329c8a 100644
--- a/docs/api/admin/code_samples/Shell/admin_notifications_{id}_resend/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_notifications_{id}_resend/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/notifications/{id}/resend' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/notifications/{id}/resend' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits/get.sh b/docs/api/admin/code_samples/Shell/admin_order-edits/get.sh
index 3a83fdf7cc..974aa8ce87 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/order-edits' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/order-edits' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits/post.sh b/docs/api/admin/code_samples/Shell/admin_order-edits/post.sh
index 65fb80274b..1168218d7d 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits/post.sh
@@ -1,4 +1,4 @@
-curl --location --request POST 'https://medusa-url.com/admin/order-edits' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/order-edits' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{ "order_id": "my_order_id", "internal_note": "my_optional_note" }'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/delete.sh
index 3cfa445f1e..4d6b529676 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/order-edits/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/order-edits/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/get.sh
index 40f89d51a1..70db2b88b9 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/order-edits/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/order-edits/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/post.sh
index 916c9d8a2f..4ea148f3c8 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/order-edits/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "internal_note": "internal reason XY"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_cancel/post.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_cancel/post.sh
index 827b3eee6c..87c63e5436 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_cancel/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_cancel/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/cancel' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/cancel' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_changes_{change_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_changes_{change_id}/delete.sh
index ea0d3790f8..302cdc2731 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_changes_{change_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_changes_{change_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/order-edits/{id}/changes/{change_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/order-edits/{id}/changes/{change_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_confirm/post.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_confirm/post.sh
index eeac43d05a..20755d8167 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_confirm/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_confirm/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/confirm' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/confirm' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items/post.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items/post.sh
index 50b46233e4..06e19fdf1a 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items/post.sh
@@ -1,4 +1,4 @@
-curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/items' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{ "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6", "quantity": 3 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items_{item_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items_{item_id}/delete.sh
index aaf8210567..a5c089c4b0 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items_{item_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items_{item_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items_{item_id}/post.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items_{item_id}/post.sh
index 1aaad546b9..ceafdea7f1 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items_{item_id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_items_{item_id}/post.sh
@@ -1,4 +1,4 @@
-curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{ "quantity": 5 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_request/post.sh b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_request/post.sh
index 9c19766746..3b5964fea6 100644
--- a/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_request/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_order-edits_{id}_request/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/request' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/order-edits/{id}/request' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders/get.sh b/docs/api/admin/code_samples/Shell/admin_orders/get.sh
index da90d88126..59c1805d74 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/orders' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/orders' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}/get.sh
index 31061a7d1d..74bbfdff6c 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/orders/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/orders/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}/post.sh
index fe9eec7ec0..ee29c85a4d 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/adasda' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/adasda' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_archive/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_archive/post.sh
index 16f952b60d..dd00fdfe74 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_archive/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_archive/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/archive' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/archive' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_cancel/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_cancel/post.sh
index 3bd1fb9e59..53a69f4a9d 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_cancel/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_cancel/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/cancel' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/cancel' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_capture/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_capture/post.sh
index 2b756505ca..df114a1ce7 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_capture/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_capture/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/capture' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/capture' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims/post.sh
index 740dcec04d..ffc6851bcc 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "type": "refund",
     "claim_items": [
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}/post.sh
index 5e8c065532..6d6f6ffd4b 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "no_notification": true
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_cancel/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_cancel/post.sh
index ce2c338ca2..f372be835f 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_cancel/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_cancel/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/cancel' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/cancel' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_fulfillments/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_fulfillments/post.sh
index 186fae177e..7a8f137ceb 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_fulfillments/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_fulfillments/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel/post.sh
index 70251d2655..8b92ec8884 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_shipments/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_shipments/post.sh
index 500f60537b..7b19013926 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_shipments/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_claims_{claim_id}_shipments/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/shipments' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/shipments' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "fulfillment_id": "{fulfillment_id}"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_complete/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_complete/post.sh
index face961e8a..30adcf57a4 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_complete/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_complete/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/complete' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/complete' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_fulfillment/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_fulfillment/post.sh
index 986ae9845c..000d8304cf 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_fulfillment/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_fulfillment/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/fulfillment' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/fulfillment' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "items": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel/post.sh
index 329baafca2..229ef7deb3 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_line-items_{line_item_id}_reserve/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_line-items_{line_item_id}_reserve/post.sh
index 4d1bc40c86..a9a986542b 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_line-items_{line_item_id}_reserve/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_line-items_{line_item_id}_reserve/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/line-items/{line_item_id}/reserve' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/line-items/{line_item_id}/reserve' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "location_id": "loc_1"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_refund/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_refund/post.sh
index c3861c12f0..717ce8689b 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_refund/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_refund/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/adasda/refund' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/adasda/refund' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "amount": 1000,
     "reason": "Do not like it"
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_reservations/get.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_reservations/get.sh
index 355ebe1f6a..990744e9a2 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_reservations/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_reservations/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/orders/{id}/reservations' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/orders/{id}/reservations' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_return/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_return/post.sh
index 7f404dcd2b..d6333345df 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_return/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_return/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/return' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/return' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "items": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_shipment/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_shipment/post.sh
index 3ce9d0dbe2..32d9670bb7 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_shipment/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_shipment/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/shipment' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/shipment' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "fulfillment_id": "{fulfillment_id}"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_shipping-methods/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_shipping-methods/post.sh
index af64417d03..4c198e694c 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_shipping-methods/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_shipping-methods/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/shipping-methods' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/shipping-methods' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "price": 1000,
     "option_id": "{option_id}"
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps/post.sh
index 05d7956247..3e50d2bcff 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "return_items": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_cancel/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_cancel/post.sh
index 3ab73a66e1..fbf0d5f749 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_cancel/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_cancel/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{order_id}/swaps/{swap_id}/cancel' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{order_id}/swaps/{swap_id}/cancel' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_fulfillments/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_fulfillments/post.sh
index e0c7c80d87..e278972989 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_fulfillments/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_fulfillments/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel/post.sh
index 9028ae28d3..cc6d403291 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_process-payment/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_process-payment/post.sh
index 25c26acf15..9da592c09f 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_process-payment/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_process-payment/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/process-payment' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/process-payment' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_shipments/post.sh b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_shipments/post.sh
index 05d727ac7f..aa2a11672b 100644
--- a/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_shipments/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_orders_{id}_swaps_{swap_id}_shipments/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/shipments' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/shipments' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "fulfillment_id": "{fulfillment_id}"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/delete.sh
index d3e5e0f82f..4efa4223d9 100644
--- a/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/payment-collections/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/payment-collections/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/get.sh
index 9aeebfd8fa..f4129708d2 100644
--- a/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/payment-collections/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/payment-collections/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/post.sh
index 4428893266..bcb0f4790d 100644
--- a/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/payment-collections/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/payment-collections/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
-    "description": "Description of payCol"
+    "description": "Description of payment collection"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}_authorize/post.sh b/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}_authorize/post.sh
index 3fcd7013dc..ac65333245 100644
--- a/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}_authorize/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_payment-collections_{id}_authorize/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/payment-collections/{id}/authorize' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/payment-collections/{id}/authorize' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_payments_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_payments_{id}/get.sh
index 4b52cbf845..afb740fc83 100644
--- a/docs/api/admin/code_samples/Shell/admin_payments_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_payments_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/payments/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/payments/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_payments_{id}_capture/post.sh b/docs/api/admin/code_samples/Shell/admin_payments_{id}_capture/post.sh
index a73c22dc9b..514075209e 100644
--- a/docs/api/admin/code_samples/Shell/admin_payments_{id}_capture/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_payments_{id}_capture/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/payments/{id}/capture' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/payments/{id}/capture' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_payments_{id}_refund/post.sh b/docs/api/admin/code_samples/Shell/admin_payments_{id}_refund/post.sh
index 4667ba8b25..addc421c43 100644
--- a/docs/api/admin/code_samples/Shell/admin_payments_{id}_refund/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_payments_{id}_refund/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/payments/pay_123/refund' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/payments/pay_123/refund' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "amount": 1000,
     "reason": "return",
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists/get.sh b/docs/api/admin/code_samples/Shell/admin_price-lists/get.sh
index c748eb2f93..124cb92fcc 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/price-lists' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/price-lists' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists/post.sh b/docs/api/admin/code_samples/Shell/admin_price-lists/post.sh
index 9220782166..4fd94319cd 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/price-lists' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/price-lists' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "New Price List",
     "description": "A new price list",
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/delete.sh
index 56b417ec43..f930e3b619 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/price-lists/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/get.sh
index f2cb825fbc..7c3b7c8b7a 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/price-lists/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/price-lists/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/post.sh
index 6b567a4234..9bed4202c8 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/price-lists/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/price-lists/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "New Price List"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_prices_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_prices_batch/delete.sh
index d0afcd6475..717c11caf4 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_prices_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_prices_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "price_ids": [
       "adasfa"
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_prices_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_prices_batch/post.sh
index f96de18054..e38ffcfa5c 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_prices_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_prices_batch/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "prices": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_products/get.sh b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_products/get.sh
index 573fdc6d1c..65c2f3a908 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_products/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_products/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/price-lists/{id}/products' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/price-lists/{id}/products' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_products_{product_id}_prices/delete.sh b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_products_{product_id}_prices/delete.sh
index 1bc7ceaa33..87c225bf6a 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_products_{product_id}_prices/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_products_{product_id}_prices/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}/products/{product_id}/prices' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/price-lists/{id}/products/{product_id}/prices' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_variants_{variant_id}_prices/delete.sh b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_variants_{variant_id}_prices/delete.sh
index 53b958b813..3ebf3cd859 100644
--- a/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_variants_{variant_id}_prices/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_price-lists_{id}_variants_{variant_id}_prices/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}/variants/{variant_id}/prices' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/price-lists/{id}/variants/{variant_id}/prices' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_product-categories/get.sh b/docs/api/admin/code_samples/Shell/admin_product-categories/get.sh
index babbcf3733..e9b30c3697 100644
--- a/docs/api/admin/code_samples/Shell/admin_product-categories/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_product-categories/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/product-categories' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/product-categories' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_product-categories/post.sh b/docs/api/admin/code_samples/Shell/admin_product-categories/post.sh
index 11856f7a09..491093747c 100644
--- a/docs/api/admin/code_samples/Shell/admin_product-categories/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_product-categories/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/product-categories' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/product-categories' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "Skinny Jeans"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/delete.sh
index be401c78c2..52a7616886 100644
--- a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/product-categories/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/product-categories/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/get.sh
index b25a813f59..c020731196 100644
--- a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/product-categories/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/product-categories/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/post.sh
index 1df1e616fc..5e02dab241 100644
--- a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/product-categories/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/product-categories/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "Skinny Jeans"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}_products_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}_products_batch/delete.sh
index f5cc8b833a..0187f60549 100644
--- a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}_products_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}_products_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/product-categories/{id}/products/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/product-categories/{id}/products/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "product_ids": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}_products_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}_products_batch/post.sh
index 5d27b9dd49..5900eaa87d 100644
--- a/docs/api/admin/code_samples/Shell/admin_product-categories_{id}_products_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_product-categories_{id}_products_batch/post.sh
@@ -1,7 +1,6 @@
-curl --location \
---request POST 'https://medusa-url.com/admin/product-categories/{id}/products/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/product-categories/{id}/products/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "product_ids": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_product-tags/get.sh b/docs/api/admin/code_samples/Shell/admin_product-tags/get.sh
index 904ad3a752..436d51fdfe 100644
--- a/docs/api/admin/code_samples/Shell/admin_product-tags/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_product-tags/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/product-tags' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/product-tags' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_product-types/get.sh b/docs/api/admin/code_samples/Shell/admin_product-types/get.sh
index c694461e93..c57dda2ea8 100644
--- a/docs/api/admin/code_samples/Shell/admin_product-types/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_product-types/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/product-types' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/product-types' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_products/get.sh b/docs/api/admin/code_samples/Shell/admin_products/get.sh
index 055991a2d9..98f6e5895e 100644
--- a/docs/api/admin/code_samples/Shell/admin_products/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/products' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/products' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_products/post.sh b/docs/api/admin/code_samples/Shell/admin_products/post.sh
index 896c192d81..22633b9bbf 100644
--- a/docs/api/admin/code_samples/Shell/admin_products/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/products' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/products' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "Shirt"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_tag-usage/get.sh b/docs/api/admin/code_samples/Shell/admin_products_tag-usage/get.sh
index 200d6de0be..eae7f22322 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_tag-usage/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_tag-usage/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/products/tag-usage' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/products/tag-usage' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_types/get.sh b/docs/api/admin/code_samples/Shell/admin_products_types/get.sh
index 10f093aa0b..08768ea2a8 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_types/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_types/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/products/types' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/products/types' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}/delete.sh
index 0d38583ed4..2734c575ff 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/products/asfsaf' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/products/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}/get.sh
index abc8f8e395..3310a4494f 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/products/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/products/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}/post.sh
index 6af08c0c74..185f1869bd 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/products/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/products/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "Size"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}_metadata/post.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}_metadata/post.sh
index 8b3c2a6539..747d6454b6 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}_metadata/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}_metadata/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/products/{id}/metadata' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/products/{id}/metadata' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "key": "test",
     "value": "true"
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}_options/post.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}_options/post.sh
index c21addc0bc..9d826105ae 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}_options/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}_options/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/products/{id}/options' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/products/{id}/options' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "Size"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}_options_{option_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}_options_{option_id}/delete.sh
index 0540a983dd..9f5cc2c342 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}_options_{option_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}_options_{option_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}_options_{option_id}/post.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}_options_{option_id}/post.sh
index b100239fe9..e6930e2477 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}_options_{option_id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}_options_{option_id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "Size"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}_variants/get.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}_variants/get.sh
index 4a5b3ec1ed..f237092804 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}_variants/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}_variants/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/products/{id}/variants' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/products/{id}/variants' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}_variants/post.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}_variants/post.sh
index 41f4cbce2a..e5b91a58b2 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}_variants/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}_variants/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/products/{id}/variants' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/products/{id}/variants' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "Color",
     "prices": [
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}_variants_{variant_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}_variants_{variant_id}/delete.sh
index e64e3e5181..66e67302c3 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}_variants_{variant_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}_variants_{variant_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/products/{id}/variants/{variant_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/products/{id}/variants/{variant_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_products_{id}_variants_{variant_id}/post.sh b/docs/api/admin/code_samples/Shell/admin_products_{id}_variants_{variant_id}/post.sh
index 652175da6e..46a028d33d 100644
--- a/docs/api/admin/code_samples/Shell/admin_products_{id}_variants_{variant_id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_products_{id}_variants_{variant_id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/products/asfsaf/variants/saaga' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/products/{id}/variants/{variant_id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "Color",
     "prices": [
diff --git a/docs/api/admin/code_samples/Shell/admin_publishable-api-key_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_publishable-api-key_{id}/post.sh
index d215a07397..2796566ac3 100644
--- a/docs/api/admin/code_samples/Shell/admin_publishable-api-key_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_publishable-api-key_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/publishable-api-key/{pka_id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/publishable-api-key/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "new title"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys/get.sh b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys/get.sh
index 919cda1ff0..47a19a870b 100644
--- a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/publishable-api-keys' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/publishable-api-keys' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys/post.sh b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys/post.sh
index d76c693a80..a573d7331b 100644
--- a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/publishable-api-keys' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/publishable-api-keys' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "title": "Web API Key"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}/delete.sh
index 2d06576df9..c928fc1f16 100644
--- a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/publishable-api-key/{pka_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/publishable-api-key/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}/get.sh
index 7eebfe5c87..67a9d11299 100644
--- a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/publishable-api-keys/{pka_id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/publishable-api-keys/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_revoke/post.sh b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_revoke/post.sh
index 6c3c1731a0..5939b4bbd0 100644
--- a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_revoke/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_revoke/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/publishable-api-keys/{pka_id}/revoke' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/publishable-api-keys/{id}/revoke' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels/get.sh b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels/get.sh
index 9b1a9ec8f3..985324a0c4 100644
--- a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/publishable-api-keys/{pka_id}/sales-channels' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/publishable-api-keys/{id}/sales-channels' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels_batch/delete.sh
index 464937929e..609371b0b9 100644
--- a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/publishable-api-keys/{pka_id}/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/publishable-api-keys/{id}/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "sales_channel_ids": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels_batch/post.sh
index 328abe74a6..fb32690968 100644
--- a/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_publishable-api-keys_{id}_sales-channels_batch/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/publishable-api-keys/{pak_id}/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/publishable-api-keys/{pak_id}/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "sales_channel_ids": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_regions/get.sh b/docs/api/admin/code_samples/Shell/admin_regions/get.sh
index fb80731951..07efacd9c8 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/regions' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/regions' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions/post.sh b/docs/api/admin/code_samples/Shell/admin_regions/post.sh
index f71a7c66a3..a576f5fc79 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/regions' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/regions' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "Europe",
     "currency_code": "eur",
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}/delete.sh
index bd6e9561c6..c743bb15a6 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/regions/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}/get.sh
index 7b2c2db4b3..ca4df7bff4 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/regions/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/regions/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}/post.sh
index 223c0f932a..795bb35acc 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/regions/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/regions/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "Europe"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}_countries/post.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}_countries/post.sh
index 0390c04b6f..806678c728 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}_countries/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}_countries/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/regions/{region_id}/countries' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/regions/{region_id}/countries' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "country_code": "dk"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}_countries_{country_code}/delete.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}_countries_{country_code}/delete.sh
index 4797a1a513..03115ae13e 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}_countries_{country_code}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}_countries_{country_code}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}/countries/dk' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/regions/{id}/countries/{country_code}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-options/get.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-options/get.sh
index c07fcb7d6d..782bb2137a 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-options/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-options/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/regions/{id}/fulfillment-options' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/regions/{id}/fulfillment-options' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-providers/post.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-providers/post.sh
index 1f4d79e6cd..017e79195d 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-providers/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-providers/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "provider_id": "manual"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-providers_{provider_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-providers_{provider_id}/delete.sh
index 72360c5976..9400addfbc 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-providers_{provider_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}_fulfillment-providers_{provider_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers/manual' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers/{provider_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}_payment-providers/post.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}_payment-providers/post.sh
index cacf292ebc..a615d51f23 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}_payment-providers/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}_payment-providers/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/regions/{id}/payment-providers' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/regions/{id}/payment-providers' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "provider_id": "manual"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_regions_{id}_payment-providers_{provider_id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_regions_{id}_payment-providers_{provider_id}/delete.sh
index 27321ae0ec..3e459cb3bf 100644
--- a/docs/api/admin/code_samples/Shell/admin_regions_{id}_payment-providers_{provider_id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_regions_{id}_payment-providers_{provider_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}/payment-providers/manual' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/regions/{id}/payment-providers/{provider_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_reservations/get.sh b/docs/api/admin/code_samples/Shell/admin_reservations/get.sh
index babbcf3733..e9b30c3697 100644
--- a/docs/api/admin/code_samples/Shell/admin_reservations/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_reservations/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/product-categories' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/product-categories' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_reservations/post.sh b/docs/api/admin/code_samples/Shell/admin_reservations/post.sh
index a8884bbf3d..9531a4878a 100644
--- a/docs/api/admin/code_samples/Shell/admin_reservations/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_reservations/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/reservations' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/reservations' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "line_item_id": "item_123",
     "location_id": "loc_123",
diff --git a/docs/api/admin/code_samples/Shell/admin_reservations_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_reservations_{id}/delete.sh
index f4e05512e9..73cb6b6a44 100644
--- a/docs/api/admin/code_samples/Shell/admin_reservations_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_reservations_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/reservations/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/reservations/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_reservations_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_reservations_{id}/get.sh
index 9b6631d783..ec777141e8 100644
--- a/docs/api/admin/code_samples/Shell/admin_reservations_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_reservations_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/reservations/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/reservations/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_reservations_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_reservations_{id}/post.sh
index 9d8e841f56..f0ce9450ff 100644
--- a/docs/api/admin/code_samples/Shell/admin_reservations_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_reservations_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/reservations/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/reservations/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
    "quantity": 3,
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_return-reasons/get.sh b/docs/api/admin/code_samples/Shell/admin_return-reasons/get.sh
index 7ee55fefab..f6e16e8dd0 100644
--- a/docs/api/admin/code_samples/Shell/admin_return-reasons/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_return-reasons/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/return-reasons' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/return-reasons' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_return-reasons/post.sh b/docs/api/admin/code_samples/Shell/admin_return-reasons/post.sh
index 8c18f704c8..5657f73813 100644
--- a/docs/api/admin/code_samples/Shell/admin_return-reasons/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_return-reasons/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/return-reasons' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/return-reasons' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "label": "Damaged",
     "value": "damaged"
diff --git a/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/delete.sh
index 996dc6343e..96904d4ad9 100644
--- a/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/return-reasons/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/return-reasons/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/get.sh
index 15b08a3c1a..870774c7d9 100644
--- a/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/return-reasons/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/return-reasons/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/post.sh
index c11a92f929..98cd418a33 100644
--- a/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_return-reasons_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/return-reasons/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/return-reasons/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "label": "Damaged"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_returns/get.sh b/docs/api/admin/code_samples/Shell/admin_returns/get.sh
index 060dbc3885..4cd713d7e1 100644
--- a/docs/api/admin/code_samples/Shell/admin_returns/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_returns/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/returns' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/returns' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_returns_{id}_cancel/post.sh b/docs/api/admin/code_samples/Shell/admin_returns_{id}_cancel/post.sh
index 67d0a2ac06..5ea4c31add 100644
--- a/docs/api/admin/code_samples/Shell/admin_returns_{id}_cancel/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_returns_{id}_cancel/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/returns/{id}/cancel' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/returns/{id}/cancel' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_returns_{id}_receive/post.sh b/docs/api/admin/code_samples/Shell/admin_returns_{id}_receive/post.sh
index c4eaefca16..661b9d88c2 100644
--- a/docs/api/admin/code_samples/Shell/admin_returns_{id}_receive/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_returns_{id}_receive/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/returns/{id}/receive' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/returns/{id}/receive' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "items": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_sales-channels/get.sh b/docs/api/admin/code_samples/Shell/admin_sales-channels/get.sh
index 24782baea9..d14017610c 100644
--- a/docs/api/admin/code_samples/Shell/admin_sales-channels/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_sales-channels/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/sales-channels' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/sales-channels' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_sales-channels/post.sh b/docs/api/admin/code_samples/Shell/admin_sales-channels/post.sh
index 97b8eff3f6..04065bd5d8 100644
--- a/docs/api/admin/code_samples/Shell/admin_sales-channels/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_sales-channels/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/sales-channels' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/sales-channels' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "App"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/delete.sh
index 2137590f84..6c01cdb5b4 100644
--- a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/sales-channels/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/sales-channels/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/get.sh
index 10a811a10a..04d309f236 100644
--- a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/sales-channels/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/sales-channels/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/post.sh
index a26d506361..acc086c585 100644
--- a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/sales-channels/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/sales-channels/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "App"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_products_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_products_batch/delete.sh
index fe3b16bda1..01185c7b0e 100644
--- a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_products_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_products_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/sales-channels/{id}/products/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/sales-channels/{id}/products/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "product_ids": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_products_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_products_batch/post.sh
index b9e4a32fd3..1279f305fd 100644
--- a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_products_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_products_batch/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/sales-channels/afasf/products/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/sales-channels/{id}/products/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "product_ids": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_stock-locations/delete.sh b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_stock-locations/delete.sh
index 6e0655dc26..329caf47ac 100644
--- a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_stock-locations/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_stock-locations/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/sales-channels/{id}/stock-locations' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/sales-channels/{id}/stock-locations' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "locaton_id": "loc_id"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_stock-locations/post.sh b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_stock-locations/post.sh
index 9f7b721d5c..913c6ce168 100644
--- a/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_stock-locations/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_sales-channels_{id}_stock-locations/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/sales-channels/{id}/stock-locations' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/sales-channels/{id}/stock-locations' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "locaton_id": "loc_123"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-options/get.sh b/docs/api/admin/code_samples/Shell/admin_shipping-options/get.sh
index 2e749082ef..8305e8966b 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-options/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-options/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/shipping-options' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/shipping-options' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-options/post.sh b/docs/api/admin/code_samples/Shell/admin_shipping-options/post.sh
index 77d68a91dd..6b56c878ad 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-options/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-options/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/shipping-options' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/shipping-options' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "PostFake",
     "region_id": "afasf",
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/delete.sh
index ca615dfc32..246ee1de0e 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/shipping-options/{option_id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/shipping-options/{option_id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/get.sh
index 852768184b..f4d7378276 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/shipping-options/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/shipping-options/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/post.sh
index d4701c31a7..06be5d60f3 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-options_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/shipping-options/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/shipping-options/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "requirements": [
       {
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-profiles/get.sh b/docs/api/admin/code_samples/Shell/admin_shipping-profiles/get.sh
index 0d5452bd32..9589604182 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-profiles/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-profiles/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/shipping-profiles' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/shipping-profiles' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-profiles/post.sh b/docs/api/admin/code_samples/Shell/admin_shipping-profiles/post.sh
index 639c2efa96..c7291753ab 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-profiles/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-profiles/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/shipping-profiles' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/shipping-profiles' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "Large Products"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/delete.sh
index a2e4101fbb..783884d527 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/shipping-profiles/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/shipping-profiles/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/get.sh
index 30387b3e43..817b6cd57f 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/shipping-profiles/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/shipping-profiles/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/post.sh
index fba91f5e74..feacb8dcb5 100644
--- a/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_shipping-profiles_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/shipping-profiles/{id} \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/shipping-profiles/{id} \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "Large Products"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_stock-locations/get.sh b/docs/api/admin/code_samples/Shell/admin_stock-locations/get.sh
index f9f88ce530..34c6beb203 100644
--- a/docs/api/admin/code_samples/Shell/admin_stock-locations/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_stock-locations/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/stock-locations' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/stock-locations' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_stock-locations/post.sh b/docs/api/admin/code_samples/Shell/admin_stock-locations/post.sh
index 4445fed6bb..9847b60865 100644
--- a/docs/api/admin/code_samples/Shell/admin_stock-locations/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_stock-locations/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/stock-locations' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/stock-locations' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "App"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/delete.sh
index 7e6622c4fa..38013fd84b 100644
--- a/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/stock-locations/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/stock-locations/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/get.sh
index ec108c3a5b..83a0460fb4 100644
--- a/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/stock-locations/{id}' \
---header 'Authorization: Bearer {api_token}' \
+curl 'https://medusa-url.com/admin/stock-locations/{id}' \
+-H 'Authorization: Bearer {api_token}' \
diff --git a/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/post.sh
index 1a75bca338..e3c19a901b 100644
--- a/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_stock-locations_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/stock-locations/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/stock-locations/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "Main Warehouse"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_store/get.sh b/docs/api/admin/code_samples/Shell/admin_store/get.sh
index 4e6788bb2b..67be62cc21 100644
--- a/docs/api/admin/code_samples/Shell/admin_store/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_store/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/store' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/store' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_store/post.sh b/docs/api/admin/code_samples/Shell/admin_store/post.sh
index dbd827b84e..30c227bcce 100644
--- a/docs/api/admin/code_samples/Shell/admin_store/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_store/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/store' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/store' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "Medusa Store"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_store_currencies_{code}/delete.sh b/docs/api/admin/code_samples/Shell/admin_store_currencies_{code}/delete.sh
index 9fcd216704..37d596628b 100644
--- a/docs/api/admin/code_samples/Shell/admin_store_currencies_{code}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_store_currencies_{code}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/store/currencies/eur' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/store/currencies/{currency_code}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_store_currencies_{code}/post.sh b/docs/api/admin/code_samples/Shell/admin_store_currencies_{code}/post.sh
index 6728f396d6..167e5cc07b 100644
--- a/docs/api/admin/code_samples/Shell/admin_store_currencies_{code}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_store_currencies_{code}/post.sh
@@ -1,2 +1,2 @@
-curl --location --request POST 'https://medusa-url.com/admin/store/currencies/eur' \
---header 'Authorization: Bearer {api_token}'
+curl -X POST 'https://medusa-url.com/admin/store/currencies/{currency_code}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_store_payment-providers/get.sh b/docs/api/admin/code_samples/Shell/admin_store_payment-providers/get.sh
index ce1d76a1ba..983c7d7b3b 100644
--- a/docs/api/admin/code_samples/Shell/admin_store_payment-providers/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_store_payment-providers/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/store/payment-providers' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/store/payment-providers' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_store_tax-providers/get.sh b/docs/api/admin/code_samples/Shell/admin_store_tax-providers/get.sh
index 994765208e..26e8312a62 100644
--- a/docs/api/admin/code_samples/Shell/admin_store_tax-providers/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_store_tax-providers/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/store/tax-providers' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/store/tax-providers' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_swaps/get.sh b/docs/api/admin/code_samples/Shell/admin_swaps/get.sh
index e59841db91..930bc9d881 100644
--- a/docs/api/admin/code_samples/Shell/admin_swaps/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_swaps/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/swaps' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/swaps' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_swaps_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_swaps_{id}/get.sh
index 46abeeebd4..41cf6e4cf3 100644
--- a/docs/api/admin/code_samples/Shell/admin_swaps_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_swaps_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/swaps/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/swaps/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates/get.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates/get.sh
index c96b101113..59bb10a155 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/tax-rates' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/tax-rates' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates/post.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates/post.sh
index d137d440b2..f648f2d1f3 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/tax-rates' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/tax-rates' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "code": "TEST",
     "name": "New Tax Rate",
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/delete.sh
index ef79c01b3a..6d8c7eca9b 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/tax-rates/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/get.sh
index dbc4c854d4..5b9cd1430f 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/tax-rates/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/tax-rates/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/post.sh
index be7f8b3044..0244452187 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/tax-rates/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "name": "New Tax Rate"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_product-types_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_product-types_batch/delete.sh
index 5b76f970b2..de04426323 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_product-types_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_product-types_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
    "product_types": [
      "{product_type_id}"
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_product-types_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_product-types_batch/post.sh
index 1a9fbf3bd8..743aa8e35b 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_product-types_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_product-types_batch/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
    "product_types": [
      "{product_type_id}"
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_products_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_products_batch/delete.sh
index 94d17024de..e6f440ad47 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_products_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_products_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
    "products": [
      "{product_id}"
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_products_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_products_batch/post.sh
index 56a3c7c1d0..25759b38f4 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_products_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_products_batch/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
    "products": [
      "{product_id}"
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_shipping-options_batch/delete.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_shipping-options_batch/delete.sh
index da28874e62..f70a730252 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_shipping-options_batch/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_shipping-options_batch/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
    "shipping_options": [
      "{shipping_option_id}"
diff --git a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_shipping-options_batch/post.sh b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_shipping-options_batch/post.sh
index 9a4832e4b1..c79ec32cad 100644
--- a/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_shipping-options_batch/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_tax-rates_{id}_shipping-options_batch/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
    "shipping_options": [
      "{shipping_option_id}"
diff --git a/docs/api/admin/code_samples/Shell/admin_uploads/delete.sh b/docs/api/admin/code_samples/Shell/admin_uploads/delete.sh
index 6f97468764..3dfb20b929 100644
--- a/docs/api/admin/code_samples/Shell/admin_uploads/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_uploads/delete.sh
@@ -1,6 +1,6 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/uploads' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X DELETE 'https://medusa-url.com/admin/uploads' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "file_key": "{file_key}"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_uploads/post.sh b/docs/api/admin/code_samples/Shell/admin_uploads/post.sh
index 5efb580f62..6a90131a4a 100644
--- a/docs/api/admin/code_samples/Shell/admin_uploads/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_uploads/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/admin/uploads' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: image/jpeg' \
+curl -X POST 'https://medusa-url.com/admin/uploads' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: image/jpeg' \
 --form 'files=@"<FILE_PATH_1>"' \
 --form 'files=@"<FILE_PATH_1>"'
diff --git a/docs/api/admin/code_samples/Shell/admin_uploads_download-url/post.sh b/docs/api/admin/code_samples/Shell/admin_uploads_download-url/post.sh
index 11f150c77c..a8d9610d32 100644
--- a/docs/api/admin/code_samples/Shell/admin_uploads_download-url/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_uploads_download-url/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/uploads/download-url' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/uploads/download-url' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "file_key": "{file_key}"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_uploads_protected/post.sh b/docs/api/admin/code_samples/Shell/admin_uploads_protected/post.sh
index e3f5e6524e..f01743316a 100644
--- a/docs/api/admin/code_samples/Shell/admin_uploads_protected/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_uploads_protected/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/admin/uploads/protected' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: image/jpeg' \
+curl -X POST 'https://medusa-url.com/admin/uploads/protected' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: image/jpeg' \
 --form 'files=@"<FILE_PATH_1>"' \
 --form 'files=@"<FILE_PATH_1>"'
diff --git a/docs/api/admin/code_samples/Shell/admin_users/get.sh b/docs/api/admin/code_samples/Shell/admin_users/get.sh
index 997a504b9a..d94efb499a 100644
--- a/docs/api/admin/code_samples/Shell/admin_users/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_users/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/users' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/users' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_users/post.sh b/docs/api/admin/code_samples/Shell/admin_users/post.sh
index ad260e50b9..f1209365b5 100644
--- a/docs/api/admin/code_samples/Shell/admin_users/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_users/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/users' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/users' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com",
     "password": "supersecret"
diff --git a/docs/api/admin/code_samples/Shell/admin_users_password-token/post.sh b/docs/api/admin/code_samples/Shell/admin_users_password-token/post.sh
index ca77eb6531..99fa516f9e 100644
--- a/docs/api/admin/code_samples/Shell/admin_users_password-token/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_users_password-token/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/users/password-token' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/users/password-token' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_users_reset-password/post.sh b/docs/api/admin/code_samples/Shell/admin_users_reset-password/post.sh
index 0da3a193c9..d723fa801e 100644
--- a/docs/api/admin/code_samples/Shell/admin_users_reset-password/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_users_reset-password/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/users/reset-password' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/users/reset-password' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "token": "supersecrettoken",
     "password": "supersecret"
diff --git a/docs/api/admin/code_samples/Shell/admin_users_{id}/delete.sh b/docs/api/admin/code_samples/Shell/admin_users_{id}/delete.sh
index 64a27ff124..42b5baae63 100644
--- a/docs/api/admin/code_samples/Shell/admin_users_{id}/delete.sh
+++ b/docs/api/admin/code_samples/Shell/admin_users_{id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/admin/users/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl -X DELETE 'https://medusa-url.com/admin/users/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_users_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_users_{id}/get.sh
index 0f9b191ecd..f65013442f 100644
--- a/docs/api/admin/code_samples/Shell/admin_users_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_users_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/users/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/users/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_users_{id}/post.sh b/docs/api/admin/code_samples/Shell/admin_users_{id}/post.sh
index 4d4cc432ba..f753a79022 100644
--- a/docs/api/admin/code_samples/Shell/admin_users_{id}/post.sh
+++ b/docs/api/admin/code_samples/Shell/admin_users_{id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/admin/users/{id}' \
---header 'Authorization: Bearer {api_token}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/admin/users/{id}' \
+-H 'Authorization: Bearer {api_token}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "first_name": "Marcellus"
 }'
diff --git a/docs/api/admin/code_samples/Shell/admin_variants/get.sh b/docs/api/admin/code_samples/Shell/admin_variants/get.sh
index 15059a495e..5f227422b1 100644
--- a/docs/api/admin/code_samples/Shell/admin_variants/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_variants/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/variants' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/variants' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_variants_{id}/get.sh b/docs/api/admin/code_samples/Shell/admin_variants_{id}/get.sh
index 940e778c5c..bc3cff04f0 100644
--- a/docs/api/admin/code_samples/Shell/admin_variants_{id}/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_variants_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/variants/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/variants/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/code_samples/Shell/admin_variants_{id}_inventory/get.sh b/docs/api/admin/code_samples/Shell/admin_variants_{id}_inventory/get.sh
index 15059a495e..5f227422b1 100644
--- a/docs/api/admin/code_samples/Shell/admin_variants_{id}_inventory/get.sh
+++ b/docs/api/admin/code_samples/Shell/admin_variants_{id}_inventory/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/admin/variants' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/admin/variants' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/admin/components/schemas/Address.yaml b/docs/api/admin/components/schemas/Address.yaml
index d2797dc196..e0aee13932 100644
--- a/docs/api/admin/components/schemas/Address.yaml
+++ b/docs/api/admin/components/schemas/Address.yaml
@@ -1,5 +1,8 @@
 title: Address
-description: An address.
+description: >-
+  An address is used across the Medusa backend within other schemas and object
+  types. For example, a customer's billing and shipping addresses both use the
+  Address entity.
 type: object
 required:
   - address_1
@@ -72,7 +75,8 @@ properties:
       description: See a list of codes.
     example: st
   country:
-    description: A country object. Available if the relation `country` is expanded.
+    description: A country object.
+    x-expandable: country
     nullable: true
     $ref: ./Country.yaml
   province:
@@ -109,3 +113,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminAppsListRes.yaml b/docs/api/admin/components/schemas/AdminAppsListRes.yaml
index f145982e38..8e153ad3a1 100644
--- a/docs/api/admin/components/schemas/AdminAppsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminAppsListRes.yaml
@@ -4,5 +4,6 @@ required:
 properties:
   apps:
     type: array
+    description: An array of app details.
     items:
       $ref: ./OAuth.yaml
diff --git a/docs/api/admin/components/schemas/AdminAppsRes.yaml b/docs/api/admin/components/schemas/AdminAppsRes.yaml
index 9ccc85746f..8fa25e62de 100644
--- a/docs/api/admin/components/schemas/AdminAppsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminAppsRes.yaml
@@ -3,4 +3,5 @@ required:
   - apps
 properties:
   apps:
+    description: App details.
     $ref: ./OAuth.yaml
diff --git a/docs/api/admin/components/schemas/AdminAuthRes.yaml b/docs/api/admin/components/schemas/AdminAuthRes.yaml
index 1b473f3131..f5834ed1e0 100644
--- a/docs/api/admin/components/schemas/AdminAuthRes.yaml
+++ b/docs/api/admin/components/schemas/AdminAuthRes.yaml
@@ -3,4 +3,5 @@ required:
   - user
 properties:
   user:
+    description: User details.
     $ref: ./User.yaml
diff --git a/docs/api/admin/components/schemas/AdminBatchJobListRes.yaml b/docs/api/admin/components/schemas/AdminBatchJobListRes.yaml
index 81194ab56b..52fece9150 100644
--- a/docs/api/admin/components/schemas/AdminBatchJobListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminBatchJobListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   batch_jobs:
     type: array
+    description: An array of batch job details.
     items:
       $ref: ./BatchJob.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of batch jobs skipped when retrieving the batch jobs.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminBatchJobRes.yaml b/docs/api/admin/components/schemas/AdminBatchJobRes.yaml
index 5148d7f665..eed89446c7 100644
--- a/docs/api/admin/components/schemas/AdminBatchJobRes.yaml
+++ b/docs/api/admin/components/schemas/AdminBatchJobRes.yaml
@@ -3,4 +3,5 @@ required:
   - batch_job
 properties:
   batch_job:
+    description: Batch job details.
     $ref: ./BatchJob.yaml
diff --git a/docs/api/admin/components/schemas/AdminCollectionsListRes.yaml b/docs/api/admin/components/schemas/AdminCollectionsListRes.yaml
index 32822ecdb6..9a61e4fa9c 100644
--- a/docs/api/admin/components/schemas/AdminCollectionsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminCollectionsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   collections:
     type: array
+    description: an array of collection details
     items:
       $ref: ./ProductCollection.yaml
   count:
@@ -14,7 +15,9 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: >-
+      The number of product collections skipped when retrieving the product
+      collections.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminCollectionsRes.yaml b/docs/api/admin/components/schemas/AdminCollectionsRes.yaml
index c5b626189c..acb25a9335 100644
--- a/docs/api/admin/components/schemas/AdminCollectionsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminCollectionsRes.yaml
@@ -7,4 +7,5 @@ required:
   - collection
 properties:
   collection:
+    type: Product Collection details.
     $ref: ./ProductCollection.yaml
diff --git a/docs/api/admin/components/schemas/AdminCreateUserRequest.yaml b/docs/api/admin/components/schemas/AdminCreateUserRequest.yaml
index e725065733..df3db57b09 100644
--- a/docs/api/admin/components/schemas/AdminCreateUserRequest.yaml
+++ b/docs/api/admin/components/schemas/AdminCreateUserRequest.yaml
@@ -4,23 +4,25 @@ required:
   - password
 properties:
   email:
-    description: The Users email.
+    description: The User's email.
     type: string
     format: email
   first_name:
-    description: The name of the User.
+    description: The first name of the User.
     type: string
   last_name:
-    description: The name of the User.
+    description: The last name of the User.
     type: string
   role:
-    description: Userrole assigned to the user.
+    description: >-
+      The role assigned to the user. These roles don't provide any different
+      privileges.
     type: string
     enum:
       - admin
       - member
       - developer
   password:
-    description: The Users password.
+    description: The User's password.
     type: string
     format: password
diff --git a/docs/api/admin/components/schemas/AdminCurrenciesListRes.yaml b/docs/api/admin/components/schemas/AdminCurrenciesListRes.yaml
index f4dd293fef..b912955581 100644
--- a/docs/api/admin/components/schemas/AdminCurrenciesListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminCurrenciesListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   currencies:
     type: array
+    description: An array of currency details.
     items:
       $ref: ./Currency.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of currencies skipped when retrieving the currencies.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminCurrenciesRes.yaml b/docs/api/admin/components/schemas/AdminCurrenciesRes.yaml
index 0dce871edf..25c62e87f6 100644
--- a/docs/api/admin/components/schemas/AdminCurrenciesRes.yaml
+++ b/docs/api/admin/components/schemas/AdminCurrenciesRes.yaml
@@ -3,4 +3,5 @@ required:
   - currency
 properties:
   currency:
+    description: Currency details.
     $ref: ./Currency.yaml
diff --git a/docs/api/admin/components/schemas/AdminCustomerGroupsListRes.yaml b/docs/api/admin/components/schemas/AdminCustomerGroupsListRes.yaml
index 13c74d86ac..c776bf16a7 100644
--- a/docs/api/admin/components/schemas/AdminCustomerGroupsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminCustomerGroupsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   customer_groups:
     type: array
+    description: An array of customer group details.
     items:
       $ref: ./CustomerGroup.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of customer groups skipped when retrieving the customer groups.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminCustomerGroupsRes.yaml b/docs/api/admin/components/schemas/AdminCustomerGroupsRes.yaml
index 2e324ec54c..dc4382b13c 100644
--- a/docs/api/admin/components/schemas/AdminCustomerGroupsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminCustomerGroupsRes.yaml
@@ -3,4 +3,5 @@ required:
   - customer_group
 properties:
   customer_group:
+    description: Customer group details.
     $ref: ./CustomerGroup.yaml
diff --git a/docs/api/admin/components/schemas/AdminCustomersListRes.yaml b/docs/api/admin/components/schemas/AdminCustomersListRes.yaml
index 531a0a23d7..7d345090bf 100644
--- a/docs/api/admin/components/schemas/AdminCustomersListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminCustomersListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   customers:
     type: array
+    description: An array of customer details.
     items:
       $ref: ./Customer.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of customers skipped when retrieving the customers.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminCustomersRes.yaml b/docs/api/admin/components/schemas/AdminCustomersRes.yaml
index 7bcdcd6186..c44155d3fd 100644
--- a/docs/api/admin/components/schemas/AdminCustomersRes.yaml
+++ b/docs/api/admin/components/schemas/AdminCustomersRes.yaml
@@ -8,4 +8,5 @@ required:
   - customer
 properties:
   customer:
+    description: Customer details.
     $ref: ./Customer.yaml
diff --git a/docs/api/admin/components/schemas/AdminDeleteDiscountsDiscountConditionsConditionBatchReq.yaml b/docs/api/admin/components/schemas/AdminDeleteDiscountsDiscountConditionsConditionBatchReq.yaml
index 02b1e9b06f..8cbf27f590 100644
--- a/docs/api/admin/components/schemas/AdminDeleteDiscountsDiscountConditionsConditionBatchReq.yaml
+++ b/docs/api/admin/components/schemas/AdminDeleteDiscountsDiscountConditionsConditionBatchReq.yaml
@@ -3,7 +3,7 @@ required:
   - resources
 properties:
   resources:
-    description: The resources to be deleted from the discount condition
+    description: The resources to be removed from the discount condition
     type: array
     items:
       type: object
diff --git a/docs/api/admin/components/schemas/AdminDeletePriceListPricesPricesReq.yaml b/docs/api/admin/components/schemas/AdminDeletePriceListPricesPricesReq.yaml
index 0b1e797641..43b788bdf6 100644
--- a/docs/api/admin/components/schemas/AdminDeletePriceListPricesPricesReq.yaml
+++ b/docs/api/admin/components/schemas/AdminDeletePriceListPricesPricesReq.yaml
@@ -1,7 +1,7 @@
 type: object
 properties:
   price_ids:
-    description: The price id's of the Money Amounts to delete.
+    description: The price IDs of the Money Amounts to delete.
     type: array
     items:
       type: string
diff --git a/docs/api/admin/components/schemas/AdminDeleteProductsFromCollectionRes.yaml b/docs/api/admin/components/schemas/AdminDeleteProductsFromCollectionRes.yaml
index c42a782b07..363119f0d4 100644
--- a/docs/api/admin/components/schemas/AdminDeleteProductsFromCollectionRes.yaml
+++ b/docs/api/admin/components/schemas/AdminDeleteProductsFromCollectionRes.yaml
@@ -15,5 +15,5 @@ properties:
     description: The IDs of the products removed from the collection
     type: array
     items:
-      description: The ID of a Product to add to the Product Collection.
+      description: The ID of the Product removed from the Product Collection.
       type: string
diff --git a/docs/api/admin/components/schemas/AdminDeletePublishableApiKeySalesChannelsBatchReq.yaml b/docs/api/admin/components/schemas/AdminDeletePublishableApiKeySalesChannelsBatchReq.yaml
index 4fb1c786f2..992882d4df 100644
--- a/docs/api/admin/components/schemas/AdminDeletePublishableApiKeySalesChannelsBatchReq.yaml
+++ b/docs/api/admin/components/schemas/AdminDeletePublishableApiKeySalesChannelsBatchReq.yaml
@@ -3,7 +3,7 @@ required:
   - sales_channel_ids
 properties:
   sales_channel_ids:
-    description: The IDs of the sales channels to delete from the publishable api key
+    description: The IDs of the sales channels to remove from the publishable API key
     type: array
     items:
       type: object
diff --git a/docs/api/admin/components/schemas/AdminDeleteSalesChannelsChannelProductsBatchReq.yaml b/docs/api/admin/components/schemas/AdminDeleteSalesChannelsChannelProductsBatchReq.yaml
index 176d203729..3526ff5c59 100644
--- a/docs/api/admin/components/schemas/AdminDeleteSalesChannelsChannelProductsBatchReq.yaml
+++ b/docs/api/admin/components/schemas/AdminDeleteSalesChannelsChannelProductsBatchReq.yaml
@@ -3,7 +3,7 @@ required:
   - product_ids
 properties:
   product_ids:
-    description: The IDs of the products to delete from the Sales Channel.
+    description: The IDs of the products to remove from the Sales Channel.
     type: array
     items:
       type: object
diff --git a/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateProductTypesReq.yaml b/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateProductTypesReq.yaml
index 499a433451..fc4d2ffb89 100644
--- a/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateProductTypesReq.yaml
+++ b/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateProductTypesReq.yaml
@@ -4,6 +4,8 @@ required:
 properties:
   product_types:
     type: array
-    description: The IDs of the types of products to remove association with this tax rate
+    description: >-
+      The IDs of the product types to remove their association with this tax
+      rate.
     items:
       type: string
diff --git a/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateProductsReq.yaml b/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateProductsReq.yaml
index 9e8ca198b0..e3036f7e2d 100644
--- a/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateProductsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateProductsReq.yaml
@@ -4,6 +4,6 @@ required:
 properties:
   products:
     type: array
-    description: The IDs of the products to remove association with this tax rate
+    description: The IDs of the products to remove their association with this tax rate.
     items:
       type: string
diff --git a/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateShippingOptionsReq.yaml b/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateShippingOptionsReq.yaml
index b3c0433aae..a870e114ea 100644
--- a/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateShippingOptionsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminDeleteTaxRatesTaxRateShippingOptionsReq.yaml
@@ -4,6 +4,8 @@ required:
 properties:
   shipping_options:
     type: array
-    description: The IDs of the shipping options to remove association with this tax rate
+    description: >-
+      The IDs of the shipping options to remove their association with this tax
+      rate.
     items:
       type: string
diff --git a/docs/api/admin/components/schemas/AdminDiscountConditionsDeleteRes.yaml b/docs/api/admin/components/schemas/AdminDiscountConditionsDeleteRes.yaml
index 189b8eb0cc..f6fd7e7001 100644
--- a/docs/api/admin/components/schemas/AdminDiscountConditionsDeleteRes.yaml
+++ b/docs/api/admin/components/schemas/AdminDiscountConditionsDeleteRes.yaml
@@ -7,15 +7,15 @@ required:
 properties:
   id:
     type: string
-    description: The ID of the deleted DiscountCondition
+    description: The ID of the deleted Discount Condition
   object:
     type: string
     description: The type of the object that was deleted.
     default: discount-condition
   deleted:
     type: boolean
-    description: Whether the discount condition was deleted successfully or not.
+    description: Whether the discount condition was deleted successfully.
     default: true
   discount:
-    description: The Discount to which the condition used to belong
+    description: The Discount to which the condition used to belong to.
     $ref: ./Discount.yaml
diff --git a/docs/api/admin/components/schemas/AdminDiscountConditionsRes.yaml b/docs/api/admin/components/schemas/AdminDiscountConditionsRes.yaml
index 0e77e73048..1afadae4db 100644
--- a/docs/api/admin/components/schemas/AdminDiscountConditionsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminDiscountConditionsRes.yaml
@@ -7,4 +7,5 @@ required:
   - discount_condition
 properties:
   discount_condition:
+    description: Discount condition details.
     $ref: ./DiscountCondition.yaml
diff --git a/docs/api/admin/components/schemas/AdminDiscountsDeleteRes.yaml b/docs/api/admin/components/schemas/AdminDiscountsDeleteRes.yaml
index d0b4c29790..d8db1a7a73 100644
--- a/docs/api/admin/components/schemas/AdminDiscountsDeleteRes.yaml
+++ b/docs/api/admin/components/schemas/AdminDiscountsDeleteRes.yaml
@@ -13,5 +13,5 @@ properties:
     default: discount
   deleted:
     type: boolean
-    description: Whether the discount was deleted successfully or not.
+    description: Whether the discount was deleted successfully.
     default: true
diff --git a/docs/api/admin/components/schemas/AdminDiscountsListRes.yaml b/docs/api/admin/components/schemas/AdminDiscountsListRes.yaml
index 981118a2c0..b0e26427a7 100644
--- a/docs/api/admin/components/schemas/AdminDiscountsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminDiscountsListRes.yaml
@@ -21,7 +21,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of discounts skipped when retrieving the discounts.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminDiscountsRes.yaml b/docs/api/admin/components/schemas/AdminDiscountsRes.yaml
index b52dcf4784..7a7a49f4e1 100644
--- a/docs/api/admin/components/schemas/AdminDiscountsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminDiscountsRes.yaml
@@ -13,4 +13,5 @@ required:
   - discount
 properties:
   discount:
+    description: Discount details.
     $ref: ./Discount.yaml
diff --git a/docs/api/admin/components/schemas/AdminDraftOrdersDeleteRes.yaml b/docs/api/admin/components/schemas/AdminDraftOrdersDeleteRes.yaml
index 542765dfed..b92534f839 100644
--- a/docs/api/admin/components/schemas/AdminDraftOrdersDeleteRes.yaml
+++ b/docs/api/admin/components/schemas/AdminDraftOrdersDeleteRes.yaml
@@ -13,5 +13,5 @@ properties:
     default: draft-order
   deleted:
     type: boolean
-    description: Whether the draft order was deleted successfully or not.
+    description: Whether the draft order was deleted successfully.
     default: true
diff --git a/docs/api/admin/components/schemas/AdminDraftOrdersListRes.yaml b/docs/api/admin/components/schemas/AdminDraftOrdersListRes.yaml
index 134f839693..4bf28364f3 100644
--- a/docs/api/admin/components/schemas/AdminDraftOrdersListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminDraftOrdersListRes.yaml
@@ -14,6 +14,7 @@ required:
 properties:
   draft_orders:
     type: array
+    description: An array of draft order's details.
     items:
       $ref: ./DraftOrder.yaml
   count:
@@ -21,7 +22,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of draft orders skipped when retrieving the draft orders.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminDraftOrdersRes.yaml b/docs/api/admin/components/schemas/AdminDraftOrdersRes.yaml
index 5a495eeb2d..19365b254d 100644
--- a/docs/api/admin/components/schemas/AdminDraftOrdersRes.yaml
+++ b/docs/api/admin/components/schemas/AdminDraftOrdersRes.yaml
@@ -32,6 +32,7 @@ x-expanded-relations:
     - cart.items.tax_lines
     - cart.items.variant
     - cart.items.variant.product
+    - cart.items.variant.product.profiles
     - cart.region
     - cart.region.tax_rates
     - cart.shipping_address
@@ -61,4 +62,5 @@ required:
   - draft_order
 properties:
   draft_order:
+    description: Draft order's details.
     $ref: ./DraftOrder.yaml
diff --git a/docs/api/admin/components/schemas/AdminExtendedStoresRes.yaml b/docs/api/admin/components/schemas/AdminExtendedStoresRes.yaml
index 8b3e0894c2..a0eddd2063 100644
--- a/docs/api/admin/components/schemas/AdminExtendedStoresRes.yaml
+++ b/docs/api/admin/components/schemas/AdminExtendedStoresRes.yaml
@@ -8,4 +8,5 @@ required:
   - store
 properties:
   store:
+    description: Store details.
     $ref: ./ExtendedStoreDTO.yaml
diff --git a/docs/api/admin/components/schemas/AdminGetRegionsRegionFulfillmentOptionsRes.yaml b/docs/api/admin/components/schemas/AdminGetRegionsRegionFulfillmentOptionsRes.yaml
index e26d1debe0..c62c12a07c 100644
--- a/docs/api/admin/components/schemas/AdminGetRegionsRegionFulfillmentOptionsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminGetRegionsRegionFulfillmentOptionsRes.yaml
@@ -4,6 +4,7 @@ required:
 properties:
   fulfillment_options:
     type: array
+    description: Fulfillment providers details.
     items:
       type: object
       required:
diff --git a/docs/api/admin/components/schemas/AdminGetVariantsVariantInventoryRes.yaml b/docs/api/admin/components/schemas/AdminGetVariantsVariantInventoryRes.yaml
index f055f06413..1c72e73f56 100644
--- a/docs/api/admin/components/schemas/AdminGetVariantsVariantInventoryRes.yaml
+++ b/docs/api/admin/components/schemas/AdminGetVariantsVariantInventoryRes.yaml
@@ -2,4 +2,5 @@ type: object
 properties:
   variant:
     type: object
+    description: The product variant's.
     $ref: ./VariantInventory.yaml
diff --git a/docs/api/admin/components/schemas/AdminGiftCardsDeleteRes.yaml b/docs/api/admin/components/schemas/AdminGiftCardsDeleteRes.yaml
index 6f113a2ed4..2c6792ccee 100644
--- a/docs/api/admin/components/schemas/AdminGiftCardsDeleteRes.yaml
+++ b/docs/api/admin/components/schemas/AdminGiftCardsDeleteRes.yaml
@@ -13,5 +13,5 @@ properties:
     default: gift-card
   deleted:
     type: boolean
-    description: Whether the gift card was deleted successfully or not.
+    description: Whether the gift card was deleted successfully.
     default: true
diff --git a/docs/api/admin/components/schemas/AdminGiftCardsListRes.yaml b/docs/api/admin/components/schemas/AdminGiftCardsListRes.yaml
index 1df6eafb6f..ed0e6d8125 100644
--- a/docs/api/admin/components/schemas/AdminGiftCardsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminGiftCardsListRes.yaml
@@ -22,7 +22,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of gift cards skipped when retrieving the gift cards.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminGiftCardsRes.yaml b/docs/api/admin/components/schemas/AdminGiftCardsRes.yaml
index 90e4caf50d..4911078159 100644
--- a/docs/api/admin/components/schemas/AdminGiftCardsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminGiftCardsRes.yaml
@@ -11,4 +11,5 @@ required:
   - gift_card
 properties:
   gift_card:
+    description: A gift card's details.
     $ref: ./GiftCard.yaml
diff --git a/docs/api/admin/components/schemas/AdminInventoryItemsListRes.yaml b/docs/api/admin/components/schemas/AdminInventoryItemsListRes.yaml
index 4f87fd6629..facac5fb99 100644
--- a/docs/api/admin/components/schemas/AdminInventoryItemsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminInventoryItemsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   inventory_items:
     type: array
+    description: an array of Inventory Item details
     items:
       $ref: ./InventoryItemDTO.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of inventory items skipped when retrieving the inventory items.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminInventoryItemsListWithVariantsAndLocationLevelsRes.yaml b/docs/api/admin/components/schemas/AdminInventoryItemsListWithVariantsAndLocationLevelsRes.yaml
index 366aa8b84d..0a8a0fcd33 100644
--- a/docs/api/admin/components/schemas/AdminInventoryItemsListWithVariantsAndLocationLevelsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminInventoryItemsListWithVariantsAndLocationLevelsRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   inventory_items:
     type: array
+    description: an array of Inventory Item details
     items:
       $ref: ./DecoratedInventoryItemDTO.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of inventory items skipped when retrieving the inventory items.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminInventoryItemsRes.yaml b/docs/api/admin/components/schemas/AdminInventoryItemsRes.yaml
index dacf72e622..c876c27e0d 100644
--- a/docs/api/admin/components/schemas/AdminInventoryItemsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminInventoryItemsRes.yaml
@@ -3,4 +3,5 @@ required:
   - inventory_item
 properties:
   inventory_item:
+    description: Inventory Item details
     $ref: ./InventoryItemDTO.yaml
diff --git a/docs/api/admin/components/schemas/AdminInviteDeleteRes.yaml b/docs/api/admin/components/schemas/AdminInviteDeleteRes.yaml
index d0a91ac8b7..c1a8947cd4 100644
--- a/docs/api/admin/components/schemas/AdminInviteDeleteRes.yaml
+++ b/docs/api/admin/components/schemas/AdminInviteDeleteRes.yaml
@@ -13,5 +13,5 @@ properties:
     default: invite
   deleted:
     type: boolean
-    description: Whether or not the Invite was deleted.
+    description: Whether or not the invite was deleted.
     default: true
diff --git a/docs/api/admin/components/schemas/AdminListInvitesRes.yaml b/docs/api/admin/components/schemas/AdminListInvitesRes.yaml
index 264a1b4e90..f9f4b9fca1 100644
--- a/docs/api/admin/components/schemas/AdminListInvitesRes.yaml
+++ b/docs/api/admin/components/schemas/AdminListInvitesRes.yaml
@@ -4,5 +4,6 @@ required:
 properties:
   invites:
     type: array
+    description: An array of invites
     items:
       $ref: ./Invite.yaml
diff --git a/docs/api/admin/components/schemas/AdminNotesListRes.yaml b/docs/api/admin/components/schemas/AdminNotesListRes.yaml
index 9721914a0e..cf9e5ff664 100644
--- a/docs/api/admin/components/schemas/AdminNotesListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminNotesListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   notes:
     type: array
+    description: An array of notes
     items:
       $ref: ./Note.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of notes skipped when retrieving the notes.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminNotesRes.yaml b/docs/api/admin/components/schemas/AdminNotesRes.yaml
index 1f495bf7c7..acd2598e9b 100644
--- a/docs/api/admin/components/schemas/AdminNotesRes.yaml
+++ b/docs/api/admin/components/schemas/AdminNotesRes.yaml
@@ -3,4 +3,5 @@ required:
   - note
 properties:
   note:
+    description: Note details.
     $ref: ./Note.yaml
diff --git a/docs/api/admin/components/schemas/AdminNotificationsListRes.yaml b/docs/api/admin/components/schemas/AdminNotificationsListRes.yaml
index ef38b0fcaa..1cc05a0a14 100644
--- a/docs/api/admin/components/schemas/AdminNotificationsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminNotificationsListRes.yaml
@@ -8,6 +8,7 @@ required:
 properties:
   notifications:
     type: array
+    description: an array of notifications
     items:
       $ref: ./Notification.yaml
   count:
@@ -15,7 +16,7 @@ properties:
     description: The total number of notifications
   offset:
     type: integer
-    description: The number of notifications skipped before these notifications
+    description: The number of notifications skipped when retrieving the notifications.
   limit:
     type: integer
     description: The number of notifications per page
diff --git a/docs/api/admin/components/schemas/AdminNotificationsRes.yaml b/docs/api/admin/components/schemas/AdminNotificationsRes.yaml
index b3b370452f..8ecc76a011 100644
--- a/docs/api/admin/components/schemas/AdminNotificationsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminNotificationsRes.yaml
@@ -7,4 +7,5 @@ required:
   - notification
 properties:
   notification:
+    description: Notification details
     $ref: ./Notification.yaml
diff --git a/docs/api/admin/components/schemas/AdminOrderEditsListRes.yaml b/docs/api/admin/components/schemas/AdminOrderEditsListRes.yaml
index efa37a0fca..c308a79b1f 100644
--- a/docs/api/admin/components/schemas/AdminOrderEditsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminOrderEditsListRes.yaml
@@ -42,6 +42,7 @@ required:
 properties:
   order_edits:
     type: array
+    description: An array of order edit details
     items:
       $ref: ./OrderEdit.yaml
   count:
@@ -49,7 +50,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of order edits skipped when retrieving the order edits.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminOrderEditsRes.yaml b/docs/api/admin/components/schemas/AdminOrderEditsRes.yaml
index 4f5087710f..b1a5813f06 100644
--- a/docs/api/admin/components/schemas/AdminOrderEditsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminOrderEditsRes.yaml
@@ -38,4 +38,5 @@ required:
   - order_edit
 properties:
   order_edit:
+    description: Order edit details
     $ref: ./OrderEdit.yaml
diff --git a/docs/api/admin/components/schemas/AdminOrdersListRes.yaml b/docs/api/admin/components/schemas/AdminOrdersListRes.yaml
index d9331dd990..ff363d4520 100644
--- a/docs/api/admin/components/schemas/AdminOrdersListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminOrdersListRes.yaml
@@ -58,6 +58,7 @@ x-expanded-relations:
     - items.tax_lines
     - items.variant
     - items.variant.product
+    - items.variant.product.profiles
     - refunds
     - region
     - shipping_methods
@@ -110,6 +111,7 @@ required:
 properties:
   orders:
     type: array
+    description: An array of order details.
     items:
       $ref: ./Order.yaml
   count:
@@ -117,7 +119,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of orders skipped when retrieving the orders.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminOrdersOrderLineItemReservationReq.yaml b/docs/api/admin/components/schemas/AdminOrdersOrderLineItemReservationReq.yaml
index afd23c7204..c8713b6be9 100644
--- a/docs/api/admin/components/schemas/AdminOrdersOrderLineItemReservationReq.yaml
+++ b/docs/api/admin/components/schemas/AdminOrdersOrderLineItemReservationReq.yaml
@@ -3,7 +3,7 @@ required:
   - location_id
 properties:
   location_id:
-    description: The id of the location of the reservation
+    description: The ID of the location of the reservation
     type: string
   quantity:
     description: The quantity to reserve
diff --git a/docs/api/admin/components/schemas/AdminOrdersRes.yaml b/docs/api/admin/components/schemas/AdminOrdersRes.yaml
index 020e86f931..def46daae7 100644
--- a/docs/api/admin/components/schemas/AdminOrdersRes.yaml
+++ b/docs/api/admin/components/schemas/AdminOrdersRes.yaml
@@ -58,6 +58,7 @@ x-expanded-relations:
     - items.tax_lines
     - items.variant
     - items.variant.product
+    - items.variant.product.profiles
     - refunds
     - region
     - shipping_methods
@@ -106,4 +107,5 @@ required:
   - order
 properties:
   order:
+    description: Order details.
     $ref: ./Order.yaml
diff --git a/docs/api/admin/components/schemas/AdminPaymentCollectionsRes.yaml b/docs/api/admin/components/schemas/AdminPaymentCollectionsRes.yaml
index 6b57258c43..3c4502a811 100644
--- a/docs/api/admin/components/schemas/AdminPaymentCollectionsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPaymentCollectionsRes.yaml
@@ -12,4 +12,5 @@ required:
   - payment_collection
 properties:
   payment_collection:
+    description: Payment Collection details.
     $ref: ./PaymentCollection.yaml
diff --git a/docs/api/admin/components/schemas/AdminPaymentProvidersList.yaml b/docs/api/admin/components/schemas/AdminPaymentProvidersList.yaml
index db6385af46..5f706026af 100644
--- a/docs/api/admin/components/schemas/AdminPaymentProvidersList.yaml
+++ b/docs/api/admin/components/schemas/AdminPaymentProvidersList.yaml
@@ -4,5 +4,6 @@ required:
 properties:
   payment_providers:
     type: array
+    description: An array of payment providers details.
     items:
       $ref: ./PaymentProvider.yaml
diff --git a/docs/api/admin/components/schemas/AdminPaymentRes.yaml b/docs/api/admin/components/schemas/AdminPaymentRes.yaml
index cba9949004..4e812a9072 100644
--- a/docs/api/admin/components/schemas/AdminPaymentRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPaymentRes.yaml
@@ -3,4 +3,5 @@ required:
   - payment
 properties:
   payment:
+    description: Payment details
     $ref: ./Payment.yaml
diff --git a/docs/api/admin/components/schemas/AdminPostAppsReq.yaml b/docs/api/admin/components/schemas/AdminPostAppsReq.yaml
index 91cda2d7de..62016f8b7b 100644
--- a/docs/api/admin/components/schemas/AdminPostAppsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostAppsReq.yaml
@@ -6,7 +6,7 @@ required:
 properties:
   application_name:
     type: string
-    description: Name of the application for the token to be generated for.
+    description: Name of the application for to generate the token for.
   state:
     type: string
     description: State of the application.
diff --git a/docs/api/admin/components/schemas/AdminPostAuthReq.yaml b/docs/api/admin/components/schemas/AdminPostAuthReq.yaml
index 2d945cc366..a70918cded 100644
--- a/docs/api/admin/components/schemas/AdminPostAuthReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostAuthReq.yaml
@@ -5,9 +5,9 @@ required:
 properties:
   email:
     type: string
-    description: The User's email.
+    description: The user's email.
     format: email
   password:
     type: string
-    description: The User's password.
+    description: The user's password.
     format: password
diff --git a/docs/api/admin/components/schemas/AdminPostBatchesReq.yaml b/docs/api/admin/components/schemas/AdminPostBatchesReq.yaml
index 2e52f9c9ee..ab6f9a5afc 100644
--- a/docs/api/admin/components/schemas/AdminPostBatchesReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostBatchesReq.yaml
@@ -5,7 +5,9 @@ required:
 properties:
   type:
     type: string
-    description: The type of batch job to start.
+    description: >-
+      The type of batch job to start, which is defined by the `batchType`
+      property of the associated batch job strategy.
     example: product-export
   context:
     type: object
@@ -29,6 +31,6 @@ properties:
   dry_run:
     type: boolean
     description: >-
-      Set a batch job in dry_run mode to get some information on what will be
-      done without applying any modifications.
+      Set a batch job in dry_run mode, which would delay executing the batch job
+      until it's confirmed.
     default: false
diff --git a/docs/api/admin/components/schemas/AdminPostCollectionsCollectionReq.yaml b/docs/api/admin/components/schemas/AdminPostCollectionsCollectionReq.yaml
index 95e7bb1f33..481f005f4d 100644
--- a/docs/api/admin/components/schemas/AdminPostCollectionsCollectionReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostCollectionsCollectionReq.yaml
@@ -2,12 +2,16 @@ type: object
 properties:
   title:
     type: string
-    description: The title to identify the Collection by.
+    description: The title of the collection.
   handle:
     type: string
     description: >-
-      An optional handle to be used in slugs, if none is provided we will
-      kebab-case the title.
+      An optional handle to be used in slugs. If none is provided, the
+      kebab-case version of the title will be used.
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostCollectionsReq.yaml b/docs/api/admin/components/schemas/AdminPostCollectionsReq.yaml
index 23edc85cc8..fb7b5921b7 100644
--- a/docs/api/admin/components/schemas/AdminPostCollectionsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostCollectionsReq.yaml
@@ -4,12 +4,16 @@ required:
 properties:
   title:
     type: string
-    description: The title to identify the Collection by.
+    description: The title of the collection.
   handle:
     type: string
     description: >-
-      An optional handle to be used in slugs, if none is provided we will
-      kebab-case the title.
+      An optional handle to be used in slugs. If none is provided, the
+      kebab-case version of the title will be used.
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostCurrenciesCurrencyReq.yaml b/docs/api/admin/components/schemas/AdminPostCurrenciesCurrencyReq.yaml
index 4c168fc38a..2d7ac5b299 100644
--- a/docs/api/admin/components/schemas/AdminPostCurrenciesCurrencyReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostCurrenciesCurrencyReq.yaml
@@ -2,4 +2,5 @@ type: object
 properties:
   includes_tax:
     type: boolean
-    description: '[EXPERIMENTAL] Tax included in prices of currency.'
+    x-featureFlag: tax_inclusive_pricing
+    description: Tax included in prices of currency.
diff --git a/docs/api/admin/components/schemas/AdminPostCustomerGroupsGroupReq.yaml b/docs/api/admin/components/schemas/AdminPostCustomerGroupsGroupReq.yaml
index 8f647d1e83..af9b08076a 100644
--- a/docs/api/admin/components/schemas/AdminPostCustomerGroupsGroupReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostCustomerGroupsGroupReq.yaml
@@ -4,5 +4,9 @@ properties:
     description: Name of the customer group
     type: string
   metadata:
-    description: Metadata for the customer.
+    description: Metadata of the customer group.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostCustomerGroupsReq.yaml b/docs/api/admin/components/schemas/AdminPostCustomerGroupsReq.yaml
index 1d5988ff67..a806ec5939 100644
--- a/docs/api/admin/components/schemas/AdminPostCustomerGroupsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostCustomerGroupsReq.yaml
@@ -7,4 +7,8 @@ properties:
     description: Name of the customer group
   metadata:
     type: object
-    description: Metadata for the customer.
+    description: Metadata of the customer group.
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostCustomersCustomerReq.yaml b/docs/api/admin/components/schemas/AdminPostCustomersCustomerReq.yaml
index 9a4edf247c..a47388fb14 100644
--- a/docs/api/admin/components/schemas/AdminPostCustomersCustomerReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostCustomersCustomerReq.yaml
@@ -19,6 +19,7 @@ properties:
     format: password
   groups:
     type: array
+    description: A list of customer groups to which the customer belongs.
     items:
       type: object
       required:
@@ -27,7 +28,10 @@ properties:
         id:
           description: The ID of a customer group
           type: string
-    description: A list of customer groups to which the customer belongs.
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostCustomersReq.yaml b/docs/api/admin/components/schemas/AdminPostCustomersReq.yaml
index 250c211fb5..00889d8f5b 100644
--- a/docs/api/admin/components/schemas/AdminPostCustomersReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostCustomersReq.yaml
@@ -25,3 +25,7 @@ properties:
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostDiscountsDiscountConditions.yaml b/docs/api/admin/components/schemas/AdminPostDiscountsDiscountConditions.yaml
index f510e4b7f2..767bd96f4c 100644
--- a/docs/api/admin/components/schemas/AdminPostDiscountsDiscountConditions.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDiscountsDiscountConditions.yaml
@@ -3,35 +3,38 @@ required:
   - operator
 properties:
   operator:
-    description: Operator of the condition
+    description: >-
+      Operator of the condition. `in` indicates that discountable resources are
+      within the specified resources. `not_in` indicates that discountable
+      resources are everything but the specified resources.
     type: string
     enum:
       - in
       - not_in
   products:
     type: array
-    description: list of product IDs if the condition is applied on products.
+    description: list of product IDs if the condition's type is `products`.
     items:
       type: string
   product_types:
     type: array
-    description: list of product type IDs if the condition is applied on product types.
+    description: list of product type IDs if the condition's type is `product_types`.
     items:
       type: string
   product_collections:
     type: array
     description: >-
-      list of product collection IDs if the condition is applied on product
-      collections.
+      list of product collection IDs if the condition's type is
+      `product_collections`.
     items:
       type: string
   product_tags:
     type: array
-    description: list of product tag IDs if the condition is applied on product tags.
+    description: list of product tag IDs if the condition's type is `product_tags`.
     items:
       type: string
   customer_groups:
     type: array
-    description: list of customer group IDs if the condition is applied on customer groups.
+    description: list of customer group IDs if the condition's type is `customer_groups`.
     items:
       type: string
diff --git a/docs/api/admin/components/schemas/AdminPostDiscountsDiscountConditionsCondition.yaml b/docs/api/admin/components/schemas/AdminPostDiscountsDiscountConditionsCondition.yaml
index 7e6f366712..23b5daf95d 100644
--- a/docs/api/admin/components/schemas/AdminPostDiscountsDiscountConditionsCondition.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDiscountsDiscountConditionsCondition.yaml
@@ -2,28 +2,28 @@ type: object
 properties:
   products:
     type: array
-    description: list of product IDs if the condition is applied on products.
+    description: list of product IDs if the condition's type is `products`.
     items:
       type: string
   product_types:
     type: array
-    description: list of product type IDs if the condition is applied on product types.
+    description: list of product type IDs if the condition's type is `product_types`.
     items:
       type: string
   product_collections:
     type: array
     description: >-
-      list of product collection IDs if the condition is applied on product
-      collections.
+      list of product collection IDs if the condition's type is
+      `product_collections`.
     items:
       type: string
   product_tags:
     type: array
-    description: list of product tag IDs if the condition is applied on product tags.
+    description: list of product tag IDs if the condition's type is `product_tags`
     items:
       type: string
   customer_groups:
     type: array
-    description: list of customer group IDs if the condition is applied on customer groups.
+    description: list of customer group IDs if the condition's type is `customer_groups`.
     items:
       type: string
diff --git a/docs/api/admin/components/schemas/AdminPostDiscountsDiscountDynamicCodesReq.yaml b/docs/api/admin/components/schemas/AdminPostDiscountsDiscountDynamicCodesReq.yaml
index 3f6a13757c..c3d055f336 100644
--- a/docs/api/admin/components/schemas/AdminPostDiscountsDiscountDynamicCodesReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDiscountsDiscountDynamicCodesReq.yaml
@@ -7,8 +7,12 @@ properties:
     description: A unique code that will be used to redeem the Discount
   usage_limit:
     type: number
-    description: Maximum times the discount can be used
+    description: Maximum number of times the discount code can be used
     default: 1
   metadata:
     type: object
     description: An optional set of key-value pairs to hold additional information.
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostDiscountsDiscountReq.yaml b/docs/api/admin/components/schemas/AdminPostDiscountsDiscountReq.yaml
index d7acadcf2f..7b87f318bc 100644
--- a/docs/api/admin/components/schemas/AdminPostDiscountsDiscountReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDiscountsDiscountReq.yaml
@@ -2,9 +2,9 @@ type: object
 properties:
   code:
     type: string
-    description: A unique code that will be used to redeem the Discount
+    description: A unique code that will be used to redeem the discount
   rule:
-    description: The Discount Rule that defines how Discounts are calculated
+    description: The discount rule that defines how discounts are calculated
     type: object
     required:
       - id
@@ -18,11 +18,15 @@ properties:
       value:
         type: number
         description: >-
-          The value that the discount represents; this will depend on the type
-          of the discount
+          The value that the discount represents. This will depend on the type
+          of the discount.
       allocation:
         type: string
-        description: The scope that the discount should apply to.
+        description: >-
+          The scope that the discount should apply to. `total` indicates that
+          the discount should be applied on the cart total, and `item` indicates
+          that the discount should be applied to each discountable item in the
+          cart.
         enum:
           - total
           - item
@@ -31,7 +35,8 @@ properties:
         description: >-
           A set of conditions that can be used to limit when the discount can be
           used. Only one of `products`, `product_types`, `product_collections`,
-          `product_tags`, and `customer_groups` should be provided.
+          `product_tags`, and `customer_groups` should be provided based on the
+          discount condition's type.
         items:
           type: object
           required:
@@ -39,69 +44,73 @@ properties:
           properties:
             id:
               type: string
-              description: The ID of the Rule
+              description: The ID of the condition
             operator:
               type: string
-              description: Operator of the condition
+              description: >-
+                Operator of the condition. `in` indicates that discountable
+                resources are within the specified resources. `not_in` indicates
+                that discountable resources are everything but the specified
+                resources.
               enum:
                 - in
                 - not_in
             products:
               type: array
-              description: list of product IDs if the condition is applied on products.
+              description: list of product IDs if the condition's type is `products`.
               items:
                 type: string
             product_types:
               type: array
               description: >-
-                list of product type IDs if the condition is applied on product
-                types.
+                list of product type IDs if the condition's type is
+                `product_types`.
               items:
                 type: string
             product_collections:
               type: array
               description: >-
-                list of product collection IDs if the condition is applied on
-                product collections.
+                list of product collection IDs if the condition's type is
+                `product_collections`.
               items:
                 type: string
             product_tags:
               type: array
               description: >-
-                list of product tag IDs if the condition is applied on product
-                tags.
+                list of product tag IDs if the condition's type is
+                `product_tags`.
               items:
                 type: string
             customer_groups:
               type: array
               description: >-
-                list of customer group IDs if the condition is applied on
-                customer groups.
+                list of customer group IDs if the condition's type is
+                `customer_groups`.
               items:
                 type: string
   is_disabled:
     type: boolean
     description: >-
-      Whether the Discount code is disabled on creation. You will have to enable
-      it later to make it available to Customers.
+      Whether the discount code is disabled on creation. If set to `true`, it
+      will not be available for customers.
   starts_at:
     type: string
     format: date-time
-    description: The time at which the Discount should be available.
+    description: The date and time at which the discount should be available.
   ends_at:
     type: string
     format: date-time
-    description: The time at which the Discount should no longer be available.
+    description: The date and time at which the discount should no longer be available.
   valid_duration:
     type: string
-    description: Duration the discount runs between
+    description: The duration the discount runs between
     example: P3Y6M4DT12H30M5S
   usage_limit:
     type: number
-    description: Maximum times the discount can be used
+    description: Maximum number of times the discount can be used
   regions:
     description: >-
-      A list of Region ids representing the Regions in which the Discount can be
+      A list of region IDs representing the Regions in which the Discount can be
       used.
     type: array
     items:
@@ -109,3 +118,7 @@ properties:
   metadata:
     description: An object containing metadata of the discount
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostDiscountsReq.yaml b/docs/api/admin/components/schemas/AdminPostDiscountsReq.yaml
index a73bc06eb3..e7a5f2568e 100644
--- a/docs/api/admin/components/schemas/AdminPostDiscountsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDiscountsReq.yaml
@@ -6,16 +6,16 @@ required:
 properties:
   code:
     type: string
-    description: A unique code that will be used to redeem the Discount
+    description: A unique code that will be used to redeem the discount
   is_dynamic:
     type: boolean
     description: >-
-      Whether the Discount should have multiple instances of itself, each with a
-      different code. This can be useful for automatically generated codes that
-      all have to follow a common set of rules.
+      Whether the discount should have multiple instances of itself, each with a
+      different code. This can be useful for automatically generated discount
+      codes that all have to follow a common set of rules.
     default: false
   rule:
-    description: The Discount Rule that defines how Discounts are calculated
+    description: The discount rule that defines how discounts are calculated
     type: object
     required:
       - type
@@ -28,7 +28,7 @@ properties:
       type:
         type: string
         description: >-
-          The type of the Discount, can be `fixed` for discounts that reduce the
+          The type of the discount, can be `fixed` for discounts that reduce the
           price by a fixed amount, `percentage` for percentage reductions or
           `free_shipping` for shipping vouchers.
         enum:
@@ -38,21 +38,25 @@ properties:
       value:
         type: number
         description: >-
-          The value that the discount represents; this will depend on the type
-          of the discount
+          The value that the discount represents. This will depend on the type
+          of the discount.
       allocation:
         type: string
-        description: The scope that the discount should apply to.
+        description: >-
+          The scope that the discount should apply to. `total` indicates that
+          the discount should be applied on the cart total, and `item` indicates
+          that the discount should be applied to each discountable item in the
+          cart.
         enum:
           - total
           - item
       conditions:
         type: array
         description: >-
-          A set of conditions that can be used to limit when  the discount can
-          be used. Only one of `products`, `product_types`,
-          `product_collections`, `product_tags`, and `customer_groups` should be
-          provided.
+          A set of conditions that can be used to limit when the discount can be
+          used. Only one of `products`, `product_types`, `product_collections`,
+          `product_tags`, and `customer_groups` should be provided based on the
+          discount condition's type.
         items:
           type: object
           required:
@@ -60,71 +64,79 @@ properties:
           properties:
             operator:
               type: string
-              description: Operator of the condition
+              description: >-
+                Operator of the condition. `in` indicates that discountable
+                resources are within the specified resources. `not_in` indicates
+                that discountable resources are everything but the specified
+                resources.
               enum:
                 - in
                 - not_in
             products:
               type: array
-              description: list of product IDs if the condition is applied on products.
+              description: list of product IDs if the condition's type is `products`.
               items:
                 type: string
             product_types:
               type: array
               description: >-
-                list of product type IDs if the condition is applied on product
-                types.
+                list of product type IDs if the condition's type is
+                `product_types`.
               items:
                 type: string
             product_collections:
               type: array
               description: >-
-                list of product collection IDs if the condition is applied on
-                product collections.
+                list of product collection IDs if the condition's type is
+                `product_collections`.
               items:
                 type: string
             product_tags:
               type: array
               description: >-
-                list of product tag IDs if the condition is applied on product
-                tags.
+                list of product tag IDs if the condition's type is
+                `product_tags`.
               items:
                 type: string
             customer_groups:
               type: array
               description: >-
-                list of customer group IDs if the condition is applied on
-                customer groups.
+                list of customer group IDs if the condition's type is
+                `customer_groups`.
               items:
                 type: string
   is_disabled:
     type: boolean
     description: >-
-      Whether the Discount code is disabled on creation. You will have to enable
-      it later to make it available to Customers.
+      Whether the discount code is disabled on creation. If set to `true`, it
+      will not be available for customers.
     default: false
   starts_at:
     type: string
     format: date-time
-    description: The time at which the Discount should be available.
+    description: The date and time at which the discount should be available.
   ends_at:
     type: string
     format: date-time
-    description: The time at which the Discount should no longer be available.
+    description: The date and time at which the discount should no longer be available.
   valid_duration:
     type: string
-    description: Duration the discount runs between
+    description: The duration the discount runs between
     example: P3Y6M4DT12H30M5S
   regions:
     description: >-
-      A list of Region ids representing the Regions in which the Discount can be
+      A list of region IDs representing the Regions in which the Discount can be
       used.
     type: array
     items:
       type: string
   usage_limit:
     type: number
-    description: Maximum times the discount can be used
+    description: Maximum number of times the discount can be used
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsItemReq.yaml b/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsItemReq.yaml
index 2f631fea3b..50739d501d 100644
--- a/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsItemReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsItemReq.yaml
@@ -1,14 +1,20 @@
 type: object
 properties:
   unit_price:
-    description: The potential custom price of the item.
+    description: >-
+      The custom price of the line item. If a `variant_id` is supplied, the
+      price provided here will override the variant's price.
     type: integer
   title:
-    description: The potential custom title of the item.
+    description: The title of the line item if `variant_id` is not provided.
     type: string
   quantity:
-    description: The quantity of the Line Item.
+    description: The quantity of the line item.
     type: integer
   metadata:
     description: The optional key-value map with additional details about the Line Item.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsReq.yaml b/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsReq.yaml
index c05a24e9ac..534a197e29 100644
--- a/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsReq.yaml
@@ -3,18 +3,26 @@ required:
   - quantity
 properties:
   variant_id:
-    description: The ID of the Product Variant to generate the Line Item from.
+    description: >-
+      The ID of the Product Variant associated with the line item. If the line
+      item is custom, the `variant_id` should be omitted.
     type: string
   unit_price:
-    description: The potential custom price of the item.
+    description: >-
+      The custom price of the line item. If a `variant_id` is supplied, the
+      price provided here will override the variant's price.
     type: integer
   title:
-    description: The potential custom title of the item.
+    description: The title of the line item if `variant_id` is not provided.
     type: string
     default: Custom item
   quantity:
-    description: The quantity of the Line Item.
+    description: The quantity of the line item.
     type: integer
   metadata:
     description: The optional key-value map with additional details about the Line Item.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderRegisterPaymentRes.yaml b/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderRegisterPaymentRes.yaml
index 53497a9af7..39f759fc27 100644
--- a/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderRegisterPaymentRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderRegisterPaymentRes.yaml
@@ -3,4 +3,5 @@ required:
   - order
 properties:
   order:
+    description: Order's details.
     $ref: ./Order.yaml
diff --git a/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderReq.yaml b/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderReq.yaml
index 29179bd29e..78ce97bc42 100644
--- a/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDraftOrdersDraftOrderReq.yaml
@@ -12,7 +12,7 @@ properties:
       description: See a list of codes.
   email:
     type: string
-    description: An email to be used on the Draft Order.
+    description: An email to be used in the Draft Order.
     format: email
   billing_address:
     description: The Address to be used for billing purposes.
@@ -20,7 +20,7 @@ properties:
       - $ref: ./AddressPayload.yaml
       - type: string
   shipping_address:
-    description: The Address to be used for shipping.
+    description: The Address to be used for shipping purposes.
     anyOf:
       - $ref: ./AddressPayload.yaml
       - type: string
@@ -37,9 +37,9 @@ properties:
           type: string
   no_notification_order:
     description: >-
-      An optional flag passed to the resulting order to determine use of
-      notifications.
+      An optional flag passed to the resulting order that indicates whether the
+      customer should receive notifications about order updates.
     type: boolean
   customer_id:
-    description: The ID of the Customer to associate the Draft Order with.
+    description: The ID of the customer this draft order is associated with.
     type: string
diff --git a/docs/api/admin/components/schemas/AdminPostDraftOrdersReq.yaml b/docs/api/admin/components/schemas/AdminPostDraftOrdersReq.yaml
index f6b12380f5..0677686a7c 100644
--- a/docs/api/admin/components/schemas/AdminPostDraftOrdersReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostDraftOrdersReq.yaml
@@ -5,7 +5,9 @@ required:
   - shipping_methods
 properties:
   status:
-    description: The status of the draft order
+    description: >-
+      The status of the draft order. The draft order's default status is `open`.
+      It's changed to `completed` when its payment is marked as paid.
     type: string
     enum:
       - open
@@ -20,12 +22,12 @@ properties:
       - $ref: ./AddressPayload.yaml
       - type: string
   shipping_address:
-    description: The Address to be used for shipping.
+    description: The Address to be used for shipping purposes.
     anyOf:
       - $ref: ./AddressPayload.yaml
       - type: string
   items:
-    description: The Line Items that have been received.
+    description: The draft order's line items.
     type: array
     items:
       type: object
@@ -33,27 +35,37 @@ properties:
         - quantity
       properties:
         variant_id:
-          description: The ID of the Product Variant to generate the Line Item from.
+          description: >-
+            The ID of the Product Variant associated with the line item. If the
+            line item is custom, the `variant_id` should be omitted.
           type: string
         unit_price:
-          description: The potential custom price of the item.
+          description: >-
+            The custom price of the line item. If a `variant_id` is supplied,
+            the price provided here will override the variant's price.
           type: integer
         title:
-          description: The potential custom title of the item.
+          description: The title of the line item if `variant_id` is not provided.
           type: string
         quantity:
-          description: The quantity of the Line Item.
+          description: The quantity of the line item.
           type: integer
         metadata:
           description: >-
-            The optional key-value map with additional details about the Line
-            Item.
+            The optional key-value map with additional details about the line
+            item.
           type: object
+          externalDocs:
+            description: >-
+              Learn about the metadata attribute, and how to delete and update
+              it.
+            url: >-
+              https://docs.medusajs.com/development/entities/overview#metadata-attribute
   region_id:
     description: The ID of the region for the draft order
     type: string
   discounts:
-    description: The discounts to add on the draft order
+    description: The discounts to add to the draft order
     type: array
     items:
       type: object
@@ -64,12 +76,12 @@ properties:
           description: The code of the discount to apply
           type: string
   customer_id:
-    description: The ID of the customer to add on the draft order
+    description: The ID of the customer this draft order is associated with.
     type: string
   no_notification_order:
     description: >-
-      An optional flag passed to the resulting order to determine use of
-      notifications.
+      An optional flag passed to the resulting order that indicates whether the
+      customer should receive notifications about order updates.
     type: boolean
   shipping_methods:
     description: The shipping methods for the draft order
@@ -86,8 +98,12 @@ properties:
           description: The optional additional data needed for the shipping method
           type: object
         price:
-          description: The potential custom price of the shipping
+          description: The price of the shipping method.
           type: integer
   metadata:
     description: The optional key-value map with additional details about the Draft Order.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostGiftCardsGiftCardReq.yaml b/docs/api/admin/components/schemas/AdminPostGiftCardsGiftCardReq.yaml
index e7976952f4..f2eed952d6 100644
--- a/docs/api/admin/components/schemas/AdminPostGiftCardsGiftCardReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostGiftCardsGiftCardReq.yaml
@@ -6,15 +6,19 @@ properties:
   is_disabled:
     type: boolean
     description: >-
-      Whether the Gift Card is disabled on creation. You will have to enable it
-      later to make it available to Customers.
+      Whether the Gift Card is disabled on creation. If set to `true`, the gift
+      card will not be available for customers.
   ends_at:
     type: string
     format: date-time
-    description: The time at which the Gift Card should no longer be available.
+    description: The date and time at which the Gift Card should no longer be available.
   region_id:
     description: The ID of the Region in which the Gift Card can be used.
     type: string
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostGiftCardsReq.yaml b/docs/api/admin/components/schemas/AdminPostGiftCardsReq.yaml
index fc19e7674d..e969813ef8 100644
--- a/docs/api/admin/components/schemas/AdminPostGiftCardsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostGiftCardsReq.yaml
@@ -8,15 +8,19 @@ properties:
   is_disabled:
     type: boolean
     description: >-
-      Whether the Gift Card is disabled on creation. You will have to enable it
-      later to make it available to Customers.
+      Whether the Gift Card is disabled on creation. If set to `true`, the gift
+      card will not be available for customers.
   ends_at:
     type: string
     format: date-time
-    description: The time at which the Gift Card should no longer be available.
+    description: The date and time at which the Gift Card should no longer be available.
   region_id:
     description: The ID of the Region in which the Gift Card can be used.
     type: string
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostInventoryItemsItemLocationLevelsReq.yaml b/docs/api/admin/components/schemas/AdminPostInventoryItemsItemLocationLevelsReq.yaml
index 05daa3f720..a581c1918d 100644
--- a/docs/api/admin/components/schemas/AdminPostInventoryItemsItemLocationLevelsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostInventoryItemsItemLocationLevelsReq.yaml
@@ -4,11 +4,11 @@ required:
   - stocked_quantity
 properties:
   location_id:
-    description: the item location ID
+    description: the ID of the stock location
     type: string
   stocked_quantity:
-    description: the stock quantity of an inventory item at the given location ID
+    description: the stock quantity of the inventory item at this location
     type: number
   incoming_quantity:
-    description: the incoming stock quantity of an inventory item at the given location ID
+    description: the incoming stock quantity of the inventory item at this location
     type: number
diff --git a/docs/api/admin/components/schemas/AdminPostInventoryItemsReq.yaml b/docs/api/admin/components/schemas/AdminPostInventoryItemsReq.yaml
index b6abd5adde..b45c6018b0 100644
--- a/docs/api/admin/components/schemas/AdminPostInventoryItemsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostInventoryItemsReq.yaml
@@ -1,7 +1,7 @@
 type: object
 properties:
   sku:
-    description: The unique SKU for the Product Variant.
+    description: The unique SKU of the associated Product Variant.
     type: string
   ean:
     description: The EAN number of the item.
@@ -13,42 +13,64 @@ properties:
     description: A generic GTIN field for the Product Variant.
     type: string
   hs_code:
-    description: The Harmonized System code for the Product Variant.
+    description: >-
+      The Harmonized System code of the Inventory Item. May be used by
+      Fulfillment Providers to pass customs information to shipping carriers.
     type: string
   inventory_quantity:
-    description: The amount of stock kept for the Product Variant.
+    description: The amount of stock kept of the associated Product Variant.
     type: integer
     default: 0
   allow_backorder:
-    description: Whether the Product Variant can be purchased when out of stock.
+    description: Whether the associated Product Variant can be purchased when out of stock.
     type: boolean
   manage_inventory:
     description: >-
-      Whether Medusa should keep track of the inventory for this Product
-      Variant.
+      Whether Medusa should keep track of the inventory for the associated
+      Product Variant.
     type: boolean
     default: true
   weight:
-    description: The wieght of the Product Variant.
+    description: >-
+      The weight of the Inventory Item. May be used in shipping rate
+      calculations.
     type: number
   length:
-    description: The length of the Product Variant.
+    description: >-
+      The length of the Inventory Item. May be used in shipping rate
+      calculations.
     type: number
   height:
-    description: The height of the Product Variant.
+    description: >-
+      The height of the Inventory Item. May be used in shipping rate
+      calculations.
     type: number
   width:
-    description: The width of the Product Variant.
+    description: >-
+      The width of the Inventory Item. May be used in shipping rate
+      calculations.
     type: number
   origin_country:
-    description: The country of origin of the Product Variant.
+    description: >-
+      The country in which the Inventory Item was produced. May be used by
+      Fulfillment Providers to pass customs information to shipping carriers.
     type: string
   mid_code:
-    description: The Manufacturer Identification code for the Product Variant.
+    description: >-
+      The Manufacturers Identification code that identifies the manufacturer of
+      the Inventory Item. May be used by Fulfillment Providers to pass customs
+      information to shipping carriers.
     type: string
   material:
-    description: The material composition of the Product Variant.
+    description: >-
+      The material and composition that the Inventory Item is made of, May be
+      used by Fulfillment Providers to pass customs information to shipping
+      carriers.
     type: string
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostInvitesInviteAcceptReq.yaml b/docs/api/admin/components/schemas/AdminPostInvitesInviteAcceptReq.yaml
index 41600a6ddb..5fcb0d30c5 100644
--- a/docs/api/admin/components/schemas/AdminPostInvitesInviteAcceptReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostInvitesInviteAcceptReq.yaml
@@ -4,10 +4,12 @@ required:
   - user
 properties:
   token:
-    description: The invite token provided by the admin.
+    description: >-
+      The token of the invite to accept. This is a unique token generated when
+      the invite was created or resent.
     type: string
   user:
-    description: The User to create.
+    description: The details of the user to create.
     type: object
     required:
       - first_name
@@ -21,6 +23,6 @@ properties:
         type: string
         description: the last name of the User
       password:
-        description: The desired password for the User
+        description: The password for the User
         type: string
         format: password
diff --git a/docs/api/admin/components/schemas/AdminPostInvitesReq.yaml b/docs/api/admin/components/schemas/AdminPostInvitesReq.yaml
index 31d8426e51..5cad953bc6 100644
--- a/docs/api/admin/components/schemas/AdminPostInvitesReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostInvitesReq.yaml
@@ -4,11 +4,15 @@ required:
   - role
 properties:
   user:
-    description: The email for the user to be created.
+    description: >-
+      The email associated with the invite. Once the invite is accepted, the
+      email will be associated with the created user.
     type: string
     format: email
   role:
-    description: The role of the user to be created.
+    description: >-
+      The role of the user to be created. This does not actually change the
+      privileges of the user that is eventually created.
     type: string
     enum:
       - admin
diff --git a/docs/api/admin/components/schemas/AdminPostNotesNoteReq.yaml b/docs/api/admin/components/schemas/AdminPostNotesNoteReq.yaml
index 1c2bb16901..e5422c1680 100644
--- a/docs/api/admin/components/schemas/AdminPostNotesNoteReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostNotesNoteReq.yaml
@@ -4,4 +4,4 @@ required:
 properties:
   value:
     type: string
-    description: The updated description of the Note.
+    description: The description of the Note.
diff --git a/docs/api/admin/components/schemas/AdminPostNotesReq.yaml b/docs/api/admin/components/schemas/AdminPostNotesReq.yaml
index 01ef23d775..94c6db4726 100644
--- a/docs/api/admin/components/schemas/AdminPostNotesReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostNotesReq.yaml
@@ -6,10 +6,12 @@ required:
 properties:
   resource_id:
     type: string
-    description: The ID of the resource which the Note relates to.
+    description: >-
+      The ID of the resource which the Note relates to. For example, an order
+      ID.
   resource_type:
     type: string
-    description: The type of resource which the Note relates to.
+    description: The type of resource which the Note relates to. For example, `order`.
   value:
     type: string
     description: The content of the Note to create.
diff --git a/docs/api/admin/components/schemas/AdminPostNotificationsNotificationResendReq.yaml b/docs/api/admin/components/schemas/AdminPostNotificationsNotificationResendReq.yaml
index 3d6d6575df..15e00764ea 100644
--- a/docs/api/admin/components/schemas/AdminPostNotificationsNotificationResendReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostNotificationsNotificationResendReq.yaml
@@ -1,5 +1,7 @@
 type: object
 properties:
   to:
-    description: A new address or user identifier that the Notification should be sent to
+    description: >-
+      A new address or user identifier that the Notification should be sent to.
+      If not provided, the previous `to` field of the notification will be used.
     type: string
diff --git a/docs/api/admin/components/schemas/AdminPostOrderEditsEditLineItemsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrderEditsEditLineItemsReq.yaml
index 6671ae2e12..8476606d5a 100644
--- a/docs/api/admin/components/schemas/AdminPostOrderEditsEditLineItemsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrderEditsEditLineItemsReq.yaml
@@ -4,11 +4,15 @@ required:
   - quantity
 properties:
   variant_id:
-    description: The ID of the variant ID to add
+    description: The ID of the product variant associated with the item.
     type: string
   quantity:
-    description: The quantity to add
+    description: The quantity of the item.
     type: number
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostOrderEditsOrderEditReq.yaml b/docs/api/admin/components/schemas/AdminPostOrderEditsOrderEditReq.yaml
index 0956090625..15db5e930f 100644
--- a/docs/api/admin/components/schemas/AdminPostOrderEditsOrderEditReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrderEditsOrderEditReq.yaml
@@ -1,5 +1,5 @@
 type: object
 properties:
   internal_note:
-    description: An optional note to create or update for the order edit.
+    description: An optional note to create or update in the order edit.
     type: string
diff --git a/docs/api/admin/components/schemas/AdminPostOrderEditsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrderEditsReq.yaml
index 37fcff4261..f02ce3c01a 100644
--- a/docs/api/admin/components/schemas/AdminPostOrderEditsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrderEditsReq.yaml
@@ -6,5 +6,5 @@ properties:
     description: The ID of the order to create the edit for.
     type: string
   internal_note:
-    description: An optional note to create for the order edit.
+    description: An optional note to associate with the order edit.
     type: string
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimFulfillmentsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimFulfillmentsReq.yaml
index 9ebb87d7e4..44986a8f4d 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimFulfillmentsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimFulfillmentsReq.yaml
@@ -3,6 +3,12 @@ properties:
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   no_notification:
-    description: If set to true no notification will be send related to this Claim.
+    description: >-
+      If set to `true`, no notification will be sent to the customer related to
+      this Claim.
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimReq.yaml
index c26136a642..273c864064 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimReq.yaml
@@ -57,6 +57,12 @@ properties:
         metadata:
           description: An optional set of key-value pairs to hold additional information.
           type: object
+          externalDocs:
+            description: >-
+              Learn about the metadata attribute, and how to delete and update
+              it.
+            url: >-
+              https://docs.medusajs.com/development/entities/overview#metadata-attribute
   shipping_methods:
     description: The Shipping Methods to send the additional Line Items with.
     type: array
@@ -81,3 +87,7 @@ properties:
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimShipmentsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimShipmentsReq.yaml
index e94def5834..1599973734 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimShipmentsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsClaimShipmentsReq.yaml
@@ -6,7 +6,7 @@ properties:
     description: The ID of the Fulfillment.
     type: string
   tracking_numbers:
-    description: The tracking numbers for the shipment.
+    description: An array of tracking numbers for the shipment.
     type: array
     items:
       type: string
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsReq.yaml
index 70a139b7a5..e46b5b55a4 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderClaimsReq.yaml
@@ -40,7 +40,7 @@ properties:
             - production_failure
             - other
         tags:
-          description: A list o tags to add to the Claim Item
+          description: A list of tags to add to the Claim Item
           type: array
           items:
             type: string
@@ -51,7 +51,8 @@ properties:
   return_shipping:
     description: >-
       Optional details for the Return Shipping Method, if the items are to be
-      sent back.
+      sent back. Providing this field will result in a return being created and
+      associated with the claim.
     type: object
     properties:
       option_id:
@@ -61,7 +62,9 @@ properties:
         type: integer
         description: The price to charge for the Shipping Method.
   additional_items:
-    description: The new items to send to the Customer when the Claim type is Replace.
+    description: >-
+      The new items to send to the Customer. This is only used if the claim's
+      type is `replace`.
     type: array
     items:
       type: object
@@ -70,13 +73,15 @@ properties:
         - quantity
       properties:
         variant_id:
-          description: The ID of the Product Variant to ship.
+          description: The ID of the Product Variant.
           type: string
         quantity:
-          description: The quantity of the Product Variant to ship.
+          description: The quantity of the Product Variant.
           type: integer
   shipping_methods:
-    description: The Shipping Methods to send the additional Line Items with.
+    description: >-
+      The Shipping Methods to send the additional Line Items with. This is only
+      used if the claim's type is `replace`.
     type: array
     items:
       type: object
@@ -95,11 +100,13 @@ properties:
           type: object
   shipping_address:
     description: >-
-      An optional shipping address to send the claim to. Defaults to the parent
-      order's shipping address
+      An optional shipping address to send the claimed items to. If not
+      provided, the parent order's shipping address will be used.
     $ref: ./AddressPayload.yaml
   refund_amount:
-    description: The amount to refund the Customer when the Claim type is `refund`.
+    description: >-
+      The amount to refund the customer. This is used when the claim's type is
+      `refund`.
     type: integer
   no_notification:
     description: If set to true no notification will be send related to this Claim.
@@ -107,3 +114,7 @@ properties:
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderFulfillmentsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderFulfillmentsReq.yaml
index 377b2b8f5f..58c6dbcd49 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderFulfillmentsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderFulfillmentsReq.yaml
@@ -12,14 +12,20 @@ properties:
         - quantity
       properties:
         item_id:
-          description: The ID of Line Item to fulfill.
+          description: The ID of the Line Item to fulfill.
           type: string
         quantity:
           description: The quantity of the Line Item to fulfill.
           type: integer
   no_notification:
-    description: If set to true no notification will be send related to this Swap.
+    description: >-
+      If set to `true`, no notification will be sent to the customer related to
+      this fulfillment.
     type: boolean
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderRefundsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderRefundsReq.yaml
index ee19081712..004cc962fc 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderRefundsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderRefundsReq.yaml
@@ -4,7 +4,9 @@ required:
   - reason
 properties:
   amount:
-    description: The amount to refund.
+    description: >-
+      The amount to refund. It should be less than or equal the
+      `refundable_amount` of the order.
     type: integer
   reason:
     description: The reason for the Refund.
@@ -13,5 +15,7 @@ properties:
     description: A note with additional details about the Refund.
     type: string
   no_notification:
-    description: If set to true no notification will be send related to this Refund.
+    description: >-
+      If set to `true`, no notification will be sent to the customer related to
+      this Refund.
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderReq.yaml
index 62d6722f97..8b1f00f5e1 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderReq.yaml
@@ -1,39 +1,39 @@
 type: object
 properties:
   email:
-    description: the email for the order
+    description: the email associated with the order
     type: string
   billing_address:
-    description: Billing address
+    description: The order's billing address
     $ref: ./AddressPayload.yaml
   shipping_address:
-    description: Shipping address
+    description: The order's shipping address
     $ref: ./AddressPayload.yaml
   items:
-    description: The Line Items for the order
+    description: The line items of the order
     type: array
     items:
       $ref: ./LineItem.yaml
   region:
-    description: ID of the region where the order belongs
+    description: ID of the region that the order is associated with.
     type: string
   discounts:
-    description: Discounts applied to the order
+    description: The discounts applied to the order
     type: array
     items:
       $ref: ./Discount.yaml
   customer_id:
-    description: ID of the customer
+    description: The ID of the customer associated with the order.
     type: string
   payment_method:
-    description: payment method chosen for the order
+    description: The payment method chosen for the order.
     type: object
     properties:
       provider_id:
         type: string
-        description: ID of the payment provider
+        description: The ID of the payment provider.
       data:
-        description: Data relevant for the given payment method
+        description: Any data relevant for the given payment method.
         type: object
   shipping_method:
     description: The Shipping Method used for shipping the order.
@@ -50,7 +50,7 @@ properties:
         description: The price of the shipping.
       data:
         type: object
-        description: Data relevant to the specific shipping method.
+        description: Any data relevant to the specific shipping method.
       items:
         type: array
         items:
@@ -58,6 +58,6 @@ properties:
         description: Items to ship
   no_notification:
     description: >-
-      A flag to indicate if no notifications should be emitted related to the
-      updated order.
+      If set to `true`, no notification will be sent to the customer related to
+      this order.
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderReturnsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderReturnsReq.yaml
index 383a5d143f..d485a2c1a3 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderReturnsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderReturnsReq.yaml
@@ -3,7 +3,7 @@ required:
   - items
 properties:
   items:
-    description: The Line Items that will be returned.
+    description: The line items that will be returned.
     type: array
     items:
       type: object
@@ -44,8 +44,8 @@ properties:
     default: false
   no_notification:
     description: >-
-      A flag to indicate if no notifications should be emitted related to the
-      requested Return.
+      If set to `true`, no notification will be sent to the customer related to
+      this Return.
     type: boolean
   refund:
     description: The amount to refund.
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderShippingMethodsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderShippingMethodsReq.yaml
index de74a2f67e..800529076e 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderShippingMethodsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderShippingMethodsReq.yaml
@@ -13,4 +13,4 @@ properties:
     type: object
     description: >-
       The data required for the Shipping Option to create a Shipping Method.
-      This will depend on the Fulfillment Provider.
+      This depends on the Fulfillment Provider.
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderSwapsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderSwapsReq.yaml
index 42491fcf7b..72ead89d62 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderSwapsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderSwapsReq.yaml
@@ -3,7 +3,7 @@ required:
   - return_items
 properties:
   return_items:
-    description: The Line Items to return as part of the Swap.
+    description: The Line Items to associate with the swap's return.
     type: array
     items:
       type: object
@@ -12,7 +12,7 @@ properties:
         - quantity
       properties:
         item_id:
-          description: The ID of the Line Item that will be claimed.
+          description: The ID of the Line Item that will be returned.
           type: string
         quantity:
           description: The number of items that will be returned
@@ -24,7 +24,7 @@ properties:
           description: An optional note with information about the Return.
           type: string
   return_shipping:
-    description: How the Swap will be returned.
+    description: The shipping method associated with the swap's return.
     type: object
     required:
       - option_id
@@ -45,13 +45,15 @@ properties:
         - quantity
       properties:
         variant_id:
-          description: The ID of the Product Variant to ship.
+          description: The ID of the Product Variant.
           type: string
         quantity:
-          description: The quantity of the Product Variant to ship.
+          description: The quantity of the Product Variant.
           type: integer
   custom_shipping_options:
-    description: The custom shipping options to potentially create a Shipping Method from.
+    description: >-
+      An array of custom shipping options to potentially create a Shipping
+      Method from to send the additional items.
     type: array
     items:
       type: object
@@ -60,15 +62,17 @@ properties:
         - price
       properties:
         option_id:
-          description: The ID of the Shipping Option to override with a custom price.
+          description: The ID of the Shipping Option.
           type: string
         price:
           description: The custom price of the Shipping Option.
           type: integer
   no_notification:
-    description: If set to true no notification will be send related to this Swap.
+    description: >-
+      If set to `true`, no notification will be sent to the customer related to
+      this Swap.
     type: boolean
   allow_backorder:
-    description: If true, swaps can be completed with items out of stock
+    description: If set to `true`, swaps can be completed with items out of stock
     type: boolean
     default: true
diff --git a/docs/api/admin/components/schemas/AdminPostOrdersOrderSwapsSwapFulfillmentsReq.yaml b/docs/api/admin/components/schemas/AdminPostOrdersOrderSwapsSwapFulfillmentsReq.yaml
index 9ebb87d7e4..5ace30af64 100644
--- a/docs/api/admin/components/schemas/AdminPostOrdersOrderSwapsSwapFulfillmentsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostOrdersOrderSwapsSwapFulfillmentsReq.yaml
@@ -3,6 +3,12 @@ properties:
   metadata:
     description: An optional set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   no_notification:
-    description: If set to true no notification will be send related to this Claim.
+    description: >-
+      If set to `true`, no notification will be sent to the customer related to
+      this swap.
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostPriceListPricesPricesReq.yaml b/docs/api/admin/components/schemas/AdminPostPriceListPricesPricesReq.yaml
index dc789b1ae4..ba11d24378 100644
--- a/docs/api/admin/components/schemas/AdminPostPriceListPricesPricesReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostPriceListPricesPricesReq.yaml
@@ -14,13 +14,13 @@ properties:
           type: string
         region_id:
           description: >-
-            The ID of the Region for which the price is used. Only required if
-            currecny_code is not provided.
+            The ID of the Region for which the price is used. This is only
+            required if `currecny_code` is not provided.
           type: string
         currency_code:
           description: >-
             The 3 character ISO currency code for which the price will be used.
-            Only required if region_id is not provided.
+            This is only required if `region_id` is not provided.
           type: string
           externalDocs:
             url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
@@ -39,6 +39,6 @@ properties:
           type: integer
   override:
     description: >-
-      If true the prices will replace all existing prices associated with the
-      Price List.
+      If set to `true`, the prices will replace all existing prices associated
+      with the Price List.
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostPriceListsPriceListPriceListReq.yaml b/docs/api/admin/components/schemas/AdminPostPriceListsPriceListPriceListReq.yaml
index 090fb1305b..bb5acd67fe 100644
--- a/docs/api/admin/components/schemas/AdminPostPriceListsPriceListPriceListReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostPriceListsPriceListPriceListReq.yaml
@@ -4,7 +4,7 @@ properties:
     description: The name of the Price List
     type: string
   description:
-    description: A description of the Price List.
+    description: The description of the Price List.
     type: string
   starts_at:
     description: The date with timezone that the Price List starts being valid.
@@ -21,7 +21,9 @@ properties:
       - sale
       - override
   status:
-    description: The status of the Price List.
+    description: >-
+      The status of the Price List. If the status is set to `draft`, the prices
+      created in the price list will not be available of the customer.
     type: string
     enum:
       - active
@@ -40,13 +42,13 @@ properties:
           type: string
         region_id:
           description: >-
-            The ID of the Region for which the price is used. Only required if
-            currecny_code is not provided.
+            The ID of the Region for which the price is used. This is only
+            required if `currecny_code` is not provided.
           type: string
         currency_code:
           description: >-
             The 3 character ISO currency code for which the price will be used.
-            Only required if region_id is not provided.
+            This is only required if `region_id` is not provided.
           type: string
           externalDocs:
             url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
@@ -65,7 +67,7 @@ properties:
           type: integer
   customer_groups:
     type: array
-    description: A list of customer groups that the Price List applies to.
+    description: An array of customer groups that the Price List applies to.
     items:
       type: object
       required:
@@ -75,5 +77,6 @@ properties:
           description: The ID of a customer group
           type: string
   includes_tax:
-    description: '[EXPERIMENTAL] Tax included in prices of price list'
+    description: Tax included in prices of price list
+    x-featureFlag: tax_inclusive_pricing
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostPriceListsPriceListReq.yaml b/docs/api/admin/components/schemas/AdminPostPriceListsPriceListReq.yaml
index fce72ccea1..d7367f1a04 100644
--- a/docs/api/admin/components/schemas/AdminPostPriceListsPriceListReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostPriceListsPriceListReq.yaml
@@ -6,10 +6,10 @@ required:
   - prices
 properties:
   name:
-    description: The name of the Price List
+    description: The name of the Price List.
     type: string
   description:
-    description: A description of the Price List.
+    description: The description of the Price List.
     type: string
   starts_at:
     description: The date with timezone that the Price List starts being valid.
@@ -26,7 +26,9 @@ properties:
       - sale
       - override
   status:
-    description: The status of the Price List.
+    description: >-
+      The status of the Price List. If the status is set to `draft`, the prices
+      created in the price list will not be available of the customer.
     type: string
     enum:
       - active
@@ -42,13 +44,13 @@ properties:
       properties:
         region_id:
           description: >-
-            The ID of the Region for which the price is used. Only required if
-            currecny_code is not provided.
+            The ID of the Region for which the price is used. This is only
+            required if `currecny_code` is not provided.
           type: string
         currency_code:
           description: >-
             The 3 character ISO currency code for which the price will be used.
-            Only required if region_id is not provided.
+            This is only required if `region_id` is not provided.
           type: string
           externalDocs:
             url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
@@ -67,7 +69,7 @@ properties:
           type: integer
   customer_groups:
     type: array
-    description: A list of customer groups that the Price List applies to.
+    description: An array of customer groups that the Price List applies to.
     items:
       type: object
       required:
@@ -77,5 +79,6 @@ properties:
           description: The ID of a customer group
           type: string
   includes_tax:
-    description: '[EXPERIMENTAL] Tax included in prices of price list'
+    description: Tax included in prices of price list
+    x-featureFlag: tax_inclusive_pricing
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostProductCategoriesReq.yaml b/docs/api/admin/components/schemas/AdminPostProductCategoriesReq.yaml
index 264859f4ef..2b003fbb24 100644
--- a/docs/api/admin/components/schemas/AdminPostProductCategoriesReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostProductCategoriesReq.yaml
@@ -4,21 +4,24 @@ required:
 properties:
   name:
     type: string
-    description: The name to identify the Product Category by.
+    description: The name of the product category
   description:
     type: string
-    description: An optional text field to describe the Product Category by.
+    description: The description of the product category.
   handle:
     type: string
     description: >-
-      An optional handle to be used in slugs, if none is provided we will
-      kebab-case the title.
+      The handle of the product category. If none is provided, the kebab-case
+      version of the name will be used. This field can be used as a slug in
+      URLs.
   is_internal:
     type: boolean
-    description: A flag to make product category an internal category for admins
+    description: If set to `true`, the product category will only be available to admins.
   is_active:
     type: boolean
-    description: A flag to make product category visible/hidden in the store front
+    description: >-
+      If set to `false`, the product category will not be available in the
+      storefront.
   parent_category_id:
     type: string
     description: The ID of the parent product category
diff --git a/docs/api/admin/components/schemas/AdminPostProductsProductOptionsReq.yaml b/docs/api/admin/components/schemas/AdminPostProductsProductOptionsReq.yaml
index db0ba5be42..55b83b8691 100644
--- a/docs/api/admin/components/schemas/AdminPostProductsProductOptionsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostProductsProductOptionsReq.yaml
@@ -3,5 +3,6 @@ required:
   - title
 properties:
   title:
-    description: The title the Product Option will be identified by i.e. "Size"
+    description: The title the Product Option.
     type: string
+    example: Size
diff --git a/docs/api/admin/components/schemas/AdminPostProductsProductReq.yaml b/docs/api/admin/components/schemas/AdminPostProductsProductReq.yaml
index aab995d09a..8d21940df0 100644
--- a/docs/api/admin/components/schemas/AdminPostProductsProductReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostProductsProductReq.yaml
@@ -7,26 +7,36 @@ properties:
     description: The subtitle of the Product
     type: string
   description:
-    description: A description of the Product.
+    description: The description of the Product.
     type: string
   discountable:
     description: >-
-      A flag to indicate if discounts can be applied to the LineItems generated
+      A flag to indicate if discounts can be applied to the Line Items generated
       from this Product
     type: boolean
   images:
-    description: Images of the Product.
+    description: >-
+      An array of images of the Product. Each value in the array is a URL to the
+      image. You can use the upload endpoints to upload the image and obtain a
+      URL.
     type: array
     items:
       type: string
   thumbnail:
-    description: The thumbnail to use for the Product.
+    description: >-
+      The thumbnail to use for the Product. The value is a URL to the thumbnail.
+      You can use the upload endpoints to upload the thumbnail and obtain a URL.
     type: string
   handle:
-    description: A unique handle to identify the Product by.
+    description: >-
+      A unique handle to identify the Product by. If not provided, the
+      kebab-case version of the product title will be used. This can be used as
+      a slug in URLs.
     type: string
   status:
-    description: The status of the product.
+    description: >-
+      The status of the product. The product is shown to the customer only if
+      its status is `published`.
     type: string
     enum:
       - draft
@@ -40,16 +50,18 @@ properties:
       - value
     properties:
       id:
-        description: The ID of the Product Type.
+        description: >-
+          The ID of an existing Product Type. If not provided, a new product
+          type will be created.
         type: string
       value:
         description: The value of the Product Type.
         type: string
   collection_id:
-    description: The ID of the Collection the Product should belong to.
+    description: The ID of the Product Collection the Product belongs to.
     type: string
   tags:
-    description: Tags to associate the Product with.
+    description: Product Tags to associate the Product with.
     type: array
     items:
       type: object
@@ -57,13 +69,17 @@ properties:
         - value
       properties:
         id:
-          description: The ID of an existing Tag.
+          description: >-
+            The ID of an existing Product Tag. If not provided, a new product
+            tag will be created.
           type: string
         value:
-          description: The value of the Tag, these will be upserted.
+          description: >-
+            The value of the Tag. If the `id` is provided, the value of the
+            existing tag will be updated.
           type: string
   sales_channels:
-    description: '[EXPERIMENTAL] Sales channels to associate the Product with.'
+    description: Sales channels to associate the Product with.
     type: array
     items:
       type: object
@@ -74,7 +90,8 @@ properties:
           description: The ID of an existing Sales channel.
           type: string
   categories:
-    description: Categories to add the Product to.
+    description: Product categories to add the Product to.
+    x-featureFlag: product_categories
     type: array
     items:
       required:
@@ -84,101 +101,126 @@ properties:
           description: The ID of a Product Category.
           type: string
   variants:
-    description: A list of Product Variants to create with the Product.
+    description: >-
+      An array of Product Variants to create with the Product. Each product
+      variant must have a unique combination of Product Option values.
     type: array
     items:
       type: object
       properties:
         id:
-          description: The ID of the Product Variant.
+          description: >-
+            The id of an existing product variant. If provided, the details of
+            the product variant will be updated. If not, a new product variant
+            will be created.
           type: string
         title:
-          description: The title to identify the Product Variant by.
+          description: The title of the product variant.
           type: string
         sku:
-          description: The unique SKU for the Product Variant.
+          description: The unique SKU of the product variant.
           type: string
         ean:
-          description: The EAN number of the item.
+          description: The EAN number of the product variant.
           type: string
         upc:
-          description: The UPC number of the item.
+          description: The UPC number of the product variant.
           type: string
         barcode:
-          description: A generic GTIN field for the Product Variant.
+          description: A generic GTIN field of the product variant.
           type: string
         hs_code:
-          description: The Harmonized System code for the Product Variant.
+          description: The Harmonized System code of the product variant.
           type: string
         inventory_quantity:
-          description: The amount of stock kept for the Product Variant.
+          description: The amount of stock kept of the product variant.
           type: integer
         allow_backorder:
-          description: Whether the Product Variant can be purchased when out of stock.
+          description: Whether the product variant can be purchased when out of stock.
           type: boolean
         manage_inventory:
           description: >-
-            Whether Medusa should keep track of the inventory for this Product
-            Variant.
+            Whether Medusa should keep track of the inventory of this product
+            variant.
           type: boolean
         weight:
-          description: The wieght of the Product Variant.
+          description: The weight of the product variant.
           type: number
         length:
-          description: The length of the Product Variant.
+          description: The length of the product variant.
           type: number
         height:
-          description: The height of the Product Variant.
+          description: The height of the product variant.
           type: number
         width:
-          description: The width of the Product Variant.
+          description: The width of the product variant.
           type: number
         origin_country:
-          description: The country of origin of the Product Variant.
+          description: The country of origin of the product variant.
           type: string
         mid_code:
-          description: The Manufacturer Identification code for the Product Variant.
+          description: The Manufacturer Identification code of the product variant.
           type: string
         material:
-          description: The material composition of the Product Variant.
+          description: The material composition of the product variant.
           type: string
         metadata:
           description: An optional set of key-value pairs with additional information.
           type: object
+          externalDocs:
+            description: >-
+              Learn about the metadata attribute, and how to delete and update
+              it.
+            url: >-
+              https://docs.medusajs.com/development/entities/overview#metadata-attribute
         prices:
           type: array
+          description: >-
+            An array of product variant prices. A product variant can have
+            different prices for each region or currency code.
+          externalDocs:
+            url: >-
+              https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices
+            description: Product variant pricing.
           items:
             type: object
             required:
               - amount
             properties:
               id:
-                description: The ID of the Price.
+                description: >-
+                  The ID of the Price. If provided, the existing price will be
+                  updated. Otherwise, a new price will be created.
                 type: string
               region_id:
                 description: >-
-                  The ID of the Region for which the price is used. Only
-                  required if currency_code is not provided.
+                  The ID of the Region the price will be used in. This is only
+                  required if `currency_code` is not provided.
                 type: string
               currency_code:
                 description: >-
-                  The 3 character ISO currency code for which the price will be
-                  used. Only required if region_id is not provided.
+                  The 3 character ISO currency code the price will be used in.
+                  This is only required if `region_id` is not provided.
                 type: string
                 externalDocs:
                   url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
                   description: See a list of codes.
               amount:
-                description: The amount to charge for the Product Variant.
+                description: The price amount.
                 type: integer
               min_quantity:
-                description: The minimum quantity for which the price will be used.
+                description: >-
+                  The minimum quantity required to be added to the cart for the
+                  price to be used.
                 type: integer
               max_quantity:
-                description: The maximum quantity for which the price will be used.
+                description: >-
+                  The maximum quantity required to be added to the cart for the
+                  price to be used.
                 type: integer
         options:
           type: array
+          description: An array of Product Option values that the variant corresponds to.
           items:
             type: object
             required:
@@ -189,12 +231,10 @@ properties:
                 description: The ID of the Option.
                 type: string
               value:
-                description: >-
-                  The value to give for the Product Option at the same index in
-                  the Product's `options` field.
+                description: The value of the Product Option.
                 type: string
   weight:
-    description: The wieght of the Product.
+    description: The weight of the Product.
     type: number
   length:
     description: The length of the Product.
@@ -209,7 +249,7 @@ properties:
     description: The country of origin of the Product.
     type: string
   mid_code:
-    description: The Manufacturer Identification code for the Product.
+    description: The Manufacturer Identification code of the Product.
     type: string
   material:
     description: The material composition of the Product.
@@ -217,3 +257,7 @@ properties:
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostProductsProductVariantsReq.yaml b/docs/api/admin/components/schemas/AdminPostProductsProductVariantsReq.yaml
index 84f2e0ca37..98424f1ed9 100644
--- a/docs/api/admin/components/schemas/AdminPostProductsProductVariantsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostProductsProductVariantsReq.yaml
@@ -5,94 +5,105 @@ required:
   - options
 properties:
   title:
-    description: The title to identify the Product Variant by.
+    description: The title of the product variant.
     type: string
   sku:
-    description: The unique SKU for the Product Variant.
+    description: The unique SKU of the product variant.
     type: string
   ean:
-    description: The EAN number of the item.
+    description: The EAN number of the product variant.
     type: string
   upc:
-    description: The UPC number of the item.
+    description: The UPC number of the product variant.
     type: string
   barcode:
-    description: A generic GTIN field for the Product Variant.
+    description: A generic GTIN field of the product variant.
     type: string
   hs_code:
-    description: The Harmonized System code for the Product Variant.
+    description: The Harmonized System code of the product variant.
     type: string
   inventory_quantity:
-    description: The amount of stock kept for the Product Variant.
+    description: The amount of stock kept of the product variant.
     type: integer
     default: 0
   allow_backorder:
-    description: Whether the Product Variant can be purchased when out of stock.
+    description: Whether the product variant can be purchased when out of stock.
     type: boolean
   manage_inventory:
-    description: >-
-      Whether Medusa should keep track of the inventory for this Product
-      Variant.
+    description: Whether Medusa should keep track of the inventory of this product variant.
     type: boolean
     default: true
   weight:
-    description: The wieght of the Product Variant.
+    description: The wieght of the product variant.
     type: number
   length:
-    description: The length of the Product Variant.
+    description: The length of the product variant.
     type: number
   height:
-    description: The height of the Product Variant.
+    description: The height of the product variant.
     type: number
   width:
-    description: The width of the Product Variant.
+    description: The width of the product variant.
     type: number
   origin_country:
-    description: The country of origin of the Product Variant.
+    description: The country of origin of the product variant.
     type: string
   mid_code:
-    description: The Manufacturer Identification code for the Product Variant.
+    description: The Manufacturer Identification code of the product variant.
     type: string
   material:
-    description: The material composition of the Product Variant.
+    description: The material composition of the product variant.
     type: string
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   prices:
     type: array
+    description: >-
+      An array of product variant prices. A product variant can have different
+      prices for each region or currency code.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices
+      description: Product variant pricing.
     items:
       type: object
       required:
         - amount
       properties:
-        id:
-          description: The ID of the price.
-          type: string
         region_id:
           description: >-
-            The ID of the Region for which the price is used. Only required if
-            currency_code is not provided.
+            The ID of the Region the price will be used in. This is only
+            required if `currency_code` is not provided.
           type: string
         currency_code:
           description: >-
-            The 3 character ISO currency code for which the price will be used.
-            Only required if region_id is not provided.
+            The 3 character ISO currency code the price will be used in. This is
+            only required if `region_id` is not provided.
           type: string
           externalDocs:
             url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
             description: See a list of codes.
         amount:
-          description: The amount to charge for the Product Variant.
+          description: The price amount.
           type: integer
         min_quantity:
-          description: The minimum quantity for which the price will be used.
+          description: >-
+            The minimum quantity required to be added to the cart for the price
+            to be used.
           type: integer
         max_quantity:
-          description: The maximum quantity for which the price will be used.
+          description: >-
+            The maximum quantity required to be added to the cart for the price
+            to be used.
           type: integer
   options:
     type: array
+    description: An array of Product Option values that the variant corresponds to.
     items:
       type: object
       required:
@@ -100,8 +111,8 @@ properties:
         - value
       properties:
         option_id:
-          description: The ID of the Product Option to set the value for.
+          description: The ID of the Product Option.
           type: string
         value:
-          description: The value to give for the Product Option.
+          description: A value to give to the Product Option.
           type: string
diff --git a/docs/api/admin/components/schemas/AdminPostProductsProductVariantsVariantReq.yaml b/docs/api/admin/components/schemas/AdminPostProductsProductVariantsVariantReq.yaml
index e9c9fbe3f2..af5c4c58a6 100644
--- a/docs/api/admin/components/schemas/AdminPostProductsProductVariantsVariantReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostProductsProductVariantsVariantReq.yaml
@@ -1,10 +1,10 @@
 type: object
 properties:
   title:
-    description: The title to identify the Product Variant by.
+    description: The title of the product variant.
     type: string
   sku:
-    description: The unique SKU for the Product Variant.
+    description: The unique SKU of the product variant.
     type: string
   ean:
     description: The EAN number of the item.
@@ -13,80 +13,96 @@ properties:
     description: The UPC number of the item.
     type: string
   barcode:
-    description: A generic GTIN field for the Product Variant.
+    description: A generic GTIN field of the product variant.
     type: string
   hs_code:
-    description: The Harmonized System code for the Product Variant.
+    description: The Harmonized System code of the product variant.
     type: string
   inventory_quantity:
-    description: The amount of stock kept for the Product Variant.
+    description: The amount of stock kept of the product variant.
     type: integer
   allow_backorder:
-    description: Whether the Product Variant can be purchased when out of stock.
+    description: Whether the product variant can be purchased when out of stock.
     type: boolean
   manage_inventory:
-    description: >-
-      Whether Medusa should keep track of the inventory for this Product
-      Variant.
+    description: Whether Medusa should keep track of the inventory of this product variant.
     type: boolean
   weight:
-    description: The weight of the Product Variant.
+    description: The weight of the product variant.
     type: number
   length:
-    description: The length of the Product Variant.
+    description: The length of the product variant.
     type: number
   height:
-    description: The height of the Product Variant.
+    description: The height of the product variant.
     type: number
   width:
-    description: The width of the Product Variant.
+    description: The width of the product variant.
     type: number
   origin_country:
-    description: The country of origin of the Product Variant.
+    description: The country of origin of the product variant.
     type: string
   mid_code:
-    description: The Manufacturer Identification code for the Product Variant.
+    description: The Manufacturer Identification code of the product variant.
     type: string
   material:
-    description: The material composition of the Product Variant.
+    description: The material composition of the product variant.
     type: string
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   prices:
     type: array
+    description: >-
+      An array of product variant prices. A product variant can have different
+      prices for each region or currency code.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices
+      description: Product variant pricing.
     items:
       type: object
       required:
         - amount
       properties:
         id:
-          description: The ID of the price.
+          description: >-
+            The ID of the price. If provided, the existing price will be
+            updated. Otherwise, a new price will be created.
           type: string
         region_id:
           description: >-
-            The ID of the Region for which the price is used. Only required if
-            currency_code is not provided.
+            The ID of the Region the price will be used in. This is only
+            required if `currency_code` is not provided.
           type: string
         currency_code:
           description: >-
-            The 3 character ISO currency code for which the price will be used.
-            Only required if region_id is not provided.
+            The 3 character ISO currency code the price will be used in. This is
+            only required if `region_id` is not provided.
           type: string
           externalDocs:
             url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
             description: See a list of codes.
         amount:
-          description: The amount to charge for the Product Variant.
+          description: The price amount.
           type: integer
         min_quantity:
-          description: The minimum quantity for which the price will be used.
+          description: >-
+            The minimum quantity required to be added to the cart for the price
+            to be used.
           type: integer
         max_quantity:
-          description: The maximum quantity for which the price will be used.
+          description: >-
+            The maximum quantity required to be added to the cart for the price
+            to be used.
           type: integer
   options:
     type: array
+    description: An array of Product Option values that the variant corresponds to.
     items:
       type: object
       required:
@@ -94,8 +110,8 @@ properties:
         - value
       properties:
         option_id:
-          description: The ID of the Product Option to set the value for.
+          description: The ID of the Product Option.
           type: string
         value:
-          description: The value to give for the Product Option.
+          description: The value of the Product Option.
           type: string
diff --git a/docs/api/admin/components/schemas/AdminPostProductsReq.yaml b/docs/api/admin/components/schemas/AdminPostProductsReq.yaml
index 7dcea9ccdc..db649ff2df 100644
--- a/docs/api/admin/components/schemas/AdminPostProductsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostProductsReq.yaml
@@ -9,7 +9,7 @@ properties:
     description: The subtitle of the Product
     type: string
   description:
-    description: A description of the Product.
+    description: The description of the Product.
     type: string
   is_giftcard:
     description: >-
@@ -20,23 +20,33 @@ properties:
     default: false
   discountable:
     description: >-
-      A flag to indicate if discounts can be applied to the LineItems generated
+      A flag to indicate if discounts can be applied to the Line Items generated
       from this Product
     type: boolean
     default: true
   images:
-    description: Images of the Product.
+    description: >-
+      An array of images of the Product. Each value in the array is a URL to the
+      image. You can use the upload endpoints to upload the image and obtain a
+      URL.
     type: array
     items:
       type: string
   thumbnail:
-    description: The thumbnail to use for the Product.
+    description: >-
+      The thumbnail to use for the Product. The value is a URL to the thumbnail.
+      You can use the upload endpoints to upload the thumbnail and obtain a URL.
     type: string
   handle:
-    description: A unique handle to identify the Product by.
+    description: >-
+      A unique handle to identify the Product by. If not provided, the
+      kebab-case version of the product title will be used. This can be used as
+      a slug in URLs.
     type: string
   status:
-    description: The status of the product.
+    description: >-
+      The status of the product. The product is shown to the customer only if
+      its status is `published`.
     type: string
     enum:
       - draft
@@ -51,16 +61,18 @@ properties:
       - value
     properties:
       id:
-        description: The ID of the Product Type.
+        description: >-
+          The ID of an existing Product Type. If not provided, a new product
+          type will be created.
         type: string
       value:
         description: The value of the Product Type.
         type: string
   collection_id:
-    description: The ID of the Collection the Product should belong to.
+    description: The ID of the Product Collection the Product belongs to.
     type: string
   tags:
-    description: Tags to associate the Product with.
+    description: Product Tags to associate the Product with.
     type: array
     items:
       type: object
@@ -68,13 +80,17 @@ properties:
         - value
       properties:
         id:
-          description: The ID of an existing Tag.
+          description: >-
+            The ID of an existing Product Tag. If not provided, a new product
+            tag will be created.
           type: string
         value:
-          description: The value of the Tag, these will be upserted.
+          description: >-
+            The value of the Tag. If the `id` is provided, the value of the
+            existing tag will be updated.
           type: string
   sales_channels:
-    description: '[EXPERIMENTAL] Sales channels to associate the Product with.'
+    description: Sales channels to associate the Product with.
     type: array
     items:
       type: object
@@ -85,7 +101,8 @@ properties:
           description: The ID of an existing Sales channel.
           type: string
   categories:
-    description: Categories to add the Product to.
+    description: Product categories to add the Product to.
+    x-featureFlag: product_categories
     type: array
     items:
       required:
@@ -96,8 +113,8 @@ properties:
           type: string
   options:
     description: >-
-      The Options that the Product should have. These define on which properties
-      the Product's Product Variants will differ.
+      The Options that the Product should have. A new product option will be
+      created for every item in the array.
     type: array
     items:
       type: object
@@ -105,10 +122,12 @@ properties:
         - title
       properties:
         title:
-          description: The title to identify the Product Option by.
+          description: The title of the Product Option.
           type: string
   variants:
-    description: A list of Product Variants to create with the Product.
+    description: >-
+      An array of Product Variants to create with the Product. Each product
+      variant must have a unique combination of Product Option values.
     type: array
     items:
       type: object
@@ -116,10 +135,10 @@ properties:
         - title
       properties:
         title:
-          description: The title to identify the Product Variant by.
+          description: The title of the Product Variant.
           type: string
         sku:
-          description: The unique SKU for the Product Variant.
+          description: The unique SKU of the Product Variant.
           type: string
         ean:
           description: The EAN number of the item.
@@ -128,13 +147,13 @@ properties:
           description: The UPC number of the item.
           type: string
         barcode:
-          description: A generic GTIN field for the Product Variant.
+          description: A generic GTIN field of the Product Variant.
           type: string
         hs_code:
-          description: The Harmonized System code for the Product Variant.
+          description: The Harmonized System code of the Product Variant.
           type: string
         inventory_quantity:
-          description: The amount of stock kept for the Product Variant.
+          description: The amount of stock kept of the Product Variant.
           type: integer
           default: 0
         allow_backorder:
@@ -142,7 +161,7 @@ properties:
           type: boolean
         manage_inventory:
           description: >-
-            Whether Medusa should keep track of the inventory for this Product
+            Whether Medusa should keep track of the inventory of this Product
             Variant.
           type: boolean
         weight:
@@ -161,7 +180,7 @@ properties:
           description: The country of origin of the Product Variant.
           type: string
         mid_code:
-          description: The Manufacturer Identification code for the Product Variant.
+          description: The Manufacturer Identification code of the Product Variant.
           type: string
         material:
           description: The material composition of the Product Variant.
@@ -169,8 +188,21 @@ properties:
         metadata:
           description: An optional set of key-value pairs with additional information.
           type: object
+          externalDocs:
+            description: >-
+              Learn about the metadata attribute, and how to delete and update
+              it.
+            url: >-
+              https://docs.medusajs.com/development/entities/overview#metadata-attribute
         prices:
           type: array
+          description: >-
+            An array of product variant prices. A product variant can have
+            different prices for each region or currency code.
+          externalDocs:
+            url: >-
+              https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices
+            description: Product variant pricing.
           items:
             type: object
             required:
@@ -178,28 +210,40 @@ properties:
             properties:
               region_id:
                 description: >-
-                  The ID of the Region for which the price is used. Only
-                  required if currency_code is not provided.
+                  The ID of the Region the price will be used in. This is only
+                  required if `currency_code` is not provided.
                 type: string
               currency_code:
                 description: >-
-                  The 3 character ISO currency code for which the price will be
-                  used. Only required if region_id is not provided.
+                  The 3 character ISO currency code the price will be used in.
+                  This is only required if `region_id` is not provided.
                 type: string
                 externalDocs:
                   url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
                   description: See a list of codes.
               amount:
-                description: The amount to charge for the Product Variant.
+                description: The price amount.
                 type: integer
               min_quantity:
-                description: The minimum quantity for which the price will be used.
+                description: >-
+                  The minimum quantity required to be added to the cart for the
+                  price to be used.
                 type: integer
               max_quantity:
-                description: The maximum quantity for which the price will be used.
+                description: >-
+                  The maximum quantity required to be added to the cart for the
+                  price to be used.
                 type: integer
         options:
           type: array
+          description: >-
+            An array of Product Option values that the variant corresponds to.
+            The option values should be added into the array in the same index
+            as in the `options` field of the product.
+          externalDocs:
+            url: >-
+              https://docs.medusajs.com/modules/products/admin/manage-products#create-a-product
+            description: Example of how to create a product with options and variants
           items:
             type: object
             required:
@@ -223,13 +267,13 @@ properties:
     description: The width of the Product.
     type: number
   hs_code:
-    description: The Harmonized System code for the Product Variant.
+    description: The Harmonized System code of the Product.
     type: string
   origin_country:
     description: The country of origin of the Product.
     type: string
   mid_code:
-    description: The Manufacturer Identification code for the Product.
+    description: The Manufacturer Identification code of the Product.
     type: string
   material:
     description: The material composition of the Product.
@@ -237,3 +281,7 @@ properties:
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostPublishableApiKeySalesChannelsBatchReq.yaml b/docs/api/admin/components/schemas/AdminPostPublishableApiKeySalesChannelsBatchReq.yaml
index 3e7c404f26..0c36582012 100644
--- a/docs/api/admin/components/schemas/AdminPostPublishableApiKeySalesChannelsBatchReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostPublishableApiKeySalesChannelsBatchReq.yaml
@@ -3,7 +3,7 @@ required:
   - sales_channel_ids
 properties:
   sales_channel_ids:
-    description: The IDs of the sales channels to add to the publishable api key
+    description: The IDs of the sales channels to add to the publishable API key
     type: array
     items:
       type: object
diff --git a/docs/api/admin/components/schemas/AdminPostPublishableApiKeysPublishableApiKeyReq.yaml b/docs/api/admin/components/schemas/AdminPostPublishableApiKeysPublishableApiKeyReq.yaml
index aeed291732..d0a54b266b 100644
--- a/docs/api/admin/components/schemas/AdminPostPublishableApiKeysPublishableApiKeyReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostPublishableApiKeysPublishableApiKeyReq.yaml
@@ -1,5 +1,5 @@
 type: object
 properties:
   title:
-    description: A title to update for the key.
+    description: The title of the Publishable API Key.
     type: string
diff --git a/docs/api/admin/components/schemas/AdminPostPublishableApiKeysReq.yaml b/docs/api/admin/components/schemas/AdminPostPublishableApiKeysReq.yaml
index fa0807e2e7..8cd110a6dc 100644
--- a/docs/api/admin/components/schemas/AdminPostPublishableApiKeysReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostPublishableApiKeysReq.yaml
@@ -3,5 +3,5 @@ required:
   - title
 properties:
   title:
-    description: A title for the publishable api key
+    description: The title of the publishable API key
     type: string
diff --git a/docs/api/admin/components/schemas/AdminPostRegionsRegionFulfillmentProvidersReq.yaml b/docs/api/admin/components/schemas/AdminPostRegionsRegionFulfillmentProvidersReq.yaml
index 6552d1244b..0a0105962b 100644
--- a/docs/api/admin/components/schemas/AdminPostRegionsRegionFulfillmentProvidersReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostRegionsRegionFulfillmentProvidersReq.yaml
@@ -3,5 +3,5 @@ required:
   - provider_id
 properties:
   provider_id:
-    description: The ID of the Fulfillment Provider to add.
+    description: The ID of the Fulfillment Provider.
     type: string
diff --git a/docs/api/admin/components/schemas/AdminPostRegionsRegionPaymentProvidersReq.yaml b/docs/api/admin/components/schemas/AdminPostRegionsRegionPaymentProvidersReq.yaml
index 325284c651..8afda21c45 100644
--- a/docs/api/admin/components/schemas/AdminPostRegionsRegionPaymentProvidersReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostRegionsRegionPaymentProvidersReq.yaml
@@ -3,5 +3,5 @@ required:
   - provider_id
 properties:
   provider_id:
-    description: The ID of the Payment Provider to add.
+    description: The ID of the Payment Provider.
     type: string
diff --git a/docs/api/admin/components/schemas/AdminPostRegionsRegionReq.yaml b/docs/api/admin/components/schemas/AdminPostRegionsRegionReq.yaml
index e55bed24f3..c38fac3063 100644
--- a/docs/api/admin/components/schemas/AdminPostRegionsRegionReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostRegionsRegionReq.yaml
@@ -4,46 +4,51 @@ properties:
     description: The name of the Region
     type: string
   currency_code:
-    description: The 3 character ISO currency code to use for the Region.
+    description: The 3 character ISO currency code to use in the Region.
     type: string
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   automatic_taxes:
     description: >-
-      If true Medusa will automatically calculate taxes for carts in this
-      region. If false you have to manually call POST /carts/:id/taxes.
+      If set to `true`, the Medusa backend will automatically calculate taxes
+      for carts in this region. If set to `false`, the taxes must be calculated
+      manually.
+    externalDocs:
+      url: https://docs.medusajs.com/modules/taxes/storefront/manual-calculation
+      description: How to calculate taxes in a storefront.
     type: boolean
   gift_cards_taxable:
-    description: >-
-      Whether gift cards in this region should be applied sales tax when
-      purchasing a gift card
+    description: If set to `true`, taxes will be applied on gift cards.
     type: boolean
   tax_provider_id:
-    description: The ID of the tax provider to use; if null the system tax provider is used
+    description: >-
+      The ID of the tax provider to use. If none provided, the system tax
+      provider is used.
     type: string
   tax_code:
-    description: An optional tax code the Region.
+    description: The tax code of the Region.
     type: string
   tax_rate:
-    description: The tax rate to use on Orders in the Region.
+    description: The tax rate to use in the Region.
     type: number
   includes_tax:
-    description: '[EXPERIMENTAL] Tax included in prices of region'
+    x-featureFlag: tax_inclusive_pricing
+    description: Whether taxes are included in the prices of the region.
     type: boolean
   payment_providers:
-    description: A list of Payment Provider IDs that should be enabled for the Region
+    description: A list of Payment Provider IDs that can be used in the Region
     type: array
     items:
       type: string
   fulfillment_providers:
-    description: A list of Fulfillment Provider IDs that should be enabled for the Region
+    description: A list of Fulfillment Provider IDs that can be used in the Region
     type: array
     items:
       type: string
   countries:
     description: >-
-      A list of countries' 2 ISO Characters that should be included in the
+      A list of countries' 2 ISO characters that should be included in the
       Region.
     type: array
     items:
diff --git a/docs/api/admin/components/schemas/AdminPostRegionsReq.yaml b/docs/api/admin/components/schemas/AdminPostRegionsReq.yaml
index 1c48e5380c..5ab04aa90b 100644
--- a/docs/api/admin/components/schemas/AdminPostRegionsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostRegionsReq.yaml
@@ -11,30 +11,30 @@ properties:
     description: The name of the Region
     type: string
   currency_code:
-    description: The 3 character ISO currency code to use for the Region.
+    description: The 3 character ISO currency code to use in the Region.
     type: string
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   tax_code:
-    description: An optional tax code the Region.
+    description: The tax code of the Region.
     type: string
   tax_rate:
-    description: The tax rate to use on Orders in the Region.
+    description: The tax rate to use in the Region.
     type: number
   payment_providers:
-    description: A list of Payment Provider IDs that should be enabled for the Region
+    description: A list of Payment Provider IDs that can be used in the Region
     type: array
     items:
       type: string
   fulfillment_providers:
-    description: A list of Fulfillment Provider IDs that should be enabled for the Region
+    description: A list of Fulfillment Provider IDs that can be used in the Region
     type: array
     items:
       type: string
   countries:
     description: >-
-      A list of countries' 2 ISO Characters that should be included in the
+      A list of countries' 2 ISO characters that should be included in the
       Region.
     example:
       - US
@@ -42,5 +42,6 @@ properties:
     items:
       type: string
   includes_tax:
-    description: '[EXPERIMENTAL] Tax included in prices of region'
+    x-featureFlag: tax_inclusive_pricing
+    description: Whether taxes are included in the prices of the region.
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostReservationsReq.yaml b/docs/api/admin/components/schemas/AdminPostReservationsReq.yaml
index e08aad2afc..14bbbad8b6 100644
--- a/docs/api/admin/components/schemas/AdminPostReservationsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostReservationsReq.yaml
@@ -5,17 +5,21 @@ required:
   - quantity
 properties:
   line_item_id:
-    description: The id of the location of the reservation
+    description: The ID of the line item of the reservation.
     type: string
   location_id:
-    description: The id of the location of the reservation
+    description: The ID of the location of the reservation.
     type: string
   inventory_item_id:
-    description: The id of the inventory item the reservation relates to
+    description: The ID of the inventory item the reservation is associated with.
     type: string
   quantity:
-    description: The id of the reservation item
+    description: The quantity to reserve.
     type: number
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostReservationsReservationReq.yaml b/docs/api/admin/components/schemas/AdminPostReservationsReservationReq.yaml
index b74d42c336..56c51300bf 100644
--- a/docs/api/admin/components/schemas/AdminPostReservationsReservationReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostReservationsReservationReq.yaml
@@ -1,11 +1,15 @@
 type: object
 properties:
   location_id:
-    description: The id of the location of the reservation
+    description: The ID of the location associated with the reservation.
     type: string
   quantity:
-    description: The id of the reservation item
+    description: The quantity to reserve.
     type: number
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostReturnReasonsReasonReq.yaml b/docs/api/admin/components/schemas/AdminPostReturnReasonsReasonReq.yaml
index 383ba92bfc..29add7bd23 100644
--- a/docs/api/admin/components/schemas/AdminPostReturnReasonsReasonReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostReturnReasonsReasonReq.yaml
@@ -4,11 +4,15 @@ properties:
     description: The label to display to the Customer.
     type: string
   value:
-    description: The value that the Return Reason will be identified by. Must be unique.
+    description: A unique value of the return reason.
     type: string
   description:
-    description: An optional description to for the Reason.
+    description: The description of the Reason.
     type: string
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostReturnReasonsReq.yaml b/docs/api/admin/components/schemas/AdminPostReturnReasonsReq.yaml
index ce30d0eefe..61574e3262 100644
--- a/docs/api/admin/components/schemas/AdminPostReturnReasonsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostReturnReasonsReq.yaml
@@ -7,14 +7,18 @@ properties:
     description: The label to display to the Customer.
     type: string
   value:
-    description: The value that the Return Reason will be identified by. Must be unique.
+    description: A unique value of the return reason.
     type: string
   parent_return_reason_id:
     description: The ID of the parent return reason.
     type: string
   description:
-    description: An optional description to for the Reason.
+    description: The description of the Reason.
     type: string
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostSalesChannelsReq.yaml b/docs/api/admin/components/schemas/AdminPostSalesChannelsReq.yaml
index 20fa813fa5..6f6e01cc4d 100644
--- a/docs/api/admin/components/schemas/AdminPostSalesChannelsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostSalesChannelsReq.yaml
@@ -9,5 +9,5 @@ properties:
     description: The description of the Sales Channel
     type: string
   is_disabled:
-    description: Whether the Sales Channel is disabled or not.
+    description: Whether the Sales Channel is disabled.
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostSalesChannelsSalesChannelReq.yaml b/docs/api/admin/components/schemas/AdminPostSalesChannelsSalesChannelReq.yaml
index 50df11bd37..8c45cfa8c1 100644
--- a/docs/api/admin/components/schemas/AdminPostSalesChannelsSalesChannelReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostSalesChannelsSalesChannelReq.yaml
@@ -2,10 +2,10 @@ type: object
 properties:
   name:
     type: string
-    description: Name of the sales channel.
+    description: The name of the sales channel
   description:
     type: string
-    description: Sales Channel description.
+    description: The description of the sales channel.
   is_disabled:
     type: boolean
-    description: Indication of if the sales channel is active.
+    description: Whether the Sales Channel is disabled.
diff --git a/docs/api/admin/components/schemas/AdminPostShippingOptionsOptionReq.yaml b/docs/api/admin/components/schemas/AdminPostShippingOptionsOptionReq.yaml
index 29bb98c358..da4ee33dec 100644
--- a/docs/api/admin/components/schemas/AdminPostShippingOptionsOptionReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostShippingOptionsOptionReq.yaml
@@ -6,14 +6,22 @@ properties:
     description: The name of the Shipping Option
     type: string
   amount:
-    description: The amount to charge for the Shipping Option.
+    description: >-
+      The amount to charge for the Shipping Option. If the `price_type` of the
+      shipping option is `calculated`, this amount will not actually be used.
     type: integer
   admin_only:
-    description: If true, the option can be used for draft orders
+    description: >-
+      If set to `true`, the shipping option can only be used when creating draft
+      orders.
     type: boolean
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   requirements:
     description: >-
       The requirements that must be satisfied for the Shipping Option to be
@@ -26,7 +34,10 @@ properties:
         - amount
       properties:
         id:
-          description: The ID of the requirement
+          description: >-
+            The ID of an existing requirement. If an ID is passed, the existing
+            requirement's details are updated. Otherwise, a new requirement is
+            created.
           type: string
         type:
           description: The type of the requirement
@@ -38,5 +49,6 @@ properties:
           description: The amount to compare with.
           type: integer
   includes_tax:
-    description: '[EXPERIMENTAL] Tax included in prices of shipping option'
+    description: Tax included in prices of shipping option
+    x-featureFlag: tax_inclusive_pricing
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostShippingOptionsReq.yaml b/docs/api/admin/components/schemas/AdminPostShippingOptionsReq.yaml
index 632348bb8b..5ba35c798e 100644
--- a/docs/api/admin/components/schemas/AdminPostShippingOptionsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostShippingOptionsReq.yaml
@@ -24,13 +24,18 @@ properties:
       Shipping Option.
     type: object
   price_type:
-    description: The type of the Shipping Option price.
+    description: >-
+      The type of the Shipping Option price. `flat_rate` indicates fixed
+      pricing, whereas `calculated` indicates that the price will be calculated
+      each time by the fulfillment provider.
     type: string
     enum:
       - flat_rate
       - calculated
   amount:
-    description: The amount to charge for the Shipping Option.
+    description: >-
+      The amount to charge for the Shipping Option. If the `price_type` is set
+      to `calculated`, this amount will not actually be used.
     type: integer
   requirements:
     description: >-
@@ -53,16 +58,23 @@ properties:
           description: The amount to compare with.
           type: integer
   is_return:
-    description: Whether the Shipping Option defines a return shipment.
+    description: Whether the Shipping Option can be used for returns or during checkout.
     type: boolean
     default: false
   admin_only:
-    description: If true, the option can be used for draft orders
+    description: >-
+      If set to `true`, the shipping option can only be used when creating draft
+      orders.
     type: boolean
     default: false
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   includes_tax:
-    description: '[EXPERIMENTAL] Tax included in prices of shipping option'
+    description: Tax included in prices of shipping option
+    x-featureFlag: tax_inclusive_pricing
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPostShippingProfilesProfileReq.yaml b/docs/api/admin/components/schemas/AdminPostShippingProfilesProfileReq.yaml
index 17ec3543b0..cb096bcfd1 100644
--- a/docs/api/admin/components/schemas/AdminPostShippingProfilesProfileReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostShippingProfilesProfileReq.yaml
@@ -6,6 +6,10 @@ properties:
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   type:
     description: The type of the Shipping Profile
     type: string
@@ -14,10 +18,8 @@ properties:
       - gift_card
       - custom
   products:
-    description: An optional array of product ids to associate with the Shipping Profile
+    description: product IDs to associate with the Shipping Profile
     type: array
   shipping_options:
-    description: >-
-      An optional array of shipping option ids to associate with the Shipping
-      Profile
+    description: Shipping option IDs to associate with the Shipping Profile
     type: array
diff --git a/docs/api/admin/components/schemas/AdminPostStockLocationsLocationReq.yaml b/docs/api/admin/components/schemas/AdminPostStockLocationsLocationReq.yaml
index 94bc44d6d2..9762d74719 100644
--- a/docs/api/admin/components/schemas/AdminPostStockLocationsLocationReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostStockLocationsLocationReq.yaml
@@ -11,5 +11,9 @@ properties:
     description: An optional key-value map with additional details
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   address:
     $ref: ./StockLocationAddressInput.yaml
diff --git a/docs/api/admin/components/schemas/AdminPostStockLocationsReq.yaml b/docs/api/admin/components/schemas/AdminPostStockLocationsReq.yaml
index 7507b09127..e9f228e3e5 100644
--- a/docs/api/admin/components/schemas/AdminPostStockLocationsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostStockLocationsReq.yaml
@@ -6,12 +6,21 @@ properties:
     description: the name of the stock location
     type: string
   address_id:
-    description: the stock location address ID
+    description: >-
+      the ID of an existing stock location address to associate with the stock
+      location. Only required if `address` is not provided.
     type: string
   metadata:
     type: object
     description: An optional key-value map with additional details
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   address:
+    description: >-
+      A new stock location address to create and associate with the stock
+      location. Only required if `address_id` is not provided.
     $ref: ./StockLocationAddressInput.yaml
diff --git a/docs/api/admin/components/schemas/AdminPostStockLocationsReqAddress.yaml b/docs/api/admin/components/schemas/AdminPostStockLocationsReqAddress.yaml
new file mode 100644
index 0000000000..e5de8e0677
--- /dev/null
+++ b/docs/api/admin/components/schemas/AdminPostStockLocationsReqAddress.yaml
@@ -0,0 +1,39 @@
+type: object
+required:
+  - address_1
+  - country_code
+properties:
+  address_1:
+    type: string
+    description: Stock location address
+    example: 35, Jhon Doe Ave
+  address_2:
+    type: string
+    description: Stock location address' complement
+    example: apartment 4432
+  company:
+    type: string
+    description: Stock location address' company
+  city:
+    type: string
+    description: Stock location address' city
+    example: Mexico city
+  country_code:
+    description: The 2 character ISO code for the country.
+    type: string
+    externalDocs:
+      url: >-
+        https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+      description: See a list of codes.
+  phone:
+    type: string
+    description: Stock location address' phone number
+    example: +1 555 61646
+  postal_code:
+    type: string
+    description: Stock location address' postal code
+    example: HD3-1G8
+  province:
+    type: string
+    description: Stock location address' province
+    example: Sinaloa
diff --git a/docs/api/admin/components/schemas/AdminPostStoreReq.yaml b/docs/api/admin/components/schemas/AdminPostStoreReq.yaml
index 6a6f746821..a1c9143841 100644
--- a/docs/api/admin/components/schemas/AdminPostStoreReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostStoreReq.yaml
@@ -4,29 +4,39 @@ properties:
     description: The name of the Store
     type: string
   swap_link_template:
-    description: A template for Swap links - use `{{cart_id}}` to insert the Swap Cart id
+    description: A template for Swap links - use `{{cart_id}}` to insert the Swap Cart ID
     type: string
+    example: http://example.com/swaps/{{cart_id}}
   payment_link_template:
-    description: >-
-      A template for payment links links - use `{{cart_id}}` to insert the Cart
-      id
+    description: A template for payment links - use `{{cart_id}}` to insert the Cart ID
+    example: http://example.com/payments/{{cart_id}}
     type: string
   invite_link_template:
     description: >-
       A template for invite links - use `{{invite_token}}` to insert the invite
       token
+    example: http://example.com/invite?token={{invite_token}}
     type: string
   default_currency_code:
-    description: The default currency code for the Store.
+    description: The default currency code of the Store.
     type: string
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currencies:
-    description: Array of currencies in 2 character ISO code format.
+    description: >-
+      Array of available currencies in the store. Each currency is in 3
+      character ISO code format.
     type: array
     items:
       type: string
+      externalDocs:
+        url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+        description: See a list of codes.
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminPostTaxRatesReq.yaml b/docs/api/admin/components/schemas/AdminPostTaxRatesReq.yaml
index ac7bcd0575..e761008909 100644
--- a/docs/api/admin/components/schemas/AdminPostTaxRatesReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostTaxRatesReq.yaml
@@ -6,19 +6,19 @@ required:
 properties:
   code:
     type: string
-    description: A code to identify the tax type by
+    description: The code of the tax rate.
   name:
     type: string
-    description: A human friendly name for the tax
+    description: The name of the tax rate.
   region_id:
     type: string
-    description: The ID of the Region that the rate belongs to
+    description: The ID of the Region that the tax rate belongs to.
   rate:
     type: number
-    description: The numeric rate to charge
+    description: The numeric rate to charge.
   products:
     type: array
-    description: The IDs of the products associated with this tax rate
+    description: The IDs of the products associated with this tax rate.
     items:
       type: string
   shipping_options:
diff --git a/docs/api/admin/components/schemas/AdminPostTaxRatesTaxRateReq.yaml b/docs/api/admin/components/schemas/AdminPostTaxRatesTaxRateReq.yaml
index 93b1597180..b16850d706 100644
--- a/docs/api/admin/components/schemas/AdminPostTaxRatesTaxRateReq.yaml
+++ b/docs/api/admin/components/schemas/AdminPostTaxRatesTaxRateReq.yaml
@@ -2,16 +2,16 @@ type: object
 properties:
   code:
     type: string
-    description: A code to identify the tax type by
+    description: The code of the tax rate.
   name:
     type: string
-    description: A human friendly name for the tax
+    description: The name of the tax rate.
   region_id:
     type: string
-    description: The ID of the Region that the rate belongs to
+    description: The ID of the Region that the tax rate belongs to.
   rate:
     type: number
-    description: The numeric rate to charge
+    description: The numeric rate to charge.
   products:
     type: array
     description: The IDs of the products associated with this tax rate
@@ -24,6 +24,6 @@ properties:
       type: string
   product_types:
     type: array
-    description: The IDs of the types of products associated with this tax rate
+    description: The IDs of the types of product types associated with this tax rate
     items:
       type: string
diff --git a/docs/api/admin/components/schemas/AdminPriceListDeleteBatchRes.yaml b/docs/api/admin/components/schemas/AdminPriceListDeleteBatchRes.yaml
index 4f128a04d4..9886cd7408 100644
--- a/docs/api/admin/components/schemas/AdminPriceListDeleteBatchRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPriceListDeleteBatchRes.yaml
@@ -8,10 +8,12 @@ properties:
     type: array
     items:
       type: string
-      description: The IDs of the deleted Money Amounts (Prices).
+      description: The IDs of the deleted prices.
   object:
     type: string
-    description: The type of the object that was deleted.
+    description: >-
+      The type of the object that was deleted. A price is also named
+      `money-amount`.
     default: money-amount
   deleted:
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPriceListDeleteProductPricesRes.yaml b/docs/api/admin/components/schemas/AdminPriceListDeleteProductPricesRes.yaml
index 23239ef090..28f88ffb6d 100644
--- a/docs/api/admin/components/schemas/AdminPriceListDeleteProductPricesRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPriceListDeleteProductPricesRes.yaml
@@ -6,12 +6,14 @@ required:
 properties:
   ids:
     type: array
-    description: The price ids that have been deleted.
+    description: The IDs of the deleted prices.
     items:
       type: string
   object:
     type: string
-    description: The type of the object that was deleted.
+    description: >-
+      The type of the object that was deleted. A price is also named
+      `money-amount`.
     default: money-amount
   deleted:
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPriceListDeleteVariantPricesRes.yaml b/docs/api/admin/components/schemas/AdminPriceListDeleteVariantPricesRes.yaml
index 23239ef090..28f88ffb6d 100644
--- a/docs/api/admin/components/schemas/AdminPriceListDeleteVariantPricesRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPriceListDeleteVariantPricesRes.yaml
@@ -6,12 +6,14 @@ required:
 properties:
   ids:
     type: array
-    description: The price ids that have been deleted.
+    description: The IDs of the deleted prices.
     items:
       type: string
   object:
     type: string
-    description: The type of the object that was deleted.
+    description: >-
+      The type of the object that was deleted. A price is also named
+      `money-amount`.
     default: money-amount
   deleted:
     type: boolean
diff --git a/docs/api/admin/components/schemas/AdminPriceListRes.yaml b/docs/api/admin/components/schemas/AdminPriceListRes.yaml
index 53323693f2..6ea0db5299 100644
--- a/docs/api/admin/components/schemas/AdminPriceListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPriceListRes.yaml
@@ -8,4 +8,5 @@ required:
   - price_list
 properties:
   price_list:
+    description: Price List details.
     $ref: ./PriceList.yaml
diff --git a/docs/api/admin/components/schemas/AdminPriceListsListRes.yaml b/docs/api/admin/components/schemas/AdminPriceListsListRes.yaml
index e11bd28269..ee8358997f 100644
--- a/docs/api/admin/components/schemas/AdminPriceListsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPriceListsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   price_lists:
     type: array
+    description: An array of price lists details.
     items:
       $ref: ./PriceList.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of price lists skipped when retrieving the price lists.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminPriceListsProductsListRes.yaml b/docs/api/admin/components/schemas/AdminPriceListsProductsListRes.yaml
index 9098b75a16..2ef7a8aa35 100644
--- a/docs/api/admin/components/schemas/AdminPriceListsProductsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPriceListsProductsListRes.yaml
@@ -18,6 +18,7 @@ required:
 properties:
   products:
     type: array
+    description: An array of products details.
     items:
       $ref: ./Product.yaml
   count:
@@ -25,7 +26,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of price lists skipped when retrieving the price lists.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminProductCategoriesCategoryRes.yaml b/docs/api/admin/components/schemas/AdminProductCategoriesCategoryRes.yaml
index eaf81a7222..bc22b78246 100644
--- a/docs/api/admin/components/schemas/AdminProductCategoriesCategoryRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductCategoriesCategoryRes.yaml
@@ -8,4 +8,5 @@ required:
   - product_category
 properties:
   product_category:
+    description: Product category details.
     $ref: ./ProductCategory.yaml
diff --git a/docs/api/admin/components/schemas/AdminProductCategoriesListRes.yaml b/docs/api/admin/components/schemas/AdminProductCategoriesListRes.yaml
index f053d45d1e..5c00fdc6d4 100644
--- a/docs/api/admin/components/schemas/AdminProductCategoriesListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductCategoriesListRes.yaml
@@ -12,6 +12,7 @@ required:
 properties:
   product_categories:
     type: array
+    description: An array of product category details.
     items:
       $ref: ./ProductCategory.yaml
   count:
@@ -19,7 +20,9 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: >-
+      The number of product categories skipped when retrieving the product
+      categories.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminProductTagsListRes.yaml b/docs/api/admin/components/schemas/AdminProductTagsListRes.yaml
index 405eac0731..199eb7e7a2 100644
--- a/docs/api/admin/components/schemas/AdminProductTagsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductTagsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   product_tags:
     type: array
+    description: An array of product tag details.
     items:
       $ref: ./ProductTag.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of product tags skipped when retrieving the product tags.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminProductTypesListRes.yaml b/docs/api/admin/components/schemas/AdminProductTypesListRes.yaml
index 774ce804cc..643254d68d 100644
--- a/docs/api/admin/components/schemas/AdminProductTypesListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductTypesListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   product_types:
     type: array
+    description: An array of product types details.
     items:
       $ref: ./ProductType.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of product types skipped when retrieving the product types.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminProductsDeleteOptionRes.yaml b/docs/api/admin/components/schemas/AdminProductsDeleteOptionRes.yaml
index a30ba74881..d3811c810e 100644
--- a/docs/api/admin/components/schemas/AdminProductsDeleteOptionRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductsDeleteOptionRes.yaml
@@ -28,4 +28,5 @@ properties:
     description: Whether or not the items were deleted.
     default: true
   product:
+    description: Product details.
     $ref: ./PricedProduct.yaml
diff --git a/docs/api/admin/components/schemas/AdminProductsDeleteVariantRes.yaml b/docs/api/admin/components/schemas/AdminProductsDeleteVariantRes.yaml
index 1d4a1c61ac..4b2277cce2 100644
--- a/docs/api/admin/components/schemas/AdminProductsDeleteVariantRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductsDeleteVariantRes.yaml
@@ -28,4 +28,5 @@ properties:
     description: Whether or not the items were deleted.
     default: true
   product:
+    description: Product details.
     $ref: ./PricedProduct.yaml
diff --git a/docs/api/admin/components/schemas/AdminProductsListRes.yaml b/docs/api/admin/components/schemas/AdminProductsListRes.yaml
index 1101d87cfe..f812bb637f 100644
--- a/docs/api/admin/components/schemas/AdminProductsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductsListRes.yaml
@@ -20,6 +20,7 @@ required:
 properties:
   products:
     type: array
+    description: An array of products details.
     items:
       $ref: ./PricedProduct.yaml
   count:
@@ -27,7 +28,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of products skipped when retrieving the products.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminProductsListTagsRes.yaml b/docs/api/admin/components/schemas/AdminProductsListTagsRes.yaml
index 36dee5cf26..cbf191a7a7 100644
--- a/docs/api/admin/components/schemas/AdminProductsListTagsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductsListTagsRes.yaml
@@ -3,6 +3,7 @@ required:
   - tags
 properties:
   tags:
+    description: An array of product tags details.
     type: array
     items:
       type: object
diff --git a/docs/api/admin/components/schemas/AdminProductsListTypesRes.yaml b/docs/api/admin/components/schemas/AdminProductsListTypesRes.yaml
index b9ce359c5d..fac5b6cfac 100644
--- a/docs/api/admin/components/schemas/AdminProductsListTypesRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductsListTypesRes.yaml
@@ -4,5 +4,6 @@ required:
 properties:
   types:
     type: array
+    description: An array of product types details.
     items:
       $ref: ./ProductType.yaml
diff --git a/docs/api/admin/components/schemas/AdminProductsListVariantsRes.yaml b/docs/api/admin/components/schemas/AdminProductsListVariantsRes.yaml
index 9f9bd329d9..e70bf99b9e 100644
--- a/docs/api/admin/components/schemas/AdminProductsListVariantsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductsListVariantsRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   variants:
     type: array
+    description: An array of product variants details.
     items:
       $ref: ./ProductVariant.yaml
   count:
@@ -14,7 +15,9 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: >-
+      The number of product variants skipped when retrieving the product
+      variants.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminProductsRes.yaml b/docs/api/admin/components/schemas/AdminProductsRes.yaml
index 0845416c01..93d2af1704 100644
--- a/docs/api/admin/components/schemas/AdminProductsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminProductsRes.yaml
@@ -14,4 +14,5 @@ required:
   - product
 properties:
   product:
+    description: Product details.
     $ref: ./PricedProduct.yaml
diff --git a/docs/api/admin/components/schemas/AdminPublishableApiKeyDeleteRes.yaml b/docs/api/admin/components/schemas/AdminPublishableApiKeyDeleteRes.yaml
index 0714ea5231..5bab265f39 100644
--- a/docs/api/admin/components/schemas/AdminPublishableApiKeyDeleteRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPublishableApiKeyDeleteRes.yaml
@@ -6,12 +6,12 @@ required:
 properties:
   id:
     type: string
-    description: The ID of the deleted PublishableApiKey.
+    description: The ID of the deleted publishable API key.
   object:
     type: string
     description: The type of the object that was deleted.
     default: publishable_api_key
   deleted:
     type: boolean
-    description: Whether the PublishableApiKeys was deleted.
+    description: Whether the publishable API key was deleted.
     default: true
diff --git a/docs/api/admin/components/schemas/AdminPublishableApiKeysListRes.yaml b/docs/api/admin/components/schemas/AdminPublishableApiKeysListRes.yaml
index 59f953bb88..5afc36dcf9 100644
--- a/docs/api/admin/components/schemas/AdminPublishableApiKeysListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPublishableApiKeysListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   publishable_api_keys:
     type: array
+    description: An array of publishable API keys details.
     items:
       $ref: ./PublishableApiKey.yaml
   count:
@@ -14,7 +15,9 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: >-
+      The number of publishable API keys skipped when retrieving the publishable
+      API keys.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminPublishableApiKeysListSalesChannelsRes.yaml b/docs/api/admin/components/schemas/AdminPublishableApiKeysListSalesChannelsRes.yaml
index 35678ee35a..416fd103b8 100644
--- a/docs/api/admin/components/schemas/AdminPublishableApiKeysListSalesChannelsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPublishableApiKeysListSalesChannelsRes.yaml
@@ -3,6 +3,7 @@ required:
   - sales_channels
 properties:
   sales_channels:
+    description: An array of sales channels details.
     type: array
     items:
       $ref: ./SalesChannel.yaml
diff --git a/docs/api/admin/components/schemas/AdminPublishableApiKeysRes.yaml b/docs/api/admin/components/schemas/AdminPublishableApiKeysRes.yaml
index c994cac4db..eb0d3fefbc 100644
--- a/docs/api/admin/components/schemas/AdminPublishableApiKeysRes.yaml
+++ b/docs/api/admin/components/schemas/AdminPublishableApiKeysRes.yaml
@@ -3,4 +3,5 @@ required:
   - publishable_api_key
 properties:
   publishable_api_key:
+    description: Publishable API key details.
     $ref: ./PublishableApiKey.yaml
diff --git a/docs/api/admin/components/schemas/AdminRefundRes.yaml b/docs/api/admin/components/schemas/AdminRefundRes.yaml
index 9f159d8a63..20dd7559fe 100644
--- a/docs/api/admin/components/schemas/AdminRefundRes.yaml
+++ b/docs/api/admin/components/schemas/AdminRefundRes.yaml
@@ -3,4 +3,5 @@ required:
   - refund
 properties:
   refund:
+    description: Refund details
     $ref: ./Refund.yaml
diff --git a/docs/api/admin/components/schemas/AdminRegionsListRes.yaml b/docs/api/admin/components/schemas/AdminRegionsListRes.yaml
index c5ff015351..4af8c05732 100644
--- a/docs/api/admin/components/schemas/AdminRegionsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminRegionsListRes.yaml
@@ -16,6 +16,7 @@ required:
 properties:
   regions:
     type: array
+    description: An array of regions details.
     items:
       $ref: ./Region.yaml
   count:
@@ -23,7 +24,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of regions skipped when retrieving the regions.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminRegionsRes.yaml b/docs/api/admin/components/schemas/AdminRegionsRes.yaml
index 4e52f90323..b2f409ff6b 100644
--- a/docs/api/admin/components/schemas/AdminRegionsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminRegionsRes.yaml
@@ -12,4 +12,5 @@ required:
   - region
 properties:
   region:
+    description: Region details.
     $ref: ./Region.yaml
diff --git a/docs/api/admin/components/schemas/AdminReservationsListRes.yaml b/docs/api/admin/components/schemas/AdminReservationsListRes.yaml
index d5b8dc1ad3..1518e2bee4 100644
--- a/docs/api/admin/components/schemas/AdminReservationsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminReservationsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   reservations:
     type: array
+    description: An array of reservations details.
     items:
       $ref: ./ExtendedReservationItem.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of reservations skipped when retrieving the reservations.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminReservationsRes.yaml b/docs/api/admin/components/schemas/AdminReservationsRes.yaml
index 6428010b23..ab8cf9ab40 100644
--- a/docs/api/admin/components/schemas/AdminReservationsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminReservationsRes.yaml
@@ -3,4 +3,5 @@ required:
   - reservation
 properties:
   reservation:
+    description: Reservation details.
     $ref: ./ReservationItemDTO.yaml
diff --git a/docs/api/admin/components/schemas/AdminResetPasswordRequest.yaml b/docs/api/admin/components/schemas/AdminResetPasswordRequest.yaml
index 149a0bddd6..efbec17c4a 100644
--- a/docs/api/admin/components/schemas/AdminResetPasswordRequest.yaml
+++ b/docs/api/admin/components/schemas/AdminResetPasswordRequest.yaml
@@ -4,13 +4,13 @@ required:
   - password
 properties:
   email:
-    description: The Users email.
+    description: The User's email.
     type: string
     format: email
   token:
-    description: The token generated from the 'password-token' endpoint.
+    description: The password-reset token generated when the password reset was requested.
     type: string
   password:
-    description: The Users new password.
+    description: The User's new password.
     type: string
     format: password
diff --git a/docs/api/admin/components/schemas/AdminResetPasswordTokenRequest.yaml b/docs/api/admin/components/schemas/AdminResetPasswordTokenRequest.yaml
index 22f7609d2e..ed2bacd924 100644
--- a/docs/api/admin/components/schemas/AdminResetPasswordTokenRequest.yaml
+++ b/docs/api/admin/components/schemas/AdminResetPasswordTokenRequest.yaml
@@ -3,6 +3,6 @@ required:
   - email
 properties:
   email:
-    description: The Users email.
+    description: The User's email.
     type: string
     format: email
diff --git a/docs/api/admin/components/schemas/AdminReturnsCancelRes.yaml b/docs/api/admin/components/schemas/AdminReturnsCancelRes.yaml
index ab11b5eeb5..771effd6e6 100644
--- a/docs/api/admin/components/schemas/AdminReturnsCancelRes.yaml
+++ b/docs/api/admin/components/schemas/AdminReturnsCancelRes.yaml
@@ -51,4 +51,5 @@ required:
   - order
 properties:
   order:
+    description: Order details.
     $ref: ./Order.yaml
diff --git a/docs/api/admin/components/schemas/AdminReturnsListRes.yaml b/docs/api/admin/components/schemas/AdminReturnsListRes.yaml
index 57b6eb15e5..350a3250c7 100644
--- a/docs/api/admin/components/schemas/AdminReturnsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminReturnsListRes.yaml
@@ -12,6 +12,7 @@ required:
 properties:
   returns:
     type: array
+    description: An array of returns details.
     items:
       $ref: ./Return.yaml
   count:
@@ -19,7 +20,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of returns skipped when retrieving the returns.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminReturnsRes.yaml b/docs/api/admin/components/schemas/AdminReturnsRes.yaml
index f8000dec9b..a7d799fb76 100644
--- a/docs/api/admin/components/schemas/AdminReturnsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminReturnsRes.yaml
@@ -7,4 +7,5 @@ required:
   - return
 properties:
   return:
+    description: Return details.
     $ref: ./Return.yaml
diff --git a/docs/api/admin/components/schemas/AdminSalesChannelsListRes.yaml b/docs/api/admin/components/schemas/AdminSalesChannelsListRes.yaml
index ed590a4737..5e64079787 100644
--- a/docs/api/admin/components/schemas/AdminSalesChannelsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminSalesChannelsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   sales_channels:
     type: array
+    description: An array of sales channels details.
     items:
       $ref: ./SalesChannel.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of items skipped before the returned results
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminSalesChannelsRes.yaml b/docs/api/admin/components/schemas/AdminSalesChannelsRes.yaml
index fda0b10e76..6ceb950176 100644
--- a/docs/api/admin/components/schemas/AdminSalesChannelsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminSalesChannelsRes.yaml
@@ -3,4 +3,5 @@ required:
   - sales_channel
 properties:
   sales_channel:
+    description: Sales Channel's details.
     $ref: ./SalesChannel.yaml
diff --git a/docs/api/admin/components/schemas/AdminShippingOptionsListRes.yaml b/docs/api/admin/components/schemas/AdminShippingOptionsListRes.yaml
index 7c8ae6f7ad..3847d8b0c7 100644
--- a/docs/api/admin/components/schemas/AdminShippingOptionsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminShippingOptionsListRes.yaml
@@ -16,6 +16,7 @@ required:
 properties:
   shipping_options:
     type: array
+    description: An array of shipping options details.
     items:
       $ref: ./ShippingOption.yaml
   count:
@@ -23,7 +24,9 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: >-
+      The number of shipping options skipped when retrieving the shipping
+      options.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminShippingOptionsRes.yaml b/docs/api/admin/components/schemas/AdminShippingOptionsRes.yaml
index 4b11048199..460a1483a5 100644
--- a/docs/api/admin/components/schemas/AdminShippingOptionsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminShippingOptionsRes.yaml
@@ -12,4 +12,5 @@ required:
   - shipping_option
 properties:
   shipping_option:
+    description: Shipping option details.
     $ref: ./ShippingOption.yaml
diff --git a/docs/api/admin/components/schemas/AdminShippingProfilesListRes.yaml b/docs/api/admin/components/schemas/AdminShippingProfilesListRes.yaml
index f0eaa82aac..6b4d186f8c 100644
--- a/docs/api/admin/components/schemas/AdminShippingProfilesListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminShippingProfilesListRes.yaml
@@ -4,5 +4,6 @@ required:
 properties:
   shipping_profiles:
     type: array
+    description: An array of shipping profiles details.
     items:
       $ref: ./ShippingProfile.yaml
diff --git a/docs/api/admin/components/schemas/AdminShippingProfilesRes.yaml b/docs/api/admin/components/schemas/AdminShippingProfilesRes.yaml
index 9e56d94a2f..b3a3413b62 100644
--- a/docs/api/admin/components/schemas/AdminShippingProfilesRes.yaml
+++ b/docs/api/admin/components/schemas/AdminShippingProfilesRes.yaml
@@ -8,4 +8,5 @@ required:
   - shipping_profile
 properties:
   shipping_profile:
+    description: Shipping profile details.
     $ref: ./ShippingProfile.yaml
diff --git a/docs/api/admin/components/schemas/AdminStockLocationsListRes.yaml b/docs/api/admin/components/schemas/AdminStockLocationsListRes.yaml
index aa29877a00..6d29c11c9d 100644
--- a/docs/api/admin/components/schemas/AdminStockLocationsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminStockLocationsListRes.yaml
@@ -14,7 +14,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of stock locations skipped when retrieving the stock locations.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminStockLocationsRes.yaml b/docs/api/admin/components/schemas/AdminStockLocationsRes.yaml
index c382f72085..4c4ec94220 100644
--- a/docs/api/admin/components/schemas/AdminStockLocationsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminStockLocationsRes.yaml
@@ -3,4 +3,5 @@ required:
   - stock_location
 properties:
   stock_location:
+    description: Stock location details.
     $ref: ./StockLocationExpandedDTO.yaml
diff --git a/docs/api/admin/components/schemas/AdminStoresRes.yaml b/docs/api/admin/components/schemas/AdminStoresRes.yaml
index a02586a781..bf36cffbb8 100644
--- a/docs/api/admin/components/schemas/AdminStoresRes.yaml
+++ b/docs/api/admin/components/schemas/AdminStoresRes.yaml
@@ -3,4 +3,5 @@ required:
   - store
 properties:
   store:
+    description: Store details.
     $ref: ./Store.yaml
diff --git a/docs/api/admin/components/schemas/AdminSwapsListRes.yaml b/docs/api/admin/components/schemas/AdminSwapsListRes.yaml
index da2e08617d..300860d604 100644
--- a/docs/api/admin/components/schemas/AdminSwapsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminSwapsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   swaps:
     type: array
+    description: An array of swaps details.
     items:
       $ref: ./Swap.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of swaps skipped when retrieving the swaps.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminSwapsRes.yaml b/docs/api/admin/components/schemas/AdminSwapsRes.yaml
index d95facc390..485be172fd 100644
--- a/docs/api/admin/components/schemas/AdminSwapsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminSwapsRes.yaml
@@ -21,4 +21,5 @@ required:
   - swap
 properties:
   swap:
+    description: Swap details.
     $ref: ./Swap.yaml
diff --git a/docs/api/admin/components/schemas/AdminTaxProvidersList.yaml b/docs/api/admin/components/schemas/AdminTaxProvidersList.yaml
index e924eba7a3..6167447314 100644
--- a/docs/api/admin/components/schemas/AdminTaxProvidersList.yaml
+++ b/docs/api/admin/components/schemas/AdminTaxProvidersList.yaml
@@ -4,5 +4,6 @@ required:
 properties:
   tax_providers:
     type: array
+    description: An array of tax providers details.
     items:
       $ref: ./TaxProvider.yaml
diff --git a/docs/api/admin/components/schemas/AdminTaxRatesListRes.yaml b/docs/api/admin/components/schemas/AdminTaxRatesListRes.yaml
index 5de6ad890f..a88ab78284 100644
--- a/docs/api/admin/components/schemas/AdminTaxRatesListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminTaxRatesListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   tax_rates:
     type: array
+    description: An array of tax rate details.
     items:
       $ref: ./TaxRate.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of tax rates to skip when retrieving the tax rates.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminTaxRatesRes.yaml b/docs/api/admin/components/schemas/AdminTaxRatesRes.yaml
index bcd007f2d4..36b8301eee 100644
--- a/docs/api/admin/components/schemas/AdminTaxRatesRes.yaml
+++ b/docs/api/admin/components/schemas/AdminTaxRatesRes.yaml
@@ -3,4 +3,5 @@ required:
   - tax_rate
 properties:
   tax_rate:
+    description: Tax rate details.
     $ref: ./TaxRate.yaml
diff --git a/docs/api/admin/components/schemas/AdminUpdatePaymentCollectionsReq.yaml b/docs/api/admin/components/schemas/AdminUpdatePaymentCollectionsReq.yaml
index 11f57ce8db..e5a532b151 100644
--- a/docs/api/admin/components/schemas/AdminUpdatePaymentCollectionsReq.yaml
+++ b/docs/api/admin/components/schemas/AdminUpdatePaymentCollectionsReq.yaml
@@ -1,8 +1,12 @@
 type: object
 properties:
   description:
-    description: An optional description to create or update the payment collection.
+    description: A description to create or update the payment collection.
     type: string
   metadata:
-    description: An optional set of key-value pairs to hold additional information.
+    description: A set of key-value pairs to hold additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminUpdateUserRequest.yaml b/docs/api/admin/components/schemas/AdminUpdateUserRequest.yaml
index df01dd696d..de06280aed 100644
--- a/docs/api/admin/components/schemas/AdminUpdateUserRequest.yaml
+++ b/docs/api/admin/components/schemas/AdminUpdateUserRequest.yaml
@@ -1,21 +1,27 @@
 type: object
 properties:
   first_name:
-    description: The name of the User.
+    description: The first name of the User.
     type: string
   last_name:
-    description: The name of the User.
+    description: The last name of the User.
     type: string
   role:
-    description: Userrole assigned to the user.
+    description: >-
+      The role assigned to the user. These roles don't provide any different
+      privileges.
     type: string
     enum:
       - admin
       - member
       - developer
   api_token:
-    description: The api token of the User.
+    description: The API token of the User.
     type: string
   metadata:
     description: An optional set of key-value pairs with additional information.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/AdminUploadsRes.yaml b/docs/api/admin/components/schemas/AdminUploadsRes.yaml
index ed8154b0bc..ca464c96b2 100644
--- a/docs/api/admin/components/schemas/AdminUploadsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminUploadsRes.yaml
@@ -4,6 +4,7 @@ required:
 properties:
   uploads:
     type: array
+    description: Uploaded files details.
     items:
       type: object
       required:
diff --git a/docs/api/admin/components/schemas/AdminUserRes.yaml b/docs/api/admin/components/schemas/AdminUserRes.yaml
index 1b473f3131..f5834ed1e0 100644
--- a/docs/api/admin/components/schemas/AdminUserRes.yaml
+++ b/docs/api/admin/components/schemas/AdminUserRes.yaml
@@ -3,4 +3,5 @@ required:
   - user
 properties:
   user:
+    description: User details.
     $ref: ./User.yaml
diff --git a/docs/api/admin/components/schemas/AdminUsersListRes.yaml b/docs/api/admin/components/schemas/AdminUsersListRes.yaml
index 42af2d23e8..104f5d2365 100644
--- a/docs/api/admin/components/schemas/AdminUsersListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminUsersListRes.yaml
@@ -4,5 +4,6 @@ required:
 properties:
   users:
     type: array
+    description: An array of users details.
     items:
       $ref: ./User.yaml
diff --git a/docs/api/admin/components/schemas/AdminVariantsListRes.yaml b/docs/api/admin/components/schemas/AdminVariantsListRes.yaml
index 2afb6eb3a2..ed865661f7 100644
--- a/docs/api/admin/components/schemas/AdminVariantsListRes.yaml
+++ b/docs/api/admin/components/schemas/AdminVariantsListRes.yaml
@@ -15,6 +15,7 @@ required:
 properties:
   variants:
     type: array
+    description: An array of product variant details.
     items:
       $ref: ./PricedVariant.yaml
   count:
@@ -22,7 +23,9 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: >-
+      The number of product variants skipped when retrieving the product
+      variants.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/admin/components/schemas/AdminVariantsRes.yaml b/docs/api/admin/components/schemas/AdminVariantsRes.yaml
index 81e344ff80..9d7334c0b1 100644
--- a/docs/api/admin/components/schemas/AdminVariantsRes.yaml
+++ b/docs/api/admin/components/schemas/AdminVariantsRes.yaml
@@ -9,4 +9,5 @@ required:
   - variant
 properties:
   variant:
+    description: Product variant's details.
     $ref: ./PricedVariant.yaml
diff --git a/docs/api/admin/components/schemas/BatchJob.yaml b/docs/api/admin/components/schemas/BatchJob.yaml
index 31782073a7..a70156fe2c 100644
--- a/docs/api/admin/components/schemas/BatchJob.yaml
+++ b/docs/api/admin/components/schemas/BatchJob.yaml
@@ -1,5 +1,7 @@
 title: Batch Job
-description: A Batch Job.
+description: >-
+  A Batch Job indicates an asynchronus task stored in the Medusa backend. Its
+  status determines whether it has been executed or not.
 type: object
 required:
   - canceled_at
@@ -47,7 +49,8 @@ properties:
     type: string
     example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
   created_by_user:
-    description: A user object. Available if the relation `created_by_user` is expanded.
+    description: The details of the user that created the batch job.
+    x-expandable: created_by_user
     nullable: true
     $ref: ./User.yaml
   context:
diff --git a/docs/api/admin/components/schemas/Cart.yaml b/docs/api/admin/components/schemas/Cart.yaml
index 42935b558b..c63dda2fd3 100644
--- a/docs/api/admin/components/schemas/Cart.yaml
+++ b/docs/api/admin/components/schemas/Cart.yaml
@@ -1,5 +1,7 @@
 title: Cart
-description: Represents a user cart
+description: >-
+  A cart represents a virtual shopping bag. It can be used to complete an order,
+  a swap, or a claim.
 type: object
 required:
   - billing_address_id
@@ -35,7 +37,8 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   billing_address:
-    description: Available if the relation `billing_address` is expanded.
+    description: The details of the billing address associated with the cart.
+    x-expandable: billing_address
     nullable: true
     $ref: ./Address.yaml
   shipping_address_id:
@@ -44,12 +47,14 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   shipping_address:
-    description: Available if the relation `shipping_address` is expanded.
+    description: The details of the shipping address associated with the cart.
+    x-expandable: shipping_address
     nullable: true
     $ref: ./Address.yaml
   items:
-    description: Available if the relation `items` is expanded.
+    description: The line items added to the cart.
     type: array
+    x-expandable: items
     items:
       $ref: ./LineItem.yaml
   region_id:
@@ -57,17 +62,20 @@ properties:
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region associated with the cart.
+    x-expandable: region
     nullable: true
     $ref: ./Region.yaml
   discounts:
-    description: Available if the relation `discounts` is expanded.
+    description: An array of details of all discounts applied to the cart.
     type: array
+    x-expandable: discounts
     items:
       $ref: ./Discount.yaml
   gift_cards:
-    description: Available if the relation `gift_cards` is expanded.
+    description: An array of details of all gift cards applied to the cart.
     type: array
+    x-expandable: gift_cards
     items:
       $ref: ./GiftCard.yaml
   customer_id:
@@ -76,16 +84,19 @@ properties:
     type: string
     example: cus_01G2SG30J8C85S4A5CHM2S1NS2
   customer:
-    description: A customer object. Available if the relation `customer` is expanded.
+    description: The details of the customer the cart belongs to.
+    x-expandable: customer
     nullable: true
     type: object
   payment_session:
-    description: The selected payment session in the cart.
+    description: The details of the selected payment session in the cart.
+    x-expandable: payment_session
     nullable: true
     type: object
   payment_sessions:
-    description: The payment sessions created on the cart.
+    description: The details of all payment sessions created on the cart.
     type: array
+    x-expandable: payment_sessions
     items:
       type: object
   payment_id:
@@ -94,12 +105,14 @@ properties:
     type: string
     example: pay_01G8ZCC5W42ZNY842124G7P5R9
   payment:
-    description: Available if the relation `payment` is expanded.
+    description: The details of the payment associated with the cart.
     nullable: true
+    x-expandable: payment
     type: object
   shipping_methods:
-    description: The shipping methods added to the cart.
+    description: The details of the shipping methods added to the cart.
     type: array
+    x-expandable: shipping_methods
     items:
       $ref: ./ShippingMethod.yaml
   type:
@@ -144,10 +157,9 @@ properties:
     type: string
     example: null
   sales_channel:
-    description: >-
-      A sales channel object. Available if the relation `sales_channel` is
-      expanded.
+    description: The details of the sales channel associated with the cart.
     nullable: true
+    x-expandable: sales_channel
     $ref: ./SalesChannel.yaml
   created_at:
     description: The date with timezone at which the resource was created.
@@ -168,6 +180,10 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   shipping_total:
     description: The total of shipping
     type: integer
diff --git a/docs/api/admin/components/schemas/ClaimImage.yaml b/docs/api/admin/components/schemas/ClaimImage.yaml
index 214446d0bb..7b64e6be1d 100644
--- a/docs/api/admin/components/schemas/ClaimImage.yaml
+++ b/docs/api/admin/components/schemas/ClaimImage.yaml
@@ -1,5 +1,5 @@
 title: Claim Image
-description: Represents photo documentation of a claim.
+description: The details of an image attached to a claim.
 type: object
 required:
   - claim_item_id
@@ -18,8 +18,9 @@ properties:
     description: The ID of the claim item associated with the image
     type: string
   claim_item:
-    description: A claim item object. Available if the relation `claim_item` is expanded.
+    description: The details of the claim item this image is associated with.
     nullable: true
+    x-expandable: claim_item
     type: object
   url:
     description: The URL of the image
@@ -44,3 +45,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ClaimItem.yaml b/docs/api/admin/components/schemas/ClaimItem.yaml
index 84a3b9afe6..6d9a8a9b67 100644
--- a/docs/api/admin/components/schemas/ClaimItem.yaml
+++ b/docs/api/admin/components/schemas/ClaimItem.yaml
@@ -1,7 +1,7 @@
 title: Claim Item
 description: >-
-  Represents a claimed item along with information about the reasons for the
-  claim.
+  A claim item is an item created as part of a claim. It references an item in
+  the order that should be exchanged or refunded.
 type: object
 required:
   - claim_order_id
@@ -21,15 +21,17 @@ properties:
     type: string
     example: citm_01G8ZH853Y6TFXWPG5EYE81X63
   images:
-    description: Available if the relation `images` is expanded.
+    description: The claim images that are attached to the claim item.
     type: array
+    x-expandable: images
     items:
       $ref: ./ClaimImage.yaml
   claim_order_id:
     description: The ID of the claim this item is associated with.
     type: string
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim this item belongs to.
+    x-expandable: claim_order
     nullable: true
     type: object
   item_id:
@@ -37,7 +39,10 @@ properties:
     type: string
     example: item_01G8ZM25TN49YV9EQBE2NC27KC
   item:
-    description: Available if the relation `item` is expanded.
+    description: >-
+      The details of the line item in the original order that this claim item
+      refers to.
+    x-expandable: item
     nullable: true
     $ref: ./LineItem.yaml
   variant_id:
@@ -45,7 +50,10 @@ properties:
     type: string
     example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
   variant:
-    description: A variant object. Available if the relation `variant` is expanded.
+    description: >-
+      The details of the product variant to potentially replace the item in the
+      original order.
+    x-expandable: variant
     nullable: true
     $ref: ./ProductVariant.yaml
   reason:
@@ -68,10 +76,9 @@ properties:
     type: integer
     example: 1
   tags:
-    description: >-
-      User defined tags for easy filtering and grouping. Available if the
-      relation 'tags' is expanded.
+    description: User defined tags for easy filtering and grouping.
     type: array
+    x-expandable: tags
     items:
       $ref: ./ClaimTag.yaml
   created_at:
@@ -93,3 +100,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ClaimOrder.yaml b/docs/api/admin/components/schemas/ClaimOrder.yaml
index 5c439738c7..e3de8e9d1b 100644
--- a/docs/api/admin/components/schemas/ClaimOrder.yaml
+++ b/docs/api/admin/components/schemas/ClaimOrder.yaml
@@ -1,8 +1,8 @@
-title: Claim Order
+title: Claim
 description: >-
-  Claim Orders represent a group of faulty or missing items. Each claim order
-  consists of a subset of items associated with an original order, and can
-  contain additional information about fulfillments and returns.
+  A Claim represents a group of faulty or missing items. It consists of claim
+  items that refer to items in the original order that should be replaced or
+  refunded. It also includes details related to shipping and fulfillment.
 type: object
 required:
   - canceled_at
@@ -53,15 +53,17 @@ properties:
       - requires_action
     default: not_fulfilled
   claim_items:
-    description: The items that have been claimed
+    description: The details of the items that should be replaced or refunded.
     type: array
+    x-expandable: claim_items
     items:
       $ref: ./ClaimItem.yaml
   additional_items:
     description: >-
-      Refers to the new items to be shipped when the claim order has the type
+      The details of the new items to be shipped when the claim's type is
       `replace`
     type: array
+    x-expandable: additional_items
     items:
       $ref: ./LineItem.yaml
   order_id:
@@ -69,13 +71,15 @@ properties:
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that this claim was created for.
+    x-expandable: order
     nullable: true
     type: object
   return_order:
     description: >-
-      A return object. Holds information about the return if the claim is to be
-      returned. Available if the relation 'return_order' is expanded
+      The details of the return associated with the claim if the claim's type is
+      `replace`.
+    x-expandable: return_order
     nullable: true
     type: object
   shipping_address_id:
@@ -84,17 +88,22 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   shipping_address:
-    description: Available if the relation `shipping_address` is expanded.
+    description: The details of the address that new items should be shipped to.
+    x-expandable: shipping_address
     nullable: true
     $ref: ./Address.yaml
   shipping_methods:
-    description: The shipping methods that the claim order will be shipped with.
+    description: >-
+      The details of the shipping methods that the claim order will be shipped
+      with.
     type: array
+    x-expandable: shipping_methods
     items:
       $ref: ./ShippingMethod.yaml
   fulfillments:
     description: The fulfillments of the new items to be shipped
     type: array
+    x-expandable: fulfillments
     items:
       type: object
   refund_amount:
@@ -126,6 +135,10 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   no_notification:
     description: >-
       Flag for describing whether or not notifications related to this should be
diff --git a/docs/api/admin/components/schemas/ClaimTag.yaml b/docs/api/admin/components/schemas/ClaimTag.yaml
index fe9a2fd418..4c8924448f 100644
--- a/docs/api/admin/components/schemas/ClaimTag.yaml
+++ b/docs/api/admin/components/schemas/ClaimTag.yaml
@@ -38,3 +38,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/Country.yaml b/docs/api/admin/components/schemas/Country.yaml
index 3b78bc3b33..cfa712f0ff 100644
--- a/docs/api/admin/components/schemas/Country.yaml
+++ b/docs/api/admin/components/schemas/Country.yaml
@@ -52,6 +52,7 @@ properties:
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region the country is associated with.
+    x-expandable: region
     nullable: true
     type: object
diff --git a/docs/api/admin/components/schemas/Currency.yaml b/docs/api/admin/components/schemas/Currency.yaml
index a7aef7d3a8..adfb21705c 100644
--- a/docs/api/admin/components/schemas/Currency.yaml
+++ b/docs/api/admin/components/schemas/Currency.yaml
@@ -27,6 +27,7 @@ properties:
     type: string
     example: US Dollar
   includes_tax:
-    description: '[EXPERIMENTAL] Does the currency prices include tax'
+    description: Whether the currency prices include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
diff --git a/docs/api/admin/components/schemas/CustomShippingOption.yaml b/docs/api/admin/components/schemas/CustomShippingOption.yaml
index e3db8a274e..66c68e1f1f 100644
--- a/docs/api/admin/components/schemas/CustomShippingOption.yaml
+++ b/docs/api/admin/components/schemas/CustomShippingOption.yaml
@@ -1,8 +1,8 @@
 title: Custom Shipping Option
 description: >-
-  Custom Shipping Options are 'overriden' Shipping Options. Store managers can
-  attach a Custom Shipping Option to a cart in order to set a custom price for a
-  particular Shipping Option
+  Custom Shipping Options are overriden Shipping Options. Admins can attach a
+  Custom Shipping Option to a cart in order to set a custom price for a
+  particular Shipping Option.
 type: object
 required:
   - cart_id
@@ -29,9 +29,8 @@ properties:
     type: string
     example: so_01G1G5V27GYX4QXNARRQCW1N8T
   shipping_option:
-    description: >-
-      A shipping option object. Available if the relation `shipping_option` is
-      expanded.
+    description: The details of the overriden shipping options.
+    x-expandable: shipping_option
     nullable: true
     $ref: ./ShippingOption.yaml
   cart_id:
@@ -40,7 +39,8 @@ properties:
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart this shipping option belongs to.
+    x-expandable: cart
     nullable: true
     $ref: ./Cart.yaml
   created_at:
@@ -62,3 +62,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/Customer.yaml b/docs/api/admin/components/schemas/Customer.yaml
index c980de29f0..ecc9c83ee4 100644
--- a/docs/api/admin/components/schemas/Customer.yaml
+++ b/docs/api/admin/components/schemas/Customer.yaml
@@ -1,5 +1,5 @@
 title: Customer
-description: Represents a customer
+description: A customer can make purchases in your store and manage their profile.
 type: object
 required:
   - billing_address_id
@@ -38,12 +38,14 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   billing_address:
-    description: Available if the relation `billing_address` is expanded.
+    description: The details of the billing address associated with the customer.
+    x-expandable: billing_address
     nullable: true
     $ref: ./Address.yaml
   shipping_addresses:
-    description: Available if the relation `shipping_addresses` is expanded.
+    description: The details of the shipping addresses associated with the customer.
     type: array
+    x-expandable: shipping_addresses
     items:
       $ref: ./Address.yaml
   phone:
@@ -56,15 +58,15 @@ properties:
     type: boolean
     default: false
   orders:
-    description: Available if the relation `orders` is expanded.
+    description: The details of the orders this customer placed.
     type: array
+    x-expandable: orders
     items:
       type: object
   groups:
-    description: >-
-      The customer groups the customer belongs to. Available if the relation
-      `groups` is expanded.
+    description: The customer groups the customer belongs to.
     type: array
+    x-expandable: groups
     items:
       $ref: ./CustomerGroup.yaml
   created_at:
@@ -86,3 +88,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/CustomerGroup.yaml b/docs/api/admin/components/schemas/CustomerGroup.yaml
index c3ae03f953..a572493cad 100644
--- a/docs/api/admin/components/schemas/CustomerGroup.yaml
+++ b/docs/api/admin/components/schemas/CustomerGroup.yaml
@@ -1,5 +1,7 @@
 title: Customer Group
-description: Represents a customer group
+description: >-
+  A customer group that can be used to organize customers into groups of similar
+  traits.
 type: object
 required:
   - created_at
@@ -18,17 +20,15 @@ properties:
     type: string
     example: VIP
   customers:
-    description: >-
-      The customers that belong to the customer group. Available if the relation
-      `customers` is expanded.
+    description: The details of the customers that belong to the customer group.
     type: array
+    x-expandable: customers
     items:
       type: object
   price_lists:
-    description: >-
-      The price lists that are associated with the customer group. Available if
-      the relation `price_lists` is expanded.
+    description: The price lists that are associated with the customer group.
     type: array
+    x-expandable: price_lists
     items:
       type: object
   created_at:
@@ -50,3 +50,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/DecoratedInventoryItemDTO.yaml b/docs/api/admin/components/schemas/DecoratedInventoryItemDTO.yaml
index 0f1c82fa99..a3b200f6e9 100644
--- a/docs/api/admin/components/schemas/DecoratedInventoryItemDTO.yaml
+++ b/docs/api/admin/components/schemas/DecoratedInventoryItemDTO.yaml
@@ -8,10 +8,12 @@ allOf:
     properties:
       location_levels:
         type: array
+        description: An array of location level details
         items:
           $ref: ./InventoryLevelDTO.yaml
       variants:
         type: array
+        description: An array of product variant details
         items:
           $ref: ./ProductVariant.yaml
       stocked_quantity:
diff --git a/docs/api/admin/components/schemas/Discount.yaml b/docs/api/admin/components/schemas/Discount.yaml
index 124f8698ed..796477999f 100644
--- a/docs/api/admin/components/schemas/Discount.yaml
+++ b/docs/api/admin/components/schemas/Discount.yaml
@@ -1,5 +1,5 @@
 title: Discount
-description: Represents a discount that can be applied to a cart for promotional purposes.
+description: A discount can be applied to a cart for promotional purposes.
 type: object
 required:
   - code
@@ -35,12 +35,17 @@ properties:
     type: boolean
     example: false
   rule_id:
-    description: The Discount Rule that governs the behaviour of the Discount
+    description: >-
+      The ID of the discount rule that defines how the discount will be applied
+      to a cart.
     nullable: true
     type: string
     example: dru_01F0YESMVK96HVX7N419E3CJ7C
   rule:
-    description: Available if the relation `rule` is expanded.
+    description: >-
+      The details of the discount rule that defines how the discount will be
+      applied to a cart..
+    x-expandable: rule
     nullable: true
     $ref: ./DiscountRule.yaml
   is_disabled:
@@ -57,7 +62,8 @@ properties:
     type: string
     example: disc_01G8ZH853YPY9B94857DY91YGW
   parent_discount:
-    description: Available if the relation `parent_discount` is expanded.
+    description: The details of the parent discount that this discount was created from.
+    x-expandable: parent_discount
     nullable: true
     type: object
   starts_at:
@@ -75,10 +81,9 @@ properties:
     type: string
     example: P3Y6M4DT12H30M5S
   regions:
-    description: >-
-      The Regions in which the Discount can be used. Available if the relation
-      `regions` is expanded.
+    description: The details of the regions in which the Discount can be used.
     type: array
+    x-expandable: regions
     items:
       $ref: ./Region.yaml
   usage_limit:
@@ -110,3 +115,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/DiscountCondition.yaml b/docs/api/admin/components/schemas/DiscountCondition.yaml
index b536b8f05f..4652b43d56 100644
--- a/docs/api/admin/components/schemas/DiscountCondition.yaml
+++ b/docs/api/admin/components/schemas/DiscountCondition.yaml
@@ -16,7 +16,11 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   type:
-    description: The type of the Condition
+    description: >-
+      The type of the condition. The type affects the available resources
+      associated with the condition. For example, if the type is `products`,
+      that means the `products` relation will hold the products associated with
+      this condition and other relations will be empty.
     type: string
     enum:
       - products
@@ -25,7 +29,10 @@ properties:
       - product_tags
       - customer_groups
   operator:
-    description: The operator of the Condition
+    description: >-
+      The operator of the condition. `in` indicates that discountable resources
+      are within the specified resources. `not_in` indicates that discountable
+      resources are everything but the specified resources.
     type: string
     enum:
       - in
@@ -35,43 +42,42 @@ properties:
     type: string
     example: dru_01F0YESMVK96HVX7N419E3CJ7C
   discount_rule:
-    description: Available if the relation `discount_rule` is expanded.
+    description: The details of the discount rule associated with the condition.
+    x-expandable: discount_rule
     nullable: true
     $ref: ./DiscountRule.yaml
   products:
-    description: >-
-      products associated with this condition if type = products. Available if
-      the relation `products` is expanded.
+    description: products associated with this condition if `type` is `products`.
     type: array
+    x-expandable: products
     items:
       $ref: ./Product.yaml
   product_types:
-    description: >-
-      Product types associated with this condition if type = product_types.
-      Available if the relation `product_types` is expanded.
+    description: Product types associated with this condition if `type` is `product_types`.
     type: array
+    x-expandable: product_types
     items:
       $ref: ./ProductType.yaml
   product_tags:
-    description: >-
-      Product tags associated with this condition if type = product_tags.
-      Available if the relation `product_tags` is expanded.
+    description: Product tags associated with this condition if `type` is `product_tags`.
     type: array
+    x-expandable: product_tags
     items:
       $ref: ./ProductTag.yaml
   product_collections:
     description: >-
-      Product collections associated with this condition if type =
-      product_collections. Available if the relation `product_collections` is
-      expanded.
+      Product collections associated with this condition if `type` is
+      `product_collections`.
     type: array
+    x-expandable: product_collections
     items:
       $ref: ./ProductCollection.yaml
   customer_groups:
     description: >-
-      Customer groups associated with this condition if type = customer_groups.
-      Available if the relation `customer_groups` is expanded.
+      Customer groups associated with this condition if `type` is
+      `customer_groups`.
     type: array
+    x-expandable: customer_groups
     items:
       $ref: ./CustomerGroup.yaml
   created_at:
@@ -93,3 +99,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/DiscountConditionCustomerGroup.yaml b/docs/api/admin/components/schemas/DiscountConditionCustomerGroup.yaml
index 136f2f8472..2f55e79142 100644
--- a/docs/api/admin/components/schemas/DiscountConditionCustomerGroup.yaml
+++ b/docs/api/admin/components/schemas/DiscountConditionCustomerGroup.yaml
@@ -38,3 +38,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/DiscountConditionProduct.yaml b/docs/api/admin/components/schemas/DiscountConditionProduct.yaml
index 4ce3691cdf..2fb9699b9e 100644
--- a/docs/api/admin/components/schemas/DiscountConditionProduct.yaml
+++ b/docs/api/admin/components/schemas/DiscountConditionProduct.yaml
@@ -1,5 +1,5 @@
 title: Product Discount Condition
-description: Associates a discount condition with a product
+description: This represents the association between a discount condition and a product
 type: object
 required:
   - condition_id
@@ -17,11 +17,13 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   product:
-    description: Available if the relation `product` is expanded.
+    description: The details of the product.
+    x-expandable: product
     nullable: true
     $ref: ./Product.yaml
   discount_condition:
-    description: Available if the relation `discount_condition` is expanded.
+    description: The details of the discount condition.
+    x-expandable: discount_condition
     nullable: true
     $ref: ./DiscountCondition.yaml
   created_at:
@@ -38,3 +40,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/DiscountConditionProductCollection.yaml b/docs/api/admin/components/schemas/DiscountConditionProductCollection.yaml
index b48d9d6516..5e8b88b9e3 100644
--- a/docs/api/admin/components/schemas/DiscountConditionProductCollection.yaml
+++ b/docs/api/admin/components/schemas/DiscountConditionProductCollection.yaml
@@ -1,5 +1,7 @@
 title: Product Collection Discount Condition
-description: Associates a discount condition with a product collection
+description: >-
+  This represents the association between a discount condition and a product
+  collection
 type: object
 required:
   - condition_id
@@ -17,11 +19,13 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   product_collection:
-    description: Available if the relation `product_collection` is expanded.
+    description: The details of the product collection.
+    x-expandable: product_collection
     nullable: true
     $ref: ./ProductCollection.yaml
   discount_condition:
-    description: Available if the relation `discount_condition` is expanded.
+    description: The details of the discount condition.
+    x-expandable: discount_condition
     nullable: true
     $ref: ./DiscountCondition.yaml
   created_at:
@@ -38,3 +42,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/DiscountConditionProductTag.yaml b/docs/api/admin/components/schemas/DiscountConditionProductTag.yaml
index 61c29d1a71..58ba07c6c3 100644
--- a/docs/api/admin/components/schemas/DiscountConditionProductTag.yaml
+++ b/docs/api/admin/components/schemas/DiscountConditionProductTag.yaml
@@ -1,5 +1,5 @@
 title: Product Tag Discount Condition
-description: Associates a discount condition with a product tag
+description: This represents the association between a discount condition and a product tag
 type: object
 required:
   - condition_id
@@ -17,11 +17,13 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   product_tag:
-    description: Available if the relation `product_tag` is expanded.
+    description: The details of the product tag.
+    x-expandable: product_tag
     nullable: true
     $ref: ./ProductTag.yaml
   discount_condition:
-    description: Available if the relation `discount_condition` is expanded.
+    description: The details of the discount condition.
+    x-expandable: discount_condition
     nullable: true
     $ref: ./DiscountCondition.yaml
   created_at:
@@ -38,3 +40,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/DiscountConditionProductType.yaml b/docs/api/admin/components/schemas/DiscountConditionProductType.yaml
index 77a7a5ad8b..d93129494c 100644
--- a/docs/api/admin/components/schemas/DiscountConditionProductType.yaml
+++ b/docs/api/admin/components/schemas/DiscountConditionProductType.yaml
@@ -1,5 +1,7 @@
 title: Product Type Discount Condition
-description: Associates a discount condition with a product type
+description: >-
+  This represents the association between a discount condition and a product
+  type
 type: object
 required:
   - condition_id
@@ -17,11 +19,13 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   product_type:
-    description: Available if the relation `product_type` is expanded.
+    description: The details of the product type.
+    x-expandable: product_type
     nullable: true
     $ref: ./ProductType.yaml
   discount_condition:
-    description: Available if the relation `discount_condition` is expanded.
+    description: The details of the discount condition.
+    x-expandable: discount_condition
     nullable: true
     $ref: ./DiscountCondition.yaml
   created_at:
@@ -38,3 +42,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/DiscountRule.yaml b/docs/api/admin/components/schemas/DiscountRule.yaml
index e2571f38a7..caa7f9d604 100644
--- a/docs/api/admin/components/schemas/DiscountRule.yaml
+++ b/docs/api/admin/components/schemas/DiscountRule.yaml
@@ -1,7 +1,5 @@
 title: Discount Rule
-description: >-
-  Holds the rules that governs how a Discount is calculated when applied to a
-  Cart.
+description: A discount rule defines how a Discount is calculated when applied to a Cart.
 type: object
 required:
   - allocation
@@ -50,9 +48,10 @@ properties:
     example: total
   conditions:
     description: >-
-      A set of conditions that can be used to limit when  the discount can be
-      used. Available if the relation `conditions` is expanded.
+      The details of the discount conditions associated with the rule. They can
+      be used to limit when the discount can be used.
     type: array
+    x-expandable: conditions
     items:
       type: object
   created_at:
@@ -74,3 +73,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/DraftOrder.yaml b/docs/api/admin/components/schemas/DraftOrder.yaml
index 39e150901f..86ff90bf25 100644
--- a/docs/api/admin/components/schemas/DraftOrder.yaml
+++ b/docs/api/admin/components/schemas/DraftOrder.yaml
@@ -1,5 +1,8 @@
 title: DraftOrder
-description: Represents a draft order
+description: >-
+  A draft order is created by an admin without direct involvement of the
+  customer. Once its payment is marked as captured, it is transformed into an
+  order.
 type: object
 required:
   - canceled_at
@@ -20,7 +23,9 @@ properties:
     type: string
     example: dorder_01G8TJFKBG38YYFQ035MSVG03C
   status:
-    description: The status of the draft order
+    description: >-
+      The status of the draft order. It's changed to `completed` when it's
+      transformed to an order.
     type: string
     enum:
       - open
@@ -36,16 +41,22 @@ properties:
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart associated with the draft order.
+    x-expandable: cart
     nullable: true
     type: object
   order_id:
-    description: The ID of the order associated with the draft order.
+    description: >-
+      The ID of the order created from the draft order when its payment is
+      captured.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: >-
+      The details of the order created from the draft order when its payment is
+      captured.
+    x-expandable: order
     nullable: true
     type: object
   canceled_at:
@@ -86,3 +97,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ExtendedReservationItem.yaml b/docs/api/admin/components/schemas/ExtendedReservationItem.yaml
index 59f1150f2a..7c4594004a 100644
--- a/docs/api/admin/components/schemas/ExtendedReservationItem.yaml
+++ b/docs/api/admin/components/schemas/ExtendedReservationItem.yaml
@@ -4,8 +4,8 @@ allOf:
   - type: object
     properties:
       line_item:
-        description: optional line item
+        description: The line item associated with the reservation.
         $ref: ./LineItem.yaml
       inventory_item:
-        description: inventory item from inventory module
+        description: The inventory item associated with the reservation.
         $ref: ./InventoryItemDTO.yaml
diff --git a/docs/api/admin/components/schemas/Fulfillment.yaml b/docs/api/admin/components/schemas/Fulfillment.yaml
index 8de3d7072b..b9f77587a4 100644
--- a/docs/api/admin/components/schemas/Fulfillment.yaml
+++ b/docs/api/admin/components/schemas/Fulfillment.yaml
@@ -1,12 +1,10 @@
 title: Fulfillment
 description: >-
-  Fulfillments are created once store operators can prepare the purchased goods.
+  A Fulfillment is created once an admin can prepare the purchased goods.
   Fulfillments will eventually be shipped and hold information about how to
-  track shipments. Fulfillments are created through a provider, which is
-  typically an external shipping aggregator, shipping partner og 3PL, most
-  plugins will have asynchronous communications with these providers through
-  webhooks in order to automatically update and synchronize the state of
-  Fulfillments.
+  track shipments. Fulfillments are created through a fulfillment provider,
+  which typically integrates a third-party shipping service. Fulfillments can be
+  associated with orders, claims, swaps, and returns.
 type: object
 required:
   - canceled_at
@@ -30,61 +28,67 @@ properties:
     type: string
     example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
   claim_order_id:
-    description: The id of the Claim that the Fulfillment belongs to.
+    description: The ID of the Claim that the Fulfillment belongs to.
     nullable: true
     type: string
     example: null
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim that the fulfillment may belong to.
+    x-expandable: claim_order
     nullable: true
     type: object
   swap_id:
-    description: The id of the Swap that the Fulfillment belongs to.
+    description: The ID of the Swap that the Fulfillment belongs to.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that the fulfillment may belong to.
+    x-expandable: swap
     nullable: true
     type: object
   order_id:
-    description: The id of the Order that the Fulfillment belongs to.
+    description: The ID of the Order that the Fulfillment belongs to.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the fulfillment may belong to.
+    x-expandable: order
     nullable: true
     type: object
   provider_id:
     description: >-
-      The id of the Fulfillment Provider responsible for handling the
-      fulfillment
+      The ID of the Fulfillment Provider responsible for handling the
+      fulfillment.
     type: string
     example: manual
   provider:
-    description: Available if the relation `provider` is expanded.
+    description: >-
+      The details of the fulfillment provider responsible for handling the
+      fulfillment.
+    x-expandable: provider
     nullable: true
     $ref: ./FulfillmentProvider.yaml
   location_id:
-    description: The id of the stock location the fulfillment will be shipped from
+    description: The ID of the stock location the fulfillment will be shipped from
     nullable: true
     type: string
     example: sloc_01G8TJSYT9M6AVS5N4EMNFS1EK
   items:
     description: >-
-      The Fulfillment Items in the Fulfillment - these hold information about
-      how many of each Line Item has been fulfilled. Available if the relation
-      `items` is expanded.
+      The Fulfillment Items in the Fulfillment. These hold information about how
+      many of each Line Item has been fulfilled.
     type: array
+    x-expandable: items
     items:
       $ref: ./FulfillmentItem.yaml
   tracking_links:
     description: >-
       The Tracking Links that can be used to track the status of the
-      Fulfillment, these will usually be provided by the Fulfillment Provider.
-      Available if the relation `tracking_links` is expanded.
+      Fulfillment. These will usually be provided by the Fulfillment Provider.
     type: array
+    x-expandable: tracking_links
     items:
       $ref: ./TrackingLink.yaml
   tracking_numbers:
@@ -141,3 +145,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/FulfillmentItem.yaml b/docs/api/admin/components/schemas/FulfillmentItem.yaml
index ad05c5637e..7204760274 100644
--- a/docs/api/admin/components/schemas/FulfillmentItem.yaml
+++ b/docs/api/admin/components/schemas/FulfillmentItem.yaml
@@ -1,7 +1,5 @@
 title: Fulfillment Item
-description: >-
-  Correlates a Line Item with a Fulfillment, keeping track of the quantity of
-  the Line Item.
+description: This represents the association between a Line Item and a Fulfillment.
 type: object
 required:
   - fulfillment_id
@@ -9,19 +7,21 @@ required:
   - quantity
 properties:
   fulfillment_id:
-    description: The id of the Fulfillment that the Fulfillment Item belongs to.
+    description: The ID of the Fulfillment that the Fulfillment Item belongs to.
     type: string
     example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
   item_id:
-    description: The id of the Line Item that the Fulfillment Item references.
+    description: The ID of the Line Item that the Fulfillment Item references.
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   fulfillment:
-    description: A fulfillment object. Available if the relation `fulfillment` is expanded.
+    description: The details of the fulfillment.
+    x-expandable: fulfillment
     nullable: true
     type: object
   item:
-    description: Available if the relation `item` is expanded.
+    description: The details of the line item.
+    x-expandable: item
     nullable: true
     $ref: ./LineItem.yaml
   quantity:
diff --git a/docs/api/admin/components/schemas/FulfillmentProvider.yaml b/docs/api/admin/components/schemas/FulfillmentProvider.yaml
index 77f50f4c75..366e045f2f 100644
--- a/docs/api/admin/components/schemas/FulfillmentProvider.yaml
+++ b/docs/api/admin/components/schemas/FulfillmentProvider.yaml
@@ -1,18 +1,21 @@
 title: Fulfillment Provider
-description: Represents a fulfillment provider plugin and holds its installation status.
+description: >-
+  A fulfillment provider represents a fulfillment service installed in the
+  Medusa backend, either through a plugin or backend customizations. It holds
+  the fulfillment service's installation status.
 type: object
 required:
   - id
   - is_installed
 properties:
   id:
-    description: The id of the fulfillment provider as given by the plugin.
+    description: The ID of the fulfillment provider as given by the fulfillment service.
     type: string
     example: manual
   is_installed:
     description: >-
-      Whether the plugin is installed in the current version. Plugins that are
-      no longer installed are not deleted by will have this field set to
-      `false`.
+      Whether the fulfillment service is installed in the current version. If a
+      fulfillment service is no longer installed, the `is_installed` attribute
+      is set to `false`.
     type: boolean
     default: true
diff --git a/docs/api/admin/components/schemas/GiftCard.yaml b/docs/api/admin/components/schemas/GiftCard.yaml
index 0967dd0b92..cd3b03dc19 100644
--- a/docs/api/admin/components/schemas/GiftCard.yaml
+++ b/docs/api/admin/components/schemas/GiftCard.yaml
@@ -37,20 +37,22 @@ properties:
     type: integer
     example: 10
   region_id:
-    description: The id of the Region in which the Gift Card is available.
+    description: The ID of the region this gift card is available in.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region this gift card is available in.
+    x-expandable: region
     nullable: true
     $ref: ./Region.yaml
   order_id:
-    description: The id of the Order that the Gift Card was purchased in.
+    description: The ID of the order that the gift card was purchased in.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the gift card was purchased in.
+    x-expandable: region
     nullable: true
     type: object
   is_disabled:
@@ -88,3 +90,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/GiftCardTransaction.yaml b/docs/api/admin/components/schemas/GiftCardTransaction.yaml
index 48cd927c23..e1f3f9b490 100644
--- a/docs/api/admin/components/schemas/GiftCardTransaction.yaml
+++ b/docs/api/admin/components/schemas/GiftCardTransaction.yaml
@@ -1,7 +1,7 @@
 title: Gift Card Transaction
 description: >-
   Gift Card Transactions are created once a Customer uses a Gift Card to pay for
-  their Order
+  their Order.
 type: object
 required:
   - amount
@@ -21,15 +21,17 @@ properties:
     type: string
     example: gift_01G8XKBPBQY2R7RBET4J7E0XQZ
   gift_card:
-    description: A gift card object. Available if the relation `gift_card` is expanded.
+    description: The details of the gift card associated used in this transaction.
+    x-expandable: gift_card
     nullable: true
     type: object
   order_id:
-    description: The ID of the Order that the Gift Card was used to pay for.
+    description: The ID of the order that the gift card was used for payment.
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the gift card was used for payment.
+    x-expandable: order
     nullable: true
     type: object
   amount:
diff --git a/docs/api/admin/components/schemas/Image.yaml b/docs/api/admin/components/schemas/Image.yaml
index e061ecefe8..c837dd4b5d 100644
--- a/docs/api/admin/components/schemas/Image.yaml
+++ b/docs/api/admin/components/schemas/Image.yaml
@@ -1,5 +1,7 @@
 title: Image
-description: Images holds a reference to a URL at which the image file can be found.
+description: >-
+  An Image is used to store details about uploaded images. Images are uploaded
+  by the File Service, and the URL is provided by the File Service.
 type: object
 required:
   - created_at
@@ -36,3 +38,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/Invite.yaml b/docs/api/admin/components/schemas/Invite.yaml
index fa8ba054c5..4ab1e33195 100644
--- a/docs/api/admin/components/schemas/Invite.yaml
+++ b/docs/api/admin/components/schemas/Invite.yaml
@@ -1,5 +1,7 @@
 title: Invite
-description: Represents an invite
+description: >-
+  An invite is created when an admin user invites a new user to join the store's
+  team. Once the invite is accepted, it's deleted.
 type: object
 required:
   - accepted
@@ -22,7 +24,7 @@ properties:
     type: string
     format: email
   role:
-    description: The user's role.
+    description: The user's role. These roles don't change the privileges of the user.
     nullable: true
     type: string
     enum:
@@ -60,3 +62,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/LineItem.yaml b/docs/api/admin/components/schemas/LineItem.yaml
index 67b1ee5cd0..155bafaedd 100644
--- a/docs/api/admin/components/schemas/LineItem.yaml
+++ b/docs/api/admin/components/schemas/LineItem.yaml
@@ -1,9 +1,9 @@
 title: Line Item
 description: >-
-  Line Items represent purchasable units that can be added to a Cart for
-  checkout. When Line Items are purchased they will get copied to the resulting
-  order and can eventually be referenced in Fulfillments and Returns. Line Items
-  may also be created when processing Swaps and Claims.
+  Line Items are created when a product is added to a Cart. When Line Items are
+  purchased they will get copied to the resulting order, swap, or claim, and can
+  eventually be referenced in Fulfillments and Returns. Line items may also be
+  used for order edits.
 type: object
 required:
   - allow_discounts
@@ -36,67 +36,76 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   cart_id:
-    description: The ID of the Cart that the Line Item belongs to.
+    description: The ID of the cart that the line item may belongs to.
     nullable: true
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart that the line item may belongs to.
+    x-expandable: cart
     nullable: true
     type: object
   order_id:
-    description: The ID of the Order that the Line Item belongs to.
+    description: The ID of the order that the line item may belongs to.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the line item may belongs to.
+    x-expandable: order
     nullable: true
     type: object
   swap_id:
-    description: The id of the Swap that the Line Item belongs to.
+    description: The ID of the swap that the line item may belong to.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that the line item may belong to.
+    x-expandable: swap
     nullable: true
     type: object
   claim_order_id:
-    description: The id of the Claim that the Line Item belongs to.
+    description: The ID of the claim that the line item may belong to.
     nullable: true
     type: string
     example: null
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim that the line item may belong to.
+    x-expandable: claim_order
     nullable: true
     type: object
   tax_lines:
-    description: Available if the relation `tax_lines` is expanded.
+    description: The details of the item's tax lines.
+    x-expandable: tax_lines
     type: array
     items:
       $ref: ./LineItemTaxLine.yaml
   adjustments:
-    description: Available if the relation `adjustments` is expanded.
+    description: >-
+      The details of the item's adjustments, which are available when a discount
+      is applied on the item.
+    x-expandable: adjustments
     type: array
     items:
       $ref: ./LineItemAdjustment.yaml
   original_item_id:
-    description: The id of the original line item
+    description: >-
+      The ID of the original line item. This is useful if the line item belongs
+      to a resource that references an order, such as a return or an order edit.
     nullable: true
     type: string
   order_edit_id:
-    description: The ID of the order edit to which a cloned item belongs
+    description: The ID of the order edit that the item may belong to.
     nullable: true
     type: string
   order_edit:
-    description: The order edit joined. Available if the relation `order_edit` is expanded.
+    description: The details of the order edit.
+    x-expandable: order_edit
     nullable: true
     type: object
   title:
-    description: >-
-      The title of the Line Item, this should be easily identifiable by the
-      Customer.
+    description: The title of the Line Item.
     type: string
     example: Medusa Coffee Mug
   description:
@@ -148,9 +157,8 @@ properties:
     type: string
     example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
   variant:
-    description: >-
-      A product variant object. The Product Variant contained in the Line Item.
-      Available if the relation `variant` is expanded.
+    description: The details of the product variant that this item was created from.
+    x-expandable: variant
     nullable: true
     $ref: ./ProductVariant.yaml
   quantity:
@@ -211,7 +219,8 @@ properties:
     type: integer
     example: 0
   includes_tax:
-    description: '[EXPERIMENTAL] Indicates if the line item unit_price include tax'
+    description: Indicates if the line item unit_price include tax
+    x-featureFlag: tax_inclusive_pricing
     type: boolean
     default: false
   created_at:
@@ -228,3 +237,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/LineItemAdjustment.yaml b/docs/api/admin/components/schemas/LineItemAdjustment.yaml
index 5dcc6f496f..7d30b61c15 100644
--- a/docs/api/admin/components/schemas/LineItemAdjustment.yaml
+++ b/docs/api/admin/components/schemas/LineItemAdjustment.yaml
@@ -1,5 +1,5 @@
 title: Line Item Adjustment
-description: Represents a Line Item Adjustment
+description: A Line Item Adjustment includes details on discounts applied on a line item.
 type: object
 required:
   - amount
@@ -18,7 +18,8 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   item:
-    description: Available if the relation `item` is expanded.
+    description: The details of the line item.
+    x-expandable: item
     nullable: true
     type: object
   description:
@@ -31,7 +32,8 @@ properties:
     type: string
     example: disc_01F0YESMW10MGHWJKZSDDMN0VN
   discount:
-    description: Available if the relation `discount` is expanded.
+    description: The details of the discount associated with the adjustment.
+    x-expandable: discount
     nullable: true
     $ref: ./Discount.yaml
   amount:
@@ -44,3 +46,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/LineItemTaxLine.yaml b/docs/api/admin/components/schemas/LineItemTaxLine.yaml
index ec316b7cb7..69832cdd1e 100644
--- a/docs/api/admin/components/schemas/LineItemTaxLine.yaml
+++ b/docs/api/admin/components/schemas/LineItemTaxLine.yaml
@@ -1,5 +1,5 @@
 title: Line Item Tax Line
-description: Represents a Line Item Tax Line
+description: A Line Item Tax Line represents the taxes applied on a line item.
 type: object
 required:
   - code
@@ -33,7 +33,8 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   item:
-    description: Available if the relation `item` is expanded.
+    description: The details of the line item.
+    x-expandable: item
     nullable: true
     type: object
   created_at:
@@ -50,3 +51,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/MoneyAmount.yaml b/docs/api/admin/components/schemas/MoneyAmount.yaml
index f2b78adabf..920f9a3242 100644
--- a/docs/api/admin/components/schemas/MoneyAmount.yaml
+++ b/docs/api/admin/components/schemas/MoneyAmount.yaml
@@ -1,10 +1,11 @@
 title: Money Amount
 description: >-
-  Money Amounts represents an amount that a given Product Variant can be
-  purcased for. Each Money Amount either has a Currency or Region associated
-  with it to indicate the pricing in a given Currency or, for fully region-based
-  pricing, the given price in a specific Region. If region-based pricing is used
-  the amount will be in the currency defined for the Reigon.
+  A Money Amount represent a price amount, for example, a product variant's
+  price or a price in a price list. Each Money Amount either has a Currency or
+  Region associated with it to indicate the pricing in a given Currency or, for
+  fully region-based pricing, the given price in a specific Region. If
+  region-based pricing is used, the amount will be in the currency defined for
+  the Region.
 type: object
 required:
   - amount
@@ -24,14 +25,15 @@ properties:
     type: string
     example: ma_01F0YESHRFQNH5S8Q0PK84YYZN
   currency_code:
-    description: The 3 character currency code that the Money Amount is given in.
+    description: The 3 character currency code that the money amount may belong to.
     type: string
     example: usd
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency that the money amount may belong to.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   amount:
@@ -55,23 +57,23 @@ properties:
     type: integer
     example: 1
   price_list_id:
-    description: The ID of the price list associated with the money amount
+    description: The ID of the price list that the money amount may belong to.
     nullable: true
     type: string
     example: pl_01G8X3CKJXCG5VXVZ87H9KC09W
   price_list:
-    description: Available if the relation `price_list` is expanded.
+    description: The details of the price list that the money amount may belong to.
+    x-expandable: price_list
     nullable: true
     type: object
   variant_id:
-    description: The id of the Product Variant contained in the Line Item.
+    description: The ID of the Product Variant contained in the Line Item.
     nullable: true
     type: string
     example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
   variant:
-    description: >-
-      The Product Variant contained in the Line Item. Available if the relation
-      `variant` is expanded.
+    description: The details of the product variant that the money amount may belong to.
+    x-expandable: variant
     nullable: true
     type: object
   region_id:
@@ -80,7 +82,8 @@ properties:
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region that the money amount may belong to.
+    x-expandable: region
     nullable: true
     type: object
   created_at:
diff --git a/docs/api/admin/components/schemas/Note.yaml b/docs/api/admin/components/schemas/Note.yaml
index 3fce158b7e..9a33972604 100644
--- a/docs/api/admin/components/schemas/Note.yaml
+++ b/docs/api/admin/components/schemas/Note.yaml
@@ -1,7 +1,8 @@
 title: Note
 description: >-
-  Notes are elements which we can use in association with different resources to
-  allow users to describe additional information in relation to these.
+  A Note is an element that can be used in association with different resources
+  to allow admin users to describe additional information. For example, they can
+  be used to add additional information about orders.
 type: object
 required:
   - author_id
@@ -31,12 +32,13 @@ properties:
     type: string
     example: This order must be fulfilled on Monday
   author_id:
-    description: The ID of the author (user)
+    description: The ID of the user that created the note.
     nullable: true
     type: string
     example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
   author:
-    description: Available if the relation `author` is expanded.
+    description: The details of the user that created the note.
+    x-expandable: author
     nullable: true
     $ref: ./User.yaml
   created_at:
diff --git a/docs/api/admin/components/schemas/Notification.yaml b/docs/api/admin/components/schemas/Notification.yaml
index 13eca79f77..0d00e6fed4 100644
--- a/docs/api/admin/components/schemas/Notification.yaml
+++ b/docs/api/admin/components/schemas/Notification.yaml
@@ -1,9 +1,8 @@
 title: Notification
 description: >-
-  Notifications a communications sent via Notification Providers as a reaction
-  to internal events such as `order.placed`. Notifications can be used to show a
-  chronological timeline for communications sent to a Customer regarding an
-  Order, and enables resends.
+  A notification is an alert sent, typically to customers, using the installed
+  Notification Provider as a reaction to internal events such as `order.placed`.
+  Notifications can be resent.
 type: object
 required:
   - created_at
@@ -36,18 +35,20 @@ properties:
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   customer_id:
-    description: The ID of the Customer that the Notification was sent to.
+    description: The ID of the customer that this notification was sent to.
     nullable: true
     type: string
     example: cus_01G2SG30J8C85S4A5CHM2S1NS2
   customer:
-    description: A customer object. Available if the relation `customer` is expanded.
+    description: The details of the customer that this notification was sent to.
+    x-expandable: customer
     nullable: true
     $ref: ./Customer.yaml
   to:
     description: >-
       The address that the Notification was sent to. This will usually be an
-      email address, but represent other addresses such as a chat bot user id
+      email address, but can represent other addresses such as a chat bot user
+      ID.
     type: string
     example: user@example.com
   data:
@@ -62,23 +63,24 @@ properties:
     type: string
     example: noti_01G53V9Y6CKMCGBM1P0X7C28RX
   parent_notification:
-    description: Available if the relation `parent_notification` is expanded.
+    description: The details of the parent notification.
+    x-expandable: parent_notification
     nullable: true
     type: object
   resends:
-    description: >-
-      The resends that have been completed after the original Notification.
-      Available if the relation `resends` is expanded.
+    description: The details of all resends of the notification.
     type: array
+    x-expandable: resends
     items:
       type: object
   provider_id:
-    description: The id of the Notification Provider that handles the Notification.
+    description: The ID of the notification provider used to send the notification.
     nullable: true
     type: string
     example: sengrid
   provider:
-    description: Available if the relation `provider` is expanded.
+    description: The notification provider used to send the notification.
+    x-expandable: provider
     nullable: true
     $ref: ./NotificationProvider.yaml
   created_at:
diff --git a/docs/api/admin/components/schemas/NotificationProvider.yaml b/docs/api/admin/components/schemas/NotificationProvider.yaml
index 71bc9d5f96..d2d2e53288 100644
--- a/docs/api/admin/components/schemas/NotificationProvider.yaml
+++ b/docs/api/admin/components/schemas/NotificationProvider.yaml
@@ -1,18 +1,21 @@
 title: Notification Provider
-description: Represents a notification provider plugin and holds its installation status.
+description: >-
+  A notification provider represents a notification service installed in the
+  Medusa backend, either through a plugin or backend customizations. It holds
+  the notification service's installation status.
 type: object
 required:
   - id
   - is_installed
 properties:
   id:
-    description: The id of the notification provider as given by the plugin.
+    description: The ID of the notification provider as given by the notification service.
     type: string
     example: sendgrid
   is_installed:
     description: >-
-      Whether the plugin is installed in the current version. Plugins that are
-      no longer installed are not deleted by will have this field set to
-      `false`.
+      Whether the notification service is installed in the current version. If a
+      notification service is no longer installed, the `is_installed` attribute
+      is set to `false`.
     type: boolean
     default: true
diff --git a/docs/api/admin/components/schemas/OAuth.yaml b/docs/api/admin/components/schemas/OAuth.yaml
index 36df175455..b1ca6bf402 100644
--- a/docs/api/admin/components/schemas/OAuth.yaml
+++ b/docs/api/admin/components/schemas/OAuth.yaml
@@ -1,5 +1,7 @@
 title: OAuth
-description: Represent an OAuth app
+description: >-
+  An Oauth app is typically created by a plugin to handle authentication to
+  third-party services.
 type: object
 required:
   - application_name
diff --git a/docs/api/admin/components/schemas/Order.yaml b/docs/api/admin/components/schemas/Order.yaml
index 1051ad1ea6..a734894904 100644
--- a/docs/api/admin/components/schemas/Order.yaml
+++ b/docs/api/admin/components/schemas/Order.yaml
@@ -1,5 +1,8 @@
 title: Order
-description: Represents an order
+description: >-
+  An order is a purchase made by a customer. It holds details about payment and
+  fulfillment of the order. An order may also be created from a draft order,
+  which is created by an admin user.
 type: object
 required:
   - billing_address_id
@@ -75,7 +78,8 @@ properties:
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart associated with the order.
+    x-expandable: cart
     nullable: true
     type: object
   customer_id:
@@ -83,7 +87,8 @@ properties:
     type: string
     example: cus_01G2SG30J8C85S4A5CHM2S1NS2
   customer:
-    description: A customer object. Available if the relation `customer` is expanded.
+    description: The details of the customer associated with the order.
+    x-expandable: customer
     nullable: true
     type: object
   email:
@@ -96,7 +101,8 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   billing_address:
-    description: Available if the relation `billing_address` is expanded.
+    description: The details of the billing address associated with the order.
+    x-expandable: billing_address
     nullable: true
     $ref: ./Address.yaml
   shipping_address_id:
@@ -105,15 +111,17 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   shipping_address:
-    description: Available if the relation `shipping_address` is expanded.
+    description: The details of the shipping address associated with the order.
+    x-expandable: shipping_address
     nullable: true
     $ref: ./Address.yaml
   region_id:
-    description: The region's ID
+    description: The ID of the region this order was created in.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region this order was created in.
+    x-expandable: region
     nullable: true
     $ref: ./Region.yaml
   currency_code:
@@ -124,7 +132,8 @@ properties:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency used in the order.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   tax_rate:
@@ -133,96 +142,85 @@ properties:
     type: number
     example: 0
   discounts:
-    description: >-
-      The discounts used in the order. Available if the relation `discounts` is
-      expanded.
+    description: The details of the discounts applied on the order.
     type: array
+    x-expandable: discounts
     items:
       $ref: ./Discount.yaml
   gift_cards:
-    description: >-
-      The gift cards used in the order. Available if the relation `gift_cards`
-      is expanded.
+    description: The details of the gift card used in the order.
     type: array
+    x-expandable: gift_cards
     items:
       $ref: ./GiftCard.yaml
   shipping_methods:
-    description: >-
-      The shipping methods used in the order. Available if the relation
-      `shipping_methods` is expanded.
+    description: The details of the shipping methods used in the order.
     type: array
+    x-expandable: shipping_methods
     items:
       $ref: ./ShippingMethod.yaml
   payments:
-    description: >-
-      The payments used in the order. Available if the relation `payments` is
-      expanded.
+    description: The details of the payments used in the order.
     type: array
+    x-expandable: payments
     items:
       type: object
   fulfillments:
-    description: >-
-      The fulfillments used in the order. Available if the relation
-      `fulfillments` is expanded.
+    description: The details of the fulfillments created for the order.
     type: array
+    x-expandable: fulfillments
     items:
       type: object
   returns:
-    description: >-
-      The returns associated with the order. Available if the relation `returns`
-      is expanded.
+    description: The details of the returns created for the order.
     type: array
+    x-expandable: returns
     items:
       type: object
   claims:
-    description: >-
-      The claims associated with the order. Available if the relation `claims`
-      is expanded.
+    description: The details of the claims created for the order.
     type: array
+    x-expandable: claims
     items:
       type: object
   refunds:
-    description: >-
-      The refunds associated with the order. Available if the relation `refunds`
-      is expanded.
+    description: The details of the refunds created for the order.
     type: array
+    x-expandable: refunds
     items:
       type: object
   swaps:
-    description: >-
-      The swaps associated with the order. Available if the relation `swaps` is
-      expanded.
+    description: The details of the swaps created for the order.
     type: array
+    x-expandable: swaps
     items:
       type: object
   draft_order_id:
-    description: The ID of the draft order this order is associated with.
+    description: The ID of the draft order this order was created from.
     nullable: true
     type: string
     example: null
   draft_order:
-    description: A draft order object. Available if the relation `draft_order` is expanded.
+    description: The details of the draft order this order was created from.
+    x-expandable: draft_order
     nullable: true
     type: object
   items:
-    description: >-
-      The line items that belong to the order. Available if the relation `items`
-      is expanded.
+    description: The details of the line items that belong to the order.
+    x-expandable: items
     type: array
     items:
       $ref: ./LineItem.yaml
   edits:
-    description: >-
-      Order edits done on the order. Available if the relation `edits` is
-      expanded.
+    description: The details of the order edits done on the order.
     type: array
+    x-expandable: edits
     items:
       type: object
   gift_card_transactions:
-    description: >-
-      The gift card transactions used in the order. Available if the relation
-      `gift_card_transactions` is expanded.
+    description: The gift card transactions made in the order.
     type: array
+    x-expandable: gift_card_transactions
     items:
       $ref: ./GiftCardTransaction.yaml
   canceled_at:
@@ -252,14 +250,13 @@ properties:
     type: string
     example: null
   sales_channel_id:
-    description: The ID of the sales channel this order is associated with.
+    description: The ID of the sales channel this order belongs to.
     nullable: true
     type: string
     example: null
   sales_channel:
-    description: >-
-      A sales channel object. Available if the relation `sales_channel` is
-      expanded.
+    description: The details of the sales channel this order belongs to.
+    x-expandable: sales_channel
     nullable: true
     $ref: ./SalesChannel.yaml
   shipping_total:
@@ -308,9 +305,10 @@ properties:
     example: 0
   returnable_items:
     description: >-
-      The items that are returnable as part of the order, order swaps or order
-      claims
+      The details of the line items that are returnable as part of the order,
+      swaps, or claims
     type: array
+    x-expandable: returnable_items
     items:
       $ref: ./LineItem.yaml
   created_at:
@@ -327,3 +325,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/OrderEdit.yaml b/docs/api/admin/components/schemas/OrderEdit.yaml
index c6b72efad7..27f1077bdb 100644
--- a/docs/api/admin/components/schemas/OrderEdit.yaml
+++ b/docs/api/admin/components/schemas/OrderEdit.yaml
@@ -1,5 +1,8 @@
 title: Order Edit
-description: Order edit keeps track of order items changes.
+description: >-
+  Order edit allows modifying items in an order, such as adding, updating, or
+  deleting items from the original order. Once the order edit is confirmed, the
+  changes are reflected on the original order.
 type: object
 required:
   - canceled_at
@@ -29,11 +32,13 @@ properties:
     type: string
     example: order_01G2SG30J8C85S4A5CHM2S1NS2
   order:
-    description: Available if the relation `order` is expanded.
+    description: The details of the order that this order edit was created for.
+    x-expandable: order
     nullable: true
     type: object
   changes:
-    description: Available if the relation `changes` is expanded.
+    description: The details of all the changes on the original order's line items.
+    x-expandable: changes
     type: array
     items:
       $ref: ./OrderItemChange.yaml
@@ -135,8 +140,12 @@ properties:
       - created
       - canceled
   items:
-    description: Available if the relation `items` is expanded.
+    description: >-
+      The details of the cloned items from the original order with the new
+      changes. Once the order edit is confirmed, these line items are associated
+      with the original order.
     type: array
+    x-expandable: items
     items:
       $ref: ./LineItem.yaml
   payment_collection_id:
@@ -145,7 +154,10 @@ properties:
     type: string
     example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK
   payment_collection:
-    description: Available if the relation `payment_collection` is expanded.
+    description: >-
+      The details of the payment collection used to authorize additional payment
+      if necessary.
+    x-expandable: payment_collection
     nullable: true
     $ref: ./PaymentCollection.yaml
   created_at:
diff --git a/docs/api/admin/components/schemas/OrderItemChange.yaml b/docs/api/admin/components/schemas/OrderItemChange.yaml
index 31a0435da5..a1cbe55425 100644
--- a/docs/api/admin/components/schemas/OrderItemChange.yaml
+++ b/docs/api/admin/components/schemas/OrderItemChange.yaml
@@ -1,5 +1,8 @@
 title: Order Item Change
-description: Represents an order edit item change
+description: >-
+  An order item change is a change made within an order edit to an order's
+  items. These changes are not reflected on the original order until the order
+  edit is confirmed.
 type: object
 required:
   - created_at
@@ -27,7 +30,8 @@ properties:
     type: string
     example: oe_01G2SG30J8C85S4A5CHM2S1NS2
   order_edit:
-    description: Available if the relation `order_edit` is expanded.
+    description: The details of the order edit the item change is associated with.
+    x-expandable: order_edit
     nullable: true
     type: object
   original_line_item_id:
@@ -36,7 +40,10 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   original_line_item:
-    description: Available if the relation `original_line_item` is expanded.
+    description: >-
+      The details of the original line item this item change references. This is
+      used if the item change updates or deletes the original item.
+    x-expandable: original_line_item
     nullable: true
     $ref: ./LineItem.yaml
   line_item_id:
@@ -45,7 +52,10 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   line_item:
-    description: Available if the relation `line_item` is expanded.
+    description: >-
+      The details of the resulting line item after the item change. This line
+      item is then used in the original order once the order edit is confirmed.
+    x-expandable: line_item
     nullable: true
     $ref: ./LineItem.yaml
   created_at:
diff --git a/docs/api/admin/components/schemas/Payment.yaml b/docs/api/admin/components/schemas/Payment.yaml
index 6f9d0d69a2..cf84c788ad 100644
--- a/docs/api/admin/components/schemas/Payment.yaml
+++ b/docs/api/admin/components/schemas/Payment.yaml
@@ -1,7 +1,9 @@
 title: Payment
 description: >-
-  Payments represent an amount authorized with a given payment method, Payments
-  can be captured, canceled or refunded.
+  A payment is originally created from a payment session. Once a payment session
+  is authorized, the payment is created to represent the authorized amount with
+  a given payment method. Payments can be captured, canceled or refunded.
+  Payments can be made towards orders, swaps, order edits, or other resources.
 type: object
 required:
   - amount
@@ -25,29 +27,36 @@ properties:
     type: string
     example: pay_01G2SJNT6DEEWDFNAJ4XWDTHKE
   swap_id:
-    description: The ID of the Swap that the Payment is used for.
+    description: The ID of the swap that this payment was potentially created for.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that this payment was potentially created for.
+    x-expandable: swap
     nullable: true
     type: object
   cart_id:
-    description: The id of the Cart that the Payment Session is created for.
+    description: The ID of the cart that the payment session was potentially created for.
     nullable: true
     type: string
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: >-
+      The details of the cart that the payment session was potentially created
+      for.
+    x-expandable: cart
     nullable: true
     type: object
   order_id:
-    description: The ID of the Order that the Payment is used for.
+    description: The ID of the order that the payment session was potentially created for.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: >-
+      The details of the order that the payment session was potentially created
+      for.
+    x-expandable: order
     nullable: true
     type: object
   amount:
@@ -55,14 +64,15 @@ properties:
     type: integer
     example: 100
   currency_code:
-    description: The 3 character ISO currency code that the Payment is completed in.
+    description: The 3 character ISO currency code of the payment.
     type: string
     example: usd
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency of the payment.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   amount_refunded:
@@ -117,3 +127,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/PaymentCollection.yaml b/docs/api/admin/components/schemas/PaymentCollection.yaml
index 83db018a75..c41fe34593 100644
--- a/docs/api/admin/components/schemas/PaymentCollection.yaml
+++ b/docs/api/admin/components/schemas/PaymentCollection.yaml
@@ -1,5 +1,8 @@
 title: Payment Collection
-description: Payment Collection
+description: >-
+  A payment collection allows grouping and managing a list of payments at one.
+  This can be helpful when making additional payment for order edits or
+  integrating installment payments.
 type: object
 required:
   - amount
@@ -46,32 +49,40 @@ properties:
     nullable: true
     type: integer
   region_id:
-    description: The region's ID
+    description: The ID of the region this payment collection is associated with.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: Available if the relation `region` is expanded.
+    description: The details of the region this payment collection is associated with.
+    x-expandable: region
     nullable: true
     $ref: ./Region.yaml
   currency_code:
-    description: The 3 character ISO code for the currency.
+    description: >-
+      The 3 character ISO code for the currency this payment collection is
+      associated with.
     type: string
     example: usd
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency this payment collection is associated with.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   payment_sessions:
-    description: Available if the relation `payment_sessions` is expanded.
+    description: >-
+      The details of the payment sessions created as part of the payment
+      collection.
     type: array
+    x-expandable: payment_sessions
     items:
       $ref: ./PaymentSession.yaml
   payments:
-    description: Available if the relation `payments` is expanded.
+    description: The details of the payments created as part of the payment collection.
     type: array
+    x-expandable: payments
     items:
       $ref: ./Payment.yaml
   created_by:
@@ -96,3 +107,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/PaymentProvider.yaml b/docs/api/admin/components/schemas/PaymentProvider.yaml
index ae7eaecb49..4a54a90729 100644
--- a/docs/api/admin/components/schemas/PaymentProvider.yaml
+++ b/docs/api/admin/components/schemas/PaymentProvider.yaml
@@ -1,18 +1,21 @@
 title: Payment Provider
-description: Represents a Payment Provider plugin and holds its installation status.
+description: >-
+  A payment provider represents a payment service installed in the Medusa
+  backend, either through a plugin or backend customizations. It holds the
+  payment service's installation status.
 type: object
 required:
   - id
   - is_installed
 properties:
   id:
-    description: The id of the payment provider as given by the plugin.
+    description: The ID of the payment provider as given by the payment service.
     type: string
     example: manual
   is_installed:
     description: >-
-      Whether the plugin is installed in the current version. Plugins that are
-      no longer installed are not deleted by will have this field set to
-      `false`.
+      Whether the payment service is installed in the current version. If a
+      payment service is no longer installed, the `is_installed` attribute is
+      set to `false`.
     type: boolean
     default: true
diff --git a/docs/api/admin/components/schemas/PaymentSession.yaml b/docs/api/admin/components/schemas/PaymentSession.yaml
index f49ce46db4..ccf7cbcda8 100644
--- a/docs/api/admin/components/schemas/PaymentSession.yaml
+++ b/docs/api/admin/components/schemas/PaymentSession.yaml
@@ -1,11 +1,12 @@
 title: Payment Session
 description: >-
-  Payment Sessions are created when a Customer initilizes the checkout flow, and
+  A Payment Session is created when a Customer initilizes the checkout flow, and
   can be used to hold the state of a payment flow. Each Payment Session is
-  controlled by a Payment Provider, who is responsible for the communication
+  controlled by a Payment Provider, which is responsible for the communication
   with external payment services. Authorized Payment Sessions will eventually
-  get promoted to Payments to indicate that they are authorized for
-  capture/refunds/etc.
+  get promoted to Payments to indicate that they are authorized for payment
+  processing such as capture or refund. Payment sessions can also be used as
+  part of payment collections.
 type: object
 required:
   - amount
@@ -26,16 +27,17 @@ properties:
     type: string
     example: ps_01G901XNSRM2YS3ASN9H5KG3FZ
   cart_id:
-    description: The id of the Cart that the Payment Session is created for.
+    description: The ID of the cart that the payment session was created for.
     nullable: true
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart that the payment session was created for.
+    x-expandable: cart
     nullable: true
     $ref: ./Cart.yaml
   provider_id:
-    description: The id of the Payment Provider that is responsible for the Payment Session
+    description: The ID of the Payment Provider that is responsible for the Payment Session
     type: string
     example: manual
   is_selected:
diff --git a/docs/api/admin/components/schemas/PriceList.yaml b/docs/api/admin/components/schemas/PriceList.yaml
index ef84ed5cb5..cb1f79566a 100644
--- a/docs/api/admin/components/schemas/PriceList.yaml
+++ b/docs/api/admin/components/schemas/PriceList.yaml
@@ -1,6 +1,6 @@
 title: Price List
 description: >-
-  Price Lists represents a set of prices that overrides the default price for
+  A Price List represents a set of prices that override the default price for
   one or more product variants.
 type: object
 required:
@@ -52,22 +52,21 @@ properties:
     type: string
     format: date-time
   customer_groups:
-    description: >-
-      The Customer Groups that the Price List applies to. Available if the
-      relation `customer_groups` is expanded.
+    description: The details of the customer groups that the Price List can apply to.
     type: array
+    x-expandable: customer_groups
     items:
       $ref: ./CustomerGroup.yaml
   prices:
-    description: >-
-      The Money Amounts that are associated with the Price List. Available if
-      the relation `prices` is expanded.
+    description: The prices that belong to the price list, represented as a Money Amount.
     type: array
+    x-expandable: prices
     items:
       $ref: ./MoneyAmount.yaml
   includes_tax:
-    description: '[EXPERIMENTAL] Does the price list prices include tax'
+    description: Whether the price list prices include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
   created_at:
     description: The date with timezone at which the resource was created.
diff --git a/docs/api/admin/components/schemas/Product.yaml b/docs/api/admin/components/schemas/Product.yaml
index 94a80dd483..d0f98a63f1 100644
--- a/docs/api/admin/components/schemas/Product.yaml
+++ b/docs/api/admin/components/schemas/Product.yaml
@@ -1,8 +1,10 @@
 title: Product
 description: >-
-  Products are a grouping of Product Variants that have common properties such
-  as images and descriptions. Products can have multiple options which define
-  the properties that Product Variants differ by.
+  A product is a saleable item that holds general information such as name or
+  description. It must include at least one Product Variant, where each product
+  variant defines different options to purchase the product with (for example,
+  different sizes or colors). The prices and inventory of the product are
+  defined on the variant level.
 type: object
 required:
   - collection_id
@@ -70,8 +72,9 @@ properties:
       - rejected
     default: draft
   images:
-    description: Images of the Product. Available if the relation `images` is expanded.
+    description: The details of the product's images.
     type: array
+    x-expandable: images
     items:
       $ref: ./Image.yaml
   thumbnail:
@@ -81,38 +84,49 @@ properties:
     format: uri
   options:
     description: >-
-      The Product Options that are defined for the Product. Product Variants of
-      the Product will have a unique combination of Product Option Values.
-      Available if the relation `options` is expanded.
+      The details of the Product Options that are defined for the Product. The
+      product's variants will have a unique combination of values of the
+      product's options.
     type: array
+    x-expandable: options
     items:
       $ref: ./ProductOption.yaml
   variants:
     description: >-
-      The Product Variants that belong to the Product. Each will have a unique
-      combination of Product Option Values. Available if the relation `variants`
-      is expanded.
+      The details of the Product Variants that belong to the Product. Each will
+      have a unique combination of values of the product's options.
     type: array
+    x-expandable: variants
     items:
       $ref: ./ProductVariant.yaml
   categories:
-    description: >-
-      The product's associated categories. Available if the relation
-      `categories` are expanded.
+    description: The details of the product categories that this product belongs to.
     type: array
+    x-expandable: categories
+    x-featureFlag: product_categories
     items:
       $ref: ./ProductCategory.yaml
   profile_id:
     description: >-
-      The ID of the Shipping Profile that the Product belongs to. Shipping
-      Profiles have a set of defined Shipping Options that can be used to
-      Fulfill a given set of Products.
+      The ID of the shipping profile that the product belongs to. The shipping
+      profile has a set of defined shipping options that can be used to fulfill
+      the product.
     type: string
     example: sp_01G1G5V239ENSZ5MV4JAR737BM
   profile:
-    description: Available if the relation `profile` is expanded.
+    description: >-
+      The details of the shipping profile that the product belongs to. The
+      shipping profile has a set of defined shipping options that can be used to
+      fulfill the product.
+    x-expandable: profile
     nullable: true
     $ref: ./ShippingProfile.yaml
+  profiles:
+    description: Available if the relation `profiles` is expanded.
+    nullable: true
+    type: array
+    items:
+      $ref: ./ShippingProfile.yaml
   weight:
     description: >-
       The weight of the Product Variant. May be used in shipping rate
@@ -172,30 +186,29 @@ properties:
     type: string
     example: null
   collection_id:
-    description: The Product Collection that the Product belongs to
+    description: The ID of the product collection that the product belongs to.
     nullable: true
     type: string
     example: pcol_01F0YESBFAZ0DV6V831JXWH0BG
   collection:
-    description: >-
-      A product collection object. Available if the relation `collection` is
-      expanded.
+    description: The details of the product collection that the product belongs to.
+    x-expandable: collection
     nullable: true
     $ref: ./ProductCollection.yaml
   type_id:
-    description: The Product type that the Product belongs to
+    description: The ID of the product type that the product belongs to.
     nullable: true
     type: string
     example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
   type:
-    description: Available if the relation `type` is expanded.
+    description: The details of the product type that the product belongs to.
+    x-expandable: type
     nullable: true
     $ref: ./ProductType.yaml
   tags:
-    description: >-
-      The Product Tags assigned to the Product. Available if the relation `tags`
-      is expanded.
+    description: The details of the product tags used in this product.
     type: array
+    x-expandable: type
     items:
       $ref: ./ProductTag.yaml
   discountable:
@@ -210,10 +223,9 @@ properties:
     type: string
     example: null
   sales_channels:
-    description: >-
-      The sales channels the product is associated with. Available if the
-      relation `sales_channels` is expanded.
+    description: The details of the sales channels this product is available in.
     type: array
+    x-expandable: sales_channels
     items:
       $ref: ./SalesChannel.yaml
   created_at:
@@ -235,3 +247,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ProductCategory.yaml b/docs/api/admin/components/schemas/ProductCategory.yaml
index 3dfe3b8ca6..b4acd30f4e 100644
--- a/docs/api/admin/components/schemas/ProductCategory.yaml
+++ b/docs/api/admin/components/schemas/ProductCategory.yaml
@@ -1,6 +1,9 @@
-title: ProductCategory
-description: Represents a product category
+title: Product Category
+description: >-
+  A product category can be used to categorize products into a hierarchy of
+  categories.
 x-resourceId: ProductCategory
+x-featureFlag: product_categories
 type: object
 required:
   - category_children
@@ -48,8 +51,9 @@ properties:
     description: An integer that depicts the rank of category in a tree node
     default: 0
   category_children:
-    description: Available if the relation `category_children` are expanded.
+    description: The details of the category's children.
     type: array
+    x-expandable: category_children
     items:
       type: object
   parent_category_id:
@@ -58,16 +62,14 @@ properties:
     type: string
     default: null
   parent_category:
-    description: >-
-      A product category object. Available if the relation `parent_category` is
-      expanded.
+    description: The details of the parent of this category.
+    x-expandable: parent_category
     nullable: true
     type: object
   products:
-    description: >-
-      Products associated with category. Available if the relation `products` is
-      expanded.
+    description: The details of the products that belong to this category.
     type: array
+    x-expandable: products
     items:
       type: object
   created_at:
diff --git a/docs/api/admin/components/schemas/ProductCollection.yaml b/docs/api/admin/components/schemas/ProductCollection.yaml
index f53db55c2d..82b6fbcca8 100644
--- a/docs/api/admin/components/schemas/ProductCollection.yaml
+++ b/docs/api/admin/components/schemas/ProductCollection.yaml
@@ -1,5 +1,8 @@
 title: Product Collection
-description: Product Collections represents a group of Products that are related.
+description: >-
+  A Product Collection allows grouping together products for promotional
+  purposes. For example, an admin can create a Summer collection, add products
+  to it, and showcase it on the storefront.
 type: object
 required:
   - created_at
@@ -26,10 +29,9 @@ properties:
     type: string
     example: summer-collection
   products:
-    description: >-
-      The Products contained in the Product Collection. Available if the
-      relation `products` is expanded.
+    description: The details of the products that belong to this product collection.
     type: array
+    x-expandable: products
     items:
       type: object
   created_at:
@@ -51,3 +53,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ProductOption.yaml b/docs/api/admin/components/schemas/ProductOption.yaml
index 3de3f509d9..6e2d829a9e 100644
--- a/docs/api/admin/components/schemas/ProductOption.yaml
+++ b/docs/api/admin/components/schemas/ProductOption.yaml
@@ -1,8 +1,8 @@
 title: Product Option
 description: >-
-  Product Options define properties that may vary between different variants of
-  a Product. Common Product Options are "Size" and "Color", but Medusa doesn't
-  limit what Product Options that can be defined.
+  A Product Option defines properties that may vary between different variants
+  of a Product. Common Product Options are "Size" and "Color". Admins are free
+  to create any product options.
 type: object
 required:
   - created_at
@@ -22,18 +22,18 @@ properties:
     type: string
     example: Size
   values:
-    description: >-
-      The Product Option Values that are defined for the Product Option.
-      Available if the relation `values` is expanded.
+    description: The details of the values of the product option.
     type: array
+    x-expandable: values
     items:
       $ref: ./ProductOptionValue.yaml
   product_id:
-    description: The ID of the Product that the Product Option is defined for.
+    description: The ID of the product that this product option belongs to.
     type: string
     example: prod_01G1G5V2MBA328390B5AXJ610F
   product:
-    description: A product object. Available if the relation `product` is expanded.
+    description: The details of the product that this product option belongs to.
+    x-expandable: product
     nullable: true
     type: object
   created_at:
@@ -55,3 +55,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ProductOptionValue.yaml b/docs/api/admin/components/schemas/ProductOptionValue.yaml
index b247b13506..af9257805c 100644
--- a/docs/api/admin/components/schemas/ProductOptionValue.yaml
+++ b/docs/api/admin/components/schemas/ProductOptionValue.yaml
@@ -1,7 +1,7 @@
 title: Product Option Value
 description: >-
-  A value given to a Product Variant's option set. Product Variant have a
-  Product Option Value for each of the Product Options defined on the Product.
+  An option value is one of the possible values of a Product Option. Product
+  Variants specify a unique combination of product option values.
 type: object
 required:
   - created_at
@@ -20,26 +20,28 @@ properties:
   value:
     description: >-
       The value that the Product Variant has defined for the specific Product
-      Option (e.g. if the Product Option is \"Size\" this value could be
-      `Small`, `Medium` or `Large`).
+      Option (e.g. if the Product Option is "Size" this value could be `Small`,
+      `Medium` or `Large`).
     type: string
     example: large
   option_id:
-    description: The ID of the Product Option that the Product Option Value is defined for.
+    description: The ID of the Product Option that the Product Option Value belongs to.
     type: string
     example: opt_01F0YESHQBZVKCEXJ24BS6PCX3
   option:
-    description: Available if the relation `option` is expanded.
+    description: >-
+      The details of the product option that the Product Option Value belongs
+      to.
+    x-expandable: option
     nullable: true
     type: object
   variant_id:
-    description: >-
-      The ID of the Product Variant that the Product Option Value is defined
-      for.
+    description: The ID of the product variant that uses this product option value.
     type: string
     example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
   variant:
-    description: Available if the relation `variant` is expanded.
+    description: The details of the product variant that uses this product option value.
+    x-expandable: variant
     nullable: true
     type: object
   created_at:
@@ -61,3 +63,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ProductTag.yaml b/docs/api/admin/components/schemas/ProductTag.yaml
index 7faa4a2c1b..829162f285 100644
--- a/docs/api/admin/components/schemas/ProductTag.yaml
+++ b/docs/api/admin/components/schemas/ProductTag.yaml
@@ -1,5 +1,5 @@
 title: Product Tag
-description: Product Tags can be added to Products for easy filtering and grouping.
+description: A Product Tag can be added to Products for easy filtering and grouping.
 type: object
 required:
   - created_at
@@ -36,3 +36,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ProductTaxRate.yaml b/docs/api/admin/components/schemas/ProductTaxRate.yaml
index d92b163428..55292d8e33 100644
--- a/docs/api/admin/components/schemas/ProductTaxRate.yaml
+++ b/docs/api/admin/components/schemas/ProductTaxRate.yaml
@@ -1,7 +1,7 @@
 title: Product Tax Rate
 description: >-
-  Associates a tax rate with a product to indicate that the product is taxed in
-  a certain way
+  This represents the association between a tax rate and a product to indicate
+  that the product is taxed in a way different than the default.
 type: object
 required:
   - created_at
@@ -15,7 +15,8 @@ properties:
     type: string
     example: prod_01G1G5V2MBA328390B5AXJ610F
   product:
-    description: Available if the relation `product` is expanded.
+    description: The details of the product.
+    x-expandable: product
     nullable: true
     $ref: ./Product.yaml
   rate_id:
@@ -23,7 +24,8 @@ properties:
     type: string
     example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
   tax_rate:
-    description: Available if the relation `tax_rate` is expanded.
+    description: The details of the tax rate.
+    x-expandable: tax_rate
     nullable: true
     $ref: ./TaxRate.yaml
   created_at:
@@ -40,3 +42,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ProductType.yaml b/docs/api/admin/components/schemas/ProductType.yaml
index 579e7a6fb4..dbdc684090 100644
--- a/docs/api/admin/components/schemas/ProductType.yaml
+++ b/docs/api/admin/components/schemas/ProductType.yaml
@@ -1,5 +1,5 @@
 title: Product Type
-description: Product Type can be added to Products for filtering and reporting purposes.
+description: A Product Type can be added to Products for filtering and reporting purposes.
 type: object
 required:
   - created_at
@@ -36,3 +36,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ProductTypeTaxRate.yaml b/docs/api/admin/components/schemas/ProductTypeTaxRate.yaml
index 4539a32fc5..3c641ab1fe 100644
--- a/docs/api/admin/components/schemas/ProductTypeTaxRate.yaml
+++ b/docs/api/admin/components/schemas/ProductTypeTaxRate.yaml
@@ -1,7 +1,7 @@
 title: Product Type Tax Rate
 description: >-
-  Associates a tax rate with a product type to indicate that the product type is
-  taxed in a certain way
+  This represents the association between a tax rate and a product type to
+  indicate that the product type is taxed in a different way than the default.
 type: object
 required:
   - created_at
@@ -15,7 +15,8 @@ properties:
     type: string
     example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
   product_type:
-    description: Available if the relation `product_type` is expanded.
+    description: The details of the product type.
+    x-expandable: product_type
     nullable: true
     $ref: ./ProductType.yaml
   rate_id:
@@ -23,7 +24,8 @@ properties:
     type: string
     example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
   tax_rate:
-    description: Available if the relation `tax_rate` is expanded.
+    description: The details of the tax rate.
+    x-expandable: tax_rate
     nullable: true
     $ref: ./TaxRate.yaml
   created_at:
@@ -40,3 +42,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ProductVariant.yaml b/docs/api/admin/components/schemas/ProductVariant.yaml
index fe8a168efc..ab1eff0624 100644
--- a/docs/api/admin/components/schemas/ProductVariant.yaml
+++ b/docs/api/admin/components/schemas/ProductVariant.yaml
@@ -1,8 +1,9 @@
 title: Product Variant
 description: >-
-  Product Variants represent a Product with a specific set of Product Option
+  A Product Variant represents a Product with a specific set of Product Option
   configurations. The maximum number of Product Variants that a Product can have
-  is given by the number of available Product Option combinations.
+  is given by the number of available Product Option combinations. A product
+  must at least have one product variant.
 type: object
 required:
   - allow_backorder
@@ -39,19 +40,21 @@ properties:
     type: string
     example: Small
   product_id:
-    description: The ID of the Product that the Product Variant belongs to.
+    description: The ID of the product that the product variant belongs to.
     type: string
     example: prod_01G1G5V2MBA328390B5AXJ610F
   product:
-    description: A product object. Available if the relation `product` is expanded.
+    description: The details of the product that the product variant belongs to.
+    x-expandable: product
     nullable: true
     type: object
   prices:
     description: >-
-      The Money Amounts defined for the Product Variant. Each Money Amount
-      represents a price in a given currency or a price in a specific Region.
-      Available if the relation `prices` is expanded.
+      The details of the prices of the Product Variant, each represented as a
+      Money Amount. Each Money Amount represents a price in a given currency or
+      a specific Region.
     type: array
+    x-expandable: prices
     items:
       $ref: ./MoneyAmount.yaml
   sku:
@@ -158,16 +161,16 @@ properties:
     example: null
   options:
     description: >-
-      The Product Option Values specified for the Product Variant. Available if
-      the relation `options` is expanded.
+      The details of the product options that this product variant defines
+      values for.
     type: array
+    x-expandable: options
     items:
       $ref: ./ProductOptionValue.yaml
   inventory_items:
-    description: >-
-      The Inventory Items related to the product variant. Available if the
-      relation `inventory_items` is expanded.
+    description: The details inventory items of the product variant.
     type: array
+    x-expandable: inventory_items
     items:
       $ref: ./ProductVariantInventoryItem.yaml
   created_at:
@@ -189,6 +192,10 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   purchasable:
     description: |
       Only used with the inventory modules.
diff --git a/docs/api/admin/components/schemas/ProductVariantInventoryItem.yaml b/docs/api/admin/components/schemas/ProductVariantInventoryItem.yaml
index d2f658ecfb..2da5bc3821 100644
--- a/docs/api/admin/components/schemas/ProductVariantInventoryItem.yaml
+++ b/docs/api/admin/components/schemas/ProductVariantInventoryItem.yaml
@@ -1,7 +1,7 @@
 title: Product Variant Inventory Item
 description: >-
-  Product Variant Inventory Items link variants with inventory items and denote
-  the number of inventory items constituting a variant.
+  A Product Variant Inventory Item links variants with inventory items and
+  denotes the required quantity of the variant.
 type: object
 required:
   - created_at
@@ -23,13 +23,12 @@ properties:
     description: The id of the variant.
     type: string
   variant:
-    description: A ProductVariant object. Available if the relation `variant` is expanded.
+    description: The details of the product variant.
+    x-expandable: variant
     nullable: true
     type: object
   required_quantity:
-    description: >-
-      The quantity of an inventory item required for one quantity of the
-      variant.
+    description: The quantity of an inventory item required for the variant.
     type: integer
     default: 1
   created_at:
diff --git a/docs/api/admin/components/schemas/PublishableApiKey.yaml b/docs/api/admin/components/schemas/PublishableApiKey.yaml
index dffb94d446..d94df58632 100644
--- a/docs/api/admin/components/schemas/PublishableApiKey.yaml
+++ b/docs/api/admin/components/schemas/PublishableApiKey.yaml
@@ -1,7 +1,12 @@
 title: Publishable API key
 description: >-
-  Publishable API key defines scopes (i.e. resources) that are available within
-  a request.
+  A Publishable API key defines scopes that resources are available in. Then, it
+  can be used in request to infer the resources without having to directly pass
+  them. For example, a publishable API key can be associated with one or more
+  sales channels. Then, when the publishable API key is passed in the header of
+  a request, it is inferred what sales channel is being used without having to
+  pass the sales channel as a query or body parameter of the request.
+  Publishable API keys can only be used with sales channels, at the moment.
 type: object
 required:
   - created_at
diff --git a/docs/api/admin/components/schemas/PublishableApiKeySalesChannel.yaml b/docs/api/admin/components/schemas/PublishableApiKeySalesChannel.yaml
index ac6c018ad7..a79fecafa9 100644
--- a/docs/api/admin/components/schemas/PublishableApiKeySalesChannel.yaml
+++ b/docs/api/admin/components/schemas/PublishableApiKeySalesChannel.yaml
@@ -1,5 +1,7 @@
-title: Publishable API key sales channel
-description: Holds mapping between Publishable API keys and Sales Channels
+title: Publishable API Key Sales Channel
+description: >-
+  This represents the association between the Publishable API keys and Sales
+  Channels
 type: object
 required:
   - publishable_key_id
diff --git a/docs/api/admin/components/schemas/Refund.yaml b/docs/api/admin/components/schemas/Refund.yaml
index 48ab1bfe12..0438bfe295 100644
--- a/docs/api/admin/components/schemas/Refund.yaml
+++ b/docs/api/admin/components/schemas/Refund.yaml
@@ -1,8 +1,8 @@
 title: Refund
 description: >-
-  Refund represent an amount of money transfered back to the Customer for a
+  A refund represents an amount of money transfered back to the customer for a
   given reason. Refunds may occur in relation to Returns, Swaps and Claims, but
-  can also be initiated by a store operator.
+  can also be initiated by an admin for an order.
 type: object
 required:
   - amount
@@ -21,21 +21,23 @@ properties:
     type: string
     example: ref_01G1G5V27GYX4QXNARRQCW1N8T
   order_id:
-    description: The id of the Order that the Refund is related to.
+    description: The ID of the order this refund was created for.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order this refund was created for.
+    x-expandable: order
     nullable: true
     type: object
   payment_id:
-    description: The payment's ID if available
+    description: The payment's ID, if available.
     nullable: true
     type: string
     example: pay_01G8ZCC5W42ZNY842124G7P5R9
   payment:
-    description: Available if the relation `payment` is expanded.
+    description: The details of the payment associated with the refund.
+    x-expandable: payment
     nullable: true
     type: object
   amount:
@@ -82,3 +84,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/Region.yaml b/docs/api/admin/components/schemas/Region.yaml
index a8df502e1f..2e19d39db4 100644
--- a/docs/api/admin/components/schemas/Region.yaml
+++ b/docs/api/admin/components/schemas/Region.yaml
@@ -1,7 +1,7 @@
 title: Region
 description: >-
-  Regions hold settings for how Customers in a given geographical location shop.
-  The is, for example, where currencies and tax rates are defined. A Region can
+  A region holds settings specific to a geographical location, including the
+  currency, tax rates, and fulfillment and payment providers. A Region can
   consist of multiple countries to accomodate common shopping settings across
   countries.
 type: object
@@ -30,14 +30,15 @@ properties:
     type: string
     example: EU
   currency_code:
-    description: The 3 character currency code that the Region uses.
+    description: The 3 character currency code used in the region.
     type: string
     example: usd
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency used in the region.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   tax_rate:
@@ -46,9 +47,10 @@ properties:
     example: 0
   tax_rates:
     description: >-
-      The tax rates that are included in the Region. Available if the relation
-      `tax_rates` is expanded.
+      The details of the tax rates used in the region, aside from the default
+      rate.
     type: array
+    x-expandable: tax_rates
     items:
       $ref: ./TaxRate.yaml
   tax_code:
@@ -67,10 +69,9 @@ properties:
     type: boolean
     default: true
   countries:
-    description: >-
-      The countries that are included in the Region. Available if the relation
-      `countries` is expanded.
+    description: The details of the countries included in this region.
     type: array
+    x-expandable: countries
     items:
       $ref: ./Country.yaml
   tax_provider_id:
@@ -79,26 +80,30 @@ properties:
     type: string
     example: null
   tax_provider:
-    description: Available if the relation `tax_provider` is expanded.
+    description: The details of the tax provider used in the region.
+    x-expandable: tax_provider
     nullable: true
     $ref: ./TaxProvider.yaml
   payment_providers:
     description: >-
-      The Payment Providers that can be used to process Payments in the Region.
-      Available if the relation `payment_providers` is expanded.
+      The details of the payment providers that can be used to process payments
+      in the region.
     type: array
+    x-expandable: payment_providers
     items:
       $ref: ./PaymentProvider.yaml
   fulfillment_providers:
     description: >-
-      The Fulfillment Providers that can be used to fulfill orders in the
-      Region. Available if the relation `fulfillment_providers` is expanded.
+      The details of the fulfillment providers that can be used to fulfill items
+      of orders and similar resources in the region.
     type: array
+    x-expandable: fulfillment_providers
     items:
       $ref: ./FulfillmentProvider.yaml
   includes_tax:
-    description: '[EXPERIMENTAL] Does the prices for the region include tax'
+    description: Whether the prices for the region include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
   created_at:
     description: The date with timezone at which the resource was created.
@@ -119,3 +124,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ResponseInventoryItem.yaml b/docs/api/admin/components/schemas/ResponseInventoryItem.yaml
index 279316dfc5..6a141e4ba9 100644
--- a/docs/api/admin/components/schemas/ResponseInventoryItem.yaml
+++ b/docs/api/admin/components/schemas/ResponseInventoryItem.yaml
@@ -1,8 +1,17 @@
 allOf:
   - $ref: ./InventoryItemDTO.yaml
   - type: object
-    required:
-      - available_quantity
     properties:
-      available_quantity:
-        type: number
+      location_levels:
+        type: array
+        description: The inventory's location levels.
+        items:
+          allOf:
+            - $ref: ./InventoryItemDTO.yaml
+            - type: object
+              required:
+                - available_quantity
+              properties:
+                available_quantity:
+                  description: The available quantity in the inventory location.
+                  type: number
diff --git a/docs/api/admin/components/schemas/Return.yaml b/docs/api/admin/components/schemas/Return.yaml
index b2b07fc9bf..d7145a0dff 100644
--- a/docs/api/admin/components/schemas/Return.yaml
+++ b/docs/api/admin/components/schemas/Return.yaml
@@ -1,8 +1,8 @@
 title: Return
 description: >-
-  Return orders hold information about Line Items that a Customer wishes to send
-  back, along with how the items will be returned. Returns can be used as part
-  of a Swap.
+  A Return holds information about Line Items that a Customer wishes to send
+  back, along with how the items will be returned. Returns can also be used as
+  part of a Swap or a Claim.
 type: object
 required:
   - claim_order_id
@@ -34,44 +34,47 @@ properties:
       - canceled
     default: requested
   items:
-    description: >-
-      The Return Items that will be shipped back to the warehouse. Available if
-      the relation `items` is expanded.
+    description: The details of the items that the customer is returning.
     type: array
+    x-expandable: items
     items:
       $ref: ./ReturnItem.yaml
   swap_id:
-    description: The ID of the Swap that the Return is a part of.
+    description: The ID of the swap that the return may belong to.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that the return may belong to.
+    x-expandable: swap
     nullable: true
     type: object
   claim_order_id:
-    description: The ID of the Claim that the Return is a part of.
+    description: The ID of the claim that the return may belong to.
     nullable: true
     type: string
     example: null
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim that the return may belong to.
+    x-expandable: claim_order
     nullable: true
     type: object
   order_id:
-    description: The ID of the Order that the Return is made from.
+    description: The ID of the order that the return was created for.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the return was created for.
+    x-expandable: order
     nullable: true
     type: object
   shipping_method:
     description: >-
-      The Shipping Method that will be used to send the Return back. Can be null
-      if the Customer facilitates the return shipment themselves. Available if
-      the relation `shipping_method` is expanded.
+      The details of the Shipping Method that will be used to send the Return
+      back. Can be null if the Customer will handle the return shipment
+      themselves.
+    x-expandable: shipping_method
     nullable: true
     $ref: ./ShippingMethod.yaml
   shipping_data:
@@ -82,7 +85,7 @@ properties:
     type: object
     example: {}
   location_id:
-    description: The id of the stock location the return will be added back.
+    description: The ID of the stock location the return will be added back.
     nullable: true
     type: string
     example: sloc_01G8TJSYT9M6AVS5N4EMNFS1EK
@@ -123,3 +126,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ReturnItem.yaml b/docs/api/admin/components/schemas/ReturnItem.yaml
index f2e6e78b7a..cbdf122007 100644
--- a/docs/api/admin/components/schemas/ReturnItem.yaml
+++ b/docs/api/admin/components/schemas/ReturnItem.yaml
@@ -1,7 +1,7 @@
 title: Return Item
 description: >-
-  Correlates a Line Item with a Return, keeping track of the quantity of the
-  Line Item that will be returned.
+  A return item represents a line item in an order that is to be returned. It
+  includes details related to the return and the reason behind it.
 type: object
 required:
   - is_requested
@@ -15,23 +15,25 @@ required:
   - return_id
 properties:
   return_id:
-    description: The id of the Return that the Return Item belongs to.
+    description: The ID of the Return that the Return Item belongs to.
     type: string
     example: ret_01F0YET7XPCMF8RZ0Y151NZV2V
   item_id:
-    description: The id of the Line Item that the Return Item references.
+    description: The ID of the Line Item that the Return Item references.
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   return_order:
-    description: Available if the relation `return_order` is expanded.
+    description: Details of the Return that the Return Item belongs to.
+    x-expandable: return_order
     nullable: true
     type: object
   item:
-    description: Available if the relation `item` is expanded.
+    description: The details of the line item in the original order to be returned.
+    x-expandable: item
     nullable: true
     $ref: ./LineItem.yaml
   quantity:
-    description: The quantity of the Line Item that is included in the Return.
+    description: The quantity of the Line Item to be returned.
     type: integer
     example: 1
   is_requested:
@@ -56,7 +58,8 @@ properties:
     type: string
     example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ
   reason:
-    description: Available if the relation `reason` is expanded.
+    description: The details of the reason for returning the item.
+    x-expandable: reason
     nullable: true
     $ref: ./ReturnReason.yaml
   note:
@@ -70,3 +73,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ReturnReason.yaml b/docs/api/admin/components/schemas/ReturnReason.yaml
index 37715c1fe9..28f6b23324 100644
--- a/docs/api/admin/components/schemas/ReturnReason.yaml
+++ b/docs/api/admin/components/schemas/ReturnReason.yaml
@@ -1,7 +1,7 @@
 title: Return Reason
 description: >-
-  A Reason for why a given product is returned. A Return Reason can be used on
-  Return Items in order to indicate why a Line Item was returned.
+  A Return Reason is a value defined by an admin. It can be used on Return Items
+  in order to indicate why a Line Item was returned.
 type: object
 required:
   - created_at
@@ -37,11 +37,13 @@ properties:
     type: string
     example: null
   parent_return_reason:
-    description: Available if the relation `parent_return_reason` is expanded.
+    description: The details of the parent reason.
+    x-expandable: parent_return_reason
     nullable: true
     type: object
   return_reason_children:
-    description: Available if the relation `return_reason_children` is expanded.
+    description: The details of the child reasons.
+    x-expandable: return_reason_children
     type: object
   created_at:
     description: The date with timezone at which the resource was created.
@@ -62,3 +64,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/SalesChannel.yaml b/docs/api/admin/components/schemas/SalesChannel.yaml
index dbb40f089c..87f03d42be 100644
--- a/docs/api/admin/components/schemas/SalesChannel.yaml
+++ b/docs/api/admin/components/schemas/SalesChannel.yaml
@@ -1,5 +1,8 @@
 title: Sales Channel
-description: A Sales Channel
+description: >-
+  A Sales Channel is a method a business offers its products for purchase for
+  the customers. For example, a Webshop can be a sales channel, and a mobile app
+  can be another.
 type: object
 required:
   - created_at
@@ -28,10 +31,9 @@ properties:
     type: boolean
     default: false
   locations:
-    description: >-
-      The Stock Locations related to the sales channel. Available if the
-      relation `locations` is expanded.
+    description: The details of the stock locations related to the sales channel.
     type: array
+    x-expandable: locations
     items:
       $ref: ./SalesChannelLocation.yaml
   created_at:
@@ -47,3 +49,13 @@ properties:
     nullable: true
     type: string
     format: date-time
+  metadata:
+    description: An optional key-value map with additional details
+    nullable: true
+    type: object
+    example:
+      car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/SalesChannelLocation.yaml b/docs/api/admin/components/schemas/SalesChannelLocation.yaml
index 27ec4fd84b..4936e19986 100644
--- a/docs/api/admin/components/schemas/SalesChannelLocation.yaml
+++ b/docs/api/admin/components/schemas/SalesChannelLocation.yaml
@@ -1,5 +1,5 @@
 title: Sales Channel Stock Location
-description: Sales Channel Stock Location link sales channels with stock locations.
+description: This represents the association between a sales channel and a stock locations.
 type: object
 required:
   - created_at
@@ -14,16 +14,15 @@ properties:
     type: string
     example: scloc_01G8X9A7ESKAJXG2H0E6F1MW7A
   sales_channel_id:
-    description: The id of the Sales Channel
+    description: The ID of the Sales Channel
     type: string
     example: sc_01G8X9A7ESKAJXG2H0E6F1MW7A
   location_id:
-    description: The id of the Location Stock.
+    description: The ID of the Location Stock.
     type: string
   sales_channel:
-    description: >-
-      The sales channel the location is associated with. Available if the
-      relation `sales_channel` is expanded.
+    description: The details of the sales channel the location is associated with.
+    x-expandable: sales_channel
     nullable: true
     type: object
   created_at:
diff --git a/docs/api/admin/components/schemas/ShippingMethod.yaml b/docs/api/admin/components/schemas/ShippingMethod.yaml
index 04dcb7020c..730bf052cd 100644
--- a/docs/api/admin/components/schemas/ShippingMethod.yaml
+++ b/docs/api/admin/components/schemas/ShippingMethod.yaml
@@ -1,9 +1,10 @@
 title: Shipping Method
 description: >-
-  Shipping Methods represent a way in which an Order or Return can be shipped.
-  Shipping Methods are built from a Shipping Option, but may contain additional
-  details, that can be necessary for the Fulfillment Provider to handle the
-  shipment.
+  A Shipping Method represents a way in which an Order or Return can be shipped.
+  Shipping Methods are created from a Shipping Option, but may contain
+  additional details that can be necessary for the Fulfillment Provider to
+  handle the shipment. If the shipping method is created for a return, it may be
+  associated with a claim or a swap that the return is part of.
 type: object
 required:
   - cart_id
@@ -21,61 +22,68 @@ properties:
     type: string
     example: sm_01F0YET7DR2E7CYVSDHM593QG2
   shipping_option_id:
-    description: The id of the Shipping Option that the Shipping Method is built from.
+    description: The ID of the Shipping Option that the Shipping Method is built from.
     type: string
     example: so_01G1G5V27GYX4QXNARRQCW1N8T
   order_id:
-    description: The id of the Order that the Shipping Method is used on.
+    description: The ID of the order that the shipping method is used in.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the shipping method is used in.
+    x-expandable: order
     nullable: true
     type: object
   claim_order_id:
-    description: The id of the Claim that the Shipping Method is used on.
+    description: The ID of the claim that the shipping method is used in.
     nullable: true
     type: string
     example: null
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim that the shipping method is used in.
+    x-expandable: claim_order
     nullable: true
     type: object
   cart_id:
-    description: The id of the Cart that the Shipping Method is used on.
+    description: The ID of the cart that the shipping method is used in.
     nullable: true
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart that the shipping method is used in.
+    x-expandable: cart
     nullable: true
     type: object
   swap_id:
-    description: The id of the Swap that the Shipping Method is used on.
+    description: The ID of the swap that the shipping method is used in.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that the shipping method is used in.
+    x-expandable: swap
     nullable: true
     type: object
   return_id:
-    description: The id of the Return that the Shipping Method is used on.
+    description: The ID of the return that the shipping method is used in.
     nullable: true
     type: string
     example: null
   return_order:
-    description: A return object. Available if the relation `return_order` is expanded.
+    description: The details of the return that the shipping method is used in.
+    x-expandable: return_order
     nullable: true
     type: object
   shipping_option:
-    description: Available if the relation `shipping_option` is expanded.
+    description: The details of the shipping option the method was created from.
+    x-expandable: shipping_option
     nullable: true
     $ref: ./ShippingOption.yaml
   tax_lines:
-    description: Available if the relation `tax_lines` is expanded.
+    description: The details of the tax lines applied on the shipping method.
     type: array
+    x-expandable: tax_lines
     items:
       $ref: ./ShippingMethodTaxLine.yaml
   price:
@@ -93,8 +101,9 @@ properties:
     type: object
     example: {}
   includes_tax:
-    description: '[EXPERIMENTAL] Indicates if the shipping method price include tax'
+    description: Whether the shipping method price include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
   subtotal:
     description: The subtotal of the shipping
diff --git a/docs/api/admin/components/schemas/ShippingMethodTaxLine.yaml b/docs/api/admin/components/schemas/ShippingMethodTaxLine.yaml
index d251624dca..892b8c06e0 100644
--- a/docs/api/admin/components/schemas/ShippingMethodTaxLine.yaml
+++ b/docs/api/admin/components/schemas/ShippingMethodTaxLine.yaml
@@ -1,5 +1,7 @@
 title: Shipping Method Tax Line
-description: Shipping Method Tax Line
+description: >-
+  A Shipping Method Tax Line represents the taxes applied on a shipping method
+  in a cart.
 type: object
 required:
   - code
@@ -33,7 +35,8 @@ properties:
     type: string
     example: sm_01F0YET7DR2E7CYVSDHM593QG2
   shipping_method:
-    description: Available if the relation `shipping_method` is expanded.
+    description: The details of the associated shipping method.
+    x-expandable: shipping_method
     nullable: true
     type: object
   created_at:
@@ -50,3 +53,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ShippingOption.yaml b/docs/api/admin/components/schemas/ShippingOption.yaml
index a8eebad545..fbc4d8ed41 100644
--- a/docs/api/admin/components/schemas/ShippingOption.yaml
+++ b/docs/api/admin/components/schemas/ShippingOption.yaml
@@ -1,6 +1,6 @@
 title: Shipping Option
 description: >-
-  Shipping Options represent a way in which an Order or Return can be shipped.
+  A Shipping Option represents a way in which an Order or Return can be shipped.
   Shipping Options have an associated Fulfillment Provider that will be used
   when the fulfillment of an Order is initiated. Shipping Options themselves
   cannot be added to Carts, but serve as a template for Shipping Methods. This
@@ -34,32 +34,36 @@ properties:
     type: string
     example: PostFake Standard
   region_id:
-    description: The region's ID
+    description: The ID of the region this shipping option can be used in.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region this shipping option can be used in.
+    x-expandable: region
     nullable: true
     type: object
   profile_id:
-    description: >-
-      The ID of the Shipping Profile that the shipping option belongs to.
-      Shipping Profiles have a set of defined Shipping Options that can be used
-      to Fulfill a given set of Products.
+    description: The ID of the Shipping Profile that the shipping option belongs to.
     type: string
     example: sp_01G1G5V239ENSZ5MV4JAR737BM
   profile:
-    description: Available if the relation `profile` is expanded.
+    description: The details of the shipping profile that the shipping option belongs to.
+    x-expandable: profile
     nullable: true
     $ref: ./ShippingProfile.yaml
   provider_id:
     description: >-
-      The id of the Fulfillment Provider, that will be used to process
-      Fulfillments from the Shipping Option.
+      The ID of the fulfillment provider that will be used to later to process
+      the shipping method created from this shipping option and its
+      fulfillments.
     type: string
     example: manual
   provider:
-    description: Available if the relation `provider` is expanded.
+    description: >-
+      The details of the fulfillment provider that will be used to later to
+      process the shipping method created from this shipping option and its
+      fulfillments.
+    x-expandable: provider
     nullable: true
     $ref: ./FulfillmentProvider.yaml
   price_type:
@@ -91,10 +95,10 @@ properties:
     default: false
   requirements:
     description: >-
-      The requirements that must be satisfied for the Shipping Option to be
-      available for a Cart. Available if the relation `requirements` is
-      expanded.
+      The details of the requirements that must be satisfied for the Shipping
+      Option to be available for usage in a Cart.
     type: array
+    x-expandable: requirements
     items:
       $ref: ./ShippingOptionRequirement.yaml
   data:
@@ -104,8 +108,9 @@ properties:
     type: object
     example: {}
   includes_tax:
-    description: '[EXPERIMENTAL] Does the shipping option price include tax'
+    description: Whether the shipping option price include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
   created_at:
     description: The date with timezone at which the resource was created.
@@ -126,3 +131,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ShippingOptionRequirement.yaml b/docs/api/admin/components/schemas/ShippingOptionRequirement.yaml
index 57d045827c..26764f96d0 100644
--- a/docs/api/admin/components/schemas/ShippingOptionRequirement.yaml
+++ b/docs/api/admin/components/schemas/ShippingOptionRequirement.yaml
@@ -1,7 +1,7 @@
 title: Shipping Option Requirement
 description: >-
-  A requirement that a Cart must satisfy for the Shipping Option to be available
-  to the Cart.
+  A shipping option requirement defines conditions that a Cart must satisfy for
+  the Shipping Option to be available for usage in the Cart.
 type: object
 required:
   - amount
@@ -15,13 +15,12 @@ properties:
     type: string
     example: sor_01G1G5V29AB4CTNDRFSRWSRKWD
   shipping_option_id:
-    description: >-
-      The id of the Shipping Option that the hipping option requirement belongs
-      to
+    description: The ID of the shipping option that the requirements belong to.
     type: string
     example: so_01G1G5V27GYX4QXNARRQCW1N8T
   shipping_option:
-    description: Available if the relation `shipping_option` is expanded.
+    description: The details of the shipping option that the requirements belong to.
+    x-expandable: shipping_option
     nullable: true
     type: object
   type:
diff --git a/docs/api/admin/components/schemas/ShippingProfile.yaml b/docs/api/admin/components/schemas/ShippingProfile.yaml
index 15ffd42c84..58c9ef4558 100644
--- a/docs/api/admin/components/schemas/ShippingProfile.yaml
+++ b/docs/api/admin/components/schemas/ShippingProfile.yaml
@@ -1,7 +1,10 @@
 title: Shipping Profile
 description: >-
-  Shipping Profiles have a set of defined Shipping Options that can be used to
-  fulfill a given set of Products.
+  A Shipping Profile has a set of defined Shipping Options that can be used to
+  fulfill a given set of Products. For example, gift cards are shipped
+  differently than physical products, so a shipping profile with the type
+  `gift_card` groups together the shipping options that can only be used for
+  gift cards.
 type: object
 required:
   - created_at
@@ -34,17 +37,18 @@ properties:
     example: default
   products:
     description: >-
-      The Products that the Shipping Profile defines Shipping Options for.
-      Available if the relation `products` is expanded.
+      The details of the products that the Shipping Profile defines Shipping
+      Options for. Available if the relation `products` is expanded.
     type: array
+    x-expandable: products
     items:
       type: object
   shipping_options:
     description: >-
-      The Shipping Options that can be used to fulfill the Products in the
-      Shipping Profile. Available if the relation `shipping_options` is
-      expanded.
+      The details of the shipping options that can be used to create shipping
+      methods for the Products in the Shipping Profile.
     type: array
+    x-expandable: shipping_options
     items:
       type: object
   created_at:
@@ -66,3 +70,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/ShippingTaxRate.yaml b/docs/api/admin/components/schemas/ShippingTaxRate.yaml
index 78734007ac..c7b36795be 100644
--- a/docs/api/admin/components/schemas/ShippingTaxRate.yaml
+++ b/docs/api/admin/components/schemas/ShippingTaxRate.yaml
@@ -1,7 +1,5 @@
 title: Shipping Tax Rate
-description: >-
-  Associates a tax rate with a shipping option to indicate that the shipping
-  option is taxed in a certain way
+description: This represents the tax rates applied on a shipping option.
 type: object
 required:
   - created_at
@@ -11,19 +9,21 @@ required:
   - updated_at
 properties:
   shipping_option_id:
-    description: The ID of the Shipping Option
+    description: The ID of the shipping option.
     type: string
     example: so_01G1G5V27GYX4QXNARRQCW1N8T
   shipping_option:
-    description: Available if the relation `shipping_option` is expanded.
+    description: The details of the shipping option.
+    x-expandable: shipping_option
     nullable: true
     $ref: ./ShippingOption.yaml
   rate_id:
-    description: The ID of the Tax Rate
+    description: The ID of the associated tax rate.
     type: string
     example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
   tax_rate:
-    description: Available if the relation `tax_rate` is expanded.
+    description: The details of the associated tax rate.
+    x-expandable: tax_rate
     nullable: true
     $ref: ./TaxRate.yaml
   created_at:
@@ -40,3 +40,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/Store.yaml b/docs/api/admin/components/schemas/Store.yaml
index 93232178dc..3a79d6301a 100644
--- a/docs/api/admin/components/schemas/Store.yaml
+++ b/docs/api/admin/components/schemas/Store.yaml
@@ -1,5 +1,8 @@
 title: Store
-description: Holds settings for the Store, such as name, currencies, etc.
+description: >-
+  A store holds the main settings of the commerce shop. By default, only one
+  store is created and used within the Medusa backend. It holds settings related
+  to the name of the store, available currencies, and more.
 type: object
 required:
   - created_at
@@ -29,14 +32,14 @@ properties:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   default_currency:
-    description: Available if the relation `default_currency` is expanded.
+    description: The details of the store's default currency.
+    x-expandable: default_currency
     nullable: true
     $ref: ./Currency.yaml
   currencies:
-    description: >-
-      The currencies that are enabled for the Store. Available if the relation
-      `currencies` is expanded.
+    description: The details of the enabled currencies in the store.
     type: array
+    x-expandable: currencies
     items:
       $ref: ./Currency.yaml
   swap_link_template:
@@ -64,14 +67,13 @@ properties:
     type: string
     example: null
   default_sales_channel_id:
-    description: The sales channel ID the cart is associated with.
+    description: The ID of the store's default sales channel.
     nullable: true
     type: string
     example: null
   default_sales_channel:
-    description: >-
-      A sales channel object. Available if the relation `default_sales_channel`
-      is expanded.
+    description: The details of the store's default sales channel.
+    x-expandable: default_sales_channel
     nullable: true
     $ref: ./SalesChannel.yaml
   created_at:
@@ -88,3 +90,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/Swap.yaml b/docs/api/admin/components/schemas/Swap.yaml
index 2a0d1938a3..7e00bf1687 100644
--- a/docs/api/admin/components/schemas/Swap.yaml
+++ b/docs/api/admin/components/schemas/Swap.yaml
@@ -1,12 +1,10 @@
 title: Swap
 description: >-
-  Swaps can be created when a Customer wishes to exchange Products that they
-  have purchased to different Products. Swaps consist of a Return of previously
-  purchased Products and a Fulfillment of new Products, the amount paid for the
-  Products being returned will be used towards payment for the new Products. In
-  the case where the amount paid for the the Products being returned exceed the
-  amount to be paid for the new Products, a Refund will be issued for the
-  difference.
+  A swap can be created when a Customer wishes to exchange Products that they
+  have purchased with different Products. It consists of a Return of previously
+  purchased Products and a Fulfillment of new Products. It also includes
+  information on any additional payment or refund required based on the
+  difference between the exchanged products.
 type: object
 required:
   - allow_backorder
@@ -58,45 +56,50 @@ properties:
       - requires_action
     example: not_paid
   order_id:
-    description: The ID of the Order where the Line Items to be returned where purchased.
+    description: The ID of the order that the swap belongs to.
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the swap belongs to.
+    x-expandable: order
     nullable: true
     type: object
   additional_items:
     description: >-
-      The new Line Items to ship to the Customer. Available if the relation
-      `additional_items` is expanded.
+      The details of the new products to send to the customer, represented as
+      line items.
     type: array
+    x-expandable: additional_items
     items:
       $ref: ./LineItem.yaml
   return_order:
     description: >-
-      A return order object. The Return that is issued for the return part of
-      the Swap. Available if the relation `return_order` is expanded.
+      The details of the return that belongs to the swap, which holds the
+      details on the items being returned.
+    x-expandable: return_order
     nullable: true
     type: object
   fulfillments:
     description: >-
-      The Fulfillments used to send the new Line Items. Available if the
-      relation `fulfillments` is expanded.
+      The details of the fulfillments that are used to send the new items to the
+      customer.
+    x-expandable: fulfillments
     type: array
     items:
       type: object
   payment:
     description: >-
-      The Payment authorized when the Swap requires an additional amount to be
-      charged from the Customer. Available if the relation `payment` is
-      expanded.
+      The details of the additional payment authorized by the customer when
+      `difference_due` is positive.
+    x-expandable: payment
     nullable: true
     type: object
   difference_due:
     description: >-
-      The difference that is paid or refunded as a result of the Swap. May be
-      negative when the amount paid for the returned items exceed the total of
-      the new Products.
+      The difference amount between the order’s original total and the new total
+      imposed by the swap. If its value is negative, a refund must be issues to
+      the customer. If it's positive, additional payment must be authorized by
+      the customer. Otherwise, no payment processing is required.
     nullable: true
     type: integer
     example: 0
@@ -108,23 +111,26 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   shipping_address:
-    description: Available if the relation `shipping_address` is expanded.
+    description: The details of the shipping address that the new items should be sent to.
+    x-expandable: shipping_address
     nullable: true
     $ref: ./Address.yaml
   shipping_methods:
     description: >-
-      The Shipping Methods used to fulfill the additional items purchased.
-      Available if the relation `shipping_methods` is expanded.
+      The details of the shipping methods used to fulfill the additional items
+      purchased.
     type: array
+    x-expandable: shipping_methods
     items:
       $ref: ./ShippingMethod.yaml
   cart_id:
-    description: The id of the Cart that the Customer will use to confirm the Swap.
+    description: The ID of the cart that the customer uses to complete the swap.
     nullable: true
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart that the customer uses to complete the swap.
+    x-expandable: cart
     nullable: true
     type: object
   confirmed_at:
@@ -174,3 +180,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/TaxLine.yaml b/docs/api/admin/components/schemas/TaxLine.yaml
index cca22c81f3..cbdb672a17 100644
--- a/docs/api/admin/components/schemas/TaxLine.yaml
+++ b/docs/api/admin/components/schemas/TaxLine.yaml
@@ -1,5 +1,5 @@
 title: Tax Line
-description: Line item that specifies an amount of tax to add to a line item.
+description: A tax line represents the taxes amount applied to a line item.
 type: object
 required:
   - code
@@ -41,3 +41,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/TaxProvider.yaml b/docs/api/admin/components/schemas/TaxProvider.yaml
index 55c326d81c..0abb0ed394 100644
--- a/docs/api/admin/components/schemas/TaxProvider.yaml
+++ b/docs/api/admin/components/schemas/TaxProvider.yaml
@@ -1,18 +1,21 @@
 title: Tax Provider
-description: The tax service used to calculate taxes
+description: >-
+  A tax provider represents a tax service installed in the Medusa backend,
+  either through a plugin or backend customizations. It holds the tax service's
+  installation status.
 type: object
 required:
   - id
   - is_installed
 properties:
   id:
-    description: The id of the tax provider as given by the plugin.
+    description: The ID of the tax provider as given by the tax service.
     type: string
     example: manual
   is_installed:
     description: >-
-      Whether the plugin is installed in the current version. Plugins that are
-      no longer installed are not deleted by will have this field set to
+      Whether the tax service is installed in the current version. If a tax
+      service is no longer installed, the `is_installed` attribute is set to
       `false`.
     type: boolean
     default: true
diff --git a/docs/api/admin/components/schemas/TaxRate.yaml b/docs/api/admin/components/schemas/TaxRate.yaml
index deb3f4d02e..aaf91c7e76 100644
--- a/docs/api/admin/components/schemas/TaxRate.yaml
+++ b/docs/api/admin/components/schemas/TaxRate.yaml
@@ -1,7 +1,7 @@
 title: Tax Rate
 description: >-
-  A Tax Rate can be used to associate a certain rate to charge on products
-  within a given Region
+  A Tax Rate can be used to define a custom rate to charge on specified
+  products, product types, and shipping options within a given region.
 type: object
 required:
   - code
@@ -32,32 +32,30 @@ properties:
     type: string
     example: Tax Example
   region_id:
-    description: The id of the Region that the rate belongs to
+    description: The ID of the region that the rate belongs to.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region that the rate belongs to.
+    x-expandable: region
     nullable: true
     type: object
   products:
-    description: >-
-      The products that belong to this tax rate. Available if the relation
-      `products` is expanded.
+    description: The details of the products that belong to this tax rate.
     type: array
+    x-expandable: products
     items:
       $ref: ./Product.yaml
   product_types:
-    description: >-
-      The product types that belong to this tax rate. Available if the relation
-      `product_types` is expanded.
+    description: The details of the product types that belong to this tax rate.
     type: array
+    x-expandable: product_types
     items:
       $ref: ./ProductType.yaml
   shipping_options:
+    description: The details of the shipping options that belong to this tax rate.
     type: array
-    description: >-
-      The shipping options that belong to this tax rate. Available if the
-      relation `shipping_options` is expanded.
+    x-expandable: shipping_options
     items:
       $ref: ./ShippingOption.yaml
   product_count:
@@ -86,3 +84,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/TrackingLink.yaml b/docs/api/admin/components/schemas/TrackingLink.yaml
index 1d73c9c7e5..2da6690dae 100644
--- a/docs/api/admin/components/schemas/TrackingLink.yaml
+++ b/docs/api/admin/components/schemas/TrackingLink.yaml
@@ -1,8 +1,9 @@
 title: Tracking Link
 description: >-
-  Tracking Link holds information about tracking numbers for a Fulfillment.
+  A tracking link holds information about tracking numbers for a Fulfillment.
   Tracking Links can optionally contain a URL that can be visited to see the
-  status of the shipment.
+  status of the shipment. Typically, the tracking link is provided from the
+  third-party service integrated through the used fulfillment provider.
 type: object
 required:
   - created_at
@@ -29,11 +30,12 @@ properties:
     type: string
     format: RH370168054CN
   fulfillment_id:
-    description: The id of the Fulfillment that the Tracking Link references.
+    description: The ID of the fulfillment that the tracking link belongs to.
     type: string
     example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
   fulfillment:
-    description: Available if the relation `fulfillment` is expanded.
+    description: The details of the fulfillment that the tracking link belongs to.
+    x-expandable: fulfillment
     nullable: true
     type: object
   idempotency_key:
@@ -64,3 +66,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/User.yaml b/docs/api/admin/components/schemas/User.yaml
index cdf5cf7506..33f313d896 100644
--- a/docs/api/admin/components/schemas/User.yaml
+++ b/docs/api/admin/components/schemas/User.yaml
@@ -1,5 +1,5 @@
 title: User
-description: Represents a User who can manage store settings.
+description: A User is an administrator who can manage store settings and data.
 type: object
 required:
   - api_token
@@ -18,7 +18,7 @@ properties:
     type: string
     example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
   role:
-    description: The user's role
+    description: The user's role. These roles don't provide any different privileges.
     type: string
     enum:
       - admin
@@ -63,3 +63,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/admin/components/schemas/VariantInventory.yaml b/docs/api/admin/components/schemas/VariantInventory.yaml
index 9b7aebc58c..8b8ee0e232 100644
--- a/docs/api/admin/components/schemas/VariantInventory.yaml
+++ b/docs/api/admin/components/schemas/VariantInventory.yaml
@@ -1,21 +1,33 @@
 type: object
+required:
+  - id
+  - inventory
+  - sales_channel_availability
 properties:
   id:
-    description: the id of the variant
+    description: the ID of the variant
     type: string
   inventory:
-    description: the stock location address ID
+    description: The inventory details.
     $ref: ./ResponseInventoryItem.yaml
   sales_channel_availability:
-    type: object
-    description: An optional key-value map with additional details
-    properties:
-      channel_name:
-        description: Sales channel name
-        type: string
-      channel_id:
-        description: Sales channel id
-        type: string
-      available_quantity:
-        description: Available quantity in sales channel
-        type: number
+    type: array
+    description: >-
+      An array of details about the variant's inventory availability in sales
+      channels.
+    items:
+      type: object
+      required:
+        - channel_name
+        - channel_id
+        - available_quantity
+      properties:
+        channel_name:
+          description: Sales channel's name
+          type: string
+        channel_id:
+          description: Sales channel's ID
+          type: string
+        available_quantity:
+          description: Available quantity in the sales channel
+          type: number
diff --git a/docs/api/admin/openapi.yaml b/docs/api/admin/openapi.yaml
index dbad6cca7e..5ebe742cf1 100644
--- a/docs/api/admin/openapi.yaml
+++ b/docs/api/admin/openapi.yaml
@@ -445,68 +445,340 @@ info:
     name: MIT
     url: https://github.com/medusajs/medusa/blob/master/LICENSE
 tags:
+  - name: Apps Oauth
+    description: >
+      Some plugins may require to authenticate with third-party services and
+      store authentication details, such as the authentication token. To do
+      that, they can create an Oauth provider within the plugin that handles the
+      authentication.
+
+      The Apps Oauth endpoints allows admins to manage and generate token for an
+      app using its oauth provider.
   - name: Auth
-    description: >-
-      Auth endpoints that allow authorization of admin Users and manages their
-      sessions.
-  - name: Apps
-    description: App endpoints that allow handling apps in Medusa.
+    description: >
+      Authentication endpoints allow admin users to manage their session, such
+      as login or log out.
+
+      When an admin user is logged in, the cookie header is set indicating the
+      admin's login session.
+    externalDocs:
+      description: How to implement user profiles
+      url: https://docs.medusajs.com/modules/users/admin/manage-profile
   - name: Batch Jobs
-    description: Batch Job endpoints that allow handling batch jobs in Medusa.
-  - name: Collections
-    description: Collection endpoints that allow handling collections in Medusa.
+    description: >
+      A batch job is a task that is performed by the Medusa backend
+      asynchronusly. For example, the Import Product feature is implemented
+      using batch jobs.
+
+      Batch Job endpoints allows admins to manage the batch jobs and their
+      state.
+    externalDocs:
+      description: How to import products
+      url: https://docs.medusajs.com/modules/products/admin/import-products
+  - name: Currencies
+    description: >
+      A store can use unlimited currencies, and each region must be associated
+      with at least one currency.
+
+      Currencies are defined within the Medusa backend. Currency endpoints allow
+      admins to list and update currencies.
+    externalDocs:
+      description: How to manage currencies
+      url: >-
+        https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-currencies
   - name: Customers
-    description: Customer endpoints that allow handling customers in Medusa.
+    description: >
+      Customers can either be created when they register through the Store APIs,
+      or created by the admin using the Admin APIs.
+    externalDocs:
+      description: How to manage customers
+      url: https://docs.medusajs.com/modules/customers/admin/manage-customers
   - name: Customer Groups
-    description: Customer Group endpoints that allow handling customer groups in Medusa.
+    description: >
+      Customer Groups can be used to organize customers that share similar data
+      or attributes into dedicated groups.
+
+      This can be useful for different purposes such as setting a different
+      price for a specific customer group.
+    externalDocs:
+      description: How to manage customer groups
+      url: https://docs.medusajs.com/modules/customers/admin/manage-customer-groups
   - name: Discounts
-    description: Discount endpoints that allow handling discounts in Medusa.
+    description: >
+      Admins can create discounts with conditions and rules, providing them with
+      advanced settings for variety of cases.
+
+      The Discount endpoints can be used to manage discounts, their conditions,
+      resources, and more.
+    externalDocs:
+      description: How to manage discounts
+      url: https://docs.medusajs.com/modules/discounts/admin/manage-discounts
   - name: Draft Orders
-    description: Draft Order endpoints that allow handling draft orders in Medusa.
+    description: >
+      A draft order is an order created manually by the admin. It allows admins
+      to create orders without direct involvement from the customer.
+    externalDocs:
+      description: How to manage draft orders
+      url: https://docs.medusajs.com/modules/orders/admin/manage-draft-orders
   - name: Gift Cards
-    description: Gift Card endpoints that allow handling gift cards in Medusa.
+    description: >
+      Admins can create gift cards and send them directly to customers,
+      specifying options like their balance, region, and more.
+
+      These gift cards are different than the saleable gift cards in a store,
+      which are created and managed through Product endpoints.
+    externalDocs:
+      description: How to manage gift cards
+      url: >-
+        https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-custom-gift-cards
+  - name: Inventory Items
+    description: >
+      Inventory items, provided by the [Inventory
+      Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module),
+      can be used to manage the inventory of saleable items in your store.
+    externalDocs:
+      description: How to manage inventory items
+      url: >-
+        https://docs.medusajs.com/modules/multiwarehouse/admin/manage-inventory-items
   - name: Invites
-    description: Invite endpoints that allow handling invites in Medusa.
+    description: >
+      An admin can invite new users to manage their team. This would allow new
+      users to authenticate as admins and perform admin functionalities.
+    externalDocs:
+      description: How to manage invites
+      url: https://docs.medusajs.com/modules/users/admin/manage-invites
   - name: Notes
-    description: Note endpoints that allow handling notes in Medusa.
+    description: >
+      Notes are created by admins and can be associated with any resource. For
+      example, an admin can add a note to an order for additional details or
+      remarks.
   - name: Notifications
-    description: Notification endpoints that allow handling notifications in Medusa.
+    description: >
+      Notifications are sent to customers to inform them of new updates. For
+      example, a notification can be sent to the customer when their order is
+      place or its state is updated.
+
+      The notification's type, such as an email or SMS, is determined by the
+      notification provider installed on the Medusa backend.
   - name: Orders
-    description: Order endpoints that allow handling orders in Medusa.
+    description: >
+      Orders are purchases made by customers, typically through a storefront
+      using the Store API. Draft orders created by the admin are also
+      transformed to an Order once the payment is captured.
+
+      Managing orders include managing fulfillment, payment, claims,
+      reservations, and more.
+    externalDocs:
+      description: How to manage orders
+      url: https://docs.medusajs.com/modules/orders/admin/manage-orders
+  - name: Order Edits
+    description: >
+      An admin can edit an order to remove, add, or update an item's quantity.
+      When an admin edits an order, they're stored as an `OrderEdit`.
+    externalDocs:
+      description: How to edit an order
+      url: https://docs.medusajs.com/modules/orders/admin/edit-order
+  - name: Payment Collections
+    description: >
+      A payment collection is useful for managing additional payments, such as
+      for Order Edits, or installment payments.
   - name: Price Lists
-    description: Price List endpoints that allow handling price lists in Medusa.
+    description: >
+      A price list are special prices applied to products based on a set of
+      conditions, such as customer group.
+    externalDocs:
+      description: How to manage price lists
+      url: https://docs.medusajs.com/modules/price-lists/admin/manage-price-lists
   - name: Products
-    description: Product endpoints that allow handling products in Medusa.
+    description: >
+      Products are saleable items in a store. This also includes [saleable gift
+      cards](https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-gift-card-product)
+      in a store.
+    externalDocs:
+      description: How to manage products
+      url: https://docs.medusajs.com/modules/products/admin/manage-products
+  - name: Product Categories
+    description: >
+      Products can be categoriezed into categories. A product can be added into
+      more than one category.
+    externalDocs:
+      description: How to manage product categories
+      url: https://docs.medusajs.com/modules/products/admin/manage-categories
+  - name: Product Collections
+    description: >
+      A product collection is used to organize products for different purposes
+      such as marketing or discount purposes. For example, you can create a
+      Summer Collection.
   - name: Product Tags
-    description: Product Tag endpoints that allow handling product tags in Medusa.
+    description: >
+      Product tags are string values created when you create or update a product
+      with a new tag.
+
+      Products can have more than one tag, and products can share tags. This
+      allows admins to associate products to similar tags that can be used to
+      filter products.
   - name: Product Types
-    description: Product Types endpoints that allow handling product types in Medusa.
+    description: >
+      Product types are string values created when you create or update a
+      product with a new type.
+
+      Products can have one type, and products can share types. This allows
+      admins to associate products with a type that can be used to filter
+      products.
+  - name: Product Variants
+    description: >
+      Product variants are the actual salable item in your store. Each variant
+      is a combination of the different option values available on the product.
+
+      Product variants can be managed through the Products endpoints.
+    externalDocs:
+      description: How to manage product variants
+      url: >-
+        https://docs.medusajs.com/modules/products/admin/manage-products#manage-product-variants
+  - name: Publishable API Keys
+    description: >
+      Publishable API Keys can be used to scope Store API calls with an API key,
+      determining what resources are retrieved when querying the API.
+
+      For example, a publishable API key can be associated with one or more
+      sales channels. When it is passed in the header of a request to the List
+      Product store endpoint,
+
+      the sales channels are inferred from the key and only products associated
+      with those sales channels are retrieved.
+
+      Admins can manage publishable API keys and their associated resources.
+      Currently, only Sales Channels are supported as a resource.
+    externalDocs:
+      description: How to manage publishable API keys
+      url: >-
+        https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys
+  - name: Reservations
+    description: >
+      Reservations, provided by the [Inventory
+      Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module),
+      are quantities of an item that are reserved, typically when an order is
+      placed but not yet fulfilled.
+
+      Reservations can be associated with any resources, but commonly with line
+      items of an order.
+    externalDocs:
+      description: How to manage item allocations in orders
+      url: >-
+        https://docs.medusajs.com/modules/multiwarehouse/admin/manage-item-allocations-in-orders
   - name: Regions
-    description: Region endpoints that allow handling regions in Medusa.
+    description: >
+      Regions are different countries or geographical regions that the commerce
+      store serves customers in.
+
+      Admins can manage these regions, their providers, and more.
+    externalDocs:
+      description: How to manage regions
+      url: >-
+        https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-regions
   - name: Return Reasons
-    description: Return Reason endpoints that allow handling return reasons in Medusa.
+    description: >
+      Return reasons are key-value pairs that are used to specify why an order
+      return is being created.
+
+      Admins can manage available return reasons, and they can be used by both
+      admins and customers when creating a return.
+    externalDocs:
+      description: How to manage return reasons
+      url: >-
+        https://docs.medusajs.com/modules/orders/admin/manage-returns#manage-return-reasons
   - name: Returns
-    description: Return endpoints that allow handling returns in Medusa.
+    description: >
+      A return can be created by a customer or an admin to return items in an
+      order.
+
+      Admins can manage these returns and change their state.
+    externalDocs:
+      description: How to manage returns
+      url: https://docs.medusajs.com/modules/orders/admin/manage-returns
   - name: Sales Channels
-    description: Sales Channel endpoints that allow handling sales channels in Medusa.
+    description: >
+      A sales channel indicates a channel where products can be sold in. For
+      example, a webshop or a mobile app.
+
+      Admins can manage sales channels and the products available in them.
+    externalDocs:
+      description: How to manage sales channels
+      url: https://docs.medusajs.com/modules/sales-channels/admin/manage
   - name: Shipping Options
-    description: Shipping Option endpoints that allow handling shipping options in Medusa.
+    description: >
+      A shipping option is used to define the available shipping methods during
+      checkout or when creating a return.
+
+      Admins can create an unlimited number of shipping options, each associated
+      with a shipping profile and fulfillment provider, among other resources.
+    externalDocs:
+      description: Shipping Option architecture
+      url: >-
+        https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option
   - name: Shipping Profiles
-    description: >-
-      Shipping Profile endpoints that allow handling shipping profiles in
-      Medusa.
+    description: >
+      A shipping profile is used to group products that can be shipped in the
+      same manner.
+
+      They are created by the admin and they're not associated with a
+      fulfillment provider.
+    externalDocs:
+      description: Shipping Option architecture
+      url: >-
+        https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-profile
+  - name: Stock Locations
+    description: >
+      A stock location, provided by the [Stock Location
+      module](https://docs.medusajs.com/modules/multiwarehouse/stock-location-module),
+      indicates a physical address that stock-kept items, such as physical
+      products, can be stored in.
+
+      An admin can create and manage available stock locations.
+    externalDocs:
+      description: How to manage stock locations.
+      url: >-
+        https://docs.medusajs.com/modules/multiwarehouse/admin/manage-stock-locations
   - name: Store
-    description: Store endpoints that allow handling stores in Medusa.
+    description: >
+      A store indicates the general configurations and details about the
+      commerce store. By default, there's only one store in the Medusa backend.
+
+      Admins can manage the store and its details or configurations.
   - name: Swaps
-    description: Swap endpoints that allow handling swaps in Medusa.
+    description: >
+      A swap is created by a customer or an admin to exchange an item with a new
+      one.
+
+      Creating a swap implicitely includes creating a return for the item being
+      exchanged.
+    externalDocs:
+      description: How to manage swaps
+      url: https://docs.medusajs.com/modules/orders/admin/manage-swaps
   - name: Tax Rates
-    description: Tax Rate endpoints that allow handling tax rates in Medusa.
+    description: >
+      Each region has at least a default tax rate. Admins can create and manage
+      additional tax rates that can be applied for certain conditions, such as
+      for specific product types.
+    externalDocs:
+      description: How to manage tax rates
+      url: https://docs.medusajs.com/modules/taxes/admin/manage-tax-rates
   - name: Uploads
-    description: Upload endpoints that allow handling uploads in Medusa.
+    description: >
+      The upload endpoints are used to upload any type of resources. For
+      example, they can be used to upload CSV files that are used to import
+      products into the store.
+    externalDocs:
+      description: How to upload CSV file when importing a product.
+      url: >-
+        https://docs.medusajs.com/modules/products/admin/import-products#1-upload-csv-file
   - name: Users
-    description: User endpoints that allow handling users in Medusa.
-  - name: Variants
-    description: Product Variant endpoints that allow handling product variants in Medusa.
+    description: >
+      A store can have more than one user, each having the same privileges.
+      Admins can manage users, their passwords, and more.
+    externalDocs:
+      description: How to manage users
+      url: https://docs.medusajs.com/modules/users/admin/manage-users
 servers:
   - url: https://api.medusa-commerce.com
 paths:
diff --git a/docs/api/admin/paths/admin_apps.yaml b/docs/api/admin/paths/admin_apps.yaml
index 9c99d37b74..5d4187adca 100644
--- a/docs/api/admin/paths/admin_apps.yaml
+++ b/docs/api/admin/paths/admin_apps.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetApps
   summary: List Applications
-  description: Retrieve a list of applications.
+  description: Retrieve a list of applications registered in the Medusa backend.
   x-authenticated: true
   x-codegen:
     method: list
@@ -14,7 +14,7 @@ get:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Apps
+    - Apps Oauth
   responses:
     '200':
       description: OK
diff --git a/docs/api/admin/paths/admin_apps_authorizations.yaml b/docs/api/admin/paths/admin_apps_authorizations.yaml
index 92d46e9a8d..6cf45c6c6f 100644
--- a/docs/api/admin/paths/admin_apps_authorizations.yaml
+++ b/docs/api/admin/paths/admin_apps_authorizations.yaml
@@ -1,7 +1,9 @@
 post:
   operationId: PostApps
   summary: Generate Token for App
-  description: Generates a token for an application.
+  description: >-
+    Use an app's Oauth provider to generate and store a new token for
+    authentication.
   x-authenticated: true
   requestBody:
     content:
@@ -19,7 +21,7 @@ post:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Apps
+    - Apps Oauth
   responses:
     '200':
       description: OK
diff --git a/docs/api/admin/paths/admin_auth.yaml b/docs/api/admin/paths/admin_auth.yaml
index 295f934faa..1e12c1758c 100644
--- a/docs/api/admin/paths/admin_auth.yaml
+++ b/docs/api/admin/paths/admin_auth.yaml
@@ -2,7 +2,7 @@ get:
   operationId: GetAuth
   summary: Get Current User
   x-authenticated: true
-  description: Gets the currently logged in User.
+  description: Get the currently logged in user's details.
   x-codegen:
     method: getSession
   x-codeSamples:
@@ -42,23 +42,16 @@ post:
   operationId: PostAuth
   summary: User Login
   x-authenticated: false
-  description: Logs a User in and authorizes them to manage Store settings.
-  parameters: []
+  description: >-
+    Log a User in and includes the Cookie session in the response header. The
+    cookie session can be used in subsequent requests to authorize the user to
+    perform admin functionalities. When using Medusa's JS or Medusa React
+    clients, the cookie is automatically attached to subsequent requests.
   requestBody:
     content:
       application/json:
         schema:
-          type: object
-          required:
-            - email
-            - password
-          properties:
-            email:
-              type: string
-              description: The User's email.
-            password:
-              type: string
-              description: The User's password.
+          $ref: ../components/schemas/AdminPostAuthReq.yaml
   x-codegen:
     method: createSession
   x-codeSamples:
@@ -95,7 +88,11 @@ delete:
   operationId: DeleteAuth
   summary: User Logout
   x-authenticated: true
-  description: Deletes the current session for the logged in user.
+  description: >-
+    Delete the current session for the logged in user. This will only work if
+    you're using Cookie session for authentication. If the API token is still
+    passed in the header, the user is still authorized to perform admin
+    functionalities in other endpoints.
   x-codegen:
     method: deleteSession
   x-codeSamples:
diff --git a/docs/api/admin/paths/admin_batch-jobs.yaml b/docs/api/admin/paths/admin_batch-jobs.yaml
index a8cbf79f4e..4fdcc2d51d 100644
--- a/docs/api/admin/paths/admin_batch-jobs.yaml
+++ b/docs/api/admin/paths/admin_batch-jobs.yaml
@@ -1,18 +1,20 @@
 get:
   operationId: GetBatchJobs
   summary: List Batch Jobs
-  description: Retrieve a list of Batch Jobs.
+  description: >-
+    Retrieve a list of Batch Jobs. The batch jobs can be filtered by fields such
+    as `type` or `confirmed_at`. The batch jobs can also be sorted or paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: limit
-      description: The number of batch jobs to return.
+      description: Limit the number of batch jobs returned.
       schema:
         type: integer
         default: 10
     - in: query
       name: offset
-      description: The number of batch jobs to skip before results.
+      description: The number of batch jobs to skip when retrieving the batch jobs.
       schema:
         type: integer
         default: 0
@@ -42,9 +44,7 @@ get:
       name: confirmed_at
       style: form
       explode: false
-      description: >-
-        Date comparison for when resulting collections was confirmed, i.e. less
-        than, greater than etc.
+      description: Filter by a confirmation date range.
       schema:
         type: object
         properties:
@@ -68,9 +68,7 @@ get:
       name: pre_processed_at
       style: form
       explode: false
-      description: >-
-        Date comparison for when resulting collections was pre processed, i.e.
-        less than, greater than etc.
+      description: Filter by a pre-processing date range.
       schema:
         type: object
         properties:
@@ -94,9 +92,7 @@ get:
       name: completed_at
       style: form
       explode: false
-      description: >-
-        Date comparison for when resulting collections was completed, i.e. less
-        than, greater than etc.
+      description: Filter by a completion date range.
       schema:
         type: object
         properties:
@@ -120,9 +116,7 @@ get:
       name: failed_at
       style: form
       explode: false
-      description: >-
-        Date comparison for when resulting collections was failed, i.e. less
-        than, greater than etc.
+      description: Filter by a failure date range.
       schema:
         type: object
         properties:
@@ -146,9 +140,7 @@ get:
       name: canceled_at
       style: form
       explode: false
-      description: >-
-        Date comparison for when resulting collections was canceled, i.e. less
-        than, greater than etc.
+      description: Filter by a cancelation date range.
       schema:
         type: object
         properties:
@@ -170,30 +162,28 @@ get:
             format: date
     - in: query
       name: order
-      description: Field used to order retrieved batch jobs
+      description: A batch-job field to sort-order the retrieved batch jobs by.
       schema:
         type: string
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each order of the
-        result.
+        Comma-separated relations that should be expanded in the returned batch
+        jobs.
       schema:
         type: string
     - in: query
       name: fields
       description: >-
-        (Comma separated) Which fields should be included in each order of the
-        result.
+        Comma-separated fields that should be included in the returned batch
+        jobs.
       schema:
         type: string
     - in: query
       name: created_at
       style: form
       explode: false
-      description: >-
-        Date comparison for when resulting collections was created, i.e. less
-        than, greater than etc.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -217,9 +207,7 @@ get:
       name: updated_at
       style: form
       explode: false
-      description: >-
-        Date comparison for when resulting collections was updated, i.e. less
-        than, greater than etc.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -278,7 +266,13 @@ get:
 post:
   operationId: PostBatchJobs
   summary: Create a Batch Job
-  description: Creates a Batch Job.
+  description: >-
+    Create a Batch Job to be executed asynchronously in the Medusa backend. If
+    `dry_run` is set to `true`, the batch job will not be executed until the it
+    is confirmed, which can be done using the Confirm Batch Job endpoint.
+  externalDocs:
+    description: How to create a batch job
+    url: https://docs.medusajs.com/development/batch-jobs/create#create-batch-job
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_batch-jobs_{id}.yaml b/docs/api/admin/paths/admin_batch-jobs_{id}.yaml
index 5e263ffaa2..18b8dbf3de 100644
--- a/docs/api/admin/paths/admin_batch-jobs_{id}.yaml
+++ b/docs/api/admin/paths/admin_batch-jobs_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetBatchJobsBatchJob
   summary: Get a Batch Job
-  description: Retrieves a Batch Job.
+  description: Retrieve the details of a batch job.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_batch-jobs_{id}_cancel.yaml b/docs/api/admin/paths/admin_batch-jobs_{id}_cancel.yaml
index 52b2f5c913..54250c5b23 100644
--- a/docs/api/admin/paths/admin_batch-jobs_{id}_cancel.yaml
+++ b/docs/api/admin/paths/admin_batch-jobs_{id}_cancel.yaml
@@ -1,7 +1,9 @@
 post:
   operationId: PostBatchJobsBatchJobCancel
   summary: Cancel a Batch Job
-  description: Marks a batch job as canceled
+  description: >-
+    Mark a batch job as canceled. When a batch job is canceled, the processing
+    of the batch job doesn’t automatically stop.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_batch-jobs_{id}_confirm.yaml b/docs/api/admin/paths/admin_batch-jobs_{id}_confirm.yaml
index 495a937aac..9ae3af4e0d 100644
--- a/docs/api/admin/paths/admin_batch-jobs_{id}_confirm.yaml
+++ b/docs/api/admin/paths/admin_batch-jobs_{id}_confirm.yaml
@@ -1,7 +1,10 @@
 post:
   operationId: PostBatchJobsBatchJobConfirmProcessing
   summary: Confirm a Batch Job
-  description: Confirms that a previously requested batch job should be executed.
+  description: >-
+    When a batch job is created, it is not executed automatically if `dry_run`
+    is set to `true`. This endpoint confirms that the batch job should be
+    executed.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_collections.yaml b/docs/api/admin/paths/admin_collections.yaml
index f5880e9cdb..6e7e1e126c 100644
--- a/docs/api/admin/paths/admin_collections.yaml
+++ b/docs/api/admin/paths/admin_collections.yaml
@@ -1,7 +1,10 @@
 get:
   operationId: GetCollections
   summary: List Collections
-  description: Retrieve a list of Product Collection.
+  description: >-
+    Retrieve a list of Product Collection. The product collections can be
+    filtered by fields such as `handle` or `title`. The collections can also be
+    sorted or paginated.
   x-authenticated: true
   parameters:
     - in: query
@@ -12,33 +15,33 @@ get:
         default: 10
     - in: query
       name: offset
-      description: The number of collections to skip before the results.
+      description: The number of collections to skip when retrieving the collections.
       schema:
         type: integer
         default: 0
     - in: query
       name: title
-      description: The title of collections to return.
+      description: Filter collections by their title.
       schema:
         type: string
     - in: query
       name: handle
-      description: The handle of collections to return.
+      description: Filter collections by their handle.
       schema:
         type: string
     - in: query
       name: q
-      description: a search term to search titles and handles.
+      description: a term to search collections by their title or handle.
       schema:
         type: string
     - in: query
       name: discount_condition_id
-      description: The discount condition id on which to filter the product collections.
+      description: Filter collections by a discount condition ID associated with them.
       schema:
         type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting collections were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -60,7 +63,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting collections were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -82,7 +85,7 @@ get:
             format: date
     - in: query
       name: deleted_at
-      description: Date comparison for when resulting collections were deleted.
+      description: Filter by a deletion date range.
       schema:
         type: object
         properties:
@@ -118,7 +121,7 @@ get:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Collections
+    - Product Collections
   responses:
     '200':
       description: OK
@@ -141,7 +144,7 @@ get:
 post:
   operationId: PostCollections
   summary: Create a Collection
-  description: Creates a Product Collection.
+  description: Create a Product Collection.
   x-authenticated: true
   requestBody:
     content:
@@ -163,7 +166,7 @@ post:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Collections
+    - Product Collections
   responses:
     '200':
       description: OK
diff --git a/docs/api/admin/paths/admin_collections_{id}.yaml b/docs/api/admin/paths/admin_collections_{id}.yaml
index 00be96a064..492f6774a4 100644
--- a/docs/api/admin/paths/admin_collections_{id}.yaml
+++ b/docs/api/admin/paths/admin_collections_{id}.yaml
@@ -1,7 +1,9 @@
 get:
   operationId: GetCollectionsCollection
   summary: Get a Collection
-  description: Retrieves a Product Collection.
+  description: >-
+    Retrieve a Product Collection by its ID. The products associated with it are
+    expanded and returned as well.
   x-authenticated: true
   parameters:
     - in: path
@@ -25,7 +27,7 @@ get:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Collections
+    - Product Collections
   responses:
     '200':
       description: OK
@@ -48,7 +50,7 @@ get:
 post:
   operationId: PostCollectionsCollection
   summary: Update a Collection
-  description: Updates a Product Collection.
+  description: Update a Product Collection's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -77,7 +79,7 @@ post:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Collections
+    - Product Collections
   responses:
     '200':
       description: OK
@@ -100,7 +102,7 @@ post:
 delete:
   operationId: DeleteCollectionsCollection
   summary: Delete a Collection
-  description: Deletes a Product Collection.
+  description: Delete a Product Collection. This does not delete associated products.
   x-authenticated: true
   parameters:
     - in: path
@@ -124,7 +126,7 @@ delete:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Collections
+    - Product Collections
   responses:
     '200':
       description: OK
diff --git a/docs/api/admin/paths/admin_collections_{id}_products_batch.yaml b/docs/api/admin/paths/admin_collections_{id}_products_batch.yaml
index 284840f648..bdbf4a0162 100644
--- a/docs/api/admin/paths/admin_collections_{id}_products_batch.yaml
+++ b/docs/api/admin/paths/admin_collections_{id}_products_batch.yaml
@@ -1,13 +1,13 @@
 post:
   operationId: PostProductsToCollection
-  summary: Update Products
-  description: Updates products associated with a Product Collection
+  summary: Add Products to Collection
+  description: Add products to a product collection.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Collection.
+      description: The ID of the product collection.
       schema:
         type: string
   requestBody:
@@ -18,6 +18,11 @@ post:
   x-codegen:
     method: addProducts
   x-codeSamples:
+    - lang: JavaScript
+      label: JS Client
+      source:
+        $ref: >-
+          ../code_samples/JavaScript/admin_collections_{id}_products_batch/post.js
     - lang: Shell
       label: cURL
       source:
@@ -26,7 +31,7 @@ post:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Collections
+    - Product Collections
   responses:
     '200':
       description: OK
@@ -48,14 +53,16 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteProductsFromCollection
-  summary: Remove Product
-  description: Removes products associated with a Product Collection
+  summary: Remove Products from Collection
+  description: >-
+    Remove a list of products from a collection. This would not delete the
+    product, only the association between the product and the collection.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Collection.
+      description: The ID of the Product Collection.
       schema:
         type: string
   requestBody:
@@ -66,6 +73,11 @@ delete:
   x-codegen:
     method: removeProducts
   x-codeSamples:
+    - lang: JavaScript
+      label: JS Client
+      source:
+        $ref: >-
+          ../code_samples/JavaScript/admin_collections_{id}_products_batch/delete.js
     - lang: Shell
       label: cURL
       source:
@@ -74,7 +86,7 @@ delete:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Collections
+    - Product Collections
   responses:
     '200':
       description: OK
diff --git a/docs/api/admin/paths/admin_currencies.yaml b/docs/api/admin/paths/admin_currencies.yaml
index fa5fc77506..7e03a03381 100644
--- a/docs/api/admin/paths/admin_currencies.yaml
+++ b/docs/api/admin/paths/admin_currencies.yaml
@@ -1,33 +1,36 @@
 get:
   operationId: GetCurrencies
   summary: List Currency
-  description: Retrieves a list of Currency
+  description: >-
+    Retrieve a list of currencies. The currencies can be filtered by fields such
+    as `code`. The currencies can also be sorted or paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: code
-      description: Code of the currency to search for.
+      description: filter by currency code.
       schema:
         type: string
     - in: query
       name: includes_tax
-      description: Search for tax inclusive currencies.
+      description: filter currencies by whether they include taxes or not.
       schema:
         type: boolean
+        x-featureFlag: tax_inclusive_pricing
     - in: query
       name: order
-      description: order to retrieve products in.
+      description: A field to sort order the retrieved currencies by.
       schema:
         type: string
     - in: query
       name: offset
-      description: How many products to skip in the result.
+      description: The number of currencies to skip when retrieving the currencies.
       schema:
         type: number
         default: '0'
     - in: query
       name: limit
-      description: Limit the number of products returned.
+      description: The number of currencies to return.
       schema:
         type: number
         default: '20'
diff --git a/docs/api/admin/paths/admin_currencies_{code}.yaml b/docs/api/admin/paths/admin_currencies_{code}.yaml
index 948e4e274b..72d84268b2 100644
--- a/docs/api/admin/paths/admin_currencies_{code}.yaml
+++ b/docs/api/admin/paths/admin_currencies_{code}.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostCurrenciesCurrency
   summary: Update a Currency
-  description: Update a Currency
+  description: Update a Currency's details.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_customer-groups.yaml b/docs/api/admin/paths/admin_customer-groups.yaml
index fb9d06d938..b6e4290c9c 100644
--- a/docs/api/admin/paths/admin_customer-groups.yaml
+++ b/docs/api/admin/paths/admin_customer-groups.yaml
@@ -1,28 +1,33 @@
 get:
   operationId: GetCustomerGroups
   summary: List Customer Groups
-  description: Retrieve a list of customer groups.
+  description: >-
+    Retrieve a list of customer groups. The customer groups can be filtered by
+    fields such as `name` or `id. The customer groups can also be sorted or
+    paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: q
-      description: Query used for searching customer group names.
+      description: term to search customer groups by name.
       schema:
         type: string
     - in: query
       name: offset
-      description: How many groups to skip in the result.
+      description: >-
+        The number of customer groups to skip when retrieving the customer
+        groups.
       schema:
         type: integer
         default: 0
     - in: query
       name: order
-      description: the field used to order the customer groups.
+      description: A field to sort order the retrieved customer groups by.
       schema:
         type: string
     - in: query
       name: discount_condition_id
-      description: The discount condition id on which to filter the customer groups.
+      description: Filter by discount condition ID.
       schema:
         type: string
     - in: query
@@ -35,7 +40,7 @@ get:
           - type: string
             description: customer group ID
           - type: array
-            description: multiple customer group IDs
+            description: an array of customer group IDs
             items:
               type: string
           - type: object
@@ -59,13 +64,13 @@ get:
       description: Filter by the customer group name
       schema:
         type: array
-        description: multiple customer group names
+        description: an array of customer group names
         items:
           type: string
           description: customer group name
     - in: query
       name: created_at
-      description: Date comparison for when resulting customer groups were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -87,7 +92,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting customer groups were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -109,15 +114,15 @@ get:
             format: date
     - in: query
       name: limit
-      description: Limit the number of customer groups returned.
+      description: The number of customer groups to return.
       schema:
         type: integer
         default: 10
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each customer
-        groups of the result.
+        Comma-separated relations that should be expanded in the returned
+        customer groups.
       schema:
         type: string
   x-codegen:
@@ -159,7 +164,7 @@ get:
 post:
   operationId: PostCustomerGroups
   summary: Create a Customer Group
-  description: Creates a CustomerGroup.
+  description: Creates a Customer Group.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_customer-groups_{id}.yaml b/docs/api/admin/paths/admin_customer-groups_{id}.yaml
index 8cf327bc8f..0dfc771208 100644
--- a/docs/api/admin/paths/admin_customer-groups_{id}.yaml
+++ b/docs/api/admin/paths/admin_customer-groups_{id}.yaml
@@ -1,7 +1,9 @@
 get:
   operationId: GetCustomerGroupsGroup
   summary: Get a Customer Group
-  description: Retrieves a Customer Group.
+  description: >-
+    Retrieve a Customer Group by its ID. You can expand the customer group's
+    relations or select the fields that should be returned.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +14,16 @@ get:
         type: string
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in the customer group.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        customer group.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Which fields should be included in the customer group.
+      description: >-
+        Comma-separated fields that should be included in the returned customer
+        group.
       schema:
         type: string
   x-codegen:
@@ -59,7 +65,7 @@ get:
 post:
   operationId: PostCustomerGroupsGroup
   summary: Update a Customer Group
-  description: Update a CustomerGroup.
+  description: Update a Customer Group's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -111,7 +117,9 @@ post:
 delete:
   operationId: DeleteCustomerGroupsCustomerGroup
   summary: Delete a Customer Group
-  description: Deletes a CustomerGroup.
+  description: >-
+    Delete a customer group. This doesn't delete the customers associated with
+    the customer group.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_customer-groups_{id}_customers.yaml b/docs/api/admin/paths/admin_customer-groups_{id}_customers.yaml
index 6e431ac4e5..a1a6d25e47 100644
--- a/docs/api/admin/paths/admin_customer-groups_{id}_customers.yaml
+++ b/docs/api/admin/paths/admin_customer-groups_{id}_customers.yaml
@@ -1,7 +1,9 @@
 get:
   operationId: GetCustomerGroupsGroupCustomers
   summary: List Customers
-  description: Retrieves a list of customers in a customer group
+  description: >-
+    Retrieve a list of customers in a customer group. The customers can be
+    filtered by the `q` field. The customers can also be paginated.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,24 +14,26 @@ get:
         type: string
     - in: query
       name: limit
-      description: The number of items to return.
+      description: The number of customers to return.
       schema:
         type: integer
         default: 50
     - in: query
       name: offset
-      description: The items to skip before result.
+      description: The number of customers to skip when retrieving the customers.
       schema:
         type: integer
         default: 0
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in each customer.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        customers.
       schema:
         type: string
     - in: query
       name: q
-      description: a search term to search email, first_name, and last_name.
+      description: a term to search customers by email, first_name, and last_name.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_customer-groups_{id}_customers_batch.yaml b/docs/api/admin/paths/admin_customer-groups_{id}_customers_batch.yaml
index 098537631c..974477da1b 100644
--- a/docs/api/admin/paths/admin_customer-groups_{id}_customers_batch.yaml
+++ b/docs/api/admin/paths/admin_customer-groups_{id}_customers_batch.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostCustomerGroupsGroupCustomersBatch
-  summary: Add Customers
-  description: Adds a list of customers, represented by id's, to a customer group.
+  summary: Add Customers to Group
+  description: Add a list of customers to a customer group.
   x-authenticated: true
   parameters:
     - in: path
@@ -55,8 +55,10 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteCustomerGroupsGroupCustomerBatch
-  summary: Remove Customers
-  description: Removes a list of customers, represented by id's, from a customer group.
+  summary: Remove Customers from Group
+  description: >-
+    Remove a list of customers from a customer group. This doesn't delete the
+    customer, only the association between the customer and the customer group.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_customers.yaml b/docs/api/admin/paths/admin_customers.yaml
index ca668a7b00..f12a750f3e 100644
--- a/docs/api/admin/paths/admin_customers.yaml
+++ b/docs/api/admin/paths/admin_customers.yaml
@@ -1,31 +1,44 @@
 get:
   operationId: GetCustomers
   summary: List Customers
-  description: Retrieves a list of Customers.
+  description: >-
+    Retrieve a list of Customers. The customers can be filtered by fields such
+    as `q` or `groups`. The customers can also be paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: limit
-      description: The number of items to return.
+      description: The number of customers to return.
       schema:
         type: integer
         default: 50
     - in: query
       name: offset
-      description: The items to skip before result.
+      description: The number of customers to skip when retrieving the customers.
       schema:
         type: integer
         default: 0
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in each customer.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        customer.
       schema:
         type: string
     - in: query
       name: q
-      description: a search term to search email, first_name, and last_name.
+      description: term to search customers' email, first_name, and last_name fields.
       schema:
         type: string
+    - in: query
+      name: groups
+      style: form
+      explode: false
+      description: Filter by customer group IDs.
+      schema:
+        type: array
+        items:
+          type: string
   x-codegen:
     method: list
     queryParams: AdminGetCustomersParams
@@ -65,7 +78,7 @@ get:
 post:
   operationId: PostCustomers
   summary: Create a Customer
-  description: Creates a Customer.
+  description: Allow admins to create a customer.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_customers_{id}.yaml b/docs/api/admin/paths/admin_customers_{id}.yaml
index 8ec560bb02..be75fed184 100644
--- a/docs/api/admin/paths/admin_customers_{id}.yaml
+++ b/docs/api/admin/paths/admin_customers_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetCustomersCustomer
   summary: Get a Customer
-  description: Retrieves a Customer.
+  description: Retrieve the details of a customer.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +12,14 @@ get:
         type: string
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in the customer.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        customer.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Which fields should be included in the customer.
+      description: Comma-separated fields that should be included in the returned customer.
       schema:
         type: string
   x-codegen:
@@ -58,7 +60,7 @@ get:
 post:
   operationId: PostCustomersCustomer
   summary: Update a Customer
-  description: Updates a Customer.
+  description: Update a Customer's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -69,12 +71,16 @@ post:
         type: string
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in each customer.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        customer.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Which fields should be retrieved in each customer.
+      description: >-
+        Comma-separated fields that should be retrieved in the returned
+        customer.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_discounts.yaml b/docs/api/admin/paths/admin_discounts.yaml
index 183b683690..3d7e4bf8e8 100644
--- a/docs/api/admin/paths/admin_discounts.yaml
+++ b/docs/api/admin/paths/admin_discounts.yaml
@@ -2,16 +2,18 @@ get:
   operationId: GetDiscounts
   summary: List Discounts
   x-authenticated: true
-  description: Retrieves a list of Discounts
+  description: >-
+    Retrieve a list of Discounts. The discounts can be filtered by fields such
+    as `rule` or `is_dynamic`. The discounts can also be paginated.
   parameters:
     - in: query
       name: q
-      description: Search query applied on the code field.
+      description: term to search discounts' code field.
       schema:
         type: string
     - in: query
       name: rule
-      description: Discount Rules filters to apply on the search
+      description: Filter discounts by rule fields.
       schema:
         type: object
         properties:
@@ -21,43 +23,40 @@ get:
               - fixed
               - percentage
               - free_shipping
-            description: >-
-              The type of the Discount, can be `fixed` for discounts that reduce
-              the price by a fixed amount, `percentage` for percentage
-              reductions or `free_shipping` for shipping vouchers.
+            description: Filter discounts by type.
           allocation:
             type: string
             enum:
               - total
               - item
-            description: >-
-              The value that the discount represents; this will depend on the
-              type of the discount
+            description: Filter discounts by allocation type.
     - in: query
       name: is_dynamic
-      description: Return only dynamic discounts.
+      description: Filter discounts by whether they're dynamic or not.
       schema:
         type: boolean
     - in: query
       name: is_disabled
-      description: Return only disabled discounts.
+      description: Filter discounts by whether they're disabled or not.
       schema:
         type: boolean
     - in: query
       name: limit
-      description: The number of items in the response
+      description: The number of discounts to return
       schema:
         type: number
         default: '20'
     - in: query
       name: offset
-      description: The offset of items in response
+      description: The number of discounts to skip when retrieving the discounts.
       schema:
         type: number
         default: '0'
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in each returned
+        discount.
       schema:
         type: string
   x-codegen:
@@ -98,20 +97,24 @@ get:
       $ref: ../components/responses/500_error.yaml
 post:
   operationId: PostDiscounts
-  summary: Creates a Discount
+  summary: Create a Discount
   x-authenticated: true
   description: >-
-    Creates a Discount with a given set of rules that define how the Discount
-    behaves.
+    Create a Discount with a given set of rules that defines how the Discount is
+    applied.
   parameters:
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Which fields should be retrieved in the results.
+      description: >-
+        Comma-separated fields that should be retrieved in the returned
+        discount.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_discounts_code_{code}.yaml b/docs/api/admin/paths/admin_discounts_code_{code}.yaml
index 2e318cc8c7..5ad8b9b401 100644
--- a/docs/api/admin/paths/admin_discounts_code_{code}.yaml
+++ b/docs/api/admin/paths/admin_discounts_code_{code}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetDiscountsDiscountCode
   summary: Get Discount by Code
-  description: Retrieves a Discount by its discount code
+  description: Retrieve a Discount's details by its discount code
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +12,14 @@ get:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: Comma-separated fields that should be included in the returned discount.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_discounts_{discount_id}_conditions.yaml b/docs/api/admin/paths/admin_discounts_{discount_id}_conditions.yaml
index 8062ba9ac6..b8305e42b5 100644
--- a/docs/api/admin/paths/admin_discounts_{discount_id}_conditions.yaml
+++ b/docs/api/admin/paths/admin_discounts_{discount_id}_conditions.yaml
@@ -2,29 +2,29 @@ post:
   operationId: PostDiscountsDiscountConditions
   summary: Create a Condition
   description: >-
-    Creates a DiscountCondition. Only one of `products`, `product_types`,
+    Create a Discount Condition. Only one of `products`, `product_types`,
     `product_collections`, `product_tags`, and `customer_groups` should be
-    provided.
+    provided, based on the type of discount condition. For example, if the
+    discount condition's type is `products`, the `products` field should be
+    provided in the request body.
   x-authenticated: true
   parameters:
     - in: path
       name: discount_id
       required: true
-      description: The ID of the Product.
+      description: The ID of the discount.
       schema:
         type: string
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each product of the
-        result.
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
-      description: >-
-        (Comma separated) Which fields should be included in each product of the
-        result.
+      description: Comma-separated fields that should be included in the returned discount.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}.yaml b/docs/api/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}.yaml
index ea496cba7f..7daef49a00 100644
--- a/docs/api/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}.yaml
+++ b/docs/api/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetDiscountsDiscountConditionsCondition
   summary: Get a Condition
-  description: Gets a DiscountCondition
+  description: Retrieve a Discount Condition's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -13,17 +13,21 @@ get:
     - in: path
       name: condition_id
       required: true
-      description: The ID of the DiscountCondition.
+      description: The ID of the Discount Condition.
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        discount condition.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned discount
+        condition.
       schema:
         type: string
   x-codegen:
@@ -68,35 +72,35 @@ post:
   operationId: PostDiscountsDiscountConditionsCondition
   summary: Update a Condition
   description: >-
-    Updates a DiscountCondition. Only one of `products`, `product_types`,
+    Update a Discount Condition. Only one of `products`, `product_types`,
     `product_collections`, `product_tags`, and `customer_groups` should be
-    provided.
+    provided, based on the type of discount condition. For example, if the
+    discount condition's type is `products`, the `products` field should be
+    provided in the request body.
   x-authenticated: true
   parameters:
     - in: path
       name: discount_id
       required: true
-      description: The ID of the Product.
+      description: The ID of the Discount.
       schema:
         type: string
     - in: path
       name: condition_id
       required: true
-      description: The ID of the DiscountCondition.
+      description: The ID of the Discount Condition.
       schema:
         type: string
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each item of the
-        result.
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
-      description: >-
-        (Comma separated) Which fields should be included in each item of the
-        result.
+      description: Comma-separated fields that should be included in the returned discount.
       schema:
         type: string
   requestBody:
@@ -146,7 +150,9 @@ post:
 delete:
   operationId: DeleteDiscountsDiscountConditionsCondition
   summary: Delete a Condition
-  description: Deletes a DiscountCondition
+  description: >-
+    Deletes a Discount Condition. This does not delete resources associated to
+    the discount condition.
   x-authenticated: true
   parameters:
     - in: path
@@ -158,17 +164,19 @@ delete:
     - in: path
       name: condition_id
       required: true
-      description: The ID of the DiscountCondition
+      description: The ID of the Discount Condition
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: Comma-separated fields that should be included in the returned discount.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}_batch.yaml b/docs/api/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}_batch.yaml
index 449b2a70aa..1a27eb4491 100644
--- a/docs/api/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}_batch.yaml
+++ b/docs/api/admin/paths/admin_discounts_{discount_id}_conditions_{condition_id}_batch.yaml
@@ -1,33 +1,35 @@
 post:
   operationId: PostDiscountsDiscountConditionsConditionBatch
   summary: Add Batch Resources
-  description: Add a batch of resources to a discount condition.
+  description: >-
+    Add a batch of resources to a discount condition. The type of resource
+    depends on the type of discount condition. For example, if the discount
+    condition's type is `products`, the resources being added should be
+    products.
   x-authenticated: true
   parameters:
     - in: path
       name: discount_id
       required: true
-      description: The ID of the Product.
+      description: The ID of the discount the condition belongs to.
       schema:
         type: string
     - in: path
       name: condition_id
       required: true
-      description: The ID of the condition on which to add the item.
+      description: The ID of the discount condition on which to add the item.
       schema:
         type: string
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which relations should be expanded in each discount of
-        the result.
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
-      description: >-
-        (Comma separated) Which fields should be included in each discount of
-        the result.
+      description: Comma-separated fields that should be included in the returned discount.
       schema:
         type: string
   requestBody:
@@ -76,34 +78,35 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteDiscountsDiscountConditionsConditionBatch
-  summary: Delete Batch Resources
-  description: Delete a batch of resources from a discount condition.
+  summary: Remove Batch Resources
+  description: >-
+    Remove a batch of resources from a discount condition. This will only remove
+    the association between the resource and the discount condition, but not the
+    resource itself.
   x-authenticated: true
   parameters:
     - in: path
       name: discount_id
       required: true
-      description: The ID of the Product.
+      description: The ID of the discount.
       schema:
         type: string
     - in: path
       name: condition_id
       required: true
-      description: The ID of the condition on which to add the item.
+      description: The ID of the condition to remove the resources from.
       schema:
         type: string
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which relations should be expanded in each discount of
-        the result.
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
-      description: >-
-        (Comma separated) Which fields should be included in each discount of
-        the result.
+      description: Comma-separated fields that should be included in the returned discount.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_discounts_{id}.yaml b/docs/api/admin/paths/admin_discounts_{id}.yaml
index d9003c625b..3c5dc40fe9 100644
--- a/docs/api/admin/paths/admin_discounts_{id}.yaml
+++ b/docs/api/admin/paths/admin_discounts_{id}.yaml
@@ -12,12 +12,14 @@ get:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: Comma-separated fields that should be included in the returned discount.
       schema:
         type: string
   x-codegen:
@@ -60,8 +62,8 @@ post:
   operationId: PostDiscountsDiscount
   summary: Update a Discount
   description: >-
-    Updates a Discount with a given set of rules that define how the Discount
-    behaves.
+    Update a Discount with a given set of rules that define how the Discount is
+    applied.
   x-authenticated: true
   parameters:
     - in: path
@@ -73,15 +75,15 @@ post:
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each item of the
-        result.
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
       description: >-
-        (Comma separated) Which fields should be included in each item of the
-        result.
+        Comma-separated fields that should be retrieved in the returned
+        discount.
       schema:
         type: string
   requestBody:
@@ -128,7 +130,9 @@ post:
 delete:
   operationId: DeleteDiscountsDiscount
   summary: Delete a Discount
-  description: Deletes a Discount.
+  description: >-
+    Delete a Discount. Deleting the discount will make it unavailable for
+    customers to use.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_discounts_{id}_dynamic-codes.yaml b/docs/api/admin/paths/admin_discounts_{id}_dynamic-codes.yaml
index 8418de52f1..6ba7684a91 100644
--- a/docs/api/admin/paths/admin_discounts_{id}_dynamic-codes.yaml
+++ b/docs/api/admin/paths/admin_discounts_{id}_dynamic-codes.yaml
@@ -2,14 +2,15 @@ post:
   operationId: PostDiscountsDiscountDynamicCodes
   summary: Create a Dynamic Code
   description: >-
-    Creates a dynamic unique code that can map to a parent Discount. This is
-    useful if you want to automatically generate codes with the same behaviour.
+    Create a dynamic unique code that can map to a parent Discount. This is
+    useful if you want to automatically generate codes with the same rules and
+    conditions.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Discount to create the dynamic code from."
+      description: The ID of the Discount to create the dynamic code for."
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_discounts_{id}_dynamic-codes_{code}.yaml b/docs/api/admin/paths/admin_discounts_{id}_dynamic-codes_{code}.yaml
index 8c0610f4a3..bec733363d 100644
--- a/docs/api/admin/paths/admin_discounts_{id}_dynamic-codes_{code}.yaml
+++ b/docs/api/admin/paths/admin_discounts_{id}_dynamic-codes_{code}.yaml
@@ -1,7 +1,7 @@
 delete:
   operationId: DeleteDiscountsDiscountDynamicCodesCode
   summary: Delete a Dynamic Code
-  description: Deletes a dynamic code from a Discount.
+  description: Delete a dynamic code from a Discount.
   x-authenticated: true
   parameters:
     - in: path
@@ -13,7 +13,7 @@ delete:
     - in: path
       name: code
       required: true
-      description: The ID of the Discount
+      description: The dynamic code to delete
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_discounts_{id}_regions_{region_id}.yaml b/docs/api/admin/paths/admin_discounts_{id}_regions_{region_id}.yaml
index 727beddea7..55155df13d 100644
--- a/docs/api/admin/paths/admin_discounts_{id}_regions_{region_id}.yaml
+++ b/docs/api/admin/paths/admin_discounts_{id}_regions_{region_id}.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostDiscountsDiscountRegionsRegion
-  summary: Add Region
-  description: Adds a Region to the list of Regions that a Discount can be used in.
+  summary: Add Region to Discount
+  description: Add a Region to the list of Regions a Discount can be used in.
   x-authenticated: true
   parameters:
     - in: path
@@ -56,7 +56,10 @@ delete:
   operationId: DeleteDiscountsDiscountRegionsRegion
   summary: Remove Region
   x-authenticated: true
-  description: Removes a Region from the list of Regions that a Discount can be used in.
+  description: >-
+    Remove a Region from the list of Regions that a Discount can be used in.
+    This does not delete a region, only the association between it and the
+    discount.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/admin/paths/admin_draft-orders.yaml b/docs/api/admin/paths/admin_draft-orders.yaml
index 22681cec9f..325a99def2 100644
--- a/docs/api/admin/paths/admin_draft-orders.yaml
+++ b/docs/api/admin/paths/admin_draft-orders.yaml
@@ -1,26 +1,28 @@
 get:
   operationId: GetDraftOrders
   summary: List Draft Orders
-  description: Retrieves an list of Draft Orders
+  description: >-
+    Retrieve an list of Draft Orders. The draft orders can be filtered by fields
+    such as `q`. The draft orders can also paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: offset
-      description: The number of items to skip before the results.
+      description: The number of draft orders to skip when retrieving the draft orders.
       schema:
         type: number
         default: '0'
     - in: query
       name: limit
-      description: Limit the number of items returned.
+      description: Limit the number of draft orders returned.
       schema:
         type: number
         default: '50'
     - in: query
       name: q
       description: >-
-        a search term to search emails in carts associated with draft orders and
-        display IDs of draft orders
+        a term to search draft orders' display IDs and emails in the draft
+        order's cart
       schema:
         type: string
   x-codegen:
@@ -62,7 +64,9 @@ get:
 post:
   operationId: PostDraftOrders
   summary: Create a Draft Order
-  description: Creates a Draft Order
+  description: >-
+    Create a Draft Order. A draft order is not transformed into an order until
+    payment is captured.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_draft-orders_{id}.yaml b/docs/api/admin/paths/admin_draft-orders_{id}.yaml
index 4bc5310a67..d42f8ec756 100644
--- a/docs/api/admin/paths/admin_draft-orders_{id}.yaml
+++ b/docs/api/admin/paths/admin_draft-orders_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetDraftOrdersDraftOrder
   summary: Get a Draft Order
-  description: Retrieves a Draft Order.
+  description: Retrieve a Draft Order's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,7 +48,7 @@ get:
 post:
   operationId: PostDraftOrdersDraftOrder
   summary: Update a Draft Order
-  description: Updates a Draft Order.
+  description: Update a Draft Order's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -100,7 +100,7 @@ post:
 delete:
   operationId: DeleteDraftOrdersDraftOrder
   summary: Delete a Draft Order
-  description: Deletes a Draft Order
+  description: Delete a Draft Order
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_draft-orders_{id}_line-items.yaml b/docs/api/admin/paths/admin_draft-orders_{id}_line-items.yaml
index 6326cea449..6c6eef29c3 100644
--- a/docs/api/admin/paths/admin_draft-orders_{id}_line-items.yaml
+++ b/docs/api/admin/paths/admin_draft-orders_{id}_line-items.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostDraftOrdersDraftOrderLineItems
   summary: Create a Line Item
-  description: Creates a Line Item for the Draft Order
+  description: Create a Line Item in the Draft Order.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_draft-orders_{id}_line-items_{line_id}.yaml b/docs/api/admin/paths/admin_draft-orders_{id}_line-items_{line_id}.yaml
index 03b48621dc..3fd8e3684b 100644
--- a/docs/api/admin/paths/admin_draft-orders_{id}_line-items_{line_id}.yaml
+++ b/docs/api/admin/paths/admin_draft-orders_{id}_line-items_{line_id}.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostDraftOrdersDraftOrderLineItemsItem
   summary: Update a Line Item
-  description: Updates a Line Item for a Draft Order
+  description: Update a Line Item in a Draft Order
   x-authenticated: true
   parameters:
     - in: path
@@ -62,7 +62,7 @@ post:
 delete:
   operationId: DeleteDraftOrdersDraftOrderLineItemsItem
   summary: Delete a Line Item
-  description: Removes a Line Item from a Draft Order.
+  description: Deletes a Line Item from a Draft Order.
   x-authenticated: true
   parameters:
     - in: path
@@ -74,7 +74,7 @@ delete:
     - in: path
       name: line_id
       required: true
-      description: The ID of the Draft Order.
+      description: The ID of the line item.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_draft-orders_{id}_pay.yaml b/docs/api/admin/paths/admin_draft-orders_{id}_pay.yaml
index bb304bca88..7ffc68e711 100644
--- a/docs/api/admin/paths/admin_draft-orders_{id}_pay.yaml
+++ b/docs/api/admin/paths/admin_draft-orders_{id}_pay.yaml
@@ -1,13 +1,18 @@
 post:
-  summary: Registers a Payment
+  summary: Mark Paid
   operationId: PostDraftOrdersDraftOrderRegisterPayment
-  description: Registers a payment for a Draft Order.
+  description: >-
+    Capture the draft order's payment. This will also set the draft order's
+    status to `completed` and create an Order from the draft order. The payment
+    is captured through Medusa's system payment, which is manual payment that
+    isn't integrated with any third-party payment provider. It is assumed that
+    the payment capturing is handled manually by the admin.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The Draft Order id.
+      description: The Draft Order ID.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_gift-cards.yaml b/docs/api/admin/paths/admin_gift-cards.yaml
index df93612ff0..5091e4004e 100644
--- a/docs/api/admin/paths/admin_gift-cards.yaml
+++ b/docs/api/admin/paths/admin_gift-cards.yaml
@@ -1,24 +1,26 @@
 get:
   operationId: GetGiftCards
   summary: List Gift Cards
-  description: Retrieves a list of Gift Cards.
+  description: >-
+    Retrieve a list of Gift Cards. The gift cards can be filtered by fields such
+    as `q`. The gift cards can also paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: offset
-      description: The number of items to skip before the results.
+      description: The number of gift cards to skip when retrieving the gift cards.
       schema:
         type: number
         default: '0'
     - in: query
       name: limit
-      description: Limit the number of items returned.
+      description: Limit the number of gift cards returned.
       schema:
         type: number
         default: '50'
     - in: query
       name: q
-      description: a search term to search by code or display ID
+      description: a term to search gift cards' code or display ID
       schema:
         type: string
   x-codegen:
@@ -61,7 +63,7 @@ post:
   operationId: PostGiftCards
   summary: Create a Gift Card
   description: >-
-    Creates a Gift Card that can redeemed by its unique code. The Gift Card is
+    Create a Gift Card that can redeemed by its unique code. The Gift Card is
     only valid within 1 region.
   x-authenticated: true
   requestBody:
diff --git a/docs/api/admin/paths/admin_gift-cards_{id}.yaml b/docs/api/admin/paths/admin_gift-cards_{id}.yaml
index 816439bed2..ac304aed29 100644
--- a/docs/api/admin/paths/admin_gift-cards_{id}.yaml
+++ b/docs/api/admin/paths/admin_gift-cards_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetGiftCardsGiftCard
   summary: Get a Gift Card
-  description: Retrieves a Gift Card.
+  description: Retrieve a Gift Card's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,9 +48,7 @@ get:
 post:
   operationId: PostGiftCardsGiftCard
   summary: Update a Gift Card
-  description: >-
-    Update a Gift Card that can redeemed by its unique code. The Gift Card is
-    only valid within 1 region.
+  description: Update a Gift Card's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -102,7 +100,7 @@ post:
 delete:
   operationId: DeleteGiftCardsGiftCard
   summary: Delete a Gift Card
-  description: Deletes a Gift Card
+  description: Delete a Gift Card. Once deleted, it can't be used by customers.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_inventory-items.yaml b/docs/api/admin/paths/admin_inventory-items.yaml
index 94da2a29a8..248c3cc281 100644
--- a/docs/api/admin/paths/admin_inventory-items.yaml
+++ b/docs/api/admin/paths/admin_inventory-items.yaml
@@ -2,13 +2,16 @@ get:
   operationId: GetInventoryItems
   summary: List Inventory Items
   description: >-
-    Lists inventory items with the ability to apply filters or search queries on
-    them.
+    Retrieve a list of inventory items. The inventory items can be filtered by
+    fields such as `q` or `location_id`. The inventory items can also be
+    paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: offset
-      description: How many inventory items to skip in the result.
+      description: >-
+        The number of inventory items to skip when retrieving the inventory
+        items.
       schema:
         type: integer
         default: 0
@@ -20,81 +23,93 @@ get:
         default: 20
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in each returned
+        inventory item.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned inventory
+        item.
       schema:
         type: string
     - in: query
       name: q
-      description: Query used for searching product inventory items and their properties.
+      description: term to search inventory item's sku, title, and description.
       schema:
         type: string
     - in: query
       name: location_id
       style: form
       explode: false
-      description: Locations ids to search for.
+      description: Filter by location IDs.
       schema:
         type: array
         items:
           type: string
     - in: query
       name: id
-      description: id to search for.
+      style: form
+      explode: false
+      description: Filter by the inventory ID
       schema:
-        type: string
+        oneOf:
+          - type: string
+            description: inventory ID
+          - type: array
+            description: an array of inventory IDs
+            items:
+              type: string
     - in: query
       name: sku
-      description: sku to search for.
+      description: Filter by SKU
       schema:
         type: string
     - in: query
       name: origin_country
-      description: origin_country to search for.
+      description: Filter by origin country
       schema:
         type: string
     - in: query
       name: mid_code
-      description: mid_code to search for.
+      description: Filter by MID code
       schema:
         type: string
     - in: query
       name: material
-      description: material to search for.
+      description: Filter by material
       schema:
         type: string
     - in: query
       name: hs_code
-      description: hs_code to search for.
+      description: Filter by HS Code
       schema:
         type: string
     - in: query
       name: weight
-      description: weight to search for.
+      description: Filter by weight
       schema:
         type: string
     - in: query
       name: length
-      description: length to search for.
+      description: Filter by length
       schema:
         type: string
     - in: query
       name: height
-      description: height to search for.
+      description: Filter by height
       schema:
         type: string
     - in: query
       name: width
-      description: width to search for.
+      description: Filter by width
       schema:
         type: string
     - in: query
       name: requires_shipping
-      description: requires_shipping to search for.
+      description: Filter by whether the item requires shipping
       schema:
         type: string
   x-codegen:
@@ -137,17 +152,21 @@ get:
 post:
   operationId: PostInventoryItems
   summary: Create an Inventory Item
-  description: Creates an Inventory Item.
+  description: Create an Inventory Item.
   x-authenticated: true
   parameters:
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        inventory item.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned inventory
+        item.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_inventory-items_{id}.yaml b/docs/api/admin/paths/admin_inventory-items_{id}.yaml
index 0834e0bbcc..904da2a89c 100644
--- a/docs/api/admin/paths/admin_inventory-items_{id}.yaml
+++ b/docs/api/admin/paths/admin_inventory-items_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetInventoryItemsInventoryItem
   summary: Get an Inventory Item
-  description: Retrieves an Inventory Item.
+  description: Retrieve an Inventory Item's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +12,16 @@ get:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        inventory item.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned inventory
+        item.
       schema:
         type: string
   x-codegen:
@@ -59,7 +63,7 @@ get:
 post:
   operationId: PostInventoryItemsInventoryItem
   summary: Update an Inventory Item
-  description: Updates an Inventory Item.
+  description: Update an Inventory Item's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -70,12 +74,16 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        inventory level.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned inventory
+        level.
       schema:
         type: string
   requestBody:
@@ -122,7 +130,9 @@ post:
 delete:
   operationId: DeleteInventoryItemsInventoryItem
   summary: Delete an Inventory Item
-  description: Delete an Inventory Item
+  description: >-
+    Delete an Inventory Item. This does not delete the associated product
+    variant.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_inventory-items_{id}_location-levels.yaml b/docs/api/admin/paths/admin_inventory-items_{id}_location-levels.yaml
index a1d9035735..9ebfe0e7a9 100644
--- a/docs/api/admin/paths/admin_inventory-items_{id}_location-levels.yaml
+++ b/docs/api/admin/paths/admin_inventory-items_{id}_location-levels.yaml
@@ -1,32 +1,39 @@
 get:
   operationId: GetInventoryItemsInventoryItemLocationLevels
-  summary: List Inventory Levels
-  description: Lists inventory levels of an inventory item.
+  summary: List Inventory Level
+  description: >-
+    Retrieve a list of inventory levels of an inventory item. The inventory
+    levels can be filtered by fields such as `location_id`. The inventory levels
+    can also be paginated.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Inventory Item.
+      description: The ID of the Inventory Item the locations are associated with.
       schema:
         type: string
     - in: query
       name: location_id
       style: form
       explode: false
-      description: Locations ids to search for.
+      description: Filter by location IDs.
       schema:
         type: array
         items:
           type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        inventory levels.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned inventory
+        levels.
       schema:
         type: string
   x-codegen:
@@ -70,7 +77,7 @@ get:
 post:
   operationId: PostInventoryItemsInventoryItemLocationLevels
   summary: Create an Inventory Level
-  description: Creates an Inventory Level for a given Inventory Item.
+  description: Create an Inventory Level for a given Inventory Item.
   x-authenticated: true
   parameters:
     - in: path
@@ -81,12 +88,16 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        inventory item.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned inventory
+        item.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_inventory-items_{id}_location-levels_{location_id}.yaml b/docs/api/admin/paths/admin_inventory-items_{id}_location-levels_{location_id}.yaml
index 398f68a2f6..574851d817 100644
--- a/docs/api/admin/paths/admin_inventory-items_{id}_location-levels_{location_id}.yaml
+++ b/docs/api/admin/paths/admin_inventory-items_{id}_location-levels_{location_id}.yaml
@@ -1,29 +1,33 @@
 post:
   operationId: PostInventoryItemsInventoryItemLocationLevelsLocationLevel
   summary: Update an Inventory Level
-  description: Updates an Inventory Level for a given Inventory Item.
+  description: Update an Inventory Level's details for a given Inventory Item.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Inventory Item.
+      description: The ID of the Inventory Item that the location is associated with.
       schema:
         type: string
     - in: path
       name: location_id
       required: true
-      description: The ID of the Location.
+      description: The ID of the Location to update.
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        inventory level.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned inventory
+        level.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_invites.yaml b/docs/api/admin/paths/admin_invites.yaml
index 2c1ae42dc4..e7770d4411 100644
--- a/docs/api/admin/paths/admin_invites.yaml
+++ b/docs/api/admin/paths/admin_invites.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetInvites
   summary: Lists Invites
-  description: Lists all Invites
+  description: Retrieve a list of invites.
   x-authenticated: true
   x-codegen:
     method: list
@@ -41,7 +41,11 @@ get:
 post:
   operationId: PostInvites
   summary: Create an Invite
-  description: Creates an Invite and triggers an 'invite' created event
+  description: >-
+    Create an Invite. This will generate a token associated with the invite and
+    trigger an `invite.created` event. If you have a Notification Provider
+    installed that handles this event, a notification should be sent to the
+    email associated with the invite to allow them to accept the invite.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_invites_accept.yaml b/docs/api/admin/paths/admin_invites_accept.yaml
index 1341e11ea5..71ea11e0bd 100644
--- a/docs/api/admin/paths/admin_invites_accept.yaml
+++ b/docs/api/admin/paths/admin_invites_accept.yaml
@@ -1,7 +1,11 @@
 post:
   operationId: PostInvitesInviteAccept
   summary: Accept an Invite
-  description: Accepts an Invite and creates a corresponding user
+  description: >-
+    Accept an Invite. This will also delete the invite and create a new user
+    that can log in and perform admin functionalities. The user will have the
+    email associated with the invite, and the password provided in the request
+    body.
   requestBody:
     content:
       application/json:
diff --git a/docs/api/admin/paths/admin_invites_{invite_id}.yaml b/docs/api/admin/paths/admin_invites_{invite_id}.yaml
index 29af360dce..fa6e7d239c 100644
--- a/docs/api/admin/paths/admin_invites_{invite_id}.yaml
+++ b/docs/api/admin/paths/admin_invites_{invite_id}.yaml
@@ -1,7 +1,7 @@
 delete:
   operationId: DeleteInvitesInvite
   summary: Delete an Invite
-  description: Deletes an Invite
+  description: Delete an Invite. Only invites that weren't accepted can be deleted.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_invites_{invite_id}_resend.yaml b/docs/api/admin/paths/admin_invites_{invite_id}_resend.yaml
index d482c36dbc..b8c06a932e 100644
--- a/docs/api/admin/paths/admin_invites_{invite_id}_resend.yaml
+++ b/docs/api/admin/paths/admin_invites_{invite_id}_resend.yaml
@@ -1,7 +1,12 @@
 post:
   operationId: PostInvitesInviteResend
   summary: Resend an Invite
-  description: Resends an Invite by triggering the 'invite' created event again
+  description: >-
+    Resend an Invite. This renews the expiry date by 7 days and generates a new
+    token for the invite. It also triggers the `invite.created` event, so if you
+    have a Notification Provider installed that handles this event, a
+    notification should be sent to the email associated with the invite to allow
+    them to accept the invite.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_notes.yaml b/docs/api/admin/paths/admin_notes.yaml
index fa32ccac98..536b6db8c0 100644
--- a/docs/api/admin/paths/admin_notes.yaml
+++ b/docs/api/admin/paths/admin_notes.yaml
@@ -2,23 +2,25 @@ get:
   operationId: GetNotes
   summary: List Notes
   x-authenticated: true
-  description: Retrieves a list of notes
+  description: >-
+    Retrieve a list of notes. The notes can be filtered by fields such as
+    `resource_id`. The notes can also be paginated.
   parameters:
     - in: query
       name: limit
-      description: The number of notes to get
+      description: Limit the number of notes returned.
       schema:
         type: number
         default: '50'
     - in: query
       name: offset
-      description: The offset at which to get notes
+      description: The number of notes to skip when retrieving the notes.
       schema:
         type: number
         default: '0'
     - in: query
       name: resource_id
-      description: The ID which the notes belongs to
+      description: Filter by resource ID
       schema:
         type: string
   x-codegen:
@@ -59,8 +61,8 @@ get:
       $ref: ../components/responses/500_error.yaml
 post:
   operationId: PostNotes
-  summary: Creates a Note
-  description: Creates a Note which can be associated with any resource as required.
+  summary: Create a Note
+  description: Create a Note which can be associated with any resource.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_notes_{id}.yaml b/docs/api/admin/paths/admin_notes_{id}.yaml
index 00e5c73ae0..5a7398a9d8 100644
--- a/docs/api/admin/paths/admin_notes_{id}.yaml
+++ b/docs/api/admin/paths/admin_notes_{id}.yaml
@@ -1,13 +1,13 @@
 get:
   operationId: GetNotesNote
   summary: Get a Note
-  description: Retrieves a single note using its id
+  description: Retrieve a note's details.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the note to retrieve.
+      description: The ID of the note.
       schema:
         type: string
   x-codegen:
@@ -49,12 +49,12 @@ post:
   operationId: PostNotesNote
   summary: Update a Note
   x-authenticated: true
-  description: Updates a Note associated with some resource
+  description: Update a Note's details.'
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Note to update
+      description: The ID of the Note
       schema:
         type: string
   requestBody:
@@ -100,7 +100,7 @@ post:
 delete:
   operationId: DeleteNotesNote
   summary: Delete a Note
-  description: Deletes a Note.
+  description: Delete a Note.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_notifications.yaml b/docs/api/admin/paths/admin_notifications.yaml
index 583b68cfab..a5161ff49d 100644
--- a/docs/api/admin/paths/admin_notifications.yaml
+++ b/docs/api/admin/paths/admin_notifications.yaml
@@ -1,53 +1,63 @@
 get:
   operationId: GetNotifications
   summary: List Notifications
-  description: Retrieves a list of Notifications.
+  description: >-
+    Retrieve a list of notifications. The notifications can be filtered by
+    fields such as `event_name` or `resource_type`. The notifications can also
+    be paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: offset
       description: >-
-        The number of notifications to skip before starting to collect the
-        notifications set
+        The number of inventory items to skip when retrieving the inventory
+        items.
       schema:
         type: integer
         default: 0
     - in: query
       name: limit
-      description: The number of notifications to return
+      description: Limit the number of notifications returned.
       schema:
         type: integer
         default: 50
     - in: query
       name: fields
-      description: Comma separated fields to include in the result set
+      description: >-
+        Comma-separated fields that should be included in each returned
+        notification.
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated fields to populate
+      description: >-
+        Comma-separated relations that should be expanded in each returned
+        notification.
       schema:
         type: string
     - in: query
       name: event_name
-      description: The name of the event that the notification was sent for.
+      description: >-
+        Filter by the name of the event that triggered sending this
+        notification.
       schema:
         type: string
     - in: query
       name: resource_type
-      description: The type of resource that the Notification refers to.
+      description: Filter by the resource type.
       schema:
         type: string
     - in: query
       name: resource_id
-      description: The ID of the resource that the Notification refers to.
+      description: Filter by the resource ID.
       schema:
         type: string
     - in: query
       name: to
       description: >-
-        The address that the Notification was sent to. This will usually be an
-        email address, but represent other addresses such as a chat bot user id
+        Filter by the address that the Notification was sent to. This will
+        usually be an email address, but it can also represent other addresses
+        such as a chat bot user id.
       schema:
         type: string
     - in: query
diff --git a/docs/api/admin/paths/admin_notifications_{id}_resend.yaml b/docs/api/admin/paths/admin_notifications_{id}_resend.yaml
index c219aa7024..1e376e1a9f 100644
--- a/docs/api/admin/paths/admin_notifications_{id}_resend.yaml
+++ b/docs/api/admin/paths/admin_notifications_{id}_resend.yaml
@@ -2,8 +2,8 @@ post:
   operationId: PostNotificationsNotificationResend
   summary: Resend Notification
   description: >-
-    Resends a previously sent notifications, with the same data but optionally
-    to a different address
+    Resend a previously sent notifications, with the same data but optionally to
+    a different address.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_order-edits.yaml b/docs/api/admin/paths/admin_order-edits.yaml
index 6468d3b538..a6f13d384d 100644
--- a/docs/api/admin/paths/admin_order-edits.yaml
+++ b/docs/api/admin/paths/admin_order-edits.yaml
@@ -1,39 +1,45 @@
 get:
   operationId: GetOrderEdits
-  summary: List OrderEdits
-  description: List OrderEdits.
+  summary: List Order Edits
+  description: >-
+    Retrieve a list of order edits. The order edits can be filtered by fields
+    such as `q` or `order_id`. The order edits can also be paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: q
-      description: Query used for searching order edit internal note.
+      description: term to search order edits' internal note.
       schema:
         type: string
     - in: query
       name: order_id
-      description: List order edits by order id.
+      description: Filter by order ID
       schema:
         type: string
     - in: query
       name: limit
-      description: The number of items in the response
+      description: Limit the number of order edits returned.
       schema:
         type: number
         default: '20'
     - in: query
       name: offset
-      description: The offset of items in response
+      description: The number of order edits to skip when retrieving the order edits.
       schema:
         type: number
         default: '0'
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in each returned order
+        edit.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in each returned order
+        edit.
       schema:
         type: string
   x-codegen:
@@ -75,7 +81,7 @@ get:
 post:
   operationId: PostOrderEdits
   summary: Create an OrderEdit
-  description: Creates an OrderEdit.
+  description: Create an Order Edit.
   requestBody:
     content:
       application/json:
diff --git a/docs/api/admin/paths/admin_order-edits_{id}.yaml b/docs/api/admin/paths/admin_order-edits_{id}.yaml
index babe0b977d..5ca8b9ff1e 100644
--- a/docs/api/admin/paths/admin_order-edits_{id}.yaml
+++ b/docs/api/admin/paths/admin_order-edits_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetOrderEditsOrderEdit
-  summary: Get an OrderEdit
-  description: Retrieves a OrderEdit.
+  summary: Get an Order Edit
+  description: Retrieve an Order Edit's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +12,16 @@ get:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in each returned order
+        edit.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned order
+        edit.
       schema:
         type: string
   x-codegen:
@@ -58,8 +62,8 @@ get:
       $ref: ../components/responses/500_error.yaml
 post:
   operationId: PostOrderEditsOrderEdit
-  summary: Update an OrderEdit
-  description: Updates a OrderEdit.
+  summary: Update an Order Edit
+  description: Updates an Order Edit's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -111,7 +115,9 @@ post:
 delete:
   operationId: DeleteOrderEditsOrderEdit
   summary: Delete an Order Edit
-  description: Delete an Order Edit
+  description: >-
+    Delete an Order Edit. Only order edits that have the status `created` can be
+    deleted.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_order-edits_{id}_cancel.yaml b/docs/api/admin/paths/admin_order-edits_{id}_cancel.yaml
index c96aa11406..e0acd7fe3e 100644
--- a/docs/api/admin/paths/admin_order-edits_{id}_cancel.yaml
+++ b/docs/api/admin/paths/admin_order-edits_{id}_cancel.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostOrderEditsOrderEditCancel
-  summary: Cancel an OrderEdit
-  description: Cancels an OrderEdit.
+  summary: Cancel an Order Edit
+  description: Cancel an OrderEdit.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_order-edits_{id}_changes_{change_id}.yaml b/docs/api/admin/paths/admin_order-edits_{id}_changes_{change_id}.yaml
index 1d12d2f785..a6bae3cd17 100644
--- a/docs/api/admin/paths/admin_order-edits_{id}_changes_{change_id}.yaml
+++ b/docs/api/admin/paths/admin_order-edits_{id}_changes_{change_id}.yaml
@@ -1,19 +1,21 @@
 delete:
   operationId: DeleteOrderEditsOrderEditItemChange
   summary: Delete a Line Item Change
-  description: Deletes an Order Edit Item Change
+  description: >-
+    Delete a line item change that indicates the addition, deletion, or update
+    of a line item in the original order.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order Edit to delete.
+      description: The ID of the Order Edit.
       schema:
         type: string
     - in: path
       name: change_id
       required: true
-      description: The ID of the Order Edit Item Change to delete.
+      description: The ID of the Line Item Change to delete.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_order-edits_{id}_confirm.yaml b/docs/api/admin/paths/admin_order-edits_{id}_confirm.yaml
index 712c203243..d1ed5e58da 100644
--- a/docs/api/admin/paths/admin_order-edits_{id}_confirm.yaml
+++ b/docs/api/admin/paths/admin_order-edits_{id}_confirm.yaml
@@ -1,7 +1,9 @@
 post:
   operationId: PostOrderEditsOrderEditConfirm
-  summary: Confirms an OrderEdit
-  description: Confirms an OrderEdit.
+  summary: Confirm an OrderEdit
+  description: >-
+    Confirm an Order Edit. This will reflect the changes in the order edit on
+    the associated order.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_order-edits_{id}_items.yaml b/docs/api/admin/paths/admin_order-edits_{id}_items.yaml
index 315462160a..9e4bba70dc 100644
--- a/docs/api/admin/paths/admin_order-edits_{id}_items.yaml
+++ b/docs/api/admin/paths/admin_order-edits_{id}_items.yaml
@@ -1,7 +1,10 @@
 post:
   operationId: PostOrderEditsEditLineItems
   summary: Add a Line Item
-  description: Create an OrderEdit LineItem.
+  description: >-
+    Create a line item change in the order edit that indicates adding an item in
+    the original order. The item will not be added to the original order until
+    the order edit is confirmed.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/admin/paths/admin_order-edits_{id}_items_{item_id}.yaml b/docs/api/admin/paths/admin_order-edits_{id}_items_{item_id}.yaml
index 1c42d69dba..3c60e51f50 100644
--- a/docs/api/admin/paths/admin_order-edits_{id}_items_{item_id}.yaml
+++ b/docs/api/admin/paths/admin_order-edits_{id}_items_{item_id}.yaml
@@ -1,19 +1,23 @@
 post:
   operationId: PostOrderEditsEditLineItemsLineItem
   summary: Upsert Line Item Change
-  description: Create or update the order edit change holding the line item changes
+  description: >-
+    Create or update a line item change in the order edit that indicates
+    addition, deletion, or update of a line item into an original order. Line
+    item changes are only reflected on the original order after the order edit
+    is confirmed.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order Edit to update.
+      description: The ID of the Order Edit.
       schema:
         type: string
     - in: path
       name: item_id
       required: true
-      description: The ID of the order edit item to update.
+      description: The ID of the line item in the original order.
       schema:
         type: string
   requestBody:
@@ -60,20 +64,23 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteOrderEditsOrderEditLineItemsLineItem
-  summary: Delete a Line Item
-  description: Delete line items from an order edit and create change item
+  summary: Delete Line Item
+  description: >-
+    Create a line item change in the order edit that indicates deleting an item
+    in the original order. The item in the original order will not be deleted
+    until the order edit is confirmed.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order Edit to delete from.
+      description: The ID of the Order Edit.
       schema:
         type: string
     - in: path
       name: item_id
       required: true
-      description: The ID of the order edit item to delete from order.
+      description: The ID of line item in the original order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_order-edits_{id}_request.yaml b/docs/api/admin/paths/admin_order-edits_{id}_request.yaml
index e2d1cf87a1..ecd86c114b 100644
--- a/docs/api/admin/paths/admin_order-edits_{id}_request.yaml
+++ b/docs/api/admin/paths/admin_order-edits_{id}_request.yaml
@@ -1,13 +1,16 @@
 post:
   operationId: PostOrderEditsOrderEditRequest
   summary: Request Confirmation
-  description: Request customer confirmation of an Order Edit
+  description: >-
+    Request customer confirmation of an Order Edit. This would emit the event
+    `order-edit.requested` which Notification Providers listen to and send a
+    notification to the customer about the order edit.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order Edit to request confirmation from.
+      description: The ID of the Order Edit.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders.yaml b/docs/api/admin/paths/admin_orders.yaml
index 7684574ecf..0aace9b7e5 100644
--- a/docs/api/admin/paths/admin_orders.yaml
+++ b/docs/api/admin/paths/admin_orders.yaml
@@ -1,26 +1,28 @@
 get:
   operationId: GetOrders
   summary: List Orders
-  description: Retrieves a list of Orders
+  description: >-
+    Retrieve a list of Orders. The orders can be filtered by fields such as
+    `status` or `display_id`. The order can also be paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: q
       description: >-
-        Query used for searching orders by shipping address first name, orders'
-        email, and orders' display ID
+        term to search orders' shipping address, first name, email, and display
+        ID
       schema:
         type: string
     - in: query
       name: id
-      description: ID of the order to search for.
+      description: Filter by ID.
       schema:
         type: string
     - in: query
       name: status
       style: form
       explode: false
-      description: Status to search for
+      description: Filter by status
       schema:
         type: array
         items:
@@ -35,7 +37,7 @@ get:
       name: fulfillment_status
       style: form
       explode: false
-      description: Fulfillment status to search for.
+      description: Filter by fulfillment status
       schema:
         type: array
         items:
@@ -54,7 +56,7 @@ get:
       name: payment_status
       style: form
       explode: false
-      description: Payment status to search for.
+      description: Filter by payment status
       schema:
         type: array
         items:
@@ -69,29 +71,29 @@ get:
             - requires_action
     - in: query
       name: display_id
-      description: Display ID to search for.
+      description: Filter by display ID
       schema:
         type: string
     - in: query
       name: cart_id
-      description: to search for.
+      description: Filter by cart ID
       schema:
         type: string
     - in: query
       name: customer_id
-      description: to search for.
+      description: Filter by customer ID
       schema:
         type: string
     - in: query
       name: email
-      description: to search for.
+      description: Filter by email
       schema:
         type: string
     - in: query
       name: region_id
       style: form
       explode: false
-      description: Regions to search orders by
+      description: Filter by region IDs.
       schema:
         oneOf:
           - type: string
@@ -104,7 +106,7 @@ get:
       name: currency_code
       style: form
       explode: false
-      description: Currency code to search for
+      description: Filter by currency codes.
       schema:
         type: string
         externalDocs:
@@ -112,12 +114,12 @@ get:
           description: See a list of codes.
     - in: query
       name: tax_rate
-      description: to search for.
+      description: Filter by tax rate.
       schema:
         type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting orders were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -139,7 +141,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting orders were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -161,7 +163,7 @@ get:
             format: date
     - in: query
       name: canceled_at
-      description: Date comparison for when resulting orders were canceled.
+      description: Filter by a cancelation date range.
       schema:
         type: object
         properties:
@@ -185,7 +187,7 @@ get:
       name: sales_channel_id
       style: form
       explode: false
-      description: Filter by Sales Channels
+      description: Filter by Sales Channel IDs
       schema:
         type: array
         items:
@@ -193,7 +195,7 @@ get:
           description: The ID of a Sales Channel
     - in: query
       name: offset
-      description: How many orders to skip before the results.
+      description: The number of orders to skip when retrieving the orders.
       schema:
         type: integer
         default: 0
@@ -205,16 +207,12 @@ get:
         default: 50
     - in: query
       name: expand
-      description: >-
-        (Comma separated) Which fields should be expanded in each order of the
-        result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: >-
-        (Comma separated) Which fields should be included in each order of the
-        result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}.yaml b/docs/api/admin/paths/admin_orders_{id}.yaml
index 332fca38cd..03b436814c 100644
--- a/docs/api/admin/paths/admin_orders_{id}.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetOrdersOrder
   summary: Get an Order
-  description: Retrieves an Order
+  description: Retrieve an Order's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +12,12 @@ get:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
@@ -59,7 +59,7 @@ get:
 post:
   operationId: PostOrdersOrder
   summary: Update an Order
-  description: Updates and order
+  description: Update and order's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -70,12 +70,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_archive.yaml b/docs/api/admin/paths/admin_orders_{id}_archive.yaml
index 7d1a27ae62..ebfe719d73 100644
--- a/docs/api/admin/paths/admin_orders_{id}_archive.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_archive.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostOrdersOrderArchive
   summary: Archive Order
-  description: Archives the order with the given id.
+  description: Archive an order and change its status.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +12,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_cancel.yaml b/docs/api/admin/paths/admin_orders_{id}_cancel.yaml
index aa327c0ad9..0c447e2d02 100644
--- a/docs/api/admin/paths/admin_orders_{id}_cancel.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_cancel.yaml
@@ -2,8 +2,8 @@ post:
   operationId: PostOrdersOrderCancel
   summary: Cancel an Order
   description: >-
-    Registers an Order as canceled. This triggers a flow that will cancel any
-    created Fulfillments and Payments, may fail if the Payment or Fulfillment
+    Cancel an order and change its status. This will also cancel any associated
+    Fulfillments and Payments, and it may fail if the Payment or Fulfillment
     Provider is unable to cancel the Payment/Fulfillment.
   x-authenticated: true
   parameters:
@@ -15,12 +15,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_capture.yaml b/docs/api/admin/paths/admin_orders_{id}_capture.yaml
index ff87be29a0..827318a50f 100644
--- a/docs/api/admin/paths/admin_orders_{id}_capture.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_capture.yaml
@@ -1,7 +1,9 @@
 post:
   operationId: PostOrdersOrderCapture
-  summary: Capture Order's Payment
-  description: Captures all the Payments associated with an Order.
+  summary: Capture an Order's Payments
+  description: >-
+    Capture all the Payments associated with an Order. The payment of canceled
+    orders can't be captured.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +14,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_claims.yaml b/docs/api/admin/paths/admin_orders_{id}_claims.yaml
index 29f9c96132..84af6ce4f4 100644
--- a/docs/api/admin/paths/admin_orders_{id}_claims.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_claims.yaml
@@ -1,7 +1,13 @@
 post:
   operationId: PostOrdersOrderClaims
   summary: Create a Claim
-  description: Creates a Claim.
+  description: >-
+    Create a Claim for an order. If a return shipping method is specified, a
+    return will also be created and associated with the claim. If the claim's
+    type is `refund`, the refund is processed as well.
+  externalDocs:
+    description: How are claims created
+    url: https://docs.medusajs.com/modules/orders/claims#how-are-claims-created
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +18,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}.yaml b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}.yaml
index bf90d5336e..e374971c87 100644
--- a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}.yaml
@@ -1,13 +1,13 @@
 post:
   operationId: PostOrdersOrderClaimsClaim
   summary: Update a Claim
-  description: Updates a Claim.
+  description: Update a Claim's details.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order.
+      description: The ID of the Order associated with the claim.
       schema:
         type: string
     - in: path
@@ -18,12 +18,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_cancel.yaml b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_cancel.yaml
index bdd9327b38..c7c7a529a3 100644
--- a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_cancel.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_cancel.yaml
@@ -1,13 +1,19 @@
 post:
   operationId: PostOrdersClaimCancel
   summary: Cancel a Claim
-  description: Cancels a Claim
+  description: >-
+    Cancel a Claim and change its status. A claim can't be canceled if it has a
+    refund, if its fulfillments haven't been canceled, of if its associated
+    return hasn't been canceled.
   x-authenticated: true
+  externalDocs:
+    description: Canceling a claim
+    url: https://docs.medusajs.com/modules/orders/claims#cancel-a-claim
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order.
+      description: The ID of the order the claim is associated with.
       schema:
         type: string
     - in: path
@@ -18,12 +24,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments.yaml b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments.yaml
index b759165741..3b9912c41e 100644
--- a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments.yaml
@@ -1,13 +1,16 @@
 post:
   operationId: PostOrdersOrderClaimsClaimFulfillments
-  summary: Create Claim Fulfillment
-  description: Creates a Fulfillment for a Claim.
+  summary: Create a Claim Fulfillment
+  description: Create a Fulfillment for a Claim.
   x-authenticated: true
+  externalDocs:
+    description: Fulfill a claim
+    url: https://docs.medusajs.com/modules/orders/claims#fulfill-a-claim
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order.
+      description: The ID of the Order the claim is associated with.
       schema:
         type: string
     - in: path
@@ -18,12 +21,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel.yaml b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel.yaml
index b15fba082b..2c5c669cbd 100644
--- a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel.yaml
@@ -1,35 +1,35 @@
 post:
   operationId: PostOrdersClaimFulfillmentsCancel
-  summary: Cancel Claim Fulfillment
-  description: Registers a claim's fulfillment as canceled.
+  summary: Cancel Claim's Fulfillment
+  description: Cancel a claim's fulfillment and change its status.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order which the Claim relates to.
+      description: The ID of the order the claim is associated with.
       schema:
         type: string
     - in: path
       name: claim_id
       required: true
-      description: The ID of the Claim which the Fulfillment relates to.
+      description: The ID of the claim.
       schema:
         type: string
     - in: path
       name: fulfillment_id
       required: true
-      description: The ID of the Fulfillment.
+      description: The ID of the fulfillment.
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_shipments.yaml b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_shipments.yaml
index 9f3414c595..bd96a0a74a 100644
--- a/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_shipments.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_claims_{claim_id}_shipments.yaml
@@ -1,13 +1,19 @@
 post:
   operationId: PostOrdersOrderClaimsClaimShipments
-  summary: Create Claim Shipment
-  description: Registers a Claim Fulfillment as shipped.
+  summary: Ship a Claim's Fulfillment
+  description: >-
+    Mark a claim's fulfillment as shipped. This changes the claim's fulfillment
+    status to either `shipped` or `partially_shipped`, depending on whether all
+    the items were shipped.
   x-authenticated: true
+  externalDocs:
+    description: Fulfill a claim
+    url: https://docs.medusajs.com/modules/orders/claims#fulfill-a-claim
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order.
+      description: The ID of the Order the claim is associated with.
       schema:
         type: string
     - in: path
@@ -18,12 +24,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_complete.yaml b/docs/api/admin/paths/admin_orders_{id}_complete.yaml
index 05cf138228..7d4e136285 100644
--- a/docs/api/admin/paths/admin_orders_{id}_complete.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_complete.yaml
@@ -1,7 +1,9 @@
 post:
   operationId: PostOrdersOrderComplete
   summary: Complete an Order
-  description: Completes an Order
+  description: >-
+    Complete an Order and change its status. A canceled order can't be
+    completed.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +14,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_fulfillment.yaml b/docs/api/admin/paths/admin_orders_{id}_fulfillment.yaml
index cfe8f822d3..1d24767c63 100644
--- a/docs/api/admin/paths/admin_orders_{id}_fulfillment.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_fulfillment.yaml
@@ -1,10 +1,11 @@
 post:
   operationId: PostOrdersOrderFulfillments
   summary: Create a Fulfillment
-  description: >-
-    Creates a Fulfillment of an Order - will notify Fulfillment Providers to
-    prepare a shipment.
+  description: Create a Fulfillment of an Order using the fulfillment provider.
   x-authenticated: true
+  externalDocs:
+    description: Fulfillments of orders
+    url: https://docs.medusajs.com/modules/orders/#fulfillments-in-orders
   parameters:
     - in: path
       name: id
@@ -14,12 +15,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel.yaml b/docs/api/admin/paths/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel.yaml
index f4dad676ea..cc7d296278 100644
--- a/docs/api/admin/paths/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel.yaml
@@ -1,29 +1,29 @@
 post:
   operationId: PostOrdersOrderFulfillmentsCancel
-  summary: Cancels a Fulfilmment
-  description: Registers a Fulfillment as canceled.
+  summary: Cancel a Fulfilmment
+  description: Cancel an order's fulfillment and change its status.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order which the Fulfillment relates to.
+      description: The ID of the Order.
       schema:
         type: string
     - in: path
       name: fulfillment_id
       required: true
-      description: The ID of the Fulfillment
+      description: The ID of the Fulfillment.
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_line-items_{line_item_id}_reserve.yaml b/docs/api/admin/paths/admin_orders_{id}_line-items_{line_item_id}_reserve.yaml
index 62f4695009..6d6eb9f736 100644
--- a/docs/api/admin/paths/admin_orders_{id}_line-items_{line_item_id}_reserve.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_line-items_{line_item_id}_reserve.yaml
@@ -1,9 +1,9 @@
 post:
   operationId: PostOrdersOrderLineItemReservations
-  summary: Create a Reservation for a line item
+  summary: Create a Reservation
   description: >-
-    Creates a Reservation for a line item at a specified location, optionally
-    for a partial quantity.
+    Create a Reservation for a line item at a specified location, optionally for
+    a partial quantity.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_orders_{id}_refund.yaml b/docs/api/admin/paths/admin_orders_{id}_refund.yaml
index e7e8c9d5d2..11274c9bd0 100644
--- a/docs/api/admin/paths/admin_orders_{id}_refund.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_refund.yaml
@@ -1,7 +1,9 @@
 post:
   operationId: PostOrdersOrderRefunds
   summary: Create a Refund
-  description: Issues a Refund.
+  description: >-
+    Refund an amount for an order. The amount must be less than or equal the
+    `refundable_amount` of the order.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +14,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_reservations.yaml b/docs/api/admin/paths/admin_orders_{id}_reservations.yaml
index 697aaaa549..cb9ec00b54 100644
--- a/docs/api/admin/paths/admin_orders_{id}_reservations.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_reservations.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetOrdersOrderReservations
-  summary: Get reservations of an Order
-  description: Retrieves reservations of an Order
+  summary: Get Order Reservations
+  description: Retrieve the list of reservations of an Order
   x-authenticated: true
   parameters:
     - in: path
@@ -12,7 +12,7 @@ get:
         type: string
     - in: query
       name: offset
-      description: How many reservations to skip before the results.
+      description: The number of reservations to skip when retrieving the reservations.
       schema:
         type: integer
         default: 0
diff --git a/docs/api/admin/paths/admin_orders_{id}_return.yaml b/docs/api/admin/paths/admin_orders_{id}_return.yaml
index c7b4d0dd37..31f4c57b09 100644
--- a/docs/api/admin/paths/admin_orders_{id}_return.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_return.yaml
@@ -2,9 +2,12 @@ post:
   operationId: PostOrdersOrderReturns
   summary: Request a Return
   description: >-
-    Requests a Return. If applicable a return label will be created and other
-    plugins notified.
+    Request and create a Return for items in an order. If the return shipping
+    method is specified, it will be automatically fulfilled.
   x-authenticated: true
+  externalDocs:
+    description: Return creation process
+    url: https://docs.medusajs.com/modules/orders/returns#returns-process
   parameters:
     - in: path
       name: id
@@ -14,12 +17,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_shipment.yaml b/docs/api/admin/paths/admin_orders_{id}_shipment.yaml
index 7e1db41a59..06e9c13c59 100644
--- a/docs/api/admin/paths/admin_orders_{id}_shipment.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_shipment.yaml
@@ -1,8 +1,14 @@
 post:
   operationId: PostOrdersOrderShipment
-  summary: Create a Shipment
-  description: Registers a Fulfillment as shipped.
+  summary: Ship a Fulfillment
+  description: >-
+    Mark a fulfillment as shipped. This changes the order's fulfillment status
+    to either `shipped` or `partially_shipped`, depending on whether all the
+    items were shipped.
   x-authenticated: true
+  externalDocs:
+    description: Fulfillments of orders
+    url: https://docs.medusajs.com/modules/orders/#fulfillments-in-orders
   parameters:
     - in: path
       name: id
@@ -12,12 +18,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_shipping-methods.yaml b/docs/api/admin/paths/admin_orders_{id}_shipping-methods.yaml
index 20a6337d61..2757a955b8 100644
--- a/docs/api/admin/paths/admin_orders_{id}_shipping-methods.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_shipping-methods.yaml
@@ -13,12 +13,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_swaps.yaml b/docs/api/admin/paths/admin_orders_{id}_swaps.yaml
index 79228b7c95..014e790c49 100644
--- a/docs/api/admin/paths/admin_orders_{id}_swaps.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_swaps.yaml
@@ -2,9 +2,12 @@ post:
   operationId: PostOrdersOrderSwaps
   summary: Create a Swap
   description: >-
-    Creates a Swap. Swaps are used to handle Return of previously purchased
-    goods and Fulfillment of replacements simultaneously.
+    Create a Swap. This includes creating a return that is associated with the
+    swap.
   x-authenticated: true
+  externalDocs:
+    description: How are swaps created
+    url: https://docs.medusajs.com/modules/orders/swaps#how-are-swaps-created
   parameters:
     - in: path
       name: id
@@ -14,16 +17,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: >-
-        (Comma separated) Which fields should be expanded the order of the
-        result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: >-
-        (Comma separated) Which fields should be included the order of the
-        result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_cancel.yaml b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_cancel.yaml
index e757819c8e..44635ad4d9 100644
--- a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_cancel.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_cancel.yaml
@@ -1,13 +1,16 @@
 post:
   operationId: PostOrdersSwapCancel
-  summary: Cancels a Swap
-  description: Cancels a Swap
+  summary: Cancel a Swap
+  description: Cancel a Swap and change its status.
   x-authenticated: true
+  externalDocs:
+    description: Canceling a swap
+    url: https://docs.medusajs.com/modules/orders/swaps#canceling-a-swap
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order.
+      description: The ID of the Order the swap is associated with.
       schema:
         type: string
     - in: path
@@ -18,12 +21,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments.yaml b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments.yaml
index 71604f75da..79f275af25 100644
--- a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments.yaml
@@ -1,13 +1,16 @@
 post:
   operationId: PostOrdersOrderSwapsSwapFulfillments
-  summary: Create Swap Fulfillment
-  description: Creates a Fulfillment for a Swap.
+  summary: Create a Swap Fulfillment
+  description: Create a Fulfillment for a Swap.
   x-authenticated: true
+  externalDocs:
+    description: Handling a swap's fulfillment
+    url: https://docs.medusajs.com/modules/orders/swaps#handling-swap-fulfillment
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order.
+      description: The ID of the Order the swap is associated with.
       schema:
         type: string
     - in: path
@@ -18,12 +21,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel.yaml b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel.yaml
index 40505d55ec..5eb5048e4e 100644
--- a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel.yaml
@@ -1,35 +1,35 @@
 post:
   operationId: PostOrdersSwapFulfillmentsCancel
   summary: Cancel Swap's Fulfilmment
-  description: Registers a Swap's Fulfillment as canceled.
+  description: Cancel a swap's fulfillment and change its status.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order which the Swap relates to.
+      description: The ID of the order the swap is associated with.
       schema:
         type: string
     - in: path
       name: swap_id
       required: true
-      description: The ID of the Swap which the Fulfillment relates to.
+      description: The ID of the swap.
       schema:
         type: string
     - in: path
       name: fulfillment_id
       required: true
-      description: The ID of the Fulfillment.
+      description: The ID of the fulfillment.
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_process-payment.yaml b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_process-payment.yaml
index 9259fe9d9d..e20ff4e3be 100644
--- a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_process-payment.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_process-payment.yaml
@@ -1,32 +1,36 @@
 post:
   operationId: PostOrdersOrderSwapsSwapProcessPayment
-  summary: Process Swap Payment
+  summary: Process a Swap Payment
   description: >-
-    When there are differences between the returned and shipped Products in a
-    Swap, the difference must be processed. Either a Refund will be issued or a
-    Payment will be captured.
+    Process a swap's payment either by refunding or issuing a payment. This
+    depends on the `difference_due` of the swap. If `difference_due` is
+    negative, the amount is refunded. If `difference_due` is positive, the
+    amount is captured.
   x-authenticated: true
+  externalDocs:
+    description: Handling a swap's payment
+    url: https://docs.medusajs.com/modules/orders/swaps#handling-swap-payment
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Order.
+      description: The ID of the order the swap is associated with.
       schema:
         type: string
     - in: path
       name: swap_id
       required: true
-      description: The ID of the Swap.
+      description: The ID of the swap.
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_shipments.yaml b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_shipments.yaml
index 833e9402bd..05ca84c6c0 100644
--- a/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_shipments.yaml
+++ b/docs/api/admin/paths/admin_orders_{id}_swaps_{swap_id}_shipments.yaml
@@ -1,8 +1,14 @@
 post:
   operationId: PostOrdersOrderSwapsSwapShipments
-  summary: Create Swap Shipment
-  description: Registers a Swap Fulfillment as shipped.
+  summary: Ship a Swap's Fulfillment
+  description: >-
+    RMark a swap's fulfillment as shipped. This changes the swap's fulfillment
+    status to either `shipped` or `partially_shipped`, depending on whether all
+    the items were shipped.
   x-authenticated: true
+  externalDocs:
+    description: Handling swap fulfillments
+    url: https://docs.medusajs.com/modules/orders/swaps#handling-swap-fulfillment
   parameters:
     - in: path
       name: id
@@ -18,12 +24,12 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the result.
+      description: Comma-separated fields that should be included in the returned order.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_payment-collections_{id}.yaml b/docs/api/admin/paths/admin_payment-collections_{id}.yaml
index b6ea47c195..e3b6300f20 100644
--- a/docs/api/admin/paths/admin_payment-collections_{id}.yaml
+++ b/docs/api/admin/paths/admin_payment-collections_{id}.yaml
@@ -1,23 +1,27 @@
 get:
   operationId: GetPaymentCollectionsPaymentCollection
-  summary: Get a PaymentCollection
-  description: Retrieves a PaymentCollection.
+  summary: Get a Payment Collection
+  description: Retrieve a Payment Collection's details.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the PaymentCollection.
+      description: The ID of the Payment Collection.
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        payment collection.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned payment
+        collection.
       schema:
         type: string
   x-codegen:
@@ -58,14 +62,14 @@ get:
       $ref: ../components/responses/500_error.yaml
 post:
   operationId: PostPaymentCollectionsPaymentCollection
-  summary: Update PaymentCollection
-  description: Updates a PaymentCollection.
+  summary: Update Payment Collection
+  description: Update a Payment Collection's details.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the PaymentCollection.
+      description: The ID of the Payment Collection.
       schema:
         type: string
   requestBody:
@@ -110,14 +114,16 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeletePaymentCollectionsPaymentCollection
-  summary: Del a PaymentCollection
-  description: Deletes a Payment Collection
+  summary: Delete a Payment Collection
+  description: >-
+    Delete a Payment Collection. Only payment collections with the statuses
+    `canceled` or `not_paid` can be deleted.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Payment Collection to delete.
+      description: The ID of the Payment Collection.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_payment-collections_{id}_authorize.yaml b/docs/api/admin/paths/admin_payment-collections_{id}_authorize.yaml
index 1d7534f1e0..11e998146c 100644
--- a/docs/api/admin/paths/admin_payment-collections_{id}_authorize.yaml
+++ b/docs/api/admin/paths/admin_payment-collections_{id}_authorize.yaml
@@ -1,13 +1,15 @@
 post:
   operationId: PostPaymentCollectionsPaymentCollectionAuthorize
   summary: Mark Authorized
-  description: Sets the status of PaymentCollection as Authorized.
+  description: >-
+    Set the status of a Payment Collection as `authorized`. This will also
+    change the `authorized_amount` of the payment collection.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the PaymentCollection.
+      description: The ID of the Payment Collection.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_payments_{id}.yaml b/docs/api/admin/paths/admin_payments_{id}.yaml
index c746517ef1..d32e7856f3 100644
--- a/docs/api/admin/paths/admin_payments_{id}.yaml
+++ b/docs/api/admin/paths/admin_payments_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetPaymentsPayment
   summary: Get Payment details
-  description: Retrieves the Payment details
+  description: Retrieve a Payment's details.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_payments_{id}_capture.yaml b/docs/api/admin/paths/admin_payments_{id}_capture.yaml
index 13d67f1ce7..7ebd203805 100644
--- a/docs/api/admin/paths/admin_payments_{id}_capture.yaml
+++ b/docs/api/admin/paths/admin_payments_{id}_capture.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostPaymentsPaymentCapture
   summary: Capture a Payment
-  description: Captures a Payment.
+  description: Capture a Payment.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_payments_{id}_refund.yaml b/docs/api/admin/paths/admin_payments_{id}_refund.yaml
index 52ccbc14be..3ba43d2d33 100644
--- a/docs/api/admin/paths/admin_payments_{id}_refund.yaml
+++ b/docs/api/admin/paths/admin_payments_{id}_refund.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostPaymentsPaymentRefunds
-  summary: Create a Refund
-  description: Issues a Refund.
+  summary: Refund Payment
+  description: Refund a payment. The payment must be captured first.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_price-lists.yaml b/docs/api/admin/paths/admin_price-lists.yaml
index 0977730c13..12588b0d30 100644
--- a/docs/api/admin/paths/admin_price-lists.yaml
+++ b/docs/api/admin/paths/admin_price-lists.yaml
@@ -1,50 +1,59 @@
 get:
   operationId: GetPriceLists
   summary: List Price Lists
-  description: Retrieves a list of Price Lists.
+  description: >-
+    Retrieve a list of price lists. The price lists can be filtered by fields
+    such as `q` or `status`. The price lists can also be sorted or paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: limit
-      description: The number of items to get
+      description: Limit the number of price lists returned.
       schema:
         type: number
         default: '10'
     - in: query
       name: offset
-      description: The offset at which to get items
+      description: The number of price lists to skip when retrieving the price lists.
       schema:
         type: number
         default: '0'
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each item of the
-        result.
+        Comma-separated relations that should be expanded in the returned price
+        lists.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: >-
+        Comma-separated fields that should be included in the returned price
+        lists.
       schema:
         type: string
     - in: query
       name: order
-      description: field to order results by.
+      description: A price-list field to sort-order the retrieved price lists by.
       schema:
         type: string
     - in: query
       name: id
-      description: ID to search for.
+      description: Filter by ID
       schema:
         type: string
     - in: query
       name: q
       description: >-
-        query to search in price list description, price list name, and customer
-        group name fields.
+        term to search price lists' description, name, and customer group's
+        name.
       schema:
         type: string
     - in: query
       name: status
       style: form
       explode: false
-      description: Status to search for.
+      description: Filter by status.
       schema:
         type: array
         items:
@@ -54,14 +63,14 @@ get:
             - draft
     - in: query
       name: name
-      description: price list name to search for.
+      description: Filter by name
       schema:
         type: string
     - in: query
       name: customer_groups
       style: form
       explode: false
-      description: Customer Group IDs to search for.
+      description: Filter by customer-group IDs.
       schema:
         type: array
         items:
@@ -70,7 +79,7 @@ get:
       name: type
       style: form
       explode: false
-      description: Type to search for.
+      description: Filter by type.
       schema:
         type: array
         items:
@@ -80,7 +89,7 @@ get:
             - override
     - in: query
       name: created_at
-      description: Date comparison for when resulting price lists were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -102,7 +111,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting price lists were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -124,7 +133,7 @@ get:
             format: date
     - in: query
       name: deleted_at
-      description: Date comparison for when resulting price lists were deleted.
+      description: Filter by a deletion date range.
       schema:
         type: object
         properties:
@@ -183,7 +192,7 @@ get:
 post:
   operationId: PostPriceListsPriceList
   summary: Create a Price List
-  description: Creates a Price List
+  description: Create a Price List.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_price-lists_{id}.yaml b/docs/api/admin/paths/admin_price-lists_{id}.yaml
index b3b945aab9..6baff64df5 100644
--- a/docs/api/admin/paths/admin_price-lists_{id}.yaml
+++ b/docs/api/admin/paths/admin_price-lists_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetPriceListsPriceList
   summary: Get a Price List
-  description: Retrieves a Price List.
+  description: Retrieve a Price List's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,7 +48,7 @@ get:
 post:
   operationId: PostPriceListsPriceListPriceList
   summary: Update a Price List
-  description: Updates a Price List
+  description: Update a Price List's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -100,13 +100,13 @@ post:
 delete:
   operationId: DeletePriceListsPriceList
   summary: Delete a Price List
-  description: Deletes a Price List
+  description: Delete a Price List and its associated prices.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Price List to delete.
+      description: The ID of the Price List.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_price-lists_{id}_prices_batch.yaml b/docs/api/admin/paths/admin_price-lists_{id}_prices_batch.yaml
index f270584d8c..80b5b83053 100644
--- a/docs/api/admin/paths/admin_price-lists_{id}_prices_batch.yaml
+++ b/docs/api/admin/paths/admin_price-lists_{id}_prices_batch.yaml
@@ -1,13 +1,13 @@
 post:
   operationId: PostPriceListsPriceListPricesBatch
-  summary: Update Prices
-  description: Batch update prices for a Price List
+  summary: Add or Update Prices
+  description: Add or update a list of prices in a Price List
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Price List to update prices for.
+      description: The ID of the Price List.
       schema:
         type: string
   requestBody:
@@ -53,15 +53,13 @@ post:
 delete:
   operationId: DeletePriceListsPriceListPricesBatch
   summary: Delete Prices
-  description: Batch delete prices that belong to a Price List
+  description: Delete a list of prices in a Price List
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: >-
-        The ID of the Price List that the Money Amounts (Prices) that will be
-        deleted belongs to.
+      description: The ID of the Price List
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_price-lists_{id}_products.yaml b/docs/api/admin/paths/admin_price-lists_{id}_products.yaml
index 16455aaeb7..a96e92efe8 100644
--- a/docs/api/admin/paths/admin_price-lists_{id}_products.yaml
+++ b/docs/api/admin/paths/admin_price-lists_{id}_products.yaml
@@ -1,7 +1,9 @@
 get:
   operationId: GetPriceListsPriceListProducts
   summary: List Products
-  description: Retrieves a list of Product that are part of a Price List
+  description: >-
+    Retrieve a price list's products. The products can be filtered by fields
+    such as `q` or `status`. The products can also be sorted or paginated.
   x-authenticated: true
   parameters:
     - in: path
@@ -13,18 +15,18 @@ get:
     - in: query
       name: q
       description: >-
-        Query used for searching product title and description, variant title
-        and sku, and collection title.
+        term used to search products' title, description, product variant's
+        title and sku, and product collection's title.
       schema:
         type: string
     - in: query
       name: id
-      description: ID of the product to search for.
+      description: Filter by product ID
       schema:
         type: string
     - in: query
       name: status
-      description: Product status to search for
+      description: Filter by product status
       style: form
       explode: false
       schema:
@@ -38,7 +40,9 @@ get:
             - rejected
     - in: query
       name: collection_id
-      description: Collection IDs to search for
+      description: >-
+        Filter by product collection ID. Only products in the specified
+        collections are retrieved.
       style: form
       explode: false
       schema:
@@ -47,7 +51,9 @@ get:
           type: string
     - in: query
       name: tags
-      description: Tag IDs to search for
+      description: >-
+        Filter by tag IDs. Only products having the specified tags are
+        retrieved.
       style: form
       explode: false
       schema:
@@ -56,37 +62,37 @@ get:
           type: string
     - in: query
       name: title
-      description: product title to search for.
+      description: Filter by title
       schema:
         type: string
     - in: query
       name: description
-      description: product description to search for.
+      description: Filter by description
       schema:
         type: string
     - in: query
       name: handle
-      description: product handle to search for.
+      description: Filter by handle
       schema:
         type: string
     - in: query
       name: is_giftcard
-      description: Search for giftcards using is_giftcard=true.
+      description: A boolean value to filter by whether the product is a gift card or not.
       schema:
         type: string
     - in: query
       name: type
-      description: to search for.
+      description: Filter product type.
       schema:
         type: string
     - in: query
       name: order
-      description: field to sort results by.
+      description: A product field to sort-order the retrieved products by.
       schema:
         type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting products were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -108,7 +114,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting products were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -130,7 +136,7 @@ get:
             format: date
     - in: query
       name: deleted_at
-      description: Date comparison for when resulting products were deleted.
+      description: Filter by a deletion date range.
       schema:
         type: object
         properties:
@@ -152,7 +158,7 @@ get:
             format: date
     - in: query
       name: offset
-      description: How many products to skip in the result.
+      description: The number of products to skip when retrieving the products.
       schema:
         type: integer
         default: 0
@@ -165,15 +171,13 @@ get:
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each product of the
-        result.
+        Comma-separated relations that should be expanded in the returned
+        products.
       schema:
         type: string
     - in: query
       name: fields
-      description: >-
-        (Comma separated) Which fields should be included in each product of the
-        result.
+      description: Comma-separated fields that should be included in the returned products.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_price-lists_{id}_products_{product_id}_prices.yaml b/docs/api/admin/paths/admin_price-lists_{id}_products_{product_id}_prices.yaml
index 9ec17f197a..f83ce14e83 100644
--- a/docs/api/admin/paths/admin_price-lists_{id}_products_{product_id}_prices.yaml
+++ b/docs/api/admin/paths/admin_price-lists_{id}_products_{product_id}_prices.yaml
@@ -1,21 +1,19 @@
 delete:
   operationId: DeletePriceListsPriceListProductsProductPrices
-  summary: Delete Product's Prices
-  description: Delete all the prices related to a specific product in a price list
+  summary: Delete a Product's Prices
+  description: Delete all the prices related to a specific product in a price list.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: >-
-        The ID of the Price List that the Money Amounts that will be deleted
-        belongs to.
+      description: The ID of the Price List.
       schema:
         type: string
     - in: path
       name: product_id
       required: true
-      description: The ID of the product from which the money amount will be deleted.
+      description: The ID of the product from which the prices will be deleted.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_price-lists_{id}_variants_{variant_id}_prices.yaml b/docs/api/admin/paths/admin_price-lists_{id}_variants_{variant_id}_prices.yaml
index c5e55267ab..408613daf7 100644
--- a/docs/api/admin/paths/admin_price-lists_{id}_variants_{variant_id}_prices.yaml
+++ b/docs/api/admin/paths/admin_price-lists_{id}_variants_{variant_id}_prices.yaml
@@ -1,21 +1,19 @@
 delete:
   operationId: DeletePriceListsPriceListVariantsVariantPrices
-  summary: Delete Variant's Prices
+  summary: Delete a Variant's Prices
   description: Delete all the prices related to a specific variant in a price list
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: >-
-        The ID of the Price List that the Money Amounts that will be deleted
-        belongs to.
+      description: The ID of the Price List.
       schema:
         type: string
     - in: path
       name: variant_id
       required: true
-      description: The ID of the variant from which the money amount will be deleted.
+      description: The ID of the variant.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_product-categories.yaml b/docs/api/admin/paths/admin_product-categories.yaml
index 5f6a6a97ac..ee54ca8dcb 100644
--- a/docs/api/admin/paths/admin_product-categories.yaml
+++ b/docs/api/admin/paths/admin_product-categories.yaml
@@ -1,42 +1,50 @@
 get:
   operationId: GetProductCategories
   summary: List Product Categories
-  description: Retrieve a list of product categories.
+  description: >-
+    Retrieve a list of product categories. The product categories can be
+    filtered by fields such as `q` or `handle`. The product categories can also
+    be paginated.
   x-authenticated: true
+  x-featureFlag: product_categories
   parameters:
     - in: query
       name: q
-      description: Query used for searching product category names or handles.
+      description: term to search product categories' names and handles.
       schema:
         type: string
     - in: query
       name: handle
-      description: Query used for searching product category by handle.
+      description: Filter by handle.
       schema:
         type: string
     - in: query
       name: is_internal
-      description: Search for only internal categories.
+      description: Filter by whether the category is internal or not.
       schema:
         type: boolean
     - in: query
       name: is_active
-      description: Search for only active categories
+      description: Filter by whether the category is active or not.
       schema:
         type: boolean
     - in: query
       name: include_descendants_tree
-      description: Include all nested descendants of category
+      description: >-
+        If set to `true`, all nested descendants of a category are included in
+        the response.
       schema:
         type: boolean
     - in: query
       name: parent_category_id
-      description: Returns categories scoped by parent
+      description: Filter by the ID of a parent category.
       schema:
         type: string
     - in: query
       name: offset
-      description: How many product categories to skip in the result.
+      description: >-
+        The number of product categories to skip when retrieving the product
+        categories.
       schema:
         type: integer
         default: 0
@@ -49,15 +57,15 @@ get:
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in the product
-        category.
+        Comma-separated relations that should be expanded in the returned
+        product categories.
       schema:
         type: string
     - in: query
       name: fields
       description: >-
-        (Comma separated) Which fields should be included in the product
-        category.
+        Comma-separated fields that should be included in the returned product
+        categories.
       schema:
         type: string
   x-codegen:
@@ -99,17 +107,22 @@ get:
 post:
   operationId: PostProductCategories
   summary: Create a Product Category
-  description: Creates a Product Category.
+  description: Create a Product Category.
   x-authenticated: true
+  x-featureFlag: product_categories
   parameters:
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        product category.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Which fields should be retrieved in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned product
+        category.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_product-categories_{id}.yaml b/docs/api/admin/paths/admin_product-categories_{id}.yaml
index 8dead6227f..f624964100 100644
--- a/docs/api/admin/paths/admin_product-categories_{id}.yaml
+++ b/docs/api/admin/paths/admin_product-categories_{id}.yaml
@@ -1,8 +1,9 @@
 get:
   operationId: GetProductCategoriesCategory
   summary: Get a Product Category
-  description: Retrieves a Product Category.
+  description: Retrieve a Product Category's details.
   x-authenticated: true
+  x-featureFlag: product_categories
   parameters:
     - in: path
       name: id
@@ -12,12 +13,16 @@ get:
         type: string
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        product category.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Which fields should be included in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned product
+        category.
       schema:
         type: string
   x-codegen:
@@ -61,6 +66,7 @@ post:
   summary: Update a Product Category
   description: Updates a Product Category.
   x-authenticated: true
+  x-featureFlag: product_categories
   parameters:
     - in: path
       name: id
@@ -126,8 +132,9 @@ post:
 delete:
   operationId: DeleteProductCategoriesCategory
   summary: Delete a Product Category
-  description: Deletes a Product Category.
+  description: Delete a Product Category. This does not delete associated products.
   x-authenticated: true
+  x-featureFlag: product_categories
   parameters:
     - in: path
       name: id
diff --git a/docs/api/admin/paths/admin_product-categories_{id}_products_batch.yaml b/docs/api/admin/paths/admin_product-categories_{id}_products_batch.yaml
index 72717738ec..fcca56b350 100644
--- a/docs/api/admin/paths/admin_product-categories_{id}_products_batch.yaml
+++ b/docs/api/admin/paths/admin_product-categories_{id}_products_batch.yaml
@@ -1,8 +1,9 @@
 post:
   operationId: PostProductCategoriesCategoryProductsBatch
   summary: Add Products to a Category
-  description: Assign a batch of products to a product category.
+  description: Add a list of products to a product category.
   x-authenticated: true
+  x-featureFlag: product_categories
   parameters:
     - in: path
       name: id
@@ -12,12 +13,16 @@ post:
         type: string
     - in: query
       name: expand
-      description: (Comma separated) Category fields to be expanded in the response.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        product category.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Category fields to be retrieved in the response.
+      description: >-
+        Comma-separated fields that should be included in the returned product
+        category.
       schema:
         type: string
   requestBody:
@@ -69,6 +74,7 @@ delete:
   summary: Remove Products from Category
   description: Remove a list of products from a product category.
   x-authenticated: true
+  x-featureFlag: product_categories
   parameters:
     - in: path
       name: id
@@ -78,12 +84,16 @@ delete:
         type: string
     - in: query
       name: expand
-      description: (Comma separated) Category fields to be expanded in the response.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        product category.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Category fields to be retrieved in the response.
+      description: >-
+        Comma-separated fields that should be included in the returned product
+        category.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_product-tags.yaml b/docs/api/admin/paths/admin_product-tags.yaml
index 8077cd2da6..2b19e84b2c 100644
--- a/docs/api/admin/paths/admin_product-tags.yaml
+++ b/docs/api/admin/paths/admin_product-tags.yaml
@@ -1,57 +1,61 @@
 get:
   operationId: GetProductTags
   summary: List Product Tags
-  description: Retrieve a list of Product Tags.
+  description: >-
+    Retrieve a list of product tags. The product tags can be filtered by fields
+    such as `q` or `value`. The product tags can also be sorted or paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: limit
-      description: The number of tags to return.
+      description: Limit the number of product tags returned.
       schema:
         type: integer
         default: 10
     - in: query
       name: offset
-      description: The number of items to skip before the results.
+      description: The number of product tags to skip when retrieving the product tags.
       schema:
         type: integer
         default: 0
     - in: query
       name: order
-      description: The field to sort items by.
+      description: A product tag field to sort-order the retrieved product tags by.
       schema:
         type: string
     - in: query
       name: discount_condition_id
-      description: The discount condition id on which to filter the tags.
+      description: >-
+        Filter by the ID of a discount condition. Only product tags that this
+        discount condition is applied to will be retrieved.
       schema:
         type: string
     - in: query
       name: value
       style: form
       explode: false
-      description: The tag values to search for
+      description: Filter by tag value.
       schema:
         type: array
         items:
           type: string
     - in: query
       name: q
-      description: A query string to search values for
+      description: term to search product tags' values.
       schema:
         type: string
     - in: query
       name: id
       style: form
       explode: false
-      description: The tag IDs to search for
+      description: Filter by tag IDs.
       schema:
         type: array
         items:
           type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting product tags were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -73,7 +77,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting product tags were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
diff --git a/docs/api/admin/paths/admin_product-types.yaml b/docs/api/admin/paths/admin_product-types.yaml
index b31a17e380..a9412be7d2 100644
--- a/docs/api/admin/paths/admin_product-types.yaml
+++ b/docs/api/admin/paths/admin_product-types.yaml
@@ -1,36 +1,41 @@
 get:
   operationId: GetProductTypes
   summary: List Product Types
-  description: Retrieve a list of Product Types.
+  description: >-
+    Retrieve a list of product types. The product types can be filtered by
+    fields such as `q` or `value`. The product types can also be sorted or
+    paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: limit
-      description: The number of types to return.
+      description: Limit the number of product types returned.
       schema:
         type: integer
         default: 20
     - in: query
       name: offset
-      description: The number of items to skip before the results.
+      description: The number of product types to skip when retrieving the product types.
       schema:
         type: integer
         default: 0
     - in: query
       name: order
-      description: The field to sort items by.
+      description: A product type field to sort-order the retrieved product types by.
       schema:
         type: string
     - in: query
       name: discount_condition_id
-      description: The discount condition id on which to filter the product types.
+      description: >-
+        Filter by the ID of a discount condition. Only product types that this
+        discount condition is applied to will be retrieved.
       schema:
         type: string
     - in: query
       name: value
       style: form
       explode: false
-      description: The type values to search for
+      description: Filter by value.
       schema:
         type: array
         items:
@@ -39,19 +44,19 @@ get:
       name: id
       style: form
       explode: false
-      description: The type IDs to search for
+      description: Filter by product type IDs.
       schema:
         type: array
         items:
           type: string
     - in: query
       name: q
-      description: A query string to search values for
+      description: term to search product types' values.
       schema:
         type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting product types were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -73,7 +78,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting product types were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
diff --git a/docs/api/admin/paths/admin_products.yaml b/docs/api/admin/paths/admin_products.yaml
index 015cdbce7c..d4f42b28ae 100644
--- a/docs/api/admin/paths/admin_products.yaml
+++ b/docs/api/admin/paths/admin_products.yaml
@@ -1,19 +1,23 @@
 get:
   operationId: GetProducts
   summary: List Products
-  description: Retrieves a list of Product
+  description: >-
+    Retrieve a list of products. The products can be filtered by fields such as
+    `q` or `status`. The products can also be sorted or paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: q
       description: >-
-        Query used for searching product title and description, variant title
-        and sku, and collection title.
+        term to search products' title, description, variants' title and sku,
+        and collections' title.
       schema:
         type: string
     - in: query
       name: discount_condition_id
-      description: The discount condition id on which to filter the product.
+      description: >-
+        Filter by the ID of a discount condition. Only products that this
+        discount condition is applied to will be retrieved.
       schema:
         type: string
     - in: query
@@ -24,7 +28,7 @@ get:
       schema:
         oneOf:
           - type: string
-            description: ID of the product to search for.
+            description: ID of the product.
           - type: array
             items:
               type: string
@@ -33,7 +37,7 @@ get:
       name: status
       style: form
       explode: false
-      description: Status to search for
+      description: Filter by status.
       schema:
         type: array
         items:
@@ -47,7 +51,9 @@ get:
       name: collection_id
       style: form
       explode: false
-      description: Collection ids to search for.
+      description: >-
+        Filter by product collection IDs. Only products that are associated with
+        the specified collections will be retrieved.
       schema:
         type: array
         items:
@@ -56,7 +62,9 @@ get:
       name: tags
       style: form
       explode: false
-      description: Tag IDs to search for
+      description: >-
+        Filter by product tag IDs. Only products that are associated with the
+        specified tags will be retrieved.
       schema:
         type: array
         items:
@@ -65,7 +73,9 @@ get:
       name: price_list_id
       style: form
       explode: false
-      description: Price List IDs to search for
+      description: >-
+        Filter by IDs of price lists. Only products that these price lists are
+        applied to will be retrieved.
       schema:
         type: array
         items:
@@ -74,7 +84,9 @@ get:
       name: sales_channel_id
       style: form
       explode: false
-      description: Sales Channel IDs to filter products by
+      description: >-
+        Filter by sales channel IDs. Only products that are available in the
+        specified sales channels will be retrieved.
       schema:
         type: array
         items:
@@ -83,7 +95,9 @@ get:
       name: type_id
       style: form
       explode: false
-      description: Type IDs to filter products by
+      description: >-
+        Filter by product type IDs. Only products that are associated with the
+        specified types will be retrieved.
       schema:
         type: array
         items:
@@ -92,39 +106,47 @@ get:
       name: category_id
       style: form
       explode: false
-      description: Category IDs to filter products by
+      description: >-
+        Filter by product category IDs. Only products that are associated with
+        the specified categories will be retrieved.
       schema:
         type: array
+        x-featureFlag: product_categories
         items:
           type: string
     - in: query
       name: include_category_children
-      description: Include category children when filtering by category_id
+      style: form
+      explode: false
+      description: >-
+        whether to include product category children when filtering by
+        `category_id`
       schema:
         type: boolean
+        x-featureFlag: product_categories
     - in: query
       name: title
-      description: title to search for.
+      description: Filter by title.
       schema:
         type: string
     - in: query
       name: description
-      description: description to search for.
+      description: Filter by description.
       schema:
         type: string
     - in: query
       name: handle
-      description: handle to search for.
+      description: Filter by handle.
       schema:
         type: string
     - in: query
       name: is_giftcard
-      description: Search for giftcards using is_giftcard=true.
+      description: Whether to retrieve gift cards or regular products.
       schema:
         type: boolean
     - in: query
       name: created_at
-      description: Date comparison for when resulting products were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -146,7 +168,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting products were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -168,7 +190,7 @@ get:
             format: date
     - in: query
       name: deleted_at
-      description: Date comparison for when resulting products were deleted.
+      description: Filter by a deletion date range.
       schema:
         type: object
         properties:
@@ -190,7 +212,7 @@ get:
             format: date
     - in: query
       name: offset
-      description: How many products to skip in the result.
+      description: The number of products to skip when retrieving the products.
       schema:
         type: integer
         default: 0
@@ -203,20 +225,18 @@ get:
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each product of the
-        result.
+        Comma-separated relations that should be expanded in the returned
+        products.
       schema:
         type: string
     - in: query
       name: fields
-      description: >-
-        (Comma separated) Which fields should be included in each product of the
-        result.
+      description: Comma-separated fields that should be included in the returned products.
       schema:
         type: string
     - in: query
       name: order
-      description: the field used to order the products.
+      description: A product field to sort-order the retrieved products by.
       schema:
         type: string
   x-codegen:
@@ -259,7 +279,9 @@ post:
   operationId: PostProducts
   summary: Create a Product
   x-authenticated: true
-  description: Creates a Product
+  description: >-
+    Create a new Product. This endpoint can also be used to create a gift card
+    if the `is_giftcard` field is set to `true`.
   requestBody:
     content:
       application/json:
diff --git a/docs/api/admin/paths/admin_products_tag-usage.yaml b/docs/api/admin/paths/admin_products_tag-usage.yaml
index 4abbf654ec..8ef725cd96 100644
--- a/docs/api/admin/paths/admin_products_tag-usage.yaml
+++ b/docs/api/admin/paths/admin_products_tag-usage.yaml
@@ -1,7 +1,9 @@
 get:
   operationId: GetProductsTagUsage
   summary: List Tags Usage Number
-  description: Retrieves a list of Product Tags with how many times each is used.
+  description: >-
+    Retrieve a list of Product Tags with how many times each is used in
+    products.
   x-authenticated: true
   x-codegen:
     method: listTags
diff --git a/docs/api/admin/paths/admin_products_types.yaml b/docs/api/admin/paths/admin_products_types.yaml
index 949a963437..6ee409f906 100644
--- a/docs/api/admin/paths/admin_products_types.yaml
+++ b/docs/api/admin/paths/admin_products_types.yaml
@@ -2,7 +2,7 @@ get:
   deprecated: true
   operationId: GetProductsTypes
   summary: List Product Types
-  description: Retrieves a list of Product Types.
+  description: Retrieve a list of Product Types.
   x-authenticated: true
   x-codegen:
     method: listTypes
diff --git a/docs/api/admin/paths/admin_products_{id}.yaml b/docs/api/admin/paths/admin_products_{id}.yaml
index 36cf087796..c232685a6d 100644
--- a/docs/api/admin/paths/admin_products_{id}.yaml
+++ b/docs/api/admin/paths/admin_products_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetProductsProduct
   summary: Get a Product
-  description: Retrieves a Product.
+  description: Retrieve a Product's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,7 +48,7 @@ get:
 post:
   operationId: PostProductsProduct
   summary: Update a Product
-  description: Updates a Product
+  description: Update a Product's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -100,7 +100,7 @@ post:
 delete:
   operationId: DeleteProductsProduct
   summary: Delete a Product
-  description: Deletes a Product and it's associated Product Variants.
+  description: Delete a Product and its associated product variants and options.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_products_{id}_metadata.yaml b/docs/api/admin/paths/admin_products_{id}_metadata.yaml
index 5a0b4f1cfe..e0e2da5b3e 100644
--- a/docs/api/admin/paths/admin_products_{id}_metadata.yaml
+++ b/docs/api/admin/paths/admin_products_{id}_metadata.yaml
@@ -1,7 +1,12 @@
 post:
   operationId: PostProductsProductMetadata
-  summary: Set Product Metadata
-  description: Set metadata key/value pair for Product
+  summary: Set Metadata
+  description: >-
+    Set the metadata of a Product. It can be any key-value pair, which allows
+    adding custom data to a product.
+  externalDocs:
+    description: Learn about the metadata attribute, and how to delete and update it.
+    url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_products_{id}_options.yaml b/docs/api/admin/paths/admin_products_{id}_options.yaml
index 599b570007..6886e92467 100644
--- a/docs/api/admin/paths/admin_products_{id}_options.yaml
+++ b/docs/api/admin/paths/admin_products_{id}_options.yaml
@@ -1,8 +1,8 @@
 post:
   operationId: PostProductsProductOptions
   summary: Add a Product Option
+  description: Add a Product Option to a Product.
   x-authenticated: true
-  description: Adds a Product Option to a Product
   parameters:
     - in: path
       name: id
diff --git a/docs/api/admin/paths/admin_products_{id}_options_{option_id}.yaml b/docs/api/admin/paths/admin_products_{id}_options_{option_id}.yaml
index c7c21d88bb..0b84402552 100644
--- a/docs/api/admin/paths/admin_products_{id}_options_{option_id}.yaml
+++ b/docs/api/admin/paths/admin_products_{id}_options_{option_id}.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostProductsProductOptionsOption
   summary: Update a Product Option
-  description: Updates a Product Option
+  description: Update a Product Option's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -61,9 +61,8 @@ delete:
   operationId: DeleteProductsProductOptionsOption
   summary: Delete a Product Option
   description: >-
-    Deletes a Product Option. Before a Product Option can be deleted all Option
-    Values for the Product Option must be the same. You may, for example, have
-    to delete some of your variants prior to deleting the Product Option
+    Delete a Product Option. If there are product variants that use this product
+    option, they must be deleted before deleting the product option.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_products_{id}_variants.yaml b/docs/api/admin/paths/admin_products_{id}_variants.yaml
index ebfc2551a2..3f047fbcaf 100644
--- a/docs/api/admin/paths/admin_products_{id}_variants.yaml
+++ b/docs/api/admin/paths/admin_products_{id}_variants.yaml
@@ -1,34 +1,42 @@
 get:
   operationId: GetProductsProductVariants
   summary: List a Product's Variants
-  description: Retrieves a list of the Product Variants associated with a Product.
+  description: >-
+    Retrieve a list of Product Variants associated with a Product. The variants
+    can be paginated.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: ID of the product to search for the variants.
+      description: ID of the product.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated string of the column to select.
+      description: >-
+        Comma-separated fields that should be included in the returned product
+        variants.
       schema:
         type: string
     - in: query
       name: expand
-      description: Comma separated string of the relations to include.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        product variants.
       schema:
         type: string
     - in: query
       name: offset
-      description: How many items to skip before the results.
+      description: >-
+        The number of product variants to skip when retrieving the product
+        variants.
       schema:
         type: integer
         default: 0
     - in: query
       name: limit
-      description: Limit the number of items returned.
+      description: Limit the number of product variants returned.
       schema:
         type: integer
         default: 100
@@ -68,8 +76,8 @@ post:
   operationId: PostProductsProductVariants
   summary: Create a Product Variant
   description: >-
-    Creates a Product Variant. Each Product Variant must have a unique
-    combination of Product Option Values.
+    Create a Product Variant associated with a Product. Each product variant
+    must have a unique combination of Product Option values.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_products_{id}_variants_{variant_id}.yaml b/docs/api/admin/paths/admin_products_{id}_variants_{variant_id}.yaml
index c42bce30e3..dff7130c04 100644
--- a/docs/api/admin/paths/admin_products_{id}_variants_{variant_id}.yaml
+++ b/docs/api/admin/paths/admin_products_{id}_variants_{variant_id}.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostProductsProductVariantsVariant
   summary: Update a Product Variant
-  description: Update a Product Variant.
+  description: Update a Product Variant's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -62,7 +62,7 @@ post:
 delete:
   operationId: DeleteProductsProductVariantsVariant
   summary: Delete a Product Variant
-  description: Deletes a Product Variant.
+  description: Delete a Product Variant.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_publishable-api-key_{id}.yaml b/docs/api/admin/paths/admin_publishable-api-key_{id}.yaml
index bf53950b68..26c7a3c18a 100644
--- a/docs/api/admin/paths/admin_publishable-api-key_{id}.yaml
+++ b/docs/api/admin/paths/admin_publishable-api-key_{id}.yaml
@@ -1,13 +1,13 @@
 post:
   operationId: PostPublishableApiKysPublishableApiKey
-  summary: Update PublishableApiKey
-  description: Updates a PublishableApiKey.
+  summary: Update Publishable API Key
+  description: Update a Publishable API Key's details.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the PublishableApiKey.
+      description: The ID of the Publishable API Key.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_publishable-api-keys.yaml b/docs/api/admin/paths/admin_publishable-api-keys.yaml
index 3b2eac0bee..772847f524 100644
--- a/docs/api/admin/paths/admin_publishable-api-keys.yaml
+++ b/docs/api/admin/paths/admin_publishable-api-keys.yaml
@@ -1,34 +1,43 @@
 get:
   operationId: GetPublishableApiKeys
-  summary: List PublishableApiKeys
-  description: List PublishableApiKeys.
+  summary: List Publishable API keys
+  description: >-
+    Retrieve a list of publishable API keys. The publishable API keys can be
+    filtered by fields such as `q`. The publishable API keys can also be
+    paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: q
-      description: Query used for searching publishable api keys by title.
+      description: term to search publishable API keys' titles.
       schema:
         type: string
     - in: query
       name: limit
-      description: The number of items in the response
+      description: Limit the number of publishable API keys returned.
       schema:
         type: number
         default: '20'
     - in: query
       name: offset
-      description: The offset of items in response
+      description: >-
+        The number of publishable API keys to skip when retrieving the
+        publishable API keys.
       schema:
         type: number
         default: '0'
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        publishable API keys.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned
+        publishable API keys.
       schema:
         type: string
   x-codegen:
@@ -69,8 +78,8 @@ get:
       $ref: ../components/responses/500_error.yaml
 post:
   operationId: PostPublishableApiKeys
-  summary: Create PublishableApiKey
-  description: Creates a PublishableApiKey.
+  summary: Create Publishable API Key
+  description: Creates a Publishable API Key.
   requestBody:
     content:
       application/json:
diff --git a/docs/api/admin/paths/admin_publishable-api-keys_{id}.yaml b/docs/api/admin/paths/admin_publishable-api-keys_{id}.yaml
index 9cd04da177..fbad24a233 100644
--- a/docs/api/admin/paths/admin_publishable-api-keys_{id}.yaml
+++ b/docs/api/admin/paths/admin_publishable-api-keys_{id}.yaml
@@ -1,12 +1,12 @@
 get:
   operationId: GetPublishableApiKeysPublishableApiKey
-  summary: Get a PublishableApiKey
-  description: Retrieve the Publishable Api Key.
+  summary: Get a Publishable API Key
+  description: Retrieve a publishable API key's details.
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the PublishableApiKey.
+      description: The ID of the Publishable API Key.
       schema:
         type: string
   x-authenticated: true
@@ -47,14 +47,16 @@ get:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeletePublishableApiKeysPublishableApiKey
-  summary: Delete PublishableApiKey
-  description: Deletes a PublishableApiKeys
+  summary: Delete Publishable API Key
+  description: >-
+    Delete a Publishable API Key. Associated resources, such as sales channels,
+    are not deleted.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the PublishableApiKeys to delete.
+      description: The ID of the Publishable API Key to delete.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_publishable-api-keys_{id}_revoke.yaml b/docs/api/admin/paths/admin_publishable-api-keys_{id}_revoke.yaml
index 76f259ad17..f0b834d59a 100644
--- a/docs/api/admin/paths/admin_publishable-api-keys_{id}_revoke.yaml
+++ b/docs/api/admin/paths/admin_publishable-api-keys_{id}_revoke.yaml
@@ -1,12 +1,14 @@
 post:
   operationId: PostPublishableApiKeysPublishableApiKeyRevoke
-  summary: Revoke PublishableApiKey
-  description: Revokes a PublishableApiKey.
+  summary: Revoke a Publishable API Key
+  description: >-
+    Revoke a Publishable API Key. Revoking the publishable API Key can't be
+    undone, and the key can't be used in future requests.
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the PublishableApiKey.
+      description: The ID of the Publishable API Key.
       schema:
         type: string
   x-authenticated: true
diff --git a/docs/api/admin/paths/admin_publishable-api-keys_{id}_sales-channels.yaml b/docs/api/admin/paths/admin_publishable-api-keys_{id}_sales-channels.yaml
index 1e94dfba13..f4ab398101 100644
--- a/docs/api/admin/paths/admin_publishable-api-keys_{id}_sales-channels.yaml
+++ b/docs/api/admin/paths/admin_publishable-api-keys_{id}_sales-channels.yaml
@@ -1,18 +1,20 @@
 get:
   operationId: GetPublishableApiKeySalesChannels
-  summary: List SalesChannels
-  description: List PublishableApiKey's SalesChannels
+  summary: List Sales Channels
+  description: >-
+    List the sales channels associated with a publishable API key. The sales
+    channels can be filtered by fields such as `q`.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Publishable Api Key.
+      description: The ID of the publishable API key.
       schema:
         type: string
     - in: query
       name: q
-      description: Query used for searching sales channels' names and descriptions.
+      description: query to search sales channels' names and descriptions.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/admin/paths/admin_publishable-api-keys_{id}_sales-channels_batch.yaml b/docs/api/admin/paths/admin_publishable-api-keys_{id}_sales-channels_batch.yaml
index 6a4b968f3f..940ea8a790 100644
--- a/docs/api/admin/paths/admin_publishable-api-keys_{id}_sales-channels_batch.yaml
+++ b/docs/api/admin/paths/admin_publishable-api-keys_{id}_sales-channels_batch.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostPublishableApiKeySalesChannelsChannelsBatch
-  summary: Add SalesChannels
-  description: Assign a batch of sales channels to a publishable api key.
+  summary: Add Sales Channels
+  description: Assign a list of sales channels to a publishable API key.
   x-authenticated: true
   parameters:
     - in: path
@@ -55,14 +55,17 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeletePublishableApiKeySalesChannelsChannelsBatch
-  summary: Delete SalesChannels
-  description: Remove a batch of sales channels from a publishable api key.
+  summary: Remove Sales Channels
+  description: >-
+    Remove a list of sales channels from a publishable API key. This doesn't
+    delete the sales channels and only removes the association between them and
+    the publishable API key.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Publishable Api Key.
+      description: The ID of the Publishable API Key.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_regions.yaml b/docs/api/admin/paths/admin_regions.yaml
index eb111a0c26..be083cfc76 100644
--- a/docs/api/admin/paths/admin_regions.yaml
+++ b/docs/api/admin/paths/admin_regions.yaml
@@ -1,7 +1,9 @@
 get:
   operationId: GetRegions
   summary: List Regions
-  description: Retrieves a list of Regions.
+  description: >-
+    Retrieve a list of Regions. The regions can be filtered by fields such as
+    `created_at`. The regions can also be paginated
   x-authenticated: true
   parameters:
     - in: query
@@ -10,38 +12,83 @@ get:
         type: integer
         default: 50
       required: false
-      description: limit the number of regions in response
+      description: Limit the number of regions returned.
     - in: query
       name: offset
       schema:
         type: integer
         default: 0
       required: false
-      description: Offset of regions in response (used for pagination)
+      description: The number of regions to skip when retrieving the regions.
     - in: query
       name: created_at
+      required: false
+      description: Filter by a creation date range.
       schema:
         type: object
-      required: false
-      description: >-
-        Date comparison for when resulting region was created, i.e. less than,
-        greater than etc.
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
     - in: query
       name: updated_at
+      required: false
+      description: Filter by an update date range.
       schema:
         type: object
-      required: false
-      description: >-
-        Date comparison for when resulting region was updated, i.e. less than,
-        greater than etc.
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
     - in: query
       name: deleted_at
+      required: false
+      description: Filter by a deletion date range.
       schema:
         type: object
-      required: false
-      description: >-
-        Date comparison for when resulting region was deleted, i.e. less than,
-        greater than etc.
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
   x-codegen:
     method: list
     queryParams: AdminGetRegionsParams
@@ -81,7 +128,7 @@ get:
 post:
   operationId: PostRegions
   summary: Create a Region
-  description: Creates a Region
+  description: Create a Region.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_regions_{id}.yaml b/docs/api/admin/paths/admin_regions_{id}.yaml
index 11dddce5f8..d3b1d2158c 100644
--- a/docs/api/admin/paths/admin_regions_{id}.yaml
+++ b/docs/api/admin/paths/admin_regions_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetRegionsRegion
   summary: Get a Region
-  description: Retrieves a Region.
+  description: Retrieve a Region's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,7 +48,7 @@ get:
 post:
   operationId: PostRegionsRegion
   summary: Update a Region
-  description: Updates a Region
+  description: Update a Region's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -100,7 +100,9 @@ post:
 delete:
   operationId: DeleteRegionsRegion
   summary: Delete a Region
-  description: Deletes a Region.
+  description: >-
+    Delete a Region. Associated resources, such as providers or currencies are
+    not deleted. Associated tax rates are deleted.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_regions_{id}_countries.yaml b/docs/api/admin/paths/admin_regions_{id}_countries.yaml
index 7216646d2c..69e46805c5 100644
--- a/docs/api/admin/paths/admin_regions_{id}_countries.yaml
+++ b/docs/api/admin/paths/admin_regions_{id}_countries.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostRegionsRegionCountries
   summary: Add Country
-  description: Adds a Country to the list of Countries in a Region
+  description: Add a Country to the list of Countries in a Region
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_regions_{id}_countries_{country_code}.yaml b/docs/api/admin/paths/admin_regions_{id}_countries_{country_code}.yaml
index e653031cbc..ce9f11c9ac 100644
--- a/docs/api/admin/paths/admin_regions_{id}_countries_{country_code}.yaml
+++ b/docs/api/admin/paths/admin_regions_{id}_countries_{country_code}.yaml
@@ -1,8 +1,10 @@
 delete:
   operationId: PostRegionsRegionCountriesCountry
-  summary: Delete Country
+  summary: Remove Country
   x-authenticated: true
-  description: Removes a Country from the list of Countries in a Region
+  description: >-
+    Remove a Country from the list of Countries in a Region. The country will
+    still be available in the system, and it can be used in other regions.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/admin/paths/admin_regions_{id}_fulfillment-options.yaml b/docs/api/admin/paths/admin_regions_{id}_fulfillment-options.yaml
index e1c4aee49a..984516a0de 100644
--- a/docs/api/admin/paths/admin_regions_{id}_fulfillment-options.yaml
+++ b/docs/api/admin/paths/admin_regions_{id}_fulfillment-options.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetRegionsRegionFulfillmentOptions
   summary: List Fulfillment Options
-  description: Gathers all the fulfillment options available to in the Region.
+  description: Retrieve a list of fulfillment options available in a Region.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_regions_{id}_fulfillment-providers.yaml b/docs/api/admin/paths/admin_regions_{id}_fulfillment-providers.yaml
index 8eba44d0ed..44834a278f 100644
--- a/docs/api/admin/paths/admin_regions_{id}_fulfillment-providers.yaml
+++ b/docs/api/admin/paths/admin_regions_{id}_fulfillment-providers.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostRegionsRegionFulfillmentProviders
   summary: Add Fulfillment Provider
-  description: Adds a Fulfillment Provider to a Region
+  description: Add a Fulfillment Provider to the list of fulfullment providers in a Region.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_regions_{id}_fulfillment-providers_{provider_id}.yaml b/docs/api/admin/paths/admin_regions_{id}_fulfillment-providers_{provider_id}.yaml
index b0a1479d77..df2f7ade2c 100644
--- a/docs/api/admin/paths/admin_regions_{id}_fulfillment-providers_{provider_id}.yaml
+++ b/docs/api/admin/paths/admin_regions_{id}_fulfillment-providers_{provider_id}.yaml
@@ -1,7 +1,9 @@
 delete:
   operationId: PostRegionsRegionFulfillmentProvidersProvider
-  summary: Del. Fulfillment Provider
-  description: Removes a Fulfillment Provider.
+  summary: Remove Fulfillment Provider
+  description: >-
+    Remove a Fulfillment Provider from a Region. The fulfillment provider will
+    still be available for usage in other regions.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_regions_{id}_payment-providers.yaml b/docs/api/admin/paths/admin_regions_{id}_payment-providers.yaml
index b75982b636..7fb34a55bd 100644
--- a/docs/api/admin/paths/admin_regions_{id}_payment-providers.yaml
+++ b/docs/api/admin/paths/admin_regions_{id}_payment-providers.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostRegionsRegionPaymentProviders
   summary: Add Payment Provider
-  description: Adds a Payment Provider to a Region
+  description: Add a Payment Provider to the list of payment providers in a Region.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_regions_{id}_payment-providers_{provider_id}.yaml b/docs/api/admin/paths/admin_regions_{id}_payment-providers_{provider_id}.yaml
index aad8aae415..986add960b 100644
--- a/docs/api/admin/paths/admin_regions_{id}_payment-providers_{provider_id}.yaml
+++ b/docs/api/admin/paths/admin_regions_{id}_payment-providers_{provider_id}.yaml
@@ -1,7 +1,9 @@
 delete:
   operationId: PostRegionsRegionPaymentProvidersProvider
-  summary: Delete Payment Provider
-  description: Removes a Payment Provider.
+  summary: Remove Payment Provider
+  description: >-
+    Remove a Payment Provider from a Region. The payment provider will still be
+    available for usage in other regions.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_reservations.yaml b/docs/api/admin/paths/admin_reservations.yaml
index 88cd069e28..50aa77d86c 100644
--- a/docs/api/admin/paths/admin_reservations.yaml
+++ b/docs/api/admin/paths/admin_reservations.yaml
@@ -1,14 +1,16 @@
 get:
   operationId: GetReservations
   summary: List Reservations
-  description: Retrieve a list of Reservations.
+  description: >-
+    Retrieve a list of Reservations. The reservations can be filtered by fields
+    such as `location_id` or `quantity`. The reservations can also be paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: location_id
       style: form
       explode: false
-      description: Location ids to search for.
+      description: Filter by location ID
       schema:
         type: array
         items:
@@ -17,7 +19,7 @@ get:
       name: inventory_item_id
       style: form
       explode: false
-      description: Inventory Item ids to search for.
+      description: Filter by inventory item ID.
       schema:
         type: array
         items:
@@ -26,7 +28,7 @@ get:
       name: line_item_id
       style: form
       explode: false
-      description: Line Item ids to search for.
+      description: Filter by line item ID.
       schema:
         type: array
         items:
@@ -53,10 +55,11 @@ get:
               number
     - in: query
       name: description
-      description: A param for search reservation descriptions
+      description: Filter by description.
       schema:
         oneOf:
           - type: string
+            description: description value to filter by.
           - type: object
             properties:
               contains:
@@ -70,7 +73,7 @@ get:
                 description: filter by reservation description ending with search string.
     - in: query
       name: created_at
-      description: Date comparison for when resulting reservations were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -92,28 +95,28 @@ get:
             format: date
     - in: query
       name: offset
-      description: How many Reservations to skip in the result.
+      description: The number of reservations to skip when retrieving the reservations.
       schema:
         type: integer
         default: 0
     - in: query
       name: limit
-      description: Limit the number of Reservations returned.
+      description: Limit the number of reservations returned.
       schema:
         type: integer
         default: 20
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in the product
-        category.
+        Comma-separated relations that should be expanded in the returned
+        reservations.
       schema:
         type: string
     - in: query
       name: fields
       description: >-
-        (Comma separated) Which fields should be included in the product
-        category.
+        Comma-separated fields that should be included in the returned
+        reservations.
       schema:
         type: string
   x-codegen:
@@ -155,7 +158,9 @@ get:
 post:
   operationId: PostReservations
   summary: Create a Reservation
-  description: Create a Reservation which can be associated with any resource as required.
+  description: >-
+    Create a Reservation which can be associated with any resource, such as an
+    order's line item.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_reservations_{id}.yaml b/docs/api/admin/paths/admin_reservations_{id}.yaml
index 0a0e95d28e..31ec8592c2 100644
--- a/docs/api/admin/paths/admin_reservations_{id}.yaml
+++ b/docs/api/admin/paths/admin_reservations_{id}.yaml
@@ -1,13 +1,13 @@
 get:
   operationId: GetReservationsReservation
   summary: Get a Reservation
-  description: Retrieves a single reservation using its ID
+  description: Retrieve a reservation's details.'
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the reservation to retrieve.
+      description: The ID of the reservation.
       schema:
         type: string
   x-codeSamples:
@@ -46,13 +46,13 @@ get:
 post:
   operationId: PostReservationsReservation
   summary: Update a Reservation
-  description: Updates a Reservation which can be associated with any resource as required.
+  description: Update a Reservation's details.'
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Reservation to update.
+      description: The ID of the Reservation.
       schema:
         type: string
   requestBody:
@@ -96,7 +96,9 @@ post:
 delete:
   operationId: DeleteReservationsReservation
   summary: Delete a Reservation
-  description: Deletes a Reservation.
+  description: >-
+    Delete a Reservation. Associated resources, such as the line item, will not
+    be deleted.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_return-reasons.yaml b/docs/api/admin/paths/admin_return-reasons.yaml
index 942fcb4ef3..6fbe97fea3 100644
--- a/docs/api/admin/paths/admin_return-reasons.yaml
+++ b/docs/api/admin/paths/admin_return-reasons.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetReturnReasons
   summary: List Return Reasons
-  description: Retrieves a list of Return Reasons.
+  description: Retrieve a list of Return Reasons.
   x-authenticated: true
   x-codegen:
     method: list
@@ -41,7 +41,7 @@ get:
 post:
   operationId: PostReturnReasons
   summary: Create a Return Reason
-  description: Creates a Return Reason
+  description: Create a Return Reason.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_return-reasons_{id}.yaml b/docs/api/admin/paths/admin_return-reasons_{id}.yaml
index 5097081744..c426de0751 100644
--- a/docs/api/admin/paths/admin_return-reasons_{id}.yaml
+++ b/docs/api/admin/paths/admin_return-reasons_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetReturnReasonsReason
   summary: Get a Return Reason
-  description: Retrieves a Return Reason.
+  description: Retrieve a Return Reason's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,7 +48,7 @@ get:
 post:
   operationId: PostReturnReasonsReason
   summary: Update a Return Reason
-  description: Updates a Return Reason
+  description: Update a Return Reason's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -100,7 +100,7 @@ post:
 delete:
   operationId: DeleteReturnReason
   summary: Delete a Return Reason
-  description: Deletes a return reason.
+  description: Delete a return reason.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_returns.yaml b/docs/api/admin/paths/admin_returns.yaml
index d716c6583e..fd847d9b5d 100644
--- a/docs/api/admin/paths/admin_returns.yaml
+++ b/docs/api/admin/paths/admin_returns.yaml
@@ -1,17 +1,17 @@
 get:
   operationId: GetReturns
   summary: List Returns
-  description: Retrieves a list of Returns
+  description: Retrieve a list of Returns. The returns can be paginated.
   parameters:
     - in: query
       name: limit
-      description: The upper limit for the amount of responses returned.
+      description: Limit the number of Returns returned.
       schema:
         type: number
         default: '50'
     - in: query
       name: offset
-      description: The offset of the list returned.
+      description: The number of Returns to skip when retrieving the Returns.
       schema:
         type: number
         default: '0'
diff --git a/docs/api/admin/paths/admin_returns_{id}_cancel.yaml b/docs/api/admin/paths/admin_returns_{id}_cancel.yaml
index fa41d224fa..9fecafffd3 100644
--- a/docs/api/admin/paths/admin_returns_{id}_cancel.yaml
+++ b/docs/api/admin/paths/admin_returns_{id}_cancel.yaml
@@ -1,7 +1,9 @@
 post:
   operationId: PostReturnsReturnCancel
   summary: Cancel a Return
-  description: Registers a Return as canceled.
+  description: >-
+    Registers a Return as canceled. The return can be associated with an order,
+    claim, or swap.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/admin/paths/admin_returns_{id}_receive.yaml b/docs/api/admin/paths/admin_returns_{id}_receive.yaml
index 156c30bfae..e3ec637bad 100644
--- a/docs/api/admin/paths/admin_returns_{id}_receive.yaml
+++ b/docs/api/admin/paths/admin_returns_{id}_receive.yaml
@@ -2,8 +2,8 @@ post:
   operationId: PostReturnsReturnReceive
   summary: Receive a Return
   description: >-
-    Registers a Return as received. Updates statuses on Orders and Swaps
-    accordingly.
+    Mark a Return as received. This also updates the status of associated order,
+    claim, or swap accordingly.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/admin/paths/admin_sales-channels.yaml b/docs/api/admin/paths/admin_sales-channels.yaml
index 127f968561..abbdf11110 100644
--- a/docs/api/admin/paths/admin_sales-channels.yaml
+++ b/docs/api/admin/paths/admin_sales-channels.yaml
@@ -1,37 +1,40 @@
 get:
   operationId: GetSalesChannels
   summary: List Sales Channels
-  description: Retrieves a list of sales channels
+  description: >-
+    Retrieve a list of sales channels. The sales channels can be filtered by
+    fields such as `q` or `name`. The sales channels can also be sorted or
+    paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: id
-      description: ID of the sales channel
+      description: Filter by a sales channel ID.
       schema:
         type: string
     - in: query
       name: name
-      description: Name of the sales channel
+      description: Filter by name.
       schema:
         type: string
     - in: query
       name: description
-      description: Description of the sales channel
+      description: Filter by description.
       schema:
         type: string
     - in: query
       name: q
-      description: Query used for searching sales channels' names and descriptions.
+      description: term used to search sales channels' names and descriptions.
       schema:
         type: string
     - in: query
       name: order
-      description: The field to order the results by.
+      description: A sales-channel field to sort-order the retrieved sales channels by.
       schema:
         type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting collections were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -53,7 +56,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting collections were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -75,7 +78,7 @@ get:
             format: date
     - in: query
       name: deleted_at
-      description: Date comparison for when resulting collections were deleted.
+      description: Filter by a deletion date range.
       schema:
         type: object
         properties:
@@ -97,7 +100,7 @@ get:
             format: date
     - in: query
       name: offset
-      description: How many sales channels to skip in the result.
+      description: The number of sales channels to skip when retrieving the sales channels.
       schema:
         type: integer
         default: 0
@@ -110,15 +113,15 @@ get:
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each sales channel
-        of the result.
+        Comma-separated relations that should be expanded in the returned sales
+        channels.
       schema:
         type: string
     - in: query
       name: fields
       description: >-
-        (Comma separated) Which fields should be included in each sales channel
-        of the result.
+        Comma-separated fields that should be included in the returned sales
+        channels.
       schema:
         type: string
   x-codegen:
@@ -160,7 +163,7 @@ get:
 post:
   operationId: PostSalesChannels
   summary: Create a Sales Channel
-  description: Creates a Sales Channel.
+  description: Create a Sales Channel.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_sales-channels_{id}.yaml b/docs/api/admin/paths/admin_sales-channels_{id}.yaml
index abd8fbb30b..a35f4501e1 100644
--- a/docs/api/admin/paths/admin_sales-channels_{id}.yaml
+++ b/docs/api/admin/paths/admin_sales-channels_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetSalesChannelsSalesChannel
   summary: Get a Sales Channel
-  description: Retrieves the sales channel.
+  description: Retrieve a sales channel's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,7 +48,7 @@ get:
 post:
   operationId: PostSalesChannelsSalesChannel
   summary: Update a Sales Channel
-  description: Updates a Sales Channel.
+  description: Update a Sales Channel's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -100,7 +100,9 @@ post:
 delete:
   operationId: DeleteSalesChannelsSalesChannel
   summary: Delete a Sales Channel
-  description: Deletes the sales channel.
+  description: >-
+    Delete a sales channel. Associated products, stock locations, and other
+    resources are not deleted.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_sales-channels_{id}_products_batch.yaml b/docs/api/admin/paths/admin_sales-channels_{id}_products_batch.yaml
index 12fccc67f4..2ed4ffd599 100644
--- a/docs/api/admin/paths/admin_sales-channels_{id}_products_batch.yaml
+++ b/docs/api/admin/paths/admin_sales-channels_{id}_products_batch.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostSalesChannelsChannelProductsBatch
-  summary: Add Products
-  description: Assign a batch of product to a sales channel.
+  summary: Add Products to Sales Channel
+  description: Add a list of products to a sales channel.
   x-authenticated: true
   parameters:
     - in: path
@@ -54,8 +54,11 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteSalesChannelsChannelProductsBatch
-  summary: Delete Products
-  description: Remove a list of products from a sales channel.
+  summary: Remove Products from Sales Channel
+  description: >-
+    Remove a list of products from a sales channel. This does not delete the
+    product. It only removes the association between the product and the sales
+    channel.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_sales-channels_{id}_stock-locations.yaml b/docs/api/admin/paths/admin_sales-channels_{id}_stock-locations.yaml
index 2318225997..d27b262e43 100644
--- a/docs/api/admin/paths/admin_sales-channels_{id}_stock-locations.yaml
+++ b/docs/api/admin/paths/admin_sales-channels_{id}_stock-locations.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostSalesChannelsSalesChannelStockLocation
   summary: Associate a Stock Location
-  description: Associates a stock location with a Sales Channel.
+  description: Associate a stock location with a Sales Channel.
   x-authenticated: true
   parameters:
     - in: path
@@ -55,8 +55,11 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteSalesChannelsSalesChannelStockLocation
-  summary: Remove a Stock Location Association
-  description: Removes a stock location from a Sales Channel.
+  summary: Remove Stock Location from Sales Channels.
+  description: >-
+    Remove a stock location from a Sales Channel. This only removes the
+    association between the stock location and the sales channel. It does not
+    delete the stock location.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_shipping-options.yaml b/docs/api/admin/paths/admin_shipping-options.yaml
index 4f18704bc7..1a38c7ae82 100644
--- a/docs/api/admin/paths/admin_shipping-options.yaml
+++ b/docs/api/admin/paths/admin_shipping-options.yaml
@@ -1,24 +1,26 @@
 get:
   operationId: GetShippingOptions
   summary: List Shipping Options
-  description: Retrieves a list of Shipping Options.
+  description: >-
+    Retrieve a list of Shipping Options. The shipping options can be filtered by
+    fields such as `region_id` or `is_return`.
   x-authenticated: true
   parameters:
     - in: query
       name: region_id
       schema:
         type: string
-      description: Region ID to fetch options from
+      description: Filter by a region ID.
     - in: query
       name: is_return
+      description: Filter by whether the shipping option is used for returns or orders.
       schema:
         type: boolean
-      description: Flag for fetching return options only
     - in: query
       name: admin_only
       schema:
         type: boolean
-      description: Flag for fetching admin specific options
+      description: Filter by whether the shipping option is used only by admins or not.
   x-codegen:
     method: list
     queryParams: AdminGetShippingOptionsParams
@@ -58,7 +60,7 @@ get:
 post:
   operationId: PostShippingOptions
   summary: Create Shipping Option
-  description: Creates a Shipping Option
+  description: Create a Shipping Option.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_shipping-options_{id}.yaml b/docs/api/admin/paths/admin_shipping-options_{id}.yaml
index 1e60a2fba7..9f36359ed6 100644
--- a/docs/api/admin/paths/admin_shipping-options_{id}.yaml
+++ b/docs/api/admin/paths/admin_shipping-options_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetShippingOptionsOption
   summary: Get a Shipping Option
-  description: Retrieves a Shipping Option.
+  description: Retrieve a Shipping Option's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,7 +48,7 @@ get:
 post:
   operationId: PostShippingOptionsOption
   summary: Update Shipping Option
-  description: Updates a Shipping Option
+  description: Update a Shipping Option's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -99,8 +99,10 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteShippingOptionsOption
-  summary: Delete a Shipping Option
-  description: Deletes a Shipping Option.
+  summary: Delete Shipping Option
+  description: >-
+    Delete a Shipping Option. Once deleted, it can't be used when creating
+    orders or returns.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_shipping-profiles.yaml b/docs/api/admin/paths/admin_shipping-profiles.yaml
index 43ce69665d..f2c7e866d9 100644
--- a/docs/api/admin/paths/admin_shipping-profiles.yaml
+++ b/docs/api/admin/paths/admin_shipping-profiles.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetShippingProfiles
   summary: List Shipping Profiles
-  description: Retrieves a list of Shipping Profile.
+  description: Retrieve a list of Shipping Profiles.
   x-authenticated: true
   x-codegen:
     method: list
@@ -41,7 +41,7 @@ get:
 post:
   operationId: PostShippingProfiles
   summary: Create a Shipping Profile
-  description: Creates a Shipping Profile
+  description: Create a Shipping Profile.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_shipping-profiles_{id}.yaml b/docs/api/admin/paths/admin_shipping-profiles_{id}.yaml
index 62fffb5901..bfbb8fbf27 100644
--- a/docs/api/admin/paths/admin_shipping-profiles_{id}.yaml
+++ b/docs/api/admin/paths/admin_shipping-profiles_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetShippingProfilesProfile
   summary: Get a Shipping Profile
-  description: Retrieves a Shipping Profile.
+  description: Retrieve a Shipping Profile's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,7 +48,7 @@ get:
 post:
   operationId: PostShippingProfilesProfile
   summary: Update a Shipping Profile
-  description: Updates a Shipping Profile
+  description: Update a Shipping Profile's details.
   parameters:
     - in: path
       name: id
@@ -99,7 +99,7 @@ post:
 delete:
   operationId: DeleteShippingProfilesProfile
   summary: Delete a Shipping Profile
-  description: Deletes a Shipping Profile.
+  description: Delete a Shipping Profile. Associated shipping options are deleted as well.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_stock-locations.yaml b/docs/api/admin/paths/admin_stock-locations.yaml
index 25cda8edc9..7d097465f9 100644
--- a/docs/api/admin/paths/admin_stock-locations.yaml
+++ b/docs/api/admin/paths/admin_stock-locations.yaml
@@ -1,27 +1,30 @@
 get:
   operationId: GetStockLocations
   summary: List Stock Locations
-  description: Retrieves a list of stock locations
+  description: >-
+    Retrieve a list of stock locations. The stock locations can be filtered by
+    fields such as `name` or `created_at`. The stock locations can also be
+    sorted or paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: id
-      description: ID of the stock location
+      description: Filter by ID.
       schema:
         type: string
     - in: query
       name: name
-      description: Name of the stock location
+      description: Filter by name.
       schema:
         type: string
     - in: query
       name: order
-      description: The field to order the results by.
+      description: A stock-location field to sort-order the retrieved stock locations by.
       schema:
         type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting collections were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -43,7 +46,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting collections were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -65,7 +68,7 @@ get:
             format: date
     - in: query
       name: deleted_at
-      description: Date comparison for when resulting collections were deleted.
+      description: Filter by a deletion date range.
       schema:
         type: object
         properties:
@@ -87,7 +90,9 @@ get:
             format: date
     - in: query
       name: offset
-      description: How many stock locations to skip in the result.
+      description: >-
+        The number of stock locations to skip when retrieving the stock
+        locations.
       schema:
         type: integer
         default: 0
@@ -100,15 +105,15 @@ get:
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each stock location
-        of the result.
+        Comma-separated relations that should be expanded in the returned stock
+        locations.
       schema:
         type: string
     - in: query
       name: fields
       description: >-
-        (Comma separated) Which fields should be included in each stock location
-        of the result.
+        Comma-separated fields that should be included in the returned stock
+        locations.
       schema:
         type: string
   x-codegen:
@@ -150,17 +155,21 @@ get:
 post:
   operationId: PostStockLocations
   summary: Create a Stock Location
-  description: Creates a Stock Location.
+  description: Create a Stock Location.
   x-authenticated: true
   parameters:
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned stock
+        location.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned stock
+        location.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/admin/paths/admin_stock-locations_{id}.yaml b/docs/api/admin/paths/admin_stock-locations_{id}.yaml
index eb46ce8a80..bca375ccd9 100644
--- a/docs/api/admin/paths/admin_stock-locations_{id}.yaml
+++ b/docs/api/admin/paths/admin_stock-locations_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetStockLocationsStockLocation
   summary: Get a Stock Location
-  description: Retrieves the Stock Location.
+  description: Retrieve a Stock Location's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -12,12 +12,16 @@ get:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned stock
+        location.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned stock
+        location.
       schema:
         type: string
   x-codegen:
@@ -47,7 +51,7 @@ get:
 post:
   operationId: PostStockLocationsStockLocation
   summary: Update a Stock Location
-  description: Updates a Stock Location.
+  description: Update a Stock Location's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -58,12 +62,16 @@ post:
         type: string
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned stock
+        location.
       schema:
         type: string
     - in: query
       name: fields
-      description: Comma separated list of fields to include in the results.
+      description: >-
+        Comma-separated fields that should be included in the returned stock
+        location.
       schema:
         type: string
   requestBody:
@@ -109,13 +117,13 @@ post:
 delete:
   operationId: DeleteStockLocationsStockLocation
   summary: Delete a Stock Location
-  description: Delete a Stock Location
+  description: Delete a Stock Location.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the Stock Location to delete.
+      description: The ID of the Stock Location.
       schema:
         type: string
   x-codeSamples:
@@ -138,18 +146,6 @@ delete:
       content:
         application/json:
           schema:
-            type: object
-            properties:
-              id:
-                type: string
-                description: The ID of the deleted Stock Location.
-              object:
-                type: string
-                description: The type of the object that was deleted.
-                format: stock_location
-              deleted:
-                type: boolean
-                description: Whether or not the Stock Location was deleted.
-                default: true
+            $ref: ../components/schemas/AdminStockLocationsDeleteRes.yaml
     '400':
       $ref: ../components/responses/400_error.yaml
diff --git a/docs/api/admin/paths/admin_store.yaml b/docs/api/admin/paths/admin_store.yaml
index ca274f0858..541e4e6b5a 100644
--- a/docs/api/admin/paths/admin_store.yaml
+++ b/docs/api/admin/paths/admin_store.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetStore
   summary: Get Store details
-  description: Retrieves the Store details
+  description: Retrieve the Store's details.
   x-authenticated: true
   x-codegen:
     method: retrieve
@@ -41,7 +41,7 @@ get:
 post:
   operationId: PostStore
   summary: Update Store Details
-  description: Updates the Store details
+  description: Update the Store's details.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_store_currencies_{code}.yaml b/docs/api/admin/paths/admin_store_currencies_{code}.yaml
index 7de11aecb5..7d9506393c 100644
--- a/docs/api/admin/paths/admin_store_currencies_{code}.yaml
+++ b/docs/api/admin/paths/admin_store_currencies_{code}.yaml
@@ -1,7 +1,11 @@
 post:
   operationId: PostStoreCurrenciesCode
   summary: Add a Currency Code
-  description: Adds a Currency Code to the available currencies.
+  description: >-
+    Add a Currency Code to the available currencies in a store. This does not
+    create new currencies, as currencies are defined within the Medusa backend.
+    To create a currency, you can create a migration that inserts the currency
+    into the database.
   x-authenticated: true
   parameters:
     - in: path
@@ -50,8 +54,11 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteStoreCurrenciesCode
-  summary: Delete a Currency Code
-  description: Removes a Currency Code from the available currencies.
+  summary: Remove a Currency
+  description: >-
+    Remove a Currency Code from the available currencies in a store. This does
+    not completely delete the currency and it can be added again later to the
+    store.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_store_payment-providers.yaml b/docs/api/admin/paths/admin_store_payment-providers.yaml
index 3383d39fdc..86277b9950 100644
--- a/docs/api/admin/paths/admin_store_payment-providers.yaml
+++ b/docs/api/admin/paths/admin_store_payment-providers.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetStorePaymentProviders
   summary: List Payment Providers
-  description: Retrieves the configured Payment Providers
+  description: Retrieve a list of available Payment Providers in a store.
   x-authenticated: true
   x-codegen:
     method: listPaymentProviders
diff --git a/docs/api/admin/paths/admin_store_tax-providers.yaml b/docs/api/admin/paths/admin_store_tax-providers.yaml
index 92b8f24717..5e528d0a1a 100644
--- a/docs/api/admin/paths/admin_store_tax-providers.yaml
+++ b/docs/api/admin/paths/admin_store_tax-providers.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetStoreTaxProviders
   summary: List Tax Providers
-  description: Retrieves the configured Tax Providers
+  description: Retrieve a list of available Tax Providers in a store.
   x-authenticated: true
   x-codegen:
     method: listTaxProviders
diff --git a/docs/api/admin/paths/admin_swaps.yaml b/docs/api/admin/paths/admin_swaps.yaml
index 5900eeddeb..4efa9383ae 100644
--- a/docs/api/admin/paths/admin_swaps.yaml
+++ b/docs/api/admin/paths/admin_swaps.yaml
@@ -1,17 +1,17 @@
 get:
   operationId: GetSwaps
   summary: List Swaps
-  description: Retrieves a list of Swaps.
+  description: Retrieve a list of Swaps. The swaps can be paginated.
   parameters:
     - in: query
       name: limit
-      description: The upper limit for the amount of responses returned.
+      description: Limit the number of swaps returned.
       schema:
         type: number
         default: '50'
     - in: query
       name: offset
-      description: The offset of the list returned.
+      description: The number of swaps to skip when retrieving the swaps.
       schema:
         type: number
         default: '0'
diff --git a/docs/api/admin/paths/admin_swaps_{id}.yaml b/docs/api/admin/paths/admin_swaps_{id}.yaml
index 81b6cbb83d..84086b8a15 100644
--- a/docs/api/admin/paths/admin_swaps_{id}.yaml
+++ b/docs/api/admin/paths/admin_swaps_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetSwapsSwap
   summary: Get a Swap
-  description: Retrieves a Swap.
+  description: Retrieve a Swap's details.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_tax-rates.yaml b/docs/api/admin/paths/admin_tax-rates.yaml
index 5df462522b..9abc43959b 100644
--- a/docs/api/admin/paths/admin_tax-rates.yaml
+++ b/docs/api/admin/paths/admin_tax-rates.yaml
@@ -1,19 +1,21 @@
 get:
   operationId: GetTaxRates
   summary: List Tax Rates
-  description: Retrieves a list of TaxRates
+  description: >-
+    Retrieve a list of Tax Rates. The tax rates can be filtered by fields such
+    as `name` or `rate`. The tax rates can also be paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: name
-      description: Name of tax rate to retrieve
+      description: Filter by name.
       schema:
         type: string
     - in: query
       name: region_id
       style: form
       explode: false
-      description: Filter by Region ID
+      description: Filter by Region IDs
       schema:
         oneOf:
           - type: string
@@ -22,7 +24,7 @@ get:
               type: string
     - in: query
       name: code
-      description: code to search for.
+      description: Filter by code.
       schema:
         type: string
     - in: query
@@ -49,7 +51,7 @@ get:
                 description: filter by rates greater than or equal to this number
     - in: query
       name: offset
-      description: How many tax rates to skip before retrieving the result.
+      description: The number of tax rates to skip when retrieving the tax rates.
       schema:
         type: integer
         default: 0
@@ -61,7 +63,7 @@ get:
         default: 50
     - in: query
       name: fields
-      description: Which fields should be included in each item.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -70,7 +72,9 @@ get:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved for each item.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
@@ -116,11 +120,11 @@ get:
 post:
   operationId: PostTaxRates
   summary: Create a Tax Rate
-  description: Creates a Tax Rate
+  description: Create a Tax Rate.
   parameters:
     - in: query
       name: fields
-      description: Which fields should be included in the result.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -129,7 +133,9 @@ post:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved in the result.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
diff --git a/docs/api/admin/paths/admin_tax-rates_{id}.yaml b/docs/api/admin/paths/admin_tax-rates_{id}.yaml
index 55f2fc7c3a..c53fb52af7 100644
--- a/docs/api/admin/paths/admin_tax-rates_{id}.yaml
+++ b/docs/api/admin/paths/admin_tax-rates_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetTaxRatesTaxRate
   summary: Get a Tax Rate
-  description: Retrieves a TaxRate
+  description: Retrieve a Tax Rate's details.
   parameters:
     - in: path
       name: id
@@ -11,7 +11,7 @@ get:
         type: string
     - in: query
       name: fields
-      description: Which fields should be included in the result.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -20,7 +20,9 @@ get:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved in the result.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
@@ -67,7 +69,7 @@ get:
 post:
   operationId: PostTaxRatesTaxRate
   summary: Update a Tax Rate
-  description: Updates a Tax Rate
+  description: Update a Tax Rate's details.
   parameters:
     - in: path
       name: id
@@ -77,7 +79,7 @@ post:
         type: string
     - in: query
       name: fields
-      description: Which fields should be included in the result.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -86,7 +88,9 @@ post:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved in the result.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
@@ -138,7 +142,9 @@ post:
 delete:
   operationId: DeleteTaxRatesTaxRate
   summary: Delete a Tax Rate
-  description: Deletes a Tax Rate
+  description: >-
+    Delete a Tax Rate. Resources associated with the tax rate, such as products
+    or product types, are not deleted.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_tax-rates_{id}_product-types_batch.yaml b/docs/api/admin/paths/admin_tax-rates_{id}_product-types_batch.yaml
index 65353a31ff..814b2775ee 100644
--- a/docs/api/admin/paths/admin_tax-rates_{id}_product-types_batch.yaml
+++ b/docs/api/admin/paths/admin_tax-rates_{id}_product-types_batch.yaml
@@ -11,7 +11,7 @@ post:
         type: string
     - in: query
       name: fields
-      description: Which fields should be included in the result.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -20,7 +20,9 @@ post:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved in the result.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
@@ -72,8 +74,11 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteTaxRatesTaxRateProductTypes
-  summary: Delete from Product Types
-  description: Removes a Tax Rate from a list of Product Types
+  summary: Remove Product Types from Rate
+  description: >-
+    Remove product types from a tax rate. This only removes the association
+    between the product types and the tax rate. It does not delete the product
+    types.
   parameters:
     - in: path
       name: id
@@ -83,7 +88,7 @@ delete:
         type: string
     - in: query
       name: fields
-      description: Which fields should be included in the result.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -92,7 +97,9 @@ delete:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved in the result.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
diff --git a/docs/api/admin/paths/admin_tax-rates_{id}_products_batch.yaml b/docs/api/admin/paths/admin_tax-rates_{id}_products_batch.yaml
index 6964aae553..78b1673f5a 100644
--- a/docs/api/admin/paths/admin_tax-rates_{id}_products_batch.yaml
+++ b/docs/api/admin/paths/admin_tax-rates_{id}_products_batch.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostTaxRatesTaxRateProducts
   summary: Add to Products
-  description: Associates a Tax Rate with a list of Products
+  description: Associates a Tax Rate with a list of Products.
   parameters:
     - in: path
       name: id
@@ -11,7 +11,7 @@ post:
         type: string
     - in: query
       name: fields
-      description: Which fields should be included in the result.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -20,7 +20,9 @@ post:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved in the result.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
@@ -71,8 +73,10 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteTaxRatesTaxRateProducts
-  summary: Delete from Products
-  description: Removes a Tax Rate from a list of Products
+  summary: Remove Products from Rate
+  description: >-
+    Remove products from a tax rate. This only removes the association between
+    the products and the tax rate. It does not delete the products.
   parameters:
     - in: path
       name: id
@@ -82,7 +86,7 @@ delete:
         type: string
     - in: query
       name: fields
-      description: Which fields should be included in the result.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -91,7 +95,9 @@ delete:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved in the result.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
diff --git a/docs/api/admin/paths/admin_tax-rates_{id}_shipping-options_batch.yaml b/docs/api/admin/paths/admin_tax-rates_{id}_shipping-options_batch.yaml
index fb306cbc84..999b74f802 100644
--- a/docs/api/admin/paths/admin_tax-rates_{id}_shipping-options_batch.yaml
+++ b/docs/api/admin/paths/admin_tax-rates_{id}_shipping-options_batch.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostTaxRatesTaxRateShippingOptions
   summary: Add to Shipping Options
-  description: Associates a Tax Rate with a list of Shipping Options
+  description: Associates a Tax Rate with a list of Shipping Options.
   parameters:
     - in: path
       name: id
@@ -11,7 +11,7 @@ post:
         type: string
     - in: query
       name: fields
-      description: Which fields should be included in the result.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -20,7 +20,9 @@ post:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved in the result.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
@@ -74,8 +76,11 @@ post:
       $ref: ../components/responses/500_error.yaml
 delete:
   operationId: DeleteTaxRatesTaxRateShippingOptions
-  summary: Del. for Shipping Options
-  description: Removes a Tax Rate from a list of Shipping Options
+  summary: Remove Shipping Options from Rate
+  description: >-
+    Remove shipping options from a tax rate. This only removes the association
+    between the shipping options and the tax rate. It does not delete the
+    shipping options.
   parameters:
     - in: path
       name: id
@@ -85,7 +90,7 @@ delete:
         type: string
     - in: query
       name: fields
-      description: Which fields should be included in the result.
+      description: Comma-separated fields that should be included in the returned tax rate.
       style: form
       explode: false
       schema:
@@ -94,7 +99,9 @@ delete:
           type: string
     - in: query
       name: expand
-      description: Which fields should be expanded and retrieved in the result.
+      description: >-
+        Comma-separated relations that should be expanded in the returned tax
+        rate.
       style: form
       explode: false
       schema:
diff --git a/docs/api/admin/paths/admin_uploads.yaml b/docs/api/admin/paths/admin_uploads.yaml
index 3a64ca4ea0..35f2bc9fda 100644
--- a/docs/api/admin/paths/admin_uploads.yaml
+++ b/docs/api/admin/paths/admin_uploads.yaml
@@ -1,9 +1,9 @@
 post:
   operationId: PostUploads
-  summary: Upload files
+  summary: Upload Files
   description: >-
-    Uploads at least one file to the specific fileservice that is installed in
-    Medusa.
+    Upload at least one file to a public bucket or storage. The file upload is
+    handled by the file service installed on the Medusa backend.
   x-authenticated: true
   requestBody:
     content:
@@ -50,7 +50,9 @@ post:
 delete:
   operationId: DeleteUploads
   summary: Delete an Uploaded File
-  description: Removes an uploaded file using the installed fileservice
+  description: >-
+    Delete an uploaded file from storage. The file is deleted using the
+    installed file service on the Medusa backend.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_uploads_download-url.yaml b/docs/api/admin/paths/admin_uploads_download-url.yaml
index edbaa161ec..8d28275aa1 100644
--- a/docs/api/admin/paths/admin_uploads_download-url.yaml
+++ b/docs/api/admin/paths/admin_uploads_download-url.yaml
@@ -1,7 +1,9 @@
 post:
   operationId: PostUploadsDownloadUrl
   summary: Get a File's Download URL
-  description: Creates a presigned download url for a file
+  description: >-
+    Create and retrieve a presigned or public download URL for a file. The URL
+    creation is handled by the file service installed on the Medusa backend.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_uploads_protected.yaml b/docs/api/admin/paths/admin_uploads_protected.yaml
index 5abe78c59b..e3ce2c20a1 100644
--- a/docs/api/admin/paths/admin_uploads_protected.yaml
+++ b/docs/api/admin/paths/admin_uploads_protected.yaml
@@ -2,8 +2,8 @@ post:
   operationId: PostUploadsProtected
   summary: Protected File Upload
   description: >-
-    Uploads at least one file with ACL or a non-public bucket to the specific
-    fileservice that is installed in Medusa.
+    Upload at least one file to an ACL or a non-public bucket. The file upload
+    is handled by the file service installed on the Medusa backend.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_users.yaml b/docs/api/admin/paths/admin_users.yaml
index d4af942bb4..7aea151912 100644
--- a/docs/api/admin/paths/admin_users.yaml
+++ b/docs/api/admin/paths/admin_users.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetUsers
   summary: List Users
-  description: Retrieves all users.
+  description: Retrieve all admin users.
   x-authenticated: true
   x-codegen:
     method: list
@@ -41,7 +41,10 @@ get:
 post:
   operationId: PostUsers
   summary: Create a User
-  description: Creates a User
+  description: >-
+    Create an admin User. The user has the same privileges as all admin users,
+    and will be able to authenticate and perform admin functionalities right
+    after creation.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/admin/paths/admin_users_password-token.yaml b/docs/api/admin/paths/admin_users_password-token.yaml
index 971f0e252d..92f832aa4b 100644
--- a/docs/api/admin/paths/admin_users_password-token.yaml
+++ b/docs/api/admin/paths/admin_users_password-token.yaml
@@ -1,8 +1,11 @@
 post:
   operationId: PostUsersUserPasswordToken
   summary: Request Password Reset
-  description: Generates a password token for a User with a given email.
-  x-authenticated: true
+  description: Generate a password token for an admin user with a given email.
+  externalDocs:
+    description: How to reset a user's password
+    url: >-
+      https://docs.medusajs.com/modules/users/admin/manage-profile#reset-password
   requestBody:
     content:
       application/json:
diff --git a/docs/api/admin/paths/admin_users_reset-password.yaml b/docs/api/admin/paths/admin_users_reset-password.yaml
index ac3a677e1d..d87a242f86 100644
--- a/docs/api/admin/paths/admin_users_reset-password.yaml
+++ b/docs/api/admin/paths/admin_users_reset-password.yaml
@@ -1,8 +1,14 @@
 post:
   operationId: PostUsersUserPassword
   summary: Reset Password
-  description: Sets the password for a User given the correct token.
-  x-authenticated: true
+  description: >-
+    Reset the password of an admin User using their reset password token. A user
+    must request to reset their password first before attempting to reset their
+    password with this request.
+  externalDocs:
+    description: How to reset a user's password
+    url: >-
+      https://docs.medusajs.com/modules/users/admin/manage-profile#reset-password
   requestBody:
     content:
       application/json:
diff --git a/docs/api/admin/paths/admin_users_{id}.yaml b/docs/api/admin/paths/admin_users_{id}.yaml
index fa32500a69..1c08ceee4c 100644
--- a/docs/api/admin/paths/admin_users_{id}.yaml
+++ b/docs/api/admin/paths/admin_users_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetUsersUser
   summary: Get a User
-  description: Retrieves a User.
+  description: Retrieve an admin user's details.
   x-authenticated: true
   parameters:
     - in: path
@@ -48,7 +48,7 @@ get:
 post:
   operationId: PostUsersUser
   summary: Update a User
-  description: Updates a User
+  description: Update an admin user's details.
   parameters:
     - in: path
       name: id
@@ -100,7 +100,9 @@ post:
 delete:
   operationId: DeleteUsersUser
   summary: Delete a User
-  description: Deletes a User
+  description: >-
+    Delete a User. Once deleted, the user will not be able to authenticate or
+    perform admin functionalities.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/admin/paths/admin_variants.yaml b/docs/api/admin/paths/admin_variants.yaml
index 463d26a7e6..d713a004b9 100644
--- a/docs/api/admin/paths/admin_variants.yaml
+++ b/docs/api/admin/paths/admin_variants.yaml
@@ -1,72 +1,105 @@
 get:
   operationId: GetVariants
   summary: List Product Variants
-  description: Retrieves a list of Product Variants
+  description: >-
+    Retrieve a list of Product Variants. The product variant can be filtered by
+    fields such as `id` or `title`. The product variant can also be paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: id
-      description: A Product Variant id to filter by.
+      style: form
+      explode: false
+      description: Filter by product variant IDs.
       schema:
-        type: string
-    - in: query
-      name: ids
-      description: A comma separated list of Product Variant ids to filter by.
-      schema:
-        type: string
+        oneOf:
+          - type: string
+            description: A product variant ID.
+          - type: array
+            description: An array of product variant IDs.
+            items:
+              type: string
     - in: query
       name: expand
-      description: A comma separated list of Product Variant relations to load.
+      description: >-
+        "Comma-separated relations that should be expanded in the returned
+        product variants."
       schema:
         type: string
     - in: query
       name: fields
-      description: A comma separated list of Product Variant fields to include.
+      description: >-
+        "Comma-separated fields that should be included in the returned product
+        variants."
       schema:
         type: string
     - in: query
       name: offset
-      description: How many product variants to skip in the result.
+      description: >-
+        The number of product variants to skip when retrieving the product
+        variants.
       schema:
         type: number
         default: '0'
     - in: query
       name: limit
-      description: Maximum number of Product Variants to return.
+      description: Limit the number of product variants returned.
       schema:
         type: number
         default: '100'
     - in: query
       name: cart_id
-      description: The id of the cart to use for price selection.
+      style: form
+      explode: false
+      description: The ID of the cart to use for the price selection context.
       schema:
         type: string
     - in: query
       name: region_id
-      description: The id of the region to use for price selection.
+      style: form
+      explode: false
+      description: The ID of the region to use for the price selection context.
       schema:
         type: string
+        externalDocs:
+          description: Price selection context overview
+          url: >-
+            https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object
     - in: query
       name: currency_code
-      description: The currency code to use for price selection.
+      style: form
+      explode: false
+      description: >-
+        The 3 character ISO currency code to use for the price selection
+        context.
       schema:
         type: string
+        externalDocs:
+          description: Price selection context overview
+          url: >-
+            https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object
     - in: query
       name: customer_id
-      description: The id of the customer to use for price selection.
+      style: form
+      explode: false
+      description: The ID of the customer to use for the price selection context.
       schema:
         type: string
+        externalDocs:
+          description: Price selection context overview
+          url: >-
+            https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object
     - in: query
       name: title
       style: form
       explode: false
-      description: product variant title to search for.
+      description: Filter by title.
       schema:
         oneOf:
           - type: string
-            description: a single title to search by
+            description: a single title to filter by
           - type: array
-            description: multiple titles to search by
+            description: multiple titles to filter by
             items:
               type: string
     - in: query
@@ -75,9 +108,9 @@ get:
       schema:
         oneOf:
           - type: number
-            description: a specific number to search by.
+            description: a specific number to filter by.
           - type: object
-            description: search using less and greater than comparisons.
+            description: filter using less and greater than comparisons.
             properties:
               lt:
                 type: number
@@ -109,7 +142,7 @@ get:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Variants
+    - Product Variants
   responses:
     '200':
       description: OK
diff --git a/docs/api/admin/paths/admin_variants_{id}.yaml b/docs/api/admin/paths/admin_variants_{id}.yaml
index dbe1b381c5..2a241cf038 100644
--- a/docs/api/admin/paths/admin_variants_{id}.yaml
+++ b/docs/api/admin/paths/admin_variants_{id}.yaml
@@ -1,27 +1,27 @@
 get:
   operationId: GetVariantsVariant
   summary: Get a Product variant
-  description: Retrieves a Product variant.
+  description: Retrieve a product variant's details.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The ID of the variant.
+      description: The ID of the product variant.
       schema:
         type: string
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded the order of the
-        result.
+        "Comma-separated relations that should be expanded in the returned
+        product variant."
       schema:
         type: string
     - in: query
       name: fields
       description: >-
-        (Comma separated) Which fields should be included the order of the
-        result.
+        "Comma-separated fields that should be included in the returned product
+        variant."
       schema:
         type: string
   x-codegen:
@@ -40,7 +40,7 @@ get:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Products
+    - Product Variants
   responses:
     '200':
       description: OK
diff --git a/docs/api/admin/paths/admin_variants_{id}_inventory.yaml b/docs/api/admin/paths/admin_variants_{id}_inventory.yaml
index b2e311fceb..9721de7cee 100644
--- a/docs/api/admin/paths/admin_variants_{id}_inventory.yaml
+++ b/docs/api/admin/paths/admin_variants_{id}_inventory.yaml
@@ -1,13 +1,13 @@
 get:
   operationId: GetVariantsVariantInventory
-  summary: Get inventory of Variant.
-  description: Returns the available inventory of a Variant.
+  summary: Get Variant's Inventory
+  description: Retrieve the available inventory of a Product Variant.
   x-authenticated: true
   parameters:
     - in: path
       name: id
       required: true
-      description: The Product Variant id to get inventory for.
+      description: The Product Variant ID.
       schema:
         type: string
   x-codegen:
@@ -25,7 +25,7 @@ get:
     - api_token: []
     - cookie_auth: []
   tags:
-    - Variants
+    - Product Variants
   responses:
     '200':
       description: OK
diff --git a/docs/api/store.oas.json b/docs/api/store.oas.json
index 3ca6fed2cc..4a5174ee15 100644
--- a/docs/api/store.oas.json
+++ b/docs/api/store.oas.json
@@ -12,55 +12,123 @@
   "tags": [
     {
       "name": "Auth",
-      "description": "Auth endpoints that allow authorization of customers and manages their sessions."
+      "description": "Authentication endpoints allow customers to manage their session, such as login or log out.\nWhen a customer is logged in, the cookie header is set indicating the customer's login session.\n",
+      "externalDocs": {
+        "description": "How to implement customer profiles in your storefront",
+        "url": "https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles"
+      }
     },
     {
       "name": "Carts",
-      "description": "Cart endpoints that allow handling carts in Medusa."
-    },
-    {
-      "name": "Collections",
-      "description": "Collection endpoints that allow handling collections in Medusa."
+      "description": "A cart is a virtual shopping bag that customers can use to add items they want to purchase.\nA cart is then used to checkout and place an order.\n",
+      "externalDocs": {
+        "description": "How to implement cart functionality in your storefront",
+        "url": "https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-cart"
+      }
     },
     {
       "name": "Customers",
-      "description": "Customer endpoints that allow handling customers in Medusa."
+      "description": "A customer can register and manage their information such as addresses, orders, payment methods, and more.\n",
+      "externalDocs": {
+        "description": "How to implement customer profiles in your storefront",
+        "url": "https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles"
+      }
     },
     {
       "name": "Gift Cards",
-      "description": "Gift Card endpoints that allow handling gift cards in Medusa."
+      "description": "Customers can use gift cards during checkout to deduct the gift card's balance from the checkout total.\nThe Gift Card endpoints allow retrieving a gift card's details by its code. A gift card can be applied to a cart using the Carts endpoints.\n",
+      "externalDocs": {
+        "description": "How to use gift cards in a storefront",
+        "url": "https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards"
+      }
     },
     {
       "name": "Orders",
-      "description": "Order endpoints that allow handling orders in Medusa."
+      "description": "Orders are purchases made by customers, typically through a storefront.\nOrders are placed and created using the Carts endpoints. The Orders endpoints allow retrieving and claiming orders.\n",
+      "externalDocs": {
+        "description": "How to retrieve order details in a storefront",
+        "url": "https://docs.medusajs.com/modules/orders/storefront/retrieve-order-details"
+      }
+    },
+    {
+      "name": "Order Edits",
+      "description": "Order edits are changes made to items in an order such as adding, updating their quantity, or deleting them. Order edits are created by the admin.\nA customer can review order edit requests created by an admin and confirm or decline them.\n",
+      "externalDocs": {
+        "description": "How to handle order edits in a storefront",
+        "url": "https://docs.medusajs.com/modules/orders/storefront/handle-order-edits"
+      }
+    },
+    {
+      "name": "Payment Collections",
+      "description": "A payment collection is useful for managing additional payments, such as for Order Edits, or installment payments.\n"
     },
     {
       "name": "Products",
-      "description": "Product endpoints that allow handling products in Medusa."
+      "description": "Products are saleable items in a store. This also includes [saleable gift cards](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards) in a store.\nUsing these endpoints, you can filter products by categories, collections, sales channels, and more.\n",
+      "externalDocs": {
+        "description": "How to show products in a storefront",
+        "url": "https://docs.medusajs.com/modules/products/storefront/show-products"
+      }
     },
     {
       "name": "Product Variants",
-      "description": "Product Variant endpoints that allow handling product variants in Medusa."
+      "description": "Product variants are the actual salable item in your store. Each variant is a combination of the different option values available on the product.\n"
+    },
+    {
+      "name": "Product Categories",
+      "description": "Products can be categoriezed into categories. A product can be associated more than one category.\nUsing these endpoints, you can list or retrieve a category's details and products.\n",
+      "externalDocs": {
+        "description": "How to use product categories in a storefront",
+        "url": "https://docs.medusajs.com/modules/products/storefront/use-categories"
+      }
+    },
+    {
+      "name": "Product Collections",
+      "description": "A product collection is used to organize products for different purposes such as marketing or discount purposes. For example, you can create a Summer Collection.\nUsing these endpoints, you can list or retrieve a collection's details and products.\n"
+    },
+    {
+      "name": "Product Tags",
+      "description": "Product tags are string values that can be used to filter products by.\nProducts can have more than one tag, and products can share tags.\n"
+    },
+    {
+      "name": "Product Types",
+      "description": "Product types are string values that can be used to filter products by.\nProducts can have more than one tag, and products can share types.\n"
     },
     {
       "name": "Regions",
-      "description": "Region endpoints that allow handling regions in Medusa."
-    },
-    {
-      "name": "Return Reasons",
-      "description": "Return Reason endpoints that allow handling return reasons in Medusa."
+      "description": "Regions are different countries or geographical regions that the commerce store serves customers in.\nCustomers can choose what region they're in, which can be used to change the prices shown based on the region and its currency.\n",
+      "externalDocs": {
+        "description": "How to use regions in a storefront",
+        "url": "https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions"
+      }
     },
     {
       "name": "Returns",
-      "description": "Return endpoints that allow handling returns in Medusa."
+      "description": "A return can be created by a customer to return items in an order.\n",
+      "externalDocs": {
+        "description": "How to create a return in a storefront",
+        "url": "https://docs.medusajs.com/modules/orders/storefront/create-return"
+      }
+    },
+    {
+      "name": "Return Reasons",
+      "description": "Return reasons are key-value pairs that are used to specify why an order return is being created.\n"
     },
     {
       "name": "Shipping Options",
-      "description": "Shipping Option endpoints that allow handling shipping options in Medusa."
+      "description": "A shipping option is used to define the available shipping methods during checkout or when creating a return.\n",
+      "externalDocs": {
+        "description": "Shipping Option architecture",
+        "url": "https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option"
+      }
     },
     {
       "name": "Swaps",
-      "description": "Swap endpoints that allow handling swaps in Medusa."
+      "description": "A swap is created by a customer or an admin to exchange an item with a new one.\nCreating a swap implicitely includes creating a return for the item being exchanged.\n",
+      "externalDocs": {
+        "description": "How to create a swap in a storefront",
+        "url": "https://docs.medusajs.com/modules/orders/storefront/create-swap"
+      }
     }
   ],
   "servers": [
@@ -73,7 +141,7 @@
       "get": {
         "operationId": "GetAuth",
         "summary": "Get Current Customer",
-        "description": "Gets the currently logged in Customer.",
+        "description": "Retrieve the currently logged in Customer's details.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "getSession"
@@ -87,7 +155,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/auth' \\\n--header 'Cookie: connect.sid={sid}'\n"
+            "source": "curl 'https://medusa-url.com/store/auth' \\\n-H 'Cookie: connect.sid={sid}'\n"
           }
         ],
         "security": [
@@ -132,7 +200,7 @@
       "post": {
         "operationId": "PostAuth",
         "summary": "Customer Login",
-        "description": "Logs a Customer in and authorizes them to view their details. Successful authentication will set a session cookie in the Customer's browser.",
+        "description": "Log a customer in and includes the Cookie session in the response header. The cookie session can be used in subsequent requests to authenticate the customer. When using Medusa's JS or Medusa React clients, the cookie is automatically attached to subsequent requests.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -149,12 +217,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.auth.authenticate({\n  email: 'user@example.com',\n  password: 'user@example.com'\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.auth.authenticate({\n  email: \"user@example.com\",\n  password: \"user@example.com\"\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/auth' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"password\": \"supersecret\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/auth' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"password\": \"supersecret\"\n}'\n"
           }
         ],
         "tags": [
@@ -194,7 +262,7 @@
       "delete": {
         "operationId": "DeleteAuth",
         "summary": "Customer Log out",
-        "description": "Destroys a Customer's authenticated session.",
+        "description": "Delete the current session for the logged in customer.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "deleteSession"
@@ -203,7 +271,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/store/auth' \\\n--header 'Cookie: connect.sid={sid}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/store/auth' \\\n-H 'Cookie: connect.sid={sid}'\n"
           }
         ],
         "security": [
@@ -242,8 +310,8 @@
     "/store/auth/{email}": {
       "get": {
         "operationId": "GetAuthEmail",
-        "summary": "Check if email exists",
-        "description": "Checks if a Customer with the given email has signed up.",
+        "summary": "Check if Email Exists",
+        "description": "Check if there's a customer already registered with the provided email.",
         "parameters": [
           {
             "in": "path",
@@ -253,7 +321,7 @@
               "format": "email"
             },
             "required": true,
-            "description": "The email to check if exists."
+            "description": "The email to check."
           }
         ],
         "x-codegen": {
@@ -263,12 +331,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.auth.exists('user@example.com')\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.auth.exists(\"user@example.com\")\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/auth/user@example.com' \\\n--header 'Cookie: connect.sid={sid}'\n"
+            "source": "curl 'https://medusa-url.com/store/auth/user@example.com'\n"
           }
         ],
         "tags": [
@@ -305,9 +373,9 @@
     },
     "/store/carts": {
       "post": {
-        "summary": "Create a Cart",
         "operationId": "PostCart",
-        "description": "Creates a Cart within the given region and with the initial items. If no `region_id` is provided the cart will be associated with the first Region available. If no items are provided the cart will be empty after creation. If a user is logged in the cart's customer id and email will be set.",
+        "summary": "Create a Cart",
+        "description": "Create a Cart. Although optional, specifying the cart's region and sales channel can affect the cart's pricing and\nthe products that can be added to the cart respectively. So, make sure to set those early on and change them if necessary, such as when the customer changes their region.\n\nIf a customer is logged in, the cart's customer ID and email will automatically be set.\n",
         "requestBody": {
           "content": {
             "application/json": {
@@ -329,7 +397,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts'\n"
           }
         ],
         "tags": [
@@ -368,13 +436,13 @@
       "get": {
         "operationId": "GetCartsCart",
         "summary": "Get a Cart",
-        "description": "Retrieves a Cart.",
+        "description": "Retrieve a Cart's details. This includes recalculating its totals.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -387,12 +455,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.retrieve(cart_id)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.retrieve(cartId)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/carts/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/carts/{id}'\n"
           }
         ],
         "tags": [
@@ -429,13 +497,13 @@
       "post": {
         "operationId": "PostCartsCart",
         "summary": "Update a Cart",
-        "description": "Updates a Cart.",
+        "description": "Update a Cart's details. If the cart has payment sessions and the region was not changed, the payment sessions are updated. The cart's totals are also recalculated.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -457,12 +525,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.update(cart_id, {\n  email: 'user@example.com'\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.update(cartId, {\n  email: \"user@example.com\"\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
           }
         ],
         "tags": [
@@ -501,13 +569,17 @@
       "post": {
         "summary": "Complete a Cart",
         "operationId": "PostCartsCartComplete",
-        "description": "Completes a cart. The following steps will be performed. Payment authorization is attempted and if more work is required, we simply return the cart for further updates. If payment is authorized and order is not yet created, we make sure to do so. The completion of a cart can be performed idempotently with a provided header `Idempotency-Key`. If not provided, we will generate one for the request.",
+        "description": "Complete a cart and place an order or create a swap, based on what the cart is created for. This includes attempting to authorize the cart's payment.\nIf authorizing the payment requires more action, the cart will not be completed and the order will not be placed or the swap will not be created.\n\nAn idempotency key will be generated if none is provided in the header `Idempotency-Key` and added to\nthe response. If an error occurs during cart completion or the request is interrupted for any reason, the cart completion can be retried by passing the idempotency\nkey in the `Idempotency-Key` header.\n",
+        "externalDocs": {
+          "description": "Cart completion overview",
+          "url": "https://docs.medusajs.com/modules/carts-and-checkout/cart#cart-completion"
+        },
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The Cart id.",
+            "description": "The Cart ID.",
             "schema": {
               "type": "string"
             }
@@ -520,12 +592,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.complete(cart_id)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.complete(cartId)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}/complete'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/complete'\n"
           }
         ],
         "tags": [
@@ -533,7 +605,7 @@
         ],
         "responses": {
           "200": {
-            "description": "If a cart was successfully authorized, but requires further action from the user the response body will contain the cart with an updated payment session. If the Cart was successfully completed the response body will contain the newly created Order.",
+            "description": "If the payment of the cart was successfully authorized, but requires further action from the customer, the response body will contain the cart with an updated payment session. Otherwise, if the payment was authorized and the cart was successfully completed, the response body will contain either the newly created order or swap, depending on what the cart was created for.",
             "content": {
               "application/json": {
                 "schema": {
@@ -563,14 +635,14 @@
     "/store/carts/{id}/discounts/{code}": {
       "delete": {
         "operationId": "DeleteCartsCartDiscountsDiscount",
-        "description": "Removes a Discount from a Cart.",
         "summary": "Remove Discount",
+        "description": "Remove a Discount from a Cart. This only removes the application of the discount, and not completely delete it. The totals will be re-calculated and the payment sessions will be refreshed after the removal.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -579,7 +651,7 @@
             "in": "path",
             "name": "code",
             "required": true,
-            "description": "The unique Discount code.",
+            "description": "The unique discount code.",
             "schema": {
               "type": "string"
             }
@@ -592,12 +664,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.deleteDiscount(cart_id, code)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.deleteDiscount(cartId, code)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/store/carts/{id}/discounts/{code}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/store/carts/{id}/discounts/{code}'\n"
           }
         ],
         "tags": [
@@ -669,7 +741,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}/line-items' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"variant_id\": \"{variant_id}\",\n    \"quantity\": 1\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/line-items' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"variant_id\": \"{variant_id}\",\n    \"quantity\": 1\n}'\n"
           }
         ],
         "tags": [
@@ -708,13 +780,13 @@
       "post": {
         "operationId": "PostCartsCartLineItemsItem",
         "summary": "Update a Line Item",
-        "description": "Updates a Line Item if the desired quantity can be fulfilled.",
+        "description": "Update a line item's quantity.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -723,7 +795,7 @@
             "in": "path",
             "name": "line_id",
             "required": true,
-            "description": "The id of the Line Item.",
+            "description": "The ID of the Line Item.",
             "schema": {
               "type": "string"
             }
@@ -745,12 +817,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.lineItems.update(cart_id, line_id, {\n  quantity: 1\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.lineItems.update(cartId, lineId, {\n  quantity: 1\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"quantity\": 1\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"quantity\": 1\n}'\n"
           }
         ],
         "tags": [
@@ -787,13 +859,13 @@
       "delete": {
         "operationId": "DeleteCartsCartLineItemsItem",
         "summary": "Delete a Line Item",
-        "description": "Removes a Line Item from a Cart.",
+        "description": "Delete a Line Item from a Cart. The payment sessions will be updated and the totals will be recalculated.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -802,7 +874,7 @@
             "in": "path",
             "name": "line_id",
             "required": true,
-            "description": "The id of the Line Item.",
+            "description": "The ID of the Line Item.",
             "schema": {
               "type": "string"
             }
@@ -815,12 +887,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.lineItems.delete(cart_id, line_id)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.lineItems.delete(cartId, lineId)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}'\n"
           }
         ],
         "tags": [
@@ -859,7 +931,7 @@
       "post": {
         "operationId": "PostCartsCartPaymentSession",
         "summary": "Select a Payment Session",
-        "description": "Selects a Payment Session as the session intended to be used towards the completion of the Cart.",
+        "description": "Select the Payment Session that will be used to complete the cart. This is typically used when the customer chooses their preferred payment method during checkout. The totals of the cart will be recalculated.",
         "parameters": [
           {
             "in": "path",
@@ -887,12 +959,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.setPaymentSession(cart_id, {\n  provider_id: 'manual'\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.setPaymentSession(cartId, {\n  provider_id: \"manual\"\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}/payment-sessions' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"provider_id\": \"manual\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"provider_id\": \"manual\"\n}'\n"
           }
         ],
         "tags": [
@@ -931,13 +1003,13 @@
       "post": {
         "operationId": "PostCartsCartPaymentSessions",
         "summary": "Create Payment Sessions",
-        "description": "Creates Payment Sessions for each of the available Payment Providers in the Cart's Region.",
+        "description": "Create Payment Sessions for each of the available Payment Providers in the Cart's Region. If there only one payment session is created, it will be selected by default. The creation of the payment session uses the payment provider and may require sending requests to third-party services.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -950,12 +1022,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.createPaymentSessions(cart_id)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.createPaymentSessions(cartId)\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}/payment-sessions'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions'\n"
           }
         ],
         "tags": [
@@ -994,13 +1066,13 @@
       "post": {
         "operationId": "PostCartsCartPaymentSessionUpdate",
         "summary": "Update a Payment Session",
-        "description": "Updates a Payment Session with additional data.",
+        "description": "Update a Payment Session with additional data. This can be useful depending on the payment provider used. All payment sessions are updated and cart totals are recalculated afterwards.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -1009,7 +1081,7 @@
             "in": "path",
             "name": "provider_id",
             "required": true,
-            "description": "The id of the payment provider.",
+            "description": "The ID of the payment provider.",
             "schema": {
               "type": "string"
             }
@@ -1031,12 +1103,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.updatePaymentSession(cart_id, 'manual', {\n  data: {\n\n  }\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.updatePaymentSession(cartId, \"manual\", {\n  data: {\n\n  }\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/manual' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"data\": {}\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/manual' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"data\": {}\n}'\n"
           }
         ],
         "tags": [
@@ -1073,13 +1145,13 @@
       "delete": {
         "operationId": "DeleteCartsCartPaymentSessionsSession",
         "summary": "Delete a Payment Session",
-        "description": "Deletes a Payment Session on a Cart. May be useful if a payment has failed.",
+        "description": "Delete a Payment Session in a Cart. May be useful if a payment has failed. The totals will be recalculated.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -1088,7 +1160,7 @@
             "in": "path",
             "name": "provider_id",
             "required": true,
-            "description": "The id of the Payment Provider used to create the Payment Session to be deleted.",
+            "description": "The ID of the Payment Provider used to create the Payment Session to be deleted.",
             "schema": {
               "type": "string"
             }
@@ -1101,12 +1173,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.deletePaymentSession(cart_id, 'manual')\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.deletePaymentSession(cartId, \"manual\")\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/store/carts/{id}/payment-sessions/manual'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/store/carts/{id}/payment-sessions/{provider_id}'\n"
           }
         ],
         "tags": [
@@ -1145,13 +1217,13 @@
       "post": {
         "operationId": "PostCartsCartPaymentSessionsSession",
         "summary": "Refresh a Payment Session",
-        "description": "Refreshes a Payment Session to ensure that it is in sync with the Cart - this is usually not necessary.",
+        "description": "Refresh a Payment Session to ensure that it is in sync with the Cart. This is usually not necessary, but is provided for edge cases.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -1160,7 +1232,7 @@
             "in": "path",
             "name": "provider_id",
             "required": true,
-            "description": "The id of the Payment Provider that created the Payment Session to be refreshed.",
+            "description": "The ID of the Payment Provider that created the Payment Session to be refreshed.",
             "schema": {
               "type": "string"
             }
@@ -1173,12 +1245,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.refreshPaymentSession(cart_id, 'manual')\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.refreshPaymentSession(cartId, \"manual\")\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/manual/refresh'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/{provider_id}/refresh'\n"
           }
         ],
         "tags": [
@@ -1216,8 +1288,8 @@
     "/store/carts/{id}/shipping-methods": {
       "post": {
         "operationId": "PostCartsCartShippingMethod",
-        "description": "Adds a Shipping Method to the Cart.",
-        "summary": "Add a Shipping Method",
+        "summary": "Add Shipping Method",
+        "description": "Add a Shipping Method to the Cart. The validation of the `data` field is handled by the fulfillment provider of the chosen shipping option.",
         "parameters": [
           {
             "in": "path",
@@ -1245,12 +1317,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.addShippingMethod(cart_id, {\n  option_id\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.addShippingMethod(cartId, {\n  option_id\n})\n.then(({ cart }) => {\n  console.log(cart.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}/shipping-methods' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"option_id\": \"{option_id}\",\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/shipping-methods' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"option_id\": \"{option_id}\",\n}'\n"
           }
         ],
         "tags": [
@@ -1287,9 +1359,13 @@
     },
     "/store/carts/{id}/taxes": {
       "post": {
-        "summary": "Calculate Cart Taxes",
         "operationId": "PostCartsCartTaxes",
-        "description": "Calculates taxes for a cart. Depending on the cart's region this may involve making 3rd party API calls to a Tax Provider service.",
+        "summary": "Calculate Cart Taxes",
+        "description": "Calculate the taxes for a cart. This is useful if the `automatic_taxes` field of the cart's region is set to `false`. If the cart's region uses a tax provider other than Medusa's system provider, this may lead to sending requests to third-party services.",
+        "externalDocs": {
+          "description": "How to calculate taxes manually during checkout",
+          "url": "https://docs.medusajs.com/modules/taxes/storefront/manual-calculation"
+        },
         "parameters": [
           {
             "in": "path",
@@ -1308,7 +1384,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/carts/{id}/taxes'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/taxes'\n"
           }
         ],
         "tags": [
@@ -1347,12 +1423,12 @@
       "get": {
         "operationId": "GetCollections",
         "summary": "List Collections",
-        "description": "Retrieve a list of Product Collection.",
+        "description": "Retrieve a list of product collections. The product collections can be filtered by fields such as `handle` or `created_at`. The product collections can also be paginated.",
         "parameters": [
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of collections to skip before starting to collect the collections set",
+            "description": "The number of product collections to skip when retrieving the product collections.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -1361,7 +1437,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of collections to return",
+            "description": "Limit the number of product collections returned.",
             "schema": {
               "type": "integer",
               "default": 10
@@ -1372,7 +1448,7 @@
             "name": "handle",
             "style": "form",
             "explode": false,
-            "description": "Filter by the collection handle",
+            "description": "Filter by handles",
             "schema": {
               "type": "array",
               "items": {
@@ -1383,7 +1459,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting collections were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -1413,7 +1489,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting collections were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -1454,11 +1530,11 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/collections'\n"
+            "source": "curl 'https://medusa-url.com/store/collections'\n"
           }
         ],
         "tags": [
-          "Collections"
+          "Product Collections"
         ],
         "responses": {
           "200": {
@@ -1493,7 +1569,7 @@
       "get": {
         "operationId": "GetCollectionsCollection",
         "summary": "Get a Collection",
-        "description": "Retrieves a Product Collection.",
+        "description": "Retrieve a Product Collection's details.",
         "parameters": [
           {
             "in": "path",
@@ -1512,16 +1588,16 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.collections.retrieve(collection_id)\n.then(({ collection }) => {\n  console.log(collection.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.collections.retrieve(collectionId)\n.then(({ collection }) => {\n  console.log(collection.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/collections/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/collections/{id}'\n"
           }
         ],
         "tags": [
-          "Collections"
+          "Product Collections"
         ],
         "responses": {
           "200": {
@@ -1556,7 +1632,7 @@
       "post": {
         "operationId": "PostCustomers",
         "summary": "Create a Customer",
-        "description": "Creates a Customer account.",
+        "description": "Register a new customer. This will also automatically authenticate the customer and set their login session in the response Cookie header. The cookie session can be used in subsequent requests to authenticate the customer. When using Medusa's JS or Medusa React clients, the cookie is automatically attached to subsequent requests.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -1573,12 +1649,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.customers.create({\n  first_name: 'Alec',\n  last_name: 'Reynolds',\n  email: 'user@example.com',\n  password: 'supersecret'\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.customers.create({\n  first_name: \"Alec\",\n  last_name: \"Reynolds\",\n  email: \"user@example.com\",\n  password: \"supersecret\"\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/customers' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Alec\",\n    \"last_name\": \"Reynolds\",\n    \"email\": \"user@example.com\",\n    \"password\": \"supersecret\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/customers' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Alec\",\n    \"last_name\": \"Reynolds\",\n    \"email\": \"user@example.com\",\n    \"password\": \"supersecret\"\n}'\n"
           }
         ],
         "tags": [
@@ -1643,7 +1719,7 @@
       "get": {
         "operationId": "GetCustomersCustomer",
         "summary": "Get a Customer",
-        "description": "Retrieves a Customer - the Customer must be logged in to retrieve their details.",
+        "description": "Retrieve the logged-in Customer's details.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "retrieve"
@@ -1657,7 +1733,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/customers/me' \\\n--header 'Cookie: connect.sid={sid}'\n"
+            "source": "curl 'https://medusa-url.com/store/customers/me' \\\n-H 'Cookie: connect.sid={sid}'\n"
           }
         ],
         "security": [
@@ -1702,7 +1778,7 @@
       "post": {
         "operationId": "PostCustomersCustomer",
         "summary": "Update Customer",
-        "description": "Updates a Customer's saved details.",
+        "description": "Update the logged-in customer's details.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -1720,12 +1796,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.update({\n  first_name: 'Laury'\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.update({\n  first_name: \"Laury\"\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/customers/me' \\\n--header 'Cookie: connect.sid={sid}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Laury\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/customers/me' \\\n-H 'Cookie: connect.sid={sid}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Laury\"\n}'\n"
           }
         ],
         "security": [
@@ -1772,7 +1848,7 @@
       "post": {
         "operationId": "PostCustomersCustomerAddresses",
         "summary": "Add a Shipping Address",
-        "description": "Adds a Shipping Address to a Customer's saved addresses.",
+        "description": "Add a Shipping Address to a Customer's saved addresses.",
         "x-authenticated": true,
         "requestBody": {
           "content": {
@@ -1790,12 +1866,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.addresses.addAddress({\n  address: {\n    first_name: 'Celia',\n    last_name: 'Schumm',\n    address_1: '225 Bednar Curve',\n    city: 'Danielville',\n    country_code: 'US',\n    postal_code: '85137',\n    phone: '981-596-6748 x90188',\n    company: 'Wyman LLC',\n    address_2: '',\n    province: 'Georgia',\n    metadata: {}\n  }\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.addresses.addAddress({\n  address: {\n    first_name: \"Celia\",\n    last_name: \"Schumm\",\n    address_1: \"225 Bednar Curve\",\n    city: \"Danielville\",\n    country_code: \"US\",\n    postal_code: \"85137\",\n    phone: \"981-596-6748 x90188\",\n    company: \"Wyman LLC\",\n    province: \"Georgia\",\n  }\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/customers/me/addresses' \\\n--header 'Cookie: connect.sid={sid}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"address\": {\n      \"first_name\": \"Celia\",\n      \"last_name\": \"Schumm\",\n      \"address_1\": \"225 Bednar Curve\",\n      \"city\": \"Danielville\",\n      \"country_code\": \"US\",\n      \"postal_code\": \"85137\"\n    }\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/customers/me/addresses' \\\n-H 'Cookie: connect.sid={sid}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"address\": {\n      \"first_name\": \"Celia\",\n      \"last_name\": \"Schumm\",\n      \"address_1\": \"225 Bednar Curve\",\n      \"city\": \"Danielville\",\n      \"country_code\": \"US\",\n      \"postal_code\": \"85137\"\n    }\n}'\n"
           }
         ],
         "security": [
@@ -1842,14 +1918,14 @@
       "post": {
         "operationId": "PostCustomersCustomerAddressesAddress",
         "summary": "Update a Shipping Address",
-        "description": "Updates a Customer's saved Shipping Address.",
+        "description": "Update the logged-in customer's saved Shipping Address's details.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "path",
             "name": "address_id",
             "required": true,
-            "description": "The id of the Address to update.",
+            "description": "The ID of the Address.",
             "schema": {
               "type": "string"
             }
@@ -1871,12 +1947,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.addresses.updateAddress(address_id, {\n  first_name: 'Gina'\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.addresses.updateAddress(addressId, {\n  first_name: \"Gina\"\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \\\n--header 'Cookie: connect.sid={sid}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Gina\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \\\n-H 'Cookie: connect.sid={sid}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"first_name\": \"Gina\"\n}'\n"
           }
         ],
         "security": [
@@ -1921,7 +1997,7 @@
       "delete": {
         "operationId": "DeleteCustomersCustomerAddressesAddress",
         "summary": "Delete an Address",
-        "description": "Removes an Address from the Customer's saved addresses.",
+        "description": "Delete an Address from the Customer's saved addresses.",
         "x-authenticated": true,
         "parameters": [
           {
@@ -1941,12 +2017,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.addresses.deleteAddress(address_id)\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.addresses.deleteAddress(addressId)\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request DELETE 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \\\n--header 'Cookie: connect.sid={sid}'\n"
+            "source": "curl -X DELETE 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \\\n-H 'Cookie: connect.sid={sid}'\n"
           }
         ],
         "security": [
@@ -1993,13 +2069,13 @@
       "get": {
         "operationId": "GetCustomersCustomerOrders",
         "summary": "List Orders",
-        "description": "Retrieves a list of a Customer's Orders.",
+        "description": "Retrieve a list of the logged-in Customer's Orders. The orders can be filtered by fields such as `status` or `fulfillment_status`. The orders can also be paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching orders.",
+            "description": "term to search orders' display ID, email, shipping address's first name, customer's first name, customer's last name, and customer's phone number.",
             "schema": {
               "type": "string"
             }
@@ -2007,7 +2083,7 @@
           {
             "in": "query",
             "name": "id",
-            "description": "Id of the order to search for.",
+            "description": "Filter by ID.",
             "schema": {
               "type": "string"
             }
@@ -2017,11 +2093,18 @@
             "name": "status",
             "style": "form",
             "explode": false,
-            "description": "Status to search for.",
+            "description": "Filter by status.",
             "schema": {
               "type": "array",
               "items": {
-                "type": "string"
+                "type": "string",
+                "enum": [
+                  "pending",
+                  "completed",
+                  "archived",
+                  "canceled",
+                  "requires_action"
+                ]
               }
             }
           },
@@ -2034,7 +2117,18 @@
             "schema": {
               "type": "array",
               "items": {
-                "type": "string"
+                "type": "string",
+                "enum": [
+                  "not_fulfilled",
+                  "partially_fulfilled",
+                  "fulfilled",
+                  "partially_shipped",
+                  "shipped",
+                  "partially_returned",
+                  "returned",
+                  "canceled",
+                  "requires_action"
+                ]
               }
             }
           },
@@ -2047,14 +2141,23 @@
             "schema": {
               "type": "array",
               "items": {
-                "type": "string"
+                "type": "string",
+                "enum": [
+                  "not_paid",
+                  "awaiting",
+                  "captured",
+                  "partially_refunded",
+                  "refunded",
+                  "canceled",
+                  "requires_action"
+                ]
               }
             }
           },
           {
             "in": "query",
             "name": "display_id",
-            "description": "Display id to search for.",
+            "description": "Filter by display ID.",
             "schema": {
               "type": "string"
             }
@@ -2062,7 +2165,7 @@
           {
             "in": "query",
             "name": "cart_id",
-            "description": "to search for.",
+            "description": "Filter by cart ID.",
             "schema": {
               "type": "string"
             }
@@ -2070,7 +2173,7 @@
           {
             "in": "query",
             "name": "email",
-            "description": "to search for.",
+            "description": "Filter by email.",
             "schema": {
               "type": "string"
             }
@@ -2078,7 +2181,7 @@
           {
             "in": "query",
             "name": "region_id",
-            "description": "to search for.",
+            "description": "Filter by region ID.",
             "schema": {
               "type": "string"
             }
@@ -2088,7 +2191,7 @@
             "name": "currency_code",
             "style": "form",
             "explode": false,
-            "description": "The 3 character ISO currency code to set prices based on.",
+            "description": "Filter by the 3 character ISO currency code of the order.",
             "schema": {
               "type": "string",
               "externalDocs": {
@@ -2100,7 +2203,7 @@
           {
             "in": "query",
             "name": "tax_rate",
-            "description": "to search for.",
+            "description": "Filter by tax rate.",
             "schema": {
               "type": "string"
             }
@@ -2108,7 +2211,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting collections were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -2138,7 +2241,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting collections were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -2168,7 +2271,7 @@
           {
             "in": "query",
             "name": "canceled_at",
-            "description": "Date comparison for when resulting collections were canceled.",
+            "description": "Filter by a cancelation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -2198,7 +2301,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "How many orders to return.",
+            "description": "Limit the number of orders returned.",
             "schema": {
               "type": "integer",
               "default": 10
@@ -2207,7 +2310,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The offset in the resulting orders.",
+            "description": "The number of orders to skip when retrieving the orders.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -2215,16 +2318,16 @@
           },
           {
             "in": "query",
-            "name": "fields",
-            "description": "(Comma separated string) Which fields should be included in the resulting orders.",
+            "name": "expand",
+            "description": "Comma-separated relations that should be expanded in the returned orders.",
             "schema": {
               "type": "string"
             }
           },
           {
             "in": "query",
-            "name": "expand",
-            "description": "(Comma separated string) Which relations should be expanded in the resulting orders.",
+            "name": "fields",
+            "description": "Comma-separated fields that should be included in the returned orders.",
             "schema": {
               "type": "string"
             }
@@ -2243,7 +2346,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/customers/me/orders' \\\n--header 'Cookie: connect.sid={sid}'\n"
+            "source": "curl 'https://medusa-url.com/store/customers/me/orders' \\\n-H 'Cookie: connect.sid={sid}'\n"
           }
         ],
         "security": [
@@ -2289,9 +2392,10 @@
     "/store/customers/me/payment-methods": {
       "get": {
         "operationId": "GetCustomersCustomerPaymentMethods",
-        "summary": "Get Payment Methods",
-        "description": "Retrieves a list of a Customer's saved payment methods. Payment methods are saved with Payment Providers and it is their responsibility to fetch saved methods.",
+        "summary": "Get Saved Payment Methods",
+        "description": "Retrieve the logged-in customer's saved payment methods. This endpoint only works with payment providers created with the deprecated Payment Service interface. The payment methods are saved using the Payment Service's third-party service, and not on the Medusa backend. So, they're retrieved from the third-party service.",
         "x-authenticated": true,
+        "deprecated": true,
         "x-codegen": {
           "method": "listPaymentMethods"
         },
@@ -2304,7 +2408,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/customers/me/payment-methods' \\\n--header 'Cookie: connect.sid={sid}'\n"
+            "source": "curl 'https://medusa-url.com/store/customers/me/payment-methods' \\\n-H 'Cookie: connect.sid={sid}'\n"
           }
         ],
         "security": [
@@ -2351,7 +2455,11 @@
       "post": {
         "operationId": "PostCustomersResetPassword",
         "summary": "Reset Password",
-        "description": "Resets a Customer's password using a password token created by a previous /password-token request.",
+        "description": "Reset a Customer's password using a password token created by a previous request to the Request Password Reset endpoint. If the password token expired, you must create a new one.",
+        "externalDocs": {
+          "description": "How to reset password",
+          "url": "https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles#reset-password"
+        },
         "requestBody": {
           "content": {
             "application/json": {
@@ -2368,12 +2476,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.customers.resetPassword({\n  email: 'user@example.com',\n  password: 'supersecret',\n  token: 'supersecrettoken'\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.customers.resetPassword({\n  email: \"user@example.com\",\n  password: \"supersecret\",\n  token: \"supersecrettoken\"\n})\n.then(({ customer }) => {\n  console.log(customer.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/customers/password-reset' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"password\": \"supersecret\",\n    \"token\": \"supersecrettoken\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/customers/password-reset' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\",\n    \"password\": \"supersecret\",\n    \"token\": \"supersecrettoken\"\n}'\n"
           }
         ],
         "tags": [
@@ -2415,7 +2523,11 @@
       "post": {
         "operationId": "PostCustomersCustomerPasswordToken",
         "summary": "Request Password Reset",
-        "description": "Creates a reset password token to be used in a subsequent /reset-password request. The password token should be sent out of band e.g. via email and will not be returned.",
+        "description": "Create a reset password token to be used in a subsequent Reset Password endpoint. This emits the event `customer.password_reset`. If a notification provider is installed in the Medusa backend and is configured to handle this event, a notification to the customer, such as an email, may be sent with reset instructions.",
+        "externalDocs": {
+          "description": "How to reset password",
+          "url": "https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles#reset-password"
+        },
         "requestBody": {
           "content": {
             "application/json": {
@@ -2432,12 +2544,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.customers.generatePasswordToken({\n  email: 'user@example.com'\n})\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // failed\n})\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.customers.generatePasswordToken({\n  email: \"user@example.com\"\n})\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // failed\n})\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/customers/password-token' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/customers/password-token' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"email\": \"user@example.com\"\n}'\n"
           }
         ],
         "tags": [
@@ -2472,7 +2584,7 @@
       "get": {
         "operationId": "GetGiftCardsCode",
         "summary": "Get Gift Card by Code",
-        "description": "Retrieves a Gift Card by its associated unique code.",
+        "description": "Retrieve a Gift Card's details by its associated unique code.",
         "parameters": [
           {
             "in": "path",
@@ -2496,7 +2608,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/gift-cards/{code}'\n"
+            "source": "curl 'https://medusa-url.com/store/gift-cards/{code}'\n"
           }
         ],
         "tags": [
@@ -2534,8 +2646,8 @@
     "/store/order-edits/{id}": {
       "get": {
         "operationId": "GetOrderEditsOrderEdit",
-        "summary": "Retrieve an OrderEdit",
-        "description": "Retrieves a OrderEdit.",
+        "summary": "Retrieve an Order Edit",
+        "description": "Retrieve an Order Edit's details.",
         "parameters": [
           {
             "in": "path",
@@ -2554,12 +2666,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orderEdits.retrieve(order_edit_id)\n.then(({ order_edit }) => {\n  console.log(order_edit.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orderEdits.retrieve(orderEditId)\n.then(({ order_edit }) => {\n  console.log(order_edit.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/order-edits/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/order-edits/{id}'\n"
           }
         ],
         "tags": [
@@ -2600,8 +2712,12 @@
     "/store/order-edits/{id}/complete": {
       "post": {
         "operationId": "PostOrderEditsOrderEditComplete",
-        "summary": "Completes an OrderEdit",
-        "description": "Completes an OrderEdit.",
+        "summary": "Complete an Order Edit",
+        "description": "Complete an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the Payment Collection endpoints.",
+        "externalDocs": {
+          "description": "How to handle order edits in a storefront",
+          "url": "https://docs.medusajs.com/modules/orders/storefront/handle-order-edits"
+        },
         "parameters": [
           {
             "in": "path",
@@ -2620,12 +2736,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orderEdits.complete(order_edit_id)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orderEdits.complete(orderEditId)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id)\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/order-edits/{id}/complete'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/order-edits/{id}/complete'\n"
           }
         ],
         "tags": [
@@ -2660,8 +2776,8 @@
     "/store/order-edits/{id}/decline": {
       "post": {
         "operationId": "PostOrderEditsOrderEditDecline",
-        "summary": "Decline an OrderEdit",
-        "description": "Declines an OrderEdit.",
+        "summary": "Decline an Order Edit",
+        "description": "Decline an Order Edit. The changes are not reflected on the original order.",
         "parameters": [
           {
             "in": "path",
@@ -2689,12 +2805,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orderEdits.decline(order_edit_id)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id);\n  })\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orderEdits.decline(orderEditId)\n  .then(({ order_edit }) => {\n    console.log(order_edit.id);\n  })\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/order-edits/{id}/decline'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/order-edits/{id}/decline'\n"
           }
         ],
         "tags": [
@@ -2730,13 +2846,13 @@
       "get": {
         "operationId": "GetOrders",
         "summary": "Look Up an Order",
-        "description": "Look up an order using filters.",
+        "description": "Look up an order using filters. If the filters don't narrow down the results to a single order, a 404 response is returned with no orders.",
         "parameters": [
           {
             "in": "query",
             "name": "display_id",
             "required": true,
-            "description": "The display id given to the Order.",
+            "description": "Filter by ID.",
             "schema": {
               "type": "number"
             }
@@ -2744,7 +2860,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -2752,7 +2868,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in the result.",
+            "description": "Comma-separated relations that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -2762,7 +2878,7 @@
             "name": "email",
             "style": "form",
             "explode": false,
-            "description": "The email associated with this order.",
+            "description": "Filter by email.",
             "required": true,
             "schema": {
               "type": "string",
@@ -2774,7 +2890,7 @@
             "name": "shipping_address",
             "style": "form",
             "explode": false,
-            "description": "The shipping address associated with this order.",
+            "description": "Filter by the shipping address's postal code.",
             "schema": {
               "type": "object",
               "properties": {
@@ -2794,12 +2910,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orders.lookupOrder({\n  display_id: 1,\n  email: 'user@example.com'\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orders.lookupOrder({\n  display_id: 1,\n  email: \"user@example.com\"\n})\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/orders?display_id=1&email=user@example.com'\n"
+            "source": "curl 'https://medusa-url.com/store/orders?display_id=1&email=user@example.com'\n"
           }
         ],
         "tags": [
@@ -2837,8 +2953,13 @@
     "/store/orders/batch/customer/token": {
       "post": {
         "operationId": "PostOrdersCustomerOrderClaim",
-        "summary": "Claim an Order",
-        "description": "Sends an email to emails registered to orders provided with link to transfer order ownership",
+        "summary": "Claim Order",
+        "description": "Allow the logged-in customer to claim ownership of one or more orders. This generates a token that can be used later on to verify the claim using the endpoint Verify Order Claim. This also emits the event `order-update-token.created`. So, if you have a notification provider installed that handles this event and sends the customer a notification, such as an email, the customer should receive instructions on how to finalize their claim ownership.",
+        "externalDocs": {
+          "description": "How to implement claim-order flow in a storefront",
+          "url": "https://docs.medusajs.com/modules/orders/storefront/implement-claim-order"
+        },
+        "x-authenticated": true,
         "requestBody": {
           "content": {
             "application/json": {
@@ -2855,12 +2976,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.orders.claimOrders({\n  display_ids,\n})\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // an error occurred\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.orders.requestCustomerOrders({\n  order_ids,\n})\n.then(() => {\n  // successful\n})\n.catch(() => {\n  // an error occurred\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/batch/customer/token' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"display_ids\": [\"id\"],\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/batch/customer/token' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"order_ids\": [\"id\"],\n}'\n"
           }
         ],
         "security": [
@@ -2903,7 +3024,7 @@
       "get": {
         "operationId": "GetOrdersOrderCartId",
         "summary": "Get by Cart ID",
-        "description": "Retrieves an Order by the id of the Cart that was used to create the Order.",
+        "description": "Retrieve an Order's details by the ID of the Cart that was used to create the Order.",
         "parameters": [
           {
             "in": "path",
@@ -2922,12 +3043,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orders.retrieveByCartId(cart_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orders.retrieveByCartId(cartId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/orders/cart/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/orders/cart/{cart_id}'\n"
           }
         ],
         "tags": [
@@ -2965,8 +3086,12 @@
     "/store/orders/customer/confirm": {
       "post": {
         "operationId": "PostOrdersCustomerOrderClaimsCustomerOrderClaimAccept",
-        "summary": "Verify an Order Claim",
-        "description": "Verifies the claim order token provided to the customer upon request of order ownership",
+        "summary": "Verify Order Claim",
+        "description": "Verify the claim order token provided to the customer when they request ownership of an order.",
+        "externalDocs": {
+          "description": "How to implement claim-order flow in a storefront",
+          "url": "https://docs.medusajs.com/modules/orders/storefront/implement-claim-order"
+        },
         "requestBody": {
           "content": {
             "application/json": {
@@ -2988,7 +3113,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/orders/customer/confirm' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"token\": \"{token}\",\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/orders/customer/confirm' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"token\": \"{token}\",\n}'\n"
           }
         ],
         "security": [
@@ -3031,13 +3156,13 @@
       "get": {
         "operationId": "GetOrdersOrder",
         "summary": "Get an Order",
-        "description": "Retrieves an Order",
+        "description": "Retrieve an Order's details.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Order.",
+            "description": "The ID of the Order.",
             "schema": {
               "type": "string"
             }
@@ -3045,7 +3170,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in the result.",
+            "description": "Comma-separated fields that should be expanded in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -3053,7 +3178,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in the result.",
+            "description": "Comma-separated relations that should be included in the returned order.",
             "schema": {
               "type": "string"
             }
@@ -3066,12 +3191,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orders.retrieve(order_id)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orders.retrieve(orderId)\n.then(({ order }) => {\n  console.log(order.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/orders/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/orders/{id}'\n"
           }
         ],
         "tags": [
@@ -3110,7 +3235,7 @@
       "get": {
         "operationId": "GetPaymentCollectionsPaymentCollection",
         "summary": "Get a PaymentCollection",
-        "description": "Get a Payment Collection",
+        "description": "Retrieve a Payment Collection's details.",
         "x-authenticated": false,
         "parameters": [
           {
@@ -3124,16 +3249,16 @@
           },
           {
             "in": "query",
-            "name": "expand",
-            "description": "Comma separated list of relations to include in the results.",
+            "name": "fields",
+            "description": "Comma-separated fields that should be expanded in the returned payment collection.",
             "schema": {
               "type": "string"
             }
           },
           {
             "in": "query",
-            "name": "fields",
-            "description": "Comma separated list of fields to include in the results.",
+            "name": "expand",
+            "description": "Comma-separated relations that should be expanded in the returned payment collection.",
             "schema": {
               "type": "string"
             }
@@ -3152,7 +3277,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/payment-collections/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/payment-collections/{id}'\n"
           }
         ],
         "security": [
@@ -3201,8 +3326,8 @@
     "/store/payment-collections/{id}/sessions": {
       "post": {
         "operationId": "PostPaymentCollectionsSessions",
-        "summary": "Manage a Payment Session",
-        "description": "Manages Payment Sessions from Payment Collections.",
+        "summary": "Create a Payment Session",
+        "description": "Create a Payment Session for a payment provider in a Payment Collection.",
         "x-authenticated": false,
         "parameters": [
           {
@@ -3231,12 +3356,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\n\n// Total amount = 10000\n\n// Adding a payment session\nmedusa.paymentCollections.managePaymentSession(payment_id, { provider_id: \"stripe\" })\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.paymentCollections.managePaymentSession(payment_id, { provider_id: \"stripe\" })\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"provider_id\": \"stripe\"\n}'\n"
           }
         ],
         "security": [
@@ -3286,7 +3411,7 @@
       "post": {
         "operationId": "PostPaymentCollectionsPaymentCollectionSessionsBatch",
         "summary": "Manage Payment Sessions",
-        "description": "Manages Multiple Payment Sessions from Payment Collections.",
+        "description": "Create, update, or delete a list of payment sessions of a Payment Collections. If a payment session is not provided in the `sessions` array, it's deleted.",
         "x-authenticated": false,
         "parameters": [
           {
@@ -3315,12 +3440,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\n\n// Total amount = 10000\n\n// Adding two new sessions\nmedusa.paymentCollections.managePaymentSessionsBatch(payment_id, [\n  {\n    provider_id: \"stripe\",\n    amount: 5000,\n  },\n  {\n    provider_id: \"manual\",\n    amount: 5000,\n  },\n])\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n\n// Updating one session and removing the other\nmedusa.paymentCollections.managePaymentSessionsBatch(payment_id, [\n  {\n    provider_id: \"stripe\",\n    amount: 10000,\n    session_id: \"ps_123456\"\n  },\n])\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\n\n// Total amount = 10000\n\n// Example 1: Adding two new sessions\nmedusa.paymentCollections.managePaymentSessionsBatch(paymentId, {\n  sessions: [\n    {\n      provider_id: \"stripe\",\n      amount: 5000,\n    },\n    {\n      provider_id: \"manual\",\n      amount: 5000,\n    },\n  ]\n})\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n\n// Example 2: Updating one session and removing the other\nmedusa.paymentCollections.managePaymentSessionsBatch(paymentId, {\n  sessions: [\n    {\n      provider_id: \"stripe\",\n      amount: 10000,\n      session_id: \"ps_123456\"\n    },\n  ]\n})\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"sessions\": [\n    {\n      \"provider_id\": \"stripe\",\n      \"amount\": 5000\n    },\n    {\n      \"provider_id\": \"manual\",\n      \"amount\": 5000\n    }\n  ]\n}'\n"
           }
         ],
         "security": [
@@ -3370,7 +3495,7 @@
       "post": {
         "operationId": "PostPaymentCollectionsSessionsBatchAuthorize",
         "summary": "Authorize PaymentSessions",
-        "description": "Authorizes Payment Sessions of a Payment Collection.",
+        "description": "Authorize the Payment Sessions of a Payment Collection.",
         "x-authenticated": false,
         "parameters": [
           {
@@ -3399,12 +3524,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.paymentCollections.authorize(payment_id)\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.paymentCollections.authorize(paymentId)\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch/authorize'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch/authorize'\n"
           }
         ],
         "security": [
@@ -3454,7 +3579,7 @@
       "post": {
         "operationId": "PostPaymentCollectionsPaymentCollectionPaymentSessionsSession",
         "summary": "Refresh a Payment Session",
-        "description": "Refreshes a Payment Session to ensure that it is in sync with the Payment Collection.",
+        "description": "Refresh a Payment Session's data to ensure that it is in sync with the Payment Collection.",
         "x-authenticated": false,
         "parameters": [
           {
@@ -3483,12 +3608,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.paymentCollections.refreshPaymentSession(payment_collection_id, session_id)\n.then(({ payment_session }) => {\n  console.log(payment_session.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.paymentCollections.refreshPaymentSession(paymentCollectionId, sessionId)\n.then(({ payment_session }) => {\n  console.log(payment_session.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}'\n"
           }
         ],
         "tags": [
@@ -3527,7 +3652,7 @@
       "post": {
         "operationId": "PostPaymentCollectionsSessionsSessionAuthorize",
         "summary": "Authorize Payment Session",
-        "description": "Authorizes a Payment Session of a Payment Collection.",
+        "description": "Authorize a Payment Session of a Payment Collection.",
         "x-authenticated": false,
         "parameters": [
           {
@@ -3556,12 +3681,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.paymentCollections.authorize(payment_id, session_id)\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.paymentCollections.authorize(paymentId, sessionId)\n.then(({ payment_collection }) => {\n  console.log(payment_collection.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}/authorize'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}/authorize'\n"
           }
         ],
         "security": [
@@ -3611,13 +3736,17 @@
       "get": {
         "operationId": "GetProductCategories",
         "summary": "List Product Categories",
-        "description": "Retrieve a list of product categories.",
-        "x-authenticated": false,
+        "description": "Retrieve a list of product categories. The product categories can be filtered by fields such as `handle` or `q`. The product categories can also be paginated. This endpoint can also be used to retrieve a product category by its handle.",
+        "x-featureFlag": "product_categories",
+        "externalDocs": {
+          "description": "How to retrieve a product category by its handle",
+          "url": "https://docs.medusajs.com/modules/products/storefront/use-categories#get-a-category-by-its-handle"
+        },
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching product category names or handles.",
+            "description": "term used to search product category's names and handles.",
             "schema": {
               "type": "string"
             }
@@ -3625,7 +3754,7 @@
           {
             "in": "query",
             "name": "handle",
-            "description": "Query used for searching product category by handle.",
+            "description": "Filter by handle.",
             "schema": {
               "type": "string"
             }
@@ -3633,7 +3762,7 @@
           {
             "in": "query",
             "name": "parent_category_id",
-            "description": "Returns categories scoped by parent",
+            "description": "Filter by the ID of a parent category. Only children of the provided parent category are retrieved.",
             "schema": {
               "type": "string"
             }
@@ -3641,7 +3770,7 @@
           {
             "in": "query",
             "name": "include_descendants_tree",
-            "description": "Include all nested descendants of category",
+            "description": "Whether all nested categories inside a category should be retrieved.",
             "schema": {
               "type": "boolean"
             }
@@ -3649,7 +3778,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many product categories to skip in the result.",
+            "description": "The number of product categories to skip when retrieving the product categories.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -3663,6 +3792,22 @@
               "type": "integer",
               "default": 100
             }
+          },
+          {
+            "in": "query",
+            "name": "expand",
+            "description": "Comma-separated relations that should be expanded in the returned product categories.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "fields",
+            "description": "Comma-separated fields that should be included in the returned product categories.",
+            "schema": {
+              "type": "string"
+            }
           }
         ],
         "x-codegen": {
@@ -3678,7 +3823,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/product-categories' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/store/product-categories' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -3728,8 +3873,8 @@
       "get": {
         "operationId": "GetProductCategoriesCategory",
         "summary": "Get a Product Category",
-        "description": "Retrieves a Product Category.",
-        "x-authenticated": false,
+        "description": "Retrieve a Product Category's details.",
+        "x-featureFlag": "product_categories",
         "parameters": [
           {
             "in": "path",
@@ -3742,16 +3887,16 @@
           },
           {
             "in": "query",
-            "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each product category.",
+            "name": "fields",
+            "description": "Comma-separated fields that should be expanded in the returned product category.",
             "schema": {
               "type": "string"
             }
           },
           {
             "in": "query",
-            "name": "fields",
-            "description": "(Comma separated) Which fields should be retrieved in each product category.",
+            "name": "expand",
+            "description": "Comma-separated relations that should be expanded in the returned product category.",
             "schema": {
               "type": "string"
             }
@@ -3765,12 +3910,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.productCategories.retrieve(product_category_id)\n  .then(({ product_category }) => {\n    console.log(product_category.id);\n  });\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.productCategories.retrieve(productCategoryId)\n  .then(({ product_category }) => {\n    console.log(product_category.id);\n  });\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/product-categories/{id}' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/store/product-categories/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n"
           }
         ],
         "security": [
@@ -3820,7 +3965,7 @@
       "get": {
         "operationId": "GetProductTags",
         "summary": "List Product Tags",
-        "description": "Retrieve a list of Product Tags.",
+        "description": "Retrieve a list of product tags. The product tags can be filtered by fields such as `id` or `q`. The product tags can also be sorted or paginated.",
         "x-authenticated": true,
         "x-codegen": {
           "method": "list",
@@ -3830,7 +3975,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of types to return.",
+            "description": "Limit the number of product tags returned.",
             "schema": {
               "type": "integer",
               "default": 20
@@ -3839,7 +3984,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of items to skip before the results.",
+            "description": "The number of product tags to skip when retrieving the product tags.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -3848,7 +3993,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "The field to sort items by.",
+            "description": "A product-tag field to sort-order the retrieved product tags by.",
             "schema": {
               "type": "string"
             }
@@ -3856,7 +4001,7 @@
           {
             "in": "query",
             "name": "discount_condition_id",
-            "description": "The discount condition id on which to filter the product tags.",
+            "description": "Filter by the ID of a discount condition. When provided, only tags that the discount condition applies for will be retrieved.",
             "schema": {
               "type": "string"
             }
@@ -3866,7 +4011,7 @@
             "name": "value",
             "style": "form",
             "explode": false,
-            "description": "The tag values to search for",
+            "description": "Filter by tag values.",
             "schema": {
               "type": "array",
               "items": {
@@ -3879,7 +4024,7 @@
             "name": "id",
             "style": "form",
             "explode": false,
-            "description": "The tag IDs to search for",
+            "description": "Filter by IDs.",
             "schema": {
               "type": "array",
               "items": {
@@ -3890,7 +4035,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "A query string to search values for",
+            "description": "term to search product tag's value.",
             "schema": {
               "type": "string"
             }
@@ -3898,7 +4043,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting product tags were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -3928,7 +4073,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting product tags were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -3965,7 +4110,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/product-tags'\n"
+            "source": "curl 'https://medusa-url.com/store/product-tags'\n"
           }
         ],
         "tags": [
@@ -4007,13 +4152,13 @@
       "get": {
         "operationId": "GetProductTypes",
         "summary": "List Product Types",
-        "description": "Retrieve a list of Product Types.",
+        "description": "Retrieve a list of product types. The product types can be filtered by fields such as `value` or `q`. The product types can also be sorted or paginated.",
         "x-authenticated": true,
         "parameters": [
           {
             "in": "query",
             "name": "limit",
-            "description": "The number of types to return.",
+            "description": "Limit the number of product types returned.",
             "schema": {
               "type": "integer",
               "default": 20
@@ -4022,7 +4167,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "The number of items to skip before the results.",
+            "description": "The number of product types to skip when retrieving the product types.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -4031,7 +4176,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "The field to sort items by.",
+            "description": "A product-type field to sort-order the retrieved product types by.",
             "schema": {
               "type": "string"
             }
@@ -4039,7 +4184,7 @@
           {
             "in": "query",
             "name": "discount_condition_id",
-            "description": "The discount condition id on which to filter the product types.",
+            "description": "Filter by the ID of a discount condition. When provided, only types that the discount condition applies for will be retrieved.",
             "schema": {
               "type": "string"
             }
@@ -4049,7 +4194,7 @@
             "name": "value",
             "style": "form",
             "explode": false,
-            "description": "The type values to search for",
+            "description": "Filter by type values.",
             "schema": {
               "type": "array",
               "items": {
@@ -4062,7 +4207,7 @@
             "name": "id",
             "style": "form",
             "explode": false,
-            "description": "The type IDs to search for",
+            "description": "Filter by IDs.",
             "schema": {
               "type": "array",
               "items": {
@@ -4073,7 +4218,7 @@
           {
             "in": "query",
             "name": "q",
-            "description": "A query string to search values for",
+            "description": "term to search product type's value.",
             "schema": {
               "type": "string"
             }
@@ -4081,7 +4226,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting product types were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -4111,7 +4256,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting product types were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -4152,7 +4297,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/product-types' \\\n--header 'Authorization: Bearer {api_token}'\n"
+            "source": "curl 'https://medusa-url.com/store/product-types'\n"
           }
         ],
         "security": [
@@ -4202,12 +4347,16 @@
       "get": {
         "operationId": "GetProducts",
         "summary": "List Products",
-        "description": "Retrieves a list of Products.",
+        "description": "Retrieves a list of products. The products can be filtered by fields such as `id` or `q`. The products can also be sorted or paginated.\nThis endpoint can also be used to retrieve a product by its handle.\n\nFor accurate and correct pricing of the products based on the customer's context, it's highly recommended to pass fields such as\n`region_id`, `currency_code`, and `cart_id` when available.\n\nPassing `sales_channel_id` ensures retrieving only products available in the specified sales channel.\nYou can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.\n",
+        "externalDocs": {
+          "description": "How to retrieve a product by its handle",
+          "url": "https://docs.medusajs.com/modules/products/storefront/show-products#retrieve-product-by-handle"
+        },
         "parameters": [
           {
             "in": "query",
             "name": "q",
-            "description": "Query used for searching products by title, description, variant's title, variant's sku, and collection's title",
+            "description": "term used to search products' title, description, variant's title, variant's sku, and collection's title.",
             "schema": {
               "type": "string"
             }
@@ -4217,7 +4366,7 @@
             "name": "id",
             "style": "form",
             "explode": false,
-            "description": "product IDs to search for.",
+            "description": "Filter by IDs.",
             "schema": {
               "oneOf": [
                 {
@@ -4237,7 +4386,7 @@
             "name": "sales_channel_id",
             "style": "form",
             "explode": false,
-            "description": "an array of sales channel IDs to filter the retrieved products by.",
+            "description": "Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect.",
             "schema": {
               "type": "array",
               "items": {
@@ -4250,7 +4399,7 @@
             "name": "collection_id",
             "style": "form",
             "explode": false,
-            "description": "Collection IDs to search for",
+            "description": "Filter by product collection IDs. When provided, only products that belong to the specified product collections are retrieved.",
             "schema": {
               "type": "array",
               "items": {
@@ -4263,7 +4412,7 @@
             "name": "type_id",
             "style": "form",
             "explode": false,
-            "description": "Type IDs to search for",
+            "description": "Filter by product type IDs. When provided, only products that belong to the specified product types are retrieved.",
             "schema": {
               "type": "array",
               "items": {
@@ -4276,7 +4425,7 @@
             "name": "tags",
             "style": "form",
             "explode": false,
-            "description": "Tag IDs to search for",
+            "description": "Filter by product tag IDs. When provided, only products that belong to the specified product tags are retrieved.",
             "schema": {
               "type": "array",
               "items": {
@@ -4287,7 +4436,7 @@
           {
             "in": "query",
             "name": "title",
-            "description": "title to search for.",
+            "description": "Filter by title.",
             "schema": {
               "type": "string"
             }
@@ -4295,7 +4444,7 @@
           {
             "in": "query",
             "name": "description",
-            "description": "description to search for.",
+            "description": "Filter by description",
             "schema": {
               "type": "string"
             }
@@ -4303,7 +4452,7 @@
           {
             "in": "query",
             "name": "handle",
-            "description": "handle to search for.",
+            "description": "Filter by handle.",
             "schema": {
               "type": "string"
             }
@@ -4311,7 +4460,7 @@
           {
             "in": "query",
             "name": "is_giftcard",
-            "description": "Search for giftcards using is_giftcard=true.",
+            "description": "Whether to retrieve regular products or gift-card products.",
             "schema": {
               "type": "boolean"
             }
@@ -4319,7 +4468,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting products were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -4349,7 +4498,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting products were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -4381,9 +4530,10 @@
             "name": "category_id",
             "style": "form",
             "explode": false,
-            "description": "Category ids to filter by.",
+            "description": "Filter by product category IDs. When provided, only products that belong to the specified product categories are retrieved.",
             "schema": {
               "type": "array",
+              "x-featureFlag": "product_categories",
               "items": {
                 "type": "string"
               }
@@ -4392,15 +4542,18 @@
           {
             "in": "query",
             "name": "include_category_children",
-            "description": "Include category children when filtering by category_id.",
+            "style": "form",
+            "explode": false,
+            "description": "Whether to include child product categories when filtering using the `category_id` field.",
             "schema": {
-              "type": "boolean"
+              "type": "boolean",
+              "x-featureFlag": "product_categories"
             }
           },
           {
             "in": "query",
             "name": "offset",
-            "description": "How many products to skip in the result.",
+            "description": "The number of products to skip when retrieving the products.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -4418,7 +4571,7 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each product of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned products.",
             "schema": {
               "type": "string"
             }
@@ -4426,7 +4579,7 @@
           {
             "in": "query",
             "name": "fields",
-            "description": "(Comma separated) Which fields should be included in each product of the result.",
+            "description": "Comma-separated fields that should be included in the returned products.",
             "schema": {
               "type": "string"
             }
@@ -4434,7 +4587,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "the field used to order the products.",
+            "description": "A product field to sort-order the retrieved products by.",
             "schema": {
               "type": "string"
             }
@@ -4442,7 +4595,7 @@
           {
             "in": "query",
             "name": "cart_id",
-            "description": "The id of the Cart to set prices based on.",
+            "description": "The ID of the cart. This is useful for accurate pricing based on the cart's context.",
             "schema": {
               "type": "string"
             }
@@ -4450,7 +4603,7 @@
           {
             "in": "query",
             "name": "region_id",
-            "description": "The id of the Region to set prices based on.",
+            "description": "The ID of the region. This is useful for accurate pricing based on the selected region.",
             "schema": {
               "type": "string"
             }
@@ -4458,9 +4611,15 @@
           {
             "in": "query",
             "name": "currency_code",
-            "description": "The currency code to use for price selection.",
+            "style": "form",
+            "explode": false,
+            "description": "A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.",
             "schema": {
-              "type": "string"
+              "type": "string",
+              "externalDocs": {
+                "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
+                "description": "See a list of codes."
+              }
             }
           }
         ],
@@ -4477,7 +4636,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/products'\n"
+            "source": "curl 'https://medusa-url.com/store/products'\n"
           }
         ],
         "tags": [
@@ -4516,7 +4675,7 @@
       "post": {
         "operationId": "PostProductsSearch",
         "summary": "Search Products",
-        "description": "Run a search query on products using the search engine installed on Medusa",
+        "description": "Run a search query on products using the search service installed on the Medusa backend. The searching is handled through the search service, so the returned data's format depends on the search service you're using.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -4533,12 +4692,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.products.search({\n  q: 'Shirt'\n})\n.then(({ hits }) => {\n  console.log(hits.length);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.products.search({\n  q: \"Shirt\"\n})\n.then(({ hits }) => {\n  console.log(hits.length);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/products/search' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"q\": \"Shirt\"\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/products/search' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"q\": \"Shirt\"\n}'\n"
           }
         ],
         "tags": [
@@ -4577,13 +4736,17 @@
       "get": {
         "operationId": "GetProductsProduct",
         "summary": "Get a Product",
-        "description": "Retrieves a Product.",
+        "description": "Retrieve a Product's details. For accurate and correct pricing of the product based on the customer's context, it's highly recommended to pass fields such as\n`region_id`, `currency_code`, and `cart_id` when available.\n\nPassing `sales_channel_id` ensures retrieving only products available in the current sales channel.\nYou can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.\n",
+        "externalDocs": {
+          "description": "How to pass product pricing parameters",
+          "url": "https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters"
+        },
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Product.",
+            "description": "The ID of the Product.",
             "schema": {
               "type": "string"
             }
@@ -4591,7 +4754,7 @@
           {
             "in": "query",
             "name": "sales_channel_id",
-            "description": "The sales channel used when fetching the product.",
+            "description": "The ID of the sales channel the customer is viewing the product from.",
             "schema": {
               "type": "string"
             }
@@ -4599,7 +4762,7 @@
           {
             "in": "query",
             "name": "cart_id",
-            "description": "The ID of the customer's cart.",
+            "description": "The ID of the cart. This is useful for accurate pricing based on the cart's context.",
             "schema": {
               "type": "string"
             }
@@ -4607,15 +4770,7 @@
           {
             "in": "query",
             "name": "region_id",
-            "description": "The ID of the region the customer is using. This is helpful to ensure correct prices are retrieved for a region.",
-            "schema": {
-              "type": "string"
-            }
-          },
-          {
-            "in": "query",
-            "name": "fields",
-            "description": "(Comma separated) Which fields should be included in the result.",
+            "description": "The ID of the region. This is useful for accurate pricing based on the selected region.",
             "schema": {
               "type": "string"
             }
@@ -4623,7 +4778,15 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "(Comma separated) Which fields should be expanded in each product of the result.",
+            "description": "Comma-separated relations that should be expanded in the returned product.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "fields",
+            "description": "Comma-separated fields that should be included in the returned product.",
             "schema": {
               "type": "string"
             }
@@ -4633,7 +4796,7 @@
             "name": "currency_code",
             "style": "form",
             "explode": false,
-            "description": "The 3 character ISO currency code to set prices based on. This is helpful to ensure correct prices are retrieved for a currency.",
+            "description": "A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.",
             "schema": {
               "type": "string",
               "externalDocs": {
@@ -4651,12 +4814,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.products.retrieve(product_id)\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.products.retrieve(productId)\n.then(({ product }) => {\n  console.log(product.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/products/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/products/{id}'\n"
           }
         ],
         "tags": [
@@ -4695,12 +4858,16 @@
       "get": {
         "operationId": "GetRegions",
         "summary": "List Regions",
-        "description": "Retrieves a list of Regions.",
+        "description": "Retrieve a list of regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated. This endpoint is useful to show the customer all available regions to choose from.",
+        "externalDocs": {
+          "description": "How to use regions in a storefront",
+          "url": "https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions"
+        },
         "parameters": [
           {
             "in": "query",
             "name": "offset",
-            "description": "How many regions to skip in the result.",
+            "description": "The number of regions to skip when retrieving the regions.",
             "schema": {
               "type": "integer",
               "default": 0
@@ -4718,7 +4885,7 @@
           {
             "in": "query",
             "name": "created_at",
-            "description": "Date comparison for when resulting regions were created.",
+            "description": "Filter by a creation date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -4748,7 +4915,7 @@
           {
             "in": "query",
             "name": "updated_at",
-            "description": "Date comparison for when resulting regions were updated.",
+            "description": "Filter by an update date range.",
             "schema": {
               "type": "object",
               "properties": {
@@ -4789,7 +4956,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/regions'\n"
+            "source": "curl 'https://medusa-url.com/store/regions'\n"
           }
         ],
         "tags": [
@@ -4828,13 +4995,13 @@
       "get": {
         "operationId": "GetRegionsRegion",
         "summary": "Get a Region",
-        "description": "Retrieves a Region.",
+        "description": "Retrieve a Region's details.",
         "parameters": [
           {
             "in": "path",
             "name": "id",
             "required": true,
-            "description": "The id of the Region.",
+            "description": "The ID of the Region.",
             "schema": {
               "type": "string"
             }
@@ -4847,12 +5014,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.regions.retrieve(region_id)\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.regions.retrieve(regionId)\n.then(({ region }) => {\n  console.log(region.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/regions/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/regions/{id}'\n"
           }
         ],
         "tags": [
@@ -4891,7 +5058,7 @@
       "get": {
         "operationId": "GetReturnReasons",
         "summary": "List Return Reasons",
-        "description": "Retrieves a list of Return Reasons.",
+        "description": "Retrieve a list of Return Reasons. This is useful when implementing a Create Return flow in the storefront.",
         "x-codegen": {
           "method": "list"
         },
@@ -4904,7 +5071,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/return-reasons'\n"
+            "source": "curl 'https://medusa-url.com/store/return-reasons'\n"
           }
         ],
         "tags": [
@@ -4943,7 +5110,7 @@
       "get": {
         "operationId": "GetReturnReasonsReason",
         "summary": "Get a Return Reason",
-        "description": "Retrieves a Return Reason.",
+        "description": "Retrieve a Return Reason's details.",
         "parameters": [
           {
             "in": "path",
@@ -4962,12 +5129,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.returnReasons.retrieve(reason_id)\n.then(({ return_reason }) => {\n  console.log(return_reason.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.returnReasons.retrieve(reasonId)\n.then(({ return_reason }) => {\n  console.log(return_reason.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/return-reasons/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/return-reasons/{id}'\n"
           }
         ],
         "tags": [
@@ -5006,7 +5173,11 @@
       "post": {
         "operationId": "PostReturns",
         "summary": "Create Return",
-        "description": "Creates a Return for an Order.",
+        "description": "Create a Return for an Order. If a return shipping method is specified, the return is automatically fulfilled.",
+        "externalDocs": {
+          "description": "How to create a return in a storefront",
+          "url": "https://docs.medusajs.com/modules/orders/storefront/create-return"
+        },
         "requestBody": {
           "content": {
             "application/json": {
@@ -5028,7 +5199,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/returns' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"order_id\": \"asfasf\",\n    \"items\": [\n      {\n        \"item_id\": \"assfasf\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/returns' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"order_id\": \"asfasf\",\n    \"items\": [\n      {\n        \"item_id\": \"assfasf\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
           }
         ],
         "tags": [
@@ -5067,12 +5238,12 @@
       "get": {
         "operationId": "GetShippingOptions",
         "summary": "Get Shipping Options",
-        "description": "Retrieves a list of Shipping Options.",
+        "description": "Retrieve a list of Shipping Options.",
         "parameters": [
           {
             "in": "query",
             "name": "is_return",
-            "description": "Whether return Shipping Options should be included. By default all Shipping Options are returned.",
+            "description": "Whether return shipping options should be included. By default, all shipping options are returned.",
             "schema": {
               "type": "boolean"
             }
@@ -5080,7 +5251,7 @@
           {
             "in": "query",
             "name": "product_ids",
-            "description": "A comma separated list of Product ids to filter Shipping Options by.",
+            "description": "\"Comma-separated list of Product IDs to filter Shipping Options by. If provided, only shipping options that can be used with the provided products are retrieved.\"",
             "schema": {
               "type": "string"
             }
@@ -5088,7 +5259,7 @@
           {
             "in": "query",
             "name": "region_id",
-            "description": "the Region to retrieve Shipping Options from.",
+            "description": "\"The ID of the region that the shipping options belong to. If not provided, all shipping options are retrieved.\"",
             "schema": {
               "type": "string"
             }
@@ -5107,7 +5278,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/shipping-options'\n"
+            "source": "curl 'https://medusa-url.com/store/shipping-options'\n"
           }
         ],
         "tags": [
@@ -5146,13 +5317,17 @@
       "get": {
         "operationId": "GetShippingOptionsCartId",
         "summary": "List for Cart",
-        "description": "Retrieves a list of Shipping Options available to a cart.",
+        "description": "Retrieve a list of Shipping Options available for a cart.",
+        "externalDocs": {
+          "description": "How to implement shipping step in checkout",
+          "url": "https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-checkout-flow#shipping-step"
+        },
         "parameters": [
           {
             "in": "path",
             "name": "cart_id",
             "required": true,
-            "description": "The id of the Cart.",
+            "description": "The ID of the Cart.",
             "schema": {
               "type": "string"
             }
@@ -5165,12 +5340,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.shippingOptions.listCartOptions(cart_id)\n.then(({ shipping_options }) => {\n  console.log(shipping_options.length);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.shippingOptions.listCartOptions(cartId)\n.then(({ shipping_options }) => {\n  console.log(shipping_options.length);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/shipping-options/{cart_id}'\n"
+            "source": "curl 'https://medusa-url.com/store/shipping-options/{cart_id}'\n"
           }
         ],
         "tags": [
@@ -5209,7 +5384,11 @@
       "post": {
         "operationId": "PostSwaps",
         "summary": "Create a Swap",
-        "description": "Creates a Swap on an Order by providing some items to return along with some items to send back",
+        "description": "Create a Swap for an Order. This will also create a return and associate it with the swap. If a return shipping option is specified, the return will automatically be fulfilled.\nTo complete the swap, you must use the Complete Cart endpoint passing it the ID of the swap's cart.\n\nAn idempotency key will be generated if none is provided in the header `Idempotency-Key` and added to\nthe response. If an error occurs during swap creation or the request is interrupted for any reason, the swap creation can be retried by passing the idempotency\nkey in the `Idempotency-Key` header.\n",
+        "externalDocs": {
+          "description": "How to create a swap",
+          "url": "https://docs.medusajs.com/modules/orders/storefront/create-swap"
+        },
         "requestBody": {
           "content": {
             "application/json": {
@@ -5231,7 +5410,7 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request POST 'https://medusa-url.com/store/swaps' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"order_id\": \"asfasf\",\n    \"return_items\": [\n      {\n        \"item_id\": \"asfas\",\n        \"quantity\": 1\n      }\n    ],\n    \"additional_items\": [\n      {\n        \"variant_id\": \"asfas\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
+            "source": "curl -X POST 'https://medusa-url.com/store/swaps' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n    \"order_id\": \"{order_id}\",\n    \"return_items\": [\n      {\n        \"item_id\": \"{item_id}\",\n        \"quantity\": 1\n      }\n    ],\n    \"additional_items\": [\n      {\n        \"variant_id\": \"{variant_id}\",\n        \"quantity\": 1\n      }\n    ]\n}'\n"
           }
         ],
         "tags": [
@@ -5270,7 +5449,7 @@
       "get": {
         "operationId": "GetSwapsSwapCartId",
         "summary": "Get by Cart ID",
-        "description": "Retrieves a Swap by the id of the Cart used to confirm the Swap.",
+        "description": "Retrieve a Swap's details by the ID of its cart.",
         "parameters": [
           {
             "in": "path",
@@ -5289,12 +5468,12 @@
           {
             "lang": "JavaScript",
             "label": "JS Client",
-            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.swaps.retrieveByCartId(cart_id)\n.then(({ swap }) => {\n  console.log(swap.id);\n});\n"
+            "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.swaps.retrieveByCartId(cartId)\n.then(({ swap }) => {\n  console.log(swap.id);\n});\n"
           },
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/swaps/{cart_id}'\n"
+            "source": "curl 'https://medusa-url.com/store/swaps/{cart_id}'\n"
           }
         ],
         "tags": [
@@ -5333,20 +5512,46 @@
       "get": {
         "operationId": "GetVariants",
         "summary": "Get Product Variants",
-        "description": "Retrieves a list of Product Variants",
+        "description": "Retrieves a list of product variants. The product variants can be filtered by fields such as `id` or `title`. The product variants can also be paginated.\n\nFor accurate and correct pricing of the product variants based on the customer's context, it's highly recommended to pass fields such as\n`region_id`, `currency_code`, and `cart_id` when available.\n\nPassing `sales_channel_id` ensures retrieving only variants of products available in the specified sales channel.\nYou can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.\n",
+        "externalDocs": {
+          "description": "How to pass product pricing parameters",
+          "url": "https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters"
+        },
         "parameters": [
           {
             "in": "query",
             "name": "ids",
-            "description": "A comma separated list of Product Variant ids to filter by.",
+            "description": "Filter by a comma-separated list of IDs. If supplied, it overrides the `id` parameter.",
             "schema": {
               "type": "string"
             }
           },
+          {
+            "in": "query",
+            "name": "id",
+            "style": "form",
+            "explode": false,
+            "description": "Filter by one or more IDs. If `ids` is supplied, it's overrides the value of this parameter.",
+            "schema": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "description": "Filter by an ID."
+                },
+                {
+                  "type": "array",
+                  "description": "Filter by IDs.",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            }
+          },
           {
             "in": "query",
             "name": "sales_channel_id",
-            "description": "A sales channel id for result configuration.",
+            "description": "\"Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect.\"",
             "schema": {
               "type": "string"
             }
@@ -5354,7 +5559,15 @@
           {
             "in": "query",
             "name": "expand",
-            "description": "A comma separated list of Product Variant relations to load.",
+            "description": "Comma-separated relations that should be expanded in the returned product variants.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "fields",
+            "description": "Comma-separated fields that should be included in the returned product variants.",
             "schema": {
               "type": "string"
             }
@@ -5362,7 +5575,7 @@
           {
             "in": "query",
             "name": "offset",
-            "description": "How many product variants to skip in the result.",
+            "description": "The number of products to skip when retrieving the product variants.",
             "schema": {
               "type": "number",
               "default": "0"
@@ -5371,7 +5584,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "Maximum number of Product Variants to return.",
+            "description": "Limit the number of product variants returned.",
             "schema": {
               "type": "number",
               "default": "100"
@@ -5380,7 +5593,7 @@
           {
             "in": "query",
             "name": "cart_id",
-            "description": "The id of the Cart to set prices based on.",
+            "description": "The ID of the cart. This is useful for accurate pricing based on the cart's context.",
             "schema": {
               "type": "string"
             }
@@ -5388,7 +5601,7 @@
           {
             "in": "query",
             "name": "region_id",
-            "description": "The id of the Region to set prices based on.",
+            "description": "The ID of the region. This is useful for accurate pricing based on the selected region.",
             "schema": {
               "type": "string"
             }
@@ -5396,9 +5609,15 @@
           {
             "in": "query",
             "name": "currency_code",
-            "description": "The currency code to use for price selection.",
+            "style": "form",
+            "explode": false,
+            "description": "A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.",
             "schema": {
-              "type": "string"
+              "type": "string",
+              "externalDocs": {
+                "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes",
+                "description": "See a list of codes."
+              }
             }
           },
           {
@@ -5406,16 +5625,16 @@
             "name": "title",
             "style": "form",
             "explode": false,
-            "description": "product variant title to search for.",
+            "description": "Filter by title",
             "schema": {
               "oneOf": [
                 {
                   "type": "string",
-                  "description": "a single title to search by"
+                  "description": "a single title to filter by"
                 },
                 {
                   "type": "array",
-                  "description": "multiple titles to search by",
+                  "description": "multiple titles to filter by",
                   "items": {
                     "type": "string"
                   }
@@ -5431,27 +5650,27 @@
               "oneOf": [
                 {
                   "type": "number",
-                  "description": "a specific number to search by."
+                  "description": "A specific number to filter by."
                 },
                 {
                   "type": "object",
-                  "description": "search using less and greater than comparisons.",
+                  "description": "Filter using less and greater than comparisons.",
                   "properties": {
                     "lt": {
                       "type": "number",
-                      "description": "filter by inventory quantity less than this number"
+                      "description": "Filter by inventory quantity less than this number"
                     },
                     "gt": {
                       "type": "number",
-                      "description": "filter by inventory quantity greater than this number"
+                      "description": "Filter by inventory quantity greater than this number"
                     },
                     "lte": {
                       "type": "number",
-                      "description": "filter by inventory quantity less than or equal to this number"
+                      "description": "Filter by inventory quantity less than or equal to this number"
                     },
                     "gte": {
                       "type": "number",
-                      "description": "filter by inventory quantity greater than or equal to this number"
+                      "description": "Filter by inventory quantity greater than or equal to this number"
                     }
                   }
                 }
@@ -5467,11 +5686,11 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/variants'\n"
+            "source": "curl 'https://medusa-url.com/store/variants'\n"
           }
         ],
         "tags": [
-          "Variants"
+          "Product Variants"
         ],
         "responses": {
           "200": {
@@ -5502,25 +5721,21 @@
         }
       }
     },
-    "/store/variants/{variant_id}": {
+    "/store/variants/{id}": {
       "get": {
         "operationId": "GetVariantsVariant",
         "summary": "Get a Product Variant",
-        "description": "Retrieves a Product Variant by id",
+        "description": "Retrieve a Product Variant's details. For accurate and correct pricing of the product variant based on the customer's context, it's highly recommended to pass fields such as\n`region_id`, `currency_code`, and `cart_id` when available.\n\nPassing `sales_channel_id` ensures retrieving only variants of products available in the current sales channel.\nYou can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.\n",
+        "externalDocs": {
+          "description": "How to pass product pricing parameters",
+          "url": "https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters"
+        },
         "parameters": [
           {
             "in": "path",
-            "name": "variant_id",
+            "name": "id",
             "required": true,
-            "description": "The id of the Product Variant.",
-            "schema": {
-              "type": "string"
-            }
-          },
-          {
-            "in": "query",
-            "name": "cart_id",
-            "description": "The id of the Cart to set prices based on.",
+            "description": "The ID of the Product Variant.",
             "schema": {
               "type": "string"
             }
@@ -5528,7 +5743,15 @@
           {
             "in": "query",
             "name": "sales_channel_id",
-            "description": "A sales channel id for result configuration.",
+            "description": "The ID of the sales channel the customer is viewing the product variant from.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "cart_id",
+            "description": "The ID of the cart. This is useful for accurate pricing based on the cart's context.",
             "schema": {
               "type": "string"
             }
@@ -5536,7 +5759,7 @@
           {
             "in": "query",
             "name": "region_id",
-            "description": "The id of the Region to set prices based on.",
+            "description": "The ID of the region. This is useful for accurate pricing based on the selected region.",
             "schema": {
               "type": "string"
             }
@@ -5546,7 +5769,7 @@
             "name": "currency_code",
             "style": "form",
             "explode": false,
-            "description": "The 3 character ISO currency code to set prices based on.",
+            "description": "A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.",
             "schema": {
               "type": "string",
               "externalDocs": {
@@ -5564,11 +5787,11 @@
           {
             "lang": "Shell",
             "label": "cURL",
-            "source": "curl --location --request GET 'https://medusa-url.com/store/variants/{id}'\n"
+            "source": "curl 'https://medusa-url.com/store/variants/{id}'\n"
           }
         ],
         "tags": [
-          "Variants"
+          "Product Variants"
         ],
         "responses": {
           "200": {
@@ -5812,7 +6035,7 @@
     "schemas": {
       "Address": {
         "title": "Address",
-        "description": "An address.",
+        "description": "An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.",
         "type": "object",
         "required": [
           "address_1",
@@ -5896,7 +6119,8 @@
             "example": "st"
           },
           "country": {
-            "description": "A country object. Available if the relation `country` is expanded.",
+            "description": "A country object.",
+            "x-expandable": "country",
             "nullable": true,
             "$ref": "#/components/schemas/Country"
           },
@@ -5940,6 +6164,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -6084,7 +6312,7 @@
       },
       "BatchJob": {
         "title": "Batch Job",
-        "description": "A Batch Job.",
+        "description": "A Batch Job indicates an asynchronus task stored in the Medusa backend. Its status determines whether it has been executed or not.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -6139,7 +6367,8 @@
             "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"
           },
           "created_by_user": {
-            "description": "A user object. Available if the relation `created_by_user` is expanded.",
+            "description": "The details of the user that created the batch job.",
+            "x-expandable": "created_by_user",
             "nullable": true,
             "$ref": "#/components/schemas/User"
           },
@@ -6314,7 +6543,7 @@
       },
       "Cart": {
         "title": "Cart",
-        "description": "Represents a user cart",
+        "description": "A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.",
         "type": "object",
         "required": [
           "billing_address_id",
@@ -6354,7 +6583,8 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "billing_address": {
-            "description": "Available if the relation `billing_address` is expanded.",
+            "description": "The details of the billing address associated with the cart.",
+            "x-expandable": "billing_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
@@ -6365,13 +6595,15 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "shipping_address": {
-            "description": "Available if the relation `shipping_address` is expanded.",
+            "description": "The details of the shipping address associated with the cart.",
+            "x-expandable": "shipping_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "items": {
-            "description": "Available if the relation `items` is expanded.",
+            "description": "The line items added to the cart.",
             "type": "array",
+            "x-expandable": "items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
@@ -6382,20 +6614,23 @@
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region associated with the cart.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "discounts": {
-            "description": "Available if the relation `discounts` is expanded.",
+            "description": "An array of details of all discounts applied to the cart.",
             "type": "array",
+            "x-expandable": "discounts",
             "items": {
               "$ref": "#/components/schemas/Discount"
             }
           },
           "gift_cards": {
-            "description": "Available if the relation `gift_cards` is expanded.",
+            "description": "An array of details of all gift cards applied to the cart.",
             "type": "array",
+            "x-expandable": "gift_cards",
             "items": {
               "$ref": "#/components/schemas/GiftCard"
             }
@@ -6407,18 +6642,21 @@
             "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "customer": {
-            "description": "A customer object. Available if the relation `customer` is expanded.",
+            "description": "The details of the customer the cart belongs to.",
+            "x-expandable": "customer",
             "nullable": true,
             "$ref": "#/components/schemas/Customer"
           },
           "payment_session": {
-            "description": "The selected payment session in the cart.",
+            "description": "The details of the selected payment session in the cart.",
+            "x-expandable": "payment_session",
             "nullable": true,
             "$ref": "#/components/schemas/PaymentSession"
           },
           "payment_sessions": {
-            "description": "The payment sessions created on the cart.",
+            "description": "The details of all payment sessions created on the cart.",
             "type": "array",
+            "x-expandable": "payment_sessions",
             "items": {
               "$ref": "#/components/schemas/PaymentSession"
             }
@@ -6430,13 +6668,15 @@
             "example": "pay_01G8ZCC5W42ZNY842124G7P5R9"
           },
           "payment": {
-            "description": "Available if the relation `payment` is expanded.",
+            "description": "The details of the payment associated with the cart.",
             "nullable": true,
+            "x-expandable": "payment",
             "$ref": "#/components/schemas/Payment"
           },
           "shipping_methods": {
-            "description": "The shipping methods added to the cart.",
+            "description": "The details of the shipping methods added to the cart.",
             "type": "array",
+            "x-expandable": "shipping_methods",
             "items": {
               "$ref": "#/components/schemas/ShippingMethod"
             }
@@ -6490,8 +6730,9 @@
             "example": null
           },
           "sales_channel": {
-            "description": "A sales channel object. Available if the relation `sales_channel` is expanded.",
+            "description": "The details of the sales channel associated with the cart.",
             "nullable": true,
+            "x-expandable": "sales_channel",
             "$ref": "#/components/schemas/SalesChannel"
           },
           "created_at": {
@@ -6516,6 +6757,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           },
           "shipping_total": {
@@ -6582,7 +6827,7 @@
       },
       "ClaimImage": {
         "title": "Claim Image",
-        "description": "Represents photo documentation of a claim.",
+        "description": "The details of an image attached to a claim.",
         "type": "object",
         "required": [
           "claim_item_id",
@@ -6604,8 +6849,9 @@
             "type": "string"
           },
           "claim_item": {
-            "description": "A claim item object. Available if the relation `claim_item` is expanded.",
+            "description": "The details of the claim item this image is associated with.",
             "nullable": true,
+            "x-expandable": "claim_item",
             "$ref": "#/components/schemas/ClaimItem"
           },
           "url": {
@@ -6635,13 +6881,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ClaimItem": {
         "title": "Claim Item",
-        "description": "Represents a claimed item along with information about the reasons for the claim.",
+        "description": "A claim item is an item created as part of a claim. It references an item in the order that should be exchanged or refunded.",
         "type": "object",
         "required": [
           "claim_order_id",
@@ -6663,8 +6913,9 @@
             "example": "citm_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "images": {
-            "description": "Available if the relation `images` is expanded.",
+            "description": "The claim images that are attached to the claim item.",
             "type": "array",
+            "x-expandable": "images",
             "items": {
               "$ref": "#/components/schemas/ClaimImage"
             }
@@ -6674,7 +6925,8 @@
             "type": "string"
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim this item belongs to.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
@@ -6684,7 +6936,8 @@
             "example": "item_01G8ZM25TN49YV9EQBE2NC27KC"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item in the original order that this claim item refers to.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -6694,7 +6947,8 @@
             "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"
           },
           "variant": {
-            "description": "A variant object. Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant to potentially replace the item in the original order.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
@@ -6720,8 +6974,9 @@
             "example": 1
           },
           "tags": {
-            "description": "User defined tags for easy filtering and grouping. Available if the relation 'tags' is expanded.",
+            "description": "User defined tags for easy filtering and grouping.",
             "type": "array",
+            "x-expandable": "tags",
             "items": {
               "$ref": "#/components/schemas/ClaimTag"
             }
@@ -6748,13 +7003,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ClaimOrder": {
-        "title": "Claim Order",
-        "description": "Claim Orders represent a group of faulty or missing items. Each claim order consists of a subset of items associated with an original order, and can contain additional information about fulfillments and returns.",
+        "title": "Claim",
+        "description": "A Claim represents a group of faulty or missing items. It consists of claim items that refer to items in the original order that should be replaced or refunded. It also includes details related to shipping and fulfillment.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -6813,15 +7072,17 @@
             "default": "not_fulfilled"
           },
           "claim_items": {
-            "description": "The items that have been claimed",
+            "description": "The details of the items that should be replaced or refunded.",
             "type": "array",
+            "x-expandable": "claim_items",
             "items": {
               "$ref": "#/components/schemas/ClaimItem"
             }
           },
           "additional_items": {
-            "description": "Refers to the new items to be shipped when the claim order has the type `replace`",
+            "description": "The details of the new items to be shipped when the claim's type is `replace`",
             "type": "array",
+            "x-expandable": "additional_items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
@@ -6832,12 +7093,14 @@
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that this claim was created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "return_order": {
-            "description": "A return object. Holds information about the return if the claim is to be returned. Available if the relation 'return_order' is expanded",
+            "description": "The details of the return associated with the claim if the claim's type is `replace`.",
+            "x-expandable": "return_order",
             "nullable": true,
             "$ref": "#/components/schemas/Return"
           },
@@ -6848,13 +7111,15 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "shipping_address": {
-            "description": "Available if the relation `shipping_address` is expanded.",
+            "description": "The details of the address that new items should be shipped to.",
+            "x-expandable": "shipping_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "shipping_methods": {
-            "description": "The shipping methods that the claim order will be shipped with.",
+            "description": "The details of the shipping methods that the claim order will be shipped with.",
             "type": "array",
+            "x-expandable": "shipping_methods",
             "items": {
               "$ref": "#/components/schemas/ShippingMethod"
             }
@@ -6862,6 +7127,7 @@
           "fulfillments": {
             "description": "The fulfillments of the new items to be shipped",
             "type": "array",
+            "x-expandable": "fulfillments",
             "items": {
               "$ref": "#/components/schemas/Fulfillment"
             }
@@ -6900,6 +7166,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           },
           "no_notification": {
@@ -6964,6 +7234,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -7031,7 +7305,8 @@
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region the country is associated with.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           }
@@ -7109,15 +7384,16 @@
             "example": "US Dollar"
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Does the currency prices include tax",
+            "description": "Whether the currency prices include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           }
         }
       },
       "CustomShippingOption": {
         "title": "Custom Shipping Option",
-        "description": "Custom Shipping Options are 'overriden' Shipping Options. Store managers can attach a Custom Shipping Option to a cart in order to set a custom price for a particular Shipping Option",
+        "description": "Custom Shipping Options are overriden Shipping Options. Admins can attach a Custom Shipping Option to a cart in order to set a custom price for a particular Shipping Option.",
         "type": "object",
         "required": [
           "cart_id",
@@ -7146,7 +7422,8 @@
             "example": "so_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "shipping_option": {
-            "description": "A shipping option object. Available if the relation `shipping_option` is expanded.",
+            "description": "The details of the overriden shipping options.",
+            "x-expandable": "shipping_option",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingOption"
           },
@@ -7157,7 +7434,8 @@
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart this shipping option belongs to.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
@@ -7183,13 +7461,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "Customer": {
         "title": "Customer",
-        "description": "Represents a customer",
+        "description": "A customer can make purchases in your store and manage their profile.",
         "type": "object",
         "required": [
           "billing_address_id",
@@ -7234,13 +7516,15 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "billing_address": {
-            "description": "Available if the relation `billing_address` is expanded.",
+            "description": "The details of the billing address associated with the customer.",
+            "x-expandable": "billing_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "shipping_addresses": {
-            "description": "Available if the relation `shipping_addresses` is expanded.",
+            "description": "The details of the shipping addresses associated with the customer.",
             "type": "array",
+            "x-expandable": "shipping_addresses",
             "items": {
               "$ref": "#/components/schemas/Address"
             }
@@ -7257,15 +7541,17 @@
             "default": false
           },
           "orders": {
-            "description": "Available if the relation `orders` is expanded.",
+            "description": "The details of the orders this customer placed.",
             "type": "array",
+            "x-expandable": "orders",
             "items": {
               "$ref": "#/components/schemas/Order"
             }
           },
           "groups": {
-            "description": "The customer groups the customer belongs to. Available if the relation `groups` is expanded.",
+            "description": "The customer groups the customer belongs to.",
             "type": "array",
+            "x-expandable": "groups",
             "items": {
               "$ref": "#/components/schemas/CustomerGroup"
             }
@@ -7292,13 +7578,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "CustomerGroup": {
         "title": "Customer Group",
-        "description": "Represents a customer group",
+        "description": "A customer group that can be used to organize customers into groups of similar traits.",
         "type": "object",
         "required": [
           "created_at",
@@ -7320,15 +7610,17 @@
             "example": "VIP"
           },
           "customers": {
-            "description": "The customers that belong to the customer group. Available if the relation `customers` is expanded.",
+            "description": "The details of the customers that belong to the customer group.",
             "type": "array",
+            "x-expandable": "customers",
             "items": {
               "$ref": "#/components/schemas/Customer"
             }
           },
           "price_lists": {
-            "description": "The price lists that are associated with the customer group. Available if the relation `price_lists` is expanded.",
+            "description": "The price lists that are associated with the customer group.",
             "type": "array",
+            "x-expandable": "price_lists",
             "items": {
               "$ref": "#/components/schemas/PriceList"
             }
@@ -7355,13 +7647,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "Discount": {
         "title": "Discount",
-        "description": "Represents a discount that can be applied to a cart for promotional purposes.",
+        "description": "A discount can be applied to a cart for promotional purposes.",
         "type": "object",
         "required": [
           "code",
@@ -7397,13 +7693,14 @@
             "example": false
           },
           "rule_id": {
-            "description": "The Discount Rule that governs the behaviour of the Discount",
+            "description": "The ID of the discount rule that defines how the discount will be applied to a cart.",
             "nullable": true,
             "type": "string",
             "example": "dru_01F0YESMVK96HVX7N419E3CJ7C"
           },
           "rule": {
-            "description": "Available if the relation `rule` is expanded.",
+            "description": "The details of the discount rule that defines how the discount will be applied to a cart..",
+            "x-expandable": "rule",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountRule"
           },
@@ -7419,7 +7716,8 @@
             "example": "disc_01G8ZH853YPY9B94857DY91YGW"
           },
           "parent_discount": {
-            "description": "Available if the relation `parent_discount` is expanded.",
+            "description": "The details of the parent discount that this discount was created from.",
+            "x-expandable": "parent_discount",
             "nullable": true,
             "$ref": "#/components/schemas/Discount"
           },
@@ -7441,8 +7739,9 @@
             "example": "P3Y6M4DT12H30M5S"
           },
           "regions": {
-            "description": "The Regions in which the Discount can be used. Available if the relation `regions` is expanded.",
+            "description": "The details of the regions in which the Discount can be used.",
             "type": "array",
+            "x-expandable": "regions",
             "items": {
               "$ref": "#/components/schemas/Region"
             }
@@ -7481,6 +7780,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -7506,7 +7809,7 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "type": {
-            "description": "The type of the Condition",
+            "description": "The type of the condition. The type affects the available resources associated with the condition. For example, if the type is `products`, that means the `products` relation will hold the products associated with this condition and other relations will be empty.",
             "type": "string",
             "enum": [
               "products",
@@ -7517,7 +7820,7 @@
             ]
           },
           "operator": {
-            "description": "The operator of the Condition",
+            "description": "The operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that discountable resources are everything but the specified resources.",
             "type": "string",
             "enum": [
               "in",
@@ -7530,41 +7833,47 @@
             "example": "dru_01F0YESMVK96HVX7N419E3CJ7C"
           },
           "discount_rule": {
-            "description": "Available if the relation `discount_rule` is expanded.",
+            "description": "The details of the discount rule associated with the condition.",
+            "x-expandable": "discount_rule",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountRule"
           },
           "products": {
-            "description": "products associated with this condition if type = products. Available if the relation `products` is expanded.",
+            "description": "products associated with this condition if `type` is `products`.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
           },
           "product_types": {
-            "description": "Product types associated with this condition if type = product_types. Available if the relation `product_types` is expanded.",
+            "description": "Product types associated with this condition if `type` is `product_types`.",
             "type": "array",
+            "x-expandable": "product_types",
             "items": {
               "$ref": "#/components/schemas/ProductType"
             }
           },
           "product_tags": {
-            "description": "Product tags associated with this condition if type = product_tags. Available if the relation `product_tags` is expanded.",
+            "description": "Product tags associated with this condition if `type` is `product_tags`.",
             "type": "array",
+            "x-expandable": "product_tags",
             "items": {
               "$ref": "#/components/schemas/ProductTag"
             }
           },
           "product_collections": {
-            "description": "Product collections associated with this condition if type = product_collections. Available if the relation `product_collections` is expanded.",
+            "description": "Product collections associated with this condition if `type` is `product_collections`.",
             "type": "array",
+            "x-expandable": "product_collections",
             "items": {
               "$ref": "#/components/schemas/ProductCollection"
             }
           },
           "customer_groups": {
-            "description": "Customer groups associated with this condition if type = customer_groups. Available if the relation `customer_groups` is expanded.",
+            "description": "Customer groups associated with this condition if `type` is `customer_groups`.",
             "type": "array",
+            "x-expandable": "customer_groups",
             "items": {
               "$ref": "#/components/schemas/CustomerGroup"
             }
@@ -7591,6 +7900,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -7643,13 +7956,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountConditionProduct": {
         "title": "Product Discount Condition",
-        "description": "Associates a discount condition with a product",
+        "description": "This represents the association between a discount condition and a product",
         "type": "object",
         "required": [
           "condition_id",
@@ -7670,12 +7987,14 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product": {
-            "description": "Available if the relation `product` is expanded.",
+            "description": "The details of the product.",
+            "x-expandable": "product",
             "nullable": true,
             "$ref": "#/components/schemas/Product"
           },
           "discount_condition": {
-            "description": "Available if the relation `discount_condition` is expanded.",
+            "description": "The details of the discount condition.",
+            "x-expandable": "discount_condition",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountCondition"
           },
@@ -7695,13 +8014,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountConditionProductCollection": {
         "title": "Product Collection Discount Condition",
-        "description": "Associates a discount condition with a product collection",
+        "description": "This represents the association between a discount condition and a product collection",
         "type": "object",
         "required": [
           "condition_id",
@@ -7722,12 +8045,14 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product_collection": {
-            "description": "Available if the relation `product_collection` is expanded.",
+            "description": "The details of the product collection.",
+            "x-expandable": "product_collection",
             "nullable": true,
             "$ref": "#/components/schemas/ProductCollection"
           },
           "discount_condition": {
-            "description": "Available if the relation `discount_condition` is expanded.",
+            "description": "The details of the discount condition.",
+            "x-expandable": "discount_condition",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountCondition"
           },
@@ -7747,13 +8072,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountConditionProductTag": {
         "title": "Product Tag Discount Condition",
-        "description": "Associates a discount condition with a product tag",
+        "description": "This represents the association between a discount condition and a product tag",
         "type": "object",
         "required": [
           "condition_id",
@@ -7774,12 +8103,14 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product_tag": {
-            "description": "Available if the relation `product_tag` is expanded.",
+            "description": "The details of the product tag.",
+            "x-expandable": "product_tag",
             "nullable": true,
             "$ref": "#/components/schemas/ProductTag"
           },
           "discount_condition": {
-            "description": "Available if the relation `discount_condition` is expanded.",
+            "description": "The details of the discount condition.",
+            "x-expandable": "discount_condition",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountCondition"
           },
@@ -7799,13 +8130,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountConditionProductType": {
         "title": "Product Type Discount Condition",
-        "description": "Associates a discount condition with a product type",
+        "description": "This represents the association between a discount condition and a product type",
         "type": "object",
         "required": [
           "condition_id",
@@ -7826,12 +8161,14 @@
             "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product_type": {
-            "description": "Available if the relation `product_type` is expanded.",
+            "description": "The details of the product type.",
+            "x-expandable": "product_type",
             "nullable": true,
             "$ref": "#/components/schemas/ProductType"
           },
           "discount_condition": {
-            "description": "Available if the relation `discount_condition` is expanded.",
+            "description": "The details of the discount condition.",
+            "x-expandable": "discount_condition",
             "nullable": true,
             "$ref": "#/components/schemas/DiscountCondition"
           },
@@ -7851,13 +8188,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DiscountRule": {
         "title": "Discount Rule",
-        "description": "Holds the rules that governs how a Discount is calculated when applied to a Cart.",
+        "description": "A discount rule defines how a Discount is calculated when applied to a Cart.",
         "type": "object",
         "required": [
           "allocation",
@@ -7908,8 +8249,9 @@
             "example": "total"
           },
           "conditions": {
-            "description": "A set of conditions that can be used to limit when  the discount can be used. Available if the relation `conditions` is expanded.",
+            "description": "The details of the discount conditions associated with the rule. They can be used to limit when the discount can be used.",
             "type": "array",
+            "x-expandable": "conditions",
             "items": {
               "$ref": "#/components/schemas/DiscountCondition"
             }
@@ -7936,13 +8278,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "DraftOrder": {
         "title": "DraftOrder",
-        "description": "Represents a draft order",
+        "description": "A draft order is created by an admin without direct involvement of the customer. Once its payment is marked as captured, it is transformed into an order.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -7965,7 +8311,7 @@
             "example": "dorder_01G8TJFKBG38YYFQ035MSVG03C"
           },
           "status": {
-            "description": "The status of the draft order",
+            "description": "The status of the draft order. It's changed to `completed` when it's transformed to an order.",
             "type": "string",
             "enum": [
               "open",
@@ -7985,18 +8331,20 @@
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart associated with the draft order.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "order_id": {
-            "description": "The ID of the order associated with the draft order.",
+            "description": "The ID of the order created from the draft order when its payment is captured.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order created from the draft order when its payment is captured.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
@@ -8043,6 +8391,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -8117,7 +8469,7 @@
       },
       "Fulfillment": {
         "title": "Fulfillment",
-        "description": "Fulfillments are created once store operators can prepare the purchased goods. Fulfillments will eventually be shipped and hold information about how to track shipments. Fulfillments are created through a provider, which is typically an external shipping aggregator, shipping partner og 3PL, most plugins will have asynchronous communications with these providers through webhooks in order to automatically update and synchronize the state of Fulfillments.",
+        "description": "A Fulfillment is created once an admin can prepare the purchased goods. Fulfillments will eventually be shipped and hold information about how to track shipments. Fulfillments are created through a fulfillment provider, which typically integrates a third-party shipping service. Fulfillments can be associated with orders, claims, swaps, and returns.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -8143,64 +8495,70 @@
             "example": "ful_01G8ZRTMQCA76TXNAT81KPJZRF"
           },
           "claim_order_id": {
-            "description": "The id of the Claim that the Fulfillment belongs to.",
+            "description": "The ID of the Claim that the Fulfillment belongs to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim that the fulfillment may belong to.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
           "swap_id": {
-            "description": "The id of the Swap that the Fulfillment belongs to.",
+            "description": "The ID of the Swap that the Fulfillment belongs to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that the fulfillment may belong to.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "order_id": {
-            "description": "The id of the Order that the Fulfillment belongs to.",
+            "description": "The ID of the Order that the Fulfillment belongs to.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the fulfillment may belong to.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "provider_id": {
-            "description": "The id of the Fulfillment Provider responsible for handling the fulfillment",
+            "description": "The ID of the Fulfillment Provider responsible for handling the fulfillment.",
             "type": "string",
             "example": "manual"
           },
           "provider": {
-            "description": "Available if the relation `provider` is expanded.",
+            "description": "The details of the fulfillment provider responsible for handling the fulfillment.",
+            "x-expandable": "provider",
             "nullable": true,
             "$ref": "#/components/schemas/FulfillmentProvider"
           },
           "location_id": {
-            "description": "The id of the stock location the fulfillment will be shipped from",
+            "description": "The ID of the stock location the fulfillment will be shipped from",
             "nullable": true,
             "type": "string",
             "example": "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "items": {
-            "description": "The Fulfillment Items in the Fulfillment - these hold information about how many of each Line Item has been fulfilled. Available if the relation `items` is expanded.",
+            "description": "The Fulfillment Items in the Fulfillment. These hold information about how many of each Line Item has been fulfilled.",
             "type": "array",
+            "x-expandable": "items",
             "items": {
               "$ref": "#/components/schemas/FulfillmentItem"
             }
           },
           "tracking_links": {
-            "description": "The Tracking Links that can be used to track the status of the Fulfillment, these will usually be provided by the Fulfillment Provider. Available if the relation `tracking_links` is expanded.",
+            "description": "The Tracking Links that can be used to track the status of the Fulfillment. These will usually be provided by the Fulfillment Provider.",
             "type": "array",
+            "x-expandable": "tracking_links",
             "items": {
               "$ref": "#/components/schemas/TrackingLink"
             }
@@ -8261,13 +8619,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "FulfillmentItem": {
         "title": "Fulfillment Item",
-        "description": "Correlates a Line Item with a Fulfillment, keeping track of the quantity of the Line Item.",
+        "description": "This represents the association between a Line Item and a Fulfillment.",
         "type": "object",
         "required": [
           "fulfillment_id",
@@ -8276,22 +8638,24 @@
         ],
         "properties": {
           "fulfillment_id": {
-            "description": "The id of the Fulfillment that the Fulfillment Item belongs to.",
+            "description": "The ID of the Fulfillment that the Fulfillment Item belongs to.",
             "type": "string",
             "example": "ful_01G8ZRTMQCA76TXNAT81KPJZRF"
           },
           "item_id": {
-            "description": "The id of the Line Item that the Fulfillment Item references.",
+            "description": "The ID of the Line Item that the Fulfillment Item references.",
             "type": "string",
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "fulfillment": {
-            "description": "A fulfillment object. Available if the relation `fulfillment` is expanded.",
+            "description": "The details of the fulfillment.",
+            "x-expandable": "fulfillment",
             "nullable": true,
             "$ref": "#/components/schemas/Fulfillment"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -8304,7 +8668,7 @@
       },
       "FulfillmentProvider": {
         "title": "Fulfillment Provider",
-        "description": "Represents a fulfillment provider plugin and holds its installation status.",
+        "description": "A fulfillment provider represents a fulfillment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the fulfillment service's installation status.",
         "type": "object",
         "required": [
           "id",
@@ -8312,12 +8676,12 @@
         ],
         "properties": {
           "id": {
-            "description": "The id of the fulfillment provider as given by the plugin.",
+            "description": "The ID of the fulfillment provider as given by the fulfillment service.",
             "type": "string",
             "example": "manual"
           },
           "is_installed": {
-            "description": "Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`.",
+            "description": "Whether the fulfillment service is installed in the current version. If a fulfillment service is no longer installed, the `is_installed` attribute is set to `false`.",
             "type": "boolean",
             "default": true
           }
@@ -8364,23 +8728,25 @@
             "example": 10
           },
           "region_id": {
-            "description": "The id of the Region in which the Gift Card is available.",
+            "description": "The ID of the region this gift card is available in.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region this gift card is available in.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "order_id": {
-            "description": "The id of the Order that the Gift Card was purchased in.",
+            "description": "The ID of the order that the gift card was purchased in.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the gift card was purchased in.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
@@ -8423,13 +8789,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "GiftCardTransaction": {
         "title": "Gift Card Transaction",
-        "description": "Gift Card Transactions are created once a Customer uses a Gift Card to pay for their Order",
+        "description": "Gift Card Transactions are created once a Customer uses a Gift Card to pay for their Order.",
         "type": "object",
         "required": [
           "amount",
@@ -8452,17 +8822,19 @@
             "example": "gift_01G8XKBPBQY2R7RBET4J7E0XQZ"
           },
           "gift_card": {
-            "description": "A gift card object. Available if the relation `gift_card` is expanded.",
+            "description": "The details of the gift card associated used in this transaction.",
+            "x-expandable": "gift_card",
             "nullable": true,
             "$ref": "#/components/schemas/GiftCard"
           },
           "order_id": {
-            "description": "The ID of the Order that the Gift Card was used to pay for.",
+            "description": "The ID of the order that the gift card was used for payment.",
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the gift card was used for payment.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
@@ -8574,7 +8946,7 @@
       },
       "Image": {
         "title": "Image",
-        "description": "Images holds a reference to a URL at which the image file can be found.",
+        "description": "An Image is used to store details about uploaded images. Images are uploaded by the File Service, and the URL is provided by the File Service.",
         "type": "object",
         "required": [
           "created_at",
@@ -8617,6 +8989,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -8755,7 +9131,7 @@
       },
       "Invite": {
         "title": "Invite",
-        "description": "Represents an invite",
+        "description": "An invite is created when an admin user invites a new user to join the store's team. Once the invite is accepted, it's deleted.",
         "type": "object",
         "required": [
           "accepted",
@@ -8781,7 +9157,7 @@
             "format": "email"
           },
           "role": {
-            "description": "The user's role.",
+            "description": "The user's role. These roles don't change the privileges of the user.",
             "nullable": true,
             "type": "string",
             "enum": [
@@ -8827,13 +9203,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "LineItem": {
         "title": "Line Item",
-        "description": "Line Items represent purchasable units that can be added to a Cart for checkout. When Line Items are purchased they will get copied to the resulting order and can eventually be referenced in Fulfillments and Returns. Line Items may also be created when processing Swaps and Claims.",
+        "description": "Line Items are created when a product is added to a Cart. When Line Items are purchased they will get copied to the resulting order, swap, or claim, and can eventually be referenced in Fulfillments and Returns. Line items may also be used for order edits.",
         "type": "object",
         "required": [
           "allow_discounts",
@@ -8868,80 +9248,87 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "cart_id": {
-            "description": "The ID of the Cart that the Line Item belongs to.",
+            "description": "The ID of the cart that the line item may belongs to.",
             "nullable": true,
             "type": "string",
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the line item may belongs to.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "order_id": {
-            "description": "The ID of the Order that the Line Item belongs to.",
+            "description": "The ID of the order that the line item may belongs to.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the line item may belongs to.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "swap_id": {
-            "description": "The id of the Swap that the Line Item belongs to.",
+            "description": "The ID of the swap that the line item may belong to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that the line item may belong to.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "claim_order_id": {
-            "description": "The id of the Claim that the Line Item belongs to.",
+            "description": "The ID of the claim that the line item may belong to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim that the line item may belong to.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
           "tax_lines": {
-            "description": "Available if the relation `tax_lines` is expanded.",
+            "description": "The details of the item's tax lines.",
+            "x-expandable": "tax_lines",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/LineItemTaxLine"
             }
           },
           "adjustments": {
-            "description": "Available if the relation `adjustments` is expanded.",
+            "description": "The details of the item's adjustments, which are available when a discount is applied on the item.",
+            "x-expandable": "adjustments",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/LineItemAdjustment"
             }
           },
           "original_item_id": {
-            "description": "The id of the original line item",
+            "description": "The ID of the original line item. This is useful if the line item belongs to a resource that references an order, such as a return or an order edit.",
             "nullable": true,
             "type": "string"
           },
           "order_edit_id": {
-            "description": "The ID of the order edit to which a cloned item belongs",
+            "description": "The ID of the order edit that the item may belong to.",
             "nullable": true,
             "type": "string"
           },
           "order_edit": {
-            "description": "The order edit joined. Available if the relation `order_edit` is expanded.",
+            "description": "The details of the order edit.",
+            "x-expandable": "order_edit",
             "nullable": true,
             "$ref": "#/components/schemas/OrderEdit"
           },
           "title": {
-            "description": "The title of the Line Item, this should be easily identifiable by the Customer.",
+            "description": "The title of the Line Item.",
             "type": "string",
             "example": "Medusa Coffee Mug"
           },
@@ -8996,7 +9383,8 @@
             "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"
           },
           "variant": {
-            "description": "A product variant object. The Product Variant contained in the Line Item. Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant that this item was created from.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
@@ -9069,7 +9457,8 @@
             "example": 0
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Indicates if the line item unit_price include tax",
+            "description": "Indicates if the line item unit_price include tax",
+            "x-featureFlag": "tax_inclusive_pricing",
             "type": "boolean",
             "default": false
           },
@@ -9089,13 +9478,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "LineItemAdjustment": {
         "title": "Line Item Adjustment",
-        "description": "Represents a Line Item Adjustment",
+        "description": "A Line Item Adjustment includes details on discounts applied on a line item.",
         "type": "object",
         "required": [
           "amount",
@@ -9117,7 +9510,8 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -9133,7 +9527,8 @@
             "example": "disc_01F0YESMW10MGHWJKZSDDMN0VN"
           },
           "discount": {
-            "description": "Available if the relation `discount` is expanded.",
+            "description": "The details of the discount associated with the adjustment.",
+            "x-expandable": "discount",
             "nullable": true,
             "$ref": "#/components/schemas/Discount"
           },
@@ -9148,13 +9543,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "LineItemTaxLine": {
         "title": "Line Item Tax Line",
-        "description": "Represents a Line Item Tax Line",
+        "description": "A Line Item Tax Line represents the taxes applied on a line item.",
         "type": "object",
         "required": [
           "code",
@@ -9194,7 +9593,8 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -9214,6 +9614,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -9240,7 +9644,7 @@
       },
       "MoneyAmount": {
         "title": "Money Amount",
-        "description": "Money Amounts represents an amount that a given Product Variant can be purcased for. Each Money Amount either has a Currency or Region associated with it to indicate the pricing in a given Currency or, for fully region-based pricing, the given price in a specific Region. If region-based pricing is used the amount will be in the currency defined for the Reigon.",
+        "description": "A Money Amount represent a price amount, for example, a product variant's price or a price in a price list. Each Money Amount either has a Currency or Region associated with it to indicate the pricing in a given Currency or, for fully region-based pricing, the given price in a specific Region. If region-based pricing is used, the amount will be in the currency defined for the Region.",
         "type": "object",
         "required": [
           "amount",
@@ -9262,7 +9666,7 @@
             "example": "ma_01F0YESHRFQNH5S8Q0PK84YYZN"
           },
           "currency_code": {
-            "description": "The 3 character currency code that the Money Amount is given in.",
+            "description": "The 3 character currency code that the money amount may belong to.",
             "type": "string",
             "example": "usd",
             "externalDocs": {
@@ -9271,7 +9675,8 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency that the money amount may belong to.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
@@ -9293,24 +9698,26 @@
             "example": 1
           },
           "price_list_id": {
-            "description": "The ID of the price list associated with the money amount",
+            "description": "The ID of the price list that the money amount may belong to.",
             "nullable": true,
             "type": "string",
             "example": "pl_01G8X3CKJXCG5VXVZ87H9KC09W"
           },
           "price_list": {
-            "description": "Available if the relation `price_list` is expanded.",
+            "description": "The details of the price list that the money amount may belong to.",
+            "x-expandable": "price_list",
             "nullable": true,
             "$ref": "#/components/schemas/PriceList"
           },
           "variant_id": {
-            "description": "The id of the Product Variant contained in the Line Item.",
+            "description": "The ID of the Product Variant contained in the Line Item.",
             "nullable": true,
             "type": "string",
             "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"
           },
           "variant": {
-            "description": "The Product Variant contained in the Line Item. Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant that the money amount may belong to.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
@@ -9321,7 +9728,8 @@
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region that the money amount may belong to.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
@@ -9362,7 +9770,7 @@
       },
       "Note": {
         "title": "Note",
-        "description": "Notes are elements which we can use in association with different resources to allow users to describe additional information in relation to these.",
+        "description": "A Note is an element that can be used in association with different resources to allow admin users to describe additional information. For example, they can be used to add additional information about orders.",
         "type": "object",
         "required": [
           "author_id",
@@ -9397,13 +9805,14 @@
             "example": "This order must be fulfilled on Monday"
           },
           "author_id": {
-            "description": "The ID of the author (user)",
+            "description": "The ID of the user that created the note.",
             "nullable": true,
             "type": "string",
             "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"
           },
           "author": {
-            "description": "Available if the relation `author` is expanded.",
+            "description": "The details of the user that created the note.",
+            "x-expandable": "author",
             "nullable": true,
             "$ref": "#/components/schemas/User"
           },
@@ -9435,7 +9844,7 @@
       },
       "Notification": {
         "title": "Notification",
-        "description": "Notifications a communications sent via Notification Providers as a reaction to internal events such as `order.placed`. Notifications can be used to show a chronological timeline for communications sent to a Customer regarding an Order, and enables resends.",
+        "description": "A notification is an alert sent, typically to customers, using the installed Notification Provider as a reaction to internal events such as `order.placed`. Notifications can be resent.",
         "type": "object",
         "required": [
           "created_at",
@@ -9473,18 +9882,19 @@
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "customer_id": {
-            "description": "The ID of the Customer that the Notification was sent to.",
+            "description": "The ID of the customer that this notification was sent to.",
             "nullable": true,
             "type": "string",
             "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "customer": {
-            "description": "A customer object. Available if the relation `customer` is expanded.",
+            "description": "The details of the customer that this notification was sent to.",
+            "x-expandable": "customer",
             "nullable": true,
             "$ref": "#/components/schemas/Customer"
           },
           "to": {
-            "description": "The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id",
+            "description": "The address that the Notification was sent to. This will usually be an email address, but can represent other addresses such as a chat bot user ID.",
             "type": "string",
             "example": "user@example.com"
           },
@@ -9500,25 +9910,28 @@
             "example": "noti_01G53V9Y6CKMCGBM1P0X7C28RX"
           },
           "parent_notification": {
-            "description": "Available if the relation `parent_notification` is expanded.",
+            "description": "The details of the parent notification.",
+            "x-expandable": "parent_notification",
             "nullable": true,
             "$ref": "#/components/schemas/Notification"
           },
           "resends": {
-            "description": "The resends that have been completed after the original Notification. Available if the relation `resends` is expanded.",
+            "description": "The details of all resends of the notification.",
             "type": "array",
+            "x-expandable": "resends",
             "items": {
               "$ref": "#/components/schemas/Notification"
             }
           },
           "provider_id": {
-            "description": "The id of the Notification Provider that handles the Notification.",
+            "description": "The ID of the notification provider used to send the notification.",
             "nullable": true,
             "type": "string",
             "example": "sengrid"
           },
           "provider": {
-            "description": "Available if the relation `provider` is expanded.",
+            "description": "The notification provider used to send the notification.",
+            "x-expandable": "provider",
             "nullable": true,
             "$ref": "#/components/schemas/NotificationProvider"
           },
@@ -9536,7 +9949,7 @@
       },
       "NotificationProvider": {
         "title": "Notification Provider",
-        "description": "Represents a notification provider plugin and holds its installation status.",
+        "description": "A notification provider represents a notification service installed in the Medusa backend, either through a plugin or backend customizations. It holds the notification service's installation status.",
         "type": "object",
         "required": [
           "id",
@@ -9544,12 +9957,12 @@
         ],
         "properties": {
           "id": {
-            "description": "The id of the notification provider as given by the plugin.",
+            "description": "The ID of the notification provider as given by the notification service.",
             "type": "string",
             "example": "sendgrid"
           },
           "is_installed": {
-            "description": "Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`.",
+            "description": "Whether the notification service is installed in the current version. If a notification service is no longer installed, the `is_installed` attribute is set to `false`.",
             "type": "boolean",
             "default": true
           }
@@ -9557,7 +9970,7 @@
       },
       "OAuth": {
         "title": "OAuth",
-        "description": "Represent an OAuth app",
+        "description": "An Oauth app is typically created by a plugin to handle authentication to third-party services.",
         "type": "object",
         "required": [
           "application_name",
@@ -9605,7 +10018,7 @@
       },
       "Order": {
         "title": "Order",
-        "description": "Represents an order",
+        "description": "An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.",
         "type": "object",
         "required": [
           "billing_address_id",
@@ -9691,7 +10104,8 @@
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart associated with the order.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
@@ -9701,7 +10115,8 @@
             "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "customer": {
-            "description": "A customer object. Available if the relation `customer` is expanded.",
+            "description": "The details of the customer associated with the order.",
+            "x-expandable": "customer",
             "nullable": true,
             "$ref": "#/components/schemas/Customer"
           },
@@ -9717,7 +10132,8 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "billing_address": {
-            "description": "Available if the relation `billing_address` is expanded.",
+            "description": "The details of the billing address associated with the order.",
+            "x-expandable": "billing_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
@@ -9728,17 +10144,19 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "shipping_address": {
-            "description": "Available if the relation `shipping_address` is expanded.",
+            "description": "The details of the shipping address associated with the order.",
+            "x-expandable": "shipping_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "region_id": {
-            "description": "The region's ID",
+            "description": "The ID of the region this order was created in.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region this order was created in.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
@@ -9752,7 +10170,8 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency used in the order.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
@@ -9763,96 +10182,109 @@
             "example": 0
           },
           "discounts": {
-            "description": "The discounts used in the order. Available if the relation `discounts` is expanded.",
+            "description": "The details of the discounts applied on the order.",
             "type": "array",
+            "x-expandable": "discounts",
             "items": {
               "$ref": "#/components/schemas/Discount"
             }
           },
           "gift_cards": {
-            "description": "The gift cards used in the order. Available if the relation `gift_cards` is expanded.",
+            "description": "The details of the gift card used in the order.",
             "type": "array",
+            "x-expandable": "gift_cards",
             "items": {
               "$ref": "#/components/schemas/GiftCard"
             }
           },
           "shipping_methods": {
-            "description": "The shipping methods used in the order. Available if the relation `shipping_methods` is expanded.",
+            "description": "The details of the shipping methods used in the order.",
             "type": "array",
+            "x-expandable": "shipping_methods",
             "items": {
               "$ref": "#/components/schemas/ShippingMethod"
             }
           },
           "payments": {
-            "description": "The payments used in the order. Available if the relation `payments` is expanded.",
+            "description": "The details of the payments used in the order.",
             "type": "array",
+            "x-expandable": "payments",
             "items": {
               "$ref": "#/components/schemas/Payment"
             }
           },
           "fulfillments": {
-            "description": "The fulfillments used in the order. Available if the relation `fulfillments` is expanded.",
+            "description": "The details of the fulfillments created for the order.",
             "type": "array",
+            "x-expandable": "fulfillments",
             "items": {
               "$ref": "#/components/schemas/Fulfillment"
             }
           },
           "returns": {
-            "description": "The returns associated with the order. Available if the relation `returns` is expanded.",
+            "description": "The details of the returns created for the order.",
             "type": "array",
+            "x-expandable": "returns",
             "items": {
               "$ref": "#/components/schemas/Return"
             }
           },
           "claims": {
-            "description": "The claims associated with the order. Available if the relation `claims` is expanded.",
+            "description": "The details of the claims created for the order.",
             "type": "array",
+            "x-expandable": "claims",
             "items": {
               "$ref": "#/components/schemas/ClaimOrder"
             }
           },
           "refunds": {
-            "description": "The refunds associated with the order. Available if the relation `refunds` is expanded.",
+            "description": "The details of the refunds created for the order.",
             "type": "array",
+            "x-expandable": "refunds",
             "items": {
               "$ref": "#/components/schemas/Refund"
             }
           },
           "swaps": {
-            "description": "The swaps associated with the order. Available if the relation `swaps` is expanded.",
+            "description": "The details of the swaps created for the order.",
             "type": "array",
+            "x-expandable": "swaps",
             "items": {
               "$ref": "#/components/schemas/Swap"
             }
           },
           "draft_order_id": {
-            "description": "The ID of the draft order this order is associated with.",
+            "description": "The ID of the draft order this order was created from.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "draft_order": {
-            "description": "A draft order object. Available if the relation `draft_order` is expanded.",
+            "description": "The details of the draft order this order was created from.",
+            "x-expandable": "draft_order",
             "nullable": true,
             "$ref": "#/components/schemas/DraftOrder"
           },
           "items": {
-            "description": "The line items that belong to the order. Available if the relation `items` is expanded.",
+            "description": "The details of the line items that belong to the order.",
+            "x-expandable": "items",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
           },
           "edits": {
-            "description": "Order edits done on the order. Available if the relation `edits` is expanded.",
+            "description": "The details of the order edits done on the order.",
             "type": "array",
+            "x-expandable": "edits",
             "items": {
               "$ref": "#/components/schemas/OrderEdit"
             }
           },
           "gift_card_transactions": {
-            "description": "The gift card transactions used in the order. Available if the relation `gift_card_transactions` is expanded.",
+            "description": "The gift card transactions made in the order.",
             "type": "array",
+            "x-expandable": "gift_card_transactions",
             "items": {
               "$ref": "#/components/schemas/GiftCardTransaction"
             }
@@ -9885,13 +10317,14 @@
             "example": null
           },
           "sales_channel_id": {
-            "description": "The ID of the sales channel this order is associated with.",
+            "description": "The ID of the sales channel this order belongs to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "sales_channel": {
-            "description": "A sales channel object. Available if the relation `sales_channel` is expanded.",
+            "description": "The details of the sales channel this order belongs to.",
+            "x-expandable": "sales_channel",
             "nullable": true,
             "$ref": "#/components/schemas/SalesChannel"
           },
@@ -9951,8 +10384,9 @@
             "example": 0
           },
           "returnable_items": {
-            "description": "The items that are returnable as part of the order, order swaps or order claims",
+            "description": "The details of the line items that are returnable as part of the order, swaps, or claims",
             "type": "array",
+            "x-expandable": "returnable_items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
@@ -9973,13 +10407,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "OrderEdit": {
         "title": "Order Edit",
-        "description": "Order edit keeps track of order items changes.",
+        "description": "Order edit allows modifying items in an order, such as adding, updating, or deleting items from the original order. Once the order edit is confirmed, the changes are reflected on the original order.",
         "type": "object",
         "required": [
           "canceled_at",
@@ -10012,12 +10450,14 @@
             "example": "order_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "order": {
-            "description": "Available if the relation `order` is expanded.",
+            "description": "The details of the order that this order edit was created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "changes": {
-            "description": "Available if the relation `changes` is expanded.",
+            "description": "The details of all the changes on the original order's line items.",
+            "x-expandable": "changes",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/OrderItemChange"
@@ -10134,8 +10574,9 @@
             ]
           },
           "items": {
-            "description": "Available if the relation `items` is expanded.",
+            "description": "The details of the cloned items from the original order with the new changes. Once the order edit is confirmed, these line items are associated with the original order.",
             "type": "array",
+            "x-expandable": "items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
@@ -10147,7 +10588,8 @@
             "example": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "payment_collection": {
-            "description": "Available if the relation `payment_collection` is expanded.",
+            "description": "The details of the payment collection used to authorize additional payment if necessary.",
+            "x-expandable": "payment_collection",
             "nullable": true,
             "$ref": "#/components/schemas/PaymentCollection"
           },
@@ -10165,7 +10607,7 @@
       },
       "OrderItemChange": {
         "title": "Order Item Change",
-        "description": "Represents an order edit item change",
+        "description": "An order item change is a change made within an order edit to an order's items. These changes are not reflected on the original order until the order edit is confirmed.",
         "type": "object",
         "required": [
           "created_at",
@@ -10198,7 +10640,8 @@
             "example": "oe_01G2SG30J8C85S4A5CHM2S1NS2"
           },
           "order_edit": {
-            "description": "Available if the relation `order_edit` is expanded.",
+            "description": "The details of the order edit the item change is associated with.",
+            "x-expandable": "order_edit",
             "nullable": true,
             "$ref": "#/components/schemas/OrderEdit"
           },
@@ -10209,7 +10652,8 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "original_line_item": {
-            "description": "Available if the relation `original_line_item` is expanded.",
+            "description": "The details of the original line item this item change references. This is used if the item change updates or deletes the original item.",
+            "x-expandable": "original_line_item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -10220,7 +10664,8 @@
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "line_item": {
-            "description": "Available if the relation `line_item` is expanded.",
+            "description": "The details of the resulting line item after the item change. This line item is then used in the original order once the order edit is confirmed.",
+            "x-expandable": "line_item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
@@ -10244,7 +10689,7 @@
       },
       "Payment": {
         "title": "Payment",
-        "description": "Payments represent an amount authorized with a given payment method, Payments can be captured, canceled or refunded.",
+        "description": "A payment is originally created from a payment session. Once a payment session is authorized, the payment is created to represent the authorized amount with a given payment method. Payments can be captured, canceled or refunded. Payments can be made towards orders, swaps, order edits, or other resources.",
         "type": "object",
         "required": [
           "amount",
@@ -10270,34 +10715,37 @@
             "example": "pay_01G2SJNT6DEEWDFNAJ4XWDTHKE"
           },
           "swap_id": {
-            "description": "The ID of the Swap that the Payment is used for.",
+            "description": "The ID of the swap that this payment was potentially created for.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that this payment was potentially created for.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "cart_id": {
-            "description": "The id of the Cart that the Payment Session is created for.",
+            "description": "The ID of the cart that the payment session was potentially created for.",
             "nullable": true,
             "type": "string"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the payment session was potentially created for.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "order_id": {
-            "description": "The ID of the Order that the Payment is used for.",
+            "description": "The ID of the order that the payment session was potentially created for.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the payment session was potentially created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
@@ -10307,7 +10755,7 @@
             "example": 100
           },
           "currency_code": {
-            "description": "The 3 character ISO currency code that the Payment is completed in.",
+            "description": "The 3 character ISO currency code of the payment.",
             "type": "string",
             "example": "usd",
             "externalDocs": {
@@ -10316,7 +10764,8 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency of the payment.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
@@ -10373,13 +10822,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "PaymentCollection": {
         "title": "Payment Collection",
-        "description": "Payment Collection",
+        "description": "A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.",
         "type": "object",
         "required": [
           "amount",
@@ -10435,17 +10888,18 @@
             "type": "integer"
           },
           "region_id": {
-            "description": "The region's ID",
+            "description": "The ID of the region this payment collection is associated with.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "Available if the relation `region` is expanded.",
+            "description": "The details of the region this payment collection is associated with.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "currency_code": {
-            "description": "The 3 character ISO code for the currency.",
+            "description": "The 3 character ISO code for the currency this payment collection is associated with.",
             "type": "string",
             "example": "usd",
             "externalDocs": {
@@ -10454,20 +10908,23 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency this payment collection is associated with.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
           "payment_sessions": {
-            "description": "Available if the relation `payment_sessions` is expanded.",
+            "description": "The details of the payment sessions created as part of the payment collection.",
             "type": "array",
+            "x-expandable": "payment_sessions",
             "items": {
               "$ref": "#/components/schemas/PaymentSession"
             }
           },
           "payments": {
-            "description": "Available if the relation `payments` is expanded.",
+            "description": "The details of the payments created as part of the payment collection.",
             "type": "array",
+            "x-expandable": "payments",
             "items": {
               "$ref": "#/components/schemas/Payment"
             }
@@ -10498,13 +10955,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "PaymentProvider": {
         "title": "Payment Provider",
-        "description": "Represents a Payment Provider plugin and holds its installation status.",
+        "description": "A payment provider represents a payment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the payment service's installation status.",
         "type": "object",
         "required": [
           "id",
@@ -10512,12 +10973,12 @@
         ],
         "properties": {
           "id": {
-            "description": "The id of the payment provider as given by the plugin.",
+            "description": "The ID of the payment provider as given by the payment service.",
             "type": "string",
             "example": "manual"
           },
           "is_installed": {
-            "description": "Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`.",
+            "description": "Whether the payment service is installed in the current version. If a payment service is no longer installed, the `is_installed` attribute is set to `false`.",
             "type": "boolean",
             "default": true
           }
@@ -10525,7 +10986,7 @@
       },
       "PaymentSession": {
         "title": "Payment Session",
-        "description": "Payment Sessions are created when a Customer initilizes the checkout flow, and can be used to hold the state of a payment flow. Each Payment Session is controlled by a Payment Provider, who is responsible for the communication with external payment services. Authorized Payment Sessions will eventually get promoted to Payments to indicate that they are authorized for capture/refunds/etc.",
+        "description": "A Payment Session is created when a Customer initilizes the checkout flow, and can be used to hold the state of a payment flow. Each Payment Session is controlled by a Payment Provider, which is responsible for the communication with external payment services. Authorized Payment Sessions will eventually get promoted to Payments to indicate that they are authorized for payment processing such as capture or refund. Payment sessions can also be used as part of payment collections.",
         "type": "object",
         "required": [
           "amount",
@@ -10548,18 +11009,19 @@
             "example": "ps_01G901XNSRM2YS3ASN9H5KG3FZ"
           },
           "cart_id": {
-            "description": "The id of the Cart that the Payment Session is created for.",
+            "description": "The ID of the cart that the payment session was created for.",
             "nullable": true,
             "type": "string",
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the payment session was created for.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "provider_id": {
-            "description": "The id of the Payment Provider that is responsible for the Payment Session",
+            "description": "The ID of the Payment Provider that is responsible for the Payment Session",
             "type": "string",
             "example": "manual"
           },
@@ -10627,7 +11089,7 @@
       },
       "PriceList": {
         "title": "Price List",
-        "description": "Price Lists represents a set of prices that overrides the default price for one or more product variants.",
+        "description": "A Price List represents a set of prices that override the default price for one or more product variants.",
         "type": "object",
         "required": [
           "created_at",
@@ -10688,22 +11150,25 @@
             "format": "date-time"
           },
           "customer_groups": {
-            "description": "The Customer Groups that the Price List applies to. Available if the relation `customer_groups` is expanded.",
+            "description": "The details of the customer groups that the Price List can apply to.",
             "type": "array",
+            "x-expandable": "customer_groups",
             "items": {
               "$ref": "#/components/schemas/CustomerGroup"
             }
           },
           "prices": {
-            "description": "The Money Amounts that are associated with the Price List. Available if the relation `prices` is expanded.",
+            "description": "The prices that belong to the price list, represented as a Money Amount.",
             "type": "array",
+            "x-expandable": "prices",
             "items": {
               "$ref": "#/components/schemas/MoneyAmount"
             }
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Does the price list prices include tax",
+            "description": "Whether the price list prices include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           },
           "created_at": {
@@ -10848,7 +11313,7 @@
       },
       "Product": {
         "title": "Product",
-        "description": "Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.",
+        "description": "A product is a saleable item that holds general information such as name or description. It must include at least one Product Variant, where each product variant defines different options to purchase the product with (for example, different sizes or colors). The prices and inventory of the product are defined on the variant level.",
         "type": "object",
         "required": [
           "collection_id",
@@ -10922,8 +11387,9 @@
             "default": "draft"
           },
           "images": {
-            "description": "Images of the Product. Available if the relation `images` is expanded.",
+            "description": "The details of the product's images.",
             "type": "array",
+            "x-expandable": "images",
             "items": {
               "$ref": "#/components/schemas/Image"
             }
@@ -10935,36 +11401,49 @@
             "format": "uri"
           },
           "options": {
-            "description": "The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation `options` is expanded.",
+            "description": "The details of the Product Options that are defined for the Product. The product's variants will have a unique combination of values of the product's options.",
             "type": "array",
+            "x-expandable": "options",
             "items": {
               "$ref": "#/components/schemas/ProductOption"
             }
           },
           "variants": {
-            "description": "The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation `variants` is expanded.",
+            "description": "The details of the Product Variants that belong to the Product. Each will have a unique combination of values of the product's options.",
             "type": "array",
+            "x-expandable": "variants",
             "items": {
               "$ref": "#/components/schemas/ProductVariant"
             }
           },
           "categories": {
-            "description": "The product's associated categories. Available if the relation `categories` are expanded.",
+            "description": "The details of the product categories that this product belongs to.",
             "type": "array",
+            "x-expandable": "categories",
+            "x-featureFlag": "product_categories",
             "items": {
               "$ref": "#/components/schemas/ProductCategory"
             }
           },
           "profile_id": {
-            "description": "The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.",
+            "description": "The ID of the shipping profile that the product belongs to. The shipping profile has a set of defined shipping options that can be used to fulfill the product.",
             "type": "string",
             "example": "sp_01G1G5V239ENSZ5MV4JAR737BM"
           },
           "profile": {
-            "description": "Available if the relation `profile` is expanded.",
+            "description": "The details of the shipping profile that the product belongs to. The shipping profile has a set of defined shipping options that can be used to fulfill the product.",
+            "x-expandable": "profile",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingProfile"
           },
+          "profiles": {
+            "description": "Available if the relation `profiles` is expanded.",
+            "nullable": true,
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ShippingProfile"
+            }
+          },
           "weight": {
             "description": "The weight of the Product Variant. May be used in shipping rate calculations.",
             "nullable": true,
@@ -11014,30 +11493,33 @@
             "example": null
           },
           "collection_id": {
-            "description": "The Product Collection that the Product belongs to",
+            "description": "The ID of the product collection that the product belongs to.",
             "nullable": true,
             "type": "string",
             "example": "pcol_01F0YESBFAZ0DV6V831JXWH0BG"
           },
           "collection": {
-            "description": "A product collection object. Available if the relation `collection` is expanded.",
+            "description": "The details of the product collection that the product belongs to.",
+            "x-expandable": "collection",
             "nullable": true,
             "$ref": "#/components/schemas/ProductCollection"
           },
           "type_id": {
-            "description": "The Product type that the Product belongs to",
+            "description": "The ID of the product type that the product belongs to.",
             "nullable": true,
             "type": "string",
             "example": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "type": {
-            "description": "Available if the relation `type` is expanded.",
+            "description": "The details of the product type that the product belongs to.",
+            "x-expandable": "type",
             "nullable": true,
             "$ref": "#/components/schemas/ProductType"
           },
           "tags": {
-            "description": "The Product Tags assigned to the Product. Available if the relation `tags` is expanded.",
+            "description": "The details of the product tags used in this product.",
             "type": "array",
+            "x-expandable": "type",
             "items": {
               "$ref": "#/components/schemas/ProductTag"
             }
@@ -11054,8 +11536,9 @@
             "example": null
           },
           "sales_channels": {
-            "description": "The sales channels the product is associated with. Available if the relation `sales_channels` is expanded.",
+            "description": "The details of the sales channels this product is available in.",
             "type": "array",
+            "x-expandable": "sales_channels",
             "items": {
               "$ref": "#/components/schemas/SalesChannel"
             }
@@ -11082,14 +11565,19 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductCategory": {
-        "title": "ProductCategory",
-        "description": "Represents a product category",
+        "title": "Product Category",
+        "description": "A product category can be used to categorize products into a hierarchy of categories.",
         "x-resourceId": "ProductCategory",
+        "x-featureFlag": "product_categories",
         "type": "object",
         "required": [
           "category_children",
@@ -11141,8 +11629,9 @@
             "default": 0
           },
           "category_children": {
-            "description": "Available if the relation `category_children` are expanded.",
+            "description": "The details of the category's children.",
             "type": "array",
+            "x-expandable": "category_children",
             "items": {
               "$ref": "#/components/schemas/ProductCategory"
             }
@@ -11154,13 +11643,15 @@
             "default": null
           },
           "parent_category": {
-            "description": "A product category object. Available if the relation `parent_category` is expanded.",
+            "description": "The details of the parent of this category.",
+            "x-expandable": "parent_category",
             "nullable": true,
             "$ref": "#/components/schemas/ProductCategory"
           },
           "products": {
-            "description": "Products associated with category. Available if the relation `products` is expanded.",
+            "description": "The details of the products that belong to this category.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
@@ -11179,7 +11670,7 @@
       },
       "ProductCollection": {
         "title": "Product Collection",
-        "description": "Product Collections represents a group of Products that are related.",
+        "description": "A Product Collection allows grouping together products for promotional purposes. For example, an admin can create a Summer collection, add products to it, and showcase it on the storefront.",
         "type": "object",
         "required": [
           "created_at",
@@ -11208,8 +11699,9 @@
             "example": "summer-collection"
           },
           "products": {
-            "description": "The Products contained in the Product Collection. Available if the relation `products` is expanded.",
+            "description": "The details of the products that belong to this product collection.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
@@ -11236,13 +11728,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductOption": {
         "title": "Product Option",
-        "description": "Product Options define properties that may vary between different variants of a Product. Common Product Options are \"Size\" and \"Color\", but Medusa doesn't limit what Product Options that can be defined.",
+        "description": "A Product Option defines properties that may vary between different variants of a Product. Common Product Options are \"Size\" and \"Color\". Admins are free to create any product options.",
         "type": "object",
         "required": [
           "created_at",
@@ -11265,19 +11761,21 @@
             "example": "Size"
           },
           "values": {
-            "description": "The Product Option Values that are defined for the Product Option. Available if the relation `values` is expanded.",
+            "description": "The details of the values of the product option.",
             "type": "array",
+            "x-expandable": "values",
             "items": {
               "$ref": "#/components/schemas/ProductOptionValue"
             }
           },
           "product_id": {
-            "description": "The ID of the Product that the Product Option is defined for.",
+            "description": "The ID of the product that this product option belongs to.",
             "type": "string",
             "example": "prod_01G1G5V2MBA328390B5AXJ610F"
           },
           "product": {
-            "description": "A product object. Available if the relation `product` is expanded.",
+            "description": "The details of the product that this product option belongs to.",
+            "x-expandable": "product",
             "nullable": true,
             "$ref": "#/components/schemas/Product"
           },
@@ -11303,13 +11801,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductOptionValue": {
         "title": "Product Option Value",
-        "description": "A value given to a Product Variant's option set. Product Variant have a Product Option Value for each of the Product Options defined on the Product.",
+        "description": "An option value is one of the possible values of a Product Option. Product Variants specify a unique combination of product option values.",
         "type": "object",
         "required": [
           "created_at",
@@ -11328,27 +11830,29 @@
             "example": "optval_01F0YESHR7S6ECD03RF6W12DSJ"
           },
           "value": {
-            "description": "The value that the Product Variant has defined for the specific Product Option (e.g. if the Product Option is \\\"Size\\\" this value could be `Small`, `Medium` or `Large`).",
+            "description": "The value that the Product Variant has defined for the specific Product Option (e.g. if the Product Option is \"Size\" this value could be `Small`, `Medium` or `Large`).",
             "type": "string",
             "example": "large"
           },
           "option_id": {
-            "description": "The ID of the Product Option that the Product Option Value is defined for.",
+            "description": "The ID of the Product Option that the Product Option Value belongs to.",
             "type": "string",
             "example": "opt_01F0YESHQBZVKCEXJ24BS6PCX3"
           },
           "option": {
-            "description": "Available if the relation `option` is expanded.",
+            "description": "The details of the product option that the Product Option Value belongs to.",
+            "x-expandable": "option",
             "nullable": true,
             "$ref": "#/components/schemas/ProductOption"
           },
           "variant_id": {
-            "description": "The ID of the Product Variant that the Product Option Value is defined for.",
+            "description": "The ID of the product variant that uses this product option value.",
             "type": "string",
             "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"
           },
           "variant": {
-            "description": "Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant that uses this product option value.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
@@ -11374,13 +11878,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductTag": {
         "title": "Product Tag",
-        "description": "Product Tags can be added to Products for easy filtering and grouping.",
+        "description": "A Product Tag can be added to Products for easy filtering and grouping.",
         "type": "object",
         "required": [
           "created_at",
@@ -11423,13 +11931,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductTaxRate": {
         "title": "Product Tax Rate",
-        "description": "Associates a tax rate with a product to indicate that the product is taxed in a certain way",
+        "description": "This represents the association between a tax rate and a product to indicate that the product is taxed in a way different than the default.",
         "type": "object",
         "required": [
           "created_at",
@@ -11445,7 +11957,8 @@
             "example": "prod_01G1G5V2MBA328390B5AXJ610F"
           },
           "product": {
-            "description": "Available if the relation `product` is expanded.",
+            "description": "The details of the product.",
+            "x-expandable": "product",
             "nullable": true,
             "$ref": "#/components/schemas/Product"
           },
@@ -11455,7 +11968,8 @@
             "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR"
           },
           "tax_rate": {
-            "description": "Available if the relation `tax_rate` is expanded.",
+            "description": "The details of the tax rate.",
+            "x-expandable": "tax_rate",
             "nullable": true,
             "$ref": "#/components/schemas/TaxRate"
           },
@@ -11475,13 +11989,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductType": {
         "title": "Product Type",
-        "description": "Product Type can be added to Products for filtering and reporting purposes.",
+        "description": "A Product Type can be added to Products for filtering and reporting purposes.",
         "type": "object",
         "required": [
           "created_at",
@@ -11524,13 +12042,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductTypeTaxRate": {
         "title": "Product Type Tax Rate",
-        "description": "Associates a tax rate with a product type to indicate that the product type is taxed in a certain way",
+        "description": "This represents the association between a tax rate and a product type to indicate that the product type is taxed in a different way than the default.",
         "type": "object",
         "required": [
           "created_at",
@@ -11546,7 +12068,8 @@
             "example": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "product_type": {
-            "description": "Available if the relation `product_type` is expanded.",
+            "description": "The details of the product type.",
+            "x-expandable": "product_type",
             "nullable": true,
             "$ref": "#/components/schemas/ProductType"
           },
@@ -11556,7 +12079,8 @@
             "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR"
           },
           "tax_rate": {
-            "description": "Available if the relation `tax_rate` is expanded.",
+            "description": "The details of the tax rate.",
+            "x-expandable": "tax_rate",
             "nullable": true,
             "$ref": "#/components/schemas/TaxRate"
           },
@@ -11576,13 +12100,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ProductVariant": {
         "title": "Product Variant",
-        "description": "Product Variants represent a Product with a specific set of Product Option configurations. The maximum number of Product Variants that a Product can have is given by the number of available Product Option combinations.",
+        "description": "A Product Variant represents a Product with a specific set of Product Option configurations. The maximum number of Product Variants that a Product can have is given by the number of available Product Option combinations. A product must at least have one product variant.",
         "type": "object",
         "required": [
           "allow_backorder",
@@ -11620,18 +12148,20 @@
             "example": "Small"
           },
           "product_id": {
-            "description": "The ID of the Product that the Product Variant belongs to.",
+            "description": "The ID of the product that the product variant belongs to.",
             "type": "string",
             "example": "prod_01G1G5V2MBA328390B5AXJ610F"
           },
           "product": {
-            "description": "A product object. Available if the relation `product` is expanded.",
+            "description": "The details of the product that the product variant belongs to.",
+            "x-expandable": "product",
             "nullable": true,
             "$ref": "#/components/schemas/Product"
           },
           "prices": {
-            "description": "The Money Amounts defined for the Product Variant. Each Money Amount represents a price in a given currency or a price in a specific Region. Available if the relation `prices` is expanded.",
+            "description": "The details of the prices of the Product Variant, each represented as a Money Amount. Each Money Amount represents a price in a given currency or a specific Region.",
             "type": "array",
+            "x-expandable": "prices",
             "items": {
               "$ref": "#/components/schemas/MoneyAmount"
             }
@@ -11730,15 +12260,17 @@
             "example": null
           },
           "options": {
-            "description": "The Product Option Values specified for the Product Variant. Available if the relation `options` is expanded.",
+            "description": "The details of the product options that this product variant defines values for.",
             "type": "array",
+            "x-expandable": "options",
             "items": {
               "$ref": "#/components/schemas/ProductOptionValue"
             }
           },
           "inventory_items": {
-            "description": "The Inventory Items related to the product variant. Available if the relation `inventory_items` is expanded.",
+            "description": "The details inventory items of the product variant.",
             "type": "array",
+            "x-expandable": "inventory_items",
             "items": {
               "$ref": "#/components/schemas/ProductVariantInventoryItem"
             }
@@ -11765,6 +12297,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           },
           "purchasable": {
@@ -11775,7 +12311,7 @@
       },
       "ProductVariantInventoryItem": {
         "title": "Product Variant Inventory Item",
-        "description": "Product Variant Inventory Items link variants with inventory items and denote the number of inventory items constituting a variant.",
+        "description": "A Product Variant Inventory Item links variants with inventory items and denotes the required quantity of the variant.",
         "type": "object",
         "required": [
           "created_at",
@@ -11801,12 +12337,13 @@
             "type": "string"
           },
           "variant": {
-            "description": "A ProductVariant object. Available if the relation `variant` is expanded.",
+            "description": "The details of the product variant.",
+            "x-expandable": "variant",
             "nullable": true,
             "$ref": "#/components/schemas/ProductVariant"
           },
           "required_quantity": {
-            "description": "The quantity of an inventory item required for one quantity of the variant.",
+            "description": "The quantity of an inventory item required for the variant.",
             "type": "integer",
             "default": 1
           },
@@ -11830,7 +12367,7 @@
       },
       "PublishableApiKey": {
         "title": "Publishable API key",
-        "description": "Publishable API key defines scopes (i.e. resources) that are available within a request.",
+        "description": "A Publishable API key defines scopes that resources are available in. Then, it can be used in request to infer the resources without having to directly pass them. For example, a publishable API key can be associated with one or more sales channels. Then, when the publishable API key is passed in the header of a request, it is inferred what sales channel is being used without having to pass the sales channel as a query or body parameter of the request. Publishable API keys can only be used with sales channels, at the moment.",
         "type": "object",
         "required": [
           "created_at",
@@ -11882,8 +12419,8 @@
         }
       },
       "PublishableApiKeySalesChannel": {
-        "title": "Publishable API key sales channel",
-        "description": "Holds mapping between Publishable API keys and Sales Channels",
+        "title": "Publishable API Key Sales Channel",
+        "description": "This represents the association between the Publishable API keys and Sales Channels",
         "type": "object",
         "required": [
           "publishable_key_id",
@@ -11904,7 +12441,7 @@
       },
       "Refund": {
         "title": "Refund",
-        "description": "Refund represent an amount of money transfered back to the Customer for a given reason. Refunds may occur in relation to Returns, Swaps and Claims, but can also be initiated by a store operator.",
+        "description": "A refund represents an amount of money transfered back to the customer for a given reason. Refunds may occur in relation to Returns, Swaps and Claims, but can also be initiated by an admin for an order.",
         "type": "object",
         "required": [
           "amount",
@@ -11925,24 +12462,26 @@
             "example": "ref_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "order_id": {
-            "description": "The id of the Order that the Refund is related to.",
+            "description": "The ID of the order this refund was created for.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order this refund was created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "payment_id": {
-            "description": "The payment's ID if available",
+            "description": "The payment's ID, if available.",
             "nullable": true,
             "type": "string",
             "example": "pay_01G8ZCC5W42ZNY842124G7P5R9"
           },
           "payment": {
-            "description": "Available if the relation `payment` is expanded.",
+            "description": "The details of the payment associated with the refund.",
+            "x-expandable": "payment",
             "nullable": true,
             "$ref": "#/components/schemas/Payment"
           },
@@ -11994,13 +12533,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "Region": {
         "title": "Region",
-        "description": "Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.",
+        "description": "A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.",
         "type": "object",
         "required": [
           "automatic_taxes",
@@ -12028,7 +12571,7 @@
             "example": "EU"
           },
           "currency_code": {
-            "description": "The 3 character currency code that the Region uses.",
+            "description": "The 3 character currency code used in the region.",
             "type": "string",
             "example": "usd",
             "externalDocs": {
@@ -12037,7 +12580,8 @@
             }
           },
           "currency": {
-            "description": "Available if the relation `currency` is expanded.",
+            "description": "The details of the currency used in the region.",
+            "x-expandable": "currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
@@ -12047,8 +12591,9 @@
             "example": 0
           },
           "tax_rates": {
-            "description": "The tax rates that are included in the Region. Available if the relation `tax_rates` is expanded.",
+            "description": "The details of the tax rates used in the region, aside from the default rate.",
             "type": "array",
+            "x-expandable": "tax_rates",
             "items": {
               "$ref": "#/components/schemas/TaxRate"
             }
@@ -12070,8 +12615,9 @@
             "default": true
           },
           "countries": {
-            "description": "The countries that are included in the Region. Available if the relation `countries` is expanded.",
+            "description": "The details of the countries included in this region.",
             "type": "array",
+            "x-expandable": "countries",
             "items": {
               "$ref": "#/components/schemas/Country"
             }
@@ -12083,27 +12629,31 @@
             "example": null
           },
           "tax_provider": {
-            "description": "Available if the relation `tax_provider` is expanded.",
+            "description": "The details of the tax provider used in the region.",
+            "x-expandable": "tax_provider",
             "nullable": true,
             "$ref": "#/components/schemas/TaxProvider"
           },
           "payment_providers": {
-            "description": "The Payment Providers that can be used to process Payments in the Region. Available if the relation `payment_providers` is expanded.",
+            "description": "The details of the payment providers that can be used to process payments in the region.",
             "type": "array",
+            "x-expandable": "payment_providers",
             "items": {
               "$ref": "#/components/schemas/PaymentProvider"
             }
           },
           "fulfillment_providers": {
-            "description": "The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation `fulfillment_providers` is expanded.",
+            "description": "The details of the fulfillment providers that can be used to fulfill items of orders and similar resources in the region.",
             "type": "array",
+            "x-expandable": "fulfillment_providers",
             "items": {
               "$ref": "#/components/schemas/FulfillmentProvider"
             }
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Does the prices for the region include tax",
+            "description": "Whether the prices for the region include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           },
           "created_at": {
@@ -12128,6 +12678,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -12193,7 +12747,7 @@
       },
       "Return": {
         "title": "Return",
-        "description": "Return orders hold information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can be used as part of a Swap.",
+        "description": "A Return holds information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can also be used as part of a Swap or a Claim.",
         "type": "object",
         "required": [
           "claim_order_id",
@@ -12229,47 +12783,52 @@
             "default": "requested"
           },
           "items": {
-            "description": "The Return Items that will be shipped back to the warehouse. Available if the relation `items` is expanded.",
+            "description": "The details of the items that the customer is returning.",
             "type": "array",
+            "x-expandable": "items",
             "items": {
               "$ref": "#/components/schemas/ReturnItem"
             }
           },
           "swap_id": {
-            "description": "The ID of the Swap that the Return is a part of.",
+            "description": "The ID of the swap that the return may belong to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that the return may belong to.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "claim_order_id": {
-            "description": "The ID of the Claim that the Return is a part of.",
+            "description": "The ID of the claim that the return may belong to.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim that the return may belong to.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
           "order_id": {
-            "description": "The ID of the Order that the Return is made from.",
+            "description": "The ID of the order that the return was created for.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the return was created for.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "shipping_method": {
-            "description": "The Shipping Method that will be used to send the Return back. Can be null if the Customer facilitates the return shipment themselves. Available if the relation `shipping_method` is expanded.",
+            "description": "The details of the Shipping Method that will be used to send the Return back. Can be null if the Customer will handle the return shipment themselves.",
+            "x-expandable": "shipping_method",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingMethod"
           },
@@ -12280,7 +12839,7 @@
             "example": {}
           },
           "location_id": {
-            "description": "The id of the stock location the return will be added back.",
+            "description": "The ID of the stock location the return will be added back.",
             "nullable": true,
             "type": "string",
             "example": "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK"
@@ -12327,13 +12886,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ReturnItem": {
         "title": "Return Item",
-        "description": "Correlates a Line Item with a Return, keeping track of the quantity of the Line Item that will be returned.",
+        "description": "A return item represents a line item in an order that is to be returned. It includes details related to the return and the reason behind it.",
         "type": "object",
         "required": [
           "is_requested",
@@ -12348,27 +12911,29 @@
         ],
         "properties": {
           "return_id": {
-            "description": "The id of the Return that the Return Item belongs to.",
+            "description": "The ID of the Return that the Return Item belongs to.",
             "type": "string",
             "example": "ret_01F0YET7XPCMF8RZ0Y151NZV2V"
           },
           "item_id": {
-            "description": "The id of the Line Item that the Return Item references.",
+            "description": "The ID of the Line Item that the Return Item references.",
             "type": "string",
             "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN"
           },
           "return_order": {
-            "description": "Available if the relation `return_order` is expanded.",
+            "description": "Details of the Return that the Return Item belongs to.",
+            "x-expandable": "return_order",
             "nullable": true,
             "$ref": "#/components/schemas/Return"
           },
           "item": {
-            "description": "Available if the relation `item` is expanded.",
+            "description": "The details of the line item in the original order to be returned.",
+            "x-expandable": "item",
             "nullable": true,
             "$ref": "#/components/schemas/LineItem"
           },
           "quantity": {
-            "description": "The quantity of the Line Item that is included in the Return.",
+            "description": "The quantity of the Line Item to be returned.",
             "type": "integer",
             "example": 1
           },
@@ -12396,7 +12961,8 @@
             "example": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ"
           },
           "reason": {
-            "description": "Available if the relation `reason` is expanded.",
+            "description": "The details of the reason for returning the item.",
+            "x-expandable": "reason",
             "nullable": true,
             "$ref": "#/components/schemas/ReturnReason"
           },
@@ -12412,13 +12978,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ReturnReason": {
         "title": "Return Reason",
-        "description": "A Reason for why a given product is returned. A Return Reason can be used on Return Items in order to indicate why a Line Item was returned.",
+        "description": "A Return Reason is a value defined by an admin. It can be used on Return Items in order to indicate why a Line Item was returned.",
         "type": "object",
         "required": [
           "created_at",
@@ -12460,12 +13030,14 @@
             "example": null
           },
           "parent_return_reason": {
-            "description": "Available if the relation `parent_return_reason` is expanded.",
+            "description": "The details of the parent reason.",
+            "x-expandable": "parent_return_reason",
             "nullable": true,
             "$ref": "#/components/schemas/ReturnReason"
           },
           "return_reason_children": {
-            "description": "Available if the relation `return_reason_children` is expanded.",
+            "description": "The details of the child reasons.",
+            "x-expandable": "return_reason_children",
             "$ref": "#/components/schemas/ReturnReason"
           },
           "created_at": {
@@ -12490,13 +13062,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "SalesChannel": {
         "title": "Sales Channel",
-        "description": "A Sales Channel",
+        "description": "A Sales Channel is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.",
         "type": "object",
         "required": [
           "created_at",
@@ -12530,8 +13106,9 @@
             "default": false
           },
           "locations": {
-            "description": "The Stock Locations related to the sales channel. Available if the relation `locations` is expanded.",
+            "description": "The details of the stock locations related to the sales channel.",
             "type": "array",
+            "x-expandable": "locations",
             "items": {
               "$ref": "#/components/schemas/SalesChannelLocation"
             }
@@ -12551,12 +13128,24 @@
             "nullable": true,
             "type": "string",
             "format": "date-time"
+          },
+          "metadata": {
+            "description": "An optional key-value map with additional details",
+            "nullable": true,
+            "type": "object",
+            "example": {
+              "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
       "SalesChannelLocation": {
         "title": "Sales Channel Stock Location",
-        "description": "Sales Channel Stock Location link sales channels with stock locations.",
+        "description": "This represents the association between a sales channel and a stock locations.",
         "type": "object",
         "required": [
           "created_at",
@@ -12573,16 +13162,17 @@
             "example": "scloc_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "sales_channel_id": {
-            "description": "The id of the Sales Channel",
+            "description": "The ID of the Sales Channel",
             "type": "string",
             "example": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A"
           },
           "location_id": {
-            "description": "The id of the Location Stock.",
+            "description": "The ID of the Location Stock.",
             "type": "string"
           },
           "sales_channel": {
-            "description": "The sales channel the location is associated with. Available if the relation `sales_channel` is expanded.",
+            "description": "The details of the sales channel the location is associated with.",
+            "x-expandable": "sales_channel",
             "nullable": true,
             "$ref": "#/components/schemas/SalesChannel"
           },
@@ -12606,7 +13196,7 @@
       },
       "ShippingMethod": {
         "title": "Shipping Method",
-        "description": "Shipping Methods represent a way in which an Order or Return can be shipped. Shipping Methods are built from a Shipping Option, but may contain additional details, that can be necessary for the Fulfillment Provider to handle the shipment.",
+        "description": "A Shipping Method represents a way in which an Order or Return can be shipped. Shipping Methods are created from a Shipping Option, but may contain additional details that can be necessary for the Fulfillment Provider to handle the shipment. If the shipping method is created for a return, it may be associated with a claim or a swap that the return is part of.",
         "type": "object",
         "required": [
           "cart_id",
@@ -12626,73 +13216,80 @@
             "example": "sm_01F0YET7DR2E7CYVSDHM593QG2"
           },
           "shipping_option_id": {
-            "description": "The id of the Shipping Option that the Shipping Method is built from.",
+            "description": "The ID of the Shipping Option that the Shipping Method is built from.",
             "type": "string",
             "example": "so_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "order_id": {
-            "description": "The id of the Order that the Shipping Method is used on.",
+            "description": "The ID of the order that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the shipping method is used in.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "claim_order_id": {
-            "description": "The id of the Claim that the Shipping Method is used on.",
+            "description": "The ID of the claim that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "claim_order": {
-            "description": "A claim order object. Available if the relation `claim_order` is expanded.",
+            "description": "The details of the claim that the shipping method is used in.",
+            "x-expandable": "claim_order",
             "nullable": true,
             "$ref": "#/components/schemas/ClaimOrder"
           },
           "cart_id": {
-            "description": "The id of the Cart that the Shipping Method is used on.",
+            "description": "The ID of the cart that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the shipping method is used in.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
           "swap_id": {
-            "description": "The id of the Swap that the Shipping Method is used on.",
+            "description": "The ID of the swap that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "swap": {
-            "description": "A swap object. Available if the relation `swap` is expanded.",
+            "description": "The details of the swap that the shipping method is used in.",
+            "x-expandable": "swap",
             "nullable": true,
             "$ref": "#/components/schemas/Swap"
           },
           "return_id": {
-            "description": "The id of the Return that the Shipping Method is used on.",
+            "description": "The ID of the return that the shipping method is used in.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "return_order": {
-            "description": "A return object. Available if the relation `return_order` is expanded.",
+            "description": "The details of the return that the shipping method is used in.",
+            "x-expandable": "return_order",
             "nullable": true,
             "$ref": "#/components/schemas/Return"
           },
           "shipping_option": {
-            "description": "Available if the relation `shipping_option` is expanded.",
+            "description": "The details of the shipping option the method was created from.",
+            "x-expandable": "shipping_option",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingOption"
           },
           "tax_lines": {
-            "description": "Available if the relation `tax_lines` is expanded.",
+            "description": "The details of the tax lines applied on the shipping method.",
             "type": "array",
+            "x-expandable": "tax_lines",
             "items": {
               "$ref": "#/components/schemas/ShippingMethodTaxLine"
             }
@@ -12708,8 +13305,9 @@
             "example": {}
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Indicates if the shipping method price include tax",
+            "description": "Whether the shipping method price include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           },
           "subtotal": {
@@ -12731,7 +13329,7 @@
       },
       "ShippingMethodTaxLine": {
         "title": "Shipping Method Tax Line",
-        "description": "Shipping Method Tax Line",
+        "description": "A Shipping Method Tax Line represents the taxes applied on a shipping method in a cart.",
         "type": "object",
         "required": [
           "code",
@@ -12771,7 +13369,8 @@
             "example": "sm_01F0YET7DR2E7CYVSDHM593QG2"
           },
           "shipping_method": {
-            "description": "Available if the relation `shipping_method` is expanded.",
+            "description": "The details of the associated shipping method.",
+            "x-expandable": "shipping_method",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingMethod"
           },
@@ -12791,13 +13390,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ShippingOption": {
         "title": "Shipping Option",
-        "description": "Shipping Options represent a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information.",
+        "description": "A Shipping Option represents a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information.",
         "type": "object",
         "required": [
           "admin_only",
@@ -12827,32 +13430,35 @@
             "example": "PostFake Standard"
           },
           "region_id": {
-            "description": "The region's ID",
+            "description": "The ID of the region this shipping option can be used in.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region this shipping option can be used in.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "profile_id": {
-            "description": "The ID of the Shipping Profile that the shipping option belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.",
+            "description": "The ID of the Shipping Profile that the shipping option belongs to.",
             "type": "string",
             "example": "sp_01G1G5V239ENSZ5MV4JAR737BM"
           },
           "profile": {
-            "description": "Available if the relation `profile` is expanded.",
+            "description": "The details of the shipping profile that the shipping option belongs to.",
+            "x-expandable": "profile",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingProfile"
           },
           "provider_id": {
-            "description": "The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option.",
+            "description": "The ID of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.",
             "type": "string",
             "example": "manual"
           },
           "provider": {
-            "description": "Available if the relation `provider` is expanded.",
+            "description": "The details of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.",
+            "x-expandable": "provider",
             "nullable": true,
             "$ref": "#/components/schemas/FulfillmentProvider"
           },
@@ -12882,8 +13488,9 @@
             "default": false
           },
           "requirements": {
-            "description": "The requirements that must be satisfied for the Shipping Option to be available for a Cart. Available if the relation `requirements` is expanded.",
+            "description": "The details of the requirements that must be satisfied for the Shipping Option to be available for usage in a Cart.",
             "type": "array",
+            "x-expandable": "requirements",
             "items": {
               "$ref": "#/components/schemas/ShippingOptionRequirement"
             }
@@ -12894,8 +13501,9 @@
             "example": {}
           },
           "includes_tax": {
-            "description": "[EXPERIMENTAL] Does the shipping option price include tax",
+            "description": "Whether the shipping option price include tax",
             "type": "boolean",
+            "x-featureFlag": "tax_inclusive_pricing",
             "default": false
           },
           "created_at": {
@@ -12920,13 +13528,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ShippingOptionRequirement": {
         "title": "Shipping Option Requirement",
-        "description": "A requirement that a Cart must satisfy for the Shipping Option to be available to the Cart.",
+        "description": "A shipping option requirement defines conditions that a Cart must satisfy for the Shipping Option to be available for usage in the Cart.",
         "type": "object",
         "required": [
           "amount",
@@ -12942,12 +13554,13 @@
             "example": "sor_01G1G5V29AB4CTNDRFSRWSRKWD"
           },
           "shipping_option_id": {
-            "description": "The id of the Shipping Option that the hipping option requirement belongs to",
+            "description": "The ID of the shipping option that the requirements belong to.",
             "type": "string",
             "example": "so_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "shipping_option": {
-            "description": "Available if the relation `shipping_option` is expanded.",
+            "description": "The details of the shipping option that the requirements belong to.",
+            "x-expandable": "shipping_option",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingOption"
           },
@@ -12975,7 +13588,7 @@
       },
       "ShippingProfile": {
         "title": "Shipping Profile",
-        "description": "Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.",
+        "description": "A Shipping Profile has a set of defined Shipping Options that can be used to fulfill a given set of Products. For example, gift cards are shipped differently than physical products, so a shipping profile with the type `gift_card` groups together the shipping options that can only be used for gift cards.",
         "type": "object",
         "required": [
           "created_at",
@@ -13008,15 +13621,17 @@
             "example": "default"
           },
           "products": {
-            "description": "The Products that the Shipping Profile defines Shipping Options for. Available if the relation `products` is expanded.",
+            "description": "The details of the products that the Shipping Profile defines Shipping Options for. Available if the relation `products` is expanded.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
           },
           "shipping_options": {
-            "description": "The Shipping Options that can be used to fulfill the Products in the Shipping Profile. Available if the relation `shipping_options` is expanded.",
+            "description": "The details of the shipping options that can be used to create shipping methods for the Products in the Shipping Profile.",
             "type": "array",
+            "x-expandable": "shipping_options",
             "items": {
               "$ref": "#/components/schemas/ShippingOption"
             }
@@ -13043,13 +13658,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "ShippingTaxRate": {
         "title": "Shipping Tax Rate",
-        "description": "Associates a tax rate with a shipping option to indicate that the shipping option is taxed in a certain way",
+        "description": "This represents the tax rates applied on a shipping option.",
         "type": "object",
         "required": [
           "created_at",
@@ -13060,22 +13679,24 @@
         ],
         "properties": {
           "shipping_option_id": {
-            "description": "The ID of the Shipping Option",
+            "description": "The ID of the shipping option.",
             "type": "string",
             "example": "so_01G1G5V27GYX4QXNARRQCW1N8T"
           },
           "shipping_option": {
-            "description": "Available if the relation `shipping_option` is expanded.",
+            "description": "The details of the shipping option.",
+            "x-expandable": "shipping_option",
             "nullable": true,
             "$ref": "#/components/schemas/ShippingOption"
           },
           "rate_id": {
-            "description": "The ID of the Tax Rate",
+            "description": "The ID of the associated tax rate.",
             "type": "string",
             "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR"
           },
           "tax_rate": {
-            "description": "Available if the relation `tax_rate` is expanded.",
+            "description": "The details of the associated tax rate.",
+            "x-expandable": "tax_rate",
             "nullable": true,
             "$ref": "#/components/schemas/TaxRate"
           },
@@ -13095,6 +13716,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -13344,7 +13969,7 @@
       },
       "Store": {
         "title": "Store",
-        "description": "Holds settings for the Store, such as name, currencies, etc.",
+        "description": "A store holds the main settings of the commerce shop. By default, only one store is created and used within the Medusa backend. It holds settings related to the name of the store, available currencies, and more.",
         "type": "object",
         "required": [
           "created_at",
@@ -13379,13 +14004,15 @@
             }
           },
           "default_currency": {
-            "description": "Available if the relation `default_currency` is expanded.",
+            "description": "The details of the store's default currency.",
+            "x-expandable": "default_currency",
             "nullable": true,
             "$ref": "#/components/schemas/Currency"
           },
           "currencies": {
-            "description": "The currencies that are enabled for the Store. Available if the relation `currencies` is expanded.",
+            "description": "The details of the enabled currencies in the store.",
             "type": "array",
+            "x-expandable": "currencies",
             "items": {
               "$ref": "#/components/schemas/Currency"
             }
@@ -13415,13 +14042,14 @@
             "example": null
           },
           "default_sales_channel_id": {
-            "description": "The sales channel ID the cart is associated with.",
+            "description": "The ID of the store's default sales channel.",
             "nullable": true,
             "type": "string",
             "example": null
           },
           "default_sales_channel": {
-            "description": "A sales channel object. Available if the relation `default_sales_channel` is expanded.",
+            "description": "The details of the store's default sales channel.",
+            "x-expandable": "default_sales_channel",
             "nullable": true,
             "$ref": "#/components/schemas/SalesChannel"
           },
@@ -13441,6 +14069,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -13460,6 +14092,7 @@
         ],
         "properties": {
           "customer": {
+            "description": "Customer's details.",
             "$ref": "#/components/schemas/Customer"
           }
         }
@@ -13479,6 +14112,7 @@
         "properties": {
           "shipping_options": {
             "type": "array",
+            "description": "An array of shipping options details.",
             "items": {
               "$ref": "#/components/schemas/PricedShippingOption"
             }
@@ -13514,6 +14148,7 @@
             "items",
             "items.variant",
             "items.variant.product",
+            "items.variant.product.profiles",
             "items.tax_lines",
             "items.adjustments",
             "gift_cards",
@@ -13552,6 +14187,7 @@
         ],
         "properties": {
           "cart": {
+            "description": "Cart details.",
             "$ref": "#/components/schemas/Cart"
           }
         }
@@ -13567,6 +14203,7 @@
         "properties": {
           "collections": {
             "type": "array",
+            "description": "An array of product collections details",
             "items": {
               "$ref": "#/components/schemas/ProductCollection"
             }
@@ -13577,7 +14214,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product collections skipped when retrieving the product collections."
           },
           "limit": {
             "type": "integer",
@@ -13592,6 +14229,7 @@
         ],
         "properties": {
           "collection": {
+            "description": "Product collection details.",
             "$ref": "#/components/schemas/ProductCollection"
           }
         }
@@ -13605,7 +14243,7 @@
         "properties": {
           "type": {
             "type": "string",
-            "description": "The type of the data property.",
+            "description": "The type of the data property. If the cart completion fails, type will be `cart` and the data object will be the cart's details. If the cart completion is successful and the cart is used for checkout, type will be `order` and the data object will be the order's details. If the cart completion is successful and the cart is used for swap creation, type will be `swap` and the data object will be the swap's details.",
             "enum": [
               "order",
               "cart",
@@ -13642,7 +14280,7 @@
                 "type": "object",
                 "allOf": [
                   {
-                    "description": "When cart is used for a swap and it has been completed successfully."
+                    "description": "Cart was used for a swap and it has been completed successfully."
                   },
                   {
                     "$ref": "#/components/schemas/Swap"
@@ -13693,6 +14331,7 @@
             "items.tax_lines",
             "items.variant",
             "items.variant.product",
+            "items.variant.product.profiles",
             "refunds",
             "region",
             "shipping_address",
@@ -13750,6 +14389,7 @@
         "properties": {
           "orders": {
             "type": "array",
+            "description": "An array of orders details.",
             "items": {
               "$ref": "#/components/schemas/Order"
             }
@@ -13759,7 +14399,7 @@
             "type": "integer"
           },
           "offset": {
-            "description": "The number of items skipped before these items",
+            "description": "The number of orders skipped when retrieving the orders.",
             "type": "integer"
           },
           "limit": {
@@ -13776,6 +14416,7 @@
         "properties": {
           "payment_methods": {
             "type": "array",
+            "description": "An array of saved payment method details.",
             "items": {
               "type": "object",
               "required": [
@@ -13784,7 +14425,7 @@
               ],
               "properties": {
                 "provider_id": {
-                  "description": "The id of the Payment Provider where the payment method is saved.",
+                  "description": "The ID of the Payment Provider where the payment method is saved.",
                   "type": "string"
                 },
                 "data": {
@@ -13810,6 +14451,7 @@
         ],
         "properties": {
           "customer": {
+            "description": "Customer details.",
             "$ref": "#/components/schemas/Customer"
           }
         }
@@ -13821,6 +14463,7 @@
         ],
         "properties": {
           "customer": {
+            "description": "Customer details.",
             "$ref": "#/components/schemas/Customer"
           }
         }
@@ -13851,6 +14494,7 @@
         ],
         "properties": {
           "product_category": {
+            "description": "Product category details.",
             "$ref": "#/components/schemas/ProductCategory"
           }
         }
@@ -13873,6 +14517,7 @@
         "properties": {
           "product_categories": {
             "type": "array",
+            "description": "An array of product categories details.",
             "items": {
               "$ref": "#/components/schemas/ProductCategory"
             }
@@ -13883,7 +14528,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product categories skipped when retrieving the product categories."
           },
           "limit": {
             "type": "integer",
@@ -13898,6 +14543,7 @@
         ],
         "properties": {
           "gift_card": {
+            "description": "Gift card details.",
             "$ref": "#/components/schemas/GiftCard"
           }
         }
@@ -13948,6 +14594,7 @@
         ],
         "properties": {
           "order_edit": {
+            "description": "Order edit details.",
             "$ref": "#/components/schemas/OrderEdit"
           }
         }
@@ -13995,6 +14642,7 @@
             "items.tax_lines",
             "items.variant",
             "items.variant.product",
+            "items.variant.product.profiles",
             "refunds",
             "region",
             "shipping_methods",
@@ -14044,6 +14692,7 @@
         },
         "properties": {
           "order": {
+            "description": "Order details.",
             "$ref": "#/components/schemas/Order"
           }
         }
@@ -14078,6 +14727,7 @@
         ],
         "properties": {
           "payment_collection": {
+            "description": "Payment collection's details.",
             "$ref": "#/components/schemas/PaymentCollection"
           }
         }
@@ -14089,6 +14739,7 @@
         ],
         "properties": {
           "payment_session": {
+            "description": "Payment session's details.",
             "$ref": "#/components/schemas/PaymentSession"
           }
         }
@@ -14115,22 +14766,22 @@
         "properties": {
           "region_id": {
             "type": "string",
-            "description": "The ID of the Region to create the Cart in."
+            "description": "The ID of the Region to create the Cart in. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency. If this parameter is not provided, the first region in the store is used by default."
           },
           "sales_channel_id": {
             "type": "string",
-            "description": "[EXPERIMENTAL] The ID of the Sales channel to create the Cart in."
+            "description": "The ID of the Sales channel to create the Cart in. The cart's sales channel affects which products can be added to the cart. If a product does not exist in the cart's sales channel, it cannot be added to the cart. If you add a publishable API key in the header of this request and specify a sales channel ID, the specified sales channel must be within the scope of the publishable API key's resources. If you add a publishable API key in the header of this request, you don't specify a sales channel ID, and the publishable API key is associated with one sales channel, that sales channel will be attached to the cart. If no sales channel is passed and no publishable API key header is passed or the publishable API key isn't associated with any sales channel, the cart will not be associated with any sales channel."
           },
           "country_code": {
             "type": "string",
-            "description": "The 2 character ISO country code to create the Cart in.",
+            "description": "The 2 character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address.",
             "externalDocs": {
               "url": "https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements",
               "description": "See a list of codes."
             }
           },
           "items": {
-            "description": "An optional array of `variant_id`, `quantity` pairs to generate Line Items from.",
+            "description": "An array of product variants to generate line items from.",
             "type": "array",
             "items": {
               "type": "object",
@@ -14140,18 +14791,18 @@
               ],
               "properties": {
                 "variant_id": {
-                  "description": "The id of the Product Variant to generate a Line Item from.",
+                  "description": "The ID of the Product Variant.",
                   "type": "string"
                 },
                 "quantity": {
-                  "description": "The quantity of the Product Variant to add",
+                  "description": "The quantity to add into the cart.",
                   "type": "integer"
                 }
               }
             }
           },
           "context": {
-            "description": "An optional object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`",
+            "description": "An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`",
             "type": "object",
             "example": {
               "ip": "::1",
@@ -14168,11 +14819,15 @@
         "properties": {
           "quantity": {
             "type": "number",
-            "description": "The quantity to set the Line Item to."
+            "description": "The quantity of the line item in the cart."
           },
           "metadata": {
             "type": "object",
-            "description": "An optional key-value map with additional details about the Line Item. If omitted, the metadata will remain unchanged.\""
+            "description": "An optional key-value map with additional details about the Line Item. If omitted, the metadata will remain unchanged.\"",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -14193,7 +14848,11 @@
           },
           "metadata": {
             "type": "object",
-            "description": "An optional key-value map with additional details about the Line Item."
+            "description": "An optional key-value map with additional details about the Line Item.",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -14226,11 +14885,11 @@
         "properties": {
           "region_id": {
             "type": "string",
-            "description": "The id of the Region to create the Cart in."
+            "description": "The ID of the Region to create the Cart in. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency."
           },
           "country_code": {
             "type": "string",
-            "description": "The 2 character ISO country code to create the Cart in.",
+            "description": "The 2 character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address.",
             "externalDocs": {
               "url": "https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements",
               "description": "See a list of codes."
@@ -14243,7 +14902,7 @@
           },
           "sales_channel_id": {
             "type": "string",
-            "description": "The ID of the Sales channel to update the Cart with."
+            "description": "The ID of the Sales channel to create the Cart in. The cart's sales channel affects which products can be added to the cart. If a product does not exist in the cart's sales channel, it cannot be added to the cart. If you add a publishable API key in the header of this request and specify a sales channel ID, the specified sales channel must be within the scope of the publishable API key's resources."
           },
           "billing_address": {
             "description": "The Address to be used for billing purposes.",
@@ -14259,7 +14918,7 @@
             ]
           },
           "shipping_address": {
-            "description": "The Address to be used for shipping.",
+            "description": "The Address to be used for shipping purposes.",
             "anyOf": [
               {
                 "$ref": "#/components/schemas/AddressPayload",
@@ -14281,7 +14940,7 @@
               ],
               "properties": {
                 "code": {
-                  "description": "The code that a Gift Card is identified by.",
+                  "description": "The code of a gift card.",
                   "type": "string"
                 }
               }
@@ -14297,7 +14956,7 @@
               ],
               "properties": {
                 "code": {
-                  "description": "The code that a Discount is identified by.",
+                  "description": "The code of the discount.",
                   "type": "string"
                 }
               }
@@ -14308,7 +14967,7 @@
             "type": "string"
           },
           "context": {
-            "description": "An optional object to provide context to the Cart.",
+            "description": "An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`",
             "type": "object",
             "example": {
               "ip": "::1",
@@ -14325,11 +14984,11 @@
         "properties": {
           "option_id": {
             "type": "string",
-            "description": "ID of the shipping option to create the method from"
+            "description": "ID of the shipping option to create the method from."
           },
           "data": {
             "type": "object",
-            "description": "Used to hold any data that the shipping method may need to process the fulfillment of the order. Look at the documentation for your installed fulfillment providers to find out what to send."
+            "description": "Used to hold any data that the shipping method may need to process the fulfillment of the order. This depends on the fulfillment provider you're using."
           }
         }
       },
@@ -14340,7 +14999,7 @@
         ],
         "properties": {
           "token": {
-            "description": "The invite token provided by the admin.",
+            "description": "The claim token generated by previous request to the Claim Order endpoint.",
             "type": "string"
           }
         }
@@ -14359,7 +15018,7 @@
         ],
         "properties": {
           "address": {
-            "description": "The Address to add to the Customer.",
+            "description": "The Address to add to the Customer's saved addresses.",
             "$ref": "#/components/schemas/AddressCreatePayload"
           }
         }
@@ -14371,7 +15030,7 @@
         ],
         "properties": {
           "order_ids": {
-            "description": "The ids of the orders to claim",
+            "description": "The ID of the orders to claim",
             "type": "array",
             "items": {
               "type": "string"
@@ -14386,7 +15045,7 @@
         ],
         "properties": {
           "email": {
-            "description": "The email of the customer.",
+            "description": "The customer's email.",
             "type": "string",
             "format": "email"
           }
@@ -14396,15 +15055,15 @@
         "type": "object",
         "properties": {
           "first_name": {
-            "description": "The Customer's first name.",
+            "description": "The customer's first name.",
             "type": "string"
           },
           "last_name": {
-            "description": "The Customer's last name.",
+            "description": "The customer's last name.",
             "type": "string"
           },
           "billing_address": {
-            "description": "The Address to be used for billing purposes.",
+            "description": "The address to be used for billing purposes.",
             "anyOf": [
               {
                 "$ref": "#/components/schemas/AddressPayload",
@@ -14417,20 +15076,24 @@
             ]
           },
           "password": {
-            "description": "The Customer's password.",
+            "description": "The customer's password.",
             "type": "string"
           },
           "phone": {
-            "description": "The Customer's phone number.",
+            "description": "The customer's phone number.",
             "type": "string"
           },
           "email": {
-            "description": "The email of the customer.",
+            "description": "The customer's email.",
             "type": "string"
           },
           "metadata": {
-            "description": "Metadata about the customer.",
-            "type": "object"
+            "description": "Additional custom data about the customer.",
+            "type": "object",
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+            }
           }
         }
       },
@@ -14444,25 +15107,25 @@
         ],
         "properties": {
           "first_name": {
-            "description": "The Customer's first name.",
+            "description": "The customer's first name.",
             "type": "string"
           },
           "last_name": {
-            "description": "The Customer's last name.",
+            "description": "The customer's last name.",
             "type": "string"
           },
           "email": {
-            "description": "The email of the customer.",
+            "description": "The customer's email.",
             "type": "string",
             "format": "email"
           },
           "password": {
-            "description": "The Customer's password.",
+            "description": "The customer's password.",
             "type": "string",
             "format": "password"
           },
           "phone": {
-            "description": "The Customer's phone number.",
+            "description": "The customer's phone number.",
             "type": "string"
           }
         }
@@ -14476,12 +15139,12 @@
         ],
         "properties": {
           "email": {
-            "description": "The email of the customer.",
+            "description": "The customer's email.",
             "type": "string",
             "format": "email"
           },
           "password": {
-            "description": "The Customer's password.",
+            "description": "The customer's password.",
             "type": "string",
             "format": "password"
           },
@@ -14496,7 +15159,7 @@
         "properties": {
           "declined_reason": {
             "type": "string",
-            "description": "The reason for declining the OrderEdit."
+            "description": "The reason for declining the Order Edit."
           }
         }
       },
@@ -14522,7 +15185,7 @@
         ],
         "properties": {
           "sessions": {
-            "description": "An array of payment sessions related to the Payment Collection. If the session_id is not provided, existing sessions not present will be deleted and the provided ones will be created.",
+            "description": "An array of payment sessions related to the Payment Collection. Existing sessions that are not added in this array will be deleted.",
             "type": "array",
             "items": {
               "type": "object",
@@ -14537,11 +15200,11 @@
                 },
                 "amount": {
                   "type": "integer",
-                  "description": "The amount ."
+                  "description": "The payment amount"
                 },
                 "session_id": {
                   "type": "string",
-                  "description": "The ID of the Payment Session to be updated."
+                  "description": "The ID of the Payment Session to be updated. If no ID is provided, a new payment session is created."
                 }
               }
             }
@@ -14557,10 +15220,10 @@
         "properties": {
           "order_id": {
             "type": "string",
-            "description": "The ID of the Order to create the Return from."
+            "description": "The ID of the Order to create the return for."
           },
           "items": {
-            "description": "The items to include in the Return.",
+            "description": "The items to include in the return.",
             "type": "array",
             "items": {
               "type": "object",
@@ -14570,7 +15233,7 @@
               ],
               "properties": {
                 "item_id": {
-                  "description": "The ID of the Line Item from the Order.",
+                  "description": "The ID of the line item to return.",
                   "type": "string"
                 },
                 "quantity": {
@@ -14578,7 +15241,7 @@
                   "type": "integer"
                 },
                 "reason_id": {
-                  "description": "The ID of the return reason.",
+                  "description": "The ID of the return reason. Return reasons can be retrieved from the List Return Reasons endpoint.",
                   "type": "string"
                 },
                 "note": {
@@ -14589,7 +15252,7 @@
             }
           },
           "return_shipping": {
-            "description": "If the Return is to be handled by the store operator the Customer can choose a Return Shipping Method. Alternatvely the Customer can handle the Return themselves.",
+            "description": "The return shipping method used to return the items. If provided, a fulfillment is automatically created for the return.",
             "type": "object",
             "required": [
               "option_id"
@@ -14608,18 +15271,18 @@
         "properties": {
           "q": {
             "type": "string",
-            "description": "The query to run the search with."
+            "description": "The search query."
           },
           "offset": {
             "type": "number",
-            "description": "How many products to skip in the result."
+            "description": "The number of products to skip when retrieving the products."
           },
           "limit": {
             "type": "number",
             "description": "Limit the number of products returned."
           },
           "filter": {
-            "description": "Filter based on the search engine."
+            "description": "Pass filters based on the search service."
           }
         }
       },
@@ -14632,7 +15295,7 @@
             ],
             "properties": {
               "hits": {
-                "description": "Array of results. The format of the items depends on the search engine installed on the server.",
+                "description": "Array of search results. The format of the items depends on the search engine installed on the Medusa backend.",
                 "type": "array"
               }
             }
@@ -14665,15 +15328,15 @@
               ],
               "properties": {
                 "item_id": {
-                  "description": "The ID of the Line Item from the Order.",
+                  "description": "The ID of the order's line item to return.",
                   "type": "string"
                 },
                 "quantity": {
-                  "description": "The quantity to swap.",
+                  "description": "The quantity to return.",
                   "type": "integer"
                 },
                 "reason_id": {
-                  "description": "The ID of the reason of this return.",
+                  "description": "The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons endpoint.",
                   "type": "string"
                 },
                 "note": {
@@ -14688,7 +15351,7 @@
             "description": "The ID of the Shipping Option to create the Shipping Method from."
           },
           "additional_items": {
-            "description": "The items to exchange the returned items to.",
+            "description": "The items to exchange the returned items with.",
             "type": "array",
             "items": {
               "type": "object",
@@ -14698,11 +15361,11 @@
               ],
               "properties": {
                 "variant_id": {
-                  "description": "The ID of the Product Variant to send.",
+                  "description": "The ID of the Product Variant.",
                   "type": "string"
                 },
                 "quantity": {
-                  "description": "The quantity to send of the variant.",
+                  "description": "The quantity of the variant.",
                   "type": "integer"
                 }
               }
@@ -14721,6 +15384,7 @@
         "properties": {
           "product_tags": {
             "type": "array",
+            "description": "An array of product tags details.",
             "items": {
               "$ref": "#/components/schemas/ProductTag"
             }
@@ -14731,7 +15395,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product tags skipped when retrieving the product tags."
           },
           "limit": {
             "type": "integer",
@@ -14750,6 +15414,7 @@
         "properties": {
           "product_types": {
             "type": "array",
+            "description": "An array of product types details.",
             "items": {
               "$ref": "#/components/schemas/ProductType"
             }
@@ -14760,7 +15425,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of product types skipped when retrieving the product types."
           },
           "limit": {
             "type": "integer",
@@ -14796,6 +15461,7 @@
         "properties": {
           "products": {
             "type": "array",
+            "description": "An array of products details.",
             "items": {
               "$ref": "#/components/schemas/PricedProduct"
             }
@@ -14806,7 +15472,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of products skipped when retrieving the products."
           },
           "limit": {
             "type": "integer",
@@ -14838,6 +15504,7 @@
         ],
         "properties": {
           "product": {
+            "description": "Product details.",
             "$ref": "#/components/schemas/PricedProduct"
           }
         }
@@ -14862,6 +15529,7 @@
         "properties": {
           "regions": {
             "type": "array",
+            "description": "An array of regions details.",
             "items": {
               "$ref": "#/components/schemas/Region"
             }
@@ -14872,7 +15540,7 @@
           },
           "offset": {
             "type": "integer",
-            "description": "The number of items skipped before these items"
+            "description": "The number of regions skipped when retrieving the regions."
           },
           "limit": {
             "type": "integer",
@@ -14899,6 +15567,7 @@
         ],
         "properties": {
           "region": {
+            "description": "Region details.",
             "$ref": "#/components/schemas/Region"
           }
         }
@@ -14918,6 +15587,7 @@
         "properties": {
           "return_reasons": {
             "type": "array",
+            "description": "An array of return reasons details.",
             "items": {
               "$ref": "#/components/schemas/ReturnReason"
             }
@@ -14938,6 +15608,7 @@
         ],
         "properties": {
           "return_reason": {
+            "description": "Return reason details.",
             "$ref": "#/components/schemas/ReturnReason"
           }
         }
@@ -14959,6 +15630,7 @@
         ],
         "properties": {
           "return": {
+            "description": "Return details.",
             "$ref": "#/components/schemas/Return"
           }
         }
@@ -14977,6 +15649,7 @@
         "properties": {
           "shipping_options": {
             "type": "array",
+            "description": "An array of shipping options details.",
             "items": {
               "$ref": "#/components/schemas/PricedShippingOption"
             }
@@ -15008,6 +15681,7 @@
         ],
         "properties": {
           "swap": {
+            "description": "Swap details.",
             "$ref": "#/components/schemas/Swap"
           }
         }
@@ -15031,6 +15705,7 @@
         "properties": {
           "variants": {
             "type": "array",
+            "description": "An array of product variant descriptions.",
             "items": {
               "$ref": "#/components/schemas/PricedVariant"
             }
@@ -15055,13 +15730,14 @@
         ],
         "properties": {
           "variant": {
+            "description": "Product variant description.",
             "$ref": "#/components/schemas/PricedVariant"
           }
         }
       },
       "Swap": {
         "title": "Swap",
-        "description": "Swaps can be created when a Customer wishes to exchange Products that they have purchased to different Products. Swaps consist of a Return of previously purchased Products and a Fulfillment of new Products, the amount paid for the Products being returned will be used towards payment for the new Products. In the case where the amount paid for the the Products being returned exceed the amount to be paid for the new Products, a Refund will be issued for the difference.",
+        "description": "A swap can be created when a Customer wishes to exchange Products that they have purchased with different Products. It consists of a Return of previously purchased Products and a Fulfillment of new Products. It also includes information on any additional payment or refund required based on the difference between the exchanged products.",
         "type": "object",
         "required": [
           "allow_backorder",
@@ -15117,41 +15793,46 @@
             "example": "not_paid"
           },
           "order_id": {
-            "description": "The ID of the Order where the Line Items to be returned where purchased.",
+            "description": "The ID of the order that the swap belongs to.",
             "type": "string",
             "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK"
           },
           "order": {
-            "description": "An order object. Available if the relation `order` is expanded.",
+            "description": "The details of the order that the swap belongs to.",
+            "x-expandable": "order",
             "nullable": true,
             "$ref": "#/components/schemas/Order"
           },
           "additional_items": {
-            "description": "The new Line Items to ship to the Customer. Available if the relation `additional_items` is expanded.",
+            "description": "The details of the new products to send to the customer, represented as line items.",
             "type": "array",
+            "x-expandable": "additional_items",
             "items": {
               "$ref": "#/components/schemas/LineItem"
             }
           },
           "return_order": {
-            "description": "A return order object. The Return that is issued for the return part of the Swap. Available if the relation `return_order` is expanded.",
+            "description": "The details of the return that belongs to the swap, which holds the details on the items being returned.",
+            "x-expandable": "return_order",
             "nullable": true,
             "$ref": "#/components/schemas/Return"
           },
           "fulfillments": {
-            "description": "The Fulfillments used to send the new Line Items. Available if the relation `fulfillments` is expanded.",
+            "description": "The details of the fulfillments that are used to send the new items to the customer.",
+            "x-expandable": "fulfillments",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/Fulfillment"
             }
           },
           "payment": {
-            "description": "The Payment authorized when the Swap requires an additional amount to be charged from the Customer. Available if the relation `payment` is expanded.",
+            "description": "The details of the additional payment authorized by the customer when `difference_due` is positive.",
+            "x-expandable": "payment",
             "nullable": true,
             "$ref": "#/components/schemas/Payment"
           },
           "difference_due": {
-            "description": "The difference that is paid or refunded as a result of the Swap. May be negative when the amount paid for the returned items exceed the total of the new Products.",
+            "description": "The difference amount between the order’s original total and the new total imposed by the swap. If its value is negative, a refund must be issues to the customer. If it's positive, additional payment must be authorized by the customer. Otherwise, no payment processing is required.",
             "nullable": true,
             "type": "integer",
             "example": 0
@@ -15163,25 +15844,28 @@
             "example": "addr_01G8ZH853YPY9B94857DY91YGW"
           },
           "shipping_address": {
-            "description": "Available if the relation `shipping_address` is expanded.",
+            "description": "The details of the shipping address that the new items should be sent to.",
+            "x-expandable": "shipping_address",
             "nullable": true,
             "$ref": "#/components/schemas/Address"
           },
           "shipping_methods": {
-            "description": "The Shipping Methods used to fulfill the additional items purchased. Available if the relation `shipping_methods` is expanded.",
+            "description": "The details of the shipping methods used to fulfill the additional items purchased.",
             "type": "array",
+            "x-expandable": "shipping_methods",
             "items": {
               "$ref": "#/components/schemas/ShippingMethod"
             }
           },
           "cart_id": {
-            "description": "The id of the Cart that the Customer will use to confirm the Swap.",
+            "description": "The ID of the cart that the customer uses to complete the swap.",
             "nullable": true,
             "type": "string",
             "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63"
           },
           "cart": {
-            "description": "A cart object. Available if the relation `cart` is expanded.",
+            "description": "The details of the cart that the customer uses to complete the swap.",
+            "x-expandable": "cart",
             "nullable": true,
             "$ref": "#/components/schemas/Cart"
           },
@@ -15239,13 +15923,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "TaxLine": {
         "title": "Tax Line",
-        "description": "Line item that specifies an amount of tax to add to a line item.",
+        "description": "A tax line represents the taxes amount applied to a line item.",
         "type": "object",
         "required": [
           "code",
@@ -15294,13 +15982,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "TaxProvider": {
         "title": "Tax Provider",
-        "description": "The tax service used to calculate taxes",
+        "description": "A tax provider represents a tax service installed in the Medusa backend, either through a plugin or backend customizations. It holds the tax service's installation status.",
         "type": "object",
         "required": [
           "id",
@@ -15308,12 +16000,12 @@
         ],
         "properties": {
           "id": {
-            "description": "The id of the tax provider as given by the plugin.",
+            "description": "The ID of the tax provider as given by the tax service.",
             "type": "string",
             "example": "manual"
           },
           "is_installed": {
-            "description": "Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`.",
+            "description": "Whether the tax service is installed in the current version. If a tax service is no longer installed, the `is_installed` attribute is set to `false`.",
             "type": "boolean",
             "default": true
           }
@@ -15321,7 +16013,7 @@
       },
       "TaxRate": {
         "title": "Tax Rate",
-        "description": "A Tax Rate can be used to associate a certain rate to charge on products within a given Region",
+        "description": "A Tax Rate can be used to define a custom rate to charge on specified products, product types, and shipping options within a given region.",
         "type": "object",
         "required": [
           "code",
@@ -15357,32 +16049,36 @@
             "example": "Tax Example"
           },
           "region_id": {
-            "description": "The id of the Region that the rate belongs to",
+            "description": "The ID of the region that the rate belongs to.",
             "type": "string",
             "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"
           },
           "region": {
-            "description": "A region object. Available if the relation `region` is expanded.",
+            "description": "The details of the region that the rate belongs to.",
+            "x-expandable": "region",
             "nullable": true,
             "$ref": "#/components/schemas/Region"
           },
           "products": {
-            "description": "The products that belong to this tax rate. Available if the relation `products` is expanded.",
+            "description": "The details of the products that belong to this tax rate.",
             "type": "array",
+            "x-expandable": "products",
             "items": {
               "$ref": "#/components/schemas/Product"
             }
           },
           "product_types": {
-            "description": "The product types that belong to this tax rate. Available if the relation `product_types` is expanded.",
+            "description": "The details of the product types that belong to this tax rate.",
             "type": "array",
+            "x-expandable": "product_types",
             "items": {
               "$ref": "#/components/schemas/ProductType"
             }
           },
           "shipping_options": {
+            "description": "The details of the shipping options that belong to this tax rate.",
             "type": "array",
-            "description": "The shipping options that belong to this tax rate. Available if the relation `shipping_options` is expanded.",
+            "x-expandable": "shipping_options",
             "items": {
               "$ref": "#/components/schemas/ShippingOption"
             }
@@ -15418,13 +16114,17 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
       },
       "TrackingLink": {
         "title": "Tracking Link",
-        "description": "Tracking Link holds information about tracking numbers for a Fulfillment. Tracking Links can optionally contain a URL that can be visited to see the status of the shipment.",
+        "description": "A tracking link holds information about tracking numbers for a Fulfillment. Tracking Links can optionally contain a URL that can be visited to see the status of the shipment. Typically, the tracking link is provided from the third-party service integrated through the used fulfillment provider.",
         "type": "object",
         "required": [
           "created_at",
@@ -15455,12 +16155,13 @@
             "format": "RH370168054CN"
           },
           "fulfillment_id": {
-            "description": "The id of the Fulfillment that the Tracking Link references.",
+            "description": "The ID of the fulfillment that the tracking link belongs to.",
             "type": "string",
             "example": "ful_01G8ZRTMQCA76TXNAT81KPJZRF"
           },
           "fulfillment": {
-            "description": "Available if the relation `fulfillment` is expanded.",
+            "description": "The details of the fulfillment that the tracking link belongs to.",
+            "x-expandable": "fulfillment",
             "nullable": true,
             "$ref": "#/components/schemas/Fulfillment"
           },
@@ -15495,6 +16196,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
@@ -15534,7 +16239,7 @@
       },
       "User": {
         "title": "User",
-        "description": "Represents a User who can manage store settings.",
+        "description": "A User is an administrator who can manage store settings and data.",
         "type": "object",
         "required": [
           "api_token",
@@ -15555,7 +16260,7 @@
             "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"
           },
           "role": {
-            "description": "The user's role",
+            "description": "The user's role. These roles don't provide any different privileges.",
             "type": "string",
             "enum": [
               "admin",
@@ -15609,6 +16314,10 @@
             "type": "object",
             "example": {
               "car": "white"
+            },
+            "externalDocs": {
+              "description": "Learn about the metadata attribute, and how to delete and update it.",
+              "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
             }
           }
         }
diff --git a/docs/api/store/code_samples/JavaScript/store_auth/post.js b/docs/api/store/code_samples/JavaScript/store_auth/post.js
index fe1dd9d1d0..2ca0af88ac 100644
--- a/docs/api/store/code_samples/JavaScript/store_auth/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_auth/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.auth.authenticate({
-  email: 'user@example.com',
-  password: 'user@example.com'
+  email: "user@example.com",
+  password: "user@example.com"
 })
 .then(({ customer }) => {
   console.log(customer.id);
diff --git a/docs/api/store/code_samples/JavaScript/store_auth_{email}/get.js b/docs/api/store/code_samples/JavaScript/store_auth_{email}/get.js
index 7a47fb4b7d..a28a5ae8a0 100644
--- a/docs/api/store/code_samples/JavaScript/store_auth_{email}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_auth_{email}/get.js
@@ -1,3 +1,3 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.auth.exists('user@example.com')
+medusa.auth.exists("user@example.com")
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}/get.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}/get.js
index 3f5adbd0ee..139cbed7f7 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.retrieve(cart_id)
+medusa.carts.retrieve(cartId)
 .then(({ cart }) => {
   console.log(cart.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}/post.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}/post.js
index ae0a9ac7ce..9884d7fa2c 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.update(cart_id, {
-  email: 'user@example.com'
+medusa.carts.update(cartId, {
+  email: "user@example.com"
 })
 .then(({ cart }) => {
   console.log(cart.id);
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_complete/post.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_complete/post.js
index c6d5cef0bc..5b48e36b7e 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_complete/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_complete/post.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.complete(cart_id)
+medusa.carts.complete(cartId)
 .then(({ cart }) => {
   console.log(cart.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_discounts_{code}/delete.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_discounts_{code}/delete.js
index d75cb36b38..f007cd25ee 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_discounts_{code}/delete.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_discounts_{code}/delete.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.deleteDiscount(cart_id, code)
+medusa.carts.deleteDiscount(cartId, code)
 .then(({ cart }) => {
   console.log(cart.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_line-items_{line_id}/delete.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_line-items_{line_id}/delete.js
index 239701d366..4facbcb7e4 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_line-items_{line_id}/delete.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_line-items_{line_id}/delete.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.lineItems.delete(cart_id, line_id)
+medusa.carts.lineItems.delete(cartId, lineId)
 .then(({ cart }) => {
   console.log(cart.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_line-items_{line_id}/post.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_line-items_{line_id}/post.js
index aa81978a10..ea73b56540 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_line-items_{line_id}/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_line-items_{line_id}/post.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.lineItems.update(cart_id, line_id, {
+medusa.carts.lineItems.update(cartId, lineId, {
   quantity: 1
 })
 .then(({ cart }) => {
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-session/post.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-session/post.js
index 107071e321..51080a095f 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-session/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-session/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.setPaymentSession(cart_id, {
-  provider_id: 'manual'
+medusa.carts.setPaymentSession(cartId, {
+  provider_id: "manual"
 })
 .then(({ cart }) => {
   console.log(cart.id);
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions/post.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions/post.js
index e762a5d1d6..1fd399dc05 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions/post.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.createPaymentSessions(cart_id)
+medusa.carts.createPaymentSessions(cartId)
 .then(({ cart }) => {
   console.log(cart.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}/delete.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}/delete.js
index fe32566f08..3051206af2 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}/delete.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}/delete.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.deletePaymentSession(cart_id, 'manual')
+medusa.carts.deletePaymentSession(cartId, "manual")
 .then(({ cart }) => {
   console.log(cart.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}/post.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}/post.js
index fbb0e0a564..71ad429b17 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}/post.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.updatePaymentSession(cart_id, 'manual', {
+medusa.carts.updatePaymentSession(cartId, "manual", {
   data: {
 
   }
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}_refresh/post.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}_refresh/post.js
index e106394882..7724a62f85 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}_refresh/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_payment-sessions_{provider_id}_refresh/post.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.refreshPaymentSession(cart_id, 'manual')
+medusa.carts.refreshPaymentSession(cartId, "manual")
 .then(({ cart }) => {
   console.log(cart.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_carts_{id}_shipping-methods/post.js b/docs/api/store/code_samples/JavaScript/store_carts_{id}_shipping-methods/post.js
index 92be47414d..f79b14bf7a 100644
--- a/docs/api/store/code_samples/JavaScript/store_carts_{id}_shipping-methods/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_carts_{id}_shipping-methods/post.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.carts.addShippingMethod(cart_id, {
+medusa.carts.addShippingMethod(cartId, {
   option_id
 })
 .then(({ cart }) => {
diff --git a/docs/api/store/code_samples/JavaScript/store_collections_{id}/get.js b/docs/api/store/code_samples/JavaScript/store_collections_{id}/get.js
index c57b33a1e7..3eacf7cb2f 100644
--- a/docs/api/store/code_samples/JavaScript/store_collections_{id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_collections_{id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.collections.retrieve(collection_id)
+medusa.collections.retrieve(collectionId)
 .then(({ collection }) => {
   console.log(collection.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_customers/post.js b/docs/api/store/code_samples/JavaScript/store_customers/post.js
index cdf5ba83bc..36ac0280c8 100644
--- a/docs/api/store/code_samples/JavaScript/store_customers/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_customers/post.js
@@ -1,10 +1,10 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.customers.create({
-  first_name: 'Alec',
-  last_name: 'Reynolds',
-  email: 'user@example.com',
-  password: 'supersecret'
+  first_name: "Alec",
+  last_name: "Reynolds",
+  email: "user@example.com",
+  password: "supersecret"
 })
 .then(({ customer }) => {
   console.log(customer.id);
diff --git a/docs/api/store/code_samples/JavaScript/store_customers_me/post.js b/docs/api/store/code_samples/JavaScript/store_customers_me/post.js
index c37ca4d74c..5008f75361 100644
--- a/docs/api/store/code_samples/JavaScript/store_customers_me/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_customers_me/post.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged
 medusa.customers.update({
-  first_name: 'Laury'
+  first_name: "Laury"
 })
 .then(({ customer }) => {
   console.log(customer.id);
diff --git a/docs/api/store/code_samples/JavaScript/store_customers_me_addresses/post.js b/docs/api/store/code_samples/JavaScript/store_customers_me_addresses/post.js
index 3a3d7d0f19..5663839ac2 100644
--- a/docs/api/store/code_samples/JavaScript/store_customers_me_addresses/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_customers_me_addresses/post.js
@@ -3,17 +3,15 @@ const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged
 medusa.customers.addresses.addAddress({
   address: {
-    first_name: 'Celia',
-    last_name: 'Schumm',
-    address_1: '225 Bednar Curve',
-    city: 'Danielville',
-    country_code: 'US',
-    postal_code: '85137',
-    phone: '981-596-6748 x90188',
-    company: 'Wyman LLC',
-    address_2: '',
-    province: 'Georgia',
-    metadata: {}
+    first_name: "Celia",
+    last_name: "Schumm",
+    address_1: "225 Bednar Curve",
+    city: "Danielville",
+    country_code: "US",
+    postal_code: "85137",
+    phone: "981-596-6748 x90188",
+    company: "Wyman LLC",
+    province: "Georgia",
   }
 })
 .then(({ customer }) => {
diff --git a/docs/api/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/delete.js b/docs/api/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/delete.js
index 2b722339b5..733b07ba54 100644
--- a/docs/api/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/delete.js
+++ b/docs/api/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/delete.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged
-medusa.customers.addresses.deleteAddress(address_id)
+medusa.customers.addresses.deleteAddress(addressId)
 .then(({ customer }) => {
   console.log(customer.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/post.js b/docs/api/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/post.js
index 1ebe44d14d..838712aee1 100644
--- a/docs/api/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_customers_me_addresses_{address_id}/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged
-medusa.customers.addresses.updateAddress(address_id, {
-  first_name: 'Gina'
+medusa.customers.addresses.updateAddress(addressId, {
+  first_name: "Gina"
 })
 .then(({ customer }) => {
   console.log(customer.id);
diff --git a/docs/api/store/code_samples/JavaScript/store_customers_password-reset/post.js b/docs/api/store/code_samples/JavaScript/store_customers_password-reset/post.js
index 2367e38c9b..62118381a1 100644
--- a/docs/api/store/code_samples/JavaScript/store_customers_password-reset/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_customers_password-reset/post.js
@@ -1,9 +1,9 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.customers.resetPassword({
-  email: 'user@example.com',
-  password: 'supersecret',
-  token: 'supersecrettoken'
+  email: "user@example.com",
+  password: "supersecret",
+  token: "supersecrettoken"
 })
 .then(({ customer }) => {
   console.log(customer.id);
diff --git a/docs/api/store/code_samples/JavaScript/store_customers_password-token/post.js b/docs/api/store/code_samples/JavaScript/store_customers_password-token/post.js
index 3273ee4fb0..57d7adff0d 100644
--- a/docs/api/store/code_samples/JavaScript/store_customers_password-token/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_customers_password-token/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.customers.generatePasswordToken({
-  email: 'user@example.com'
+  email: "user@example.com"
 })
 .then(() => {
   // successful
diff --git a/docs/api/store/code_samples/JavaScript/store_order-edits_{id}/get.js b/docs/api/store/code_samples/JavaScript/store_order-edits_{id}/get.js
index 08e3f53272..c87462c010 100644
--- a/docs/api/store/code_samples/JavaScript/store_order-edits_{id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_order-edits_{id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.orderEdits.retrieve(order_edit_id)
+medusa.orderEdits.retrieve(orderEditId)
 .then(({ order_edit }) => {
   console.log(order_edit.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_order-edits_{id}_complete/post.js b/docs/api/store/code_samples/JavaScript/store_order-edits_{id}_complete/post.js
index f1e6affb37..e675dc9bf0 100644
--- a/docs/api/store/code_samples/JavaScript/store_order-edits_{id}_complete/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_order-edits_{id}_complete/post.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.orderEdits.complete(order_edit_id)
+medusa.orderEdits.complete(orderEditId)
   .then(({ order_edit }) => {
     console.log(order_edit.id)
   })
diff --git a/docs/api/store/code_samples/JavaScript/store_order-edits_{id}_decline/post.js b/docs/api/store/code_samples/JavaScript/store_order-edits_{id}_decline/post.js
index d5d9c6c5d4..982a69fa63 100644
--- a/docs/api/store/code_samples/JavaScript/store_order-edits_{id}_decline/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_order-edits_{id}_decline/post.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.orderEdits.decline(order_edit_id)
+medusa.orderEdits.decline(orderEditId)
   .then(({ order_edit }) => {
     console.log(order_edit.id);
   })
diff --git a/docs/api/store/code_samples/JavaScript/store_orders/get.js b/docs/api/store/code_samples/JavaScript/store_orders/get.js
index 4eb5ea5d67..752d402f6a 100644
--- a/docs/api/store/code_samples/JavaScript/store_orders/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_orders/get.js
@@ -2,7 +2,7 @@ import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.orders.lookupOrder({
   display_id: 1,
-  email: 'user@example.com'
+  email: "user@example.com"
 })
 .then(({ order }) => {
   console.log(order.id);
diff --git a/docs/api/store/code_samples/JavaScript/store_orders_batch_customer_token/post.js b/docs/api/store/code_samples/JavaScript/store_orders_batch_customer_token/post.js
index 72554acc41..3e6f7f187a 100644
--- a/docs/api/store/code_samples/JavaScript/store_orders_batch_customer_token/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_orders_batch_customer_token/post.js
@@ -1,8 +1,8 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.orders.claimOrders({
-  display_ids,
+medusa.orders.requestCustomerOrders({
+  order_ids,
 })
 .then(() => {
   // successful
diff --git a/docs/api/store/code_samples/JavaScript/store_orders_cart_{cart_id}/get.js b/docs/api/store/code_samples/JavaScript/store_orders_cart_{cart_id}/get.js
index 2318153197..2b3a951751 100644
--- a/docs/api/store/code_samples/JavaScript/store_orders_cart_{cart_id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_orders_cart_{cart_id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.orders.retrieveByCartId(cart_id)
+medusa.orders.retrieveByCartId(cartId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_orders_{id}/get.js b/docs/api/store/code_samples/JavaScript/store_orders_{id}/get.js
index 4698ecf018..9d6d19410a 100644
--- a/docs/api/store/code_samples/JavaScript/store_orders_{id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_orders_{id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.orders.retrieve(order_id)
+medusa.orders.retrieve(orderId)
 .then(({ order }) => {
   console.log(order.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions/post.js b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions/post.js
index 59e3022db9..1c3b157a61 100644
--- a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions/post.js
@@ -1,10 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-
-// Total amount = 10000
-
-// Adding a payment session
 medusa.paymentCollections.managePaymentSession(payment_id, { provider_id: "stripe" })
 .then(({ payment_collection }) => {
   console.log(payment_collection.id);
diff --git a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_batch/post.js b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_batch/post.js
index 6a87deeeee..4a653c973e 100644
--- a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_batch/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_batch/post.js
@@ -4,29 +4,33 @@ const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 
 // Total amount = 10000
 
-// Adding two new sessions
-medusa.paymentCollections.managePaymentSessionsBatch(payment_id, [
-  {
-    provider_id: "stripe",
-    amount: 5000,
-  },
-  {
-    provider_id: "manual",
-    amount: 5000,
-  },
-])
+// Example 1: Adding two new sessions
+medusa.paymentCollections.managePaymentSessionsBatch(paymentId, {
+  sessions: [
+    {
+      provider_id: "stripe",
+      amount: 5000,
+    },
+    {
+      provider_id: "manual",
+      amount: 5000,
+    },
+  ]
+})
 .then(({ payment_collection }) => {
   console.log(payment_collection.id);
 });
 
-// Updating one session and removing the other
-medusa.paymentCollections.managePaymentSessionsBatch(payment_id, [
-  {
-    provider_id: "stripe",
-    amount: 10000,
-    session_id: "ps_123456"
-  },
-])
+// Example 2: Updating one session and removing the other
+medusa.paymentCollections.managePaymentSessionsBatch(paymentId, {
+  sessions: [
+    {
+      provider_id: "stripe",
+      amount: 10000,
+      session_id: "ps_123456"
+    },
+  ]
+})
 .then(({ payment_collection }) => {
   console.log(payment_collection.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_batch_authorize/post.js b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_batch_authorize/post.js
index 07a13c56a9..3de81243e0 100644
--- a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_batch_authorize/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_batch_authorize/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.paymentCollections.authorize(payment_id)
+medusa.paymentCollections.authorize(paymentId)
 .then(({ payment_collection }) => {
   console.log(payment_collection.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_{session_id}/post.js b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_{session_id}/post.js
index 8dfeeb183e..88bffc5121 100644
--- a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_{session_id}/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_{session_id}/post.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.paymentCollections.refreshPaymentSession(payment_collection_id, session_id)
+medusa.paymentCollections.refreshPaymentSession(paymentCollectionId, sessionId)
 .then(({ payment_session }) => {
   console.log(payment_session.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_{session_id}_authorize/post.js b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_{session_id}_authorize/post.js
index 6ded159b96..64de9d34fb 100644
--- a/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_{session_id}_authorize/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_payment-collections_{id}_sessions_{session_id}_authorize/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.paymentCollections.authorize(payment_id, session_id)
+medusa.paymentCollections.authorize(paymentId, sessionId)
 .then(({ payment_collection }) => {
   console.log(payment_collection.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_product-categories_{id}/get.js b/docs/api/store/code_samples/JavaScript/store_product-categories_{id}/get.js
index 62b8663838..c2ed536dfe 100644
--- a/docs/api/store/code_samples/JavaScript/store_product-categories_{id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_product-categories_{id}/get.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 // must be previously logged in or use api token
-medusa.productCategories.retrieve(product_category_id)
+medusa.productCategories.retrieve(productCategoryId)
   .then(({ product_category }) => {
     console.log(product_category.id);
   });
diff --git a/docs/api/store/code_samples/JavaScript/store_products_search/post.js b/docs/api/store/code_samples/JavaScript/store_products_search/post.js
index 74c0fcefbf..4b261f2535 100644
--- a/docs/api/store/code_samples/JavaScript/store_products_search/post.js
+++ b/docs/api/store/code_samples/JavaScript/store_products_search/post.js
@@ -1,7 +1,7 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
 medusa.products.search({
-  q: 'Shirt'
+  q: "Shirt"
 })
 .then(({ hits }) => {
   console.log(hits.length);
diff --git a/docs/api/store/code_samples/JavaScript/store_products_{id}/get.js b/docs/api/store/code_samples/JavaScript/store_products_{id}/get.js
index cae2281bb8..bf85f9521c 100644
--- a/docs/api/store/code_samples/JavaScript/store_products_{id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_products_{id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.products.retrieve(product_id)
+medusa.products.retrieve(productId)
 .then(({ product }) => {
   console.log(product.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_regions_{id}/get.js b/docs/api/store/code_samples/JavaScript/store_regions_{id}/get.js
index 9a54ea3f82..699aa67088 100644
--- a/docs/api/store/code_samples/JavaScript/store_regions_{id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_regions_{id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.regions.retrieve(region_id)
+medusa.regions.retrieve(regionId)
 .then(({ region }) => {
   console.log(region.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_return-reasons_{id}/get.js b/docs/api/store/code_samples/JavaScript/store_return-reasons_{id}/get.js
index a1f180d6e0..123e755c02 100644
--- a/docs/api/store/code_samples/JavaScript/store_return-reasons_{id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_return-reasons_{id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.returnReasons.retrieve(reason_id)
+medusa.returnReasons.retrieve(reasonId)
 .then(({ return_reason }) => {
   console.log(return_reason.id);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_shipping-options_{cart_id}/get.js b/docs/api/store/code_samples/JavaScript/store_shipping-options_{cart_id}/get.js
index f9c335af6a..dbb08d94ef 100644
--- a/docs/api/store/code_samples/JavaScript/store_shipping-options_{cart_id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_shipping-options_{cart_id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.shippingOptions.listCartOptions(cart_id)
+medusa.shippingOptions.listCartOptions(cartId)
 .then(({ shipping_options }) => {
   console.log(shipping_options.length);
 });
diff --git a/docs/api/store/code_samples/JavaScript/store_swaps_{cart_id}/get.js b/docs/api/store/code_samples/JavaScript/store_swaps_{cart_id}/get.js
index f01c35da41..e0eec5b76c 100644
--- a/docs/api/store/code_samples/JavaScript/store_swaps_{cart_id}/get.js
+++ b/docs/api/store/code_samples/JavaScript/store_swaps_{cart_id}/get.js
@@ -1,6 +1,6 @@
 import Medusa from "@medusajs/medusa-js"
 const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-medusa.swaps.retrieveByCartId(cart_id)
+medusa.swaps.retrieveByCartId(cartId)
 .then(({ swap }) => {
   console.log(swap.id);
 });
diff --git a/docs/api/store/code_samples/Shell/store_auth/delete.sh b/docs/api/store/code_samples/Shell/store_auth/delete.sh
index 57af41ea72..10c49c31a5 100644
--- a/docs/api/store/code_samples/Shell/store_auth/delete.sh
+++ b/docs/api/store/code_samples/Shell/store_auth/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/store/auth' \
---header 'Cookie: connect.sid={sid}'
+curl -X DELETE 'https://medusa-url.com/store/auth' \
+-H 'Cookie: connect.sid={sid}'
diff --git a/docs/api/store/code_samples/Shell/store_auth/get.sh b/docs/api/store/code_samples/Shell/store_auth/get.sh
index 4b522129cb..7f7eeee60c 100644
--- a/docs/api/store/code_samples/Shell/store_auth/get.sh
+++ b/docs/api/store/code_samples/Shell/store_auth/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/store/auth' \
---header 'Cookie: connect.sid={sid}'
+curl 'https://medusa-url.com/store/auth' \
+-H 'Cookie: connect.sid={sid}'
diff --git a/docs/api/store/code_samples/Shell/store_auth/post.sh b/docs/api/store/code_samples/Shell/store_auth/post.sh
index f35d447286..dcb555d1a8 100644
--- a/docs/api/store/code_samples/Shell/store_auth/post.sh
+++ b/docs/api/store/code_samples/Shell/store_auth/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/auth' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/auth' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com",
     "password": "supersecret"
diff --git a/docs/api/store/code_samples/Shell/store_auth_{email}/get.sh b/docs/api/store/code_samples/Shell/store_auth_{email}/get.sh
index 091d9550bf..d9213490a5 100644
--- a/docs/api/store/code_samples/Shell/store_auth_{email}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_auth_{email}/get.sh
@@ -1,2 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/auth/user@example.com' \
---header 'Cookie: connect.sid={sid}'
+curl 'https://medusa-url.com/store/auth/user@example.com'
diff --git a/docs/api/store/code_samples/Shell/store_carts/post.sh b/docs/api/store/code_samples/Shell/store_carts/post.sh
index a3099b3313..dddb7a7ca0 100644
--- a/docs/api/store/code_samples/Shell/store_carts/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/carts'
+curl -X POST 'https://medusa-url.com/store/carts'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}/get.sh b/docs/api/store/code_samples/Shell/store_carts_{id}/get.sh
index 76955da49d..f5cf5bf5c2 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/carts/{id}'
+curl 'https://medusa-url.com/store/carts/{id}'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}/post.sh
index 0ac6b61b04..831ace5072 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/carts/{id}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com"
 }'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_complete/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_complete/post.sh
index 9f219793bc..1fc4faaef1 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_complete/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_complete/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}/complete'
+curl -X POST 'https://medusa-url.com/store/carts/{id}/complete'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_discounts_{code}/delete.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_discounts_{code}/delete.sh
index 66c40764e9..67b84be261 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_discounts_{code}/delete.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_discounts_{code}/delete.sh
@@ -1 +1 @@
-curl --location --request DELETE 'https://medusa-url.com/store/carts/{id}/discounts/{code}'
+curl -X DELETE 'https://medusa-url.com/store/carts/{id}/discounts/{code}'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_line-items/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_line-items/post.sh
index b2501c8d06..9a1843b5e6 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_line-items/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_line-items/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}/line-items' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/carts/{id}/line-items' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "variant_id": "{variant_id}",
     "quantity": 1
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_line-items_{line_id}/delete.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_line-items_{line_id}/delete.sh
index ab5e4a252b..305f16dd86 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_line-items_{line_id}/delete.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_line-items_{line_id}/delete.sh
@@ -1 +1 @@
-curl --location --request DELETE 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}'
+curl -X DELETE 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_line-items_{line_id}/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_line-items_{line_id}/post.sh
index ec45835403..7900039623 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_line-items_{line_id}/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_line-items_{line_id}/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "quantity": 1
 }'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-session/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-session/post.sh
index 298a4d5134..8e975e74f3 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-session/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-session/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}/payment-sessions' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "provider_id": "manual"
 }'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions/post.sh
index db8d6448a4..30998c869d 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}/payment-sessions'
+curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}/delete.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}/delete.sh
index 103cc5206d..4c03fbcf23 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}/delete.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}/delete.sh
@@ -1 +1 @@
-curl --location --request DELETE 'https://medusa-url.com/store/carts/{id}/payment-sessions/manual'
+curl -X DELETE 'https://medusa-url.com/store/carts/{id}/payment-sessions/{provider_id}'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}/post.sh
index 87714529b5..ef2d8b5042 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/manual' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/manual' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "data": {}
 }'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}_refresh/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}_refresh/post.sh
index b8c4233e82..6cf4a5092d 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}_refresh/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_payment-sessions_{provider_id}_refresh/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/manual/refresh'
+curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/{provider_id}/refresh'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_shipping-methods/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_shipping-methods/post.sh
index cc15f640df..8d04c22301 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_shipping-methods/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_shipping-methods/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}/shipping-methods' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/carts/{id}/shipping-methods' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "option_id": "{option_id}",
 }'
diff --git a/docs/api/store/code_samples/Shell/store_carts_{id}_taxes/post.sh b/docs/api/store/code_samples/Shell/store_carts_{id}_taxes/post.sh
index 75e50772f7..fa5252d0db 100644
--- a/docs/api/store/code_samples/Shell/store_carts_{id}_taxes/post.sh
+++ b/docs/api/store/code_samples/Shell/store_carts_{id}_taxes/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/carts/{id}/taxes'
+curl -X POST 'https://medusa-url.com/store/carts/{id}/taxes'
diff --git a/docs/api/store/code_samples/Shell/store_collections/get.sh b/docs/api/store/code_samples/Shell/store_collections/get.sh
index ad7979b616..06072a3592 100644
--- a/docs/api/store/code_samples/Shell/store_collections/get.sh
+++ b/docs/api/store/code_samples/Shell/store_collections/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/collections'
+curl 'https://medusa-url.com/store/collections'
diff --git a/docs/api/store/code_samples/Shell/store_collections_{id}/get.sh b/docs/api/store/code_samples/Shell/store_collections_{id}/get.sh
index 3b322d611f..9d23c77c3f 100644
--- a/docs/api/store/code_samples/Shell/store_collections_{id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_collections_{id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/collections/{id}'
+curl 'https://medusa-url.com/store/collections/{id}'
diff --git a/docs/api/store/code_samples/Shell/store_customers/post.sh b/docs/api/store/code_samples/Shell/store_customers/post.sh
index e38ed51c09..14b8cee284 100644
--- a/docs/api/store/code_samples/Shell/store_customers/post.sh
+++ b/docs/api/store/code_samples/Shell/store_customers/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/customers' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/customers' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "first_name": "Alec",
     "last_name": "Reynolds",
diff --git a/docs/api/store/code_samples/Shell/store_customers_me/get.sh b/docs/api/store/code_samples/Shell/store_customers_me/get.sh
index 5c7447f1f4..a2118e4e70 100644
--- a/docs/api/store/code_samples/Shell/store_customers_me/get.sh
+++ b/docs/api/store/code_samples/Shell/store_customers_me/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/store/customers/me' \
---header 'Cookie: connect.sid={sid}'
+curl 'https://medusa-url.com/store/customers/me' \
+-H 'Cookie: connect.sid={sid}'
diff --git a/docs/api/store/code_samples/Shell/store_customers_me/post.sh b/docs/api/store/code_samples/Shell/store_customers_me/post.sh
index 7fee8f1d18..22e6636525 100644
--- a/docs/api/store/code_samples/Shell/store_customers_me/post.sh
+++ b/docs/api/store/code_samples/Shell/store_customers_me/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/store/customers/me' \
---header 'Cookie: connect.sid={sid}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/customers/me' \
+-H 'Cookie: connect.sid={sid}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "first_name": "Laury"
 }'
diff --git a/docs/api/store/code_samples/Shell/store_customers_me_addresses/post.sh b/docs/api/store/code_samples/Shell/store_customers_me_addresses/post.sh
index b09ba84e2c..3c93a418e5 100644
--- a/docs/api/store/code_samples/Shell/store_customers_me_addresses/post.sh
+++ b/docs/api/store/code_samples/Shell/store_customers_me_addresses/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/store/customers/me/addresses' \
---header 'Cookie: connect.sid={sid}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/customers/me/addresses' \
+-H 'Cookie: connect.sid={sid}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "address": {
       "first_name": "Celia",
diff --git a/docs/api/store/code_samples/Shell/store_customers_me_addresses_{address_id}/delete.sh b/docs/api/store/code_samples/Shell/store_customers_me_addresses_{address_id}/delete.sh
index e0248069d7..388364755a 100644
--- a/docs/api/store/code_samples/Shell/store_customers_me_addresses_{address_id}/delete.sh
+++ b/docs/api/store/code_samples/Shell/store_customers_me_addresses_{address_id}/delete.sh
@@ -1,2 +1,2 @@
-curl --location --request DELETE 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \
---header 'Cookie: connect.sid={sid}'
+curl -X DELETE 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \
+-H 'Cookie: connect.sid={sid}'
diff --git a/docs/api/store/code_samples/Shell/store_customers_me_addresses_{address_id}/post.sh b/docs/api/store/code_samples/Shell/store_customers_me_addresses_{address_id}/post.sh
index 4e9a361fe5..cad6de4d31 100644
--- a/docs/api/store/code_samples/Shell/store_customers_me_addresses_{address_id}/post.sh
+++ b/docs/api/store/code_samples/Shell/store_customers_me_addresses_{address_id}/post.sh
@@ -1,6 +1,6 @@
-curl --location --request POST 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \
---header 'Cookie: connect.sid={sid}' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \
+-H 'Cookie: connect.sid={sid}' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "first_name": "Gina"
 }'
diff --git a/docs/api/store/code_samples/Shell/store_customers_me_orders/get.sh b/docs/api/store/code_samples/Shell/store_customers_me_orders/get.sh
index 86bc5700cd..cf1057398c 100644
--- a/docs/api/store/code_samples/Shell/store_customers_me_orders/get.sh
+++ b/docs/api/store/code_samples/Shell/store_customers_me_orders/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/store/customers/me/orders' \
---header 'Cookie: connect.sid={sid}'
+curl 'https://medusa-url.com/store/customers/me/orders' \
+-H 'Cookie: connect.sid={sid}'
diff --git a/docs/api/store/code_samples/Shell/store_customers_me_payment-methods/get.sh b/docs/api/store/code_samples/Shell/store_customers_me_payment-methods/get.sh
index d3b31353b5..edca1ff1f1 100644
--- a/docs/api/store/code_samples/Shell/store_customers_me_payment-methods/get.sh
+++ b/docs/api/store/code_samples/Shell/store_customers_me_payment-methods/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/store/customers/me/payment-methods' \
---header 'Cookie: connect.sid={sid}'
+curl 'https://medusa-url.com/store/customers/me/payment-methods' \
+-H 'Cookie: connect.sid={sid}'
diff --git a/docs/api/store/code_samples/Shell/store_customers_password-reset/post.sh b/docs/api/store/code_samples/Shell/store_customers_password-reset/post.sh
index 7c283ab21c..cf20bd9cbf 100644
--- a/docs/api/store/code_samples/Shell/store_customers_password-reset/post.sh
+++ b/docs/api/store/code_samples/Shell/store_customers_password-reset/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/customers/password-reset' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/customers/password-reset' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com",
     "password": "supersecret",
diff --git a/docs/api/store/code_samples/Shell/store_customers_password-token/post.sh b/docs/api/store/code_samples/Shell/store_customers_password-token/post.sh
index 1d363fa361..9fea525a84 100644
--- a/docs/api/store/code_samples/Shell/store_customers_password-token/post.sh
+++ b/docs/api/store/code_samples/Shell/store_customers_password-token/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/customers/password-token' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/customers/password-token' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "email": "user@example.com"
 }'
diff --git a/docs/api/store/code_samples/Shell/store_gift-cards_{code}/get.sh b/docs/api/store/code_samples/Shell/store_gift-cards_{code}/get.sh
index 2332d07e61..a075489c53 100644
--- a/docs/api/store/code_samples/Shell/store_gift-cards_{code}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_gift-cards_{code}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/gift-cards/{code}'
+curl 'https://medusa-url.com/store/gift-cards/{code}'
diff --git a/docs/api/store/code_samples/Shell/store_order-edits_{id}/get.sh b/docs/api/store/code_samples/Shell/store_order-edits_{id}/get.sh
index 10abf0b797..4cef3603a0 100644
--- a/docs/api/store/code_samples/Shell/store_order-edits_{id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_order-edits_{id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/order-edits/{id}'
+curl 'https://medusa-url.com/store/order-edits/{id}'
diff --git a/docs/api/store/code_samples/Shell/store_order-edits_{id}_complete/post.sh b/docs/api/store/code_samples/Shell/store_order-edits_{id}_complete/post.sh
index 4fbcea1656..048f277f9d 100644
--- a/docs/api/store/code_samples/Shell/store_order-edits_{id}_complete/post.sh
+++ b/docs/api/store/code_samples/Shell/store_order-edits_{id}_complete/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/order-edits/{id}/complete'
+curl -X POST 'https://medusa-url.com/store/order-edits/{id}/complete'
diff --git a/docs/api/store/code_samples/Shell/store_order-edits_{id}_decline/post.sh b/docs/api/store/code_samples/Shell/store_order-edits_{id}_decline/post.sh
index 3fdbfd7094..69f698ea41 100644
--- a/docs/api/store/code_samples/Shell/store_order-edits_{id}_decline/post.sh
+++ b/docs/api/store/code_samples/Shell/store_order-edits_{id}_decline/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/order-edits/{id}/decline'
+curl -X POST 'https://medusa-url.com/store/order-edits/{id}/decline'
diff --git a/docs/api/store/code_samples/Shell/store_orders/get.sh b/docs/api/store/code_samples/Shell/store_orders/get.sh
index 983b8c826d..a3edb25dbd 100644
--- a/docs/api/store/code_samples/Shell/store_orders/get.sh
+++ b/docs/api/store/code_samples/Shell/store_orders/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/orders?display_id=1&email=user@example.com'
+curl 'https://medusa-url.com/store/orders?display_id=1&email=user@example.com'
diff --git a/docs/api/store/code_samples/Shell/store_orders_batch_customer_token/post.sh b/docs/api/store/code_samples/Shell/store_orders_batch_customer_token/post.sh
index 21521c3ef5..a68e46625f 100644
--- a/docs/api/store/code_samples/Shell/store_orders_batch_customer_token/post.sh
+++ b/docs/api/store/code_samples/Shell/store_orders_batch_customer_token/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/batch/customer/token' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/batch/customer/token' \
+-H 'Content-Type: application/json' \
 --data-raw '{
-    "display_ids": ["id"],
+    "order_ids": ["id"],
 }'
diff --git a/docs/api/store/code_samples/Shell/store_orders_cart_{cart_id}/get.sh b/docs/api/store/code_samples/Shell/store_orders_cart_{cart_id}/get.sh
index 94c6dea6c0..c1f66b05bc 100644
--- a/docs/api/store/code_samples/Shell/store_orders_cart_{cart_id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_orders_cart_{cart_id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/orders/cart/{id}'
+curl 'https://medusa-url.com/store/orders/cart/{cart_id}'
diff --git a/docs/api/store/code_samples/Shell/store_orders_customer_confirm/post.sh b/docs/api/store/code_samples/Shell/store_orders_customer_confirm/post.sh
index 2439ee98c3..24fdd0a6af 100644
--- a/docs/api/store/code_samples/Shell/store_orders_customer_confirm/post.sh
+++ b/docs/api/store/code_samples/Shell/store_orders_customer_confirm/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/orders/customer/confirm' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/orders/customer/confirm' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "token": "{token}",
 }'
diff --git a/docs/api/store/code_samples/Shell/store_orders_{id}/get.sh b/docs/api/store/code_samples/Shell/store_orders_{id}/get.sh
index 2010e19cf3..bdfd27145d 100644
--- a/docs/api/store/code_samples/Shell/store_orders_{id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_orders_{id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/orders/{id}'
+curl 'https://medusa-url.com/store/orders/{id}'
diff --git a/docs/api/store/code_samples/Shell/store_payment-collections_{id}/get.sh b/docs/api/store/code_samples/Shell/store_payment-collections_{id}/get.sh
index 8901cffbad..55a380fb66 100644
--- a/docs/api/store/code_samples/Shell/store_payment-collections_{id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_payment-collections_{id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/payment-collections/{id}'
+curl 'https://medusa-url.com/store/payment-collections/{id}'
diff --git a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions/post.sh b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions/post.sh
index 1d15f4300e..2124f83f5d 100644
--- a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions/post.sh
+++ b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions/post.sh
@@ -1 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions'
+curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "provider_id": "stripe"
+}'
diff --git a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_batch/post.sh b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_batch/post.sh
index 4c5bcbc44b..11806b629b 100644
--- a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_batch/post.sh
+++ b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_batch/post.sh
@@ -1 +1,14 @@
-curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch'
+curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "sessions": [
+    {
+      "provider_id": "stripe",
+      "amount": 5000
+    },
+    {
+      "provider_id": "manual",
+      "amount": 5000
+    }
+  ]
+}'
diff --git a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_batch_authorize/post.sh b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_batch_authorize/post.sh
index 33206c8c19..9390e15611 100644
--- a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_batch_authorize/post.sh
+++ b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_batch_authorize/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch/authorize'
+curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch/authorize'
diff --git a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_{session_id}/post.sh b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_{session_id}/post.sh
index c307160781..9403e557d2 100644
--- a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_{session_id}/post.sh
+++ b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_{session_id}/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}'
+curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}'
diff --git a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_{session_id}_authorize/post.sh b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_{session_id}_authorize/post.sh
index ece1417b0c..2974f91ba2 100644
--- a/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_{session_id}_authorize/post.sh
+++ b/docs/api/store/code_samples/Shell/store_payment-collections_{id}_sessions_{session_id}_authorize/post.sh
@@ -1 +1 @@
-curl --location --request POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}/authorize'
+curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}/authorize'
diff --git a/docs/api/store/code_samples/Shell/store_product-categories/get.sh b/docs/api/store/code_samples/Shell/store_product-categories/get.sh
index 73332a22f3..2514d361e6 100644
--- a/docs/api/store/code_samples/Shell/store_product-categories/get.sh
+++ b/docs/api/store/code_samples/Shell/store_product-categories/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/store/product-categories' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/store/product-categories' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/store/code_samples/Shell/store_product-categories_{id}/get.sh b/docs/api/store/code_samples/Shell/store_product-categories_{id}/get.sh
index 2df11a1fa6..5bfbb4ffc7 100644
--- a/docs/api/store/code_samples/Shell/store_product-categories_{id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_product-categories_{id}/get.sh
@@ -1,2 +1,2 @@
-curl --location --request GET 'https://medusa-url.com/store/product-categories/{id}' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/store/product-categories/{id}' \
+-H 'Authorization: Bearer {api_token}'
diff --git a/docs/api/store/code_samples/Shell/store_product-tags/get.sh b/docs/api/store/code_samples/Shell/store_product-tags/get.sh
index 7013d00968..607bbe670e 100644
--- a/docs/api/store/code_samples/Shell/store_product-tags/get.sh
+++ b/docs/api/store/code_samples/Shell/store_product-tags/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/product-tags'
+curl 'https://medusa-url.com/store/product-tags'
diff --git a/docs/api/store/code_samples/Shell/store_product-types/get.sh b/docs/api/store/code_samples/Shell/store_product-types/get.sh
index 8b3ab56826..67123f373c 100644
--- a/docs/api/store/code_samples/Shell/store_product-types/get.sh
+++ b/docs/api/store/code_samples/Shell/store_product-types/get.sh
@@ -1,2 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/product-types' \
---header 'Authorization: Bearer {api_token}'
+curl 'https://medusa-url.com/store/product-types'
diff --git a/docs/api/store/code_samples/Shell/store_products/get.sh b/docs/api/store/code_samples/Shell/store_products/get.sh
index f2caa5c410..b384b4ea5e 100644
--- a/docs/api/store/code_samples/Shell/store_products/get.sh
+++ b/docs/api/store/code_samples/Shell/store_products/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/products'
+curl 'https://medusa-url.com/store/products'
diff --git a/docs/api/store/code_samples/Shell/store_products_search/post.sh b/docs/api/store/code_samples/Shell/store_products_search/post.sh
index 5bb73b0210..462b6e0d06 100644
--- a/docs/api/store/code_samples/Shell/store_products_search/post.sh
+++ b/docs/api/store/code_samples/Shell/store_products_search/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/products/search' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/products/search' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "q": "Shirt"
 }'
diff --git a/docs/api/store/code_samples/Shell/store_products_{id}/get.sh b/docs/api/store/code_samples/Shell/store_products_{id}/get.sh
index 01e92bf292..f376534100 100644
--- a/docs/api/store/code_samples/Shell/store_products_{id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_products_{id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/products/{id}'
+curl 'https://medusa-url.com/store/products/{id}'
diff --git a/docs/api/store/code_samples/Shell/store_regions/get.sh b/docs/api/store/code_samples/Shell/store_regions/get.sh
index d768567fa2..b799165f7e 100644
--- a/docs/api/store/code_samples/Shell/store_regions/get.sh
+++ b/docs/api/store/code_samples/Shell/store_regions/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/regions'
+curl 'https://medusa-url.com/store/regions'
diff --git a/docs/api/store/code_samples/Shell/store_regions_{id}/get.sh b/docs/api/store/code_samples/Shell/store_regions_{id}/get.sh
index deb4970f93..92fba8edd4 100644
--- a/docs/api/store/code_samples/Shell/store_regions_{id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_regions_{id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/regions/{id}'
+curl 'https://medusa-url.com/store/regions/{id}'
diff --git a/docs/api/store/code_samples/Shell/store_return-reasons/get.sh b/docs/api/store/code_samples/Shell/store_return-reasons/get.sh
index 64d05b4425..80bdf342c1 100644
--- a/docs/api/store/code_samples/Shell/store_return-reasons/get.sh
+++ b/docs/api/store/code_samples/Shell/store_return-reasons/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/return-reasons'
+curl 'https://medusa-url.com/store/return-reasons'
diff --git a/docs/api/store/code_samples/Shell/store_return-reasons_{id}/get.sh b/docs/api/store/code_samples/Shell/store_return-reasons_{id}/get.sh
index 5a9d698343..8cca1060ec 100644
--- a/docs/api/store/code_samples/Shell/store_return-reasons_{id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_return-reasons_{id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/return-reasons/{id}'
+curl 'https://medusa-url.com/store/return-reasons/{id}'
diff --git a/docs/api/store/code_samples/Shell/store_returns/post.sh b/docs/api/store/code_samples/Shell/store_returns/post.sh
index f34ac1925b..c9f43d8ace 100644
--- a/docs/api/store/code_samples/Shell/store_returns/post.sh
+++ b/docs/api/store/code_samples/Shell/store_returns/post.sh
@@ -1,5 +1,5 @@
-curl --location --request POST 'https://medusa-url.com/store/returns' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/returns' \
+-H 'Content-Type: application/json' \
 --data-raw '{
     "order_id": "asfasf",
     "items": [
diff --git a/docs/api/store/code_samples/Shell/store_shipping-options/get.sh b/docs/api/store/code_samples/Shell/store_shipping-options/get.sh
index 12818d8ed7..0795b1d6e8 100644
--- a/docs/api/store/code_samples/Shell/store_shipping-options/get.sh
+++ b/docs/api/store/code_samples/Shell/store_shipping-options/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/shipping-options'
+curl 'https://medusa-url.com/store/shipping-options'
diff --git a/docs/api/store/code_samples/Shell/store_shipping-options_{cart_id}/get.sh b/docs/api/store/code_samples/Shell/store_shipping-options_{cart_id}/get.sh
index b7b747f9f9..8698aae4a0 100644
--- a/docs/api/store/code_samples/Shell/store_shipping-options_{cart_id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_shipping-options_{cart_id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/shipping-options/{cart_id}'
+curl 'https://medusa-url.com/store/shipping-options/{cart_id}'
diff --git a/docs/api/store/code_samples/Shell/store_swaps/post.sh b/docs/api/store/code_samples/Shell/store_swaps/post.sh
index 14b03ca379..3bc9fa266f 100644
--- a/docs/api/store/code_samples/Shell/store_swaps/post.sh
+++ b/docs/api/store/code_samples/Shell/store_swaps/post.sh
@@ -1,16 +1,16 @@
-curl --location --request POST 'https://medusa-url.com/store/swaps' \
---header 'Content-Type: application/json' \
+curl -X POST 'https://medusa-url.com/store/swaps' \
+-H 'Content-Type: application/json' \
 --data-raw '{
-    "order_id": "asfasf",
+    "order_id": "{order_id}",
     "return_items": [
       {
-        "item_id": "asfas",
+        "item_id": "{item_id}",
         "quantity": 1
       }
     ],
     "additional_items": [
       {
-        "variant_id": "asfas",
+        "variant_id": "{variant_id}",
         "quantity": 1
       }
     ]
diff --git a/docs/api/store/code_samples/Shell/store_swaps_{cart_id}/get.sh b/docs/api/store/code_samples/Shell/store_swaps_{cart_id}/get.sh
index 2b9aef474b..748a946533 100644
--- a/docs/api/store/code_samples/Shell/store_swaps_{cart_id}/get.sh
+++ b/docs/api/store/code_samples/Shell/store_swaps_{cart_id}/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/swaps/{cart_id}'
+curl 'https://medusa-url.com/store/swaps/{cart_id}'
diff --git a/docs/api/store/code_samples/Shell/store_variants/get.sh b/docs/api/store/code_samples/Shell/store_variants/get.sh
index 4568d2c137..67e2101103 100644
--- a/docs/api/store/code_samples/Shell/store_variants/get.sh
+++ b/docs/api/store/code_samples/Shell/store_variants/get.sh
@@ -1 +1 @@
-curl --location --request GET 'https://medusa-url.com/store/variants'
+curl 'https://medusa-url.com/store/variants'
diff --git a/docs/api/store/code_samples/Shell/store_variants_{id}/get.sh b/docs/api/store/code_samples/Shell/store_variants_{id}/get.sh
new file mode 100644
index 0000000000..fdeb0eeb0d
--- /dev/null
+++ b/docs/api/store/code_samples/Shell/store_variants_{id}/get.sh
@@ -0,0 +1 @@
+curl 'https://medusa-url.com/store/variants/{id}'
diff --git a/docs/api/store/code_samples/Shell/store_variants_{variant_id}/get.sh b/docs/api/store/code_samples/Shell/store_variants_{variant_id}/get.sh
deleted file mode 100644
index d9ca508004..0000000000
--- a/docs/api/store/code_samples/Shell/store_variants_{variant_id}/get.sh
+++ /dev/null
@@ -1 +0,0 @@
-curl --location --request GET 'https://medusa-url.com/store/variants/{id}'
diff --git a/docs/api/store/components/schemas/Address.yaml b/docs/api/store/components/schemas/Address.yaml
index d2797dc196..e0aee13932 100644
--- a/docs/api/store/components/schemas/Address.yaml
+++ b/docs/api/store/components/schemas/Address.yaml
@@ -1,5 +1,8 @@
 title: Address
-description: An address.
+description: >-
+  An address is used across the Medusa backend within other schemas and object
+  types. For example, a customer's billing and shipping addresses both use the
+  Address entity.
 type: object
 required:
   - address_1
@@ -72,7 +75,8 @@ properties:
       description: See a list of codes.
     example: st
   country:
-    description: A country object. Available if the relation `country` is expanded.
+    description: A country object.
+    x-expandable: country
     nullable: true
     $ref: ./Country.yaml
   province:
@@ -109,3 +113,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/BatchJob.yaml b/docs/api/store/components/schemas/BatchJob.yaml
index 31782073a7..a70156fe2c 100644
--- a/docs/api/store/components/schemas/BatchJob.yaml
+++ b/docs/api/store/components/schemas/BatchJob.yaml
@@ -1,5 +1,7 @@
 title: Batch Job
-description: A Batch Job.
+description: >-
+  A Batch Job indicates an asynchronus task stored in the Medusa backend. Its
+  status determines whether it has been executed or not.
 type: object
 required:
   - canceled_at
@@ -47,7 +49,8 @@ properties:
     type: string
     example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
   created_by_user:
-    description: A user object. Available if the relation `created_by_user` is expanded.
+    description: The details of the user that created the batch job.
+    x-expandable: created_by_user
     nullable: true
     $ref: ./User.yaml
   context:
diff --git a/docs/api/store/components/schemas/Cart.yaml b/docs/api/store/components/schemas/Cart.yaml
index 42935b558b..c63dda2fd3 100644
--- a/docs/api/store/components/schemas/Cart.yaml
+++ b/docs/api/store/components/schemas/Cart.yaml
@@ -1,5 +1,7 @@
 title: Cart
-description: Represents a user cart
+description: >-
+  A cart represents a virtual shopping bag. It can be used to complete an order,
+  a swap, or a claim.
 type: object
 required:
   - billing_address_id
@@ -35,7 +37,8 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   billing_address:
-    description: Available if the relation `billing_address` is expanded.
+    description: The details of the billing address associated with the cart.
+    x-expandable: billing_address
     nullable: true
     $ref: ./Address.yaml
   shipping_address_id:
@@ -44,12 +47,14 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   shipping_address:
-    description: Available if the relation `shipping_address` is expanded.
+    description: The details of the shipping address associated with the cart.
+    x-expandable: shipping_address
     nullable: true
     $ref: ./Address.yaml
   items:
-    description: Available if the relation `items` is expanded.
+    description: The line items added to the cart.
     type: array
+    x-expandable: items
     items:
       $ref: ./LineItem.yaml
   region_id:
@@ -57,17 +62,20 @@ properties:
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region associated with the cart.
+    x-expandable: region
     nullable: true
     $ref: ./Region.yaml
   discounts:
-    description: Available if the relation `discounts` is expanded.
+    description: An array of details of all discounts applied to the cart.
     type: array
+    x-expandable: discounts
     items:
       $ref: ./Discount.yaml
   gift_cards:
-    description: Available if the relation `gift_cards` is expanded.
+    description: An array of details of all gift cards applied to the cart.
     type: array
+    x-expandable: gift_cards
     items:
       $ref: ./GiftCard.yaml
   customer_id:
@@ -76,16 +84,19 @@ properties:
     type: string
     example: cus_01G2SG30J8C85S4A5CHM2S1NS2
   customer:
-    description: A customer object. Available if the relation `customer` is expanded.
+    description: The details of the customer the cart belongs to.
+    x-expandable: customer
     nullable: true
     type: object
   payment_session:
-    description: The selected payment session in the cart.
+    description: The details of the selected payment session in the cart.
+    x-expandable: payment_session
     nullable: true
     type: object
   payment_sessions:
-    description: The payment sessions created on the cart.
+    description: The details of all payment sessions created on the cart.
     type: array
+    x-expandable: payment_sessions
     items:
       type: object
   payment_id:
@@ -94,12 +105,14 @@ properties:
     type: string
     example: pay_01G8ZCC5W42ZNY842124G7P5R9
   payment:
-    description: Available if the relation `payment` is expanded.
+    description: The details of the payment associated with the cart.
     nullable: true
+    x-expandable: payment
     type: object
   shipping_methods:
-    description: The shipping methods added to the cart.
+    description: The details of the shipping methods added to the cart.
     type: array
+    x-expandable: shipping_methods
     items:
       $ref: ./ShippingMethod.yaml
   type:
@@ -144,10 +157,9 @@ properties:
     type: string
     example: null
   sales_channel:
-    description: >-
-      A sales channel object. Available if the relation `sales_channel` is
-      expanded.
+    description: The details of the sales channel associated with the cart.
     nullable: true
+    x-expandable: sales_channel
     $ref: ./SalesChannel.yaml
   created_at:
     description: The date with timezone at which the resource was created.
@@ -168,6 +180,10 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   shipping_total:
     description: The total of shipping
     type: integer
diff --git a/docs/api/store/components/schemas/ClaimImage.yaml b/docs/api/store/components/schemas/ClaimImage.yaml
index 214446d0bb..7b64e6be1d 100644
--- a/docs/api/store/components/schemas/ClaimImage.yaml
+++ b/docs/api/store/components/schemas/ClaimImage.yaml
@@ -1,5 +1,5 @@
 title: Claim Image
-description: Represents photo documentation of a claim.
+description: The details of an image attached to a claim.
 type: object
 required:
   - claim_item_id
@@ -18,8 +18,9 @@ properties:
     description: The ID of the claim item associated with the image
     type: string
   claim_item:
-    description: A claim item object. Available if the relation `claim_item` is expanded.
+    description: The details of the claim item this image is associated with.
     nullable: true
+    x-expandable: claim_item
     type: object
   url:
     description: The URL of the image
@@ -44,3 +45,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ClaimItem.yaml b/docs/api/store/components/schemas/ClaimItem.yaml
index 84a3b9afe6..6d9a8a9b67 100644
--- a/docs/api/store/components/schemas/ClaimItem.yaml
+++ b/docs/api/store/components/schemas/ClaimItem.yaml
@@ -1,7 +1,7 @@
 title: Claim Item
 description: >-
-  Represents a claimed item along with information about the reasons for the
-  claim.
+  A claim item is an item created as part of a claim. It references an item in
+  the order that should be exchanged or refunded.
 type: object
 required:
   - claim_order_id
@@ -21,15 +21,17 @@ properties:
     type: string
     example: citm_01G8ZH853Y6TFXWPG5EYE81X63
   images:
-    description: Available if the relation `images` is expanded.
+    description: The claim images that are attached to the claim item.
     type: array
+    x-expandable: images
     items:
       $ref: ./ClaimImage.yaml
   claim_order_id:
     description: The ID of the claim this item is associated with.
     type: string
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim this item belongs to.
+    x-expandable: claim_order
     nullable: true
     type: object
   item_id:
@@ -37,7 +39,10 @@ properties:
     type: string
     example: item_01G8ZM25TN49YV9EQBE2NC27KC
   item:
-    description: Available if the relation `item` is expanded.
+    description: >-
+      The details of the line item in the original order that this claim item
+      refers to.
+    x-expandable: item
     nullable: true
     $ref: ./LineItem.yaml
   variant_id:
@@ -45,7 +50,10 @@ properties:
     type: string
     example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
   variant:
-    description: A variant object. Available if the relation `variant` is expanded.
+    description: >-
+      The details of the product variant to potentially replace the item in the
+      original order.
+    x-expandable: variant
     nullable: true
     $ref: ./ProductVariant.yaml
   reason:
@@ -68,10 +76,9 @@ properties:
     type: integer
     example: 1
   tags:
-    description: >-
-      User defined tags for easy filtering and grouping. Available if the
-      relation 'tags' is expanded.
+    description: User defined tags for easy filtering and grouping.
     type: array
+    x-expandable: tags
     items:
       $ref: ./ClaimTag.yaml
   created_at:
@@ -93,3 +100,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ClaimOrder.yaml b/docs/api/store/components/schemas/ClaimOrder.yaml
index 5c439738c7..e3de8e9d1b 100644
--- a/docs/api/store/components/schemas/ClaimOrder.yaml
+++ b/docs/api/store/components/schemas/ClaimOrder.yaml
@@ -1,8 +1,8 @@
-title: Claim Order
+title: Claim
 description: >-
-  Claim Orders represent a group of faulty or missing items. Each claim order
-  consists of a subset of items associated with an original order, and can
-  contain additional information about fulfillments and returns.
+  A Claim represents a group of faulty or missing items. It consists of claim
+  items that refer to items in the original order that should be replaced or
+  refunded. It also includes details related to shipping and fulfillment.
 type: object
 required:
   - canceled_at
@@ -53,15 +53,17 @@ properties:
       - requires_action
     default: not_fulfilled
   claim_items:
-    description: The items that have been claimed
+    description: The details of the items that should be replaced or refunded.
     type: array
+    x-expandable: claim_items
     items:
       $ref: ./ClaimItem.yaml
   additional_items:
     description: >-
-      Refers to the new items to be shipped when the claim order has the type
+      The details of the new items to be shipped when the claim's type is
       `replace`
     type: array
+    x-expandable: additional_items
     items:
       $ref: ./LineItem.yaml
   order_id:
@@ -69,13 +71,15 @@ properties:
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that this claim was created for.
+    x-expandable: order
     nullable: true
     type: object
   return_order:
     description: >-
-      A return object. Holds information about the return if the claim is to be
-      returned. Available if the relation 'return_order' is expanded
+      The details of the return associated with the claim if the claim's type is
+      `replace`.
+    x-expandable: return_order
     nullable: true
     type: object
   shipping_address_id:
@@ -84,17 +88,22 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   shipping_address:
-    description: Available if the relation `shipping_address` is expanded.
+    description: The details of the address that new items should be shipped to.
+    x-expandable: shipping_address
     nullable: true
     $ref: ./Address.yaml
   shipping_methods:
-    description: The shipping methods that the claim order will be shipped with.
+    description: >-
+      The details of the shipping methods that the claim order will be shipped
+      with.
     type: array
+    x-expandable: shipping_methods
     items:
       $ref: ./ShippingMethod.yaml
   fulfillments:
     description: The fulfillments of the new items to be shipped
     type: array
+    x-expandable: fulfillments
     items:
       type: object
   refund_amount:
@@ -126,6 +135,10 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   no_notification:
     description: >-
       Flag for describing whether or not notifications related to this should be
diff --git a/docs/api/store/components/schemas/ClaimTag.yaml b/docs/api/store/components/schemas/ClaimTag.yaml
index fe9a2fd418..4c8924448f 100644
--- a/docs/api/store/components/schemas/ClaimTag.yaml
+++ b/docs/api/store/components/schemas/ClaimTag.yaml
@@ -38,3 +38,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/Country.yaml b/docs/api/store/components/schemas/Country.yaml
index 3b78bc3b33..cfa712f0ff 100644
--- a/docs/api/store/components/schemas/Country.yaml
+++ b/docs/api/store/components/schemas/Country.yaml
@@ -52,6 +52,7 @@ properties:
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region the country is associated with.
+    x-expandable: region
     nullable: true
     type: object
diff --git a/docs/api/store/components/schemas/Currency.yaml b/docs/api/store/components/schemas/Currency.yaml
index a7aef7d3a8..adfb21705c 100644
--- a/docs/api/store/components/schemas/Currency.yaml
+++ b/docs/api/store/components/schemas/Currency.yaml
@@ -27,6 +27,7 @@ properties:
     type: string
     example: US Dollar
   includes_tax:
-    description: '[EXPERIMENTAL] Does the currency prices include tax'
+    description: Whether the currency prices include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
diff --git a/docs/api/store/components/schemas/CustomShippingOption.yaml b/docs/api/store/components/schemas/CustomShippingOption.yaml
index e3db8a274e..66c68e1f1f 100644
--- a/docs/api/store/components/schemas/CustomShippingOption.yaml
+++ b/docs/api/store/components/schemas/CustomShippingOption.yaml
@@ -1,8 +1,8 @@
 title: Custom Shipping Option
 description: >-
-  Custom Shipping Options are 'overriden' Shipping Options. Store managers can
-  attach a Custom Shipping Option to a cart in order to set a custom price for a
-  particular Shipping Option
+  Custom Shipping Options are overriden Shipping Options. Admins can attach a
+  Custom Shipping Option to a cart in order to set a custom price for a
+  particular Shipping Option.
 type: object
 required:
   - cart_id
@@ -29,9 +29,8 @@ properties:
     type: string
     example: so_01G1G5V27GYX4QXNARRQCW1N8T
   shipping_option:
-    description: >-
-      A shipping option object. Available if the relation `shipping_option` is
-      expanded.
+    description: The details of the overriden shipping options.
+    x-expandable: shipping_option
     nullable: true
     $ref: ./ShippingOption.yaml
   cart_id:
@@ -40,7 +39,8 @@ properties:
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart this shipping option belongs to.
+    x-expandable: cart
     nullable: true
     $ref: ./Cart.yaml
   created_at:
@@ -62,3 +62,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/Customer.yaml b/docs/api/store/components/schemas/Customer.yaml
index c980de29f0..ecc9c83ee4 100644
--- a/docs/api/store/components/schemas/Customer.yaml
+++ b/docs/api/store/components/schemas/Customer.yaml
@@ -1,5 +1,5 @@
 title: Customer
-description: Represents a customer
+description: A customer can make purchases in your store and manage their profile.
 type: object
 required:
   - billing_address_id
@@ -38,12 +38,14 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   billing_address:
-    description: Available if the relation `billing_address` is expanded.
+    description: The details of the billing address associated with the customer.
+    x-expandable: billing_address
     nullable: true
     $ref: ./Address.yaml
   shipping_addresses:
-    description: Available if the relation `shipping_addresses` is expanded.
+    description: The details of the shipping addresses associated with the customer.
     type: array
+    x-expandable: shipping_addresses
     items:
       $ref: ./Address.yaml
   phone:
@@ -56,15 +58,15 @@ properties:
     type: boolean
     default: false
   orders:
-    description: Available if the relation `orders` is expanded.
+    description: The details of the orders this customer placed.
     type: array
+    x-expandable: orders
     items:
       type: object
   groups:
-    description: >-
-      The customer groups the customer belongs to. Available if the relation
-      `groups` is expanded.
+    description: The customer groups the customer belongs to.
     type: array
+    x-expandable: groups
     items:
       $ref: ./CustomerGroup.yaml
   created_at:
@@ -86,3 +88,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/CustomerGroup.yaml b/docs/api/store/components/schemas/CustomerGroup.yaml
index c3ae03f953..a572493cad 100644
--- a/docs/api/store/components/schemas/CustomerGroup.yaml
+++ b/docs/api/store/components/schemas/CustomerGroup.yaml
@@ -1,5 +1,7 @@
 title: Customer Group
-description: Represents a customer group
+description: >-
+  A customer group that can be used to organize customers into groups of similar
+  traits.
 type: object
 required:
   - created_at
@@ -18,17 +20,15 @@ properties:
     type: string
     example: VIP
   customers:
-    description: >-
-      The customers that belong to the customer group. Available if the relation
-      `customers` is expanded.
+    description: The details of the customers that belong to the customer group.
     type: array
+    x-expandable: customers
     items:
       type: object
   price_lists:
-    description: >-
-      The price lists that are associated with the customer group. Available if
-      the relation `price_lists` is expanded.
+    description: The price lists that are associated with the customer group.
     type: array
+    x-expandable: price_lists
     items:
       type: object
   created_at:
@@ -50,3 +50,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/Discount.yaml b/docs/api/store/components/schemas/Discount.yaml
index 124f8698ed..796477999f 100644
--- a/docs/api/store/components/schemas/Discount.yaml
+++ b/docs/api/store/components/schemas/Discount.yaml
@@ -1,5 +1,5 @@
 title: Discount
-description: Represents a discount that can be applied to a cart for promotional purposes.
+description: A discount can be applied to a cart for promotional purposes.
 type: object
 required:
   - code
@@ -35,12 +35,17 @@ properties:
     type: boolean
     example: false
   rule_id:
-    description: The Discount Rule that governs the behaviour of the Discount
+    description: >-
+      The ID of the discount rule that defines how the discount will be applied
+      to a cart.
     nullable: true
     type: string
     example: dru_01F0YESMVK96HVX7N419E3CJ7C
   rule:
-    description: Available if the relation `rule` is expanded.
+    description: >-
+      The details of the discount rule that defines how the discount will be
+      applied to a cart..
+    x-expandable: rule
     nullable: true
     $ref: ./DiscountRule.yaml
   is_disabled:
@@ -57,7 +62,8 @@ properties:
     type: string
     example: disc_01G8ZH853YPY9B94857DY91YGW
   parent_discount:
-    description: Available if the relation `parent_discount` is expanded.
+    description: The details of the parent discount that this discount was created from.
+    x-expandable: parent_discount
     nullable: true
     type: object
   starts_at:
@@ -75,10 +81,9 @@ properties:
     type: string
     example: P3Y6M4DT12H30M5S
   regions:
-    description: >-
-      The Regions in which the Discount can be used. Available if the relation
-      `regions` is expanded.
+    description: The details of the regions in which the Discount can be used.
     type: array
+    x-expandable: regions
     items:
       $ref: ./Region.yaml
   usage_limit:
@@ -110,3 +115,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/DiscountCondition.yaml b/docs/api/store/components/schemas/DiscountCondition.yaml
index b536b8f05f..4652b43d56 100644
--- a/docs/api/store/components/schemas/DiscountCondition.yaml
+++ b/docs/api/store/components/schemas/DiscountCondition.yaml
@@ -16,7 +16,11 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   type:
-    description: The type of the Condition
+    description: >-
+      The type of the condition. The type affects the available resources
+      associated with the condition. For example, if the type is `products`,
+      that means the `products` relation will hold the products associated with
+      this condition and other relations will be empty.
     type: string
     enum:
       - products
@@ -25,7 +29,10 @@ properties:
       - product_tags
       - customer_groups
   operator:
-    description: The operator of the Condition
+    description: >-
+      The operator of the condition. `in` indicates that discountable resources
+      are within the specified resources. `not_in` indicates that discountable
+      resources are everything but the specified resources.
     type: string
     enum:
       - in
@@ -35,43 +42,42 @@ properties:
     type: string
     example: dru_01F0YESMVK96HVX7N419E3CJ7C
   discount_rule:
-    description: Available if the relation `discount_rule` is expanded.
+    description: The details of the discount rule associated with the condition.
+    x-expandable: discount_rule
     nullable: true
     $ref: ./DiscountRule.yaml
   products:
-    description: >-
-      products associated with this condition if type = products. Available if
-      the relation `products` is expanded.
+    description: products associated with this condition if `type` is `products`.
     type: array
+    x-expandable: products
     items:
       $ref: ./Product.yaml
   product_types:
-    description: >-
-      Product types associated with this condition if type = product_types.
-      Available if the relation `product_types` is expanded.
+    description: Product types associated with this condition if `type` is `product_types`.
     type: array
+    x-expandable: product_types
     items:
       $ref: ./ProductType.yaml
   product_tags:
-    description: >-
-      Product tags associated with this condition if type = product_tags.
-      Available if the relation `product_tags` is expanded.
+    description: Product tags associated with this condition if `type` is `product_tags`.
     type: array
+    x-expandable: product_tags
     items:
       $ref: ./ProductTag.yaml
   product_collections:
     description: >-
-      Product collections associated with this condition if type =
-      product_collections. Available if the relation `product_collections` is
-      expanded.
+      Product collections associated with this condition if `type` is
+      `product_collections`.
     type: array
+    x-expandable: product_collections
     items:
       $ref: ./ProductCollection.yaml
   customer_groups:
     description: >-
-      Customer groups associated with this condition if type = customer_groups.
-      Available if the relation `customer_groups` is expanded.
+      Customer groups associated with this condition if `type` is
+      `customer_groups`.
     type: array
+    x-expandable: customer_groups
     items:
       $ref: ./CustomerGroup.yaml
   created_at:
@@ -93,3 +99,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/DiscountConditionCustomerGroup.yaml b/docs/api/store/components/schemas/DiscountConditionCustomerGroup.yaml
index 136f2f8472..2f55e79142 100644
--- a/docs/api/store/components/schemas/DiscountConditionCustomerGroup.yaml
+++ b/docs/api/store/components/schemas/DiscountConditionCustomerGroup.yaml
@@ -38,3 +38,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/DiscountConditionProduct.yaml b/docs/api/store/components/schemas/DiscountConditionProduct.yaml
index 4ce3691cdf..2fb9699b9e 100644
--- a/docs/api/store/components/schemas/DiscountConditionProduct.yaml
+++ b/docs/api/store/components/schemas/DiscountConditionProduct.yaml
@@ -1,5 +1,5 @@
 title: Product Discount Condition
-description: Associates a discount condition with a product
+description: This represents the association between a discount condition and a product
 type: object
 required:
   - condition_id
@@ -17,11 +17,13 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   product:
-    description: Available if the relation `product` is expanded.
+    description: The details of the product.
+    x-expandable: product
     nullable: true
     $ref: ./Product.yaml
   discount_condition:
-    description: Available if the relation `discount_condition` is expanded.
+    description: The details of the discount condition.
+    x-expandable: discount_condition
     nullable: true
     $ref: ./DiscountCondition.yaml
   created_at:
@@ -38,3 +40,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/DiscountConditionProductCollection.yaml b/docs/api/store/components/schemas/DiscountConditionProductCollection.yaml
index b48d9d6516..5e8b88b9e3 100644
--- a/docs/api/store/components/schemas/DiscountConditionProductCollection.yaml
+++ b/docs/api/store/components/schemas/DiscountConditionProductCollection.yaml
@@ -1,5 +1,7 @@
 title: Product Collection Discount Condition
-description: Associates a discount condition with a product collection
+description: >-
+  This represents the association between a discount condition and a product
+  collection
 type: object
 required:
   - condition_id
@@ -17,11 +19,13 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   product_collection:
-    description: Available if the relation `product_collection` is expanded.
+    description: The details of the product collection.
+    x-expandable: product_collection
     nullable: true
     $ref: ./ProductCollection.yaml
   discount_condition:
-    description: Available if the relation `discount_condition` is expanded.
+    description: The details of the discount condition.
+    x-expandable: discount_condition
     nullable: true
     $ref: ./DiscountCondition.yaml
   created_at:
@@ -38,3 +42,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/DiscountConditionProductTag.yaml b/docs/api/store/components/schemas/DiscountConditionProductTag.yaml
index 61c29d1a71..58ba07c6c3 100644
--- a/docs/api/store/components/schemas/DiscountConditionProductTag.yaml
+++ b/docs/api/store/components/schemas/DiscountConditionProductTag.yaml
@@ -1,5 +1,5 @@
 title: Product Tag Discount Condition
-description: Associates a discount condition with a product tag
+description: This represents the association between a discount condition and a product tag
 type: object
 required:
   - condition_id
@@ -17,11 +17,13 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   product_tag:
-    description: Available if the relation `product_tag` is expanded.
+    description: The details of the product tag.
+    x-expandable: product_tag
     nullable: true
     $ref: ./ProductTag.yaml
   discount_condition:
-    description: Available if the relation `discount_condition` is expanded.
+    description: The details of the discount condition.
+    x-expandable: discount_condition
     nullable: true
     $ref: ./DiscountCondition.yaml
   created_at:
@@ -38,3 +40,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/DiscountConditionProductType.yaml b/docs/api/store/components/schemas/DiscountConditionProductType.yaml
index 77a7a5ad8b..d93129494c 100644
--- a/docs/api/store/components/schemas/DiscountConditionProductType.yaml
+++ b/docs/api/store/components/schemas/DiscountConditionProductType.yaml
@@ -1,5 +1,7 @@
 title: Product Type Discount Condition
-description: Associates a discount condition with a product type
+description: >-
+  This represents the association between a discount condition and a product
+  type
 type: object
 required:
   - condition_id
@@ -17,11 +19,13 @@ properties:
     type: string
     example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
   product_type:
-    description: Available if the relation `product_type` is expanded.
+    description: The details of the product type.
+    x-expandable: product_type
     nullable: true
     $ref: ./ProductType.yaml
   discount_condition:
-    description: Available if the relation `discount_condition` is expanded.
+    description: The details of the discount condition.
+    x-expandable: discount_condition
     nullable: true
     $ref: ./DiscountCondition.yaml
   created_at:
@@ -38,3 +42,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/DiscountRule.yaml b/docs/api/store/components/schemas/DiscountRule.yaml
index e2571f38a7..caa7f9d604 100644
--- a/docs/api/store/components/schemas/DiscountRule.yaml
+++ b/docs/api/store/components/schemas/DiscountRule.yaml
@@ -1,7 +1,5 @@
 title: Discount Rule
-description: >-
-  Holds the rules that governs how a Discount is calculated when applied to a
-  Cart.
+description: A discount rule defines how a Discount is calculated when applied to a Cart.
 type: object
 required:
   - allocation
@@ -50,9 +48,10 @@ properties:
     example: total
   conditions:
     description: >-
-      A set of conditions that can be used to limit when  the discount can be
-      used. Available if the relation `conditions` is expanded.
+      The details of the discount conditions associated with the rule. They can
+      be used to limit when the discount can be used.
     type: array
+    x-expandable: conditions
     items:
       type: object
   created_at:
@@ -74,3 +73,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/DraftOrder.yaml b/docs/api/store/components/schemas/DraftOrder.yaml
index 39e150901f..86ff90bf25 100644
--- a/docs/api/store/components/schemas/DraftOrder.yaml
+++ b/docs/api/store/components/schemas/DraftOrder.yaml
@@ -1,5 +1,8 @@
 title: DraftOrder
-description: Represents a draft order
+description: >-
+  A draft order is created by an admin without direct involvement of the
+  customer. Once its payment is marked as captured, it is transformed into an
+  order.
 type: object
 required:
   - canceled_at
@@ -20,7 +23,9 @@ properties:
     type: string
     example: dorder_01G8TJFKBG38YYFQ035MSVG03C
   status:
-    description: The status of the draft order
+    description: >-
+      The status of the draft order. It's changed to `completed` when it's
+      transformed to an order.
     type: string
     enum:
       - open
@@ -36,16 +41,22 @@ properties:
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart associated with the draft order.
+    x-expandable: cart
     nullable: true
     type: object
   order_id:
-    description: The ID of the order associated with the draft order.
+    description: >-
+      The ID of the order created from the draft order when its payment is
+      captured.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: >-
+      The details of the order created from the draft order when its payment is
+      captured.
+    x-expandable: order
     nullable: true
     type: object
   canceled_at:
@@ -86,3 +97,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/Fulfillment.yaml b/docs/api/store/components/schemas/Fulfillment.yaml
index 8de3d7072b..b9f77587a4 100644
--- a/docs/api/store/components/schemas/Fulfillment.yaml
+++ b/docs/api/store/components/schemas/Fulfillment.yaml
@@ -1,12 +1,10 @@
 title: Fulfillment
 description: >-
-  Fulfillments are created once store operators can prepare the purchased goods.
+  A Fulfillment is created once an admin can prepare the purchased goods.
   Fulfillments will eventually be shipped and hold information about how to
-  track shipments. Fulfillments are created through a provider, which is
-  typically an external shipping aggregator, shipping partner og 3PL, most
-  plugins will have asynchronous communications with these providers through
-  webhooks in order to automatically update and synchronize the state of
-  Fulfillments.
+  track shipments. Fulfillments are created through a fulfillment provider,
+  which typically integrates a third-party shipping service. Fulfillments can be
+  associated with orders, claims, swaps, and returns.
 type: object
 required:
   - canceled_at
@@ -30,61 +28,67 @@ properties:
     type: string
     example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
   claim_order_id:
-    description: The id of the Claim that the Fulfillment belongs to.
+    description: The ID of the Claim that the Fulfillment belongs to.
     nullable: true
     type: string
     example: null
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim that the fulfillment may belong to.
+    x-expandable: claim_order
     nullable: true
     type: object
   swap_id:
-    description: The id of the Swap that the Fulfillment belongs to.
+    description: The ID of the Swap that the Fulfillment belongs to.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that the fulfillment may belong to.
+    x-expandable: swap
     nullable: true
     type: object
   order_id:
-    description: The id of the Order that the Fulfillment belongs to.
+    description: The ID of the Order that the Fulfillment belongs to.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the fulfillment may belong to.
+    x-expandable: order
     nullable: true
     type: object
   provider_id:
     description: >-
-      The id of the Fulfillment Provider responsible for handling the
-      fulfillment
+      The ID of the Fulfillment Provider responsible for handling the
+      fulfillment.
     type: string
     example: manual
   provider:
-    description: Available if the relation `provider` is expanded.
+    description: >-
+      The details of the fulfillment provider responsible for handling the
+      fulfillment.
+    x-expandable: provider
     nullable: true
     $ref: ./FulfillmentProvider.yaml
   location_id:
-    description: The id of the stock location the fulfillment will be shipped from
+    description: The ID of the stock location the fulfillment will be shipped from
     nullable: true
     type: string
     example: sloc_01G8TJSYT9M6AVS5N4EMNFS1EK
   items:
     description: >-
-      The Fulfillment Items in the Fulfillment - these hold information about
-      how many of each Line Item has been fulfilled. Available if the relation
-      `items` is expanded.
+      The Fulfillment Items in the Fulfillment. These hold information about how
+      many of each Line Item has been fulfilled.
     type: array
+    x-expandable: items
     items:
       $ref: ./FulfillmentItem.yaml
   tracking_links:
     description: >-
       The Tracking Links that can be used to track the status of the
-      Fulfillment, these will usually be provided by the Fulfillment Provider.
-      Available if the relation `tracking_links` is expanded.
+      Fulfillment. These will usually be provided by the Fulfillment Provider.
     type: array
+    x-expandable: tracking_links
     items:
       $ref: ./TrackingLink.yaml
   tracking_numbers:
@@ -141,3 +145,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/FulfillmentItem.yaml b/docs/api/store/components/schemas/FulfillmentItem.yaml
index ad05c5637e..7204760274 100644
--- a/docs/api/store/components/schemas/FulfillmentItem.yaml
+++ b/docs/api/store/components/schemas/FulfillmentItem.yaml
@@ -1,7 +1,5 @@
 title: Fulfillment Item
-description: >-
-  Correlates a Line Item with a Fulfillment, keeping track of the quantity of
-  the Line Item.
+description: This represents the association between a Line Item and a Fulfillment.
 type: object
 required:
   - fulfillment_id
@@ -9,19 +7,21 @@ required:
   - quantity
 properties:
   fulfillment_id:
-    description: The id of the Fulfillment that the Fulfillment Item belongs to.
+    description: The ID of the Fulfillment that the Fulfillment Item belongs to.
     type: string
     example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
   item_id:
-    description: The id of the Line Item that the Fulfillment Item references.
+    description: The ID of the Line Item that the Fulfillment Item references.
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   fulfillment:
-    description: A fulfillment object. Available if the relation `fulfillment` is expanded.
+    description: The details of the fulfillment.
+    x-expandable: fulfillment
     nullable: true
     type: object
   item:
-    description: Available if the relation `item` is expanded.
+    description: The details of the line item.
+    x-expandable: item
     nullable: true
     $ref: ./LineItem.yaml
   quantity:
diff --git a/docs/api/store/components/schemas/FulfillmentProvider.yaml b/docs/api/store/components/schemas/FulfillmentProvider.yaml
index 77f50f4c75..366e045f2f 100644
--- a/docs/api/store/components/schemas/FulfillmentProvider.yaml
+++ b/docs/api/store/components/schemas/FulfillmentProvider.yaml
@@ -1,18 +1,21 @@
 title: Fulfillment Provider
-description: Represents a fulfillment provider plugin and holds its installation status.
+description: >-
+  A fulfillment provider represents a fulfillment service installed in the
+  Medusa backend, either through a plugin or backend customizations. It holds
+  the fulfillment service's installation status.
 type: object
 required:
   - id
   - is_installed
 properties:
   id:
-    description: The id of the fulfillment provider as given by the plugin.
+    description: The ID of the fulfillment provider as given by the fulfillment service.
     type: string
     example: manual
   is_installed:
     description: >-
-      Whether the plugin is installed in the current version. Plugins that are
-      no longer installed are not deleted by will have this field set to
-      `false`.
+      Whether the fulfillment service is installed in the current version. If a
+      fulfillment service is no longer installed, the `is_installed` attribute
+      is set to `false`.
     type: boolean
     default: true
diff --git a/docs/api/store/components/schemas/GiftCard.yaml b/docs/api/store/components/schemas/GiftCard.yaml
index 0967dd0b92..cd3b03dc19 100644
--- a/docs/api/store/components/schemas/GiftCard.yaml
+++ b/docs/api/store/components/schemas/GiftCard.yaml
@@ -37,20 +37,22 @@ properties:
     type: integer
     example: 10
   region_id:
-    description: The id of the Region in which the Gift Card is available.
+    description: The ID of the region this gift card is available in.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region this gift card is available in.
+    x-expandable: region
     nullable: true
     $ref: ./Region.yaml
   order_id:
-    description: The id of the Order that the Gift Card was purchased in.
+    description: The ID of the order that the gift card was purchased in.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the gift card was purchased in.
+    x-expandable: region
     nullable: true
     type: object
   is_disabled:
@@ -88,3 +90,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/GiftCardTransaction.yaml b/docs/api/store/components/schemas/GiftCardTransaction.yaml
index 48cd927c23..e1f3f9b490 100644
--- a/docs/api/store/components/schemas/GiftCardTransaction.yaml
+++ b/docs/api/store/components/schemas/GiftCardTransaction.yaml
@@ -1,7 +1,7 @@
 title: Gift Card Transaction
 description: >-
   Gift Card Transactions are created once a Customer uses a Gift Card to pay for
-  their Order
+  their Order.
 type: object
 required:
   - amount
@@ -21,15 +21,17 @@ properties:
     type: string
     example: gift_01G8XKBPBQY2R7RBET4J7E0XQZ
   gift_card:
-    description: A gift card object. Available if the relation `gift_card` is expanded.
+    description: The details of the gift card associated used in this transaction.
+    x-expandable: gift_card
     nullable: true
     type: object
   order_id:
-    description: The ID of the Order that the Gift Card was used to pay for.
+    description: The ID of the order that the gift card was used for payment.
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the gift card was used for payment.
+    x-expandable: order
     nullable: true
     type: object
   amount:
diff --git a/docs/api/store/components/schemas/Image.yaml b/docs/api/store/components/schemas/Image.yaml
index e061ecefe8..c837dd4b5d 100644
--- a/docs/api/store/components/schemas/Image.yaml
+++ b/docs/api/store/components/schemas/Image.yaml
@@ -1,5 +1,7 @@
 title: Image
-description: Images holds a reference to a URL at which the image file can be found.
+description: >-
+  An Image is used to store details about uploaded images. Images are uploaded
+  by the File Service, and the URL is provided by the File Service.
 type: object
 required:
   - created_at
@@ -36,3 +38,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/Invite.yaml b/docs/api/store/components/schemas/Invite.yaml
index fa8ba054c5..4ab1e33195 100644
--- a/docs/api/store/components/schemas/Invite.yaml
+++ b/docs/api/store/components/schemas/Invite.yaml
@@ -1,5 +1,7 @@
 title: Invite
-description: Represents an invite
+description: >-
+  An invite is created when an admin user invites a new user to join the store's
+  team. Once the invite is accepted, it's deleted.
 type: object
 required:
   - accepted
@@ -22,7 +24,7 @@ properties:
     type: string
     format: email
   role:
-    description: The user's role.
+    description: The user's role. These roles don't change the privileges of the user.
     nullable: true
     type: string
     enum:
@@ -60,3 +62,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/LineItem.yaml b/docs/api/store/components/schemas/LineItem.yaml
index 67b1ee5cd0..155bafaedd 100644
--- a/docs/api/store/components/schemas/LineItem.yaml
+++ b/docs/api/store/components/schemas/LineItem.yaml
@@ -1,9 +1,9 @@
 title: Line Item
 description: >-
-  Line Items represent purchasable units that can be added to a Cart for
-  checkout. When Line Items are purchased they will get copied to the resulting
-  order and can eventually be referenced in Fulfillments and Returns. Line Items
-  may also be created when processing Swaps and Claims.
+  Line Items are created when a product is added to a Cart. When Line Items are
+  purchased they will get copied to the resulting order, swap, or claim, and can
+  eventually be referenced in Fulfillments and Returns. Line items may also be
+  used for order edits.
 type: object
 required:
   - allow_discounts
@@ -36,67 +36,76 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   cart_id:
-    description: The ID of the Cart that the Line Item belongs to.
+    description: The ID of the cart that the line item may belongs to.
     nullable: true
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart that the line item may belongs to.
+    x-expandable: cart
     nullable: true
     type: object
   order_id:
-    description: The ID of the Order that the Line Item belongs to.
+    description: The ID of the order that the line item may belongs to.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the line item may belongs to.
+    x-expandable: order
     nullable: true
     type: object
   swap_id:
-    description: The id of the Swap that the Line Item belongs to.
+    description: The ID of the swap that the line item may belong to.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that the line item may belong to.
+    x-expandable: swap
     nullable: true
     type: object
   claim_order_id:
-    description: The id of the Claim that the Line Item belongs to.
+    description: The ID of the claim that the line item may belong to.
     nullable: true
     type: string
     example: null
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim that the line item may belong to.
+    x-expandable: claim_order
     nullable: true
     type: object
   tax_lines:
-    description: Available if the relation `tax_lines` is expanded.
+    description: The details of the item's tax lines.
+    x-expandable: tax_lines
     type: array
     items:
       $ref: ./LineItemTaxLine.yaml
   adjustments:
-    description: Available if the relation `adjustments` is expanded.
+    description: >-
+      The details of the item's adjustments, which are available when a discount
+      is applied on the item.
+    x-expandable: adjustments
     type: array
     items:
       $ref: ./LineItemAdjustment.yaml
   original_item_id:
-    description: The id of the original line item
+    description: >-
+      The ID of the original line item. This is useful if the line item belongs
+      to a resource that references an order, such as a return or an order edit.
     nullable: true
     type: string
   order_edit_id:
-    description: The ID of the order edit to which a cloned item belongs
+    description: The ID of the order edit that the item may belong to.
     nullable: true
     type: string
   order_edit:
-    description: The order edit joined. Available if the relation `order_edit` is expanded.
+    description: The details of the order edit.
+    x-expandable: order_edit
     nullable: true
     type: object
   title:
-    description: >-
-      The title of the Line Item, this should be easily identifiable by the
-      Customer.
+    description: The title of the Line Item.
     type: string
     example: Medusa Coffee Mug
   description:
@@ -148,9 +157,8 @@ properties:
     type: string
     example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
   variant:
-    description: >-
-      A product variant object. The Product Variant contained in the Line Item.
-      Available if the relation `variant` is expanded.
+    description: The details of the product variant that this item was created from.
+    x-expandable: variant
     nullable: true
     $ref: ./ProductVariant.yaml
   quantity:
@@ -211,7 +219,8 @@ properties:
     type: integer
     example: 0
   includes_tax:
-    description: '[EXPERIMENTAL] Indicates if the line item unit_price include tax'
+    description: Indicates if the line item unit_price include tax
+    x-featureFlag: tax_inclusive_pricing
     type: boolean
     default: false
   created_at:
@@ -228,3 +237,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/LineItemAdjustment.yaml b/docs/api/store/components/schemas/LineItemAdjustment.yaml
index 5dcc6f496f..7d30b61c15 100644
--- a/docs/api/store/components/schemas/LineItemAdjustment.yaml
+++ b/docs/api/store/components/schemas/LineItemAdjustment.yaml
@@ -1,5 +1,5 @@
 title: Line Item Adjustment
-description: Represents a Line Item Adjustment
+description: A Line Item Adjustment includes details on discounts applied on a line item.
 type: object
 required:
   - amount
@@ -18,7 +18,8 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   item:
-    description: Available if the relation `item` is expanded.
+    description: The details of the line item.
+    x-expandable: item
     nullable: true
     type: object
   description:
@@ -31,7 +32,8 @@ properties:
     type: string
     example: disc_01F0YESMW10MGHWJKZSDDMN0VN
   discount:
-    description: Available if the relation `discount` is expanded.
+    description: The details of the discount associated with the adjustment.
+    x-expandable: discount
     nullable: true
     $ref: ./Discount.yaml
   amount:
@@ -44,3 +46,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/LineItemTaxLine.yaml b/docs/api/store/components/schemas/LineItemTaxLine.yaml
index ec316b7cb7..69832cdd1e 100644
--- a/docs/api/store/components/schemas/LineItemTaxLine.yaml
+++ b/docs/api/store/components/schemas/LineItemTaxLine.yaml
@@ -1,5 +1,5 @@
 title: Line Item Tax Line
-description: Represents a Line Item Tax Line
+description: A Line Item Tax Line represents the taxes applied on a line item.
 type: object
 required:
   - code
@@ -33,7 +33,8 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   item:
-    description: Available if the relation `item` is expanded.
+    description: The details of the line item.
+    x-expandable: item
     nullable: true
     type: object
   created_at:
@@ -50,3 +51,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/MoneyAmount.yaml b/docs/api/store/components/schemas/MoneyAmount.yaml
index f2b78adabf..920f9a3242 100644
--- a/docs/api/store/components/schemas/MoneyAmount.yaml
+++ b/docs/api/store/components/schemas/MoneyAmount.yaml
@@ -1,10 +1,11 @@
 title: Money Amount
 description: >-
-  Money Amounts represents an amount that a given Product Variant can be
-  purcased for. Each Money Amount either has a Currency or Region associated
-  with it to indicate the pricing in a given Currency or, for fully region-based
-  pricing, the given price in a specific Region. If region-based pricing is used
-  the amount will be in the currency defined for the Reigon.
+  A Money Amount represent a price amount, for example, a product variant's
+  price or a price in a price list. Each Money Amount either has a Currency or
+  Region associated with it to indicate the pricing in a given Currency or, for
+  fully region-based pricing, the given price in a specific Region. If
+  region-based pricing is used, the amount will be in the currency defined for
+  the Region.
 type: object
 required:
   - amount
@@ -24,14 +25,15 @@ properties:
     type: string
     example: ma_01F0YESHRFQNH5S8Q0PK84YYZN
   currency_code:
-    description: The 3 character currency code that the Money Amount is given in.
+    description: The 3 character currency code that the money amount may belong to.
     type: string
     example: usd
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency that the money amount may belong to.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   amount:
@@ -55,23 +57,23 @@ properties:
     type: integer
     example: 1
   price_list_id:
-    description: The ID of the price list associated with the money amount
+    description: The ID of the price list that the money amount may belong to.
     nullable: true
     type: string
     example: pl_01G8X3CKJXCG5VXVZ87H9KC09W
   price_list:
-    description: Available if the relation `price_list` is expanded.
+    description: The details of the price list that the money amount may belong to.
+    x-expandable: price_list
     nullable: true
     type: object
   variant_id:
-    description: The id of the Product Variant contained in the Line Item.
+    description: The ID of the Product Variant contained in the Line Item.
     nullable: true
     type: string
     example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
   variant:
-    description: >-
-      The Product Variant contained in the Line Item. Available if the relation
-      `variant` is expanded.
+    description: The details of the product variant that the money amount may belong to.
+    x-expandable: variant
     nullable: true
     type: object
   region_id:
@@ -80,7 +82,8 @@ properties:
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region that the money amount may belong to.
+    x-expandable: region
     nullable: true
     type: object
   created_at:
diff --git a/docs/api/store/components/schemas/Note.yaml b/docs/api/store/components/schemas/Note.yaml
index 3fce158b7e..9a33972604 100644
--- a/docs/api/store/components/schemas/Note.yaml
+++ b/docs/api/store/components/schemas/Note.yaml
@@ -1,7 +1,8 @@
 title: Note
 description: >-
-  Notes are elements which we can use in association with different resources to
-  allow users to describe additional information in relation to these.
+  A Note is an element that can be used in association with different resources
+  to allow admin users to describe additional information. For example, they can
+  be used to add additional information about orders.
 type: object
 required:
   - author_id
@@ -31,12 +32,13 @@ properties:
     type: string
     example: This order must be fulfilled on Monday
   author_id:
-    description: The ID of the author (user)
+    description: The ID of the user that created the note.
     nullable: true
     type: string
     example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
   author:
-    description: Available if the relation `author` is expanded.
+    description: The details of the user that created the note.
+    x-expandable: author
     nullable: true
     $ref: ./User.yaml
   created_at:
diff --git a/docs/api/store/components/schemas/Notification.yaml b/docs/api/store/components/schemas/Notification.yaml
index 13eca79f77..0d00e6fed4 100644
--- a/docs/api/store/components/schemas/Notification.yaml
+++ b/docs/api/store/components/schemas/Notification.yaml
@@ -1,9 +1,8 @@
 title: Notification
 description: >-
-  Notifications a communications sent via Notification Providers as a reaction
-  to internal events such as `order.placed`. Notifications can be used to show a
-  chronological timeline for communications sent to a Customer regarding an
-  Order, and enables resends.
+  A notification is an alert sent, typically to customers, using the installed
+  Notification Provider as a reaction to internal events such as `order.placed`.
+  Notifications can be resent.
 type: object
 required:
   - created_at
@@ -36,18 +35,20 @@ properties:
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   customer_id:
-    description: The ID of the Customer that the Notification was sent to.
+    description: The ID of the customer that this notification was sent to.
     nullable: true
     type: string
     example: cus_01G2SG30J8C85S4A5CHM2S1NS2
   customer:
-    description: A customer object. Available if the relation `customer` is expanded.
+    description: The details of the customer that this notification was sent to.
+    x-expandable: customer
     nullable: true
     $ref: ./Customer.yaml
   to:
     description: >-
       The address that the Notification was sent to. This will usually be an
-      email address, but represent other addresses such as a chat bot user id
+      email address, but can represent other addresses such as a chat bot user
+      ID.
     type: string
     example: user@example.com
   data:
@@ -62,23 +63,24 @@ properties:
     type: string
     example: noti_01G53V9Y6CKMCGBM1P0X7C28RX
   parent_notification:
-    description: Available if the relation `parent_notification` is expanded.
+    description: The details of the parent notification.
+    x-expandable: parent_notification
     nullable: true
     type: object
   resends:
-    description: >-
-      The resends that have been completed after the original Notification.
-      Available if the relation `resends` is expanded.
+    description: The details of all resends of the notification.
     type: array
+    x-expandable: resends
     items:
       type: object
   provider_id:
-    description: The id of the Notification Provider that handles the Notification.
+    description: The ID of the notification provider used to send the notification.
     nullable: true
     type: string
     example: sengrid
   provider:
-    description: Available if the relation `provider` is expanded.
+    description: The notification provider used to send the notification.
+    x-expandable: provider
     nullable: true
     $ref: ./NotificationProvider.yaml
   created_at:
diff --git a/docs/api/store/components/schemas/NotificationProvider.yaml b/docs/api/store/components/schemas/NotificationProvider.yaml
index 71bc9d5f96..d2d2e53288 100644
--- a/docs/api/store/components/schemas/NotificationProvider.yaml
+++ b/docs/api/store/components/schemas/NotificationProvider.yaml
@@ -1,18 +1,21 @@
 title: Notification Provider
-description: Represents a notification provider plugin and holds its installation status.
+description: >-
+  A notification provider represents a notification service installed in the
+  Medusa backend, either through a plugin or backend customizations. It holds
+  the notification service's installation status.
 type: object
 required:
   - id
   - is_installed
 properties:
   id:
-    description: The id of the notification provider as given by the plugin.
+    description: The ID of the notification provider as given by the notification service.
     type: string
     example: sendgrid
   is_installed:
     description: >-
-      Whether the plugin is installed in the current version. Plugins that are
-      no longer installed are not deleted by will have this field set to
-      `false`.
+      Whether the notification service is installed in the current version. If a
+      notification service is no longer installed, the `is_installed` attribute
+      is set to `false`.
     type: boolean
     default: true
diff --git a/docs/api/store/components/schemas/OAuth.yaml b/docs/api/store/components/schemas/OAuth.yaml
index 36df175455..b1ca6bf402 100644
--- a/docs/api/store/components/schemas/OAuth.yaml
+++ b/docs/api/store/components/schemas/OAuth.yaml
@@ -1,5 +1,7 @@
 title: OAuth
-description: Represent an OAuth app
+description: >-
+  An Oauth app is typically created by a plugin to handle authentication to
+  third-party services.
 type: object
 required:
   - application_name
diff --git a/docs/api/store/components/schemas/Order.yaml b/docs/api/store/components/schemas/Order.yaml
index 1051ad1ea6..a734894904 100644
--- a/docs/api/store/components/schemas/Order.yaml
+++ b/docs/api/store/components/schemas/Order.yaml
@@ -1,5 +1,8 @@
 title: Order
-description: Represents an order
+description: >-
+  An order is a purchase made by a customer. It holds details about payment and
+  fulfillment of the order. An order may also be created from a draft order,
+  which is created by an admin user.
 type: object
 required:
   - billing_address_id
@@ -75,7 +78,8 @@ properties:
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart associated with the order.
+    x-expandable: cart
     nullable: true
     type: object
   customer_id:
@@ -83,7 +87,8 @@ properties:
     type: string
     example: cus_01G2SG30J8C85S4A5CHM2S1NS2
   customer:
-    description: A customer object. Available if the relation `customer` is expanded.
+    description: The details of the customer associated with the order.
+    x-expandable: customer
     nullable: true
     type: object
   email:
@@ -96,7 +101,8 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   billing_address:
-    description: Available if the relation `billing_address` is expanded.
+    description: The details of the billing address associated with the order.
+    x-expandable: billing_address
     nullable: true
     $ref: ./Address.yaml
   shipping_address_id:
@@ -105,15 +111,17 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   shipping_address:
-    description: Available if the relation `shipping_address` is expanded.
+    description: The details of the shipping address associated with the order.
+    x-expandable: shipping_address
     nullable: true
     $ref: ./Address.yaml
   region_id:
-    description: The region's ID
+    description: The ID of the region this order was created in.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region this order was created in.
+    x-expandable: region
     nullable: true
     $ref: ./Region.yaml
   currency_code:
@@ -124,7 +132,8 @@ properties:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency used in the order.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   tax_rate:
@@ -133,96 +142,85 @@ properties:
     type: number
     example: 0
   discounts:
-    description: >-
-      The discounts used in the order. Available if the relation `discounts` is
-      expanded.
+    description: The details of the discounts applied on the order.
     type: array
+    x-expandable: discounts
     items:
       $ref: ./Discount.yaml
   gift_cards:
-    description: >-
-      The gift cards used in the order. Available if the relation `gift_cards`
-      is expanded.
+    description: The details of the gift card used in the order.
     type: array
+    x-expandable: gift_cards
     items:
       $ref: ./GiftCard.yaml
   shipping_methods:
-    description: >-
-      The shipping methods used in the order. Available if the relation
-      `shipping_methods` is expanded.
+    description: The details of the shipping methods used in the order.
     type: array
+    x-expandable: shipping_methods
     items:
       $ref: ./ShippingMethod.yaml
   payments:
-    description: >-
-      The payments used in the order. Available if the relation `payments` is
-      expanded.
+    description: The details of the payments used in the order.
     type: array
+    x-expandable: payments
     items:
       type: object
   fulfillments:
-    description: >-
-      The fulfillments used in the order. Available if the relation
-      `fulfillments` is expanded.
+    description: The details of the fulfillments created for the order.
     type: array
+    x-expandable: fulfillments
     items:
       type: object
   returns:
-    description: >-
-      The returns associated with the order. Available if the relation `returns`
-      is expanded.
+    description: The details of the returns created for the order.
     type: array
+    x-expandable: returns
     items:
       type: object
   claims:
-    description: >-
-      The claims associated with the order. Available if the relation `claims`
-      is expanded.
+    description: The details of the claims created for the order.
     type: array
+    x-expandable: claims
     items:
       type: object
   refunds:
-    description: >-
-      The refunds associated with the order. Available if the relation `refunds`
-      is expanded.
+    description: The details of the refunds created for the order.
     type: array
+    x-expandable: refunds
     items:
       type: object
   swaps:
-    description: >-
-      The swaps associated with the order. Available if the relation `swaps` is
-      expanded.
+    description: The details of the swaps created for the order.
     type: array
+    x-expandable: swaps
     items:
       type: object
   draft_order_id:
-    description: The ID of the draft order this order is associated with.
+    description: The ID of the draft order this order was created from.
     nullable: true
     type: string
     example: null
   draft_order:
-    description: A draft order object. Available if the relation `draft_order` is expanded.
+    description: The details of the draft order this order was created from.
+    x-expandable: draft_order
     nullable: true
     type: object
   items:
-    description: >-
-      The line items that belong to the order. Available if the relation `items`
-      is expanded.
+    description: The details of the line items that belong to the order.
+    x-expandable: items
     type: array
     items:
       $ref: ./LineItem.yaml
   edits:
-    description: >-
-      Order edits done on the order. Available if the relation `edits` is
-      expanded.
+    description: The details of the order edits done on the order.
     type: array
+    x-expandable: edits
     items:
       type: object
   gift_card_transactions:
-    description: >-
-      The gift card transactions used in the order. Available if the relation
-      `gift_card_transactions` is expanded.
+    description: The gift card transactions made in the order.
     type: array
+    x-expandable: gift_card_transactions
     items:
       $ref: ./GiftCardTransaction.yaml
   canceled_at:
@@ -252,14 +250,13 @@ properties:
     type: string
     example: null
   sales_channel_id:
-    description: The ID of the sales channel this order is associated with.
+    description: The ID of the sales channel this order belongs to.
     nullable: true
     type: string
     example: null
   sales_channel:
-    description: >-
-      A sales channel object. Available if the relation `sales_channel` is
-      expanded.
+    description: The details of the sales channel this order belongs to.
+    x-expandable: sales_channel
     nullable: true
     $ref: ./SalesChannel.yaml
   shipping_total:
@@ -308,9 +305,10 @@ properties:
     example: 0
   returnable_items:
     description: >-
-      The items that are returnable as part of the order, order swaps or order
-      claims
+      The details of the line items that are returnable as part of the order,
+      swaps, or claims
     type: array
+    x-expandable: returnable_items
     items:
       $ref: ./LineItem.yaml
   created_at:
@@ -327,3 +325,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/OrderEdit.yaml b/docs/api/store/components/schemas/OrderEdit.yaml
index c6b72efad7..27f1077bdb 100644
--- a/docs/api/store/components/schemas/OrderEdit.yaml
+++ b/docs/api/store/components/schemas/OrderEdit.yaml
@@ -1,5 +1,8 @@
 title: Order Edit
-description: Order edit keeps track of order items changes.
+description: >-
+  Order edit allows modifying items in an order, such as adding, updating, or
+  deleting items from the original order. Once the order edit is confirmed, the
+  changes are reflected on the original order.
 type: object
 required:
   - canceled_at
@@ -29,11 +32,13 @@ properties:
     type: string
     example: order_01G2SG30J8C85S4A5CHM2S1NS2
   order:
-    description: Available if the relation `order` is expanded.
+    description: The details of the order that this order edit was created for.
+    x-expandable: order
     nullable: true
     type: object
   changes:
-    description: Available if the relation `changes` is expanded.
+    description: The details of all the changes on the original order's line items.
+    x-expandable: changes
     type: array
     items:
       $ref: ./OrderItemChange.yaml
@@ -135,8 +140,12 @@ properties:
       - created
       - canceled
   items:
-    description: Available if the relation `items` is expanded.
+    description: >-
+      The details of the cloned items from the original order with the new
+      changes. Once the order edit is confirmed, these line items are associated
+      with the original order.
     type: array
+    x-expandable: items
     items:
       $ref: ./LineItem.yaml
   payment_collection_id:
@@ -145,7 +154,10 @@ properties:
     type: string
     example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK
   payment_collection:
-    description: Available if the relation `payment_collection` is expanded.
+    description: >-
+      The details of the payment collection used to authorize additional payment
+      if necessary.
+    x-expandable: payment_collection
     nullable: true
     $ref: ./PaymentCollection.yaml
   created_at:
diff --git a/docs/api/store/components/schemas/OrderItemChange.yaml b/docs/api/store/components/schemas/OrderItemChange.yaml
index 31a0435da5..a1cbe55425 100644
--- a/docs/api/store/components/schemas/OrderItemChange.yaml
+++ b/docs/api/store/components/schemas/OrderItemChange.yaml
@@ -1,5 +1,8 @@
 title: Order Item Change
-description: Represents an order edit item change
+description: >-
+  An order item change is a change made within an order edit to an order's
+  items. These changes are not reflected on the original order until the order
+  edit is confirmed.
 type: object
 required:
   - created_at
@@ -27,7 +30,8 @@ properties:
     type: string
     example: oe_01G2SG30J8C85S4A5CHM2S1NS2
   order_edit:
-    description: Available if the relation `order_edit` is expanded.
+    description: The details of the order edit the item change is associated with.
+    x-expandable: order_edit
     nullable: true
     type: object
   original_line_item_id:
@@ -36,7 +40,10 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   original_line_item:
-    description: Available if the relation `original_line_item` is expanded.
+    description: >-
+      The details of the original line item this item change references. This is
+      used if the item change updates or deletes the original item.
+    x-expandable: original_line_item
     nullable: true
     $ref: ./LineItem.yaml
   line_item_id:
@@ -45,7 +52,10 @@ properties:
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   line_item:
-    description: Available if the relation `line_item` is expanded.
+    description: >-
+      The details of the resulting line item after the item change. This line
+      item is then used in the original order once the order edit is confirmed.
+    x-expandable: line_item
     nullable: true
     $ref: ./LineItem.yaml
   created_at:
diff --git a/docs/api/store/components/schemas/Payment.yaml b/docs/api/store/components/schemas/Payment.yaml
index 6f9d0d69a2..cf84c788ad 100644
--- a/docs/api/store/components/schemas/Payment.yaml
+++ b/docs/api/store/components/schemas/Payment.yaml
@@ -1,7 +1,9 @@
 title: Payment
 description: >-
-  Payments represent an amount authorized with a given payment method, Payments
-  can be captured, canceled or refunded.
+  A payment is originally created from a payment session. Once a payment session
+  is authorized, the payment is created to represent the authorized amount with
+  a given payment method. Payments can be captured, canceled or refunded.
+  Payments can be made towards orders, swaps, order edits, or other resources.
 type: object
 required:
   - amount
@@ -25,29 +27,36 @@ properties:
     type: string
     example: pay_01G2SJNT6DEEWDFNAJ4XWDTHKE
   swap_id:
-    description: The ID of the Swap that the Payment is used for.
+    description: The ID of the swap that this payment was potentially created for.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that this payment was potentially created for.
+    x-expandable: swap
     nullable: true
     type: object
   cart_id:
-    description: The id of the Cart that the Payment Session is created for.
+    description: The ID of the cart that the payment session was potentially created for.
     nullable: true
     type: string
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: >-
+      The details of the cart that the payment session was potentially created
+      for.
+    x-expandable: cart
     nullable: true
     type: object
   order_id:
-    description: The ID of the Order that the Payment is used for.
+    description: The ID of the order that the payment session was potentially created for.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: >-
+      The details of the order that the payment session was potentially created
+      for.
+    x-expandable: order
     nullable: true
     type: object
   amount:
@@ -55,14 +64,15 @@ properties:
     type: integer
     example: 100
   currency_code:
-    description: The 3 character ISO currency code that the Payment is completed in.
+    description: The 3 character ISO currency code of the payment.
     type: string
     example: usd
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency of the payment.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   amount_refunded:
@@ -117,3 +127,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/PaymentCollection.yaml b/docs/api/store/components/schemas/PaymentCollection.yaml
index 83db018a75..c41fe34593 100644
--- a/docs/api/store/components/schemas/PaymentCollection.yaml
+++ b/docs/api/store/components/schemas/PaymentCollection.yaml
@@ -1,5 +1,8 @@
 title: Payment Collection
-description: Payment Collection
+description: >-
+  A payment collection allows grouping and managing a list of payments at one.
+  This can be helpful when making additional payment for order edits or
+  integrating installment payments.
 type: object
 required:
   - amount
@@ -46,32 +49,40 @@ properties:
     nullable: true
     type: integer
   region_id:
-    description: The region's ID
+    description: The ID of the region this payment collection is associated with.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: Available if the relation `region` is expanded.
+    description: The details of the region this payment collection is associated with.
+    x-expandable: region
     nullable: true
     $ref: ./Region.yaml
   currency_code:
-    description: The 3 character ISO code for the currency.
+    description: >-
+      The 3 character ISO code for the currency this payment collection is
+      associated with.
     type: string
     example: usd
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency this payment collection is associated with.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   payment_sessions:
-    description: Available if the relation `payment_sessions` is expanded.
+    description: >-
+      The details of the payment sessions created as part of the payment
+      collection.
     type: array
+    x-expandable: payment_sessions
     items:
       $ref: ./PaymentSession.yaml
   payments:
-    description: Available if the relation `payments` is expanded.
+    description: The details of the payments created as part of the payment collection.
     type: array
+    x-expandable: payments
     items:
       $ref: ./Payment.yaml
   created_by:
@@ -96,3 +107,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/PaymentProvider.yaml b/docs/api/store/components/schemas/PaymentProvider.yaml
index ae7eaecb49..4a54a90729 100644
--- a/docs/api/store/components/schemas/PaymentProvider.yaml
+++ b/docs/api/store/components/schemas/PaymentProvider.yaml
@@ -1,18 +1,21 @@
 title: Payment Provider
-description: Represents a Payment Provider plugin and holds its installation status.
+description: >-
+  A payment provider represents a payment service installed in the Medusa
+  backend, either through a plugin or backend customizations. It holds the
+  payment service's installation status.
 type: object
 required:
   - id
   - is_installed
 properties:
   id:
-    description: The id of the payment provider as given by the plugin.
+    description: The ID of the payment provider as given by the payment service.
     type: string
     example: manual
   is_installed:
     description: >-
-      Whether the plugin is installed in the current version. Plugins that are
-      no longer installed are not deleted by will have this field set to
-      `false`.
+      Whether the payment service is installed in the current version. If a
+      payment service is no longer installed, the `is_installed` attribute is
+      set to `false`.
     type: boolean
     default: true
diff --git a/docs/api/store/components/schemas/PaymentSession.yaml b/docs/api/store/components/schemas/PaymentSession.yaml
index f49ce46db4..ccf7cbcda8 100644
--- a/docs/api/store/components/schemas/PaymentSession.yaml
+++ b/docs/api/store/components/schemas/PaymentSession.yaml
@@ -1,11 +1,12 @@
 title: Payment Session
 description: >-
-  Payment Sessions are created when a Customer initilizes the checkout flow, and
+  A Payment Session is created when a Customer initilizes the checkout flow, and
   can be used to hold the state of a payment flow. Each Payment Session is
-  controlled by a Payment Provider, who is responsible for the communication
+  controlled by a Payment Provider, which is responsible for the communication
   with external payment services. Authorized Payment Sessions will eventually
-  get promoted to Payments to indicate that they are authorized for
-  capture/refunds/etc.
+  get promoted to Payments to indicate that they are authorized for payment
+  processing such as capture or refund. Payment sessions can also be used as
+  part of payment collections.
 type: object
 required:
   - amount
@@ -26,16 +27,17 @@ properties:
     type: string
     example: ps_01G901XNSRM2YS3ASN9H5KG3FZ
   cart_id:
-    description: The id of the Cart that the Payment Session is created for.
+    description: The ID of the cart that the payment session was created for.
     nullable: true
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart that the payment session was created for.
+    x-expandable: cart
     nullable: true
     $ref: ./Cart.yaml
   provider_id:
-    description: The id of the Payment Provider that is responsible for the Payment Session
+    description: The ID of the Payment Provider that is responsible for the Payment Session
     type: string
     example: manual
   is_selected:
diff --git a/docs/api/store/components/schemas/PriceList.yaml b/docs/api/store/components/schemas/PriceList.yaml
index ef84ed5cb5..cb1f79566a 100644
--- a/docs/api/store/components/schemas/PriceList.yaml
+++ b/docs/api/store/components/schemas/PriceList.yaml
@@ -1,6 +1,6 @@
 title: Price List
 description: >-
-  Price Lists represents a set of prices that overrides the default price for
+  A Price List represents a set of prices that override the default price for
   one or more product variants.
 type: object
 required:
@@ -52,22 +52,21 @@ properties:
     type: string
     format: date-time
   customer_groups:
-    description: >-
-      The Customer Groups that the Price List applies to. Available if the
-      relation `customer_groups` is expanded.
+    description: The details of the customer groups that the Price List can apply to.
     type: array
+    x-expandable: customer_groups
     items:
       $ref: ./CustomerGroup.yaml
   prices:
-    description: >-
-      The Money Amounts that are associated with the Price List. Available if
-      the relation `prices` is expanded.
+    description: The prices that belong to the price list, represented as a Money Amount.
     type: array
+    x-expandable: prices
     items:
       $ref: ./MoneyAmount.yaml
   includes_tax:
-    description: '[EXPERIMENTAL] Does the price list prices include tax'
+    description: Whether the price list prices include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
   created_at:
     description: The date with timezone at which the resource was created.
diff --git a/docs/api/store/components/schemas/Product.yaml b/docs/api/store/components/schemas/Product.yaml
index 94a80dd483..d0f98a63f1 100644
--- a/docs/api/store/components/schemas/Product.yaml
+++ b/docs/api/store/components/schemas/Product.yaml
@@ -1,8 +1,10 @@
 title: Product
 description: >-
-  Products are a grouping of Product Variants that have common properties such
-  as images and descriptions. Products can have multiple options which define
-  the properties that Product Variants differ by.
+  A product is a saleable item that holds general information such as name or
+  description. It must include at least one Product Variant, where each product
+  variant defines different options to purchase the product with (for example,
+  different sizes or colors). The prices and inventory of the product are
+  defined on the variant level.
 type: object
 required:
   - collection_id
@@ -70,8 +72,9 @@ properties:
       - rejected
     default: draft
   images:
-    description: Images of the Product. Available if the relation `images` is expanded.
+    description: The details of the product's images.
     type: array
+    x-expandable: images
     items:
       $ref: ./Image.yaml
   thumbnail:
@@ -81,38 +84,49 @@ properties:
     format: uri
   options:
     description: >-
-      The Product Options that are defined for the Product. Product Variants of
-      the Product will have a unique combination of Product Option Values.
-      Available if the relation `options` is expanded.
+      The details of the Product Options that are defined for the Product. The
+      product's variants will have a unique combination of values of the
+      product's options.
     type: array
+    x-expandable: options
     items:
       $ref: ./ProductOption.yaml
   variants:
     description: >-
-      The Product Variants that belong to the Product. Each will have a unique
-      combination of Product Option Values. Available if the relation `variants`
-      is expanded.
+      The details of the Product Variants that belong to the Product. Each will
+      have a unique combination of values of the product's options.
     type: array
+    x-expandable: variants
     items:
       $ref: ./ProductVariant.yaml
   categories:
-    description: >-
-      The product's associated categories. Available if the relation
-      `categories` are expanded.
+    description: The details of the product categories that this product belongs to.
     type: array
+    x-expandable: categories
+    x-featureFlag: product_categories
     items:
       $ref: ./ProductCategory.yaml
   profile_id:
     description: >-
-      The ID of the Shipping Profile that the Product belongs to. Shipping
-      Profiles have a set of defined Shipping Options that can be used to
-      Fulfill a given set of Products.
+      The ID of the shipping profile that the product belongs to. The shipping
+      profile has a set of defined shipping options that can be used to fulfill
+      the product.
     type: string
     example: sp_01G1G5V239ENSZ5MV4JAR737BM
   profile:
-    description: Available if the relation `profile` is expanded.
+    description: >-
+      The details of the shipping profile that the product belongs to. The
+      shipping profile has a set of defined shipping options that can be used to
+      fulfill the product.
+    x-expandable: profile
     nullable: true
     $ref: ./ShippingProfile.yaml
+  profiles:
+    description: Available if the relation `profiles` is expanded.
+    nullable: true
+    type: array
+    items:
+      $ref: ./ShippingProfile.yaml
   weight:
     description: >-
       The weight of the Product Variant. May be used in shipping rate
@@ -172,30 +186,29 @@ properties:
     type: string
     example: null
   collection_id:
-    description: The Product Collection that the Product belongs to
+    description: The ID of the product collection that the product belongs to.
     nullable: true
     type: string
     example: pcol_01F0YESBFAZ0DV6V831JXWH0BG
   collection:
-    description: >-
-      A product collection object. Available if the relation `collection` is
-      expanded.
+    description: The details of the product collection that the product belongs to.
+    x-expandable: collection
     nullable: true
     $ref: ./ProductCollection.yaml
   type_id:
-    description: The Product type that the Product belongs to
+    description: The ID of the product type that the product belongs to.
     nullable: true
     type: string
     example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
   type:
-    description: Available if the relation `type` is expanded.
+    description: The details of the product type that the product belongs to.
+    x-expandable: type
     nullable: true
     $ref: ./ProductType.yaml
   tags:
-    description: >-
-      The Product Tags assigned to the Product. Available if the relation `tags`
-      is expanded.
+    description: The details of the product tags used in this product.
     type: array
+    x-expandable: type
     items:
       $ref: ./ProductTag.yaml
   discountable:
@@ -210,10 +223,9 @@ properties:
     type: string
     example: null
   sales_channels:
-    description: >-
-      The sales channels the product is associated with. Available if the
-      relation `sales_channels` is expanded.
+    description: The details of the sales channels this product is available in.
     type: array
+    x-expandable: sales_channels
     items:
       $ref: ./SalesChannel.yaml
   created_at:
@@ -235,3 +247,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ProductCategory.yaml b/docs/api/store/components/schemas/ProductCategory.yaml
index 3dfe3b8ca6..b4acd30f4e 100644
--- a/docs/api/store/components/schemas/ProductCategory.yaml
+++ b/docs/api/store/components/schemas/ProductCategory.yaml
@@ -1,6 +1,9 @@
-title: ProductCategory
-description: Represents a product category
+title: Product Category
+description: >-
+  A product category can be used to categorize products into a hierarchy of
+  categories.
 x-resourceId: ProductCategory
+x-featureFlag: product_categories
 type: object
 required:
   - category_children
@@ -48,8 +51,9 @@ properties:
     description: An integer that depicts the rank of category in a tree node
     default: 0
   category_children:
-    description: Available if the relation `category_children` are expanded.
+    description: The details of the category's children.
     type: array
+    x-expandable: category_children
     items:
       type: object
   parent_category_id:
@@ -58,16 +62,14 @@ properties:
     type: string
     default: null
   parent_category:
-    description: >-
-      A product category object. Available if the relation `parent_category` is
-      expanded.
+    description: The details of the parent of this category.
+    x-expandable: parent_category
     nullable: true
     type: object
   products:
-    description: >-
-      Products associated with category. Available if the relation `products` is
-      expanded.
+    description: The details of the products that belong to this category.
     type: array
+    x-expandable: products
     items:
       type: object
   created_at:
diff --git a/docs/api/store/components/schemas/ProductCollection.yaml b/docs/api/store/components/schemas/ProductCollection.yaml
index f53db55c2d..82b6fbcca8 100644
--- a/docs/api/store/components/schemas/ProductCollection.yaml
+++ b/docs/api/store/components/schemas/ProductCollection.yaml
@@ -1,5 +1,8 @@
 title: Product Collection
-description: Product Collections represents a group of Products that are related.
+description: >-
+  A Product Collection allows grouping together products for promotional
+  purposes. For example, an admin can create a Summer collection, add products
+  to it, and showcase it on the storefront.
 type: object
 required:
   - created_at
@@ -26,10 +29,9 @@ properties:
     type: string
     example: summer-collection
   products:
-    description: >-
-      The Products contained in the Product Collection. Available if the
-      relation `products` is expanded.
+    description: The details of the products that belong to this product collection.
     type: array
+    x-expandable: products
     items:
       type: object
   created_at:
@@ -51,3 +53,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ProductOption.yaml b/docs/api/store/components/schemas/ProductOption.yaml
index 3de3f509d9..6e2d829a9e 100644
--- a/docs/api/store/components/schemas/ProductOption.yaml
+++ b/docs/api/store/components/schemas/ProductOption.yaml
@@ -1,8 +1,8 @@
 title: Product Option
 description: >-
-  Product Options define properties that may vary between different variants of
-  a Product. Common Product Options are "Size" and "Color", but Medusa doesn't
-  limit what Product Options that can be defined.
+  A Product Option defines properties that may vary between different variants
+  of a Product. Common Product Options are "Size" and "Color". Admins are free
+  to create any product options.
 type: object
 required:
   - created_at
@@ -22,18 +22,18 @@ properties:
     type: string
     example: Size
   values:
-    description: >-
-      The Product Option Values that are defined for the Product Option.
-      Available if the relation `values` is expanded.
+    description: The details of the values of the product option.
     type: array
+    x-expandable: values
     items:
       $ref: ./ProductOptionValue.yaml
   product_id:
-    description: The ID of the Product that the Product Option is defined for.
+    description: The ID of the product that this product option belongs to.
     type: string
     example: prod_01G1G5V2MBA328390B5AXJ610F
   product:
-    description: A product object. Available if the relation `product` is expanded.
+    description: The details of the product that this product option belongs to.
+    x-expandable: product
     nullable: true
     type: object
   created_at:
@@ -55,3 +55,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ProductOptionValue.yaml b/docs/api/store/components/schemas/ProductOptionValue.yaml
index b247b13506..af9257805c 100644
--- a/docs/api/store/components/schemas/ProductOptionValue.yaml
+++ b/docs/api/store/components/schemas/ProductOptionValue.yaml
@@ -1,7 +1,7 @@
 title: Product Option Value
 description: >-
-  A value given to a Product Variant's option set. Product Variant have a
-  Product Option Value for each of the Product Options defined on the Product.
+  An option value is one of the possible values of a Product Option. Product
+  Variants specify a unique combination of product option values.
 type: object
 required:
   - created_at
@@ -20,26 +20,28 @@ properties:
   value:
     description: >-
       The value that the Product Variant has defined for the specific Product
-      Option (e.g. if the Product Option is \"Size\" this value could be
-      `Small`, `Medium` or `Large`).
+      Option (e.g. if the Product Option is "Size" this value could be `Small`,
+      `Medium` or `Large`).
     type: string
     example: large
   option_id:
-    description: The ID of the Product Option that the Product Option Value is defined for.
+    description: The ID of the Product Option that the Product Option Value belongs to.
     type: string
     example: opt_01F0YESHQBZVKCEXJ24BS6PCX3
   option:
-    description: Available if the relation `option` is expanded.
+    description: >-
+      The details of the product option that the Product Option Value belongs
+      to.
+    x-expandable: option
     nullable: true
     type: object
   variant_id:
-    description: >-
-      The ID of the Product Variant that the Product Option Value is defined
-      for.
+    description: The ID of the product variant that uses this product option value.
     type: string
     example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
   variant:
-    description: Available if the relation `variant` is expanded.
+    description: The details of the product variant that uses this product option value.
+    x-expandable: variant
     nullable: true
     type: object
   created_at:
@@ -61,3 +63,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ProductTag.yaml b/docs/api/store/components/schemas/ProductTag.yaml
index 7faa4a2c1b..829162f285 100644
--- a/docs/api/store/components/schemas/ProductTag.yaml
+++ b/docs/api/store/components/schemas/ProductTag.yaml
@@ -1,5 +1,5 @@
 title: Product Tag
-description: Product Tags can be added to Products for easy filtering and grouping.
+description: A Product Tag can be added to Products for easy filtering and grouping.
 type: object
 required:
   - created_at
@@ -36,3 +36,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ProductTaxRate.yaml b/docs/api/store/components/schemas/ProductTaxRate.yaml
index d92b163428..55292d8e33 100644
--- a/docs/api/store/components/schemas/ProductTaxRate.yaml
+++ b/docs/api/store/components/schemas/ProductTaxRate.yaml
@@ -1,7 +1,7 @@
 title: Product Tax Rate
 description: >-
-  Associates a tax rate with a product to indicate that the product is taxed in
-  a certain way
+  This represents the association between a tax rate and a product to indicate
+  that the product is taxed in a way different than the default.
 type: object
 required:
   - created_at
@@ -15,7 +15,8 @@ properties:
     type: string
     example: prod_01G1G5V2MBA328390B5AXJ610F
   product:
-    description: Available if the relation `product` is expanded.
+    description: The details of the product.
+    x-expandable: product
     nullable: true
     $ref: ./Product.yaml
   rate_id:
@@ -23,7 +24,8 @@ properties:
     type: string
     example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
   tax_rate:
-    description: Available if the relation `tax_rate` is expanded.
+    description: The details of the tax rate.
+    x-expandable: tax_rate
     nullable: true
     $ref: ./TaxRate.yaml
   created_at:
@@ -40,3 +42,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ProductType.yaml b/docs/api/store/components/schemas/ProductType.yaml
index 579e7a6fb4..dbdc684090 100644
--- a/docs/api/store/components/schemas/ProductType.yaml
+++ b/docs/api/store/components/schemas/ProductType.yaml
@@ -1,5 +1,5 @@
 title: Product Type
-description: Product Type can be added to Products for filtering and reporting purposes.
+description: A Product Type can be added to Products for filtering and reporting purposes.
 type: object
 required:
   - created_at
@@ -36,3 +36,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ProductTypeTaxRate.yaml b/docs/api/store/components/schemas/ProductTypeTaxRate.yaml
index 4539a32fc5..3c641ab1fe 100644
--- a/docs/api/store/components/schemas/ProductTypeTaxRate.yaml
+++ b/docs/api/store/components/schemas/ProductTypeTaxRate.yaml
@@ -1,7 +1,7 @@
 title: Product Type Tax Rate
 description: >-
-  Associates a tax rate with a product type to indicate that the product type is
-  taxed in a certain way
+  This represents the association between a tax rate and a product type to
+  indicate that the product type is taxed in a different way than the default.
 type: object
 required:
   - created_at
@@ -15,7 +15,8 @@ properties:
     type: string
     example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
   product_type:
-    description: Available if the relation `product_type` is expanded.
+    description: The details of the product type.
+    x-expandable: product_type
     nullable: true
     $ref: ./ProductType.yaml
   rate_id:
@@ -23,7 +24,8 @@ properties:
     type: string
     example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
   tax_rate:
-    description: Available if the relation `tax_rate` is expanded.
+    description: The details of the tax rate.
+    x-expandable: tax_rate
     nullable: true
     $ref: ./TaxRate.yaml
   created_at:
@@ -40,3 +42,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ProductVariant.yaml b/docs/api/store/components/schemas/ProductVariant.yaml
index fe8a168efc..ab1eff0624 100644
--- a/docs/api/store/components/schemas/ProductVariant.yaml
+++ b/docs/api/store/components/schemas/ProductVariant.yaml
@@ -1,8 +1,9 @@
 title: Product Variant
 description: >-
-  Product Variants represent a Product with a specific set of Product Option
+  A Product Variant represents a Product with a specific set of Product Option
   configurations. The maximum number of Product Variants that a Product can have
-  is given by the number of available Product Option combinations.
+  is given by the number of available Product Option combinations. A product
+  must at least have one product variant.
 type: object
 required:
   - allow_backorder
@@ -39,19 +40,21 @@ properties:
     type: string
     example: Small
   product_id:
-    description: The ID of the Product that the Product Variant belongs to.
+    description: The ID of the product that the product variant belongs to.
     type: string
     example: prod_01G1G5V2MBA328390B5AXJ610F
   product:
-    description: A product object. Available if the relation `product` is expanded.
+    description: The details of the product that the product variant belongs to.
+    x-expandable: product
     nullable: true
     type: object
   prices:
     description: >-
-      The Money Amounts defined for the Product Variant. Each Money Amount
-      represents a price in a given currency or a price in a specific Region.
-      Available if the relation `prices` is expanded.
+      The details of the prices of the Product Variant, each represented as a
+      Money Amount. Each Money Amount represents a price in a given currency or
+      a specific Region.
     type: array
+    x-expandable: prices
     items:
       $ref: ./MoneyAmount.yaml
   sku:
@@ -158,16 +161,16 @@ properties:
     example: null
   options:
     description: >-
-      The Product Option Values specified for the Product Variant. Available if
-      the relation `options` is expanded.
+      The details of the product options that this product variant defines
+      values for.
     type: array
+    x-expandable: options
     items:
       $ref: ./ProductOptionValue.yaml
   inventory_items:
-    description: >-
-      The Inventory Items related to the product variant. Available if the
-      relation `inventory_items` is expanded.
+    description: The details inventory items of the product variant.
     type: array
+    x-expandable: inventory_items
     items:
       $ref: ./ProductVariantInventoryItem.yaml
   created_at:
@@ -189,6 +192,10 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
   purchasable:
     description: |
       Only used with the inventory modules.
diff --git a/docs/api/store/components/schemas/ProductVariantInventoryItem.yaml b/docs/api/store/components/schemas/ProductVariantInventoryItem.yaml
index d2f658ecfb..2da5bc3821 100644
--- a/docs/api/store/components/schemas/ProductVariantInventoryItem.yaml
+++ b/docs/api/store/components/schemas/ProductVariantInventoryItem.yaml
@@ -1,7 +1,7 @@
 title: Product Variant Inventory Item
 description: >-
-  Product Variant Inventory Items link variants with inventory items and denote
-  the number of inventory items constituting a variant.
+  A Product Variant Inventory Item links variants with inventory items and
+  denotes the required quantity of the variant.
 type: object
 required:
   - created_at
@@ -23,13 +23,12 @@ properties:
     description: The id of the variant.
     type: string
   variant:
-    description: A ProductVariant object. Available if the relation `variant` is expanded.
+    description: The details of the product variant.
+    x-expandable: variant
     nullable: true
     type: object
   required_quantity:
-    description: >-
-      The quantity of an inventory item required for one quantity of the
-      variant.
+    description: The quantity of an inventory item required for the variant.
     type: integer
     default: 1
   created_at:
diff --git a/docs/api/store/components/schemas/PublishableApiKey.yaml b/docs/api/store/components/schemas/PublishableApiKey.yaml
index dffb94d446..d94df58632 100644
--- a/docs/api/store/components/schemas/PublishableApiKey.yaml
+++ b/docs/api/store/components/schemas/PublishableApiKey.yaml
@@ -1,7 +1,12 @@
 title: Publishable API key
 description: >-
-  Publishable API key defines scopes (i.e. resources) that are available within
-  a request.
+  A Publishable API key defines scopes that resources are available in. Then, it
+  can be used in request to infer the resources without having to directly pass
+  them. For example, a publishable API key can be associated with one or more
+  sales channels. Then, when the publishable API key is passed in the header of
+  a request, it is inferred what sales channel is being used without having to
+  pass the sales channel as a query or body parameter of the request.
+  Publishable API keys can only be used with sales channels, at the moment.
 type: object
 required:
   - created_at
diff --git a/docs/api/store/components/schemas/PublishableApiKeySalesChannel.yaml b/docs/api/store/components/schemas/PublishableApiKeySalesChannel.yaml
index ac6c018ad7..a79fecafa9 100644
--- a/docs/api/store/components/schemas/PublishableApiKeySalesChannel.yaml
+++ b/docs/api/store/components/schemas/PublishableApiKeySalesChannel.yaml
@@ -1,5 +1,7 @@
-title: Publishable API key sales channel
-description: Holds mapping between Publishable API keys and Sales Channels
+title: Publishable API Key Sales Channel
+description: >-
+  This represents the association between the Publishable API keys and Sales
+  Channels
 type: object
 required:
   - publishable_key_id
diff --git a/docs/api/store/components/schemas/Refund.yaml b/docs/api/store/components/schemas/Refund.yaml
index 48ab1bfe12..0438bfe295 100644
--- a/docs/api/store/components/schemas/Refund.yaml
+++ b/docs/api/store/components/schemas/Refund.yaml
@@ -1,8 +1,8 @@
 title: Refund
 description: >-
-  Refund represent an amount of money transfered back to the Customer for a
+  A refund represents an amount of money transfered back to the customer for a
   given reason. Refunds may occur in relation to Returns, Swaps and Claims, but
-  can also be initiated by a store operator.
+  can also be initiated by an admin for an order.
 type: object
 required:
   - amount
@@ -21,21 +21,23 @@ properties:
     type: string
     example: ref_01G1G5V27GYX4QXNARRQCW1N8T
   order_id:
-    description: The id of the Order that the Refund is related to.
+    description: The ID of the order this refund was created for.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order this refund was created for.
+    x-expandable: order
     nullable: true
     type: object
   payment_id:
-    description: The payment's ID if available
+    description: The payment's ID, if available.
     nullable: true
     type: string
     example: pay_01G8ZCC5W42ZNY842124G7P5R9
   payment:
-    description: Available if the relation `payment` is expanded.
+    description: The details of the payment associated with the refund.
+    x-expandable: payment
     nullable: true
     type: object
   amount:
@@ -82,3 +84,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/Region.yaml b/docs/api/store/components/schemas/Region.yaml
index a8df502e1f..2e19d39db4 100644
--- a/docs/api/store/components/schemas/Region.yaml
+++ b/docs/api/store/components/schemas/Region.yaml
@@ -1,7 +1,7 @@
 title: Region
 description: >-
-  Regions hold settings for how Customers in a given geographical location shop.
-  The is, for example, where currencies and tax rates are defined. A Region can
+  A region holds settings specific to a geographical location, including the
+  currency, tax rates, and fulfillment and payment providers. A Region can
   consist of multiple countries to accomodate common shopping settings across
   countries.
 type: object
@@ -30,14 +30,15 @@ properties:
     type: string
     example: EU
   currency_code:
-    description: The 3 character currency code that the Region uses.
+    description: The 3 character currency code used in the region.
     type: string
     example: usd
     externalDocs:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   currency:
-    description: Available if the relation `currency` is expanded.
+    description: The details of the currency used in the region.
+    x-expandable: currency
     nullable: true
     $ref: ./Currency.yaml
   tax_rate:
@@ -46,9 +47,10 @@ properties:
     example: 0
   tax_rates:
     description: >-
-      The tax rates that are included in the Region. Available if the relation
-      `tax_rates` is expanded.
+      The details of the tax rates used in the region, aside from the default
+      rate.
     type: array
+    x-expandable: tax_rates
     items:
       $ref: ./TaxRate.yaml
   tax_code:
@@ -67,10 +69,9 @@ properties:
     type: boolean
     default: true
   countries:
-    description: >-
-      The countries that are included in the Region. Available if the relation
-      `countries` is expanded.
+    description: The details of the countries included in this region.
     type: array
+    x-expandable: countries
     items:
       $ref: ./Country.yaml
   tax_provider_id:
@@ -79,26 +80,30 @@ properties:
     type: string
     example: null
   tax_provider:
-    description: Available if the relation `tax_provider` is expanded.
+    description: The details of the tax provider used in the region.
+    x-expandable: tax_provider
     nullable: true
     $ref: ./TaxProvider.yaml
   payment_providers:
     description: >-
-      The Payment Providers that can be used to process Payments in the Region.
-      Available if the relation `payment_providers` is expanded.
+      The details of the payment providers that can be used to process payments
+      in the region.
     type: array
+    x-expandable: payment_providers
     items:
       $ref: ./PaymentProvider.yaml
   fulfillment_providers:
     description: >-
-      The Fulfillment Providers that can be used to fulfill orders in the
-      Region. Available if the relation `fulfillment_providers` is expanded.
+      The details of the fulfillment providers that can be used to fulfill items
+      of orders and similar resources in the region.
     type: array
+    x-expandable: fulfillment_providers
     items:
       $ref: ./FulfillmentProvider.yaml
   includes_tax:
-    description: '[EXPERIMENTAL] Does the prices for the region include tax'
+    description: Whether the prices for the region include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
   created_at:
     description: The date with timezone at which the resource was created.
@@ -119,3 +124,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/Return.yaml b/docs/api/store/components/schemas/Return.yaml
index b2b07fc9bf..d7145a0dff 100644
--- a/docs/api/store/components/schemas/Return.yaml
+++ b/docs/api/store/components/schemas/Return.yaml
@@ -1,8 +1,8 @@
 title: Return
 description: >-
-  Return orders hold information about Line Items that a Customer wishes to send
-  back, along with how the items will be returned. Returns can be used as part
-  of a Swap.
+  A Return holds information about Line Items that a Customer wishes to send
+  back, along with how the items will be returned. Returns can also be used as
+  part of a Swap or a Claim.
 type: object
 required:
   - claim_order_id
@@ -34,44 +34,47 @@ properties:
       - canceled
     default: requested
   items:
-    description: >-
-      The Return Items that will be shipped back to the warehouse. Available if
-      the relation `items` is expanded.
+    description: The details of the items that the customer is returning.
     type: array
+    x-expandable: items
     items:
       $ref: ./ReturnItem.yaml
   swap_id:
-    description: The ID of the Swap that the Return is a part of.
+    description: The ID of the swap that the return may belong to.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that the return may belong to.
+    x-expandable: swap
     nullable: true
     type: object
   claim_order_id:
-    description: The ID of the Claim that the Return is a part of.
+    description: The ID of the claim that the return may belong to.
     nullable: true
     type: string
     example: null
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim that the return may belong to.
+    x-expandable: claim_order
     nullable: true
     type: object
   order_id:
-    description: The ID of the Order that the Return is made from.
+    description: The ID of the order that the return was created for.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the return was created for.
+    x-expandable: order
     nullable: true
     type: object
   shipping_method:
     description: >-
-      The Shipping Method that will be used to send the Return back. Can be null
-      if the Customer facilitates the return shipment themselves. Available if
-      the relation `shipping_method` is expanded.
+      The details of the Shipping Method that will be used to send the Return
+      back. Can be null if the Customer will handle the return shipment
+      themselves.
+    x-expandable: shipping_method
     nullable: true
     $ref: ./ShippingMethod.yaml
   shipping_data:
@@ -82,7 +85,7 @@ properties:
     type: object
     example: {}
   location_id:
-    description: The id of the stock location the return will be added back.
+    description: The ID of the stock location the return will be added back.
     nullable: true
     type: string
     example: sloc_01G8TJSYT9M6AVS5N4EMNFS1EK
@@ -123,3 +126,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ReturnItem.yaml b/docs/api/store/components/schemas/ReturnItem.yaml
index f2e6e78b7a..cbdf122007 100644
--- a/docs/api/store/components/schemas/ReturnItem.yaml
+++ b/docs/api/store/components/schemas/ReturnItem.yaml
@@ -1,7 +1,7 @@
 title: Return Item
 description: >-
-  Correlates a Line Item with a Return, keeping track of the quantity of the
-  Line Item that will be returned.
+  A return item represents a line item in an order that is to be returned. It
+  includes details related to the return and the reason behind it.
 type: object
 required:
   - is_requested
@@ -15,23 +15,25 @@ required:
   - return_id
 properties:
   return_id:
-    description: The id of the Return that the Return Item belongs to.
+    description: The ID of the Return that the Return Item belongs to.
     type: string
     example: ret_01F0YET7XPCMF8RZ0Y151NZV2V
   item_id:
-    description: The id of the Line Item that the Return Item references.
+    description: The ID of the Line Item that the Return Item references.
     type: string
     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
   return_order:
-    description: Available if the relation `return_order` is expanded.
+    description: Details of the Return that the Return Item belongs to.
+    x-expandable: return_order
     nullable: true
     type: object
   item:
-    description: Available if the relation `item` is expanded.
+    description: The details of the line item in the original order to be returned.
+    x-expandable: item
     nullable: true
     $ref: ./LineItem.yaml
   quantity:
-    description: The quantity of the Line Item that is included in the Return.
+    description: The quantity of the Line Item to be returned.
     type: integer
     example: 1
   is_requested:
@@ -56,7 +58,8 @@ properties:
     type: string
     example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ
   reason:
-    description: Available if the relation `reason` is expanded.
+    description: The details of the reason for returning the item.
+    x-expandable: reason
     nullable: true
     $ref: ./ReturnReason.yaml
   note:
@@ -70,3 +73,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ReturnReason.yaml b/docs/api/store/components/schemas/ReturnReason.yaml
index 37715c1fe9..28f6b23324 100644
--- a/docs/api/store/components/schemas/ReturnReason.yaml
+++ b/docs/api/store/components/schemas/ReturnReason.yaml
@@ -1,7 +1,7 @@
 title: Return Reason
 description: >-
-  A Reason for why a given product is returned. A Return Reason can be used on
-  Return Items in order to indicate why a Line Item was returned.
+  A Return Reason is a value defined by an admin. It can be used on Return Items
+  in order to indicate why a Line Item was returned.
 type: object
 required:
   - created_at
@@ -37,11 +37,13 @@ properties:
     type: string
     example: null
   parent_return_reason:
-    description: Available if the relation `parent_return_reason` is expanded.
+    description: The details of the parent reason.
+    x-expandable: parent_return_reason
     nullable: true
     type: object
   return_reason_children:
-    description: Available if the relation `return_reason_children` is expanded.
+    description: The details of the child reasons.
+    x-expandable: return_reason_children
     type: object
   created_at:
     description: The date with timezone at which the resource was created.
@@ -62,3 +64,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/SalesChannel.yaml b/docs/api/store/components/schemas/SalesChannel.yaml
index dbb40f089c..87f03d42be 100644
--- a/docs/api/store/components/schemas/SalesChannel.yaml
+++ b/docs/api/store/components/schemas/SalesChannel.yaml
@@ -1,5 +1,8 @@
 title: Sales Channel
-description: A Sales Channel
+description: >-
+  A Sales Channel is a method a business offers its products for purchase for
+  the customers. For example, a Webshop can be a sales channel, and a mobile app
+  can be another.
 type: object
 required:
   - created_at
@@ -28,10 +31,9 @@ properties:
     type: boolean
     default: false
   locations:
-    description: >-
-      The Stock Locations related to the sales channel. Available if the
-      relation `locations` is expanded.
+    description: The details of the stock locations related to the sales channel.
     type: array
+    x-expandable: locations
     items:
       $ref: ./SalesChannelLocation.yaml
   created_at:
@@ -47,3 +49,13 @@ properties:
     nullable: true
     type: string
     format: date-time
+  metadata:
+    description: An optional key-value map with additional details
+    nullable: true
+    type: object
+    example:
+      car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/SalesChannelLocation.yaml b/docs/api/store/components/schemas/SalesChannelLocation.yaml
index 27ec4fd84b..4936e19986 100644
--- a/docs/api/store/components/schemas/SalesChannelLocation.yaml
+++ b/docs/api/store/components/schemas/SalesChannelLocation.yaml
@@ -1,5 +1,5 @@
 title: Sales Channel Stock Location
-description: Sales Channel Stock Location link sales channels with stock locations.
+description: This represents the association between a sales channel and a stock locations.
 type: object
 required:
   - created_at
@@ -14,16 +14,15 @@ properties:
     type: string
     example: scloc_01G8X9A7ESKAJXG2H0E6F1MW7A
   sales_channel_id:
-    description: The id of the Sales Channel
+    description: The ID of the Sales Channel
     type: string
     example: sc_01G8X9A7ESKAJXG2H0E6F1MW7A
   location_id:
-    description: The id of the Location Stock.
+    description: The ID of the Location Stock.
     type: string
   sales_channel:
-    description: >-
-      The sales channel the location is associated with. Available if the
-      relation `sales_channel` is expanded.
+    description: The details of the sales channel the location is associated with.
+    x-expandable: sales_channel
     nullable: true
     type: object
   created_at:
diff --git a/docs/api/store/components/schemas/ShippingMethod.yaml b/docs/api/store/components/schemas/ShippingMethod.yaml
index 04dcb7020c..730bf052cd 100644
--- a/docs/api/store/components/schemas/ShippingMethod.yaml
+++ b/docs/api/store/components/schemas/ShippingMethod.yaml
@@ -1,9 +1,10 @@
 title: Shipping Method
 description: >-
-  Shipping Methods represent a way in which an Order or Return can be shipped.
-  Shipping Methods are built from a Shipping Option, but may contain additional
-  details, that can be necessary for the Fulfillment Provider to handle the
-  shipment.
+  A Shipping Method represents a way in which an Order or Return can be shipped.
+  Shipping Methods are created from a Shipping Option, but may contain
+  additional details that can be necessary for the Fulfillment Provider to
+  handle the shipment. If the shipping method is created for a return, it may be
+  associated with a claim or a swap that the return is part of.
 type: object
 required:
   - cart_id
@@ -21,61 +22,68 @@ properties:
     type: string
     example: sm_01F0YET7DR2E7CYVSDHM593QG2
   shipping_option_id:
-    description: The id of the Shipping Option that the Shipping Method is built from.
+    description: The ID of the Shipping Option that the Shipping Method is built from.
     type: string
     example: so_01G1G5V27GYX4QXNARRQCW1N8T
   order_id:
-    description: The id of the Order that the Shipping Method is used on.
+    description: The ID of the order that the shipping method is used in.
     nullable: true
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the shipping method is used in.
+    x-expandable: order
     nullable: true
     type: object
   claim_order_id:
-    description: The id of the Claim that the Shipping Method is used on.
+    description: The ID of the claim that the shipping method is used in.
     nullable: true
     type: string
     example: null
   claim_order:
-    description: A claim order object. Available if the relation `claim_order` is expanded.
+    description: The details of the claim that the shipping method is used in.
+    x-expandable: claim_order
     nullable: true
     type: object
   cart_id:
-    description: The id of the Cart that the Shipping Method is used on.
+    description: The ID of the cart that the shipping method is used in.
     nullable: true
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart that the shipping method is used in.
+    x-expandable: cart
     nullable: true
     type: object
   swap_id:
-    description: The id of the Swap that the Shipping Method is used on.
+    description: The ID of the swap that the shipping method is used in.
     nullable: true
     type: string
     example: null
   swap:
-    description: A swap object. Available if the relation `swap` is expanded.
+    description: The details of the swap that the shipping method is used in.
+    x-expandable: swap
     nullable: true
     type: object
   return_id:
-    description: The id of the Return that the Shipping Method is used on.
+    description: The ID of the return that the shipping method is used in.
     nullable: true
     type: string
     example: null
   return_order:
-    description: A return object. Available if the relation `return_order` is expanded.
+    description: The details of the return that the shipping method is used in.
+    x-expandable: return_order
     nullable: true
     type: object
   shipping_option:
-    description: Available if the relation `shipping_option` is expanded.
+    description: The details of the shipping option the method was created from.
+    x-expandable: shipping_option
     nullable: true
     $ref: ./ShippingOption.yaml
   tax_lines:
-    description: Available if the relation `tax_lines` is expanded.
+    description: The details of the tax lines applied on the shipping method.
     type: array
+    x-expandable: tax_lines
     items:
       $ref: ./ShippingMethodTaxLine.yaml
   price:
@@ -93,8 +101,9 @@ properties:
     type: object
     example: {}
   includes_tax:
-    description: '[EXPERIMENTAL] Indicates if the shipping method price include tax'
+    description: Whether the shipping method price include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
   subtotal:
     description: The subtotal of the shipping
diff --git a/docs/api/store/components/schemas/ShippingMethodTaxLine.yaml b/docs/api/store/components/schemas/ShippingMethodTaxLine.yaml
index d251624dca..892b8c06e0 100644
--- a/docs/api/store/components/schemas/ShippingMethodTaxLine.yaml
+++ b/docs/api/store/components/schemas/ShippingMethodTaxLine.yaml
@@ -1,5 +1,7 @@
 title: Shipping Method Tax Line
-description: Shipping Method Tax Line
+description: >-
+  A Shipping Method Tax Line represents the taxes applied on a shipping method
+  in a cart.
 type: object
 required:
   - code
@@ -33,7 +35,8 @@ properties:
     type: string
     example: sm_01F0YET7DR2E7CYVSDHM593QG2
   shipping_method:
-    description: Available if the relation `shipping_method` is expanded.
+    description: The details of the associated shipping method.
+    x-expandable: shipping_method
     nullable: true
     type: object
   created_at:
@@ -50,3 +53,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ShippingOption.yaml b/docs/api/store/components/schemas/ShippingOption.yaml
index a8eebad545..fbc4d8ed41 100644
--- a/docs/api/store/components/schemas/ShippingOption.yaml
+++ b/docs/api/store/components/schemas/ShippingOption.yaml
@@ -1,6 +1,6 @@
 title: Shipping Option
 description: >-
-  Shipping Options represent a way in which an Order or Return can be shipped.
+  A Shipping Option represents a way in which an Order or Return can be shipped.
   Shipping Options have an associated Fulfillment Provider that will be used
   when the fulfillment of an Order is initiated. Shipping Options themselves
   cannot be added to Carts, but serve as a template for Shipping Methods. This
@@ -34,32 +34,36 @@ properties:
     type: string
     example: PostFake Standard
   region_id:
-    description: The region's ID
+    description: The ID of the region this shipping option can be used in.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region this shipping option can be used in.
+    x-expandable: region
     nullable: true
     type: object
   profile_id:
-    description: >-
-      The ID of the Shipping Profile that the shipping option belongs to.
-      Shipping Profiles have a set of defined Shipping Options that can be used
-      to Fulfill a given set of Products.
+    description: The ID of the Shipping Profile that the shipping option belongs to.
     type: string
     example: sp_01G1G5V239ENSZ5MV4JAR737BM
   profile:
-    description: Available if the relation `profile` is expanded.
+    description: The details of the shipping profile that the shipping option belongs to.
+    x-expandable: profile
     nullable: true
     $ref: ./ShippingProfile.yaml
   provider_id:
     description: >-
-      The id of the Fulfillment Provider, that will be used to process
-      Fulfillments from the Shipping Option.
+      The ID of the fulfillment provider that will be used to later to process
+      the shipping method created from this shipping option and its
+      fulfillments.
     type: string
     example: manual
   provider:
-    description: Available if the relation `provider` is expanded.
+    description: >-
+      The details of the fulfillment provider that will be used to later to
+      process the shipping method created from this shipping option and its
+      fulfillments.
+    x-expandable: provider
     nullable: true
     $ref: ./FulfillmentProvider.yaml
   price_type:
@@ -91,10 +95,10 @@ properties:
     default: false
   requirements:
     description: >-
-      The requirements that must be satisfied for the Shipping Option to be
-      available for a Cart. Available if the relation `requirements` is
-      expanded.
+      The details of the requirements that must be satisfied for the Shipping
+      Option to be available for usage in a Cart.
     type: array
+    x-expandable: requirements
     items:
       $ref: ./ShippingOptionRequirement.yaml
   data:
@@ -104,8 +108,9 @@ properties:
     type: object
     example: {}
   includes_tax:
-    description: '[EXPERIMENTAL] Does the shipping option price include tax'
+    description: Whether the shipping option price include tax
     type: boolean
+    x-featureFlag: tax_inclusive_pricing
     default: false
   created_at:
     description: The date with timezone at which the resource was created.
@@ -126,3 +131,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ShippingOptionRequirement.yaml b/docs/api/store/components/schemas/ShippingOptionRequirement.yaml
index 57d045827c..26764f96d0 100644
--- a/docs/api/store/components/schemas/ShippingOptionRequirement.yaml
+++ b/docs/api/store/components/schemas/ShippingOptionRequirement.yaml
@@ -1,7 +1,7 @@
 title: Shipping Option Requirement
 description: >-
-  A requirement that a Cart must satisfy for the Shipping Option to be available
-  to the Cart.
+  A shipping option requirement defines conditions that a Cart must satisfy for
+  the Shipping Option to be available for usage in the Cart.
 type: object
 required:
   - amount
@@ -15,13 +15,12 @@ properties:
     type: string
     example: sor_01G1G5V29AB4CTNDRFSRWSRKWD
   shipping_option_id:
-    description: >-
-      The id of the Shipping Option that the hipping option requirement belongs
-      to
+    description: The ID of the shipping option that the requirements belong to.
     type: string
     example: so_01G1G5V27GYX4QXNARRQCW1N8T
   shipping_option:
-    description: Available if the relation `shipping_option` is expanded.
+    description: The details of the shipping option that the requirements belong to.
+    x-expandable: shipping_option
     nullable: true
     type: object
   type:
diff --git a/docs/api/store/components/schemas/ShippingProfile.yaml b/docs/api/store/components/schemas/ShippingProfile.yaml
index 15ffd42c84..58c9ef4558 100644
--- a/docs/api/store/components/schemas/ShippingProfile.yaml
+++ b/docs/api/store/components/schemas/ShippingProfile.yaml
@@ -1,7 +1,10 @@
 title: Shipping Profile
 description: >-
-  Shipping Profiles have a set of defined Shipping Options that can be used to
-  fulfill a given set of Products.
+  A Shipping Profile has a set of defined Shipping Options that can be used to
+  fulfill a given set of Products. For example, gift cards are shipped
+  differently than physical products, so a shipping profile with the type
+  `gift_card` groups together the shipping options that can only be used for
+  gift cards.
 type: object
 required:
   - created_at
@@ -34,17 +37,18 @@ properties:
     example: default
   products:
     description: >-
-      The Products that the Shipping Profile defines Shipping Options for.
-      Available if the relation `products` is expanded.
+      The details of the products that the Shipping Profile defines Shipping
+      Options for. Available if the relation `products` is expanded.
     type: array
+    x-expandable: products
     items:
       type: object
   shipping_options:
     description: >-
-      The Shipping Options that can be used to fulfill the Products in the
-      Shipping Profile. Available if the relation `shipping_options` is
-      expanded.
+      The details of the shipping options that can be used to create shipping
+      methods for the Products in the Shipping Profile.
     type: array
+    x-expandable: shipping_options
     items:
       type: object
   created_at:
@@ -66,3 +70,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/ShippingTaxRate.yaml b/docs/api/store/components/schemas/ShippingTaxRate.yaml
index 78734007ac..c7b36795be 100644
--- a/docs/api/store/components/schemas/ShippingTaxRate.yaml
+++ b/docs/api/store/components/schemas/ShippingTaxRate.yaml
@@ -1,7 +1,5 @@
 title: Shipping Tax Rate
-description: >-
-  Associates a tax rate with a shipping option to indicate that the shipping
-  option is taxed in a certain way
+description: This represents the tax rates applied on a shipping option.
 type: object
 required:
   - created_at
@@ -11,19 +9,21 @@ required:
   - updated_at
 properties:
   shipping_option_id:
-    description: The ID of the Shipping Option
+    description: The ID of the shipping option.
     type: string
     example: so_01G1G5V27GYX4QXNARRQCW1N8T
   shipping_option:
-    description: Available if the relation `shipping_option` is expanded.
+    description: The details of the shipping option.
+    x-expandable: shipping_option
     nullable: true
     $ref: ./ShippingOption.yaml
   rate_id:
-    description: The ID of the Tax Rate
+    description: The ID of the associated tax rate.
     type: string
     example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
   tax_rate:
-    description: Available if the relation `tax_rate` is expanded.
+    description: The details of the associated tax rate.
+    x-expandable: tax_rate
     nullable: true
     $ref: ./TaxRate.yaml
   created_at:
@@ -40,3 +40,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/Store.yaml b/docs/api/store/components/schemas/Store.yaml
index 93232178dc..3a79d6301a 100644
--- a/docs/api/store/components/schemas/Store.yaml
+++ b/docs/api/store/components/schemas/Store.yaml
@@ -1,5 +1,8 @@
 title: Store
-description: Holds settings for the Store, such as name, currencies, etc.
+description: >-
+  A store holds the main settings of the commerce shop. By default, only one
+  store is created and used within the Medusa backend. It holds settings related
+  to the name of the store, available currencies, and more.
 type: object
 required:
   - created_at
@@ -29,14 +32,14 @@ properties:
       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
       description: See a list of codes.
   default_currency:
-    description: Available if the relation `default_currency` is expanded.
+    description: The details of the store's default currency.
+    x-expandable: default_currency
     nullable: true
     $ref: ./Currency.yaml
   currencies:
-    description: >-
-      The currencies that are enabled for the Store. Available if the relation
-      `currencies` is expanded.
+    description: The details of the enabled currencies in the store.
     type: array
+    x-expandable: currencies
     items:
       $ref: ./Currency.yaml
   swap_link_template:
@@ -64,14 +67,13 @@ properties:
     type: string
     example: null
   default_sales_channel_id:
-    description: The sales channel ID the cart is associated with.
+    description: The ID of the store's default sales channel.
     nullable: true
     type: string
     example: null
   default_sales_channel:
-    description: >-
-      A sales channel object. Available if the relation `default_sales_channel`
-      is expanded.
+    description: The details of the store's default sales channel.
+    x-expandable: default_sales_channel
     nullable: true
     $ref: ./SalesChannel.yaml
   created_at:
@@ -88,3 +90,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/StoreAuthRes.yaml b/docs/api/store/components/schemas/StoreAuthRes.yaml
index d46f399b85..2d0677080d 100644
--- a/docs/api/store/components/schemas/StoreAuthRes.yaml
+++ b/docs/api/store/components/schemas/StoreAuthRes.yaml
@@ -9,4 +9,5 @@ required:
   - customer
 properties:
   customer:
+    description: Customer's details.
     $ref: ./Customer.yaml
diff --git a/docs/api/store/components/schemas/StoreCartShippingOptionsListRes.yaml b/docs/api/store/components/schemas/StoreCartShippingOptionsListRes.yaml
index fa027c42a6..3e5c1e0aa4 100644
--- a/docs/api/store/components/schemas/StoreCartShippingOptionsListRes.yaml
+++ b/docs/api/store/components/schemas/StoreCartShippingOptionsListRes.yaml
@@ -9,5 +9,6 @@ required:
 properties:
   shipping_options:
     type: array
+    description: An array of shipping options details.
     items:
       $ref: ./PricedShippingOption.yaml
diff --git a/docs/api/store/components/schemas/StoreCartsRes.yaml b/docs/api/store/components/schemas/StoreCartsRes.yaml
index bcc2ca7b8d..b3f5bd7488 100644
--- a/docs/api/store/components/schemas/StoreCartsRes.yaml
+++ b/docs/api/store/components/schemas/StoreCartsRes.yaml
@@ -24,6 +24,7 @@ x-expanded-relations:
     - items
     - items.variant
     - items.variant.product
+    - items.variant.product.profiles
     - items.tax_lines
     - items.adjustments
     - gift_cards
@@ -58,4 +59,5 @@ required:
   - cart
 properties:
   cart:
+    description: Cart details.
     $ref: ./Cart.yaml
diff --git a/docs/api/store/components/schemas/StoreCollectionsListRes.yaml b/docs/api/store/components/schemas/StoreCollectionsListRes.yaml
index 32822ecdb6..73b8557c45 100644
--- a/docs/api/store/components/schemas/StoreCollectionsListRes.yaml
+++ b/docs/api/store/components/schemas/StoreCollectionsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   collections:
     type: array
+    description: An array of product collections details
     items:
       $ref: ./ProductCollection.yaml
   count:
@@ -14,7 +15,9 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: >-
+      The number of product collections skipped when retrieving the product
+      collections.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/store/components/schemas/StoreCollectionsRes.yaml b/docs/api/store/components/schemas/StoreCollectionsRes.yaml
index e21873dbc1..f5e0d5b0f2 100644
--- a/docs/api/store/components/schemas/StoreCollectionsRes.yaml
+++ b/docs/api/store/components/schemas/StoreCollectionsRes.yaml
@@ -3,4 +3,5 @@ required:
   - collection
 properties:
   collection:
+    description: Product collection details.
     $ref: ./ProductCollection.yaml
diff --git a/docs/api/store/components/schemas/StoreCompleteCartRes.yaml b/docs/api/store/components/schemas/StoreCompleteCartRes.yaml
index 0359a68f13..0624fa5271 100644
--- a/docs/api/store/components/schemas/StoreCompleteCartRes.yaml
+++ b/docs/api/store/components/schemas/StoreCompleteCartRes.yaml
@@ -5,7 +5,13 @@ required:
 properties:
   type:
     type: string
-    description: The type of the data property.
+    description: >-
+      The type of the data property. If the cart completion fails, type will be
+      `cart` and the data object will be the cart's details. If the cart
+      completion is successful and the cart is used for checkout, type will be
+      `order` and the data object will be the order's details. If the cart
+      completion is successful and the cart is used for swap creation, type will
+      be `swap` and the data object will be the swap's details.
     enum:
       - order
       - cart
@@ -26,7 +32,5 @@ properties:
           - $ref: ./Cart.yaml
       - type: object
         allOf:
-          - description: >-
-              When cart is used for a swap and it has been completed
-              successfully.
+          - description: Cart was used for a swap and it has been completed successfully.
           - $ref: ./Swap.yaml
diff --git a/docs/api/store/components/schemas/StoreCustomersListOrdersRes.yaml b/docs/api/store/components/schemas/StoreCustomersListOrdersRes.yaml
index 2733f8b01b..24a102a92c 100644
--- a/docs/api/store/components/schemas/StoreCustomersListOrdersRes.yaml
+++ b/docs/api/store/components/schemas/StoreCustomersListOrdersRes.yaml
@@ -35,6 +35,7 @@ x-expanded-relations:
     - items.tax_lines
     - items.variant
     - items.variant.product
+    - items.variant.product.profiles
     - refunds
     - region
     - shipping_address
@@ -88,13 +89,14 @@ required:
 properties:
   orders:
     type: array
+    description: An array of orders details.
     items:
       $ref: ./Order.yaml
   count:
     description: The total number of items available
     type: integer
   offset:
-    description: The number of items skipped before these items
+    description: The number of orders skipped when retrieving the orders.
     type: integer
   limit:
     description: The number of items per page
diff --git a/docs/api/store/components/schemas/StoreCustomersListPaymentMethodsRes.yaml b/docs/api/store/components/schemas/StoreCustomersListPaymentMethodsRes.yaml
index a2ebfb8cfa..6a25bc8a68 100644
--- a/docs/api/store/components/schemas/StoreCustomersListPaymentMethodsRes.yaml
+++ b/docs/api/store/components/schemas/StoreCustomersListPaymentMethodsRes.yaml
@@ -4,6 +4,7 @@ required:
 properties:
   payment_methods:
     type: array
+    description: An array of saved payment method details.
     items:
       type: object
       required:
@@ -11,7 +12,7 @@ properties:
         - data
       properties:
         provider_id:
-          description: The id of the Payment Provider where the payment method is saved.
+          description: The ID of the Payment Provider where the payment method is saved.
           type: string
         data:
           description: >-
diff --git a/docs/api/store/components/schemas/StoreCustomersRes.yaml b/docs/api/store/components/schemas/StoreCustomersRes.yaml
index 3569d05363..a98b41e268 100644
--- a/docs/api/store/components/schemas/StoreCustomersRes.yaml
+++ b/docs/api/store/components/schemas/StoreCustomersRes.yaml
@@ -8,4 +8,5 @@ required:
   - customer
 properties:
   customer:
+    description: Customer details.
     $ref: ./Customer.yaml
diff --git a/docs/api/store/components/schemas/StoreCustomersResetPasswordRes.yaml b/docs/api/store/components/schemas/StoreCustomersResetPasswordRes.yaml
index 4c256ac6ce..f732f2eea4 100644
--- a/docs/api/store/components/schemas/StoreCustomersResetPasswordRes.yaml
+++ b/docs/api/store/components/schemas/StoreCustomersResetPasswordRes.yaml
@@ -3,4 +3,5 @@ required:
   - customer
 properties:
   customer:
+    description: Customer details.
     $ref: ./Customer.yaml
diff --git a/docs/api/store/components/schemas/StoreGetProductCategoriesCategoryRes.yaml b/docs/api/store/components/schemas/StoreGetProductCategoriesCategoryRes.yaml
index eaf81a7222..bc22b78246 100644
--- a/docs/api/store/components/schemas/StoreGetProductCategoriesCategoryRes.yaml
+++ b/docs/api/store/components/schemas/StoreGetProductCategoriesCategoryRes.yaml
@@ -8,4 +8,5 @@ required:
   - product_category
 properties:
   product_category:
+    description: Product category details.
     $ref: ./ProductCategory.yaml
diff --git a/docs/api/store/components/schemas/StoreGetProductCategoriesRes.yaml b/docs/api/store/components/schemas/StoreGetProductCategoriesRes.yaml
index f053d45d1e..55c49a2d38 100644
--- a/docs/api/store/components/schemas/StoreGetProductCategoriesRes.yaml
+++ b/docs/api/store/components/schemas/StoreGetProductCategoriesRes.yaml
@@ -12,6 +12,7 @@ required:
 properties:
   product_categories:
     type: array
+    description: An array of product categories details.
     items:
       $ref: ./ProductCategory.yaml
   count:
@@ -19,7 +20,9 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: >-
+      The number of product categories skipped when retrieving the product
+      categories.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/store/components/schemas/StoreGiftCardsRes.yaml b/docs/api/store/components/schemas/StoreGiftCardsRes.yaml
index b866fde0a4..b089e39740 100644
--- a/docs/api/store/components/schemas/StoreGiftCardsRes.yaml
+++ b/docs/api/store/components/schemas/StoreGiftCardsRes.yaml
@@ -3,4 +3,5 @@ required:
   - gift_card
 properties:
   gift_card:
+    description: Gift card details.
     $ref: ./GiftCard.yaml
diff --git a/docs/api/store/components/schemas/StoreOrderEditsRes.yaml b/docs/api/store/components/schemas/StoreOrderEditsRes.yaml
index 4f5087710f..2ce8949be8 100644
--- a/docs/api/store/components/schemas/StoreOrderEditsRes.yaml
+++ b/docs/api/store/components/schemas/StoreOrderEditsRes.yaml
@@ -38,4 +38,5 @@ required:
   - order_edit
 properties:
   order_edit:
+    description: Order edit details.
     $ref: ./OrderEdit.yaml
diff --git a/docs/api/store/components/schemas/StoreOrdersRes.yaml b/docs/api/store/components/schemas/StoreOrdersRes.yaml
index 2cd84fe12d..37131a3f45 100644
--- a/docs/api/store/components/schemas/StoreOrdersRes.yaml
+++ b/docs/api/store/components/schemas/StoreOrdersRes.yaml
@@ -37,6 +37,7 @@ x-expanded-relations:
     - items.tax_lines
     - items.variant
     - items.variant.product
+    - items.variant.product.profiles
     - refunds
     - region
     - shipping_methods
@@ -83,4 +84,5 @@ x-expanded-relations:
     - swaps.additional_items.total
 properties:
   order:
+    description: Order details.
     $ref: ./Order.yaml
diff --git a/docs/api/store/components/schemas/StorePaymentCollectionsRes.yaml b/docs/api/store/components/schemas/StorePaymentCollectionsRes.yaml
index 235443c942..892745b97b 100644
--- a/docs/api/store/components/schemas/StorePaymentCollectionsRes.yaml
+++ b/docs/api/store/components/schemas/StorePaymentCollectionsRes.yaml
@@ -11,4 +11,5 @@ required:
   - payment_collection
 properties:
   payment_collection:
+    description: Payment collection's details.
     $ref: ./PaymentCollection.yaml
diff --git a/docs/api/store/components/schemas/StorePaymentCollectionsSessionRes.yaml b/docs/api/store/components/schemas/StorePaymentCollectionsSessionRes.yaml
index 075c9ef9e2..182f41c280 100644
--- a/docs/api/store/components/schemas/StorePaymentCollectionsSessionRes.yaml
+++ b/docs/api/store/components/schemas/StorePaymentCollectionsSessionRes.yaml
@@ -3,4 +3,5 @@ required:
   - payment_session
 properties:
   payment_session:
+    description: Payment session's details.
     $ref: ./PaymentSession.yaml
diff --git a/docs/api/store/components/schemas/StorePostCartReq.yaml b/docs/api/store/components/schemas/StorePostCartReq.yaml
index 836a28a8b9..ed170c0acd 100644
--- a/docs/api/store/components/schemas/StorePostCartReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCartReq.yaml
@@ -2,21 +2,37 @@ type: object
 properties:
   region_id:
     type: string
-    description: The ID of the Region to create the Cart in.
+    description: >-
+      The ID of the Region to create the Cart in. Setting the cart's region can
+      affect the pricing of the items in the cart as well as the used currency.
+      If this parameter is not provided, the first region in the store is used
+      by default.
   sales_channel_id:
     type: string
-    description: '[EXPERIMENTAL] The ID of the Sales channel to create the Cart in.'
+    description: >-
+      The ID of the Sales channel to create the Cart in. The cart's sales
+      channel affects which products can be added to the cart. If a product does
+      not exist in the cart's sales channel, it cannot be added to the cart. If
+      you add a publishable API key in the header of this request and specify a
+      sales channel ID, the specified sales channel must be within the scope of
+      the publishable API key's resources. If you add a publishable API key in
+      the header of this request, you don't specify a sales channel ID, and the
+      publishable API key is associated with one sales channel, that sales
+      channel will be attached to the cart. If no sales channel is passed and no
+      publishable API key header is passed or the publishable API key isn't
+      associated with any sales channel, the cart will not be associated with
+      any sales channel.
   country_code:
     type: string
-    description: The 2 character ISO country code to create the Cart in.
+    description: >-
+      The 2 character ISO country code to create the Cart in. Setting this
+      parameter will set the country code of the shipping address.
     externalDocs:
       url: >-
         https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
       description: See a list of codes.
   items:
-    description: >-
-      An optional array of `variant_id`, `quantity` pairs to generate Line Items
-      from.
+    description: An array of product variants to generate line items from.
     type: array
     items:
       type: object
@@ -25,14 +41,14 @@ properties:
         - quantity
       properties:
         variant_id:
-          description: The id of the Product Variant to generate a Line Item from.
+          description: The ID of the Product Variant.
           type: string
         quantity:
-          description: The quantity of the Product Variant to add
+          description: The quantity to add into the cart.
           type: integer
   context:
     description: >-
-      An optional object to provide context to the Cart. The `context` field is
+      An object to provide context to the Cart. The `context` field is
       automatically populated with `ip` and `user_agent`
     type: object
     example:
diff --git a/docs/api/store/components/schemas/StorePostCartsCartLineItemsItemReq.yaml b/docs/api/store/components/schemas/StorePostCartsCartLineItemsItemReq.yaml
index 7bbbc6dcb6..08f84fd8b8 100644
--- a/docs/api/store/components/schemas/StorePostCartsCartLineItemsItemReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCartsCartLineItemsItemReq.yaml
@@ -4,9 +4,13 @@ required:
 properties:
   quantity:
     type: number
-    description: The quantity to set the Line Item to.
+    description: The quantity of the line item in the cart.
   metadata:
     type: object
     description: >-
       An optional key-value map with additional details about the Line Item. If
       omitted, the metadata will remain unchanged."
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/StorePostCartsCartLineItemsReq.yaml b/docs/api/store/components/schemas/StorePostCartsCartLineItemsReq.yaml
index 39e4f1b97a..13728fbc1d 100644
--- a/docs/api/store/components/schemas/StorePostCartsCartLineItemsReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCartsCartLineItemsReq.yaml
@@ -12,3 +12,7 @@ properties:
   metadata:
     type: object
     description: An optional key-value map with additional details about the Line Item.
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/StorePostCartsCartReq.yaml b/docs/api/store/components/schemas/StorePostCartsCartReq.yaml
index a54a1d60a8..93a1140b09 100644
--- a/docs/api/store/components/schemas/StorePostCartsCartReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCartsCartReq.yaml
@@ -2,10 +2,14 @@ type: object
 properties:
   region_id:
     type: string
-    description: The id of the Region to create the Cart in.
+    description: >-
+      The ID of the Region to create the Cart in. Setting the cart's region can
+      affect the pricing of the items in the cart as well as the used currency.
   country_code:
     type: string
-    description: The 2 character ISO country code to create the Cart in.
+    description: >-
+      The 2 character ISO country code to create the Cart in. Setting this
+      parameter will set the country code of the shipping address.
     externalDocs:
       url: >-
         https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
@@ -16,7 +20,13 @@ properties:
     format: email
   sales_channel_id:
     type: string
-    description: The ID of the Sales channel to update the Cart with.
+    description: >-
+      The ID of the Sales channel to create the Cart in. The cart's sales
+      channel affects which products can be added to the cart. If a product does
+      not exist in the cart's sales channel, it cannot be added to the cart. If
+      you add a publishable API key in the header of this request and specify a
+      sales channel ID, the specified sales channel must be within the scope of
+      the publishable API key's resources.
   billing_address:
     description: The Address to be used for billing purposes.
     anyOf:
@@ -25,7 +35,7 @@ properties:
       - type: string
         description: The billing address ID
   shipping_address:
-    description: The Address to be used for shipping.
+    description: The Address to be used for shipping purposes.
     anyOf:
       - $ref: ./AddressPayload.yaml
         description: A full shipping address object.
@@ -40,7 +50,7 @@ properties:
         - code
       properties:
         code:
-          description: The code that a Gift Card is identified by.
+          description: The code of a gift card.
           type: string
   discounts:
     description: An array of Discount codes to add to the Cart.
@@ -51,13 +61,15 @@ properties:
         - code
       properties:
         code:
-          description: The code that a Discount is identified by.
+          description: The code of the discount.
           type: string
   customer_id:
     description: The ID of the Customer to associate the Cart with.
     type: string
   context:
-    description: An optional object to provide context to the Cart.
+    description: >-
+      An object to provide context to the Cart. The `context` field is
+      automatically populated with `ip` and `user_agent`
     type: object
     example:
       ip: '::1'
diff --git a/docs/api/store/components/schemas/StorePostCartsCartShippingMethodReq.yaml b/docs/api/store/components/schemas/StorePostCartsCartShippingMethodReq.yaml
index de546145c2..3226d41099 100644
--- a/docs/api/store/components/schemas/StorePostCartsCartShippingMethodReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCartsCartShippingMethodReq.yaml
@@ -4,10 +4,10 @@ required:
 properties:
   option_id:
     type: string
-    description: ID of the shipping option to create the method from
+    description: ID of the shipping option to create the method from.
   data:
     type: object
     description: >-
       Used to hold any data that the shipping method may need to process the
-      fulfillment of the order. Look at the documentation for your installed
-      fulfillment providers to find out what to send.
+      fulfillment of the order. This depends on the fulfillment provider you're
+      using.
diff --git a/docs/api/store/components/schemas/StorePostCustomersCustomerAcceptClaimReq.yaml b/docs/api/store/components/schemas/StorePostCustomersCustomerAcceptClaimReq.yaml
index 6bfeab6613..1848dbaa95 100644
--- a/docs/api/store/components/schemas/StorePostCustomersCustomerAcceptClaimReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCustomersCustomerAcceptClaimReq.yaml
@@ -3,5 +3,5 @@ required:
   - token
 properties:
   token:
-    description: The invite token provided by the admin.
+    description: The claim token generated by previous request to the Claim Order endpoint.
     type: string
diff --git a/docs/api/store/components/schemas/StorePostCustomersCustomerAddressesReq.yaml b/docs/api/store/components/schemas/StorePostCustomersCustomerAddressesReq.yaml
index 84aed96646..5e31c8f41c 100644
--- a/docs/api/store/components/schemas/StorePostCustomersCustomerAddressesReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCustomersCustomerAddressesReq.yaml
@@ -3,5 +3,5 @@ required:
   - address
 properties:
   address:
-    description: The Address to add to the Customer.
+    description: The Address to add to the Customer's saved addresses.
     $ref: ./AddressCreatePayload.yaml
diff --git a/docs/api/store/components/schemas/StorePostCustomersCustomerOrderClaimReq.yaml b/docs/api/store/components/schemas/StorePostCustomersCustomerOrderClaimReq.yaml
index d9787d6b58..dad38b1c3b 100644
--- a/docs/api/store/components/schemas/StorePostCustomersCustomerOrderClaimReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCustomersCustomerOrderClaimReq.yaml
@@ -3,7 +3,7 @@ required:
   - order_ids
 properties:
   order_ids:
-    description: The ids of the orders to claim
+    description: The ID of the orders to claim
     type: array
     items:
       type: string
diff --git a/docs/api/store/components/schemas/StorePostCustomersCustomerPasswordTokenReq.yaml b/docs/api/store/components/schemas/StorePostCustomersCustomerPasswordTokenReq.yaml
index fad16b2e72..da738333c3 100644
--- a/docs/api/store/components/schemas/StorePostCustomersCustomerPasswordTokenReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCustomersCustomerPasswordTokenReq.yaml
@@ -3,6 +3,6 @@ required:
   - email
 properties:
   email:
-    description: The email of the customer.
+    description: The customer's email.
     type: string
     format: email
diff --git a/docs/api/store/components/schemas/StorePostCustomersCustomerReq.yaml b/docs/api/store/components/schemas/StorePostCustomersCustomerReq.yaml
index 6b2089aeb1..fd46bd0b68 100644
--- a/docs/api/store/components/schemas/StorePostCustomersCustomerReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCustomersCustomerReq.yaml
@@ -1,27 +1,31 @@
 type: object
 properties:
   first_name:
-    description: The Customer's first name.
+    description: The customer's first name.
     type: string
   last_name:
-    description: The Customer's last name.
+    description: The customer's last name.
     type: string
   billing_address:
-    description: The Address to be used for billing purposes.
+    description: The address to be used for billing purposes.
     anyOf:
       - $ref: ./AddressPayload.yaml
         description: The full billing address object
       - type: string
         description: The ID of an existing billing address
   password:
-    description: The Customer's password.
+    description: The customer's password.
     type: string
   phone:
-    description: The Customer's phone number.
+    description: The customer's phone number.
     type: string
   email:
-    description: The email of the customer.
+    description: The customer's email.
     type: string
   metadata:
-    description: Metadata about the customer.
+    description: Additional custom data about the customer.
     type: object
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/StorePostCustomersReq.yaml b/docs/api/store/components/schemas/StorePostCustomersReq.yaml
index 3504e00533..ead1b666bb 100644
--- a/docs/api/store/components/schemas/StorePostCustomersReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCustomersReq.yaml
@@ -6,19 +6,19 @@ required:
   - password
 properties:
   first_name:
-    description: The Customer's first name.
+    description: The customer's first name.
     type: string
   last_name:
-    description: The Customer's last name.
+    description: The customer's last name.
     type: string
   email:
-    description: The email of the customer.
+    description: The customer's email.
     type: string
     format: email
   password:
-    description: The Customer's password.
+    description: The customer's password.
     type: string
     format: password
   phone:
-    description: The Customer's phone number.
+    description: The customer's phone number.
     type: string
diff --git a/docs/api/store/components/schemas/StorePostCustomersResetPasswordReq.yaml b/docs/api/store/components/schemas/StorePostCustomersResetPasswordReq.yaml
index e41c6ff8b0..36c3084296 100644
--- a/docs/api/store/components/schemas/StorePostCustomersResetPasswordReq.yaml
+++ b/docs/api/store/components/schemas/StorePostCustomersResetPasswordReq.yaml
@@ -5,11 +5,11 @@ required:
   - token
 properties:
   email:
-    description: The email of the customer.
+    description: The customer's email.
     type: string
     format: email
   password:
-    description: The Customer's password.
+    description: The customer's password.
     type: string
     format: password
   token:
diff --git a/docs/api/store/components/schemas/StorePostOrderEditsOrderEditDecline.yaml b/docs/api/store/components/schemas/StorePostOrderEditsOrderEditDecline.yaml
index c6d23fec71..be411e5559 100644
--- a/docs/api/store/components/schemas/StorePostOrderEditsOrderEditDecline.yaml
+++ b/docs/api/store/components/schemas/StorePostOrderEditsOrderEditDecline.yaml
@@ -2,4 +2,4 @@ type: object
 properties:
   declined_reason:
     type: string
-    description: The reason for declining the OrderEdit.
+    description: The reason for declining the Order Edit.
diff --git a/docs/api/store/components/schemas/StorePostPaymentCollectionsBatchSessionsReq.yaml b/docs/api/store/components/schemas/StorePostPaymentCollectionsBatchSessionsReq.yaml
index 38b13cf93c..358ccf173a 100644
--- a/docs/api/store/components/schemas/StorePostPaymentCollectionsBatchSessionsReq.yaml
+++ b/docs/api/store/components/schemas/StorePostPaymentCollectionsBatchSessionsReq.yaml
@@ -4,9 +4,8 @@ required:
 properties:
   sessions:
     description: >-
-      An array of payment sessions related to the Payment Collection. If the
-      session_id is not provided, existing sessions not present will be deleted
-      and the provided ones will be created.
+      An array of payment sessions related to the Payment Collection. Existing
+      sessions that are not added in this array will be deleted.
     type: array
     items:
       type: object
@@ -19,7 +18,9 @@ properties:
           description: The ID of the Payment Provider.
         amount:
           type: integer
-          description: The amount .
+          description: The payment amount
         session_id:
           type: string
-          description: The ID of the Payment Session to be updated.
+          description: >-
+            The ID of the Payment Session to be updated. If no ID is provided, a
+            new payment session is created.
diff --git a/docs/api/store/components/schemas/StorePostReturnsReq.yaml b/docs/api/store/components/schemas/StorePostReturnsReq.yaml
index 28a7393f57..6e7ce06763 100644
--- a/docs/api/store/components/schemas/StorePostReturnsReq.yaml
+++ b/docs/api/store/components/schemas/StorePostReturnsReq.yaml
@@ -5,9 +5,9 @@ required:
 properties:
   order_id:
     type: string
-    description: The ID of the Order to create the Return from.
+    description: The ID of the Order to create the return for.
   items:
-    description: The items to include in the Return.
+    description: The items to include in the return.
     type: array
     items:
       type: object
@@ -16,22 +16,23 @@ properties:
         - quantity
       properties:
         item_id:
-          description: The ID of the Line Item from the Order.
+          description: The ID of the line item to return.
           type: string
         quantity:
           description: The quantity to return.
           type: integer
         reason_id:
-          description: The ID of the return reason.
+          description: >-
+            The ID of the return reason. Return reasons can be retrieved from
+            the List Return Reasons endpoint.
           type: string
         note:
           description: A note to add to the item returned.
           type: string
   return_shipping:
     description: >-
-      If the Return is to be handled by the store operator the Customer can
-      choose a Return Shipping Method. Alternatvely the Customer can handle the
-      Return themselves.
+      The return shipping method used to return the items. If provided, a
+      fulfillment is automatically created for the return.
     type: object
     required:
       - option_id
diff --git a/docs/api/store/components/schemas/StorePostSearchReq.yaml b/docs/api/store/components/schemas/StorePostSearchReq.yaml
index 1dc8b0219b..77c49f5e3a 100644
--- a/docs/api/store/components/schemas/StorePostSearchReq.yaml
+++ b/docs/api/store/components/schemas/StorePostSearchReq.yaml
@@ -2,12 +2,12 @@ type: object
 properties:
   q:
     type: string
-    description: The query to run the search with.
+    description: The search query.
   offset:
     type: number
-    description: How many products to skip in the result.
+    description: The number of products to skip when retrieving the products.
   limit:
     type: number
     description: Limit the number of products returned.
   filter:
-    description: Filter based on the search engine.
+    description: Pass filters based on the search service.
diff --git a/docs/api/store/components/schemas/StorePostSearchRes.yaml b/docs/api/store/components/schemas/StorePostSearchRes.yaml
index b2eec4718a..3c87ebc5ec 100644
--- a/docs/api/store/components/schemas/StorePostSearchRes.yaml
+++ b/docs/api/store/components/schemas/StorePostSearchRes.yaml
@@ -5,7 +5,7 @@ allOf:
     properties:
       hits:
         description: >-
-          Array of results. The format of the items depends on the search engine
-          installed on the server.
+          Array of search results. The format of the items depends on the search
+          engine installed on the Medusa backend.
         type: array
   - type: object
diff --git a/docs/api/store/components/schemas/StorePostSwapsReq.yaml b/docs/api/store/components/schemas/StorePostSwapsReq.yaml
index fd08d4a05a..827f3ca2d6 100644
--- a/docs/api/store/components/schemas/StorePostSwapsReq.yaml
+++ b/docs/api/store/components/schemas/StorePostSwapsReq.yaml
@@ -17,13 +17,15 @@ properties:
         - quantity
       properties:
         item_id:
-          description: The ID of the Line Item from the Order.
+          description: The ID of the order's line item to return.
           type: string
         quantity:
-          description: The quantity to swap.
+          description: The quantity to return.
           type: integer
         reason_id:
-          description: The ID of the reason of this return.
+          description: >-
+            The ID of the reason of this return. Return reasons can be retrieved
+            from the List Return Reasons endpoint.
           type: string
         note:
           description: The note to add to the item being swapped.
@@ -32,7 +34,7 @@ properties:
     type: string
     description: The ID of the Shipping Option to create the Shipping Method from.
   additional_items:
-    description: The items to exchange the returned items to.
+    description: The items to exchange the returned items with.
     type: array
     items:
       type: object
@@ -41,8 +43,8 @@ properties:
         - quantity
       properties:
         variant_id:
-          description: The ID of the Product Variant to send.
+          description: The ID of the Product Variant.
           type: string
         quantity:
-          description: The quantity to send of the variant.
+          description: The quantity of the variant.
           type: integer
diff --git a/docs/api/store/components/schemas/StoreProductTagsListRes.yaml b/docs/api/store/components/schemas/StoreProductTagsListRes.yaml
index 405eac0731..e25f98e822 100644
--- a/docs/api/store/components/schemas/StoreProductTagsListRes.yaml
+++ b/docs/api/store/components/schemas/StoreProductTagsListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   product_tags:
     type: array
+    description: An array of product tags details.
     items:
       $ref: ./ProductTag.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of product tags skipped when retrieving the product tags.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/store/components/schemas/StoreProductTypesListRes.yaml b/docs/api/store/components/schemas/StoreProductTypesListRes.yaml
index 774ce804cc..643254d68d 100644
--- a/docs/api/store/components/schemas/StoreProductTypesListRes.yaml
+++ b/docs/api/store/components/schemas/StoreProductTypesListRes.yaml
@@ -7,6 +7,7 @@ required:
 properties:
   product_types:
     type: array
+    description: An array of product types details.
     items:
       $ref: ./ProductType.yaml
   count:
@@ -14,7 +15,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of product types skipped when retrieving the product types.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/store/components/schemas/StoreProductsListRes.yaml b/docs/api/store/components/schemas/StoreProductsListRes.yaml
index 7e5d2def7e..6b7b2e1de6 100644
--- a/docs/api/store/components/schemas/StoreProductsListRes.yaml
+++ b/docs/api/store/components/schemas/StoreProductsListRes.yaml
@@ -21,6 +21,7 @@ required:
 properties:
   products:
     type: array
+    description: An array of products details.
     items:
       $ref: ./PricedProduct.yaml
   count:
@@ -28,7 +29,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of products skipped when retrieving the products.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/store/components/schemas/StoreProductsRes.yaml b/docs/api/store/components/schemas/StoreProductsRes.yaml
index 68fd762db4..b911e26d37 100644
--- a/docs/api/store/components/schemas/StoreProductsRes.yaml
+++ b/docs/api/store/components/schemas/StoreProductsRes.yaml
@@ -17,4 +17,5 @@ required:
   - product
 properties:
   product:
+    description: Product details.
     $ref: ./PricedProduct.yaml
diff --git a/docs/api/store/components/schemas/StoreRegionsListRes.yaml b/docs/api/store/components/schemas/StoreRegionsListRes.yaml
index a5a11f7153..b08a1baa11 100644
--- a/docs/api/store/components/schemas/StoreRegionsListRes.yaml
+++ b/docs/api/store/components/schemas/StoreRegionsListRes.yaml
@@ -13,6 +13,7 @@ required:
 properties:
   regions:
     type: array
+    description: An array of regions details.
     items:
       $ref: ./Region.yaml
   count:
@@ -20,7 +21,7 @@ properties:
     description: The total number of items available
   offset:
     type: integer
-    description: The number of items skipped before these items
+    description: The number of regions skipped when retrieving the regions.
   limit:
     type: integer
     description: The number of items per page
diff --git a/docs/api/store/components/schemas/StoreRegionsRes.yaml b/docs/api/store/components/schemas/StoreRegionsRes.yaml
index f8a5d38f26..e905119273 100644
--- a/docs/api/store/components/schemas/StoreRegionsRes.yaml
+++ b/docs/api/store/components/schemas/StoreRegionsRes.yaml
@@ -12,4 +12,5 @@ required:
   - region
 properties:
   region:
+    description: Region details.
     $ref: ./Region.yaml
diff --git a/docs/api/store/components/schemas/StoreReturnReasonsListRes.yaml b/docs/api/store/components/schemas/StoreReturnReasonsListRes.yaml
index 0f212752fc..49723b49f7 100644
--- a/docs/api/store/components/schemas/StoreReturnReasonsListRes.yaml
+++ b/docs/api/store/components/schemas/StoreReturnReasonsListRes.yaml
@@ -9,5 +9,6 @@ required:
 properties:
   return_reasons:
     type: array
+    description: An array of return reasons details.
     items:
       $ref: ./ReturnReason.yaml
diff --git a/docs/api/store/components/schemas/StoreReturnReasonsRes.yaml b/docs/api/store/components/schemas/StoreReturnReasonsRes.yaml
index f5a1907b17..3612cfb1d7 100644
--- a/docs/api/store/components/schemas/StoreReturnReasonsRes.yaml
+++ b/docs/api/store/components/schemas/StoreReturnReasonsRes.yaml
@@ -8,4 +8,5 @@ required:
   - return_reason
 properties:
   return_reason:
+    description: Return reason details.
     $ref: ./ReturnReason.yaml
diff --git a/docs/api/store/components/schemas/StoreReturnsRes.yaml b/docs/api/store/components/schemas/StoreReturnsRes.yaml
index e786e22d89..80898a7a94 100644
--- a/docs/api/store/components/schemas/StoreReturnsRes.yaml
+++ b/docs/api/store/components/schemas/StoreReturnsRes.yaml
@@ -10,4 +10,5 @@ required:
   - return
 properties:
   return:
+    description: Return details.
     $ref: ./Return.yaml
diff --git a/docs/api/store/components/schemas/StoreShippingOptionsListRes.yaml b/docs/api/store/components/schemas/StoreShippingOptionsListRes.yaml
index fab21b5ea1..3c89434c3a 100644
--- a/docs/api/store/components/schemas/StoreShippingOptionsListRes.yaml
+++ b/docs/api/store/components/schemas/StoreShippingOptionsListRes.yaml
@@ -8,5 +8,6 @@ required:
 properties:
   shipping_options:
     type: array
+    description: An array of shipping options details.
     items:
       $ref: ./PricedShippingOption.yaml
diff --git a/docs/api/store/components/schemas/StoreSwapsRes.yaml b/docs/api/store/components/schemas/StoreSwapsRes.yaml
index f1b319e8de..c5f516da65 100644
--- a/docs/api/store/components/schemas/StoreSwapsRes.yaml
+++ b/docs/api/store/components/schemas/StoreSwapsRes.yaml
@@ -18,4 +18,5 @@ required:
   - swap
 properties:
   swap:
+    description: Swap details.
     $ref: ./Swap.yaml
diff --git a/docs/api/store/components/schemas/StoreVariantsListRes.yaml b/docs/api/store/components/schemas/StoreVariantsListRes.yaml
index 2084fd5b61..8dfeaf532f 100644
--- a/docs/api/store/components/schemas/StoreVariantsListRes.yaml
+++ b/docs/api/store/components/schemas/StoreVariantsListRes.yaml
@@ -12,5 +12,6 @@ required:
 properties:
   variants:
     type: array
+    description: An array of product variant descriptions.
     items:
       $ref: ./PricedVariant.yaml
diff --git a/docs/api/store/components/schemas/StoreVariantsRes.yaml b/docs/api/store/components/schemas/StoreVariantsRes.yaml
index 6128f33e7f..a786096a7d 100644
--- a/docs/api/store/components/schemas/StoreVariantsRes.yaml
+++ b/docs/api/store/components/schemas/StoreVariantsRes.yaml
@@ -11,4 +11,5 @@ required:
   - variant
 properties:
   variant:
+    description: Product variant description.
     $ref: ./PricedVariant.yaml
diff --git a/docs/api/store/components/schemas/Swap.yaml b/docs/api/store/components/schemas/Swap.yaml
index 2a0d1938a3..7e00bf1687 100644
--- a/docs/api/store/components/schemas/Swap.yaml
+++ b/docs/api/store/components/schemas/Swap.yaml
@@ -1,12 +1,10 @@
 title: Swap
 description: >-
-  Swaps can be created when a Customer wishes to exchange Products that they
-  have purchased to different Products. Swaps consist of a Return of previously
-  purchased Products and a Fulfillment of new Products, the amount paid for the
-  Products being returned will be used towards payment for the new Products. In
-  the case where the amount paid for the the Products being returned exceed the
-  amount to be paid for the new Products, a Refund will be issued for the
-  difference.
+  A swap can be created when a Customer wishes to exchange Products that they
+  have purchased with different Products. It consists of a Return of previously
+  purchased Products and a Fulfillment of new Products. It also includes
+  information on any additional payment or refund required based on the
+  difference between the exchanged products.
 type: object
 required:
   - allow_backorder
@@ -58,45 +56,50 @@ properties:
       - requires_action
     example: not_paid
   order_id:
-    description: The ID of the Order where the Line Items to be returned where purchased.
+    description: The ID of the order that the swap belongs to.
     type: string
     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
   order:
-    description: An order object. Available if the relation `order` is expanded.
+    description: The details of the order that the swap belongs to.
+    x-expandable: order
     nullable: true
     type: object
   additional_items:
     description: >-
-      The new Line Items to ship to the Customer. Available if the relation
-      `additional_items` is expanded.
+      The details of the new products to send to the customer, represented as
+      line items.
     type: array
+    x-expandable: additional_items
     items:
       $ref: ./LineItem.yaml
   return_order:
     description: >-
-      A return order object. The Return that is issued for the return part of
-      the Swap. Available if the relation `return_order` is expanded.
+      The details of the return that belongs to the swap, which holds the
+      details on the items being returned.
+    x-expandable: return_order
     nullable: true
     type: object
   fulfillments:
     description: >-
-      The Fulfillments used to send the new Line Items. Available if the
-      relation `fulfillments` is expanded.
+      The details of the fulfillments that are used to send the new items to the
+      customer.
+    x-expandable: fulfillments
     type: array
     items:
       type: object
   payment:
     description: >-
-      The Payment authorized when the Swap requires an additional amount to be
-      charged from the Customer. Available if the relation `payment` is
-      expanded.
+      The details of the additional payment authorized by the customer when
+      `difference_due` is positive.
+    x-expandable: payment
     nullable: true
     type: object
   difference_due:
     description: >-
-      The difference that is paid or refunded as a result of the Swap. May be
-      negative when the amount paid for the returned items exceed the total of
-      the new Products.
+      The difference amount between the order’s original total and the new total
+      imposed by the swap. If its value is negative, a refund must be issues to
+      the customer. If it's positive, additional payment must be authorized by
+      the customer. Otherwise, no payment processing is required.
     nullable: true
     type: integer
     example: 0
@@ -108,23 +111,26 @@ properties:
     type: string
     example: addr_01G8ZH853YPY9B94857DY91YGW
   shipping_address:
-    description: Available if the relation `shipping_address` is expanded.
+    description: The details of the shipping address that the new items should be sent to.
+    x-expandable: shipping_address
     nullable: true
     $ref: ./Address.yaml
   shipping_methods:
     description: >-
-      The Shipping Methods used to fulfill the additional items purchased.
-      Available if the relation `shipping_methods` is expanded.
+      The details of the shipping methods used to fulfill the additional items
+      purchased.
     type: array
+    x-expandable: shipping_methods
     items:
       $ref: ./ShippingMethod.yaml
   cart_id:
-    description: The id of the Cart that the Customer will use to confirm the Swap.
+    description: The ID of the cart that the customer uses to complete the swap.
     nullable: true
     type: string
     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
   cart:
-    description: A cart object. Available if the relation `cart` is expanded.
+    description: The details of the cart that the customer uses to complete the swap.
+    x-expandable: cart
     nullable: true
     type: object
   confirmed_at:
@@ -174,3 +180,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/TaxLine.yaml b/docs/api/store/components/schemas/TaxLine.yaml
index cca22c81f3..cbdb672a17 100644
--- a/docs/api/store/components/schemas/TaxLine.yaml
+++ b/docs/api/store/components/schemas/TaxLine.yaml
@@ -1,5 +1,5 @@
 title: Tax Line
-description: Line item that specifies an amount of tax to add to a line item.
+description: A tax line represents the taxes amount applied to a line item.
 type: object
 required:
   - code
@@ -41,3 +41,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/TaxProvider.yaml b/docs/api/store/components/schemas/TaxProvider.yaml
index 55c326d81c..0abb0ed394 100644
--- a/docs/api/store/components/schemas/TaxProvider.yaml
+++ b/docs/api/store/components/schemas/TaxProvider.yaml
@@ -1,18 +1,21 @@
 title: Tax Provider
-description: The tax service used to calculate taxes
+description: >-
+  A tax provider represents a tax service installed in the Medusa backend,
+  either through a plugin or backend customizations. It holds the tax service's
+  installation status.
 type: object
 required:
   - id
   - is_installed
 properties:
   id:
-    description: The id of the tax provider as given by the plugin.
+    description: The ID of the tax provider as given by the tax service.
     type: string
     example: manual
   is_installed:
     description: >-
-      Whether the plugin is installed in the current version. Plugins that are
-      no longer installed are not deleted by will have this field set to
+      Whether the tax service is installed in the current version. If a tax
+      service is no longer installed, the `is_installed` attribute is set to
       `false`.
     type: boolean
     default: true
diff --git a/docs/api/store/components/schemas/TaxRate.yaml b/docs/api/store/components/schemas/TaxRate.yaml
index deb3f4d02e..aaf91c7e76 100644
--- a/docs/api/store/components/schemas/TaxRate.yaml
+++ b/docs/api/store/components/schemas/TaxRate.yaml
@@ -1,7 +1,7 @@
 title: Tax Rate
 description: >-
-  A Tax Rate can be used to associate a certain rate to charge on products
-  within a given Region
+  A Tax Rate can be used to define a custom rate to charge on specified
+  products, product types, and shipping options within a given region.
 type: object
 required:
   - code
@@ -32,32 +32,30 @@ properties:
     type: string
     example: Tax Example
   region_id:
-    description: The id of the Region that the rate belongs to
+    description: The ID of the region that the rate belongs to.
     type: string
     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
   region:
-    description: A region object. Available if the relation `region` is expanded.
+    description: The details of the region that the rate belongs to.
+    x-expandable: region
     nullable: true
     type: object
   products:
-    description: >-
-      The products that belong to this tax rate. Available if the relation
-      `products` is expanded.
+    description: The details of the products that belong to this tax rate.
     type: array
+    x-expandable: products
     items:
       $ref: ./Product.yaml
   product_types:
-    description: >-
-      The product types that belong to this tax rate. Available if the relation
-      `product_types` is expanded.
+    description: The details of the product types that belong to this tax rate.
     type: array
+    x-expandable: product_types
     items:
       $ref: ./ProductType.yaml
   shipping_options:
+    description: The details of the shipping options that belong to this tax rate.
     type: array
-    description: >-
-      The shipping options that belong to this tax rate. Available if the
-      relation `shipping_options` is expanded.
+    x-expandable: shipping_options
     items:
       $ref: ./ShippingOption.yaml
   product_count:
@@ -86,3 +84,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/TrackingLink.yaml b/docs/api/store/components/schemas/TrackingLink.yaml
index 1d73c9c7e5..2da6690dae 100644
--- a/docs/api/store/components/schemas/TrackingLink.yaml
+++ b/docs/api/store/components/schemas/TrackingLink.yaml
@@ -1,8 +1,9 @@
 title: Tracking Link
 description: >-
-  Tracking Link holds information about tracking numbers for a Fulfillment.
+  A tracking link holds information about tracking numbers for a Fulfillment.
   Tracking Links can optionally contain a URL that can be visited to see the
-  status of the shipment.
+  status of the shipment. Typically, the tracking link is provided from the
+  third-party service integrated through the used fulfillment provider.
 type: object
 required:
   - created_at
@@ -29,11 +30,12 @@ properties:
     type: string
     format: RH370168054CN
   fulfillment_id:
-    description: The id of the Fulfillment that the Tracking Link references.
+    description: The ID of the fulfillment that the tracking link belongs to.
     type: string
     example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
   fulfillment:
-    description: Available if the relation `fulfillment` is expanded.
+    description: The details of the fulfillment that the tracking link belongs to.
+    x-expandable: fulfillment
     nullable: true
     type: object
   idempotency_key:
@@ -64,3 +66,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/components/schemas/User.yaml b/docs/api/store/components/schemas/User.yaml
index cdf5cf7506..33f313d896 100644
--- a/docs/api/store/components/schemas/User.yaml
+++ b/docs/api/store/components/schemas/User.yaml
@@ -1,5 +1,5 @@
 title: User
-description: Represents a User who can manage store settings.
+description: A User is an administrator who can manage store settings and data.
 type: object
 required:
   - api_token
@@ -18,7 +18,7 @@ properties:
     type: string
     example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
   role:
-    description: The user's role
+    description: The user's role. These roles don't provide any different privileges.
     type: string
     enum:
       - admin
@@ -63,3 +63,7 @@ properties:
     type: object
     example:
       car: white
+    externalDocs:
+      description: Learn about the metadata attribute, and how to delete and update it.
+      url: >-
+        https://docs.medusajs.com/development/entities/overview#metadata-attribute
diff --git a/docs/api/store/openapi.yaml b/docs/api/store/openapi.yaml
index f603c6c6ab..0531bf4467 100644
--- a/docs/api/store/openapi.yaml
+++ b/docs/api/store/openapi.yaml
@@ -409,33 +409,148 @@ info:
     url: https://github.com/medusajs/medusa/blob/master/LICENSE
 tags:
   - name: Auth
-    description: >-
-      Auth endpoints that allow authorization of customers and manages their
-      sessions.
+    description: >
+      Authentication endpoints allow customers to manage their session, such as
+      login or log out.
+
+      When a customer is logged in, the cookie header is set indicating the
+      customer's login session.
+    externalDocs:
+      description: How to implement customer profiles in your storefront
+      url: >-
+        https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles
   - name: Carts
-    description: Cart endpoints that allow handling carts in Medusa.
-  - name: Collections
-    description: Collection endpoints that allow handling collections in Medusa.
+    description: >
+      A cart is a virtual shopping bag that customers can use to add items they
+      want to purchase.
+
+      A cart is then used to checkout and place an order.
+    externalDocs:
+      description: How to implement cart functionality in your storefront
+      url: >-
+        https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-cart
   - name: Customers
-    description: Customer endpoints that allow handling customers in Medusa.
+    description: >
+      A customer can register and manage their information such as addresses,
+      orders, payment methods, and more.
+    externalDocs:
+      description: How to implement customer profiles in your storefront
+      url: >-
+        https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles
   - name: Gift Cards
-    description: Gift Card endpoints that allow handling gift cards in Medusa.
+    description: >
+      Customers can use gift cards during checkout to deduct the gift card's
+      balance from the checkout total.
+
+      The Gift Card endpoints allow retrieving a gift card's details by its
+      code. A gift card can be applied to a cart using the Carts endpoints.
+    externalDocs:
+      description: How to use gift cards in a storefront
+      url: https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards
   - name: Orders
-    description: Order endpoints that allow handling orders in Medusa.
+    description: >
+      Orders are purchases made by customers, typically through a storefront.
+
+      Orders are placed and created using the Carts endpoints. The Orders
+      endpoints allow retrieving and claiming orders.
+    externalDocs:
+      description: How to retrieve order details in a storefront
+      url: >-
+        https://docs.medusajs.com/modules/orders/storefront/retrieve-order-details
+  - name: Order Edits
+    description: >
+      Order edits are changes made to items in an order such as adding, updating
+      their quantity, or deleting them. Order edits are created by the admin.
+
+      A customer can review order edit requests created by an admin and confirm
+      or decline them.
+    externalDocs:
+      description: How to handle order edits in a storefront
+      url: https://docs.medusajs.com/modules/orders/storefront/handle-order-edits
+  - name: Payment Collections
+    description: >
+      A payment collection is useful for managing additional payments, such as
+      for Order Edits, or installment payments.
   - name: Products
-    description: Product endpoints that allow handling products in Medusa.
+    description: >
+      Products are saleable items in a store. This also includes [saleable gift
+      cards](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards)
+      in a store.
+
+      Using these endpoints, you can filter products by categories, collections,
+      sales channels, and more.
+    externalDocs:
+      description: How to show products in a storefront
+      url: https://docs.medusajs.com/modules/products/storefront/show-products
   - name: Product Variants
-    description: Product Variant endpoints that allow handling product variants in Medusa.
+    description: >
+      Product variants are the actual salable item in your store. Each variant
+      is a combination of the different option values available on the product.
+  - name: Product Categories
+    description: >
+      Products can be categoriezed into categories. A product can be associated
+      more than one category.
+
+      Using these endpoints, you can list or retrieve a category's details and
+      products.
+    externalDocs:
+      description: How to use product categories in a storefront
+      url: https://docs.medusajs.com/modules/products/storefront/use-categories
+  - name: Product Collections
+    description: >
+      A product collection is used to organize products for different purposes
+      such as marketing or discount purposes. For example, you can create a
+      Summer Collection.
+
+      Using these endpoints, you can list or retrieve a collection's details and
+      products.
+  - name: Product Tags
+    description: |
+      Product tags are string values that can be used to filter products by.
+      Products can have more than one tag, and products can share tags.
+  - name: Product Types
+    description: |
+      Product types are string values that can be used to filter products by.
+      Products can have more than one tag, and products can share types.
   - name: Regions
-    description: Region endpoints that allow handling regions in Medusa.
-  - name: Return Reasons
-    description: Return Reason endpoints that allow handling return reasons in Medusa.
+    description: >
+      Regions are different countries or geographical regions that the commerce
+      store serves customers in.
+
+      Customers can choose what region they're in, which can be used to change
+      the prices shown based on the region and its currency.
+    externalDocs:
+      description: How to use regions in a storefront
+      url: >-
+        https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions
   - name: Returns
-    description: Return endpoints that allow handling returns in Medusa.
+    description: |
+      A return can be created by a customer to return items in an order.
+    externalDocs:
+      description: How to create a return in a storefront
+      url: https://docs.medusajs.com/modules/orders/storefront/create-return
+  - name: Return Reasons
+    description: >
+      Return reasons are key-value pairs that are used to specify why an order
+      return is being created.
   - name: Shipping Options
-    description: Shipping Option endpoints that allow handling shipping options in Medusa.
+    description: >
+      A shipping option is used to define the available shipping methods during
+      checkout or when creating a return.
+    externalDocs:
+      description: Shipping Option architecture
+      url: >-
+        https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option
   - name: Swaps
-    description: Swap endpoints that allow handling swaps in Medusa.
+    description: >
+      A swap is created by a customer or an admin to exchange an item with a new
+      one.
+
+      Creating a swap implicitely includes creating a return for the item being
+      exchanged.
+    externalDocs:
+      description: How to create a swap in a storefront
+      url: https://docs.medusajs.com/modules/orders/storefront/create-swap
 servers:
   - url: https://api.medusa-commerce.com
 paths:
@@ -551,8 +666,8 @@ paths:
     $ref: paths/store_swaps_{cart_id}.yaml
   /store/variants:
     $ref: paths/store_variants.yaml
-  /store/variants/{variant_id}:
-    $ref: paths/store_variants_{variant_id}.yaml
+  /store/variants/{id}:
+    $ref: paths/store_variants_{id}.yaml
 components:
   securitySchemes:
     cookie_auth:
diff --git a/docs/api/store/paths/store_auth.yaml b/docs/api/store/paths/store_auth.yaml
index 7cb59f50a9..80c495e366 100644
--- a/docs/api/store/paths/store_auth.yaml
+++ b/docs/api/store/paths/store_auth.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetAuth
   summary: Get Current Customer
-  description: Gets the currently logged in Customer.
+  description: Retrieve the currently logged in Customer's details.
   x-authenticated: true
   x-codegen:
     method: getSession
@@ -41,8 +41,10 @@ post:
   operationId: PostAuth
   summary: Customer Login
   description: >-
-    Logs a Customer in and authorizes them to view their details. Successful
-    authentication will set a session cookie in the Customer's browser.
+    Log a customer in and includes the Cookie session in the response header.
+    The cookie session can be used in subsequent requests to authenticate the
+    customer. When using Medusa's JS or Medusa React clients, the cookie is
+    automatically attached to subsequent requests.
   requestBody:
     content:
       application/json:
@@ -83,7 +85,7 @@ post:
 delete:
   operationId: DeleteAuth
   summary: Customer Log out
-  description: Destroys a Customer's authenticated session.
+  description: Delete the current session for the logged in customer.
   x-authenticated: true
   x-codegen:
     method: deleteSession
diff --git a/docs/api/store/paths/store_auth_{email}.yaml b/docs/api/store/paths/store_auth_{email}.yaml
index b02b775028..9b1b2ac50d 100644
--- a/docs/api/store/paths/store_auth_{email}.yaml
+++ b/docs/api/store/paths/store_auth_{email}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetAuthEmail
-  summary: Check if email exists
-  description: Checks if a Customer with the given email has signed up.
+  summary: Check if Email Exists
+  description: Check if there's a customer already registered with the provided email.
   parameters:
     - in: path
       name: email
@@ -9,7 +9,7 @@ get:
         type: string
         format: email
       required: true
-      description: The email to check if exists.
+      description: The email to check.
   x-codegen:
     method: exists
   x-codeSamples:
diff --git a/docs/api/store/paths/store_carts.yaml b/docs/api/store/paths/store_carts.yaml
index 5925c934d4..b72b588bcd 100644
--- a/docs/api/store/paths/store_carts.yaml
+++ b/docs/api/store/paths/store_carts.yaml
@@ -1,11 +1,17 @@
 post:
-  summary: Create a Cart
   operationId: PostCart
-  description: >-
-    Creates a Cart within the given region and with the initial items. If no
-    `region_id` is provided the cart will be associated with the first Region
-    available. If no items are provided the cart will be empty after creation.
-    If a user is logged in the cart's customer id and email will be set.
+  summary: Create a Cart
+  description: >
+    Create a Cart. Although optional, specifying the cart's region and sales
+    channel can affect the cart's pricing and
+
+    the products that can be added to the cart respectively. So, make sure to
+    set those early on and change them if necessary, such as when the customer
+    changes their region.
+
+
+    If a customer is logged in, the cart's customer ID and email will
+    automatically be set.
   requestBody:
     content:
       application/json:
diff --git a/docs/api/store/paths/store_carts_{id}.yaml b/docs/api/store/paths/store_carts_{id}.yaml
index 1b46a1d457..821ee29ae5 100644
--- a/docs/api/store/paths/store_carts_{id}.yaml
+++ b/docs/api/store/paths/store_carts_{id}.yaml
@@ -1,12 +1,12 @@
 get:
   operationId: GetCartsCart
   summary: Get a Cart
-  description: Retrieves a Cart.
+  description: Retrieve a Cart's details. This includes recalculating its totals.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
   x-codegen:
@@ -42,12 +42,15 @@ get:
 post:
   operationId: PostCartsCart
   summary: Update a Cart
-  description: Updates a Cart.
+  description: >-
+    Update a Cart's details. If the cart has payment sessions and the region was
+    not changed, the payment sessions are updated. The cart's totals are also
+    recalculated.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
   requestBody:
diff --git a/docs/api/store/paths/store_carts_{id}_complete.yaml b/docs/api/store/paths/store_carts_{id}_complete.yaml
index 2113e2d024..3e3555cbc6 100644
--- a/docs/api/store/paths/store_carts_{id}_complete.yaml
+++ b/docs/api/store/paths/store_carts_{id}_complete.yaml
@@ -1,18 +1,30 @@
 post:
   summary: Complete a Cart
   operationId: PostCartsCartComplete
-  description: >-
-    Completes a cart. The following steps will be performed. Payment
-    authorization is attempted and if more work is required, we simply return
-    the cart for further updates. If payment is authorized and order is not yet
-    created, we make sure to do so. The completion of a cart can be performed
-    idempotently with a provided header `Idempotency-Key`. If not provided, we
-    will generate one for the request.
+  description: >
+    Complete a cart and place an order or create a swap, based on what the cart
+    is created for. This includes attempting to authorize the cart's payment.
+
+    If authorizing the payment requires more action, the cart will not be
+    completed and the order will not be placed or the swap will not be created.
+
+
+    An idempotency key will be generated if none is provided in the header
+    `Idempotency-Key` and added to
+
+    the response. If an error occurs during cart completion or the request is
+    interrupted for any reason, the cart completion can be retried by passing
+    the idempotency
+
+    key in the `Idempotency-Key` header.
+  externalDocs:
+    description: Cart completion overview
+    url: https://docs.medusajs.com/modules/carts-and-checkout/cart#cart-completion
   parameters:
     - in: path
       name: id
       required: true
-      description: The Cart id.
+      description: The Cart ID.
       schema:
         type: string
   x-codegen:
@@ -31,10 +43,12 @@ post:
   responses:
     '200':
       description: >-
-        If a cart was successfully authorized, but requires further action from
-        the user the response body will contain the cart with an updated payment
-        session. If the Cart was successfully completed the response body will
-        contain the newly created Order.
+        If the payment of the cart was successfully authorized, but requires
+        further action from the customer, the response body will contain the
+        cart with an updated payment session. Otherwise, if the payment was
+        authorized and the cart was successfully completed, the response body
+        will contain either the newly created order or swap, depending on what
+        the cart was created for.
       content:
         application/json:
           schema:
diff --git a/docs/api/store/paths/store_carts_{id}_discounts_{code}.yaml b/docs/api/store/paths/store_carts_{id}_discounts_{code}.yaml
index 740838c76b..877b3f01c4 100644
--- a/docs/api/store/paths/store_carts_{id}_discounts_{code}.yaml
+++ b/docs/api/store/paths/store_carts_{id}_discounts_{code}.yaml
@@ -1,18 +1,21 @@
 delete:
   operationId: DeleteCartsCartDiscountsDiscount
-  description: Removes a Discount from a Cart.
   summary: Remove Discount
+  description: >-
+    Remove a Discount from a Cart. This only removes the application of the
+    discount, and not completely delete it. The totals will be re-calculated and
+    the payment sessions will be refreshed after the removal.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
     - in: path
       name: code
       required: true
-      description: The unique Discount code.
+      description: The unique discount code.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_carts_{id}_line-items_{line_id}.yaml b/docs/api/store/paths/store_carts_{id}_line-items_{line_id}.yaml
index bd9d50e7a3..f6bd24c0c0 100644
--- a/docs/api/store/paths/store_carts_{id}_line-items_{line_id}.yaml
+++ b/docs/api/store/paths/store_carts_{id}_line-items_{line_id}.yaml
@@ -1,18 +1,18 @@
 post:
   operationId: PostCartsCartLineItemsItem
   summary: Update a Line Item
-  description: Updates a Line Item if the desired quantity can be fulfilled.
+  description: Update a line item's quantity.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
     - in: path
       name: line_id
       required: true
-      description: The id of the Line Item.
+      description: The ID of the Line Item.
       schema:
         type: string
   requestBody:
@@ -54,18 +54,20 @@ post:
 delete:
   operationId: DeleteCartsCartLineItemsItem
   summary: Delete a Line Item
-  description: Removes a Line Item from a Cart.
+  description: >-
+    Delete a Line Item from a Cart. The payment sessions will be updated and the
+    totals will be recalculated.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
     - in: path
       name: line_id
       required: true
-      description: The id of the Line Item.
+      description: The ID of the Line Item.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_carts_{id}_payment-session.yaml b/docs/api/store/paths/store_carts_{id}_payment-session.yaml
index 248f6c3733..7a6f27e24a 100644
--- a/docs/api/store/paths/store_carts_{id}_payment-session.yaml
+++ b/docs/api/store/paths/store_carts_{id}_payment-session.yaml
@@ -2,8 +2,9 @@ post:
   operationId: PostCartsCartPaymentSession
   summary: Select a Payment Session
   description: >-
-    Selects a Payment Session as the session intended to be used towards the
-    completion of the Cart.
+    Select the Payment Session that will be used to complete the cart. This is
+    typically used when the customer chooses their preferred payment method
+    during checkout. The totals of the cart will be recalculated.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/store/paths/store_carts_{id}_payment-sessions.yaml b/docs/api/store/paths/store_carts_{id}_payment-sessions.yaml
index 22ef8e378f..e51878c2fc 100644
--- a/docs/api/store/paths/store_carts_{id}_payment-sessions.yaml
+++ b/docs/api/store/paths/store_carts_{id}_payment-sessions.yaml
@@ -2,13 +2,15 @@ post:
   operationId: PostCartsCartPaymentSessions
   summary: Create Payment Sessions
   description: >-
-    Creates Payment Sessions for each of the available Payment Providers in the
-    Cart's Region.
+    Create Payment Sessions for each of the available Payment Providers in the
+    Cart's Region. If there only one payment session is created, it will be
+    selected by default. The creation of the payment session uses the payment
+    provider and may require sending requests to third-party services.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_carts_{id}_payment-sessions_{provider_id}.yaml b/docs/api/store/paths/store_carts_{id}_payment-sessions_{provider_id}.yaml
index 5d8877f3f2..1423e5afde 100644
--- a/docs/api/store/paths/store_carts_{id}_payment-sessions_{provider_id}.yaml
+++ b/docs/api/store/paths/store_carts_{id}_payment-sessions_{provider_id}.yaml
@@ -1,18 +1,21 @@
 post:
   operationId: PostCartsCartPaymentSessionUpdate
   summary: Update a Payment Session
-  description: Updates a Payment Session with additional data.
+  description: >-
+    Update a Payment Session with additional data. This can be useful depending
+    on the payment provider used. All payment sessions are updated and cart
+    totals are recalculated afterwards.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
     - in: path
       name: provider_id
       required: true
-      description: The id of the payment provider.
+      description: The ID of the payment provider.
       schema:
         type: string
   requestBody:
@@ -55,19 +58,21 @@ post:
 delete:
   operationId: DeleteCartsCartPaymentSessionsSession
   summary: Delete a Payment Session
-  description: Deletes a Payment Session on a Cart. May be useful if a payment has failed.
+  description: >-
+    Delete a Payment Session in a Cart. May be useful if a payment has failed.
+    The totals will be recalculated.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
     - in: path
       name: provider_id
       required: true
       description: >-
-        The id of the Payment Provider used to create the Payment Session to be
+        The ID of the Payment Provider used to create the Payment Session to be
         deleted.
       schema:
         type: string
diff --git a/docs/api/store/paths/store_carts_{id}_payment-sessions_{provider_id}_refresh.yaml b/docs/api/store/paths/store_carts_{id}_payment-sessions_{provider_id}_refresh.yaml
index 13808738e2..8f3a0f1361 100644
--- a/docs/api/store/paths/store_carts_{id}_payment-sessions_{provider_id}_refresh.yaml
+++ b/docs/api/store/paths/store_carts_{id}_payment-sessions_{provider_id}_refresh.yaml
@@ -2,20 +2,20 @@ post:
   operationId: PostCartsCartPaymentSessionsSession
   summary: Refresh a Payment Session
   description: >-
-    Refreshes a Payment Session to ensure that it is in sync with the Cart -
-    this is usually not necessary.
+    Refresh a Payment Session to ensure that it is in sync with the Cart. This
+    is usually not necessary, but is provided for edge cases.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
     - in: path
       name: provider_id
       required: true
       description: >-
-        The id of the Payment Provider that created the Payment Session to be
+        The ID of the Payment Provider that created the Payment Session to be
         refreshed.
       schema:
         type: string
diff --git a/docs/api/store/paths/store_carts_{id}_shipping-methods.yaml b/docs/api/store/paths/store_carts_{id}_shipping-methods.yaml
index cc7833976c..38a899f2a7 100644
--- a/docs/api/store/paths/store_carts_{id}_shipping-methods.yaml
+++ b/docs/api/store/paths/store_carts_{id}_shipping-methods.yaml
@@ -1,7 +1,9 @@
 post:
   operationId: PostCartsCartShippingMethod
-  description: Adds a Shipping Method to the Cart.
-  summary: Add a Shipping Method
+  summary: Add Shipping Method
+  description: >-
+    Add a Shipping Method to the Cart. The validation of the `data` field is
+    handled by the fulfillment provider of the chosen shipping option.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/store/paths/store_carts_{id}_taxes.yaml b/docs/api/store/paths/store_carts_{id}_taxes.yaml
index 994b1daffd..fd002e7f31 100644
--- a/docs/api/store/paths/store_carts_{id}_taxes.yaml
+++ b/docs/api/store/paths/store_carts_{id}_taxes.yaml
@@ -1,9 +1,14 @@
 post:
-  summary: Calculate Cart Taxes
   operationId: PostCartsCartTaxes
+  summary: Calculate Cart Taxes
   description: >-
-    Calculates taxes for a cart. Depending on the cart's region this may involve
-    making 3rd party API calls to a Tax Provider service.
+    Calculate the taxes for a cart. This is useful if the `automatic_taxes`
+    field of the cart's region is set to `false`. If the cart's region uses a
+    tax provider other than Medusa's system provider, this may lead to sending
+    requests to third-party services.
+  externalDocs:
+    description: How to calculate taxes manually during checkout
+    url: https://docs.medusajs.com/modules/taxes/storefront/manual-calculation
   parameters:
     - in: path
       name: id
diff --git a/docs/api/store/paths/store_collections.yaml b/docs/api/store/paths/store_collections.yaml
index 3ebc694a93..89db538f6f 100644
--- a/docs/api/store/paths/store_collections.yaml
+++ b/docs/api/store/paths/store_collections.yaml
@@ -1,19 +1,22 @@
 get:
   operationId: GetCollections
   summary: List Collections
-  description: Retrieve a list of Product Collection.
+  description: >-
+    Retrieve a list of product collections. The product collections can be
+    filtered by fields such as `handle` or `created_at`. The product collections
+    can also be paginated.
   parameters:
     - in: query
       name: offset
       description: >-
-        The number of collections to skip before starting to collect the
-        collections set
+        The number of product collections to skip when retrieving the product
+        collections.
       schema:
         type: integer
         default: 0
     - in: query
       name: limit
-      description: The number of collections to return
+      description: Limit the number of product collections returned.
       schema:
         type: integer
         default: 10
@@ -21,14 +24,14 @@ get:
       name: handle
       style: form
       explode: false
-      description: Filter by the collection handle
+      description: Filter by handles
       schema:
         type: array
         items:
           type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting collections were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -50,7 +53,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting collections were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -83,7 +86,7 @@ get:
       source:
         $ref: ../code_samples/Shell/store_collections/get.sh
   tags:
-    - Collections
+    - Product Collections
   responses:
     '200':
       description: OK
diff --git a/docs/api/store/paths/store_collections_{id}.yaml b/docs/api/store/paths/store_collections_{id}.yaml
index 57782abd2c..fb9a6775de 100644
--- a/docs/api/store/paths/store_collections_{id}.yaml
+++ b/docs/api/store/paths/store_collections_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetCollectionsCollection
   summary: Get a Collection
-  description: Retrieves a Product Collection.
+  description: Retrieve a Product Collection's details.
   parameters:
     - in: path
       name: id
@@ -21,7 +21,7 @@ get:
       source:
         $ref: ../code_samples/Shell/store_collections_{id}/get.sh
   tags:
-    - Collections
+    - Product Collections
   responses:
     '200':
       description: OK
diff --git a/docs/api/store/paths/store_customers.yaml b/docs/api/store/paths/store_customers.yaml
index 4d1c1131b1..fc9dae89fd 100644
--- a/docs/api/store/paths/store_customers.yaml
+++ b/docs/api/store/paths/store_customers.yaml
@@ -1,7 +1,12 @@
 post:
   operationId: PostCustomers
   summary: Create a Customer
-  description: Creates a Customer account.
+  description: >-
+    Register a new customer. This will also automatically authenticate the
+    customer and set their login session in the response Cookie header. The
+    cookie session can be used in subsequent requests to authenticate the
+    customer. When using Medusa's JS or Medusa React clients, the cookie is
+    automatically attached to subsequent requests.
   requestBody:
     content:
       application/json:
diff --git a/docs/api/store/paths/store_customers_me.yaml b/docs/api/store/paths/store_customers_me.yaml
index b09af257ae..714678aabf 100644
--- a/docs/api/store/paths/store_customers_me.yaml
+++ b/docs/api/store/paths/store_customers_me.yaml
@@ -1,9 +1,7 @@
 get:
   operationId: GetCustomersCustomer
   summary: Get a Customer
-  description: >-
-    Retrieves a Customer - the Customer must be logged in to retrieve their
-    details.
+  description: Retrieve the logged-in Customer's details.
   x-authenticated: true
   x-codegen:
     method: retrieve
@@ -42,7 +40,7 @@ get:
 post:
   operationId: PostCustomersCustomer
   summary: Update Customer
-  description: Updates a Customer's saved details.
+  description: Update the logged-in customer's details.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/store/paths/store_customers_me_addresses.yaml b/docs/api/store/paths/store_customers_me_addresses.yaml
index 841ec61ba6..7327927218 100644
--- a/docs/api/store/paths/store_customers_me_addresses.yaml
+++ b/docs/api/store/paths/store_customers_me_addresses.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostCustomersCustomerAddresses
   summary: Add a Shipping Address
-  description: Adds a Shipping Address to a Customer's saved addresses.
+  description: Add a Shipping Address to a Customer's saved addresses.
   x-authenticated: true
   requestBody:
     content:
diff --git a/docs/api/store/paths/store_customers_me_addresses_{address_id}.yaml b/docs/api/store/paths/store_customers_me_addresses_{address_id}.yaml
index 94b1dd6731..71b37b8247 100644
--- a/docs/api/store/paths/store_customers_me_addresses_{address_id}.yaml
+++ b/docs/api/store/paths/store_customers_me_addresses_{address_id}.yaml
@@ -1,13 +1,13 @@
 post:
   operationId: PostCustomersCustomerAddressesAddress
   summary: Update a Shipping Address
-  description: Updates a Customer's saved Shipping Address.
+  description: Update the logged-in customer's saved Shipping Address's details.
   x-authenticated: true
   parameters:
     - in: path
       name: address_id
       required: true
-      description: The id of the Address to update.
+      description: The ID of the Address.
       schema:
         type: string
   requestBody:
@@ -55,7 +55,7 @@ post:
 delete:
   operationId: DeleteCustomersCustomerAddressesAddress
   summary: Delete an Address
-  description: Removes an Address from the Customer's saved addresses.
+  description: Delete an Address from the Customer's saved addresses.
   x-authenticated: true
   parameters:
     - in: path
diff --git a/docs/api/store/paths/store_customers_me_orders.yaml b/docs/api/store/paths/store_customers_me_orders.yaml
index 960f944c96..098f04ab35 100644
--- a/docs/api/store/paths/store_customers_me_orders.yaml
+++ b/docs/api/store/paths/store_customers_me_orders.yaml
@@ -1,28 +1,40 @@
 get:
   operationId: GetCustomersCustomerOrders
   summary: List Orders
-  description: Retrieves a list of a Customer's Orders.
+  description: >-
+    Retrieve a list of the logged-in Customer's Orders. The orders can be
+    filtered by fields such as `status` or `fulfillment_status`. The orders can
+    also be paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: q
-      description: Query used for searching orders.
+      description: >-
+        term to search orders' display ID, email, shipping address's first name,
+        customer's first name, customer's last name, and customer's phone
+        number.
       schema:
         type: string
     - in: query
       name: id
-      description: Id of the order to search for.
+      description: Filter by ID.
       schema:
         type: string
     - in: query
       name: status
       style: form
       explode: false
-      description: Status to search for.
+      description: Filter by status.
       schema:
         type: array
         items:
           type: string
+          enum:
+            - pending
+            - completed
+            - archived
+            - canceled
+            - requires_action
     - in: query
       name: fulfillment_status
       style: form
@@ -32,6 +44,16 @@ get:
         type: array
         items:
           type: string
+          enum:
+            - not_fulfilled
+            - partially_fulfilled
+            - fulfilled
+            - partially_shipped
+            - shipped
+            - partially_returned
+            - returned
+            - canceled
+            - requires_action
     - in: query
       name: payment_status
       style: form
@@ -41,31 +63,39 @@ get:
         type: array
         items:
           type: string
+          enum:
+            - not_paid
+            - awaiting
+            - captured
+            - partially_refunded
+            - refunded
+            - canceled
+            - requires_action
     - in: query
       name: display_id
-      description: Display id to search for.
+      description: Filter by display ID.
       schema:
         type: string
     - in: query
       name: cart_id
-      description: to search for.
+      description: Filter by cart ID.
       schema:
         type: string
     - in: query
       name: email
-      description: to search for.
+      description: Filter by email.
       schema:
         type: string
     - in: query
       name: region_id
-      description: to search for.
+      description: Filter by region ID.
       schema:
         type: string
     - in: query
       name: currency_code
       style: form
       explode: false
-      description: The 3 character ISO currency code to set prices based on.
+      description: Filter by the 3 character ISO currency code of the order.
       schema:
         type: string
         externalDocs:
@@ -73,12 +103,12 @@ get:
           description: See a list of codes.
     - in: query
       name: tax_rate
-      description: to search for.
+      description: Filter by tax rate.
       schema:
         type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting collections were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -100,7 +130,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting collections were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -122,7 +152,7 @@ get:
             format: date
     - in: query
       name: canceled_at
-      description: Date comparison for when resulting collections were canceled.
+      description: Filter by a cancelation date range.
       schema:
         type: object
         properties:
@@ -144,28 +174,26 @@ get:
             format: date
     - in: query
       name: limit
-      description: How many orders to return.
+      description: Limit the number of orders returned.
       schema:
         type: integer
         default: 10
     - in: query
       name: offset
-      description: The offset in the resulting orders.
+      description: The number of orders to skip when retrieving the orders.
       schema:
         type: integer
         default: 0
     - in: query
-      name: fields
+      name: expand
       description: >-
-        (Comma separated string) Which fields should be included in the
-        resulting orders.
+        Comma-separated relations that should be expanded in the returned
+        orders.
       schema:
         type: string
     - in: query
-      name: expand
-      description: >-
-        (Comma separated string) Which relations should be expanded in the
-        resulting orders.
+      name: fields
+      description: Comma-separated fields that should be included in the returned orders.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_customers_me_payment-methods.yaml b/docs/api/store/paths/store_customers_me_payment-methods.yaml
index 3f5dcd6639..f7cba3b220 100644
--- a/docs/api/store/paths/store_customers_me_payment-methods.yaml
+++ b/docs/api/store/paths/store_customers_me_payment-methods.yaml
@@ -1,11 +1,14 @@
 get:
   operationId: GetCustomersCustomerPaymentMethods
-  summary: Get Payment Methods
+  summary: Get Saved Payment Methods
   description: >-
-    Retrieves a list of a Customer's saved payment methods. Payment methods are
-    saved with Payment Providers and it is their responsibility to fetch saved
-    methods.
+    Retrieve the logged-in customer's saved payment methods. This endpoint only
+    works with payment providers created with the deprecated Payment Service
+    interface. The payment methods are saved using the Payment Service's
+    third-party service, and not on the Medusa backend. So, they're retrieved
+    from the third-party service.
   x-authenticated: true
+  deprecated: true
   x-codegen:
     method: listPaymentMethods
   x-codeSamples:
diff --git a/docs/api/store/paths/store_customers_password-reset.yaml b/docs/api/store/paths/store_customers_password-reset.yaml
index 78f71d059f..6aac430500 100644
--- a/docs/api/store/paths/store_customers_password-reset.yaml
+++ b/docs/api/store/paths/store_customers_password-reset.yaml
@@ -2,8 +2,13 @@ post:
   operationId: PostCustomersResetPassword
   summary: Reset Password
   description: >-
-    Resets a Customer's password using a password token created by a previous
-    /password-token request.
+    Reset a Customer's password using a password token created by a previous
+    request to the Request Password Reset endpoint. If the password token
+    expired, you must create a new one.
+  externalDocs:
+    description: How to reset password
+    url: >-
+      https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles#reset-password
   requestBody:
     content:
       application/json:
diff --git a/docs/api/store/paths/store_customers_password-token.yaml b/docs/api/store/paths/store_customers_password-token.yaml
index f49a22542c..df7843813e 100644
--- a/docs/api/store/paths/store_customers_password-token.yaml
+++ b/docs/api/store/paths/store_customers_password-token.yaml
@@ -2,9 +2,15 @@ post:
   operationId: PostCustomersCustomerPasswordToken
   summary: Request Password Reset
   description: >-
-    Creates a reset password token to be used in a subsequent /reset-password
-    request. The password token should be sent out of band e.g. via email and
-    will not be returned.
+    Create a reset password token to be used in a subsequent Reset Password
+    endpoint. This emits the event `customer.password_reset`. If a notification
+    provider is installed in the Medusa backend and is configured to handle this
+    event, a notification to the customer, such as an email, may be sent with
+    reset instructions.
+  externalDocs:
+    description: How to reset password
+    url: >-
+      https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles#reset-password
   requestBody:
     content:
       application/json:
diff --git a/docs/api/store/paths/store_gift-cards_{code}.yaml b/docs/api/store/paths/store_gift-cards_{code}.yaml
index dfba240fbb..7ae718781b 100644
--- a/docs/api/store/paths/store_gift-cards_{code}.yaml
+++ b/docs/api/store/paths/store_gift-cards_{code}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetGiftCardsCode
   summary: Get Gift Card by Code
-  description: Retrieves a Gift Card by its associated unique code.
+  description: Retrieve a Gift Card's details by its associated unique code.
   parameters:
     - in: path
       name: code
diff --git a/docs/api/store/paths/store_order-edits_{id}.yaml b/docs/api/store/paths/store_order-edits_{id}.yaml
index 4d77c09cf4..78432bf61d 100644
--- a/docs/api/store/paths/store_order-edits_{id}.yaml
+++ b/docs/api/store/paths/store_order-edits_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetOrderEditsOrderEdit
-  summary: Retrieve an OrderEdit
-  description: Retrieves a OrderEdit.
+  summary: Retrieve an Order Edit
+  description: Retrieve an Order Edit's details.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/store/paths/store_order-edits_{id}_complete.yaml b/docs/api/store/paths/store_order-edits_{id}_complete.yaml
index 39d132b04a..2ca13e864a 100644
--- a/docs/api/store/paths/store_order-edits_{id}_complete.yaml
+++ b/docs/api/store/paths/store_order-edits_{id}_complete.yaml
@@ -1,7 +1,13 @@
 post:
   operationId: PostOrderEditsOrderEditComplete
-  summary: Completes an OrderEdit
-  description: Completes an OrderEdit.
+  summary: Complete an Order Edit
+  description: >-
+    Complete an Order Edit and reflect its changes on the original order. Any
+    additional payment required must be authorized first using the Payment
+    Collection endpoints.
+  externalDocs:
+    description: How to handle order edits in a storefront
+    url: https://docs.medusajs.com/modules/orders/storefront/handle-order-edits
   parameters:
     - in: path
       name: id
diff --git a/docs/api/store/paths/store_order-edits_{id}_decline.yaml b/docs/api/store/paths/store_order-edits_{id}_decline.yaml
index 94fdff9486..b596bb8544 100644
--- a/docs/api/store/paths/store_order-edits_{id}_decline.yaml
+++ b/docs/api/store/paths/store_order-edits_{id}_decline.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostOrderEditsOrderEditDecline
-  summary: Decline an OrderEdit
-  description: Declines an OrderEdit.
+  summary: Decline an Order Edit
+  description: Decline an Order Edit. The changes are not reflected on the original order.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/store/paths/store_orders.yaml b/docs/api/store/paths/store_orders.yaml
index 9479e9bbc0..e649f00c70 100644
--- a/docs/api/store/paths/store_orders.yaml
+++ b/docs/api/store/paths/store_orders.yaml
@@ -1,29 +1,31 @@
 get:
   operationId: GetOrders
   summary: Look Up an Order
-  description: Look up an order using filters.
+  description: >-
+    Look up an order using filters. If the filters don't narrow down the results
+    to a single order, a 404 response is returned with no orders.
   parameters:
     - in: query
       name: display_id
       required: true
-      description: The display id given to the Order.
+      description: Filter by ID.
       schema:
         type: number
     - in: query
       name: fields
-      description: (Comma separated) Which fields should be included in the result.
+      description: Comma-separated fields that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in the result.
+      description: Comma-separated relations that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: email
       style: form
       explode: false
-      description: The email associated with this order.
+      description: Filter by email.
       required: true
       schema:
         type: string
@@ -32,7 +34,7 @@ get:
       name: shipping_address
       style: form
       explode: false
-      description: The shipping address associated with this order.
+      description: Filter by the shipping address's postal code.
       schema:
         type: object
         properties:
diff --git a/docs/api/store/paths/store_orders_batch_customer_token.yaml b/docs/api/store/paths/store_orders_batch_customer_token.yaml
index e8346ff429..beabeb5990 100644
--- a/docs/api/store/paths/store_orders_batch_customer_token.yaml
+++ b/docs/api/store/paths/store_orders_batch_customer_token.yaml
@@ -1,9 +1,18 @@
 post:
   operationId: PostOrdersCustomerOrderClaim
-  summary: Claim an Order
+  summary: Claim Order
   description: >-
-    Sends an email to emails registered to orders provided with link to transfer
-    order ownership
+    Allow the logged-in customer to claim ownership of one or more orders. This
+    generates a token that can be used later on to verify the claim using the
+    endpoint Verify Order Claim. This also emits the event
+    `order-update-token.created`. So, if you have a notification provider
+    installed that handles this event and sends the customer a notification,
+    such as an email, the customer should receive instructions on how to
+    finalize their claim ownership.
+  externalDocs:
+    description: How to implement claim-order flow in a storefront
+    url: https://docs.medusajs.com/modules/orders/storefront/implement-claim-order
+  x-authenticated: true
   requestBody:
     content:
       application/json:
diff --git a/docs/api/store/paths/store_orders_cart_{cart_id}.yaml b/docs/api/store/paths/store_orders_cart_{cart_id}.yaml
index 30780eb6ce..1e354fcbd3 100644
--- a/docs/api/store/paths/store_orders_cart_{cart_id}.yaml
+++ b/docs/api/store/paths/store_orders_cart_{cart_id}.yaml
@@ -1,7 +1,9 @@
 get:
   operationId: GetOrdersOrderCartId
   summary: Get by Cart ID
-  description: Retrieves an Order by the id of the Cart that was used to create the Order.
+  description: >-
+    Retrieve an Order's details by the ID of the Cart that was used to create
+    the Order.
   parameters:
     - in: path
       name: cart_id
diff --git a/docs/api/store/paths/store_orders_customer_confirm.yaml b/docs/api/store/paths/store_orders_customer_confirm.yaml
index e9b166bac6..d67043fb2f 100644
--- a/docs/api/store/paths/store_orders_customer_confirm.yaml
+++ b/docs/api/store/paths/store_orders_customer_confirm.yaml
@@ -1,9 +1,12 @@
 post:
   operationId: PostOrdersCustomerOrderClaimsCustomerOrderClaimAccept
-  summary: Verify an Order Claim
+  summary: Verify Order Claim
   description: >-
-    Verifies the claim order token provided to the customer upon request of
-    order ownership
+    Verify the claim order token provided to the customer when they request
+    ownership of an order.
+  externalDocs:
+    description: How to implement claim-order flow in a storefront
+    url: https://docs.medusajs.com/modules/orders/storefront/implement-claim-order
   requestBody:
     content:
       application/json:
diff --git a/docs/api/store/paths/store_orders_{id}.yaml b/docs/api/store/paths/store_orders_{id}.yaml
index 10f587f07d..c0e3c1cdd5 100644
--- a/docs/api/store/paths/store_orders_{id}.yaml
+++ b/docs/api/store/paths/store_orders_{id}.yaml
@@ -1,22 +1,22 @@
 get:
   operationId: GetOrdersOrder
   summary: Get an Order
-  description: Retrieves an Order
+  description: Retrieve an Order's details.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Order.
+      description: The ID of the Order.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Which fields should be included in the result.
+      description: Comma-separated fields that should be expanded in the returned order.
       schema:
         type: string
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in the result.
+      description: Comma-separated relations that should be included in the returned order.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_payment-collections_{id}.yaml b/docs/api/store/paths/store_payment-collections_{id}.yaml
index fd4b2aa306..d1b704a552 100644
--- a/docs/api/store/paths/store_payment-collections_{id}.yaml
+++ b/docs/api/store/paths/store_payment-collections_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetPaymentCollectionsPaymentCollection
   summary: Get a PaymentCollection
-  description: Get a Payment Collection
+  description: Retrieve a Payment Collection's details.
   x-authenticated: false
   parameters:
     - in: path
@@ -11,13 +11,17 @@ get:
       schema:
         type: string
     - in: query
-      name: expand
-      description: Comma separated list of relations to include in the results.
+      name: fields
+      description: >-
+        Comma-separated fields that should be expanded in the returned payment
+        collection.
       schema:
         type: string
     - in: query
-      name: fields
-      description: Comma separated list of fields to include in the results.
+      name: expand
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        payment collection.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_payment-collections_{id}_sessions.yaml b/docs/api/store/paths/store_payment-collections_{id}_sessions.yaml
index 24230b7395..773c1b66c9 100644
--- a/docs/api/store/paths/store_payment-collections_{id}_sessions.yaml
+++ b/docs/api/store/paths/store_payment-collections_{id}_sessions.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostPaymentCollectionsSessions
-  summary: Manage a Payment Session
-  description: Manages Payment Sessions from Payment Collections.
+  summary: Create a Payment Session
+  description: Create a Payment Session for a payment provider in a Payment Collection.
   x-authenticated: false
   parameters:
     - in: path
diff --git a/docs/api/store/paths/store_payment-collections_{id}_sessions_batch.yaml b/docs/api/store/paths/store_payment-collections_{id}_sessions_batch.yaml
index c894269f3b..4b7af56501 100644
--- a/docs/api/store/paths/store_payment-collections_{id}_sessions_batch.yaml
+++ b/docs/api/store/paths/store_payment-collections_{id}_sessions_batch.yaml
@@ -1,7 +1,10 @@
 post:
   operationId: PostPaymentCollectionsPaymentCollectionSessionsBatch
   summary: Manage Payment Sessions
-  description: Manages Multiple Payment Sessions from Payment Collections.
+  description: >-
+    Create, update, or delete a list of payment sessions of a Payment
+    Collections. If a payment session is not provided in the `sessions` array,
+    it's deleted.
   x-authenticated: false
   parameters:
     - in: path
diff --git a/docs/api/store/paths/store_payment-collections_{id}_sessions_batch_authorize.yaml b/docs/api/store/paths/store_payment-collections_{id}_sessions_batch_authorize.yaml
index a3bb6178f7..1936a27dba 100644
--- a/docs/api/store/paths/store_payment-collections_{id}_sessions_batch_authorize.yaml
+++ b/docs/api/store/paths/store_payment-collections_{id}_sessions_batch_authorize.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostPaymentCollectionsSessionsBatchAuthorize
   summary: Authorize PaymentSessions
-  description: Authorizes Payment Sessions of a Payment Collection.
+  description: Authorize the Payment Sessions of a Payment Collection.
   x-authenticated: false
   parameters:
     - in: path
diff --git a/docs/api/store/paths/store_payment-collections_{id}_sessions_{session_id}.yaml b/docs/api/store/paths/store_payment-collections_{id}_sessions_{session_id}.yaml
index 746d8cec0c..52a4a4772f 100644
--- a/docs/api/store/paths/store_payment-collections_{id}_sessions_{session_id}.yaml
+++ b/docs/api/store/paths/store_payment-collections_{id}_sessions_{session_id}.yaml
@@ -2,8 +2,8 @@ post:
   operationId: PostPaymentCollectionsPaymentCollectionPaymentSessionsSession
   summary: Refresh a Payment Session
   description: >-
-    Refreshes a Payment Session to ensure that it is in sync with the Payment
-    Collection.
+    Refresh a Payment Session's data to ensure that it is in sync with the
+    Payment Collection.
   x-authenticated: false
   parameters:
     - in: path
diff --git a/docs/api/store/paths/store_payment-collections_{id}_sessions_{session_id}_authorize.yaml b/docs/api/store/paths/store_payment-collections_{id}_sessions_{session_id}_authorize.yaml
index 3d41bc7feb..962ac58bcc 100644
--- a/docs/api/store/paths/store_payment-collections_{id}_sessions_{session_id}_authorize.yaml
+++ b/docs/api/store/paths/store_payment-collections_{id}_sessions_{session_id}_authorize.yaml
@@ -1,7 +1,7 @@
 post:
   operationId: PostPaymentCollectionsSessionsSessionAuthorize
   summary: Authorize Payment Session
-  description: Authorizes a Payment Session of a Payment Collection.
+  description: Authorize a Payment Session of a Payment Collection.
   x-authenticated: false
   parameters:
     - in: path
diff --git a/docs/api/store/paths/store_product-categories.yaml b/docs/api/store/paths/store_product-categories.yaml
index f6c21f81be..7fb0a808fa 100644
--- a/docs/api/store/paths/store_product-categories.yaml
+++ b/docs/api/store/paths/store_product-categories.yaml
@@ -1,32 +1,44 @@
 get:
   operationId: GetProductCategories
   summary: List Product Categories
-  description: Retrieve a list of product categories.
-  x-authenticated: false
+  description: >-
+    Retrieve a list of product categories. The product categories can be
+    filtered by fields such as `handle` or `q`. The product categories can also
+    be paginated. This endpoint can also be used to retrieve a product category
+    by its handle.
+  x-featureFlag: product_categories
+  externalDocs:
+    description: How to retrieve a product category by its handle
+    url: >-
+      https://docs.medusajs.com/modules/products/storefront/use-categories#get-a-category-by-its-handle
   parameters:
     - in: query
       name: q
-      description: Query used for searching product category names or handles.
+      description: term used to search product category's names and handles.
       schema:
         type: string
     - in: query
       name: handle
-      description: Query used for searching product category by handle.
+      description: Filter by handle.
       schema:
         type: string
     - in: query
       name: parent_category_id
-      description: Returns categories scoped by parent
+      description: >-
+        Filter by the ID of a parent category. Only children of the provided
+        parent category are retrieved.
       schema:
         type: string
     - in: query
       name: include_descendants_tree
-      description: Include all nested descendants of category
+      description: Whether all nested categories inside a category should be retrieved.
       schema:
         type: boolean
     - in: query
       name: offset
-      description: How many product categories to skip in the result.
+      description: >-
+        The number of product categories to skip when retrieving the product
+        categories.
       schema:
         type: integer
         default: 0
@@ -36,6 +48,20 @@ get:
       schema:
         type: integer
         default: 100
+    - in: query
+      name: expand
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        product categories.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: >-
+        Comma-separated fields that should be included in the returned product
+        categories.
+      schema:
+        type: string
   x-codegen:
     method: list
     queryParams: StoreGetProductCategoriesParams
diff --git a/docs/api/store/paths/store_product-categories_{id}.yaml b/docs/api/store/paths/store_product-categories_{id}.yaml
index a066d66be8..a1052982c5 100644
--- a/docs/api/store/paths/store_product-categories_{id}.yaml
+++ b/docs/api/store/paths/store_product-categories_{id}.yaml
@@ -1,8 +1,8 @@
 get:
   operationId: GetProductCategoriesCategory
   summary: Get a Product Category
-  description: Retrieves a Product Category.
-  x-authenticated: false
+  description: Retrieve a Product Category's details.
+  x-featureFlag: product_categories
   parameters:
     - in: path
       name: id
@@ -11,17 +11,17 @@ get:
       schema:
         type: string
     - in: query
-      name: expand
+      name: fields
       description: >-
-        (Comma separated) Which fields should be expanded in each product
+        Comma-separated fields that should be expanded in the returned product
         category.
       schema:
         type: string
     - in: query
-      name: fields
+      name: expand
       description: >-
-        (Comma separated) Which fields should be retrieved in each product
-        category.
+        Comma-separated relations that should be expanded in the returned
+        product category.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_product-tags.yaml b/docs/api/store/paths/store_product-tags.yaml
index 14ef6c1a86..5221ed8ae2 100644
--- a/docs/api/store/paths/store_product-tags.yaml
+++ b/docs/api/store/paths/store_product-tags.yaml
@@ -1,7 +1,9 @@
 get:
   operationId: GetProductTags
   summary: List Product Tags
-  description: Retrieve a list of Product Tags.
+  description: >-
+    Retrieve a list of product tags. The product tags can be filtered by fields
+    such as `id` or `q`. The product tags can also be sorted or paginated.
   x-authenticated: true
   x-codegen:
     method: list
@@ -9,31 +11,33 @@ get:
   parameters:
     - in: query
       name: limit
-      description: The number of types to return.
+      description: Limit the number of product tags returned.
       schema:
         type: integer
         default: 20
     - in: query
       name: offset
-      description: The number of items to skip before the results.
+      description: The number of product tags to skip when retrieving the product tags.
       schema:
         type: integer
         default: 0
     - in: query
       name: order
-      description: The field to sort items by.
+      description: A product-tag field to sort-order the retrieved product tags by.
       schema:
         type: string
     - in: query
       name: discount_condition_id
-      description: The discount condition id on which to filter the product tags.
+      description: >-
+        Filter by the ID of a discount condition. When provided, only tags that
+        the discount condition applies for will be retrieved.
       schema:
         type: string
     - in: query
       name: value
       style: form
       explode: false
-      description: The tag values to search for
+      description: Filter by tag values.
       schema:
         type: array
         items:
@@ -42,19 +46,19 @@ get:
       name: id
       style: form
       explode: false
-      description: The tag IDs to search for
+      description: Filter by IDs.
       schema:
         type: array
         items:
           type: string
     - in: query
       name: q
-      description: A query string to search values for
+      description: term to search product tag's value.
       schema:
         type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting product tags were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -76,7 +80,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting product tags were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
diff --git a/docs/api/store/paths/store_product-types.yaml b/docs/api/store/paths/store_product-types.yaml
index c562e8f096..b079d2da97 100644
--- a/docs/api/store/paths/store_product-types.yaml
+++ b/docs/api/store/paths/store_product-types.yaml
@@ -1,36 +1,41 @@
 get:
   operationId: GetProductTypes
   summary: List Product Types
-  description: Retrieve a list of Product Types.
+  description: >-
+    Retrieve a list of product types. The product types can be filtered by
+    fields such as `value` or `q`. The product types can also be sorted or
+    paginated.
   x-authenticated: true
   parameters:
     - in: query
       name: limit
-      description: The number of types to return.
+      description: Limit the number of product types returned.
       schema:
         type: integer
         default: 20
     - in: query
       name: offset
-      description: The number of items to skip before the results.
+      description: The number of product types to skip when retrieving the product types.
       schema:
         type: integer
         default: 0
     - in: query
       name: order
-      description: The field to sort items by.
+      description: A product-type field to sort-order the retrieved product types by.
       schema:
         type: string
     - in: query
       name: discount_condition_id
-      description: The discount condition id on which to filter the product types.
+      description: >-
+        Filter by the ID of a discount condition. When provided, only types that
+        the discount condition applies for will be retrieved.
       schema:
         type: string
     - in: query
       name: value
       style: form
       explode: false
-      description: The type values to search for
+      description: Filter by type values.
       schema:
         type: array
         items:
@@ -39,19 +44,19 @@ get:
       name: id
       style: form
       explode: false
-      description: The type IDs to search for
+      description: Filter by IDs.
       schema:
         type: array
         items:
           type: string
     - in: query
       name: q
-      description: A query string to search values for
+      description: term to search product type's value.
       schema:
         type: string
     - in: query
       name: created_at
-      description: Date comparison for when resulting product types were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -73,7 +78,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting product types were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
diff --git a/docs/api/store/paths/store_products.yaml b/docs/api/store/paths/store_products.yaml
index 6e57992712..c6d9cfe224 100644
--- a/docs/api/store/paths/store_products.yaml
+++ b/docs/api/store/paths/store_products.yaml
@@ -1,20 +1,41 @@
 get:
   operationId: GetProducts
   summary: List Products
-  description: Retrieves a list of Products.
+  description: >
+    Retrieves a list of products. The products can be filtered by fields such as
+    `id` or `q`. The products can also be sorted or paginated.
+
+    This endpoint can also be used to retrieve a product by its handle.
+
+
+    For accurate and correct pricing of the products based on the customer's
+    context, it's highly recommended to pass fields such as
+
+    `region_id`, `currency_code`, and `cart_id` when available.
+
+
+    Passing `sales_channel_id` ensures retrieving only products available in the
+    specified sales channel.
+
+    You can alternatively use a publishable API key in the request header
+    instead of passing a `sales_channel_id`.
+  externalDocs:
+    description: How to retrieve a product by its handle
+    url: >-
+      https://docs.medusajs.com/modules/products/storefront/show-products#retrieve-product-by-handle
   parameters:
     - in: query
       name: q
       description: >-
-        Query used for searching products by title, description, variant's
-        title, variant's sku, and collection's title
+        term used to search products' title, description, variant's title,
+        variant's sku, and collection's title.
       schema:
         type: string
     - in: query
       name: id
       style: form
       explode: false
-      description: product IDs to search for.
+      description: Filter by IDs.
       schema:
         oneOf:
           - type: string
@@ -25,7 +46,11 @@ get:
       name: sales_channel_id
       style: form
       explode: false
-      description: an array of sales channel IDs to filter the retrieved products by.
+      description: >-
+        Filter by sales channel IDs. When provided, only products available in
+        the selected sales channels are retrieved. Alternatively, you can pass a
+        publishable API key in the request header and this will have the same
+        effect.
       schema:
         type: array
         items:
@@ -34,7 +59,9 @@ get:
       name: collection_id
       style: form
       explode: false
-      description: Collection IDs to search for
+      description: >-
+        Filter by product collection IDs. When provided, only products that
+        belong to the specified product collections are retrieved.
       schema:
         type: array
         items:
@@ -43,7 +70,9 @@ get:
       name: type_id
       style: form
       explode: false
-      description: Type IDs to search for
+      description: >-
+        Filter by product type IDs. When provided, only products that belong to
+        the specified product types are retrieved.
       schema:
         type: array
         items:
@@ -52,34 +81,36 @@ get:
       name: tags
       style: form
       explode: false
-      description: Tag IDs to search for
+      description: >-
+        Filter by product tag IDs. When provided, only products that belong to
+        the specified product tags are retrieved.
       schema:
         type: array
         items:
           type: string
     - in: query
       name: title
-      description: title to search for.
+      description: Filter by title.
       schema:
         type: string
     - in: query
       name: description
-      description: description to search for.
+      description: Filter by description
       schema:
         type: string
     - in: query
       name: handle
-      description: handle to search for.
+      description: Filter by handle.
       schema:
         type: string
     - in: query
       name: is_giftcard
-      description: Search for giftcards using is_giftcard=true.
+      description: Whether to retrieve regular products or gift-card products.
       schema:
         type: boolean
     - in: query
       name: created_at
-      description: Date comparison for when resulting products were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -101,7 +132,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting products were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
@@ -125,19 +156,27 @@ get:
       name: category_id
       style: form
       explode: false
-      description: Category ids to filter by.
+      description: >-
+        Filter by product category IDs. When provided, only products that belong
+        to the specified product categories are retrieved.
       schema:
         type: array
+        x-featureFlag: product_categories
         items:
           type: string
     - in: query
       name: include_category_children
-      description: Include category children when filtering by category_id.
+      style: form
+      explode: false
+      description: >-
+        Whether to include child product categories when filtering using the
+        `category_id` field.
       schema:
         type: boolean
+        x-featureFlag: product_categories
     - in: query
       name: offset
-      description: How many products to skip in the result.
+      description: The number of products to skip when retrieving the products.
       schema:
         type: integer
         default: 0
@@ -150,37 +189,46 @@ get:
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each product of the
-        result.
+        Comma-separated relations that should be expanded in the returned
+        products.
       schema:
         type: string
     - in: query
       name: fields
-      description: >-
-        (Comma separated) Which fields should be included in each product of the
-        result.
+      description: Comma-separated fields that should be included in the returned products.
       schema:
         type: string
     - in: query
       name: order
-      description: the field used to order the products.
+      description: A product field to sort-order the retrieved products by.
       schema:
         type: string
     - in: query
       name: cart_id
-      description: The id of the Cart to set prices based on.
+      description: >-
+        The ID of the cart. This is useful for accurate pricing based on the
+        cart's context.
       schema:
         type: string
     - in: query
       name: region_id
-      description: The id of the Region to set prices based on.
+      description: >-
+        The ID of the region. This is useful for accurate pricing based on the
+        selected region.
       schema:
         type: string
     - in: query
       name: currency_code
-      description: The currency code to use for price selection.
+      style: form
+      explode: false
+      description: >-
+        A 3 character ISO currency code. This is useful for accurate pricing
+        based on the selected currency.
       schema:
         type: string
+        externalDocs:
+          url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+          description: See a list of codes.
   x-codegen:
     method: list
     queryParams: StoreGetProductsParams
diff --git a/docs/api/store/paths/store_products_search.yaml b/docs/api/store/paths/store_products_search.yaml
index d1cec1b314..06eeecdf7c 100644
--- a/docs/api/store/paths/store_products_search.yaml
+++ b/docs/api/store/paths/store_products_search.yaml
@@ -1,7 +1,10 @@
 post:
   operationId: PostProductsSearch
   summary: Search Products
-  description: Run a search query on products using the search engine installed on Medusa
+  description: >-
+    Run a search query on products using the search service installed on the
+    Medusa backend. The searching is handled through the search service, so the
+    returned data's format depends on the search service you're using.
   requestBody:
     content:
       application/json:
diff --git a/docs/api/store/paths/store_products_{id}.yaml b/docs/api/store/paths/store_products_{id}.yaml
index 7cc2bcad51..c4d0a3520f 100644
--- a/docs/api/store/paths/store_products_{id}.yaml
+++ b/docs/api/store/paths/store_products_{id}.yaml
@@ -1,41 +1,59 @@
 get:
   operationId: GetProductsProduct
   summary: Get a Product
-  description: Retrieves a Product.
+  description: >
+    Retrieve a Product's details. For accurate and correct pricing of the
+    product based on the customer's context, it's highly recommended to pass
+    fields such as
+
+    `region_id`, `currency_code`, and `cart_id` when available.
+
+
+    Passing `sales_channel_id` ensures retrieving only products available in the
+    current sales channel.
+
+    You can alternatively use a publishable API key in the request header
+    instead of passing a `sales_channel_id`.
+  externalDocs:
+    description: How to pass product pricing parameters
+    url: >-
+      https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Product.
+      description: The ID of the Product.
       schema:
         type: string
     - in: query
       name: sales_channel_id
-      description: The sales channel used when fetching the product.
+      description: The ID of the sales channel the customer is viewing the product from.
       schema:
         type: string
     - in: query
       name: cart_id
-      description: The ID of the customer's cart.
+      description: >-
+        The ID of the cart. This is useful for accurate pricing based on the
+        cart's context.
       schema:
         type: string
     - in: query
       name: region_id
       description: >-
-        The ID of the region the customer is using. This is helpful to ensure
-        correct prices are retrieved for a region.
-      schema:
-        type: string
-    - in: query
-      name: fields
-      description: (Comma separated) Which fields should be included in the result.
+        The ID of the region. This is useful for accurate pricing based on the
+        selected region.
       schema:
         type: string
     - in: query
       name: expand
       description: >-
-        (Comma separated) Which fields should be expanded in each product of the
-        result.
+        Comma-separated relations that should be expanded in the returned
+        product.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: Comma-separated fields that should be included in the returned product.
       schema:
         type: string
     - in: query
@@ -43,8 +61,8 @@ get:
       style: form
       explode: false
       description: >-
-        The 3 character ISO currency code to set prices based on. This is
-        helpful to ensure correct prices are retrieved for a currency.
+        A 3 character ISO currency code. This is useful for accurate pricing
+        based on the selected currency.
       schema:
         type: string
         externalDocs:
diff --git a/docs/api/store/paths/store_regions.yaml b/docs/api/store/paths/store_regions.yaml
index 5004737470..5d129c1ff9 100644
--- a/docs/api/store/paths/store_regions.yaml
+++ b/docs/api/store/paths/store_regions.yaml
@@ -1,11 +1,18 @@
 get:
   operationId: GetRegions
   summary: List Regions
-  description: Retrieves a list of Regions.
+  description: >-
+    Retrieve a list of regions. The regions can be filtered by fields such as
+    `created_at`. The regions can also be paginated. This endpoint is useful to
+    show the customer all available regions to choose from.
+  externalDocs:
+    description: How to use regions in a storefront
+    url: >-
+      https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions
   parameters:
     - in: query
       name: offset
-      description: How many regions to skip in the result.
+      description: The number of regions to skip when retrieving the regions.
       schema:
         type: integer
         default: 0
@@ -17,7 +24,7 @@ get:
         default: 100
     - in: query
       name: created_at
-      description: Date comparison for when resulting regions were created.
+      description: Filter by a creation date range.
       schema:
         type: object
         properties:
@@ -39,7 +46,7 @@ get:
             format: date
     - in: query
       name: updated_at
-      description: Date comparison for when resulting regions were updated.
+      description: Filter by an update date range.
       schema:
         type: object
         properties:
diff --git a/docs/api/store/paths/store_regions_{id}.yaml b/docs/api/store/paths/store_regions_{id}.yaml
index 1754659804..a3300e413a 100644
--- a/docs/api/store/paths/store_regions_{id}.yaml
+++ b/docs/api/store/paths/store_regions_{id}.yaml
@@ -1,12 +1,12 @@
 get:
   operationId: GetRegionsRegion
   summary: Get a Region
-  description: Retrieves a Region.
+  description: Retrieve a Region's details.
   parameters:
     - in: path
       name: id
       required: true
-      description: The id of the Region.
+      description: The ID of the Region.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_return-reasons.yaml b/docs/api/store/paths/store_return-reasons.yaml
index cf06804410..8ad0f52a7a 100644
--- a/docs/api/store/paths/store_return-reasons.yaml
+++ b/docs/api/store/paths/store_return-reasons.yaml
@@ -1,7 +1,9 @@
 get:
   operationId: GetReturnReasons
   summary: List Return Reasons
-  description: Retrieves a list of Return Reasons.
+  description: >-
+    Retrieve a list of Return Reasons. This is useful when implementing a Create
+    Return flow in the storefront.
   x-codegen:
     method: list
   x-codeSamples:
diff --git a/docs/api/store/paths/store_return-reasons_{id}.yaml b/docs/api/store/paths/store_return-reasons_{id}.yaml
index e7bc32989a..5d7176ee73 100644
--- a/docs/api/store/paths/store_return-reasons_{id}.yaml
+++ b/docs/api/store/paths/store_return-reasons_{id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetReturnReasonsReason
   summary: Get a Return Reason
-  description: Retrieves a Return Reason.
+  description: Retrieve a Return Reason's details.
   parameters:
     - in: path
       name: id
diff --git a/docs/api/store/paths/store_returns.yaml b/docs/api/store/paths/store_returns.yaml
index 644e8b36fd..3cd268be36 100644
--- a/docs/api/store/paths/store_returns.yaml
+++ b/docs/api/store/paths/store_returns.yaml
@@ -1,7 +1,12 @@
 post:
   operationId: PostReturns
   summary: Create Return
-  description: Creates a Return for an Order.
+  description: >-
+    Create a Return for an Order. If a return shipping method is specified, the
+    return is automatically fulfilled.
+  externalDocs:
+    description: How to create a return in a storefront
+    url: https://docs.medusajs.com/modules/orders/storefront/create-return
   requestBody:
     content:
       application/json:
diff --git a/docs/api/store/paths/store_shipping-options.yaml b/docs/api/store/paths/store_shipping-options.yaml
index 7e695789cb..6c7fc4e360 100644
--- a/docs/api/store/paths/store_shipping-options.yaml
+++ b/docs/api/store/paths/store_shipping-options.yaml
@@ -1,23 +1,28 @@
 get:
   operationId: GetShippingOptions
   summary: Get Shipping Options
-  description: Retrieves a list of Shipping Options.
+  description: Retrieve a list of Shipping Options.
   parameters:
     - in: query
       name: is_return
       description: >-
-        Whether return Shipping Options should be included. By default all
-        Shipping Options are returned.
+        Whether return shipping options should be included. By default, all
+        shipping options are returned.
       schema:
         type: boolean
     - in: query
       name: product_ids
-      description: A comma separated list of Product ids to filter Shipping Options by.
+      description: >-
+        "Comma-separated list of Product IDs to filter Shipping Options by. If
+        provided, only shipping options that can be used with the provided
+        products are retrieved."
       schema:
         type: string
     - in: query
       name: region_id
-      description: the Region to retrieve Shipping Options from.
+      description: >-
+        "The ID of the region that the shipping options belong to. If not
+        provided, all shipping options are retrieved."
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_shipping-options_{cart_id}.yaml b/docs/api/store/paths/store_shipping-options_{cart_id}.yaml
index 47056d05e1..0303724297 100644
--- a/docs/api/store/paths/store_shipping-options_{cart_id}.yaml
+++ b/docs/api/store/paths/store_shipping-options_{cart_id}.yaml
@@ -1,12 +1,16 @@
 get:
   operationId: GetShippingOptionsCartId
   summary: List for Cart
-  description: Retrieves a list of Shipping Options available to a cart.
+  description: Retrieve a list of Shipping Options available for a cart.
+  externalDocs:
+    description: How to implement shipping step in checkout
+    url: >-
+      https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-checkout-flow#shipping-step
   parameters:
     - in: path
       name: cart_id
       required: true
-      description: The id of the Cart.
+      description: The ID of the Cart.
       schema:
         type: string
   x-codegen:
diff --git a/docs/api/store/paths/store_swaps.yaml b/docs/api/store/paths/store_swaps.yaml
index cd06c487bf..7a6e64878f 100644
--- a/docs/api/store/paths/store_swaps.yaml
+++ b/docs/api/store/paths/store_swaps.yaml
@@ -1,9 +1,26 @@
 post:
   operationId: PostSwaps
   summary: Create a Swap
-  description: >-
-    Creates a Swap on an Order by providing some items to return along with some
-    items to send back
+  description: >
+    Create a Swap for an Order. This will also create a return and associate it
+    with the swap. If a return shipping option is specified, the return will
+    automatically be fulfilled.
+
+    To complete the swap, you must use the Complete Cart endpoint passing it the
+    ID of the swap's cart.
+
+
+    An idempotency key will be generated if none is provided in the header
+    `Idempotency-Key` and added to
+
+    the response. If an error occurs during swap creation or the request is
+    interrupted for any reason, the swap creation can be retried by passing the
+    idempotency
+
+    key in the `Idempotency-Key` header.
+  externalDocs:
+    description: How to create a swap
+    url: https://docs.medusajs.com/modules/orders/storefront/create-swap
   requestBody:
     content:
       application/json:
diff --git a/docs/api/store/paths/store_swaps_{cart_id}.yaml b/docs/api/store/paths/store_swaps_{cart_id}.yaml
index 8bccd19bbb..d01ff474b7 100644
--- a/docs/api/store/paths/store_swaps_{cart_id}.yaml
+++ b/docs/api/store/paths/store_swaps_{cart_id}.yaml
@@ -1,7 +1,7 @@
 get:
   operationId: GetSwapsSwapCartId
   summary: Get by Cart ID
-  description: Retrieves a Swap by the id of the Cart used to confirm the Swap.
+  description: Retrieve a Swap's details by the ID of its cart.
   parameters:
     - in: path
       name: cart_id
diff --git a/docs/api/store/paths/store_variants.yaml b/docs/api/store/paths/store_variants.yaml
index fd071c0f97..f4a5a30887 100644
--- a/docs/api/store/paths/store_variants.yaml
+++ b/docs/api/store/paths/store_variants.yaml
@@ -1,61 +1,122 @@
 get:
   operationId: GetVariants
   summary: Get Product Variants
-  description: Retrieves a list of Product Variants
+  description: >
+    Retrieves a list of product variants. The product variants can be filtered
+    by fields such as `id` or `title`. The product variants can also be
+    paginated.
+
+
+    For accurate and correct pricing of the product variants based on the
+    customer's context, it's highly recommended to pass fields such as
+
+    `region_id`, `currency_code`, and `cart_id` when available.
+
+
+    Passing `sales_channel_id` ensures retrieving only variants of products
+    available in the specified sales channel.
+
+    You can alternatively use a publishable API key in the request header
+    instead of passing a `sales_channel_id`.
+  externalDocs:
+    description: How to pass product pricing parameters
+    url: >-
+      https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters
   parameters:
     - in: query
       name: ids
-      description: A comma separated list of Product Variant ids to filter by.
+      description: >-
+        Filter by a comma-separated list of IDs. If supplied, it overrides the
+        `id` parameter.
       schema:
         type: string
+    - in: query
+      name: id
+      style: form
+      explode: false
+      description: >-
+        Filter by one or more IDs. If `ids` is supplied, it's overrides the
+        value of this parameter.
+      schema:
+        oneOf:
+          - type: string
+            description: Filter by an ID.
+          - type: array
+            description: Filter by IDs.
+            items:
+              type: string
     - in: query
       name: sales_channel_id
-      description: A sales channel id for result configuration.
+      description: >-
+        "Filter by sales channel IDs. When provided, only products available in
+        the selected sales channels are retrieved. Alternatively, you can pass a
+        publishable API key in the request header and this will have the same
+        effect."
       schema:
         type: string
     - in: query
       name: expand
-      description: A comma separated list of Product Variant relations to load.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        product variants.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: >-
+        Comma-separated fields that should be included in the returned product
+        variants.
       schema:
         type: string
     - in: query
       name: offset
-      description: How many product variants to skip in the result.
+      description: The number of products to skip when retrieving the product variants.
       schema:
         type: number
         default: '0'
     - in: query
       name: limit
-      description: Maximum number of Product Variants to return.
+      description: Limit the number of product variants returned.
       schema:
         type: number
         default: '100'
     - in: query
       name: cart_id
-      description: The id of the Cart to set prices based on.
+      description: >-
+        The ID of the cart. This is useful for accurate pricing based on the
+        cart's context.
       schema:
         type: string
     - in: query
       name: region_id
-      description: The id of the Region to set prices based on.
+      description: >-
+        The ID of the region. This is useful for accurate pricing based on the
+        selected region.
       schema:
         type: string
     - in: query
       name: currency_code
-      description: The currency code to use for price selection.
+      style: form
+      explode: false
+      description: >-
+        A 3 character ISO currency code. This is useful for accurate pricing
+        based on the selected currency.
       schema:
         type: string
+        externalDocs:
+          url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+          description: See a list of codes.
     - in: query
       name: title
       style: form
       explode: false
-      description: product variant title to search for.
+      description: Filter by title
       schema:
         oneOf:
           - type: string
-            description: a single title to search by
+            description: a single title to filter by
           - type: array
-            description: multiple titles to search by
+            description: multiple titles to filter by
             items:
               type: string
     - in: query
@@ -64,23 +125,23 @@ get:
       schema:
         oneOf:
           - type: number
-            description: a specific number to search by.
+            description: A specific number to filter by.
           - type: object
-            description: search using less and greater than comparisons.
+            description: Filter using less and greater than comparisons.
             properties:
               lt:
                 type: number
-                description: filter by inventory quantity less than this number
+                description: Filter by inventory quantity less than this number
               gt:
                 type: number
-                description: filter by inventory quantity greater than this number
+                description: Filter by inventory quantity greater than this number
               lte:
                 type: number
-                description: filter by inventory quantity less than or equal to this number
+                description: Filter by inventory quantity less than or equal to this number
               gte:
                 type: number
                 description: >-
-                  filter by inventory quantity greater than or equal to this
+                  Filter by inventory quantity greater than or equal to this
                   number
   x-codegen:
     method: list
@@ -91,7 +152,7 @@ get:
       source:
         $ref: ../code_samples/Shell/store_variants/get.sh
   tags:
-    - Variants
+    - Product Variants
   responses:
     '200':
       description: OK
diff --git a/docs/api/store/paths/store_variants_{id}.yaml b/docs/api/store/paths/store_variants_{id}.yaml
new file mode 100644
index 0000000000..78ae0da5c7
--- /dev/null
+++ b/docs/api/store/paths/store_variants_{id}.yaml
@@ -0,0 +1,87 @@
+get:
+  operationId: GetVariantsVariant
+  summary: Get a Product Variant
+  description: >
+    Retrieve a Product Variant's details. For accurate and correct pricing of
+    the product variant based on the customer's context, it's highly recommended
+    to pass fields such as
+
+    `region_id`, `currency_code`, and `cart_id` when available.
+
+
+    Passing `sales_channel_id` ensures retrieving only variants of products
+    available in the current sales channel.
+
+    You can alternatively use a publishable API key in the request header
+    instead of passing a `sales_channel_id`.
+  externalDocs:
+    description: How to pass product pricing parameters
+    url: >-
+      https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Product Variant.
+      schema:
+        type: string
+    - in: query
+      name: sales_channel_id
+      description: >-
+        The ID of the sales channel the customer is viewing the product variant
+        from.
+      schema:
+        type: string
+    - in: query
+      name: cart_id
+      description: >-
+        The ID of the cart. This is useful for accurate pricing based on the
+        cart's context.
+      schema:
+        type: string
+    - in: query
+      name: region_id
+      description: >-
+        The ID of the region. This is useful for accurate pricing based on the
+        selected region.
+      schema:
+        type: string
+    - in: query
+      name: currency_code
+      style: form
+      explode: false
+      description: >-
+        A 3 character ISO currency code. This is useful for accurate pricing
+        based on the selected currency.
+      schema:
+        type: string
+        externalDocs:
+          url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+          description: See a list of codes.
+  x-codegen:
+    method: retrieve
+    queryParams: StoreGetVariantsVariantParams
+  x-codeSamples:
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: ../code_samples/Shell/store_variants_{id}/get.sh
+  tags:
+    - Product Variants
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/StoreVariantsRes.yaml
+    '400':
+      $ref: ../components/responses/400_error.yaml
+    '404':
+      $ref: ../components/responses/not_found_error.yaml
+    '409':
+      $ref: ../components/responses/invalid_state_error.yaml
+    '422':
+      $ref: ../components/responses/invalid_request_error.yaml
+    '500':
+      $ref: ../components/responses/500_error.yaml
diff --git a/docs/api/store/paths/store_variants_{variant_id}.yaml b/docs/api/store/paths/store_variants_{variant_id}.yaml
deleted file mode 100644
index 9270e2839c..0000000000
--- a/docs/api/store/paths/store_variants_{variant_id}.yaml
+++ /dev/null
@@ -1,63 +0,0 @@
-get:
-  operationId: GetVariantsVariant
-  summary: Get a Product Variant
-  description: Retrieves a Product Variant by id
-  parameters:
-    - in: path
-      name: variant_id
-      required: true
-      description: The id of the Product Variant.
-      schema:
-        type: string
-    - in: query
-      name: cart_id
-      description: The id of the Cart to set prices based on.
-      schema:
-        type: string
-    - in: query
-      name: sales_channel_id
-      description: A sales channel id for result configuration.
-      schema:
-        type: string
-    - in: query
-      name: region_id
-      description: The id of the Region to set prices based on.
-      schema:
-        type: string
-    - in: query
-      name: currency_code
-      style: form
-      explode: false
-      description: The 3 character ISO currency code to set prices based on.
-      schema:
-        type: string
-        externalDocs:
-          url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
-          description: See a list of codes.
-  x-codegen:
-    method: retrieve
-    queryParams: StoreGetVariantsVariantParams
-  x-codeSamples:
-    - lang: Shell
-      label: cURL
-      source:
-        $ref: ../code_samples/Shell/store_variants_{variant_id}/get.sh
-  tags:
-    - Variants
-  responses:
-    '200':
-      description: OK
-      content:
-        application/json:
-          schema:
-            $ref: ../components/schemas/StoreVariantsRes.yaml
-    '400':
-      $ref: ../components/responses/400_error.yaml
-    '404':
-      $ref: ../components/responses/not_found_error.yaml
-    '409':
-      $ref: ../components/responses/invalid_state_error.yaml
-    '422':
-      $ref: ../components/responses/invalid_request_error.yaml
-    '500':
-      $ref: ../components/responses/500_error.yaml