docs: added region-related documentation pages (#2845)
* docs: added region doc pages * docs: small fixes
This commit is contained in:
Shahed Nasser
GitHub
403
docs/content/advanced/admin/manage-regions.mdx
Normal file
403
docs/content/advanced/admin/manage-regions.mdx
Normal file
@@ -0,0 +1,403 @@
|
|||||||
|
import Tabs from '@theme/Tabs';
|
||||||
|
import TabItem from '@theme/TabItem';
|
||||||
|
|
||||||
|
# Manage Regions using Admin APIs
|
||||||
|
|
||||||
|
In this document, you’ll learn how to manage regions using the Admin APIs.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Using the [region admin REST APIs](/api/admin/#tag/Region), you can manage regions in your store, including creating, updating, and deleting regions.
|
||||||
|
|
||||||
|
### Scenario
|
||||||
|
|
||||||
|
You want to add or use the following admin functionalities:
|
||||||
|
|
||||||
|
- List regions
|
||||||
|
- Create a region
|
||||||
|
- Update a region
|
||||||
|
- Add shipping options to a region
|
||||||
|
- Delete a Region
|
||||||
|
|
||||||
|
:::info
|
||||||
|
|
||||||
|
You can use Medusa’s Admin APIs to achieve more functionalities as well. Check out the [API reference](/api/admin/#tag/Region) to learn more.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
### Medusa Components
|
||||||
|
|
||||||
|
It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.md) to get started.
|
||||||
|
|
||||||
|
### JS Client
|
||||||
|
|
||||||
|
This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client, JavaScript’s Fetch API, or cURL.
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
### 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 Regions
|
||||||
|
|
||||||
|
You can retrieve regions available on your server using the [List Regions](/api/admin/#tag/Region/operation/GetRegions) endpoint:
|
||||||
|
|
||||||
|
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||||
|
<TabItem value="client" label="Medusa JS Client" default>
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
medusa.admin.regions.list()
|
||||||
|
.then(({ regions, limit, offset, count }) => {
|
||||||
|
console.log(regions.length);
|
||||||
|
//display regions
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="fetch" label="Fetch API">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
fetch(`<SERVER_URL>/admin/regions`, {
|
||||||
|
credentials: 'include',
|
||||||
|
})
|
||||||
|
.then((response) => response.json())
|
||||||
|
.then(({ regions, limit, offset, count }) => {
|
||||||
|
console.log(regions.length);
|
||||||
|
//display regions
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="curl" label="cURL">
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -L -X GET '<SERVER_URL>/admin/regions' \
|
||||||
|
-H 'Authorization: Bearer <API_TOKEN>'
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
This request returns an array of regions, as well as [pagination fields](/api/admin/#section/Pagination).
|
||||||
|
|
||||||
|
You can also pass filters and other selection query parameters to the request. Check out the [API reference](/api/admin/#tag/Region/operation/GetRegions) for more details on available query parameters.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Create a Region
|
||||||
|
|
||||||
|
You can create a region by sending a request to the [Create a Region](/api/admin/#tag/Region/operation/PostRegions) endpoint:
|
||||||
|
|
||||||
|
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||||
|
<TabItem value="client" label="Medusa JS Client" default>
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
medusa.admin.regions.create({
|
||||||
|
name: 'Europe',
|
||||||
|
currency_code: 'eur',
|
||||||
|
tax_rate: 0,
|
||||||
|
payment_providers: [
|
||||||
|
'manual'
|
||||||
|
],
|
||||||
|
fulfillment_providers: [
|
||||||
|
'manual'
|
||||||
|
],
|
||||||
|
countries: [
|
||||||
|
'DK'
|
||||||
|
]
|
||||||
|
})
|
||||||
|
.then(({ region }) => {
|
||||||
|
console.log(region.id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="fetch" label="Fetch API">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
fetch(`<SERVER_URL>/admin/regions`, {
|
||||||
|
credentials: 'include',
|
||||||
|
method: 'POST',
|
||||||
|
body: JSON.stringify({
|
||||||
|
name: 'Europe',
|
||||||
|
currency_code: 'eur',
|
||||||
|
tax_rate: 0,
|
||||||
|
payment_providers: [
|
||||||
|
'manual'
|
||||||
|
],
|
||||||
|
fulfillment_providers: [
|
||||||
|
'manual'
|
||||||
|
],
|
||||||
|
countries: [
|
||||||
|
'DK'
|
||||||
|
]
|
||||||
|
})
|
||||||
|
})
|
||||||
|
.then((response) => response.json())
|
||||||
|
.then(({ region }) => {
|
||||||
|
console.log(region.id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="curl" label="cURL">
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -L -X POST '<SERVER_URL>/admin/regions' \
|
||||||
|
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
--data-raw '{
|
||||||
|
"name": "Europe",
|
||||||
|
"currency_code": "eur",
|
||||||
|
"tax_rate": 0,
|
||||||
|
"payment_providers": [
|
||||||
|
"manual"
|
||||||
|
],
|
||||||
|
"fulfillment_providers": [
|
||||||
|
"manual"
|
||||||
|
],
|
||||||
|
"countries": [
|
||||||
|
"DK"
|
||||||
|
]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
This request requires the following body parameters:
|
||||||
|
|
||||||
|
- `name`: The name of the region.
|
||||||
|
- `currency_code`: The 3 character ISO currency code.
|
||||||
|
- `tax_rate`: The tax rate in the Region.
|
||||||
|
- `payment_providers`: An array of payment provider IDs. The array must contain at least one item.
|
||||||
|
- `fulfillment_providers`: An array of fulfillment provider IDs. The array must contain at least one item.
|
||||||
|
- `countries`: An array of the 2 character ISO code of the countries included in the region.
|
||||||
|
|
||||||
|
This request also accepts optional parameters, which you can view in the [API reference](/api/admin/#tag/Region/operation/PostRegions).
|
||||||
|
|
||||||
|
The request returns the created region in the response.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Update a Region
|
||||||
|
|
||||||
|
You can update any of the region’s fields and configurations. The REST APIs offer different APIs for updating specific configurations, such as the [Add Country](/api/admin/#tag/Region/operation/PostRegionsRegionCountries) endpoint.
|
||||||
|
|
||||||
|
Alternatively, you can update the details of a region using the [Update a Region](/api/admin/#tag/Region/operation/PostRegionsRegion) endpoint:
|
||||||
|
|
||||||
|
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||||
|
<TabItem value="client" label="Medusa JS Client" default>
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
medusa.admin.regions.update(regionId, {
|
||||||
|
countries: [
|
||||||
|
"DK",
|
||||||
|
"DE"
|
||||||
|
]
|
||||||
|
})
|
||||||
|
.then(({ region }) => {
|
||||||
|
console.log(region.id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="fetch" label="Fetch API">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
fetch(`<SERVER_URL>/admin/regions/${regionId}`, {
|
||||||
|
credentials: 'include',
|
||||||
|
method: 'POST',
|
||||||
|
body: JSON.stringify({
|
||||||
|
countries: [
|
||||||
|
'DK',
|
||||||
|
'DE'
|
||||||
|
]
|
||||||
|
})
|
||||||
|
})
|
||||||
|
.then((response) => response.json())
|
||||||
|
.then(({ region }) => {
|
||||||
|
console.log(region.id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="curl" label="cURL">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
curl -L -X POST '<SERVER_URL>/admin/regions/<REGION_ID>' \
|
||||||
|
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
--data-raw '{
|
||||||
|
"countries": [
|
||||||
|
"DK",
|
||||||
|
"DE"
|
||||||
|
]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
This request accepts in its body parameters any of the region’s fields that you want to update. In the example above, you update the list of countries that are included in that region.
|
||||||
|
|
||||||
|
You can see the list of accepted fields in the [API reference](/api/admin/#tag/Region/operation/PostRegionsRegion).
|
||||||
|
|
||||||
|
This request returns the full object of the updated region.
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
In the example above, the list of countries replace any countries that were previously in the region. So, if you’re adding a country, make sure to include previously added countries as well.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Add a Shipping Option to a Region
|
||||||
|
|
||||||
|
You can add a shipping option to a region by sending a request to the [Create Shipping Option](/api/admin/#tag/Shipping-Option/operation/PostShippingOptions) endpoint:
|
||||||
|
|
||||||
|
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||||
|
<TabItem value="client" label="Medusa JS Client" default>
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
medusa.admin.shippingOptions.create({
|
||||||
|
name: 'PostFake',
|
||||||
|
region_id: regionId,
|
||||||
|
provider_id: "manual",
|
||||||
|
data: {
|
||||||
|
},
|
||||||
|
price_type: 'flat_rate',
|
||||||
|
amount: 1000
|
||||||
|
})
|
||||||
|
.then(({ shipping_option }) => {
|
||||||
|
console.log(shipping_option.id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="fetch" label="Fetch API">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
fetch(`<SERVER_URL>/admin/shipping-options`, {
|
||||||
|
credentials: 'include',
|
||||||
|
method: 'POST',
|
||||||
|
body: JSON.stringify({
|
||||||
|
name: 'PostFake',
|
||||||
|
region_id: regionId,
|
||||||
|
provider_id: "manual",
|
||||||
|
price_type: 'flat_rate',
|
||||||
|
data: {
|
||||||
|
},
|
||||||
|
amount: 1000
|
||||||
|
})
|
||||||
|
})
|
||||||
|
.then((response) => response.json())
|
||||||
|
.then(({ shipping_option }) => {
|
||||||
|
console.log(shipping_option.id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="curl" label="cURL">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
curl -L -X POST '<SERVER_URL>/admin/shipping-options' \
|
||||||
|
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
--data-raw '{
|
||||||
|
"name": "PostFake",
|
||||||
|
"region_id": "<REGION_ID>",
|
||||||
|
"provider_id": "manual",
|
||||||
|
"price_type": "flat_rate",
|
||||||
|
"data": {},
|
||||||
|
"amount": 1000
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
This request requires the following body parameters:
|
||||||
|
|
||||||
|
- `name`: The name of the shipping option.
|
||||||
|
- `region_id`: The ID of the region.
|
||||||
|
- `provider_id`: The ID of the fulfillment provider. The fulfillment provider must be enabled in the region.
|
||||||
|
- `data`: An object of data needed for the fulfillment provider to handle shipping with this shipping option. If none is required, you can pass an empty object.
|
||||||
|
- `price_type`: The price type of the shipping option. Can be `flat_rate` for fixed price, or `calculated` for prices that are calculated using custom logic.
|
||||||
|
- If `price_type` is `flat_rate`, the `amount` field is then required. It is the price of the shipping option. If `price_type` is `calculated`, `amount` is not required.
|
||||||
|
|
||||||
|
The `is_return` body parameter can also be passed if the shipping option is a return shipping option. Its boolean value indicates whether the shipping option is a return option or not.
|
||||||
|
|
||||||
|
This request accepts other optional body parameters, which you can learn more about in the [API reference](/api/admin/#tag/Shipping-Option/operation/PostShippingOptions).
|
||||||
|
|
||||||
|
This request returns the created shipping option.
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
You can also manage shipping options such as list, update, and delete. You can learn more in the [API reference](/api/admin/#tag/Shipping-Option).
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Delete a Region
|
||||||
|
|
||||||
|
You can delete a region by sending a request to the [Delete a Region](/api/admin/#tag/Region/operation/DeleteRegionsRegion) endpoint:
|
||||||
|
|
||||||
|
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||||
|
<TabItem value="client" label="Medusa JS Client" default>
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
medusa.admin.regions.delete(regionId)
|
||||||
|
.then(({ id, object, deleted }) => {
|
||||||
|
console.log(id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="fetch" label="Fetch API">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
fetch(`<SERVER_URL>/admin/regions/${regionId}`, {
|
||||||
|
credentials: 'include',
|
||||||
|
method: 'DELETE'
|
||||||
|
})
|
||||||
|
.then((response) => response.json())
|
||||||
|
.then(({ id, object, deleted }) => {
|
||||||
|
console.log(id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="curl" label="cURL">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
curl -L -X DELETE '<SERVER_URL>/admin/regions/<REGION_ID>' \
|
||||||
|
-H 'Authorization: Bearer <API_TOKEN>'
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
This request requires the region ID as a path parameter. It deletes the region and returns the following fields:
|
||||||
|
|
||||||
|
- `id`: The ID of the deleted region.
|
||||||
|
- `object`: The type of object that was deleted. In this case, the value will be `region`.
|
||||||
|
- `deleted`: A boolean value indicating whether the region was deleted.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What’s Next
|
||||||
|
|
||||||
|
- Learn more about [Regions’ architecture](../backend/regions/overview.md).
|
||||||
|
- Learn [how to use Regions on the storefront](../storefront/use-regions.mdx).
|
||||||
@@ -24,8 +24,6 @@ Discounts can be used in many use cases including:
|
|||||||
2. Creating a sale within a specific period of time (for example, a summer sale).
|
2. Creating a sale within a specific period of time (for example, a summer sale).
|
||||||
3. Give your customers free shipping for a limited time.
|
3. Give your customers free shipping for a limited time.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Discount Entity Overview
|
## Discount Entity Overview
|
||||||
@@ -96,6 +94,8 @@ Based on the value of `type`, one of the following relations can be used to retr
|
|||||||
- `product_tags` is an array of product types that this condition applies to if the condition’s `type` is `product_tags`. Each item of the array would be a [`DiscountConditionProductTag`](../../../references/entities/classes/DiscountConditionProductTag.md).
|
- `product_tags` is an array of product types that this condition applies to if the condition’s `type` is `product_tags`. Each item of the array would be a [`DiscountConditionProductTag`](../../../references/entities/classes/DiscountConditionProductTag.md).
|
||||||
- `customer_groups` is an array of product types that this condition applies to if the condition’s `type` is `customer_groups`. Each item of the array would be a [`DiscountConditionCustomerGroup`](../../../references/entities/classes/DiscountConditionCustomerGroup.md).
|
- `customer_groups` is an array of product types that this condition applies to if the condition’s `type` is `customer_groups`. Each item of the array would be a [`DiscountConditionCustomerGroup`](../../../references/entities/classes/DiscountConditionCustomerGroup.md).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## What’s Next
|
## What’s Next
|
||||||
|
|||||||
117
docs/content/advanced/backend/regions/overview.md
Normal file
117
docs/content/advanced/backend/regions/overview.md
Normal file
@@ -0,0 +1,117 @@
|
|||||||
|
# Regions Overview
|
||||||
|
|
||||||
|
In this document, you’ll learn about Regions and their importance in your Medusa server.
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
Regions represent at least one country on your Medusa server. They're used to define different business logic and configurations for a set of countries.
|
||||||
|
|
||||||
|
For example, you can enable one payment provider for region A, and a different payment provider for region B. Customers can then use the payment provider enabled in their region.
|
||||||
|
|
||||||
|
This applies to other relations and entities in your store such as different currencies, fulfillment providers, and tax providers.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Region Configurations
|
||||||
|
|
||||||
|
The following configurations can be set for each region:
|
||||||
|
|
||||||
|
1. The currency used.
|
||||||
|
2. The tax provider and rates.
|
||||||
|
3. The countries that belong to that region. A country can only belong to one region.
|
||||||
|
4. The enabled payment providers.
|
||||||
|
5. The enabled fulfillment providers.
|
||||||
|
6. The shipping and return shipping options.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## One vs Multiple Regions
|
||||||
|
|
||||||
|
Your store needs at least one region so that your customers can place orders.
|
||||||
|
|
||||||
|
If you serve customers in different countries that use the same configurations, such as the same currency and payment providers, then you can include more countries in the same region.
|
||||||
|
|
||||||
|
If you serve customers in different countries that have at least one different configuration, such as different payment providers, you need to create a new region for those countries.
|
||||||
|
|
||||||
|
There is no limit on how many regions you can create, and regions can share similar configurations.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Region Entity Overview
|
||||||
|
|
||||||
|
A region is stored in the database as a [Region](../../../references/entities/classes/Region.md) entity. Some of its important attributes are:
|
||||||
|
|
||||||
|
- `name`: The name of the region. Customers will see this name on the storefront.
|
||||||
|
- `tax_rate`: A number that indicates the tax rate. The tax rate is a percentage.
|
||||||
|
- `tax_code`: An optional string that is used as the code for the default tax rate.
|
||||||
|
- `gift_cards_taxable`: A boolean value that indicates whether gift cards in a region are taxable or not.
|
||||||
|
- `automatic_taxes`: A boolean value that indicates whether taxes should be calculated during checkout automatically or manually for that region. You can learn more about manually calculating taxes in [this documentation](../taxes/manual-calculation.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Relations to Other Entities
|
||||||
|
|
||||||
|
As regions are a core part of your Medusa server, there are many relations to other entities.
|
||||||
|
|
||||||
|
This section covers relations to entities that make up the configurations of a region.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Country
|
||||||
|
|
||||||
|
A region must have at least one country. A country can belong to only one region.
|
||||||
|
|
||||||
|
The relation between the `Region` and `Country` entities is available on both entities:
|
||||||
|
|
||||||
|
- You can access the countries that belong to a region by expanding the `countries` relation and accessing `region.countries`.
|
||||||
|
- You can access the region of a country by expanding the `region` relation and accessing `country.region`. Also, you can access the ID of the region through `country.region_id`.
|
||||||
|
|
||||||
|
### Currency
|
||||||
|
|
||||||
|
A region must have one currency. A currency can be used for more than one region.
|
||||||
|
|
||||||
|
The relation is available on a region by expanding the `currency` relation and accessing `region.currency`. The 3 character currency code can also be accessed through `region.currency_code`.
|
||||||
|
|
||||||
|
### FulfillmentProvider
|
||||||
|
|
||||||
|
A region must have at least one fulfillment provider. A fulfillment provider can be used in more than one region.
|
||||||
|
|
||||||
|
The relation is available on a region by expanding the `fulfillment_providers` relation and accessing `region.fulfillment_providers`.
|
||||||
|
|
||||||
|
### PaymentProvider
|
||||||
|
|
||||||
|
A region must have at least one payment provider. A payment provider can be used in more than one region.
|
||||||
|
|
||||||
|
The relation is available on a region by expanding the `payment_providers` relation and accessing `region.payment_providers`.
|
||||||
|
|
||||||
|
### ShippingOption
|
||||||
|
|
||||||
|
:::info
|
||||||
|
|
||||||
|
Both shipping options and return shipping options are represented by the `ShippingOption` entity. You can learn more in the [Shipping Architecture documentation](../shipping/overview.md#shipping-option).
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
More than one shipping option can belong to a region. The relation is available on a shipping option by expanding the `region` relation and accessing `shipping_option.region`.
|
||||||
|
|
||||||
|
### TaxProvider
|
||||||
|
|
||||||
|
A region can have one tax provider. A tax provider can be used for more than one region.
|
||||||
|
|
||||||
|
The relation is available on a region by expanding the `tax_provider` relation and accessing `region.tax_provider`. You can also access the ID of the tax provider through `region.tax_provider_id`.
|
||||||
|
|
||||||
|
### TaxRate
|
||||||
|
|
||||||
|
A region can have more than one tax rate, and a tax rate belongs to one region.
|
||||||
|
|
||||||
|
The relation between the `Region` and `TaxRate` entities is available on both entities:
|
||||||
|
|
||||||
|
- You can access the tax rates of a region by expanding the `tax_rates` relation and accessing `region.tax_rates`.
|
||||||
|
- You can access the region of a tax rate by expanding the `region` relation and accessing `tax_rate.region`. You can also access the ID of the region through `tax_rate.region_id`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What’s Next
|
||||||
|
|
||||||
|
- Learn [how to use regions in a storefront using the store REST APIs](../../storefront/use-regions.mdx).
|
||||||
|
- Learn how to [manage regions using the admin REST APIs](../../admin/manage-regions.mdx).
|
||||||
175
docs/content/advanced/storefront/use-regions.mdx
Normal file
175
docs/content/advanced/storefront/use-regions.mdx
Normal file
@@ -0,0 +1,175 @@
|
|||||||
|
import Tabs from '@theme/Tabs';
|
||||||
|
import TabItem from '@theme/TabItem';
|
||||||
|
|
||||||
|
# Use Regions in the Storefront
|
||||||
|
|
||||||
|
In this document, you’ll learn how to use Regions in the storefront.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Regions represent the supported countries and currencies in your store. Customers can use the region that fits them based on their country and currency.
|
||||||
|
|
||||||
|
### Scenario
|
||||||
|
|
||||||
|
You want to implement the following in your storefront:
|
||||||
|
|
||||||
|
- Show customers available regions.
|
||||||
|
- Show product prices based on the selected region.
|
||||||
|
- Set a cart’s region to the selected region.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
### Medusa Components
|
||||||
|
|
||||||
|
It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.md) to get started.
|
||||||
|
|
||||||
|
It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.md) or [Gatsby](../../starters/gatsby-medusa-starter.md) storefronts.
|
||||||
|
|
||||||
|
### JS Client
|
||||||
|
|
||||||
|
This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client and JavaScript’s Fetch API.
|
||||||
|
|
||||||
|
If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../js-client/overview.md) and have [created an instance of the client](../../js-client/overview.md#configuration).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Show List of Regions
|
||||||
|
|
||||||
|
Customers should be able to see the list of available regions and select their region.
|
||||||
|
|
||||||
|
You can retrieve available regions by sending a request to the [List Regions](/api/store/#tag/Region/operation/GetRegions) endpoint:
|
||||||
|
|
||||||
|
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||||
|
<TabItem value="client" label="Medusa JS Client" default>
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
medusa.regions.list()
|
||||||
|
.then(({ regions }) => {
|
||||||
|
console.log(regions.length);
|
||||||
|
//show customers available regions
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="fetch" label="Fetch API">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
fetch(`<SERVER_URL>/store/regions`, {
|
||||||
|
credentials: 'include',
|
||||||
|
})
|
||||||
|
.then((response) => response.json())
|
||||||
|
.then(({ regions }) => {
|
||||||
|
console.log(regions.length);
|
||||||
|
//show customers available regions
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
This request returns the list of available regions. You can show them to your customers to select their region.
|
||||||
|
|
||||||
|
When a customer selects a region, you should store that region’s ID. You’ll need it to show the customer product prices based on the selected region, and set the region of their cart.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Show Product Prices Based on the Selected Region
|
||||||
|
|
||||||
|
To retrieve products with the prices based on the selected regions, you can pass the `region_id` query parameter to the [List Products](/api/store/#tag/Product/operation/GetProducts) or [Get a Product](/api/store/#tag/Product/operation/GetProductsProduct) endpoints.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||||
|
<TabItem value="client" label="Medusa JS Client" default>
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
medusa.products.list({
|
||||||
|
region_id: regionId
|
||||||
|
})
|
||||||
|
.then(({ products, limit, offset, count }) => {
|
||||||
|
console.log(products.length);
|
||||||
|
//show customer the products
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="fetch" label="Fetch API">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
fetch(`<SERVER_URL>/store/products?region_id=${regionId}`, {
|
||||||
|
credentials: 'include',
|
||||||
|
})
|
||||||
|
.then((response) => response.json())
|
||||||
|
.then(({ products, limit, offset, count }) => {
|
||||||
|
console.log(products.length);
|
||||||
|
//show customer the products
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
In this example, you send a request to the List Products endpoint, passing it the `region_id` query parameter. It is assumed that you have the ID of the region stored in the variable `regionId`.
|
||||||
|
|
||||||
|
This request returns the list of products along with [pagination fields](/api/store/#section/Pagination). The prices of the products are based on the selected region.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Set a Cart’s Region
|
||||||
|
|
||||||
|
When the customer changes their region, you must also reflect that change on their cart.
|
||||||
|
|
||||||
|
You can set the cart’s region while creating it and later on by updating it.
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
You can learn how to implement cart functionalities in your storefront in [this documentation](../../guides/carts-in-medusa.mdx).
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||||
|
<TabItem value="client" label="Medusa JS Client" default>
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
medusa.carts.update(cartId, {
|
||||||
|
region_id: regionId
|
||||||
|
})
|
||||||
|
.then(({ cart }) => {
|
||||||
|
console.log(cart.id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="fetch" label="Fetch API">
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
fetch(`<SERVER_URL>/store/carts/${cartId}`, {
|
||||||
|
method: 'POST',
|
||||||
|
credentials: 'include',
|
||||||
|
body: JSON.stringify({
|
||||||
|
region_id: regionId
|
||||||
|
})
|
||||||
|
})
|
||||||
|
.then((response) => response.json())
|
||||||
|
.then(({ cart }) => {
|
||||||
|
console.log(cart.id);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
In this example, you send a request to the [Update Cart](/api/store/#tag/Cart/operation/PostCartsCart) endpoint. In the request’s body, you pass the parameter `region_id` and set its value to the selected region’s ID. It is assumed that you have the ID of the region stored in the variable `regionId`.
|
||||||
|
|
||||||
|
This request returns the full object of the updated cart.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What’s Next
|
||||||
|
|
||||||
|
- Learn [how to implement cart functionalities in your storefront](../../guides/carts-in-medusa.mdx)
|
||||||
|
- Learn [how to implement checkout in your storefront](./how-to-implement-checkout-flow.mdx)
|
||||||
@@ -1,70 +0,0 @@
|
|||||||
---
|
|
||||||
title: Linking your local project with Medusa Cloud
|
|
||||||
---
|
|
||||||
|
|
||||||
<!-- vale off -->
|
|
||||||
|
|
||||||
# Linking your local project with Medusa Cloud
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
In this part of the tutorial you will learn how to link your local Medusa project to Medusa Cloud. Doing this will enhance you development experience as you will closely mimic how Medusa would work in a production environment. Furthermore, you will be able to easily manage orders and products in your local project directly from Medusa Cloud. Linking Medusa is easily done with the Medusa CLI which you should already be installed when you set up your development environment.
|
|
||||||
|
|
||||||
## Creating a Medusa Cloud account and CLI authentication
|
|
||||||
|
|
||||||
To link your local project you must first authenticate to Medusa using your CLI. Authenticating with the CLI is done by running:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
medusa login
|
|
||||||
```
|
|
||||||
|
|
||||||
The `login` command will open your browser where you will be presented with the authentication options available. If you already have an account you can simply authenticate and you CLI will automatically be authenticated.
|
|
||||||
|
|
||||||
If you don't have an account yet you can easily create one as part of the CLI authentication. First, choose the method that you want to login with we support logging in with GitHub, Google or simple email/password authentication. If choosing GitHub or Google without an existing account you will be taken straight to the sign up form where you can fill in your details and create an account. If you wish to sign up with an email/password combination simply click "Log in with email" and at the bottom of the form click "Sign up". Once you have filled out the sign up form your CLI will be authenticated.
|
|
||||||
|
|
||||||
To test that you have successfully authenticated you can run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
medusa whoami
|
|
||||||
```
|
|
||||||
|
|
||||||
This will print out your account details.
|
|
||||||
|
|
||||||
## Linking your local project
|
|
||||||
|
|
||||||
Once you have authenticated your CLI for your Medusa Cloud account you are ready to perform local linking. To link your project first naviagate to your project root - where your `medusa-config.js` file is. You can now run the following command:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
medusa link --develop
|
|
||||||
```
|
|
||||||
|
|
||||||
The `link` command will first check that you have authenticated your CLI which we did in the previous step. Then it will perform the local linking, which essentially adds an admin user in the local database specified in `medusa-config.js`. Finally, your browser will open Medusa Cloud to perform the linking there, which tells Medusa Cloud where your local server is running. On successful linking in the browser you will see a confirmation page with a "Go to orders" button. If you click this button you will be taken to an overview of the orders made in your local project.
|
|
||||||
|
|
||||||
You should note that the `--develop` flag is optional for the `link` command. If provided it tells the CLI to start up your server after linking is completed; you may leave it out if you'd rather start your server separately.
|
|
||||||
|
|
||||||
:::note
|
|
||||||
|
|
||||||
For local linking to work you must make sure to have your CORS settings configured correctly. This is done by adding `https://app.medusajs.com` to your `cors_admin` config in `medusa-config.js`.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
:::note
|
|
||||||
|
|
||||||
If you change the port that your local server is running on you will have to run `medusa link` again. `medusa link` uses your `PORT` environment variable to specify where Medusa Cloud should look for your local server.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
You are now able to run a local development environment that is nearly identical to a production environment. This is made possible by linking your local project using the `medusa link` command. In Medusa Cloud you will be able to manage your store and test the features you are developing.
|
|
||||||
|
|
||||||
### What's next?
|
|
||||||
|
|
||||||
You are all set to start developing on your Medusa project. If you haven't already now would be a good time to add a front-end to your Medusa server. We have two starters that you can use to get going:
|
|
||||||
|
|
||||||
- [Nextjs Starter](https://github.com/medusajs/nextjs-starter-medusa)
|
|
||||||
- [Gatsby Starter](https://github.com/medusajs/gatsby-starter-medusa)
|
|
||||||
|
|
||||||
The final step to take from here is to deploy your Medusa project. We will cover how this is done in the next part of the tutorial (Coming soon!).
|
|
||||||
|
|
||||||
<!-- vale on -->
|
|
||||||
@@ -220,6 +220,11 @@ module.exports = {
|
|||||||
type: "category",
|
type: "category",
|
||||||
label: "Storefront",
|
label: "Storefront",
|
||||||
items: [
|
items: [
|
||||||
|
{
|
||||||
|
type: "doc",
|
||||||
|
id: "advanced/storefront/use-regions",
|
||||||
|
label: "Use Regions"
|
||||||
|
},
|
||||||
{
|
{
|
||||||
type: "doc",
|
type: "doc",
|
||||||
id: "guides/carts-in-medusa",
|
id: "guides/carts-in-medusa",
|
||||||
@@ -256,6 +261,11 @@ module.exports = {
|
|||||||
type: "category",
|
type: "category",
|
||||||
label: "Admin",
|
label: "Admin",
|
||||||
items: [
|
items: [
|
||||||
|
{
|
||||||
|
type: "doc",
|
||||||
|
id: "advanced/admin/manage-regions",
|
||||||
|
label: "Manage Regions"
|
||||||
|
},
|
||||||
{
|
{
|
||||||
type: "doc",
|
type: "doc",
|
||||||
id: "advanced/admin/import-products",
|
id: "advanced/admin/import-products",
|
||||||
@@ -417,6 +427,11 @@ module.exports = {
|
|||||||
id: "advanced/backend/batch-jobs/index",
|
id: "advanced/backend/batch-jobs/index",
|
||||||
label: "Batch Jobs"
|
label: "Batch Jobs"
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
type: "doc",
|
||||||
|
id: "advanced/backend/regions/overview",
|
||||||
|
label: "Regions"
|
||||||
|
},
|
||||||
{
|
{
|
||||||
type: "doc",
|
type: "doc",
|
||||||
id: "advanced/backend/taxes/inclusive-pricing",
|
id: "advanced/backend/taxes/inclusive-pricing",
|
||||||
|
|||||||
Reference in New Issue
Block a user