diff --git a/docs/content/modules/taxes/admin/manage-tax-settings.mdx b/docs/content/modules/taxes/admin/manage-tax-settings.mdx new file mode 100644 index 0000000000..bfd8c98aa5 --- /dev/null +++ b/docs/content/modules/taxes/admin/manage-tax-settings.mdx @@ -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): + + + + +```ts +medusa.admin.store.listTaxProviders() +.then(({ tax_providers }) => { + console.log(tax_providers.length) +}) +``` + + + + +```tsx +import { useAdminStoreTaxProviders } from "medusa-react" + +const TaxProviders = () => { + const { + tax_providers, + isLoading, + } = useAdminStoreTaxProviders() + + return ( +
+ {isLoading && Loading...} + {tax_providers && !tax_providers.length && ( + No Tax Providers + )} + {tax_providers && tax_providers.length > 0 && ( +
    + {tax_providers.map((tax_provider) => ( +
  • {tax_provider.id}
    • + ))} +
+ )} +
+ ) +} + +export default TaxProviders +``` + + + + +```ts +fetch(`/admin/store/tax-providers`, { + credentials: "include", +}) +.then((response) => response.json()) +.then(({ tax_providers }) => { + console.log(tax_providers.length) +}) +``` + + + + +```bash +curl -L -X GET '/admin/store/tax-providers' \ +-H 'Authorization: Bearer ' +``` + + + + +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): + + + + +```ts +medusa.admin.regions.update(regionId, { + tax_provider_id, +}) +.then(({ region }) => { + console.log(region.id) +}) +``` + + + + +```tsx +import { useAdminUpdateRegion } from "medusa-react" + +const UpdateRegion = () => { + const updateRegion = useAdminUpdateRegion(regionId) + // ... + + const handleUpdate = () => { + updateRegion.mutate({ + tax_provider_id, + }) + } + + // ... +} + +export default UpdateRegion +``` + + + + +```ts +fetch(`/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) +}) +``` + + + + +```bash +curl -L -X POST '/admin/regions/' \ +-H 'Authorization: Bearer ' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "tax_provider_id": "" +}' +``` + + + + +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: + + + + +```ts +medusa.admin.regions.update(regionId, { + tax_provider_id, + automatic_taxes, + gift_cards_taxable, + tax_code, + tax_rate, +}) +.then(({ region }) => { + console.log(region.id) +}) +``` + + + + +```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 +``` + + + + +```ts +fetch(`/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) +}) +``` + + + + +```bash +curl -L -X POST '/admin/regions/' \ +-H 'Authorization: Bearer ' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "tax_provider_id": "", + "automatic_taxes": true, + "gift_cards_taxable": true, + "tax_code": "", + "tax_rate": 10 +}' +``` + + + + +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. diff --git a/docs/content/modules/taxes/backend/create-tax-provider.md b/docs/content/modules/taxes/backend/create-tax-provider.md index f58f5c8f3f..5a87cb3578 100644 --- a/docs/content/modules/taxes/backend/create-tax-provider.md +++ b/docs/content/modules/taxes/backend/create-tax-provider.md @@ -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. diff --git a/docs/content/modules/taxes/overview.mdx b/docs/content/modules/taxes/overview.mdx index fb80d589d6..05f1ba3fd9 100644 --- a/docs/content/modules/taxes/overview.mdx +++ b/docs/content/modules/taxes/overview.mdx @@ -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.', } }, ]} /> diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index b8adf17136..59ea8985af 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -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",