asyavee/medusa-store
1
0 Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: revise commerce modules overview pages (#10738)

Browse Source 
* revise API Key Module overview

* revise auth module

* support ref sidebar items

* remove examples

* revise cart module

* revise currency

* revise customer module

* revise fulfillment module

* revise inventory module

* revise order module

* revise payment

* revise pricing module

* revise product module

* revise promotion module

* revise region module

* revise sales channel module

* revise stock location module

* revise store module

* revise tax module

* revise user module

* lint content + fix snippets
This commit is contained in:
Shahed Nasser authored and GitHub committed 2024-12-26 10:32:16 +02:00
1 parent c8f9938865
commit ebca8fed28
112 files changed
+9465 -7731
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

www/apps/resources/app/commerce-modules/tax/examples/page.mdx
-344
View File
@@ -1,344 +0,0 @@
import { CodeTabs, CodeTab } from "docs-ui"
export const metadata = {
title: `Examples of the Tax Module`,
}
# {metadata.title}
In this guide, you’ll find common examples of how you can use the Tax Module in your application.
<Note>
You should only use the Tax Module's main service when implementing complex customizations. For common cases, check out [available workflows instead](../../../medusa-workflows-reference/page.mdx).
</Note>
## Create a Tax Region
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const taxModuleService = req.scope.resolve(
Modules.TAX
)
const taxRegion = await taxModuleService.createTaxRegions({
country_code: "us",
default_tax_rate: {
rate: 10,
name: "Default rate",
},
})
res.json({
tax_region: taxRegion,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeTaxModule } from "@medusajs/medusa/tax"
export async function POST(request: Request) {
const taxModuleService = await initializeTaxModule()
const taxRegion = await taxModuleService.createTaxRegions({
country_code: "us",
default_tax_rate: {
rate: 10,
name: "Default rate",
},
})
return NextResponse.json({
tax_region: taxRegion,
})
}
```
</CodeTab>
</CodeTabs>
---
## List Tax Regions
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const taxModuleService = req.scope.resolve(
Modules.TAX
)
res.json({
tax_regions: await taxModuleService.listTaxRegions(),
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeTaxModule } from "@medusajs/medusa/tax"
export async function GET(request: Request) {
const taxModuleService = await initializeTaxModule()
return NextResponse.json({
tax_regions: await taxModuleService.listTaxRegions(),
})
}
```
</CodeTab>
</CodeTabs>
---
## Create Tax Rate with Rules
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const taxModuleService = req.scope.resolve(
Modules.TAX
)
const taxRate = await taxModuleService.createTaxRates({
tax_region_id: "txreg_123",
name: "Custom rate",
rate: 15,
rules: [
{
reference: "product_type",
reference_id: "ptyp_1",
},
{
reference: "product",
reference_id: "prod_123",
},
],
})
res.json({
tax_rate: taxRate,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeTaxModule } from "@medusajs/medusa/tax"
export async function POST(request: Request) {
const taxModuleService = await initializeTaxModule()
const taxRate = await taxModuleService.createTaxRates({
tax_region_id: "txreg_123",
name: "Custom rate",
rate: 15,
rules: [
{
reference: "product_type",
reference_id: "ptyp_1",
},
{
reference: "product",
reference_id: "prod_123",
},
],
})
return NextResponse.json({
tax_rate: taxRate,
})
}
```
</CodeTab>
</CodeTabs>
---
## List Tax Rates
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const taxModuleService = req.scope.resolve(
Modules.TAX
)
res.json({
tax_rates: await taxModuleService.listTaxRates(),
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeTaxModule } from "@medusajs/medusa/tax"
export async function GET(request: Request) {
const taxModuleService = await initializeTaxModule()
return NextResponse.json({
tax_rates: await taxModuleService.listTaxRates(),
})
}
```
</CodeTab>
</CodeTabs>
---
## Get Tax Lines
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const taxModuleService = req.scope.resolve(
Modules.TAX
)
const taxLines = await taxModuleService.getTaxLines(
[
{
id: "cali_123",
product_id: "prod_123",
unit_price: 1000,
},
{
id: "casm_123",
shipping_option_id: "so_123",
unit_price: 2000,
},
],
{
address: {
country_code: "us",
postal_code: "123456",
},
customer: {
id: "cus_123",
email: "user@example.com",
customer_groups: ["VIP"],
},
}
)
res.json({
tax_lines: taxLines,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeTaxModule } from "@medusajs/medusa/tax"
export async function GET(request: Request) {
const taxModuleService = await initializeTaxModule()
const taxLines = await taxModuleService.getTaxLines(
[
{
id: "cali_123",
product_id: "prod_123",
unit_price: 1000,
},
{
id: "casm_123",
shipping_option_id: "so_123",
unit_price: 2000,
},
],
{
address: {
country_code: "us",
postal_code: "123456",
},
customer: {
id: "cus_123",
email: "user@example.com",
customer_groups: ["VIP"],
},
}
)
return NextResponse.json({
tax_lines: taxLines,
})
}
```
</CodeTab>
</CodeTabs>
---
## More Examples
The [Tax Module's main service reference](/references/tax) provides a reference to all the methods available for use with examples for each.
www/apps/resources/app/commerce-modules/tax/page.mdx
+118 -103
View File
@@ -6,142 +6,157 @@ export const metadata = {
# {metadata.title}
The Tax Module provides tax-related features in your Medusa and Node.js applications.
In this section of the documentation, you will find resources to learn more about the Tax Module and how to use it in your application.
Medusa has tax related features available out-of-the-box through the Tax Module. A [module](!docs!/learn/fundamentals/modules) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Tax Module.
<Note>
Learn more about why modules are isolated in [this documentation](!docs!/learn/fundamentals/modules/isolation).
</Note>
## Tax Features
- [Tax Settings Per Region](./tax-region/page.mdx): Set different tax settings for each tax region.
- [Tax Rates and Rules](./tax-rates-and-rules/page.mdx): Manage each region's default tax rates and override them with conditioned tax rates.
- [Retrieve Tax Lines for carts and orders](./tax-calculation-with-provider/page.mdx): Calculate and retrieve the tax lines of a cart or order's line items and shipping methods with tax providers.
---
## How to Use Tax Module's Service
You can use the Tax Module's main service by resolving from the Medusa container the resource `Modules.TAX`.
In your Medusa application, you build flows around commerce modules. A flow is built as a [Workflow](!docs!/learn/fundamentals/workflows), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
For example:
<CodeTabs groupId="resource-type">
<CodeTab label="Workflow Step" value="workflow-step">
export const highlights = [
["12", "Modules.TAX", "Resolve the module in a step."]
]
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
```ts title="src/workflows/create-tax-region.ts" highlights={highlights}
import {
createWorkflow,
WorkflowResponse,
createStep,
StepResponse,
} from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const taxModuleService = container.resolve(
Modules.TAX
)
const createTaxRegionStep = createStep(
"create-tax-region",
async ({}, { container }) => {
const taxModuleService = container.resolve(Modules.TAX)
const taxRegions = await taxModuleService.listTaxRegions()
})
const taxRegion = await taxModuleService.createTaxRegions({
country_code: "us",
})
return new StepResponse({ taxRegion }, taxRegion.id)
},
async (taxRegionId, { container }) => {
if (!taxRegionId) {
return
}
const taxModuleService = container.resolve(Modules.TAX)
await taxModuleService.deleteTaxRegions([taxRegionId])
}
)
export const createTaxRegionWorkflow = createWorkflow(
"create-tax-region",
() => {
const { taxRegion } = createTaxRegionStep()
return new WorkflowResponse({ taxRegion })
}
)
```
</CodeTab>
<CodeTab label="API Route" value="api-route">
You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
<CodeTabs group="resource-types">
<CodeTab label="API Route" value="api-route">
```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
import { createTaxRegionWorkflow } from "../../workflows/create-tax-region"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const taxModuleService = req.scope.resolve(
Modules.TAX
)
) {
const { result } = await createTaxRegionWorkflow(req.scope)
.run()
res.json({
tax_regions: await taxModuleService.listTaxRegions(),
})
res.send(result)
}
```
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
<CodeTab label="Subscriber" value="subscriber">
```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/framework"
import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
export default async function handleUserCreated({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const { result } = await createTaxRegionWorkflow(container)
.run()
export default async function subscriberHandler({ container }: SubscriberArgs) {
const taxModuleService = container.resolve(
Modules.TAX
)
console.log(result)
}
const taxRegions = await taxModuleService.listTaxRegions()
export const config: SubscriberConfig = {
event: "user.created",
}
```
</CodeTab>
<CodeTab label="Scheduled Job" value="scheduled-job">
```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
import { MedusaContainer } from "@medusajs/framework/types"
import { createTaxRegionWorkflow } from "../workflows/create-tax-region"
export default async function myCustomJob(
container: MedusaContainer
) {
const { result } = await createTaxRegionWorkflow(container)
.run()
console.log(result)
}
export const config = {
name: "run-once-a-day",
schedule: `0 0 * * *`,
}
```
</CodeTab>
</CodeTabs>
---
## Features
### Tax Settings Per Region
Set different tax settings for each tax region.
```ts
const taxRegion = await taxModuleService.createTaxRegions({
country_code: "us",
})
```
### Tax Rates and Rules
Manage each region's default tax rates and override them with conditioned tax rates.
```ts
const taxRates = await taxModuleService.createTaxRates([
{
tax_region_id: "txreg_123",
name: "Default tax rate",
is_default: true,
rate: 10,
},
{
tax_region_id: "txreg_123",
name: "Shirt product type",
is_default: false,
rate: 15,
rules: [
{
reference: "product_type",
reference_id: "ptyp_1",
},
],
},
])
```
### Retrieve Cart's Tax Lines
Calculate and retrieve the tax lines of a cart's line items and shipping methods with tax providers.
```ts
const taxLines = await taxModuleService.getTaxLines(
[
{
id: "cali_123",
product_id: "prod_123",
unit_price: 1000,
quantity: 1,
},
{
id: "casm_123",
shipping_option_id: "so_123",
unit_price: 2000,
},
],
{
address: {
country_code: "us",
},
}
)
```
You can use different tax providers for each region to handle tax-line retrieval differently.
Learn more about workflows in [this documentation](!docs!/learn/fundamentals/workflows).
---
## Configure Tax Module
Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
The Tax Module accepts options for further configurations. Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
---
<CommerceModuleSections name="Tax" />