api-ref: custom API reference (#4770)
* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,212 @@
|
||||
---
|
||||
description: 'Learn how to create a tax provider. You can create a tax provider in a Medusa backend or a plugin.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# How to Create a Tax Provider
|
||||
|
||||
In this document, you’ll learn how to create a tax provider.
|
||||
|
||||
## Overview
|
||||
|
||||
A tax provider is used to retrieve the tax lines in a cart. The Medusa backend provides a default `system` provider. You can create your own tax provider, either in a plugin or directly in your Medusa backend, then use it in any region.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create Tax Provider Class
|
||||
|
||||
A tax provider class should be defined in a TypeScript or JavaScript file under `src/services` and the class should extend `AbstractTaxService` imported from `@medusajs/medusa`.
|
||||
|
||||
For example, you can create the file `src/services/my-tax.ts` with the following content:
|
||||
|
||||
```ts title=src/services/my-tax.ts
|
||||
import {
|
||||
AbstractTaxService,
|
||||
ItemTaxCalculationLine,
|
||||
ShippingTaxCalculationLine,
|
||||
TaxCalculationContext,
|
||||
} from "@medusajs/medusa"
|
||||
import {
|
||||
ProviderTaxLine,
|
||||
} from "@medusajs/medusa/dist/types/tax-service"
|
||||
|
||||
class MyTaxService extends AbstractTaxService {
|
||||
async getTaxLines(
|
||||
itemLines: ItemTaxCalculationLine[],
|
||||
shippingLines: ShippingTaxCalculationLine[],
|
||||
context: TaxCalculationContext):
|
||||
Promise<ProviderTaxLine[]> {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
}
|
||||
|
||||
export default MyTaxService
|
||||
```
|
||||
|
||||
Since the class extends `AbstractTaxService`, it must implement its abstract method `getTaxLines`, which is explained later in this guide.
|
||||
|
||||
### Using a Constructor
|
||||
|
||||
You can use a constructor to access services and resources registered in the dependency container using dependency injection. For example:
|
||||
|
||||
```ts title=src/services/my-tax.ts
|
||||
// ...
|
||||
import { LineItemService } from "@medusajs/medusa"
|
||||
|
||||
type InjectedDependencies = {
|
||||
lineItemService: LineItemService
|
||||
}
|
||||
|
||||
class MyTaxService extends AbstractTaxService {
|
||||
protected readonly lineItemService_: LineItemService
|
||||
|
||||
constructor({ lineItemService }: InjectedDependencies) {
|
||||
super()
|
||||
this.lineItemService_ = lineItemService
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default MyTaxService
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Define Identifier
|
||||
|
||||
Every tax provider must have a unique identifier. The identifier is defined as a static property in the class, and its value is used when registering the tax provider in the database and in the dependency container.
|
||||
|
||||
Add the static property `identifier` in your tax provider class:
|
||||
|
||||
```ts title=src/services/my-tax.ts
|
||||
class MyTaxService extends AbstractTaxService {
|
||||
static identifier = "my-tax"
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Make sure to change `my-tax` to the name of your tax provider.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Implement getTaxLines Method
|
||||
|
||||
The `getTaxLines` method is the only required method in a tax provider. It’s used when retrieving the tax lines for line items and shipping methods, typically during checkout or when calculating totals, for example, for orders, swaps, or returns.
|
||||
|
||||
The method accepts three parameters. The first parameter is an array of tax calculation objects for line items. Each object having the following properties:
|
||||
|
||||
- `item`: a line item object.
|
||||
- `rates`: an array of objects, each object having the following properties:
|
||||
- `rate`: an optional number indicating the tax rate.
|
||||
- `name`: a string indicating the name of the tax rate.
|
||||
- `code`: an optional string indicating the tax code.
|
||||
|
||||
The second parameter is an array of tax calculation objects for shipping methods. Each object having the following properties:
|
||||
|
||||
- `shipping_method`: a shipping method object.
|
||||
- `rates`: an array of objects, each object having the following properties:
|
||||
- `rate`: an optional number indicating the tax rate.
|
||||
- `name`: a string indicating the name of the tax rate.
|
||||
- `code`: an optional string indicating the tax code.
|
||||
|
||||
The third parameter is a context object that can be helpful for the tax calculation. The object can have the following properties:
|
||||
|
||||
- `shipping_address`: an optional address object used for shipping.
|
||||
- `customer`: an optional customer object.
|
||||
- `region`: an optional region object.
|
||||
- `is_return`: a boolean value that determines whether the taxes are being calculated for a return flow.
|
||||
- `shipping_methods`: an array of shipping methods being used in the current context.
|
||||
- `allocation_map`: an object that indicates the gift cards and discounts applied on line items. Each object key or property is an ID of a line item, and the value is an object having the following properties:
|
||||
- `gift_card`: an optional object indicating the gift card applied on the line item.
|
||||
- `discount`: an optional object indicating the discount applied on the line item.
|
||||
|
||||
This method is expected to return an array of line item tax line or shipping method tax line objects.
|
||||
|
||||
The line item tax line object has the following properties:
|
||||
|
||||
- `rate`: a number indicating the tax rate.
|
||||
- `name`: a string indicating the name of the tax rate.
|
||||
- `code`: an optional string indicating the tax code.
|
||||
- `item_id`: the ID of the line item.
|
||||
- `metadata`: an optional object that can hold any necessary additional data to be added to the line item tax lines.
|
||||
|
||||
The shipping method tax line object has the following properties:
|
||||
|
||||
- `rate`: a number indicating the tax rate.
|
||||
- `name`: a string indicating the name of the tax rate.
|
||||
- `code`: an optional string indicating the tax code.
|
||||
- `shipping_method_id`: the ID of the shipping method.
|
||||
- `metadata`: an optional object that can hold any necessary additional data to be added to the shipping method tax lines.
|
||||
|
||||
The returned array would be a combination of both the line item tax lines and shipping method tax lines.
|
||||
|
||||
:::note
|
||||
|
||||
The Medusa backend determines whether an object in the returned array is a shipping method tax line item, depending on the availability of the `shipping_method_id` attribute. For line items, it depends on the availability of the `item_id` attribute.
|
||||
|
||||
:::
|
||||
|
||||
For example, the `system` tax provider returns the tax calculation line items in the first parameter and the tax calculation shipping methods in the second parameter as is:
|
||||
|
||||
```ts title=src/services/my-tax.ts
|
||||
// ...
|
||||
|
||||
class SystemTaxService extends AbstractTaxService {
|
||||
// ...
|
||||
|
||||
async getTaxLines(
|
||||
itemLines: ItemTaxCalculationLine[],
|
||||
shippingLines: ShippingTaxCalculationLine[],
|
||||
context: TaxCalculationContext
|
||||
): Promise<ProviderTaxLine[]> {
|
||||
let taxLines: ProviderTaxLine[] = itemLines.flatMap((l) => {
|
||||
return l.rates.map((r) => ({
|
||||
rate: r.rate || 0,
|
||||
name: r.name,
|
||||
code: r.code,
|
||||
item_id: l.item.id,
|
||||
}))
|
||||
})
|
||||
|
||||
taxLines = taxLines.concat(
|
||||
shippingLines.flatMap((l) => {
|
||||
return l.rates.map((r) => ({
|
||||
rate: r.rate || 0,
|
||||
name: r.name,
|
||||
code: r.code,
|
||||
shipping_method_id: l.shipping_method.id,
|
||||
}))
|
||||
})
|
||||
)
|
||||
|
||||
return taxLines
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Run the Build Command
|
||||
|
||||
In the directory of the Medusa backend, run the `build` command to transpile the files in the `src` directory into the `dist` directory:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test it Out
|
||||
|
||||
Run your backend to test it out:
|
||||
|
||||
```bash npm2yarn
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
Similarly, you should see the shipping method tax lines in the cart’s `shipping_methods`, as each shipping method object has a `tax_lines` array which are the tax lines that you return in the `getTaxLines` method for shipping methods.
|
||||
@@ -0,0 +1,132 @@
|
||||
---
|
||||
description: 'Learn how to create a tax provider. You can create a tax provider in a Medusa backend or a plugin.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# How to Override a Tax Calculation Strategy
|
||||
|
||||
In this document, you’ll learn how to override a tax calculation strategy.
|
||||
|
||||
## Overview
|
||||
|
||||
A tax calculation strategy is used to calculate taxes when calculating totals. The Medusa backend provides a tax calculation strategy that handles calculating the taxes accounting for defined tax rates, and settings such as whether tax-inclusive pricing is enabled.
|
||||
|
||||
You can override the tax calculation strategy to implement different calculation logic or to integrate a third-party service that handles the tax calculation. You can override it either in a Medusa backend setup or in a plugin.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create Strategy Class
|
||||
|
||||
A tax calculation strategy should be defined in a TypeScript or JavaScript file created under the `src/strategies` directory. The class must also implement the `ITaxCalculationStrategy` interface imported from the `@medusajs/medusa` package.
|
||||
|
||||
For example, you can create the file `src/strategies/tax-calculation.ts` with the following content:
|
||||
|
||||
```ts title=src/strategies/tax-calculation.ts
|
||||
import {
|
||||
ITaxCalculationStrategy,
|
||||
LineItem,
|
||||
LineItemTaxLine,
|
||||
ShippingMethodTaxLine,
|
||||
TaxCalculationContext,
|
||||
} from "@medusajs/medusa"
|
||||
|
||||
class TaxCalculationStrategy
|
||||
implements ITaxCalculationStrategy {
|
||||
|
||||
async calculate(
|
||||
items: LineItem[],
|
||||
taxLines: (ShippingMethodTaxLine | LineItemTaxLine)[],
|
||||
calculationContext: TaxCalculationContext
|
||||
): Promise<number> {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
export default TaxCalculationStrategy
|
||||
```
|
||||
|
||||
Note that you add a basic implementation of the `calculate` method because it’s required by the `ITaxCalculationStrategy` interface. You’ll learn about the method later in the guide.
|
||||
|
||||
### Using a Constructor
|
||||
|
||||
You can use a constructor to access services and resources registered in the dependency container using dependency injection. For example:
|
||||
|
||||
```ts title=src/strategies/tax-calculation.ts
|
||||
// ...
|
||||
import {
|
||||
LineItemService,
|
||||
} from "@medusajs/medusa"
|
||||
|
||||
type InjectedDependencies = {
|
||||
lineItemService: LineItemService
|
||||
}
|
||||
|
||||
class TaxCalculationStrategy
|
||||
implements ITaxCalculationStrategy {
|
||||
|
||||
protected readonly lineItemService_: LineItemService
|
||||
|
||||
constructor({ lineItemService }: InjectedDependencies) {
|
||||
this.lineItemService_ = lineItemService
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Implement the calculate Method
|
||||
|
||||
A tax calculation strategy is only required to implement the `calculate` method. This method is used whenever the totals are calculated.
|
||||
|
||||
:::tip
|
||||
|
||||
If automatic tax calculation is disabled, then the tax calculation strategy will only be used when taxes are calculated manually as explain [this guide](../storefront/manual-calculation.md).
|
||||
|
||||
:::
|
||||
|
||||
The `calculate` method expects three parameters:
|
||||
|
||||
- `items`: the first parameter is an array of [line item](../../../references/entities/classes/LineItem.md) objects.
|
||||
- `taxLines`: the second parameter is an array of either [shipping method tax line](../../../references/entities/classes/ShippingMethodTaxLine.md) or [line item tax line](../../../references/entities/classes/LineItemTaxLine.md) objects.
|
||||
- `calculationContext`: an object holding the context of the tax calculation. The object has the following properties:
|
||||
- `shipping_address`: an optional address object used for shipping.
|
||||
- `customer`: an optional customer object.
|
||||
- `region`: an optional region object.
|
||||
- `is_return`: a boolean value that determines whether the taxes are being calculated for a return flow.
|
||||
- `shipping_methods`: an array of shipping methods being used in the current context.
|
||||
- `allocation_map`: an object that indicates the gift cards and discounts applied on line items. Each object key or property is an ID of a line item, and the value is an object having the following properties:
|
||||
- `gift_card`: an optional object indicating the gift card applied on the line item.
|
||||
- `discount`: an optional object indicating the discount applied on the line item.
|
||||
|
||||
The method returns a number, being the tax amount for the line items, tax lines, and context provided.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Run Build Command
|
||||
|
||||
In the directory of the Medusa backend, run the `build` command to transpile the files in the `src` directory into the `dist` directory:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test it Out
|
||||
|
||||
Run your backend to test it out:
|
||||
|
||||
```bash npm2yarn
|
||||
npx medusa develop
|
||||
```
|
||||
|
||||
To test it out, you can simulate a checkout flow and check the calculated taxes to see if it matches the logic you implemented in the `calculate` method.
|
||||
|
||||
:::tip
|
||||
|
||||
As mentioned earlier, if automatic calculation of taxes is disabled in the region, you have to manually trigger tax calculation as explained in [this guide](../storefront/manual-calculation.md).
|
||||
|
||||
:::
|
||||
Reference in New Issue
Block a user