asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: added currency documentation pages (#3803)

Browse Source 
* docs: added currency documentation pages

* fixes to OAS
This commit is contained in:
Shahed Nasser
2023-04-11 21:39:24 +03:00
committed by GitHub
parent 654a546223
commit 1651cfd4ac
7 changed files with 535 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

435
docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx Normal file
View File

@@ -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)

90
docs/content/modules/regions-and-currencies/currencies.md Normal file
View File

@@ -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)

8
docs/content/modules/regions-and-currencies/overview.mdx
View File

@@ -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.',
isSoon: true
description: 'Learn how to manage currencies using the Admin APIs.'
}
},
{
@@ -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,
}
},
]} />

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

@@ -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

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

@@ -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

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

@@ -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

14
www/docs/sidebars.js
View File

@@ -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",