docs: added currency documentation pages (#3803)

* docs: added currency documentation pages

* fixes to OAS

docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx

@@ -0,0 +1,435 @@
+---
+description: 'Learn how to manage currencies using the Admin APIs. This includes how to list and update currencies, and how to manage currencies in a store.'
+addHowToData: true
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# How to Manage Currencies Using Admin APIs
+
+In this document, you’ll learn how to manage currencies using the Admin APIs.
+
+## Overview
+
+The currencies admin APIs allow you to manage currencies in your commerce store.
+
+Currencies are available in your commerce system, even if they’re not added to the store. This guide explains how to manage currencies globally, and how to manage them from a store’s context.
+
+### Scenario
+
+You want to add or use the following admin functionalities:
+
+- List currencies
+- Update a currency
+- Manage currencies in a store including listing, adding, and removing currencies from a store.
+
+:::note
+
+As explained in the [Currencies architecture guide](../currencies.md), currencies are created through migrations. So, you can’t create a currency through the admin APIs.
+
+:::
+
+---
+
+## Prerequisites
+
+### Medusa Components
+
+It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../../development/backend/install.mdx) to get started.
+
+### JS Client
+
+This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.
+
+If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration).
+
+### Medusa React
+
+This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.
+
+If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).
+
+### Authenticated Admin User
+
+You must be an authenticated admin user before following along with the steps in the tutorial.
+
+You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication).
+
+---
+
+## List Currencies
+
+You can list all available currencies in your system by sending a request to the [List Currencies endpoint](/api/admin#tag/Currencies/operation/GetCurrencies):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.currencies.list()
+.then(({ currencies, count, offset, limit }) => {
+  console.log(currencies.length)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { Currency } from "@medusajs/medusa"
+import { useAdminCurrencies } from "medusa-react"
+
+const Currencies = () => {
+  const { currencies, isLoading } = useAdminCurrencies()
+
+  return (
+    <div>
+      {isLoading && <span>Loading...</span>}
+      {currencies && !currencies.length && (
+        <span>No Currencies</span>
+      )}
+      {currencies && currencies.length > 0 && (
+        <ul>
+          {currencies.map((currency: Currency) => (
+            <li key={currency.code}>{currency.name}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
+
+export default Currencies
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/currencies`, {
+  credentials: "include",
+})
+.then((response) => response.json())
+.then(({ currencies, count, offset, limit }) => {
+  console.log(currencies.length)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X GET '<BACKEND_URL>/admin/currencies' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint accepts optional filter and search query parameters. For example, you can pass the `code` query parameter to search the list of currencies by a code. You can learn about available query parameters in the [API reference](/api/admin#tag/Currencies/operation/GetCurrencies).
+
+This request returns an array of currencies along with pagination parameters.
+
+---
+
+## Update Currencies
+
+You can update a currency by sending a request to the [Update Currency endpoint](/api/admin#tag/Currencies/operation/PostCurrenciesCurrency):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.currencies.update(code, {
+  includes_tax: true,
+})
+.then(({ currency }) => {
+  console.log(currency.code)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminUpdateCurrency } from "medusa-react"
+
+const UpdateCode = () => {
+  const updateCode = useAdminUpdateCurrency(code)
+  // ...
+
+  const handleUpdate = () => {
+    updateCode.mutate({
+      includes_tax,
+    })
+  }
+
+  // ...
+}
+
+export default UpdateCode
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/currencies/${code}`, {
+    credentials: "include",
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      includes_tax,
+    }),
+  })
+  .then((response) => response.json())
+  .then(({ currency }) => {
+    console.log(currency.code)
+  })
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X GET '<BACKEND_URL>/admin/currencies/<CODE>' \
+-H 'Authorization: Bearer <API_TOKEN>' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+    "includes_tax": true
+}'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the currency code as a path parameter.
+
+In the request body parameter, it accepts the field `includes_tax` which is a boolean value that indicates whether tax inclusion is enabled for the currency. This is only available if you’ve enabled the Tax Inclusive feature.
+
+:::tip
+
+You can learn more in the [Tax-Inclusive Pricing guide](../../taxes/inclusive-pricing.md).
+
+:::
+
+The request returns the updated currency as an object.
+
+---
+
+## Manage Currencies in a Store
+
+This section explains how you can manage the currencies of a store.
+
+### List Currencies in a Store
+
+You can list currencies in a store by sending a request to the [Get Store Details endpoint](/api/admin#tag/Store/operation/GetStore):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.store.retrieve()
+.then(({ store }) => {
+  console.log(store.currencies, store.default_currency)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { Currency } from "@medusajs/medusa"
+import { useAdminStore } from "medusa-react"
+
+const StoreCurrencies = () => {
+  const { store, isLoading } = useAdminStore()
+
+  return (
+    <div>
+      {isLoading && <span>Loading...</span>}
+      {store && store.default_currency && (
+        <span>
+          Default Currency: {store.default_currency.code}
+        </span>
+      )}
+      {store && !store.currencies.length && (
+        <span>No Currencies</span>
+      )}
+      {store?.currencies && store.currencies.length > 0 && (
+        <ul>
+          {store.currencies.map((currency: Currency) => (
+            <li key={currency.code}>{currency.name}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
+
+export default StoreCurrencies
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/store`, {
+  credentials: "include",
+})
+.then((response) => response.json())
+.then(({ store }) => {
+  console.log(store.currencies, store.default_currency)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/store' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This request returns the store as an object. In that object, there are two properties related to currencies:
+
+1. `default_currency` is a currency object with details about the default currency.
+2. `currencies` is an array of currency objects.
+
+### Add Currency to the Store
+
+You can add a currency to a store using the [Add a Currency Code endpoint](/api/admin#tag/Store/operation/PostStoreCurrenciesCode):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.store.addCurrency(code)
+.then(({ store }) => {
+  console.log(store.currencies)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminAddStoreCurrency } from "medusa-react"
+
+const AddCurrency = () => {
+  const addCode = useAdminAddStoreCurrency()
+  // ...
+
+  const handleAdd = () => {
+    addCode.mutate(code)
+  }
+
+  // ...
+}
+
+export default AddCurrency
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/store/currencies/${code}`, {
+  credentials: "include",
+  method: "POST",
+})
+.then((response) => response.json())
+.then(({ store }) => {
+  console.log(store.currencies)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/store/currencies/<CODE>' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the currency code to be passed as a path parameter.
+
+The request returns the updated store as an object. You can access the new list of currencies under the `store.currencies` property.
+
+### Delete a Currency from the Store
+
+You can remove a currency from a store by sending a request to the [Delete Currency Code endpoint](/api/admin#tag/Store/operation/DeleteStoreCurrenciesCode):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.store.deleteCurrency(code)
+.then(({ store }) => {
+  console.log(store.currencies)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminDeleteStoreCurrency } from "medusa-react"
+
+const DeleteCurrency = () => {
+  const deleteCurrency = useAdminDeleteStoreCurrency()
+  // ...
+
+  const handleDelete = () => {
+    deleteCurrency.mutate(code)
+  }
+
+  // ...
+}
+
+export default DeleteCurrency
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/store/currencies/${code}`, {
+  credentials: "include",
+  method: "DELETE",
+})
+.then((response) => response.json())
+.then(({ store }) => {
+  console.log(store.currencies)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X DELETE '<BACKEND_URL>/admin/store/currencies/<CODE>' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the currency code to be passed as a path parameter.
+
+The request returns the updated store as an object. You can access the new list of currencies under the `store.currencies` property.
+
+---
+
+## See Also
+
+- [Currency architecture](../currencies.md)
+- [How to manage regions](./manage-regions.mdx)

docs/content/modules/regions-and-currencies/currencies.md

@@ -0,0 +1,90 @@
+---
+description: 'Learn about the Currency entity and its relation to other entities. Currencies are used to define the price of products, services, and other monetary details in a commerce system.'
+---
+
+# Currency Architecture
+
+In this document, you’ll learn about the Currency entity and its relation to other entities.
+
+## Introduction
+
+Currencies are used to define the price of products, services, and other monetary details in a commerce system.
+
+Medusa supports multi-currency within your commerce store. You can specify prices per currency, and even per region. This means that you can serve customers globally without limitations related to pricing.
+
+---
+
+## Currency Entity Overview
+
+The `Currency` entity has the following attributes:
+
+- `code`: A string indicating the [3 character ISO code](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) for the currency. This attribute also acts as a unique and primary column of the entity.
+- `symbol`: A string indicating the display symbol of the currency. This would typically be the symbol you would show to the customer or admin users when displaying a price.
+- `symbol_native`: A string indicating the native symbol of the currency.
+- `name`: A string indicating the name of the currency.
+
+---
+
+## How Currencies are Created
+
+Currencies are defined in the core of your Medusa backend under `utils/currencies.js` (or `packages/medusa/src/utils/currencies.ts` if you’re using the Medusa mono-repository). They’re defined in an object in that file.
+
+When you run the `migration` or `seed` command the first time on your Medusa server, a migration uses this object to insert all its properties (the currencies) into the database.
+
+So, if you want to add more currencies, you can create a migration that inserts your currencies into the database.
+
+:::tip
+
+You can learn more about Migrations in [this guide](../../development/entities/migrations/overview.mdx).
+
+:::
+
+---
+
+## Relation to Other Entities
+
+### Store
+
+A store has a default currency and can have many currencies. These currencies are then used in other relations, such as when associating a region with a currency.
+
+There are two relations available on the `Store` entity related to the `Currency` entity:
+
+- You can expand the `default_currency` relation on a store and access the default currency with `store.default_currency`. You can also use the `default_currency_code` attribute on the store to access the code of the default currency.
+- You can expand the `currencies` relation on a store and access the currencies with `store.currencies`.
+
+### Region
+
+Each region is associated with a currency. A currency can be used in more than one region, but a region can have only one currency.
+
+The relation is available on a region by expanding the `region.currency` relation and accessing `region.currency`. You can also access the currency code through the attribute `currency_code` on the region.
+
+### MoneyAmount
+
+The `MoneyAmount` entity is used to store the price of different entities within your commerce store.
+
+The relation is available on the `MoneyAmount` entity by expanding the `currency` relation and accessing `money_amount.currency`. You can also access the currency code through the attribute `currency_code` on the money amount.
+
+### Order
+
+The `Order` entity includes a relation to the currency, as it is the currency that the order was placed in.
+
+The relation is available on the `Order` entity by expanding the `currency` relation and accessing `order.currency`. You can also access the currency code through the attribute `currency_code` on the order.
+
+### Payment
+
+The `Payment` entity is used to represent a payment of any kind, such as for orders. Each payment is associated with a currency.
+
+The relation is available on the `Payment` entity by expanding the `currency` relation and accessing `payment.currency_code`. You can also access the currency code through the attribute `currency_code` on the payment.
+
+### PaymentCollection
+
+The `PaymentCollection` entity is used to represent a collection of payments. Each payment collection is associated with a currency.
+
+The relation is available on the `PaymentCollection` entity by expanding the `currency` relation and accessing `payment_collection.currency_code`. You can also access the currency code through the attribute `currency_code` on the payment collection.
+
+---
+
+## See Also
+
+- [Price Selection Strategy](../price-lists/price-selection-strategy.md)
+- [Tax-Inclusive Pricing](../taxes/inclusive-pricing.md)

docs/content/modules/regions-and-currencies/overview.mdx

@@ -55,12 +55,11 @@ You have complete control over the format and value of the price of a product pe
 <DocCardList colSize={6} items={[
   {
     type: 'link',
-    href: '#',
+    href: '/modules/regions-and-currencies/admin/manage-currencies',
     label: 'Admin: Manage Currencies',
     customProps: {
       icon: Icons['academic-cap-solid'],
-      description: 'Learn how to manage currencies using the Admin APIs.',
+      description: 'Learn how to manage currencies using the Admin APIs.'
-      isSoon: true
     }
   },
   {
@@ -119,12 +118,11 @@ Learn how Regions and Currencies are built, their relation to other modules, and
   },
   {
     type: 'link',
-    href: '#',
+    href: '/modules/regions-and-currencies/currencies',
     label: 'Architecture: Currency',
     customProps: {
       icon: Icons['circle-stack-solid'],
       description: 'Learn about the Currency Architecture.',
-      isSoon: true,
     }
   },
 ]} />

packages/medusa/src/api/routes/admin/currencies/update-currency.ts

@@ -32,7 +32,7 @@ import { EntityManager } from "typeorm"
  *         includes_tax: true
  *       })
  *       .then(({ currency }) => {
- *         console.log(currency.id);
+ *         console.log(currency.code);
  *       });
  *   - lang: Shell
  *     label: cURL

packages/medusa/src/api/routes/admin/store/add-currency.ts

@@ -28,7 +28,7 @@ import { EntityManager } from "typeorm"
  *       // must be previously logged in or use api token
  *       medusa.admin.store.addCurrency('eur')
  *       .then(({ store }) => {
- *         console.log(store.id);
+ *         console.log(store.currencies);
  *       });
  *   - lang: Shell
  *     label: cURL

packages/medusa/src/api/routes/admin/store/remove-currency.ts

@@ -28,7 +28,7 @@ import { EntityManager } from "typeorm"
  *       // must be previously logged in or use api token
  *       medusa.admin.store.deleteCurrency('eur')
  *       .then(({ store }) => {
- *         console.log(store.id);
+ *         console.log(store.currencies);
  *       });
  *   - lang: Shell
  *     label: cURL

www/docs/sidebars.js

@@ -456,12 +456,9 @@ module.exports = {
           label: "Regions",
         },
         {
-          type: "link",
+          type: "doc",
-          href: "#",
+          id: "modules/regions-and-currencies/currencies",
           label: "Currencies",
-          customProps: {
-            sidebar_is_soon: true,
-          },
         },
         {
           type: "html",
@@ -476,12 +473,9 @@ module.exports = {
           label: "Admin: Manage Regions",
         },
         {
-          type: "link",
+          type: "doc",
-          href: "#",
+          id: "modules/regions-and-currencies/admin/manage-currencies",
           label: "Admin: Manage Currencies",
-          customProps: {
-            sidebar_is_soon: true,
-          },
         },
         {
           type: "doc",