docs: update endpoints to use file-routing approach (#5397)
- Move the original guides for creating endpoints and middlewares to sub-sections in the Endpoints category. - Replace existing guides for endpoints and middlewares with the new approach. - Update all endpoints-related snippets across docs to use this new approach.
This commit is contained in:
Shahed Nasser
@@ -51,7 +51,7 @@ You can learn more about [authenticating as an admin user in the API reference](
|
||||
|
||||
## List Tax Rates
|
||||
|
||||
You can list the tax rates by sending a request to the [List Tax Rates endpoint](https://docs.medusajs.com/api/admin#tax-rates_gettaxrates):
|
||||
You can list the tax rates by sending a request to the [List Tax Rates API Route](https://docs.medusajs.com/api/admin#tax-rates_gettaxrates):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -116,9 +116,9 @@ curl -L -X GET '<BACKEND_URL>/admin/tax-rates' \
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
You can pass to this endpoint filter and search parameters as explained in the [API reference](https://docs.medusajs.com/api/admin#tax-rates_gettaxrates).
|
||||
You can pass to this API Route filter and search parameters as explained in the [API reference](https://docs.medusajs.com/api/admin#tax-rates_gettaxrates).
|
||||
|
||||
The endpoint returns an array of tax rate objects along with [pagination parameters](https://docs.medusajs.com/api/admin#pagination).
|
||||
The API Route returns an array of tax rate objects along with [pagination parameters](https://docs.medusajs.com/api/admin#pagination).
|
||||
|
||||
### Listing Tax Rates for a Region
|
||||
|
||||
@@ -268,7 +268,7 @@ curl -L -X GET '<BACKEND_URL>/admin/tax-rates?region_id[]=reg_123®ion_id[]=re
|
||||
|
||||
## Create Tax Rate
|
||||
|
||||
You can create a tax rate by sending a request to the [Create Tax Rate endpoint](https://docs.medusajs.com/api/admin#tax-rates_posttaxrates):
|
||||
You can create a tax rate by sending a request to the [Create Tax Rate API Route](https://docs.medusajs.com/api/admin#tax-rates_posttaxrates):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -351,7 +351,7 @@ curl -L -X POST '<BACKEND_URL>/admin/tax-rates' \
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the following body parameters:
|
||||
This API Route requires the following body parameters:
|
||||
|
||||
- `code`: a string indicating the tax code
|
||||
- `name`: a string indicating the name of the tax rate
|
||||
@@ -361,7 +361,7 @@ You can optionally pass other parameters, such as `rate`, which is a number that
|
||||
|
||||
:::tip
|
||||
|
||||
You can specify here the products, product types, or shipping options that this tax rate is created for as explained in the API reference. In this guide, you’ll be using other endpoints to add or delete these conditions on a tax rate.
|
||||
You can specify here the products, product types, or shipping options that this tax rate is created for as explained in the API reference. In this guide, you’ll be using other API Routes to add or delete these conditions on a tax rate.
|
||||
|
||||
:::
|
||||
|
||||
@@ -371,7 +371,7 @@ The request returns the created tax rate as an object.
|
||||
|
||||
## Update Tax Rate
|
||||
|
||||
You can update a tax rate by sending a request to the [Update Tax Rate endpoint](https://docs.medusajs.com/api/admin#tax-rates_posttaxratestaxrate):
|
||||
You can update a tax rate by sending a request to the [Update Tax Rate API Route](https://docs.medusajs.com/api/admin#tax-rates_posttaxratestaxrate):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -442,7 +442,7 @@ curl -L -X POST '<BACKEND_URL>/admin/tax-rates/<TAX_RATE_ID>' \
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the tax rate ID to be passed as a path parameter.
|
||||
This API Route requires the tax rate ID to be passed as a path parameter.
|
||||
|
||||
In the request body, you can pass any of the tax rate’s fields as a parameter. In the example above, you pass the `name` parameter to update the name of the tax rate. Refer to the [API reference](https://docs.medusajs.com/api/admin#tax-rates_posttaxratestaxrate) for other parameters you can pass in the request body.
|
||||
|
||||
@@ -456,7 +456,7 @@ This section explains how you can add and remove products from a tax rate.
|
||||
|
||||
### Add Product to Tax Rate
|
||||
|
||||
You can add a product to a tax rate by sending a request to the [Add Products endpoint](https://docs.medusajs.com/api/admin#tax-rates_posttaxratestaxrateproducts):
|
||||
You can add a product to a tax rate by sending a request to the [Add Products API Route](https://docs.medusajs.com/api/admin#tax-rates_posttaxratestaxrateproducts):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -537,7 +537,7 @@ curl -L -X POST '<BACKEND_URL>/admin/tax-rates/<TAX_RATE_ID>/products/batch' \
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the tax rate’s ID as a path parameter.
|
||||
This API Route requires the tax rate’s ID as a path parameter.
|
||||
|
||||
In the request body, the `products` parameter is required. It’s an array of strings, each string being the ID of a product to add to the tax rate.
|
||||
|
||||
@@ -545,7 +545,7 @@ The request returns the updated tax rate as an object. You can access the tax ra
|
||||
|
||||
### Remove Product from Tax Rate
|
||||
|
||||
You can remove a product from a tax rate by sending a request to the [Delete Products endpoint](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratestaxrateproducts):
|
||||
You can remove a product from a tax rate by sending a request to the [Delete Products API Route](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratestaxrateproducts):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -626,7 +626,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/tax-rates/<TAX_RATE_ID>/products/batch' \
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the tax rate’s ID as a path parameter.
|
||||
This API Route requires the tax rate’s ID as a path parameter.
|
||||
|
||||
In the request body, the `products` parameter is required. It’s an array of strings, each string being the ID of a product to remove from the tax rate.
|
||||
|
||||
@@ -640,7 +640,7 @@ This section explains how you can add and remove product types from a tax rate.
|
||||
|
||||
### Add Product Type to Tax Rate
|
||||
|
||||
You can add a product type to a tax rate by sending a request to the [Add Product Types endpoint](https://docs.medusajs.com/api/admin#tax-rates_posttaxratestaxrateproducttypes):
|
||||
You can add a product type to a tax rate by sending a request to the [Add Product Types API Route](https://docs.medusajs.com/api/admin#tax-rates_posttaxratestaxrateproducttypes):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -725,7 +725,7 @@ curl -L -X POST '<BACKEND_URL>/admin/tax-rates/<TAX_RATE_ID>/product-types/batch
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the tax rate’s ID as a path parameter.
|
||||
This API Route requires the tax rate’s ID as a path parameter.
|
||||
|
||||
In the request body, the `product_types` parameter is required. It’s an array of strings, each string being the ID of a product type to add to the tax rate.
|
||||
|
||||
@@ -733,7 +733,7 @@ The request returns the updated tax rate as an object. You can access the tax ra
|
||||
|
||||
### Remove Product Type from Tax Rate
|
||||
|
||||
You can remove a product type from a tax rate by sending a request to the [Delete Product Types endpoint](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratestaxrateproducttypes):
|
||||
You can remove a product type from a tax rate by sending a request to the [Delete Product Types API Route](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratestaxrateproducttypes):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -818,7 +818,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/tax-rates/<TAX_RATE_ID>/product-types/bat
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the tax rate’s ID as a path parameter.
|
||||
This API Route requires the tax rate’s ID as a path parameter.
|
||||
|
||||
In the request body, the `product_types` parameter is required. It’s an array of strings, each string being the ID of a product type to remove from the tax rate.
|
||||
|
||||
@@ -832,7 +832,7 @@ This section explains how you can add and remove shipping options from a tax rat
|
||||
|
||||
### Add Shipping Option to Tax Rate
|
||||
|
||||
You can add a shipping option to a tax rate by sending a request to the [Add Shipping Option endpoint](https://docs.medusajs.com/api/admin#tax-rates_posttaxratestaxrateshippingoptions):
|
||||
You can add a shipping option to a tax rate by sending a request to the [Add Shipping Option API Route](https://docs.medusajs.com/api/admin#tax-rates_posttaxratestaxrateshippingoptions):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -915,7 +915,7 @@ curl -L -X POST '<BACKEND_URL>/admin/tax-rates/<TAX_RATE_ID>/shipping-options/ba
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the tax rate’s ID as a path parameter.
|
||||
This API Route requires the tax rate’s ID as a path parameter.
|
||||
|
||||
In the request body, the `shipping_options` parameter is required. It’s an array of strings, each string being the ID of a shipping option to add to the tax rate.
|
||||
|
||||
@@ -923,7 +923,7 @@ The request returns the updated tax rate as an object. You can access the tax ra
|
||||
|
||||
### Remove Shipping Options from Tax Rate
|
||||
|
||||
You can remove a shipping option from a tax rate by sending a request to the [Delete Shipping Options endpoint](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratestaxrateshippingoptions):
|
||||
You can remove a shipping option from a tax rate by sending a request to the [Delete Shipping Options API Route](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratestaxrateshippingoptions):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -1006,7 +1006,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/tax-rates/<TAX_RATE_ID>/shipping-options/
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the tax rate’s ID as a path parameter.
|
||||
This API Route requires the tax rate’s ID as a path parameter.
|
||||
|
||||
In the request body, the `shipping_options` parameter is required. It’s an array of strings, each string being the ID of a shipping option to remove from the tax rate.
|
||||
|
||||
@@ -1016,7 +1016,7 @@ The request returns the updated tax rate as an object. You can access the tax ra
|
||||
|
||||
## Delete Tax Rate
|
||||
|
||||
You can delete a tax rate by sending a request to the [Delete Tax Rate endpoint](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratestaxrate):
|
||||
You can delete a tax rate by sending a request to the [Delete Tax Rate API Route](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratestaxrate):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -1073,7 +1073,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/tax-rates/<TAX_RATE_ID>' \
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the tax rate’s ID as a path parameter.
|
||||
This API Route requires the tax rate’s ID as a path parameter.
|
||||
|
||||
The request returns the following fields:
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ 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](https://docs.medusajs.com/api/admin#regions_postregionsregion).
|
||||
Tax settings are defined per region. You can change the tax settings of a region using the [Update Region API Route](https://docs.medusajs.com/api/admin#regions_postregionsregion).
|
||||
|
||||
### Scenario
|
||||
|
||||
@@ -52,7 +52,7 @@ You can learn more about [authenticating as an admin user in the API reference](
|
||||
|
||||
## List Tax Providers
|
||||
|
||||
You can list all tax providers of a store using the [List Tax Providers endpoint](https://docs.medusajs.com/api/admin#store_getstoretaxproviders):
|
||||
You can list all tax providers of a store using the [List Tax Providers API Route](https://docs.medusajs.com/api/admin#store_getstoretaxproviders):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -120,7 +120,7 @@ curl -L -X GET '<BACKEND_URL>/admin/store/tax-providers' \
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint does not accept any parameters.
|
||||
This API Route doesn't accept any parameters.
|
||||
|
||||
The request returns an array of tax provider objects.
|
||||
|
||||
@@ -128,7 +128,7 @@ 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](https://docs.medusajs.com/api/admin#regions_postregionsregion):
|
||||
You can change the tax provider of a region using the [Update Region API Route](https://docs.medusajs.com/api/admin#regions_postregionsregion):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
@@ -199,7 +199,7 @@ curl -L -X POST '<BACKEND_URL>/admin/regions/<REGION_ID>' \
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the ID of the region to be passed as a path parameter.
|
||||
This API Route 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.
|
||||
|
||||
@@ -209,7 +209,7 @@ 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](https://docs.medusajs.com/api/admin#regions_postregionsregion) to update the region’s other tax settings:
|
||||
In addition to changing the tax provider, you can use the same [Update Region API Route](https://docs.medusajs.com/api/admin#regions_postregionsregion) to update the region’s other tax settings:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
@@ -205,7 +205,7 @@ Run your backend to test it out:
|
||||
npx medusa develop
|
||||
```
|
||||
|
||||
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).
|
||||
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 API Route](../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.
|
||||
|
||||
|
||||
@@ -31,7 +31,7 @@ Then, Medusa handles calculating the tax amount using the tax rate and the tax-i
|
||||
|
||||
Tax inclusivity can be toggled for regions, currencies, price lists, and shipping options either during creation or while editing. This is represented by the boolean attribute `includes_tax` available in the entities `Region`, `Currency`, `PriceList`, and `ShippingOption`. By default, this attribute is set to `false`.
|
||||
|
||||
If you want to enable or disable this attribute for any of these entities, you can use the create or update endpoints related to these entities as shown in the [Admin API reference](https://docs.medusajs.com/api/admin/).
|
||||
If you want to enable or disable this attribute for any of these entities, you can use the create or update API Routes related to these entities as shown in the [Admin API reference](https://docs.medusajs.com/api/admin/).
|
||||
|
||||
The value set for these entities can affect whether line items and shipping methods are tax inclusive or not.
|
||||
|
||||
@@ -78,7 +78,7 @@ For example, if the tax rate is `0.25` and the price of a product is `100`, the
|
||||
|
||||
## Retrieving Tax Amounts
|
||||
|
||||
This section covers at which point tax amounts are calculated for different entities, how they are calculated when the price is tax inclusive, and what fields can be returned in the endpoints relative to each of the entities.
|
||||
This section covers at which point tax amounts are calculated for different entities, how they are calculated when the price is tax inclusive, and what fields can be returned in the API Routes relative to each of the entities.
|
||||
|
||||
:::note
|
||||
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
---
|
||||
description: 'Learn how to manually calculate taxes during checkout in the Medusa backend. There are different methods including using endpoints or services.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
@@ -19,9 +18,9 @@ If you disable this behavior, you must manually trigger taxes calculation. When
|
||||
|
||||
This section explores different ways you can calculate taxes based on your purpose.
|
||||
|
||||
### Use Calculate Cart Taxes Endpoint
|
||||
### Use Calculate Cart Taxes API Route
|
||||
|
||||
The [Calculate Cart Taxes](https://docs.medusajs.com/api/store#carts_postcartscarttaxes) endpoint forces the calculation of taxes for a cart during checkout. This bypasses the option set in admin to not calculate taxes automatically, which results in sending requests to the tax provider.
|
||||
The [Calculate Cart Taxes](https://docs.medusajs.com/api/store#carts_postcartscarttaxes) API Route forces the calculation of taxes for a cart during checkout. This bypasses the option set in admin to not calculate taxes automatically, which results in sending requests to the tax provider.
|
||||
|
||||
This calculates and retrieves the taxes on the cart and each of the line items in that cart.
|
||||
|
||||
@@ -53,24 +52,30 @@ You can learn how to [retrieve and use services](../../../development/services/c
|
||||
|
||||
Another way you can use the `CartService` to calculate taxes is using the method `decorateTotals`:
|
||||
|
||||
```jsx
|
||||
```ts title=src/api/store/line-taxes/[cart_id]/route.ts
|
||||
import { CartService } from "@medusajs/medusa"
|
||||
import type {
|
||||
MedusaRequest,
|
||||
MedusaResponse,
|
||||
} from "@medusajs/medusa"
|
||||
|
||||
export default () => {
|
||||
export const GET = async (
|
||||
req: MedusaRequest,
|
||||
res: MedusaResponse
|
||||
) => {
|
||||
// example of retrieving cart
|
||||
const cartService = req.scope.resolve<CartService>(
|
||||
"cartService"
|
||||
)
|
||||
const cart = await cartService.retrieve(req.params.cart_id)
|
||||
|
||||
// ...
|
||||
|
||||
router.get("/store/line-taxes", async (req, res) => {
|
||||
// example of retrieving cart
|
||||
const cartService = req.scope.resolve("cartService")
|
||||
const cart = await cartService.retrieve(cart_id)
|
||||
|
||||
// ...
|
||||
// retrieve taxes of line items
|
||||
const data = await decorateTotals(cart, {
|
||||
force_taxes: true,
|
||||
})
|
||||
|
||||
return res.status(200).json({ cart: data })
|
||||
// retrieve taxes of line items
|
||||
const data = await cartService.decorateTotals(cart, {
|
||||
force_taxes: true,
|
||||
})
|
||||
|
||||
return res.status(200).json({ cart: data })
|
||||
}
|
||||
```
|
||||
|
||||
@@ -80,7 +85,7 @@ The `decorateTotals` method accepts the cart as a first parameter and an options
|
||||
|
||||
You can calculate and retrieve taxes of line items using the `getLineItemTotals` method available in the `TotalService` class. All you need to do is pass in the third argument to that method an options object with the key `include_tax` set to true:
|
||||
|
||||
```jsx
|
||||
```ts
|
||||
const itemTotals = await totalsService
|
||||
.getLineItemTotals(item, cart, {
|
||||
include_tax: true,
|
||||
|
||||
@@ -14,7 +14,7 @@ In Medusa, there are different ways you can customize taxes, allowing you to imp
|
||||
|
||||
- Create a tax provider that defines the tax lines applied to line items and shipping methods.
|
||||
- Customize the tax calculation strategy to change how taxes are calculated.
|
||||
- Override tax rates for specific products, product types, or shipping options in a region using endpoints or services.
|
||||
- Override tax rates for specific products, product types, or shipping options in a region using API Routes or services.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user