From 1651cfd4acabaaafe3fb3da61849778ee22cd76c Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 11 Apr 2023 21:39:24 +0300 Subject: [PATCH] docs: added currency documentation pages (#3803) * docs: added currency documentation pages * fixes to OAS --- .../admin/manage-currencies.mdx | 435 ++++++++++++++++++ .../regions-and-currencies/currencies.md | 90 ++++ .../regions-and-currencies/overview.mdx | 8 +- .../admin/currencies/update-currency.ts | 2 +- .../api/routes/admin/store/add-currency.ts | 2 +- .../api/routes/admin/store/remove-currency.ts | 2 +- www/docs/sidebars.js | 14 +- 7 files changed, 535 insertions(+), 18 deletions(-) create mode 100644 docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx create mode 100644 docs/content/modules/regions-and-currencies/currencies.md diff --git a/docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx b/docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx new file mode 100644 index 0000000000..07ea860353 --- /dev/null +++ b/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): + + + + +```ts +medusa.admin.currencies.list() +.then(({ currencies, count, offset, limit }) => { + console.log(currencies.length) +}) +``` + + + + +```tsx +import { Currency } from "@medusajs/medusa" +import { useAdminCurrencies } from "medusa-react" + +const Currencies = () => { + const { currencies, isLoading } = useAdminCurrencies() + + return ( +
+ {isLoading && Loading...} + {currencies && !currencies.length && ( + No Currencies + )} + {currencies && currencies.length > 0 && ( +
    + {currencies.map((currency: Currency) => ( +
  • {currency.name}
    • + ))} +
+ )} +
+ ) +} + +export default Currencies +``` + + + + +```ts +fetch(`/admin/currencies`, { + credentials: "include", +}) +.then((response) => response.json()) +.then(({ currencies, count, offset, limit }) => { + console.log(currencies.length) +}) +``` + + + + +```bash +curl -L -X GET '/admin/currencies' \ +-H 'Authorization: Bearer ' +``` + + + + +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): + + + + +```ts +medusa.admin.currencies.update(code, { + includes_tax: true, +}) +.then(({ currency }) => { + console.log(currency.code) +}) +``` + + + + +```tsx +import { useAdminUpdateCurrency } from "medusa-react" + +const UpdateCode = () => { + const updateCode = useAdminUpdateCurrency(code) + // ... + + const handleUpdate = () => { + updateCode.mutate({ + includes_tax, + }) + } + + // ... +} + +export default UpdateCode +``` + + + + +```ts +fetch(`/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) + }) +``` + + + + +```bash +curl -L -X GET '/admin/currencies/' \ +-H 'Authorization: Bearer ' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "includes_tax": true +}' +``` + + + + +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): + + + + +```ts +medusa.admin.store.retrieve() +.then(({ store }) => { + console.log(store.currencies, store.default_currency) +}) +``` + + + + +```tsx +import { Currency } from "@medusajs/medusa" +import { useAdminStore } from "medusa-react" + +const StoreCurrencies = () => { + const { store, isLoading } = useAdminStore() + + return ( +
+ {isLoading && Loading...} + {store && store.default_currency && ( + + Default Currency: {store.default_currency.code} + + )} + {store && !store.currencies.length && ( + No Currencies + )} + {store?.currencies && store.currencies.length > 0 && ( +
    + {store.currencies.map((currency: Currency) => ( +
  • {currency.name}
    • + ))} +
+ )} +
+ ) +} + +export default StoreCurrencies +``` + + + + +```ts +fetch(`/admin/store`, { + credentials: "include", +}) +.then((response) => response.json()) +.then(({ store }) => { + console.log(store.currencies, store.default_currency) +}) +``` + + + + +```bash +curl -L -X POST '/admin/store' \ +-H 'Authorization: Bearer ' +``` + + + + +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): + + + + +```ts +medusa.admin.store.addCurrency(code) +.then(({ store }) => { + console.log(store.currencies) +}) +``` + + + + +```tsx +import { useAdminAddStoreCurrency } from "medusa-react" + +const AddCurrency = () => { + const addCode = useAdminAddStoreCurrency() + // ... + + const handleAdd = () => { + addCode.mutate(code) + } + + // ... +} + +export default AddCurrency +``` + + + + +```ts +fetch(`/admin/store/currencies/${code}`, { + credentials: "include", + method: "POST", +}) +.then((response) => response.json()) +.then(({ store }) => { + console.log(store.currencies) +}) +``` + + + + +```bash +curl -L -X POST '/admin/store/currencies/' \ +-H 'Authorization: Bearer ' +``` + + + + +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): + + + + +```ts +medusa.admin.store.deleteCurrency(code) +.then(({ store }) => { + console.log(store.currencies) +}) +``` + + + + +```tsx +import { useAdminDeleteStoreCurrency } from "medusa-react" + +const DeleteCurrency = () => { + const deleteCurrency = useAdminDeleteStoreCurrency() + // ... + + const handleDelete = () => { + deleteCurrency.mutate(code) + } + + // ... +} + +export default DeleteCurrency +``` + + + + +```ts +fetch(`/admin/store/currencies/${code}`, { + credentials: "include", + method: "DELETE", +}) +.then((response) => response.json()) +.then(({ store }) => { + console.log(store.currencies) +}) +``` + + + + +```bash +curl -L -X DELETE '/admin/store/currencies/' \ +-H 'Authorization: Bearer ' +``` + + + + +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) diff --git a/docs/content/modules/regions-and-currencies/currencies.md b/docs/content/modules/regions-and-currencies/currencies.md new file mode 100644 index 0000000000..e65e1be553 --- /dev/null +++ b/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) diff --git a/docs/content/modules/regions-and-currencies/overview.mdx b/docs/content/modules/regions-and-currencies/overview.mdx index fd01c2809c..9ba57d46af 100644 --- a/docs/content/modules/regions-and-currencies/overview.mdx +++ b/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 diff --git a/packages/medusa/src/api/routes/admin/currencies/update-currency.ts b/packages/medusa/src/api/routes/admin/currencies/update-currency.ts index 506336e4d6..552d953609 100644 --- a/packages/medusa/src/api/routes/admin/currencies/update-currency.ts +++ b/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 diff --git a/packages/medusa/src/api/routes/admin/store/add-currency.ts b/packages/medusa/src/api/routes/admin/store/add-currency.ts index fd350d608f..89798a0329 100644 --- a/packages/medusa/src/api/routes/admin/store/add-currency.ts +++ b/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 diff --git a/packages/medusa/src/api/routes/admin/store/remove-currency.ts b/packages/medusa/src/api/routes/admin/store/remove-currency.ts index 34dffde139..39ace9ecda 100644 --- a/packages/medusa/src/api/routes/admin/store/remove-currency.ts +++ b/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 diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 5d8a98e18c..9a75bd493f 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -456,12 +456,9 @@ module.exports = { label: "Regions", }, { - type: "link", - href: "#", + type: "doc", + 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", - href: "#", + type: "doc", + id: "modules/regions-and-currencies/admin/manage-currencies", label: "Admin: Manage Currencies", - customProps: { - sidebar_is_soon: true, - }, }, { type: "doc",