docs: added Manage Tax Settings doc (#3983)
* docs: added Manage Tax Settings doc * fixed eslint errors
This commit is contained in:
Shahed Nasser
GitHub
306
docs/content/modules/taxes/admin/manage-tax-settings.mdx
Normal file
306
docs/content/modules/taxes/admin/manage-tax-settings.mdx
Normal file
@@ -0,0 +1,306 @@
|
||||
---
|
||||
description: 'Learn how to import products into Medusa using the Admin REST APIs. The steps include uploading a CSV file, creating a batch job for the import, and confirming the batch job.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Manage Tax Settings
|
||||
|
||||
In this document, you’ll learn how to manage tax settings using admin APIs.
|
||||
|
||||
## Overview
|
||||
|
||||
Tax settings are defined per region. You can change the tax settings of a region using the [Update Region endpoint](/api/admin#tag/Regions/operation/PostRegionsRegion).
|
||||
|
||||
### Scenario
|
||||
|
||||
You want to add or use the following admin functionalities:
|
||||
|
||||
- List available tax providers in a store.
|
||||
- Change the tax provider of a region.
|
||||
- Change tax settings of a region.
|
||||
|
||||
---
|
||||
|
||||
## 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 Tax Providers
|
||||
|
||||
You can list all tax providers of a store using the [List Tax Providers endpoint](/api/admin#tag/Store/operation/GetStoreTaxProviders):
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.store.listTaxProviders()
|
||||
.then(({ tax_providers }) => {
|
||||
console.log(tax_providers.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminStoreTaxProviders } from "medusa-react"
|
||||
|
||||
const TaxProviders = () => {
|
||||
const {
|
||||
tax_providers,
|
||||
isLoading,
|
||||
} = useAdminStoreTaxProviders()
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{tax_providers && !tax_providers.length && (
|
||||
<span>No Tax Providers</span>
|
||||
)}
|
||||
{tax_providers && tax_providers.length > 0 && (
|
||||
<ul>
|
||||
{tax_providers.map((tax_provider) => (
|
||||
<li key={tax_provider.id}>{tax_provider.id}</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default TaxProviders
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/store/tax-providers`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ tax_providers }) => {
|
||||
console.log(tax_providers.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/store/tax-providers' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint does not accept any parameters.
|
||||
|
||||
The request returns an array of tax provider objects.
|
||||
|
||||
---
|
||||
|
||||
## Change Tax Provider of a Region
|
||||
|
||||
You can change the tax provider of a region using the [Update Region endpoint](/api/admin#tag/Regions/operation/PostRegionsRegion):
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.regions.update(regionId, {
|
||||
tax_provider_id,
|
||||
})
|
||||
.then(({ region }) => {
|
||||
console.log(region.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminUpdateRegion } from "medusa-react"
|
||||
|
||||
const UpdateRegion = () => {
|
||||
const updateRegion = useAdminUpdateRegion(regionId)
|
||||
// ...
|
||||
|
||||
const handleUpdate = () => {
|
||||
updateRegion.mutate({
|
||||
tax_provider_id,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default UpdateRegion
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/regions/${regionId}`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
tax_provider_id,
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ region }) => {
|
||||
console.log(region.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/regions/<REGION_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"tax_provider_id": "<TAX_PROVIDER_ID>"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the ID of the region to be passed as a path parameter.
|
||||
|
||||
In the body of the request, you can pass any of the region’s attributes to update. To update the tax provider of a region, you can pass the `tax_provider_id` request body parameter.
|
||||
|
||||
The request returns the updated region as an object.
|
||||
|
||||
---
|
||||
|
||||
## Change Tax Settings of a Region
|
||||
|
||||
In addition to changing the tax provider, you can use the same [Update Region endpoint](/api/admin#tag/Regions/operation/PostRegionsRegion) to update the region’s other tax settings:
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.regions.update(regionId, {
|
||||
tax_provider_id,
|
||||
automatic_taxes,
|
||||
gift_cards_taxable,
|
||||
tax_code,
|
||||
tax_rate,
|
||||
})
|
||||
.then(({ region }) => {
|
||||
console.log(region.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminUpdateRegion } from "medusa-react"
|
||||
|
||||
const UpdateRegion = () => {
|
||||
const updateRegion = useAdminUpdateRegion(regionId)
|
||||
// ...
|
||||
|
||||
const handleUpdate = () => {
|
||||
updateRegion.mutate({
|
||||
tax_provider_id,
|
||||
automatic_taxes,
|
||||
gift_cards_taxable,
|
||||
tax_code,
|
||||
tax_rate,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default UpdateRegion
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/regions/${regionId}`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
tax_provider_id,
|
||||
automatic_taxes,
|
||||
gift_cards_taxable,
|
||||
tax_code,
|
||||
tax_rate,
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ region }) => {
|
||||
console.log(region.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/regions/<REGION_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"tax_provider_id": "<TAX_PROVIDER_ID>",
|
||||
"automatic_taxes": true,
|
||||
"gift_cards_taxable": true,
|
||||
"tax_code": "<TAX_CODE>",
|
||||
"tax_rate": 10
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
You can pass the following parameters in the body of the request that are related to tax settings:
|
||||
|
||||
- `automatic_taxes`: a boolean value indicating whether taxes should be calculated automatically when calculating totals. The default value is `true`.
|
||||
- `gift_cards_taxable`: a boolean value indicating whether gift cards are taxable. The default value is `true`.
|
||||
- `tax_code`: a string indicating the tax code of the region.
|
||||
- `tax_rate`: a number indicating the default tax rate of the region.
|
||||
|
||||
The request returns the updated region as an object.
|
||||
@@ -205,7 +205,7 @@ Run your backend to test it out:
|
||||
npm run start
|
||||
```
|
||||
|
||||
Before you can test out your tax provider, you must enable it in a region. You can do that either using the [Medusa Admin dashboard](../../../user-guide/taxes/manage.md#change-tax-provider) or using the [Update Region admin endpoint](https://docs.medusajs.com/api/admin#tag/Regions/operation/PostRegionsRegion).
|
||||
Before you can test out your tax provider, you must enable it in a region. You can do that either using the [Medusa Admin dashboard](../../../user-guide/taxes/manage.md#change-tax-provider) or using the [Update Region admin endpoint](../admin/manage-tax-settings.mdx#change-tax-provider-of-a-region).
|
||||
|
||||
Then, you can test out the tax provider by simulating a checkout process in that region. You should see the line item tax lines in the cart’s `items`, as each item object has a `tax_lines` array which are the tax lines that you return in the `getTaxLines` method for line items.
|
||||
|
||||
|
||||
@@ -46,12 +46,11 @@ Customers can view calculated taxes during their checkout process.
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '#',
|
||||
label: 'Admin: Manage Tax Providers',
|
||||
href: '/modules/taxes/admin/manage-tax-settings',
|
||||
label: 'Admin: Manage Tax Settings',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to manage a taxes using Admin APIs.',
|
||||
isSoon: true
|
||||
description: 'Learn how to manage tax settings using Admin APIs.',
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
@@ -945,12 +945,9 @@ module.exports = {
|
||||
label: "Backend: Override Tax Calculation",
|
||||
},
|
||||
{
|
||||
type: "link",
|
||||
href: "#",
|
||||
type: "doc",
|
||||
id: "modules/taxes/admin/manage-tax-settings",
|
||||
label: "Admin: Manage Taxes",
|
||||
customProps: {
|
||||
sidebar_is_soon: true,
|
||||
},
|
||||
},
|
||||
{
|
||||
type: "link",
|
||||
@@ -960,14 +957,6 @@ module.exports = {
|
||||
sidebar_is_soon: true,
|
||||
},
|
||||
},
|
||||
{
|
||||
type: "link",
|
||||
href: "#",
|
||||
label: "Admin: Manage Tax Overrides",
|
||||
customProps: {
|
||||
sidebar_is_soon: true,
|
||||
},
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "modules/taxes/storefront/manual-calculation",
|
||||
|
||||
Reference in New Issue
Block a user