docs: added currency documentation pages (#3803)
* docs: added currency documentation pages * fixes to OAS
This commit is contained in:
Shahed Nasser
@@ -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)
|
||||
Reference in New Issue
Block a user