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

docs: update endpoints to use file-routing approach (#5397)

Browse Source 
- 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 authored and GitHub committed 2023-10-19 15:56:26 +00:00
1 parent b38f73726d
commit c28935b4e8
170 files changed
+3658 -3344
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

www/apps/docs/content/modules/carts-and-checkout/backend/add-fulfillment-provider.md
+4 -4
View File
@@ -162,13 +162,13 @@ class MyFulfillmentService extends AbstractFulfillmentService {
### getFulfillmentOptions
This method is used when retrieving the list of fulfillment options available in a region, particularly by the [List Fulfillment Options endpoint](https://docs.medusajs.com/api/admin#regions_getregionsregionfulfillmentoptions).
This method is used when retrieving the list of fulfillment options available in a region, particularly by the [List Fulfillment Options API Route](https://docs.medusajs.com/api/admin#regions_getregionsregionfulfillmentoptions).
For example, if you’re integrating UPS as a fulfillment provider, you might support two fulfillment options: UPS Express Shipping and UPS Access Point. Each of these options can have different data associated with them.
This method is expected to return an array of options. These options don't have any required format.
Later on, these options can be used when creating a shipping option, such as when using the [Create Shipping Option endpoint](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions). The chosen fulfillment option, which is one of the items in the array returned by this method, will be set in the `data` object of the shipping option.
Later on, these options can be used when creating a shipping option, such as when using the [Create Shipping Option API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions). The chosen fulfillment option, which is one of the items in the array returned by this method, will be set in the `data` object of the shipping option.
For example:
@@ -190,7 +190,7 @@ class MyFulfillmentService extends AbstractFulfillmentService {
### validateOption
Once the admin creates the shipping option, the data of the shipping option will be validated first using this method. This method is called when the [Create Shipping Option endpoint](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions) is used.
Once the admin creates the shipping option, the data of the shipping option will be validated first using this method. This method is called when the [Create Shipping Option API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions) is used.
This method accepts the `data` object that is sent in the body of the request, basically, the `data` object of the shipping option. You can use this data to validate the shipping option before it is saved.
@@ -223,7 +223,7 @@ This method accepts three parameters:
You can use these parameters to validate the chosen shipping option. For example, you can check if the `data` object passed as a second parameter includes all data needed to fulfill the shipment later on.
If any of the data is invalid, you can throw an error. This error will stop Medusa from creating a shipping method and the error message will be returned as a result to the endpoint.
If any of the data is invalid, you can throw an error. This error will stop Medusa from creating a shipping method and the error message will be returned as a result of the API Route.
If everything is valid, this method must return an object that will be stored in the `data` property of the shipping method to be created. So, make sure the value you return contains everything you need to fulfill the shipment later on.
www/apps/docs/content/modules/carts-and-checkout/backend/add-payment-provider.md
+2 -2
View File
@@ -510,7 +510,7 @@ class MyPaymentService extends AbstractPaymentProcessor {
This method is used to capture the payment amount of an order. This is typically triggered manually by the store operator from the admin.
This method is also used for capturing payments of a swap of an order, or when the [Capture Payment](https://docs.medusajs.com/api/admin#payments_postpaymentspaymentcapture) endpoint is called.
This method is also used for capturing payments of a swap of an order, or when a request is sent to the [Capture Payment API Route](https://docs.medusajs.com/api/admin#payments_postpaymentspaymentcapture).
You can utilize this method to interact with the third-party provider and perform any actions necessary to capture the payment.
@@ -538,7 +538,7 @@ class MyPaymentService extends AbstractPaymentProcessor {
This method is used to refund an order’s payment. This is typically triggered manually by the store operator from the admin. The refund amount might be the total order amount or part of it.
This method is also used for refunding payments of a swap or a claim of an order, or when the [Refund Payment](https://docs.medusajs.com/api/admin#payments_postpaymentspaymentrefunds) endpoint is called.
This method is also used for refunding payments of a swap or a claim of an order, or when a request is sent to the [Refund Payment API Route](https://docs.medusajs.com/api/admin#payments_postpaymentspaymentrefunds).
You can utilize this method to interact with the third-party provider and perform any actions necessary to refund the payment.
www/apps/docs/content/modules/carts-and-checkout/backend/cart-completion-strategy.md
+2 -2
View File
@@ -85,7 +85,7 @@ In the above example, you inject the `IdempotencyKeyService` in the constructor.
## Step 2: Implement the complete Method
The cart completion strategy is required to implement a single method: the `complete` method. This method is used in the [Complete Cart endpoint](https://docs.medusajs.com/api/store#carts_postcartscartcomplete) to handle the logic of completing the cart.
The cart completion strategy is required to implement a single method: the `complete` method. This method is used in the [Complete Cart API Route](https://docs.medusajs.com/api/store#carts_postcartscartcomplete) to handle the logic of completing the cart.
The method accepts three parameters:
@@ -120,7 +120,7 @@ Run your backend to test it out:
npx medusa develop
```
Then, try out your strategy using the Complete Cart endpoint. You should see the logic you implemented used for completing the cart.
Then, try out your strategy using the Complete Cart API Route. You should see the logic you implemented used for completing the cart.
---
www/apps/docs/content/modules/carts-and-checkout/cart.md
+1 -1
View File
@@ -63,7 +63,7 @@ The cart’s totals are retrieved by default in all the [cart’s store APIs](ht
The cart completion functionality is implemented inside the strategy `cartCompletionStrategy`. This allows you to customize how the process is implemented in your store.
You can initiate the cart completion process by sending a request to the [Complete Cart endpoint](https://docs.medusajs.com/api/store#carts_postcartscartcomplete).
You can initiate the cart completion process by sending a request to the [Complete Cart API Route](https://docs.medusajs.com/api/store#carts_postcartscartcomplete).
### Idempotency Key
www/apps/docs/content/modules/carts-and-checkout/storefront/implement-checkout-flow.mdx
+8 -8
View File
@@ -60,7 +60,7 @@ In this step, the customer generally enters their shipping info, then chooses th
### Add Shipping Address
After the customer enters their shipping address information, you must send a `POST` request to the [Update a Cart](https://docs.medusajs.com/api/store#carts_postcartscart) API endpoint:
After the customer enters their shipping address information, you must send a `POST` request to the [Update a Cart API Route](https://docs.medusajs.com/api/store#carts_postcartscart):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -164,7 +164,7 @@ The request returns the updated cart, with the new shipping address available in
After updating the cart with the customer’s address, the list of available [shipping options](../shipping.md#shipping-option) for that cart might change. So, you should retrieve the updated list of options.
You can retrieve the list of shipping options by sending a `GET` request to the [Retrieve Shipping Options for Cart API](https://docs.medusajs.com/api/store#shipping-options_getshippingoptionscartid) endpoint:
You can retrieve the list of shipping options by sending a `GET` request to the [Retrieve Shipping Options for Cart API Route](https://docs.medusajs.com/api/store#shipping-options_getshippingoptionscartid):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -234,7 +234,7 @@ The request accepts the ID of the cart as a path parameter. It returns the array
### Choose Shipping Option
Once the customer chooses one of the available shipping options, send a `POST` request to the [Add a Shipping Method](https://docs.medusajs.com/api/store#carts_postcartscartshippingmethod) API endpoint. This will create a [shipping method](../shipping.md#shipping-method) based on the shipping option chosen and will associate it with the customer’s cart:
Once the customer chooses one of the available shipping options, send a `POST` request to the [Add a Shipping Method API Route](https://docs.medusajs.com/api/store#carts_postcartscartshippingmethod). This will create a [shipping method](../shipping.md#shipping-method) based on the shipping option chosen and will associate it with the customer’s cart:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -308,7 +308,7 @@ In this step, the customer generally chooses a payment method to complete their
When the page opens and before the payment providers are displayed to the customer to choose from, you must create the [payment sessions](../payment.md#payment-session) for the current cart. Each payment provider will have a payment session associated with it. These payment sessions will be used later when the customer chooses the payment provider they want to complete their purchase with.
To initialize the payment sessions, send a `POST` request to the [Initialize Payment Sessions](https://docs.medusajs.com/api/store#carts_postcartscartpaymentsession) API endpoint:
To initialize the payment sessions, send a `POST` request to the [Initialize Payment Sessions API Route](https://docs.medusajs.com/api/store#carts_postcartscartpaymentsession):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -372,11 +372,11 @@ fetch(`<BACKEND_URL>/store/carts/${cartId}/payment-sessions`, {
</TabItem>
</Tabs>
This endpoint accepts the ID of the cart as a path parameter. It returns the updated cart with the initialized payment sessions available on `cart.payment_sessions`.
This API Route accepts the ID of the cart as a path parameter. It returns the updated cart with the initialized payment sessions available on `cart.payment_sessions`.
### Select Payment Session
When the customer chooses the payment processor they want to complete purchase with, you should select the payment session associated with that payment processor. To do that, send a `POST` request to the [Select a Payment Session](https://docs.medusajs.comapi/store#carts_postcartscartpaymentsession) API endpoint:
When the customer chooses the payment processor they want to complete purchase with, you should select the payment session associated with that payment processor. To do that, send a `POST` request to the [Select a Payment Session API Route](https://docs.medusajs.comapi/store#carts_postcartscartpaymentsession):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -451,7 +451,7 @@ If you have one payment processor or if only one payment processor is available
This step is optional and is only necessary for some payment processors. As mentioned in the [Payment Architecture](../payment.md#overview) documentation, the `PaymentSession` model has a `data` attribute that holds any data required for the Payment Processor to perform payment operations such as capturing payment.
If you need to update that data at any point before the purchase is made, send a request to [Update a Payment Session](https://docs.medusajs.com/api/store#carts_postcartscartpaymentsessionupdate) API endpoint:
If you need to update that data at any point before the purchase is made, send a request to [Update a Payment Session API Route](https://docs.medusajs.com/api/store#carts_postcartscartpaymentsessionupdate):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -537,7 +537,7 @@ It returns the updated cart. You can access the payment session's data on `cart.
The last step is to place the order by completing the cart. When you complete the cart, your Medusa backend will try to authorize the payment first, then place the order if the authorization is successful. So, you should perform any necessary action with your payment processor first to make sure the authorization is successful when you send the request to complete the cart.
To complete a cart, send a `POST` request to the [Complete a Cart](https://docs.medusajs.com/api/store#carts_postcartscartcomplete) API endpoint:
To complete a cart, send a `POST` request to the [Complete a Cart API Route](https://docs.medusajs.com/api/store#carts_postcartscartcomplete):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/customers/admin/manage-customer-groups.mdx
+8 -8
View File
@@ -48,7 +48,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## Create Customer Groups
You can create a customer group by sending a request to the Create Customer Group endpoint:
You can create a customer group by sending a request to the Create Customer Group API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -131,7 +131,7 @@ This request requires the `name` parameter and optionally accepts the `metadata`
## List Customer Groups
You can get a list of all customer groups by sending a request to the List Customer Groups endpoint:
You can get a list of all customer groups by sending a request to the List Customer Groups API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -212,7 +212,7 @@ You can also pass filters and other selection query parameters to the request. C
## Retrieve a Customer Group
You can retrieve a single customer group by sending a request to the Get a Customer Group endpoint:
You can retrieve a single customer group by sending a request to the Get a Customer Group API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -279,7 +279,7 @@ This request accepts the ID of the customer group to retrieve as a path paramete
## Update a Customer Group
You can update a customer group’s data by sending a request to the Update Customer Group endpoint:
You can update a customer group’s data by sending a request to the Update Customer Group API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -373,7 +373,7 @@ This request accepts the ID of the customer group as a path parameter, and optio
## Delete Customer Group
You can delete a customer group by sending a request to the Delete a Customer Group endpoint:
You can delete a customer group by sending a request to the Delete a Customer Group API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -443,7 +443,7 @@ This request accepts the ID of the customer group to delete as a path parameter.
### Add Customer to Group
You can add a customer to a group by sending a request to the Customer Group’s Add Customer endpoint:
You can add a customer to a group by sending a request to the Customer Group’s Add Customer API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -543,7 +543,7 @@ This request accepts the ID of the customer group as a path parameter. In its bo
### List Customers
You can retrieve a list of all customers in a customer group using the List Customers endpoint:
You can retrieve a list of all customers in a customer group using the List Customers API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -626,7 +626,7 @@ Removing customers from a group does not remove them entirely. They’ll still b
:::
You can remove customers from a customer group by sending a request to the Remove Customers endpoint:
You can remove customers from a customer group by sending a request to the Remove Customers API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/customers/admin/manage-customers.mdx
+3 -3
View File
@@ -52,7 +52,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Customers
You can show a list of customers by sending a request to the [List Customers](https://docs.medusajs.com/api/admin#customers_getcustomers) endpoint:
You can show a list of customers by sending a request to the [List Customers API Route](https://docs.medusajs.com/api/admin#customers_getcustomers):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -139,7 +139,7 @@ You can learn more about pagination in the [API reference](https://docs.medusajs
Admins can create customer accounts. They have to supply the customer’s credentials and basic info.
You can create a customer account by sending a request to the [Create a Customer](https://docs.medusajs.com/api/admin#customers_postcustomers) endpoint:
You can create a customer account by sending a request to the [Create a Customer API Route](https://docs.medusajs.com/api/admin#customers_postcustomers):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -246,7 +246,7 @@ The request returns the created customer object in the response.
An admin can edit a customer’s basic information and credentials.
You can edit a customer’s information by sending a request to the [Update a Customer](https://docs.medusajs.com/api/admin#customers_postcustomerscustomer) endpoint:
You can edit a customer’s information by sending a request to the [Update a Customer API Route](https://docs.medusajs.com/api/admin#customers_postcustomerscustomer):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/customers/storefront/implement-customer-profiles.mdx
+12 -12
View File
@@ -12,7 +12,7 @@ In this document, you’ll learn how to implement customer account functionaliti
## Overview
Medusa provides the necessary functionalities and endpoints to allow integrating essential customer features. Customers can create accounts to manage their information and keep track of their orders.
Medusa provides the necessary functionalities and API Routes to allow integrating essential customer features. Customers can create accounts to manage their information and keep track of their orders.
### Scenario
@@ -58,7 +58,7 @@ If you follow the Medusa React code blocks, it's assumed you already have [Medus
A customer can register with an email and a password to store and manage their data.
You can register a new customer by sending a request to the [Create a Customer](https://docs.medusajs.com/api/store#customers_postcustomers) endpoint:
You can register a new customer by sending a request to the [Create a Customer API Route](https://docs.medusajs.com/api/store#customers_postcustomers):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -135,7 +135,7 @@ fetch(`<BACKEND_URL>/store/customers`, {
This request requires the following body parameters:
- `email`: An email used to log in after registration. This email must be unique. You can check if an email is unique using the “[Check if email exists](https://docs.medusajs.com/api/store#auth_getauthemail)” endpoint.
- `email`: An email used to log in after registration. This email must be unique. You can check if an email is unique using the “[Check if email exists](https://docs.medusajs.com/api/store#auth_getauthemail)” API Route.
- `password`: A password used to log in after registration.
- `first_name`: The customer’s first name.
- `last_name`: The customer’s last name.
@@ -150,7 +150,7 @@ It returns the created customer object in the response.
A customer can log in to your store to manage their data and make purchases using their account.
You can log in a customer into your store by sending a request to the [Customer Login](https://docs.medusajs.com/api/store#auth_postauth) endpoint:
You can log in a customer into your store by sending a request to the [Customer Login API Route](https://docs.medusajs.com/api/store#auth_postauth):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -199,7 +199,7 @@ However, if you’re using the Fetch API, you must include the option `credentia
## Log out a Customer
You can log out a customer by sending a request to the [Customer Logout](https://docs.medusajs.com/api/store#auth_deleteauth) endpoint:
You can log out a customer by sending a request to the [Customer Logout API Route](https://docs.medusajs.com/api/store#auth_deleteauth):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -239,7 +239,7 @@ Customers might need to reset their password in case they forget it. To reset a
The customer must first enter their account’s email. Then, if an account with that email address exists, an email will be sent to that email address with a link that points the customer to step 2.
You can request to reset a customer’s password by sending a request to the [Request Password Reset](https://docs.medusajs.com/api/store#customers_postcustomerscustomerpasswordtoken) endpoint:
You can request to reset a customer’s password by sending a request to the [Request Password Reset API Route](https://docs.medusajs.com/api/store#customers_postcustomerscustomerpasswordtoken):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -295,7 +295,7 @@ If the customer doesn’t receive an email after this request, make sure that yo
After the first step, the customer should receive an email with a link to a page in the storefront. This page should accept a `token` query parameter. Then, the customer should be prompted to enter their email and password.
You can then reset the customer’s password to the new password they enter by sending a request to the [Reset Password](https://docs.medusajs.com/api/store#customers_postcustomersresetpassword) endpoint:
You can then reset the customer’s password to the new password they enter by sending a request to the [Reset Password API Route](https://docs.medusajs.com/api/store#customers_postcustomersresetpassword):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -350,7 +350,7 @@ If successful, this request returns the customer object in the response.
A logged-in customer can edit their info, such as their first name or email address.
You can edit a customer’s info using the [Update Customer](https://docs.medusajs.com/api/store#customers_postcustomerscustomer) endpoint:
You can edit a customer’s info using the [Update Customer API Route](https://docs.medusajs.com/api/store#customers_postcustomerscustomer):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -435,7 +435,7 @@ The customer object returned in the requests mentioned in this document include
### Add a Shipping Address
You can add a shipping address to a customer’s account by sending a request to the [Add a Shipping Address](https://docs.medusajs.com/api/store#customers_postcustomerscustomeraddresses) endpoint:
You can add a shipping address to a customer’s account by sending a request to the [Add a Shipping Address API Route](https://docs.medusajs.com/api/store#customers_postcustomerscustomeraddresses):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -511,7 +511,7 @@ This request returns the updated customer object in the response.
### Edit a Shipping Address
You can edit a customer’s shipping address using the [Update a Shipping Address](https://docs.medusajs.com/api/store#customers_postcustomerscustomeraddressesaddress) endpoint:
You can edit a customer’s shipping address using the [Update a Shipping Address API Route](https://docs.medusajs.com/api/store#customers_postcustomerscustomeraddressesaddress):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -556,7 +556,7 @@ This request returns the updated customer object in the response.
### Delete a Shipping Address
You can delete a shipping address by sending a request to the [Delete an Address](https://docs.medusajs.com/api/store#customers_deletecustomerscustomeraddressesaddress) endpoint:
You can delete a shipping address by sending a request to the [Delete an Address API Route](https://docs.medusajs.com/api/store#customers_deletecustomerscustomeraddressesaddress):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -595,7 +595,7 @@ This request requires the address’s ID as a path parameter. It returns in the
Logged-in customers can see their orders along with the orders’ details.
You can retrieve a customer’s orders by sending a request to the [List Orders](https://docs.medusajs.com/api/store#customers_getcustomerscustomerorders) endpoint:
You can retrieve a customer’s orders by sending a request to the [List Orders API Route](https://docs.medusajs.com/api/store#customers_getcustomerscustomerorders):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/discounts/admin/manage-discounts.mdx
+7 -7
View File
@@ -64,7 +64,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## Create a Discount
You can create a discount by sending a request to the [Create Discount](https://docs.medusajs.com/api/admin#discounts_postdiscounts) endpoint:
You can create a discount by sending a request to the [Create Discount API Route](https://docs.medusajs.com/api/admin#discounts_postdiscounts):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -202,7 +202,7 @@ This request returns the full `discount` object.
## Update Discount
You can update any of the discount’s information, configurations, and conditions by sending a request to the [Update Discount](https://docs.medusajs.com/api/admin#discounts_postdiscountsdiscount) endpoint.
You can update any of the discount’s information, configurations, and conditions by sending a request to the [Update Discount API Route](https://docs.medusajs.com/api/admin#discounts_postdiscountsdiscount).
For example, you can update the discount’s description and status by sending the following request:
@@ -294,7 +294,7 @@ You can learn more about conditions and conditions types in the [Discount Archit
:::
You can send a request to the [Create Condition](https://docs.medusajs.com/api/admin#discounts_postdiscountsdiscountconditions) endpoint to create a condition in a discount:
You can send a request to the [Create Condition API Route](https://docs.medusajs.com/api/admin#discounts_postdiscountsdiscountconditions) to create a condition in a discount:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -407,7 +407,7 @@ This request returns the full `discount` object in the response which includes a
### Retrieve Condition
You can retrieve a condition and its resources by sending a request to the [Get Condition](https://docs.medusajs.com/api/admin#discounts_getdiscountsdiscountconditionscondition) endpoint:
You can retrieve a condition and its resources by sending a request to the [Get Condition API Route](https://docs.medusajs.com/api/admin#discounts_getdiscountsdiscountconditionscondition):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -506,7 +506,7 @@ In the previous example, you pass `expand=products` as a query parameter, which
### Update Condition
You can update a condition’s resources using the [Update Condition](https://docs.medusajs.com/api/admin#discounts_postdiscountsdiscountconditionscondition) endpoint. You can’t update a condition’s operator.
You can update a condition’s resources using the [Update Condition API Route](https://docs.medusajs.com/api/admin#discounts_postdiscountsdiscountconditionscondition). You can’t update a condition’s operator.
For example, to update the products in a condition:
@@ -608,7 +608,7 @@ This request returns the full `discount` object with the updated condition in th
### Delete Condition
You can delete a condition by sending a request to the [Delete Condition](https://docs.medusajs.com/api/admin#discounts_deletediscountsdiscountconditionscondition) endpoint:
You can delete a condition by sending a request to the [Delete Condition API Route](https://docs.medusajs.com/api/admin#discounts_deletediscountsdiscountconditionscondition):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -683,7 +683,7 @@ It returns the `discount` object in the response.
## Delete Discount
You can delete a discount by sending a request to the [Delete Discount](https://docs.medusajs.com/api/admin#discounts_deletediscountsdiscount) endpoint:
You can delete a discount by sending a request to the [Delete Discount API Route](https://docs.medusajs.com/api/admin#discounts_deletediscountsdiscount):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx
+10 -10
View File
@@ -59,11 +59,11 @@ You can learn more about [authenticating as an admin user in the API reference](
This section covers managing the gift card products. Each gift card can have unlimited denominations.
As gift cards are, before purchase, essentially products, you’ll be using product endpoints to manage them.
As gift cards are, before purchase, essentially products, you’ll be using product API Routes to manage them.
### Retrieve Gift Card Product
You can retrieve the gift card products by sending a request to the [List Products](https://docs.medusajs.com/api/admin#products_getproducts) endpoint, but filtering the products with the `is_giftcard` flag:
You can retrieve the gift card products by sending a request to the [List Products API Route](https://docs.medusajs.com/api/admin#products_getproducts), but filtering the products with the `is_giftcard` flag:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -146,13 +146,13 @@ curl -L -X GET '<BACKEND_URL>/admin/products?is_giftcard=true' \
</TabItem>
</Tabs>
The List Products endpoint accepts a variety of query parameters that can be used to filter the products. One of them is `is_giftcard`. When set to `true`, it will only retrieve the gift card products.
The List Products API Route accepts a variety of query parameters that can be used to filter the products. One of them is `is_giftcard`. When set to `true`, it will only retrieve the gift card products.
The request returns the `products` array in the response which holds the gift card in it, if it’s available. It also returns [pagination fields](https://docs.medusajs.com/api/admin#pagination).
### Create Gift Card Product
You can create a gift card product by sending a request to the [Create a Product](https://docs.medusajs.com/api/admin#products_postproducts) endpoint:
You can create a gift card product by sending a request to the [Create a Product API Route](https://docs.medusajs.com/api/admin#products_postproducts):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -353,7 +353,7 @@ Although you can create an unlimited number of gift cards, the admin dashboard's
After creating a gift card, merchants can update it or its denomination.
You can update a gift card product’s details by sending a request to the [Update a Product](https://docs.medusajs.com/api/admin#products_postproductsproduct) endpoint:
You can update a gift card product’s details by sending a request to the [Update a Product API Route](https://docs.medusajs.com/api/admin#products_postproductsproduct):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -432,7 +432,7 @@ This request returns the updated gift card product in the response.
### Delete Gift Card Product
You can delete a gift card product by sending a request to the [Delete a Product](https://docs.medusajs.com/api/admin#products_deleteproductsproduct) endpoint:
You can delete a gift card product by sending a request to the [Delete a Product API Route](https://docs.medusajs.com/api/admin#products_deleteproductsproduct):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -505,7 +505,7 @@ This section covers how to manage custom gift cards. You can create an unlimited
### List Custom Gift Cards
You can retrieve all custom gift cards by sending a request to the [List Gift Cards](https://docs.medusajs.com/api/admin#gift-cards_getgiftcards) endpoint:
You can retrieve all custom gift cards by sending a request to the [List Gift Cards API Route](https://docs.medusajs.com/api/admin#gift-cards_getgiftcards):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -579,7 +579,7 @@ This request returns an array of `gift_cards` and [pagination fields](https://do
Merchants can create custom gift cards to send a reward or gift to the customer.
You can create a custom gift card by sending a request to the [Create a Gift Card](https://docs.medusajs.com/api/admin#gift-cards_postgiftcards) endpoint:
You can create a custom gift card by sending a request to the [Create a Gift Card API Route](https://docs.medusajs.com/api/admin#gift-cards_postgiftcards):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -664,7 +664,7 @@ This request returns the created gift card object in the response.
Merchants can update any of the gift card’s properties, except for the value of the gift card.
You can update a gift card by sending a request to the [Update a Gift Card](https://docs.medusajs.com/api/admin#gift-cards_postgiftcardsgiftcard) endpoint:
You can update a gift card by sending a request to the [Update a Gift Card API Route](https://docs.medusajs.com/api/admin#gift-cards_postgiftcardsgiftcard):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -745,7 +745,7 @@ This request returns the updated gift card object in the response.
### Delete Custom Gift Card
You can delete a custom gift card by sending a request to the [Delete a Gift Card](https://docs.medusajs.com/api/admin#gift-cards_deletegiftcardsgiftcard) endpoint:
You can delete a custom gift card by sending a request to the [Delete a Gift Card API Route](https://docs.medusajs.com/api/admin#gift-cards_deletegiftcardsgiftcard):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx
+4 -4
View File
@@ -58,7 +58,7 @@ In addition, this document doesn't cover how to implement checkout functionality
Customers should be able to view gift cards before they make the purchase. Gift cards are essentially products like any other.
You can retrieve the gift card product using the [List Products](https://docs.medusajs.com/api/store#products_getproducts) endpoint, but passing it the `is_giftcard` query parameter:
You can retrieve the gift card product using the [List Products API Route](https://docs.medusajs.com/api/store#products_getproducts), but passing it the `is_giftcard` query parameter:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -147,7 +147,7 @@ The value of each denomination (or variant) is under the `prices` array. If you
After the customer purchases the gift card, they’ll receive a code to redeem that gift card. Using that code, the customer can also view the details of that gift card.
You can retrieve the details of a gift card by sending a request to the [Get Gift Card by Code](https://docs.medusajs.com/api/store#gift-cards_getgiftcardscode) endpoint:
You can retrieve the details of a gift card by sending a request to the [Get Gift Card by Code API Route](https://docs.medusajs.com/api/store#gift-cards_getgiftcardscode):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -222,7 +222,7 @@ You can learn what other properties are available in the returned gift card obje
A customer can redeem more than one gift card during checkout. The cart’s totals will then be adjusted based on the applied gift card. The gift card’s amount isn’t actually used until the order is placed.
You can redeem a gift card during checkout by sending a request to the [Update Cart](https://docs.medusajs.com/api/store#carts_postcartscart) endpoint:
You can redeem a gift card during checkout by sending a request to the [Update Cart API Route](https://docs.medusajs.com/api/store#carts_postcartscart):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -306,7 +306,7 @@ To add gift cards, you must pass the array `gift_cards`. Each item in the array
:::tip
The parameters passed in the update endpoint replace existing values. So, if you previously added a gift card, then tried adding another, you must include both in the `gift_cards` array.
The parameters passed to the update API Route replace existing values. So, if you previously added a gift card, then tried adding another, you must include both in the `gift_cards` array.
:::
www/apps/docs/content/modules/multiwarehouse/admin/manage-inventory-items.mdx
+18 -18
View File
@@ -57,7 +57,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Inventory Items
You can list inventory items by sending a request to the [List Inventory Items endpoint](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitems):
You can list inventory items by sending a request to the [List Inventory Items API Route](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitems):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -126,7 +126,7 @@ curl -L -X GET '<BACKEND_URL>/admin/inventory-items' \
</TabItem>
</Tabs>
This endpoint does not require any path or query parameters. You can, however, pass path parameters to search or filter inventory items. For example, you can get inventory items in a specific location by passing the `location_id` query parameter. You can learn more about available query parameters in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitems).
This API Route doesn't require any path or query parameters. You can, however, pass path parameters to search or filter inventory items. For example, you can get inventory items in a specific location by passing the `location_id` query parameter. You can learn more about available query parameters in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitems).
This request returns an array of inventory item objects.
@@ -140,7 +140,7 @@ Inventory items are automatically created when a variant is created with `manage
:::
You can create an inventory item by sending a request to the [Create Inventory Item endpoint](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitems):
You can create an inventory item by sending a request to the [Create Inventory Item API Route](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitems):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -211,7 +211,7 @@ curl -L -X POST '<BACKEND_URL>/admin/inventory-items' \
</TabItem>
</Tabs>
This endpoint requires in the body parameter the `variant_id` parameter, which is the ID of the variant to create this inventory item for. You can also pass other inventory-related parameters, such as `sku`. You can learn more about other available parameters in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitems).
This API Route requires in the body parameter the `variant_id` parameter, which is the ID of the variant to create this inventory item for. You can also pass other inventory-related parameters, such as `sku`. You can learn more about other available parameters in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitems).
This request returns the created inventory item as an object.
@@ -219,7 +219,7 @@ This request returns the created inventory item as an object.
## Retrieve Inventory Item
You can retrieve an inventory item by sending a request to the [Get Inventory Item endpoint](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitemsinventoryitem):
You can retrieve an inventory item by sending a request to the [Get Inventory Item API Route](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitemsinventoryitem):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -281,7 +281,7 @@ curl -L -X GET '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>' \
</TabItem>
</Tabs>
This endpoint accepts the ID of the inventory item as a path parameter. You can also path query parameters such as [expand](https://docs.medusajs.com/api/admin#expanding-fields) and [fields](https://docs.medusajs.com/api/admin#selecting-fields).
This API Route accepts the ID of the inventory item as a path parameter. You can also path query parameters such as [expand](https://docs.medusajs.com/api/admin#expanding-fields) and [fields](https://docs.medusajs.com/api/admin#selecting-fields).
The request returns the inventory item as an object.
@@ -289,7 +289,7 @@ The request returns the inventory item as an object.
## Update Inventory Item
You can update an inventory item by sending a request to the [Update Inventory Item endpoint](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitem):
You can update an inventory item by sending a request to the [Update Inventory Item API Route](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitem):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -364,7 +364,7 @@ curl -L -X POST '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>' \
</TabItem>
</Tabs>
This endpoint requires the inventory item’s ID as a path parameter. You can pass any of the inventory item’s attributes that you want to update in its body parameter. The example above updates the value of the `origin_country` attribute. You can learn more about available body parameters in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitem).
This API Route requires the inventory item’s ID as a path parameter. You can pass any of the inventory item’s attributes that you want to update in its body parameter. The example above updates the value of the `origin_country` attribute. You can learn more about available body parameters in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitem).
The request returns the updated inventory item as an object.
@@ -376,7 +376,7 @@ This section shows you the different ways you can manage inventory levels. Each
### List inventory levels
You can list inventory levels of an inventory item by sending a request to the [List inventory levels endpoint](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitemsinventoryitemlocationlevels):
You can list inventory levels of an inventory item by sending a request to the [List inventory levels API Route](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitemsinventoryitemlocationlevels):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -445,13 +445,13 @@ curl -L -X GET '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels' \
</TabItem>
</Tabs>
This endpoint requires the ID of the inventory item as a path parameter. You can also pass [expand](https://docs.medusajs.com/api/admin#expanding-fields) and [fields](https://docs.medusajs.com/api/admin#selecting-fields) query parameters.
This API Route requires the ID of the inventory item as a path parameter. You can also pass [expand](https://docs.medusajs.com/api/admin#expanding-fields) and [fields](https://docs.medusajs.com/api/admin#selecting-fields) query parameters.
The request returns the inventory item as an object. In that object, the list of inventory levels are available under the property `location_levels`.
### Create Inventory Level
You can create a location level by sending a request to the [Create Inventory Level endpoint](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitemlocationlevels):
You can create a location level by sending a request to the [Create Inventory Level API Route](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitemlocationlevels):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -533,7 +533,7 @@ curl -L -X POST '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels'
</TabItem>
</Tabs>
This endpoint requires the inventory item ID as a path parameter. In the request body, it requires the following parameters:
This API Route requires the inventory item ID as a path parameter. In the request body, it requires the following parameters:
- `location_id`: The ID of the location associated with this location level. This ID is typically available through using the stock location module.
- `stocked_quantity`: A number indicating the item’s quantity in stock.
@@ -544,7 +544,7 @@ This request returns the inventory item associated with the created location lev
### Update Location Level
You can update a location level by sending a request to the [Update Location Level endpoint](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitemlocationlevelslocationlevel):
You can update a location level by sending a request to the [Update Location Level API Route](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitemlocationlevelslocationlevel):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -624,7 +624,7 @@ curl -L -X POST '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels/<
</TabItem>
</Tabs>
This endpoint requires two path parameters: the first one being the ID of the inventory item, and the second one being the ID of the location.
This API Route requires two path parameters: the first one being the ID of the inventory item, and the second one being the ID of the location.
In the body, you can optionally pass any of the location level’s attributes to update. In the example above, you update the `stocked_quantity` attribute of the location level.
@@ -632,7 +632,7 @@ The request returns the inventory item associated with the location level as an
### Delete Location Level
You can delete a location level of an inventory item by sending a request to the [Delete Location Level endpoint](https://docs.medusajs.com/api/admin#inventory-items_deleteinventoryitemsinventoryitelocationlevelslocation):
You can delete a location level of an inventory item by sending a request to the [Delete Location Level API Route](https://docs.medusajs.com/api/admin#inventory-items_deleteinventoryitemsinventoryitelocationlevelslocation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -696,7 +696,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels
</TabItem>
</Tabs>
This endpoint requires two path parameters: the first one being the inventory item’s ID and the second one being the location level’s ID.
This API Route requires two path parameters: the first one being the inventory item’s ID and the second one being the location level’s ID.
The request returns the inventory item as an object.
@@ -704,7 +704,7 @@ The request returns the inventory item as an object.
## Delete Inventory Item
You can delete an inventory item by sending a request to the [Delete Inventory Item endpoint](https://docs.medusajs.com/api/admin#inventory-items_deleteinventoryitemsinventoryitem):
You can delete an inventory item by sending a request to the [Delete Inventory Item API Route](https://docs.medusajs.com/api/admin#inventory-items_deleteinventoryitemsinventoryitem):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -765,7 +765,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>' \
</TabItem>
</Tabs>
This endpoint requires the inventory item’s ID be passed as a path parameter.
This API Route requires the inventory item’s ID be passed as a path parameter.
It returns the following fields in the response:
www/apps/docs/content/modules/multiwarehouse/admin/manage-item-allocations-in-orders.mdx
+14 -14
View File
@@ -70,13 +70,13 @@ You can learn more about [authenticating as an admin user in the API reference](
Using the reservations admin REST APIs, you can create an item allocation or reservation for any resource, and not just items in an order. This gives you more options in how you handle item allocations.
In this guide, however, the focus will be on how to use these endpoints for order-related functionalities.
In this guide, however, the focus will be on how to use these API Routes for order-related functionalities.
### Create Item Allocation
Item allocations are created automatically for items that are associated with product variants having the `manage_inventory` attribute enabled. You typically don’t need to create an item allocation, unless you delete the previous item allocation.
You can create an item allocation by sending a request to the [Create a Reservation endpoint](https://docs.medusajs.com/api/admin#reservations_postreservations):
You can create an item allocation by sending a request to the [Create a Reservation API Route](https://docs.medusajs.com/api/admin#reservations_postreservations):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -159,7 +159,7 @@ curl -L -X POST '<BACKEND_URL>/admin/reservations' \
</TabItem>
</Tabs>
This endpoint requires the following body parameters:
This API Route requires the following body parameters:
- `line_item_id`: The ID of the order’s line item the allocation is being created for.
- `location_id`: The ID of the location the item is being allocated from.
@@ -172,7 +172,7 @@ The request returns the created reservation as an object.
When listing item allocations, by default, you’ll be retrieving all item allocations in your commerce system. You can, however, provide optional fields to filter the item allocations retrieved.
You can retrieve the item allocations of a line item in an order using the [List Reservations endpoint](https://docs.medusajs.com/api/admin#reservations_getreservations):
You can retrieve the item allocations of a line item in an order using the [List Reservations API Route](https://docs.medusajs.com/api/admin#reservations_getreservations):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -243,13 +243,13 @@ curl -L -X GET '<BACKEND_URL>/admin/reservations?line_item_id=<LINE_ITEM_ID>' \
</TabItem>
</Tabs>
This endpoint does not require any path or query parameters. As mentioned earlier, you can pass query parameters to filter the reservations. In the code snippets above, you filter the reservations by a line item ID. You can, however, filter by other attributes, such as the ID of the location. You can refer to the [API reference](https://docs.medusajs.com/api/admin#reservations_getreservations) for a full list of query parameters.
This API Route doesn't require any path or query parameters. As mentioned earlier, you can pass query parameters to filter the reservations. In the code snippets above, you filter the reservations by a line item ID. You can, however, filter by other attributes, such as the ID of the location. You can refer to the [API reference](https://docs.medusajs.com/api/admin#reservations_getreservations) for a full list of query parameters.
The request returns the reservations along with [pagination fields](https://docs.medusajs.com/api/admin#pagination).
### Retrieve Item Allocation
You can retrieve a single item allocation by its ID using the [Get a Reservation endpoint](https://docs.medusajs.com/api/admin#reservations_getreservationsreservation):
You can retrieve a single item allocation by its ID using the [Get a Reservation API Route](https://docs.medusajs.com/api/admin#reservations_getreservationsreservation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -309,13 +309,13 @@ curl -L -X GET '<BACKEND_URL>/admin/reservations/<RESERVATION_ID>' \
</TabItem>
</Tabs>
This endpoint requires the reservation’s ID as a path parameter.
This API Route requires the reservation’s ID as a path parameter.
The request returns the reservation as an object.
### Update Item Allocation
You can update an item allocation to change the location to allocate from or the quantity to allocate by sending a request to the [Update Reservation endpoint](https://docs.medusajs.com/api/admin#reservations_postreservationsreservation):
You can update an item allocation to change the location to allocate from or the quantity to allocate by sending a request to the [Update Reservation API Route](https://docs.medusajs.com/api/admin#reservations_postreservationsreservation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -388,7 +388,7 @@ curl -L -X POST '<BACKEND_URL>/admin/reservations/<RESERVATION_ID>' \
</TabItem>
</Tabs>
This endpoint requires the ID of the reservation as a path parameter.
This API Route requires the ID of the reservation as a path parameter.
In the request body parameters, you can optionally pass any of the following parameters to make updates to the reservation:
@@ -402,7 +402,7 @@ The request returns the updated reservation as an object.
Deleting an item allocation means that the quantity that was previously reserved is no longer reserved.
You can delete an item allocation by sending a request to the [Delete Reservation endpoint](https://docs.medusajs.com/api/admin#reservations_deletereservationsreservation):
You can delete an item allocation by sending a request to the [Delete Reservation API Route](https://docs.medusajs.com/api/admin#reservations_deletereservationsreservation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -461,12 +461,12 @@ curl -L -X DELETE '<BACKEND_URL>/admin/reservations/<RESERVATION_ID>' \
</TabItem>
</Tabs>
This endpoint requires the reservation ID to be passed as a path parameter.
This API Route requires the reservation ID to be passed as a path parameter.
The request returns the following fields:
- `id`: The ID of the reservation.
- `object`: The type of object that was removed. In this case, the value will be `reservation`.
- `object`: The type of object that was removed. In this case, the value will be `reservation`.
- `deleted`: A boolean value indicating whether the reservation was successfully deleted.
---
@@ -573,7 +573,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/fulfillment' \
The `location_id` is an optional parameter that allows you to specify where to fulfill the item from. This subsequently decrements the stock quantity of the product variant in that location.
You can learn more about this endpoint’s parameters and response in the [API reference](https://docs.medusajs.com/api/admin#orders_postordersorderfulfillments).
You can learn more about this API Route's parameters and response in the [API reference](https://docs.medusajs.com/api/admin#orders_postordersorderfulfillments).
---
@@ -679,7 +679,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/return' \
The `location_id` is an optional parameter that allows you to specify where to return the item to. This subsequently increments the stock quantity of the product variant in that location.
You can learn more about this endpoint’s parameters and response in [the API reference](https://docs.medusajs.com/api/admin#orders_postordersorderreturns).
You can learn more about this API Route's parameters and response in [the API reference](https://docs.medusajs.com/api/admin#orders_postordersorderreturns).
---
www/apps/docs/content/modules/multiwarehouse/admin/manage-reservations.mdx
+10 -10
View File
@@ -31,7 +31,7 @@ You want to add or use the following admin functionalities:
:::note
You can check the [API reference](https://docs.medusajs.com/api/admin) for all available Reservations endpoints.
You can check the [API reference](https://docs.medusajs.com/api/admin) for all available Reservations API Routes.
:::
@@ -69,7 +69,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Reservations
You can list all reservations in your store by sending a request to the [List Reservations endpoint](https://docs.medusajs.com/api/admin#reservations_getreservations):
You can list all reservations in your store by sending a request to the [List Reservations API Route](https://docs.medusajs.com/api/admin#reservations_getreservations):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -134,9 +134,9 @@ curl -L -X GET '<BACKEND_URL>/admin/reservations' \
</TabItem>
</Tabs>
This endpoint does not require any query or path parameters. You can pass it query parameters for filtering or pagination purposes. Check out the [API reference](https://docs.medusajs.com/api/admin#reservations_getreservations) for a list of accepted query parameters.
This API Route doesn't require any query or path parameters. You can pass it query parameters for filtering or pagination purposes. Check out the [API reference](https://docs.medusajs.com/api/admin#reservations_getreservations) for a list of accepted query parameters.
This endpoint returns an array of reservations along with [pagination parameters](https://docs.medusajs.com/api/admin#pagination).
This API Route returns an array of reservations along with [pagination parameters](https://docs.medusajs.com/api/admin#pagination).
---
@@ -148,7 +148,7 @@ Before you create a reservation for a product variant, make sure you’ve create
:::
You can create a reservation by sending a request to the [Create Reservation endpoint](https://docs.medusajs.com/api/admin#reservations_postreservations):
You can create a reservation by sending a request to the [Create Reservation API Route](https://docs.medusajs.com/api/admin#reservations_postreservations):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -227,7 +227,7 @@ curl -L -X POST '<BACKEND_URL>/admin/reservations' \
</TabItem>
</Tabs>
This endpoint requires the following body parameters:
This API Route requires the following body parameters:
- `location_id`: The ID of the location the reservation is created in.
- `inventory_item_id`: The ID of the inventory item the product variant is associated with.
@@ -239,7 +239,7 @@ The request returns the created reservation as an object.
## Update a Reservation
You can update a reservation by sending a request to the [Update Reservation endpoint](https://docs.medusajs.com/api/admin#reservations_postreservationsreservation):
You can update a reservation by sending a request to the [Update Reservation API Route](https://docs.medusajs.com/api/admin#reservations_postreservationsreservation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -312,7 +312,7 @@ curl -L -X POST '<BACKEND_URL>/admin/reservations/<RESERVATION_ID>' \
</TabItem>
</Tabs>
This endpoint requires the ID of the reservation as a path parameter.
This API Route requires the ID of the reservation as a path parameter.
In the request body parameters, you can optionally pass any of the following parameters to make updates to the reservation:
@@ -326,7 +326,7 @@ The request returns the updated reservation as an object.
## Delete a Reservation
You can delete a reservation by sending a request to the [Delete Reservation endpoint](https://docs.medusajs.com/api/admin#reservations_deletereservationsreservation):
You can delete a reservation by sending a request to the [Delete Reservation API Route](https://docs.medusajs.com/api/admin#reservations_deletereservationsreservation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -385,7 +385,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/reservations/<RESERVATION_ID>' \
</TabItem>
</Tabs>
This endpoint requires the reservation ID to be passed as a path parameter.
This API Route requires the reservation ID to be passed as a path parameter.
The request returns the following fields:
www/apps/docs/content/modules/multiwarehouse/admin/manage-stock-locations.mdx
+14 -14
View File
@@ -59,7 +59,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Stock Locations
You can list stock locations by using the [List Stock Locations endpoint](https://docs.medusajs.com/api/admin#stock-locations_getstocklocations):
You can list stock locations by using the [List Stock Locations API Route](https://docs.medusajs.com/api/admin#stock-locations_getstocklocations):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -128,7 +128,7 @@ curl -L -X GET '<BACKEND_URL>/admin/stock-locations' \
</TabItem>
</Tabs>
This endpoint does not require any path or query parameters. You can, however, pass it query parameters to search or filter the list of stock locations. For example, you can pass the `q` query parameter to search through the locations by name. You can learn about available query parameters in the [API reference](https://docs.medusajs.com/api/admin#stock-locations_getstocklocations).
This API Route doesn't require any path or query parameters. You can, however, pass it query parameters to search or filter the list of stock locations. For example, you can pass the `q` query parameter to search through the locations by name. You can learn about available query parameters in the [API reference](https://docs.medusajs.com/api/admin#stock-locations_getstocklocations).
The request returns an array of stock location objects along with [pagination parameters](https://docs.medusajs.com/api/admin#pagination).
@@ -136,7 +136,7 @@ The request returns an array of stock location objects along with [pagination pa
## Create a Stock Location
You can create a stock location using the [Create a Stock Location endpoint](https://docs.medusajs.com/api/admin#stock-locations_poststocklocations):
You can create a stock location using the [Create a Stock Location API Route](https://docs.medusajs.com/api/admin#stock-locations_poststocklocations):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -207,7 +207,7 @@ curl -L -X POST '<BACKEND_URL>/admin/stock-locations' \
</TabItem>
</Tabs>
This endpoint requires in its body parameters the `name` field, which is the name of the stock location. You can also pass in the request body parameters other fields related to the address or metadata. You can learn more in the [API reference](https://docs.medusajs.com/api/admin#stock-locations_poststocklocations).
This API Route requires in its body parameters the `name` field, which is the name of the stock location. You can also pass in the request body parameters other fields related to the address or metadata. You can learn more in the [API reference](https://docs.medusajs.com/api/admin#stock-locations_poststocklocations).
This request returns the created stock location as an object.
@@ -215,7 +215,7 @@ This request returns the created stock location as an object.
## Retrieve a Stock Location
You can retrieve a stock location by sending a request to the [Get Stock Location endpoint](https://docs.medusajs.com/api/admin#stock-locations_getstocklocationsstocklocation):
You can retrieve a stock location by sending a request to the [Get Stock Location API Route](https://docs.medusajs.com/api/admin#stock-locations_getstocklocationsstocklocation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -277,7 +277,7 @@ curl -L -X GET '<BACKEND_URL>/admin/stock-locations/<LOC_ID>' \
</TabItem>
</Tabs>
This endpoint requires the stock location ID to be passed as a path parameter. It also accepts query parameters related to expanding and selecting fields. You can learn more in the [API reference](https://docs.medusajs.com/api/admin#stock-locations_getstocklocationsstocklocation).
This API Route requires the stock location ID to be passed as a path parameter. It also accepts query parameters related to expanding and selecting fields. You can learn more in the [API reference](https://docs.medusajs.com/api/admin#stock-locations_getstocklocationsstocklocation).
It returns the stock location as an object.
@@ -285,7 +285,7 @@ It returns the stock location as an object.
## Associate a Stock Location with a Sales Channel
You can associate a stock location with a sales channel by sending a request to the [Associate Stock Channel endpoint](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannelssaleschannelstocklocation):
You can associate a stock location with a sales channel by sending a request to the [Associate Stock Channel API Route](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannelssaleschannelstocklocation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -357,7 +357,7 @@ curl -L -X POST '<BACKEND_URL>/admin/sales-channels/<CHANNEL_ID>/stock-locations
</TabItem>
</Tabs>
This endpoint requires the ID of the sales channel as a path parameter. In its body parameters, it requires the ID of the stock location you’re associating the sales channel with.
This API Route requires the ID of the sales channel as a path parameter. In its body parameters, it requires the ID of the stock location you’re associating the sales channel with.
This request returns the sales channel object.
@@ -371,7 +371,7 @@ You can associate a location with more than one sales channel, and you can assoc
## Remove Association Between Stock Location and Sales Channel
You can remove the association between a stock location and a sales channel by sending a request to the [Remove Stock Location Association endpoint](https://docs.medusajs.com/api/admin#sales-channels_deletesaleschannelssaleschannelstocklocation):
You can remove the association between a stock location and a sales channel by sending a request to the [Remove Stock Location Association API Route](https://docs.medusajs.com/api/admin#sales-channels_deletesaleschannelssaleschannelstocklocation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -446,7 +446,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/sales-channels/<CHANNEL_ID>/stock-locatio
</TabItem>
</Tabs>
This endpoint requires the ID of the sales channel as a path parameter. In its body parameters, it requires the ID of the stock location you’re removing the association of the sales channel with.
This API Route requires the ID of the sales channel as a path parameter. In its body parameters, it requires the ID of the stock location you’re removing the association of the sales channel with.
The request returns the following fields:
@@ -464,7 +464,7 @@ This request does not delete the stock location. It only removes the association
## Update a Stock Location
You can update a stock location by sending a request to the [Update Stock Location endpoint](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsstocklocation):
You can update a stock location by sending a request to the [Update Stock Location API Route](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsstocklocation):
<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/stock-locations/<LOC_ID>' \
</TabItem>
</Tabs>
This endpoint requires the ID of a stock location as a path parameter. In its body parameters, you can pass any of the location’s attributes to update, such as the name or address. You can learn more in the [API reference](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsstocklocation).
This API Route requires the ID of a stock location as a path parameter. In its body parameters, you can pass any of the location’s attributes to update, such as the name or address. You can learn more in the [API reference](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsstocklocation).
This request returns the updated stock location as an object.
@@ -545,7 +545,7 @@ This request returns the updated stock location as an object.
## Delete a Stock Location
You can delete a stock location by sending a request to the [Delete Stock Location endpoint](https://docs.medusajs.com/api/admin#stock-locations_deletestocklocationsstocklocation):
You can delete a stock location by sending a request to the [Delete Stock Location API Route](https://docs.medusajs.com/api/admin#stock-locations_deletestocklocationsstocklocation):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -604,7 +604,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/stock-locations/<LOC_ID>' \
</TabItem>
</Tabs>
This endpoint requires the ID of the stock location as a path parameter.
This API Route requires the ID of the stock location as a path parameter.
It returns the following fields in the response:
www/apps/docs/content/modules/multiwarehouse/backend/create-inventory-service.md
+1 -1
View File
@@ -19,7 +19,7 @@ This guide will only explain what is required to create in your custom inventory
:::note
It should be noted that the Medusa backend expects the inventory module to have entities for an inventory item, an inventory level, and a reservation item, as it uses the IDs of those entities when orchestrating between different modules and the in the endpoints it exposes. You can learn more about this in the [Inventory Module Architecture documentation](../inventory-module.md).
It should be noted that the Medusa backend expects the inventory module to have entities for an inventory item, an inventory level, and a reservation item, as it uses the IDs of those entities when orchestrating between different modules and the in the API Routes it exposes. You can learn more about this in the [Inventory Module Architecture documentation](../inventory-module.md).
:::
www/apps/docs/content/modules/multiwarehouse/backend/create-stock-location-service.md
+1 -1
View File
@@ -19,7 +19,7 @@ This guide will only explain what is required to create in your custom stock loc
:::note
It should be noted that the Medusa backend expects the stock location module to have entities for a location and a location address, as it uses the IDs of those entities when orchestrating between different modules and the in the endpoints it exposes. You can learn more about this in the [Stock Location Module Architecture documentation](../stock-location-module.md).
It should be noted that the Medusa backend expects the stock location module to have entities for a location and a location address, as it uses the IDs of those entities when orchestrating between different modules and the in the API Routes it exposes. You can learn more about this in the [Stock Location Module Architecture documentation](../stock-location-module.md).
:::
www/apps/docs/content/modules/orders/admin/edit-order.mdx
+11 -11
View File
@@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem';
# How to Edit an Order
In this document, you’ll learn how to create an order edit using the Admin API endpoints.
In this document, you’ll learn how to create an order edit using the Admin API Routes.
## Overview
@@ -80,7 +80,7 @@ You must have an existing order that you want to edit.
Before you can start making changes to an order, you have to create a new order edit.
To do that, send a request to the [Create an OrderEdit](https://docs.medusajs.com/api/admin#order-edits_postorderedits) endpoint:
To do that, send a request to the [Create an OrderEdit API Route](https://docs.medusajs.com/api/admin#order-edits_postorderedits):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -150,7 +150,7 @@ curl -L -X POST '<BACKEND_URL>/admin/order-edits' \
</TabItem>
</Tabs>
This endpoint has one required request body parameter `order_id` which is the ID of the order this edit is being created for.
This API Route has one required request body parameter `order_id` which is the ID of the order this edit is being created for.
This request returns the Order Edit under the `order_edit` property.
@@ -174,7 +174,7 @@ You can only make changes to items that have not been fulfilled yet in the order
### Add an Item
To add a new item to the original order, send a request to the [Add Line Item](https://docs.medusajs.com/api/admin#order-edits_postordereditseditlineitems) endpoint:
To add a new item to the original order, send a request to the [Add Line Item API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditseditlineitems):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -259,7 +259,7 @@ This request returns the Order Edit object. You can access returned item changes
You can edit an item’s quantity in the original order.
To update an item, send a request to the [Update Line Item](https://docs.medusajs.com/api/admin#order-edits_postordereditseditlineitemslineitem) endpoint:
To update an item, send a request to the [Update Line Item API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditseditlineitemslineitem):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -342,7 +342,7 @@ This request returns the Order Edit object. You can access returned item changes
### Remove an Item
You can remove an item from the original order by sending a request to the [Remove Line Item](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsordereditlineitemslineitem) endpoint:
You can remove an item from the original order by sending a request to the [Remove Line Item API Route](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsordereditlineitemslineitem):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -413,7 +413,7 @@ This request returns the Order Edit object. You can access returned item changes
A merchant might make a mistake while making a change to the original order’s items. Using the Admin API, you can revert item changes previously created.
To revert an item change, send a request to the [Delete Item Change](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsorderedititemchange) endpoint:
To revert an item change, send a request to the [Delete Item Change API Route](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsorderedititemchange):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -491,7 +491,7 @@ This request returns an object with the following properties:
After an Order Edit is created and all the item changes are added, it must be moved into the request state.
To move an Order Edit into the request state, send a request to the [Request Confirmation](https://docs.medusajs.com/api/admin#order-edits_postordereditsordereditrequest) endpoint:
To move an Order Edit into the request state, send a request to the [Request Confirmation API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsordereditrequest):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -587,7 +587,7 @@ When the merchant force-confirms the order edit, however, it bypasses the paymen
This section covers how the Admin API can be used to force-confirm the Order Edit. You can refer to [this documentation to learn how to implement Order Edit confirmation on the storefront](../storefront/handle-order-edits.mdx).
To confirm an Order Edit, send a request to the [Confirm Order Edit](https://docs.medusajs.com/api/admin#order-edits_postordereditsordereditconfirm) endpoint:
To confirm an Order Edit, send a request to the [Confirm Order Edit API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsordereditconfirm):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -670,7 +670,7 @@ You can learn how to allow customers to authorize payment on the storefront in [
### Capture Payment
If the payment is authorized by the customer, it can be captured by sending a request to the [Capture Payment](https://docs.medusajs.com/api/admin#payments_postpaymentspaymentcapture) endpoint:
If the payment is authorized by the customer, it can be captured by sending a request to the [Capture Payment API Route](https://docs.medusajs.com/api/admin#payments_postpaymentspaymentcapture):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -736,7 +736,7 @@ It returns in the response the full Payment object.
When the total after the order edit is less than the original order total, the merchant can refund the difference to the customer.
To refund the difference to the customer, send a request to the [Refund Payment](https://docs.medusajs.com/api/admin#payments_postpaymentspaymentrefunds) endpoint:
To refund the difference to the customer, send a request to the [Refund Payment API Route](https://docs.medusajs.com/api/admin#payments_postpaymentspaymentrefunds):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/orders/admin/manage-claims.mdx
+13 -13
View File
@@ -58,7 +58,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## View Order’s Claims
To view an order’s claims, you can retrieve the order using the [Get Order endpoint](https://docs.medusajs.com/api/admin#orders_getordersorder) and access the order’s claims:
To view an order’s claims, you can retrieve the order using the [Get Order API Route](https://docs.medusajs.com/api/admin#orders_getordersorder) and access the order’s claims:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -137,7 +137,7 @@ The request returns the order as an object. In that object, you can access an ar
## Create Claim
You can create a claim by sending a request to the [Create Claim endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderclaims):
You can create a claim by sending a request to the [Create Claim API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaims):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -232,7 +232,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims' \
</TabItem>
</Tabs>
This endpoint requires the order ID to be passed as a path parameter.
This API Route requires the order ID to be passed as a path parameter.
In the request body, the following parameters are required:
@@ -255,7 +255,7 @@ The request returns the updated order as an object. You can access the order’s
## Update a Claim
You can update a claim by sending a request to the [Update Claim endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaim):
You can update a claim by sending a request to the [Update Claim API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaim):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -330,7 +330,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>' \
</TabItem>
</Tabs>
This endpoint requires the ID of the order and the claim to be passed as path parameters.
This API Route requires the ID of the order and the claim to be passed as path parameters.
In the request body, you can pass any of the claim’s fields that you want to update as parameters. In the example above, the `no_notification` field is updated.
@@ -346,7 +346,7 @@ Fulfillments are available on a claim object under the `fulfillments` property,
### Create Fulfillment
You can create a fulfillment for a claim by sending a request to the [Create Claim Fulfillment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimfulfillments):
You can create a fulfillment for a claim by sending a request to the [Create Claim Fulfillment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimfulfillments):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -408,7 +408,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/fulfill
</TabItem>
</Tabs>
This endpoint requires the order and claim IDs as path parameters.
This API Route requires the order and claim IDs as path parameters.
In the request body, you can pass optional parameters such as `metadata` or `no_notification`. These parameters will be used to create the fulfillment. You can learn more about available request body parameters in the [API reference](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimfulfillments).
@@ -416,7 +416,7 @@ The request returns the updated order as an object. You can access the order’s
### Create a Shipment
You can create a shipment for a claim by sending a request to the [Create Claim Shipment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimshipments):
You can create a shipment for a claim by sending a request to the [Create Claim Shipment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimshipments):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -490,7 +490,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/shipmen
</TabItem>
</Tabs>
This endpoint requires the order and claim IDs as path parameters.
This API Route requires the order and claim IDs as path parameters.
In the request body, it’s required to pass the `fulfillment_id` parameter, which is the ID of the fulfillment the shipment is being created for. You can pass other optional parameters, such as an array of tracking numbers. You can learn more in the [API reference](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimshipments).
@@ -508,7 +508,7 @@ You can’t cancel a fulfillment that has a shipment
:::
You can cancel a fulfillment by sending a request to the [Cancel Fulfillment endpoint](https://docs.medusajs.com/api/admin#orders_postordersclaimfulfillmentscancel):
You can cancel a fulfillment by sending a request to the [Cancel Fulfillment API Route](https://docs.medusajs.com/api/admin#orders_postordersclaimfulfillmentscancel):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -576,7 +576,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/fulfill
</TabItem>
</Tabs>
This endpoint requires the order, claim, and fulfillment IDs to be passed as path parameters.
This API Route requires the order, claim, and fulfillment IDs to be passed as path parameters.
The request returns the updated order as an object. You can access the claims using the `claims` property of the order object, which is an array of claim objects.
@@ -592,7 +592,7 @@ You can’t cancel a claim that has been refunded. You must also cancel the clai
:::
You can cancel a claim by sending a request to the [Cancel Claim endpoint](https://docs.medusajs.com/api/admin#orders_postordersclaimcancel):
You can cancel a claim by sending a request to the [Cancel Claim API Route](https://docs.medusajs.com/api/admin#orders_postordersclaimcancel):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -651,7 +651,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/cancel'
</TabItem>
</Tabs>
This endpoint requires the order and claim IDs as path parameters.
This API Route requires the order and claim IDs as path parameters.
The request returns the updated order as an object. You can access the claims using the `claims` property of the order object, which is an array of claim objects.
www/apps/docs/content/modules/orders/admin/manage-draft-orders.mdx
+18 -18
View File
@@ -52,7 +52,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Draft Orders
You can list draft orders by sending a request to the [List Draft Orders endpoint](https://docs.medusajs.com/api/admin#draft-orders_getdraftorders):
You can list draft orders by sending a request to the [List Draft Orders API Route](https://docs.medusajs.com/api/admin#draft-orders_getdraftorders):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -117,7 +117,7 @@ curl -L -X GET '<BACKEND_URL>/admin/draft-orders' \
</TabItem>
</Tabs>
This endpoint does not require any path or query parameters. You can pass search or pagination query parameters as explained in the [API reference](https://docs.medusajs.com/api/admin#draft-orders_getdraftorders).
This API Route doesn't require any path or query parameters. You can pass search or pagination query parameters as explained in the [API reference](https://docs.medusajs.com/api/admin#draft-orders_getdraftorders).
The request returns an array of draft order objects along with [pagination parameters](https://docs.medusajs.com/api/admin#pagination).
@@ -125,7 +125,7 @@ The request returns an array of draft order objects along with [pagination param
## Create a Draft Order
You can create a draft order by sending a request to the [Create Draft Order endpoint](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders):
You can create a draft order by sending a request to the [Create Draft Order API Route](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -277,7 +277,7 @@ curl -L -X POST '<BACKEND_URL>/admin/draft-orders' \
</TabItem>
</Tabs>
This endpoint requires the following request body parameters:
This API Route requires the following request body parameters:
- `email`: a string indicating the email of the customer to associate this draft order with.
- `region_id`: a string indicating the ID of the region this draft order belongs to.
@@ -298,7 +298,7 @@ The request returns the created draft order as an object.
## Retrieve Draft Order
You can retrieve a draft order by sending a request to the [Get Draft Order endpoint](https://docs.medusajs.com/api/admin#draft-orders_getdraftordersdraftorder):
You can retrieve a draft order by sending a request to the [Get Draft Order API Route](https://docs.medusajs.com/api/admin#draft-orders_getdraftordersdraftorder):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -358,7 +358,7 @@ curl -L -X GET '<BACKEND_URL>/admin/draft-orders/<DRAFT_ORDER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the draft order’s ID as a path parameter.
This API Route requires the draft order’s ID as a path parameter.
The request returns the draft order as an object.
@@ -366,7 +366,7 @@ The request returns the draft order as an object.
## Update Draft Order
You can update a draft order by sending a request to the [Update Draft Order endpoint](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorder):
You can update a draft order by sending a request to the [Update Draft Order API Route](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorder):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -439,7 +439,7 @@ curl -L -X POST '<BACKEND_URL>/admin/draft-orders/<DRAFT_ORDER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the draft order’s ID as a path parameter.
This API Route requires the draft order’s ID as a path parameter.
In the request body, you can pass any of the draft order’s fields to update. In the example above, you update the `email` field. Check out the [API reference](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorder) to learn about other accepted request body parameters.
@@ -451,7 +451,7 @@ The request returns the updated draft order as an object.
### Add Line Items
You can add line items to a draft order by sending a request to the [Create Line Items endpoint](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorderlineitems):
You can add line items to a draft order by sending a request to the [Create Line Items API Route](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorderlineitems):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -526,7 +526,7 @@ curl -L -X POST '<BACKEND_URL>/admin/draft-orders/<DRAFT_ORDER_ID>/line-items' \
</TabItem>
</Tabs>
This endpoint requires the ID of the draft order as a path parameter.
This API Route requires the ID of the draft order as a path parameter.
In the request body, it’s required to pass the `quantity` parameter, which is a number indicating the quantity of the item in the draft order. You can also pass other optional parameters based on the type of line item you’re adding.
@@ -541,7 +541,7 @@ The request returns the updated draft order as an object. You can access the dra
### Update Line Item
You can update a line item by sending a request to the [Update Line Item endpoint](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorderlineitemsitem):
You can update a line item by sending a request to the [Update Line Item API Route](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorderlineitemsitem):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -617,7 +617,7 @@ curl -L -X POST '<BACKEND_URL>/admin/draft-orders/<DRAFT_ORDER_ID>/line-items/<I
</TabItem>
</Tabs>
This endpoint requires the draft order and line item’s IDs as path parameters.
This API Route requires the draft order and line item’s IDs as path parameters.
In the request body, you can pass any of the line item’s fields as parameters to update them. In the example above, you pass the `quantity` parameter to update the quantity of the item. Check out the [API reference](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorderlineitemsitem) for a full list of request body parameters.
@@ -625,7 +625,7 @@ The request returns the updated draft order as an object. You can access the dra
### Delete Line Item
You can delete a line item by sending a request to the [Delete Line Item endpoint](https://docs.medusajs.com/api/admin#draft-orders_deletedraftordersdraftorderlineitemsitem):
You can delete a line item by sending a request to the [Delete Line Item API Route](https://docs.medusajs.com/api/admin#draft-orders_deletedraftordersdraftorderlineitemsitem):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -686,7 +686,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/draft-orders/<DRAFT_ORDER_ID>/line-items/
</TabItem>
</Tabs>
This endpoint requires the draft order and line item’s IDs as path parameters.
This API Route requires the draft order and line item’s IDs as path parameters.
The request returns the updated draft order as an object. You can access the draft order’s items by accessing the `carts` property in the draft item, then the `items` property. The `items` property is an array of line item objects.
@@ -696,7 +696,7 @@ The request returns the updated draft order as an object. You can access the dra
Registering the draft order’s payment leads to authorizing and capturing the payment using the `system` payment method. This would complete the draft order and create an order from it.
You can register the draft order payment by sending a request to the [Register Draft Order Payment endpoint](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorderregisterpayment):
You can register the draft order payment by sending a request to the [Register Draft Order Payment API Route](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorderregisterpayment):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -755,7 +755,7 @@ curl -L -X POST '<BACKEND_URL>/admin/draft-orders/<DRAFT_ORDER_ID>/pay' \
</TabItem>
</Tabs>
This endpoint requires the draft order’s ID as a path parameter.
This API Route requires the draft order’s ID as a path parameter.
The request returns the order created from the draft order as an object.
@@ -763,7 +763,7 @@ The request returns the order created from the draft order as an object.
## Delete a Draft Order
You can delete a draft order by sending a request to the [Delete Draft Order endpoint](https://docs.medusajs.com/api/admin#draft-orders_deletedraftordersdraftorder):
You can delete a draft order by sending a request to the [Delete Draft Order API Route](https://docs.medusajs.com/api/admin#draft-orders_deletedraftordersdraftorder):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -822,7 +822,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/draft-orders/<DRAFT_ORDER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the draft order’s ID as a path parameter.
This API Route requires the draft order’s ID as a path parameter.
The request returns the following fields:
www/apps/docs/content/modules/orders/admin/manage-orders.mdx
+23 -23
View File
@@ -60,7 +60,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Orders
You can list orders by sending a request to the [List Orders endpoint](https://docs.medusajs.com/api/admin#orders_getorders):
You can list orders by sending a request to the [List Orders API Route](https://docs.medusajs.com/api/admin#orders_getorders):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -123,13 +123,13 @@ curl -L -X GET '<BACKEND_URL>/admin/orders' \
</TabItem>
</Tabs>
This endpoint does not require any path parameters. You can pass it query parameters to filter the orders received.
This API Route doesn't require any path parameters. You can pass it query parameters to filter the orders received.
The request returns an array of orders along with [pagination fields](https://docs.medusajs.com/api/admin#pagination).
### Filter Orders
This endpoint accepts a variety of query parameters that allow you to filter orders. You can check available query parameters in the [API reference](https://docs.medusajs.com/api/admin#orders_getorders).
This API Route accepts a variety of query parameters that allow you to filter orders. You can check available query parameters in the [API reference](https://docs.medusajs.com/api/admin#orders_getorders).
For example, you can filter the orders by one or more status:
@@ -380,7 +380,7 @@ curl -L -X GET '<BACKEND_URL>/admin/orders?status[]=completed&sales_channel_id[]
## Retrieve an Order
You can retrieve an order by sending a request to the [Get an Order endpoint](https://docs.medusajs.com/api/admin#orders_getordersorder):
You can retrieve an order by sending a request to the [Get an Order API Route](https://docs.medusajs.com/api/admin#orders_getordersorder):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -440,7 +440,7 @@ curl -L -X GET '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the order ID to be passed as a path parameter.
This API Route requires the order ID to be passed as a path parameter.
The request returns the full order as an object.
@@ -461,7 +461,7 @@ Updating an order’s details can include updating its:
- Shipping Method
- `no_notification` property
You can update any of the above details of an order by sending a request to the [Update an Order endpoint](https://docs.medusajs.com/api/admin#orders_postordersorder):
You can update any of the above details of an order by sending a request to the [Update an Order API Route](https://docs.medusajs.com/api/admin#orders_postordersorder):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -534,7 +534,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the order’s ID to be passed as a path parameter.
This API Route requires the order’s ID to be passed as a path parameter.
In the request body parameters, you can pass any of the order’s fields mentioned earlier that you want to update. In the example above, you edit the email associated with the order. You can learn about other available request body parameters in the [API reference](https://docs.medusajs.com/api/admin#orders_postordersorder).
@@ -546,7 +546,7 @@ The request returns the updated order as an object.
### Capture an Order’s Payment
You can capture an order’s payment by sending a request to the [Capture Order’s Payment endpoint](https://docs.medusajs.com/api/admin#orders_postordersordercapture):
You can capture an order’s payment by sending a request to the [Capture Order’s Payment API Route](https://docs.medusajs.com/api/admin#orders_postordersordercapture):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -606,7 +606,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/capture' \
</TabItem>
</Tabs>
This endpoint requires the Order ID as a path parameter.
This API Route requires the Order ID as a path parameter.
The request returns the updated order as an object.
@@ -614,7 +614,7 @@ The request returns the updated order as an object.
You can refund an amount that is less than `order.refundable_amount`.
To refund payment, send a request to the [Refund Payment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderrefunds):
To refund payment, send a request to the [Refund Payment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderrefunds):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -691,7 +691,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/refund' \
</TabItem>
</Tabs>
This endpoint requires the order’s ID to be passed as a path parameter.
This API Route requires the order’s ID to be passed as a path parameter.
The following parameters are required in the request body parameters:
@@ -708,7 +708,7 @@ The request returns the updated order as an object.
### Create a Fulfillment
You can create a fulfillment by sending a request to the [Create a Fulfillment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderfulfillments):
You can create a fulfillment by sending a request to the [Create a Fulfillment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderfulfillments):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -801,7 +801,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/fulfillment' \
</TabItem>
</Tabs>
This endpoint requires the order’s ID to be passed as a path parameter.
This API Route requires the order’s ID to be passed as a path parameter.
In the request body, the `items` parameter is required. It’s an array of objects that are the items to fulfill. You can fulfill all items in the order or some items.
@@ -816,7 +816,7 @@ The request returns the updated order as an object.
### Create Shipment
You can create a shipment for a fulfillment by sending a request to the [Create Shipment endpoint](https://docs.medusajs.com/api/admin#orders_postordersordershipment):
You can create a shipment for a fulfillment by sending a request to the [Create Shipment API Route](https://docs.medusajs.com/api/admin#orders_postordersordershipment):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -889,7 +889,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/shipment' \
</TabItem>
</Tabs>
This endpoint requires passing the order’s ID as a path parameter.
This API Route requires passing the order’s ID as a path parameter.
In the request body, the `fulfillment_id` parameter is required. Its value is the ID of the fulfillment to create the shipment for. You can also pass other optional body parameters as explained in the [API reference](https://docs.medusajs.com/api/admin#orders_postordersordershipment).
@@ -897,7 +897,7 @@ The request returns the updated order as an object.
### Cancel Fulfillment
You can cancel a fulfillment by sending a request to the [Cancel Fulfillment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderfulfillmentscancel):
You can cancel a fulfillment by sending a request to the [Cancel Fulfillment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderfulfillmentscancel):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -958,7 +958,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/fulfillments/<FUL_ID>/can
</TabItem>
</Tabs>
This endpoint requires passing the order’s ID and fulfillment ID as path parameters.
This API Route requires passing the order’s ID and fulfillment ID as path parameters.
The request returns the updated order as an object.
@@ -966,7 +966,7 @@ The request returns the updated order as an object.
## Completing an Order
You can mark an order completed, changing its status, by sending a request to the [Complete an Order endpoint](https://docs.medusajs.com/api/admin#orders_postordersordercomplete):
You can mark an order completed, changing its status, by sending a request to the [Complete an Order API Route](https://docs.medusajs.com/api/admin#orders_postordersordercomplete):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -1025,7 +1025,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/complete' \
</TabItem>
</Tabs>
This endpoint requires the order ID to be passed as a path parameter.
This API Route requires the order ID to be passed as a path parameter.
The request returns the updated order as an object.
@@ -1033,7 +1033,7 @@ The request returns the updated order as an object.
## Cancel an Order
You can cancel an order by sending a request to the [Cancel Order endpoint](https://docs.medusajs.com/api/admin#orders_postordersordercancel):
You can cancel an order by sending a request to the [Cancel Order API Route](https://docs.medusajs.com/api/admin#orders_postordersordercancel):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -1092,7 +1092,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/cancel' \
</TabItem>
</Tabs>
This endpoint requires the order ID to be passed as a path parameter.
This API Route requires the order ID to be passed as a path parameter.
The request returns the updated order as an object.
@@ -1100,7 +1100,7 @@ The request returns the updated order as an object.
## Archive Order
You can archive an order by sending a request to the [Archive Order endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderarchive):
You can archive an order by sending a request to the [Archive Order API Route](https://docs.medusajs.com/api/admin#orders_postordersorderarchive):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -1159,7 +1159,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/archive' \
</TabItem>
</Tabs>
This endpoint requires the order ID to be passed as a path parameter.
This API Route requires the order ID to be passed as a path parameter.
The request returns the updated order as an object.
www/apps/docs/content/modules/orders/admin/manage-returns.mdx
+17 -17
View File
@@ -57,7 +57,7 @@ Return reasons allow you to specify why an item is returned. They are especially
### List Return Reasons
You can list available return reasons using the [List Return Reasons endpoint](https://docs.medusajs.com/api/admin#return-reasons_getreturnreasons):
You can list available return reasons using the [List Return Reasons API Route](https://docs.medusajs.com/api/admin#return-reasons_getreturnreasons):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -124,13 +124,13 @@ curl -L -X GET '<BACKEND_URL>/admin/return-reasons' \
</TabItem>
</Tabs>
This endpoint does not require or accept any path or query parameters.
This API Route doesn't require or accept any path or query parameters.
The request returns an array of return reason objects.
### Create a Return Reason
You can create a return reason using the [Create Return Reason endpoint](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasons):
You can create a return reason using the [Create Return Reason API Route](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasons):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -205,7 +205,7 @@ curl -L -X POST '<BACKEND_URL>/admin/return-reasons' \
</TabItem>
</Tabs>
This endpoint requires the following request body parameters:
This API Route requires the following request body parameters:
- `label`: a string that will be used as the label of the return reason. This is typically the label shown to the customer or the merchant.
- `value`: a string that is unique among return reasons. It is typically used internally for identification
@@ -216,7 +216,7 @@ This request returns the created return reason as an object.
### Update a Return Reason
You can update a return reason by sending a request to the [Update Return Reason endpoint](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasonsreason):
You can update a return reason by sending a request to the [Update Return Reason API Route](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasonsreason):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -289,7 +289,7 @@ curl -L -X POST '<BACKEND_URL>/admin/return-reasons/<REASON_ID>' \
</TabItem>
</Tabs>
This endpoint requires the return reason ID to be passed as a path parameter.
This API Route requires the return reason ID to be passed as a path parameter.
In the request body, you can pass any of the return reason’s fields that you want to update as parameters. In the example above, the label is passed in the request body to be updated.
@@ -297,7 +297,7 @@ The request returns the updated return reason as an object.
### Delete a Return Reason
You can delete a return reason by sending a request to the [Delete Return Reason endpoint](https://docs.medusajs.com/api/admin#return-reasons_deletereturnreason):
You can delete a return reason by sending a request to the [Delete Return Reason API Route](https://docs.medusajs.com/api/admin#return-reasons_deletereturnreason):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -356,7 +356,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/return-reasons/<REASON_ID>' \
</TabItem>
</Tabs>
This endpoint requires the return reason ID as a path parameter.
This API Route requires the return reason ID as a path parameter.
The request returns the following fields:
@@ -370,11 +370,11 @@ The request returns the following fields:
:::note
You can view all returns in your commerce system, regardless of which order they belong to, using the [List Returns endpoint](https://docs.medusajs.com/api/admin#return-reasons_getreturnreasons).
You can view all returns in your commerce system, regardless of which order they belong to, using the [List Returns API Route](https://docs.medusajs.com/api/admin#return-reasons_getreturnreasons).
:::
When you retrieve an order using the [Get Order endpoint](https://docs.medusajs.com/api/admin#orders_getordersorder), you can access the returns within the order object:
When you retrieve an order using the [Get Order API Route](https://docs.medusajs.com/api/admin#orders_getordersorder), you can access the returns within the order object:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -445,7 +445,7 @@ curl -L -X GET '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the order ID as a path parameter.
This API Route requires the order ID as a path parameter.
The request returns the order as an object. In that object, you can access an array of return objects using the property `returns` of the order object.
@@ -453,7 +453,7 @@ The request returns the order as an object. In that object, you can access an ar
## View a Swap’s Return
You can retrieve a swap either using the Get Order endpoint as explained [here](./manage-swaps.mdx#view-orders-swaps), or using the [List Swaps](https://docs.medusajs.com/api/admin#swaps_getswaps) or [Get Swap endpoint](https://docs.medusajs.com/api/admin#swaps_getswapsswap).
You can retrieve a swap either using the Get Order API Route as explained [here](./manage-swaps.mdx#view-orders-swaps), or using the [List Swaps](https://docs.medusajs.com/api/admin#swaps_getswaps) or [Get Swap](https://docs.medusajs.com/api/admin#swaps_getswapsswap) API Routes.
In a swap object, the swap’s return is available under the `return_order` property.
@@ -461,13 +461,13 @@ In a swap object, the swap’s return is available under the `return_order` prop
## View a Claim’s Return
You can retrieve a claim using the Get Order endpoint as explained [here](./manage-claims#view-orders-claims). In a claim object, the claim’s return is available under the `return_order` property.
You can retrieve a claim using the Get Order API Route as explained [here](./manage-claims#view-orders-claims). In a claim object, the claim’s return is available under the `return_order` property.
---
## Mark a Return as Received
You can mark a return as received by sending a request to the [Receive a Return endpoint](https://docs.medusajs.com/api/admin#returns_postreturnsreturnreceive):
You can mark a return as received by sending a request to the [Receive a Return API Route](https://docs.medusajs.com/api/admin#returns_postreturnsreturnreceive):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -555,7 +555,7 @@ curl -L -X POST '<BACKEND_URL>/admin/returns/<RETURN_ID>/receive' \
</TabItem>
</Tabs>
This endpoint requires the ID of the return as a path parameter.
This API Route requires the ID of the return as a path parameter.
In the request body, the `items` parameter is required. It’s an array of objects having the following properties:
@@ -576,7 +576,7 @@ A received return can’t be canceled.
:::
You can cancel a return by sending a request to the [Cancel Return endpoint](https://docs.medusajs.com/api/admin#returns_postreturnsreturncancel):
You can cancel a return by sending a request to the [Cancel Return API Route](https://docs.medusajs.com/api/admin#returns_postreturnsreturncancel):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -635,7 +635,7 @@ curl -L -X POST '<BACKEND_URL>/admin/returns/<RETURN_ID>/cancel' \
</TabItem>
</Tabs>
This endpoint requires the return ID to be passed as a path parameter.
This API Route requires the return ID to be passed as a path parameter.
The request returns one of the following object types:
www/apps/docs/content/modules/orders/admin/manage-swaps.mdx
+13 -13
View File
@@ -61,11 +61,11 @@ You can learn more about [authenticating as an admin user in the API reference](
:::note
If you want to view all swaps in your system, and not swaps specific to an order, you can use the [List Swaps endpoint](https://docs.medusajs.com/api/admin#swaps_getswaps) instead.
If you want to view all swaps in your system, and not swaps specific to an order, you can use the [List Swaps API Route](https://docs.medusajs.com/api/admin#swaps_getswaps) instead.
:::
You can view an order’s swaps by retrieving the order using the [Get Order endpoint](https://docs.medusajs.com/api/admin#orders_getordersorder):
You can view an order’s swaps by retrieving the order using the [Get Order API Route](https://docs.medusajs.com/api/admin#orders_getordersorder):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -135,7 +135,7 @@ curl -L -X GET '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the order ID to be passed as a path parameter.
This API Route requires the order ID to be passed as a path parameter.
The request returns the order as an object. The order’s swaps are available under the `swaps` property, which is an array of swap objects.
@@ -145,7 +145,7 @@ The request returns the order as an object. The order’s swaps are available un
Processing a swap’s payment can mean either refunding or capturing payment, depending on the value of `difference_due` of the swap. If the `difference_due` is less than 0, then the payment should be refunded. If it’s greater than 0, then the payment should be captured. If it’s 0, no payment processing is performed.
Regardless of whether you need to refund or capture the payment, you can process the swap’s payment by sending a request to the [Process Swap Payment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapprocesspayment):
Regardless of whether you need to refund or capture the payment, you can process the swap’s payment by sending a request to the [Process Swap Payment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapprocesspayment):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -206,7 +206,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/process-p
</TabItem>
</Tabs>
This endpoint requires the order ID and the swap ID as path parameters.
This API Route requires the order ID and the swap ID as path parameters.
The request returns the updated order as an object. You can access the swaps of the order in the `order.swaps` property. It’s an array of swap objects.
@@ -220,7 +220,7 @@ Fulfillments are available on a swap object under the `fulfillments` property, w
### Create a Fulfillment
You can create a fulfillment for a swap by sending a request to the [Create Swap Fulfillment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapfulfillments):
You can create a fulfillment for a swap by sending a request to the [Create Swap Fulfillment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapfulfillments):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -284,7 +284,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/fulfillme
</TabItem>
</Tabs>
This endpoint requires the order ID and swap ID as path parameters.
This API Route requires the order ID and swap ID as path parameters.
In the request body, you can pass optional parameters such as `metadata` or `no_notification`. These parameters will be used to create the fulfillment. You can learn more about available request body parameters in the [API reference](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapfulfillments).
@@ -292,7 +292,7 @@ The request returns the updated order as an object. You can access the order’s
### Create a Shipment
You can create a shipment for a swap’s fulfillment using the [Create Swap Shipment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapshipments):
You can create a shipment for a swap’s fulfillment using the [Create Swap Shipment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapshipments):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -368,7 +368,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/shipments
</TabItem>
</Tabs>
This endpoint expects the order and swap IDs to be passed as path parameters.
This API Route expects the order and swap IDs to be passed as path parameters.
In the request body, it’s required to pass the `fulfillment_id` parameter, which is the ID of the fulfillment the shipment is being created for. You can pass other optional parameters, such as an array of tracking numbers. You can learn more in the [API reference](https://docs.medusajs.com/api/admin#tag/Orders/operation/PostOrdersOrderSwapsSwapShipments).
@@ -386,7 +386,7 @@ You can’t cancel a fulfillment that has a shipment
:::
You can cancel a fulfillment by sending a request to the [Cancel Swap Fulfillment endpoint](https://docs.medusajs.com/api/admin#orders_postordersswapfulfillmentscancel):
You can cancel a fulfillment by sending a request to the [Cancel Swap Fulfillment API Route](https://docs.medusajs.com/api/admin#orders_postordersswapfulfillmentscancel):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -454,7 +454,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/fulfillme
</TabItem>
</Tabs>
This endpoint requires the order, swap, and fulfillment IDs to be passed as path parameters.
This API Route requires the order, swap, and fulfillment IDs to be passed as path parameters.
The request returns the updated order as an object. You can access the swaps using the `swaps` property of the order object, which is an array of swap objects.
@@ -470,7 +470,7 @@ You can’t cancel a swap that has been refunded. You must also cancel all swap
:::
You can cancel a swap by sending a request to the [Cancel Swap endpoint](https://docs.medusajs.com/api/admin#orders_postordersswapcancel):
You can cancel a swap by sending a request to the [Cancel Swap API Route](https://docs.medusajs.com/api/admin#orders_postordersswapcancel):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -531,7 +531,7 @@ curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/cancel' \
</TabItem>
</Tabs>
This endpoint requires the order and swap IDs as path parameters.
This API Route requires the order and swap IDs as path parameters.
The request returns the updated order as an object. You can access the swaps using the `swaps` property of the order object, which is an array of swap objects.
www/apps/docs/content/modules/orders/claims.md
+10 -10
View File
@@ -32,19 +32,19 @@ There are other important attributes discussed in later sections. Check out the
Claims are created in Medusa by an admin (typically a merchant). They are created on an order, and depending on the claim’s type the admin can specify details like the amount to be refunded, or the items to be returned and the new items to replace them.
You can create a claim either using the [Create Claim endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderclaims) or using the `ClaimService`'s [create method](../../references/services/classes/ClaimService.md#create). This section explains the process within the Create Claim endpoint, with a focus on the `create` method.
You can create a claim either using the [Create Claim API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaims) or using the `ClaimService`'s [create method](../../references/services/classes/ClaimService.md#create). This section explains the process within the Create Claim API Route, with a focus on the `create` method.
### Idempotency Key
An Idempotency Key is a unique key associated with a claim. It is generated when the claim creation process is started by the admin using the [Create Claim endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderclaims) and can be used to retry the claim creation safely if an error occurs. The idempotency key is stored in the `ClaimOrder` entity in the attribute `idempotency_key`.
An Idempotency Key is a unique key associated with a claim. It is generated when the claim creation process is started by the admin using the [Create Claim API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaims) and can be used to retry the claim creation safely if an error occurs. The idempotency key is stored in the `ClaimOrder` entity in the attribute `idempotency_key`.
You can learn more about idempotency keys [here](../../development/idempotency-key/overview.mdx).
### Create Claim Endpoint Process
### Create Claim API Route Process
The following flow is implemented within the Create Claim endpoint:
The following flow is implemented within the Create Claim API Route:
![Create Claim Endpoint Overview](https://res.cloudinary.com/dza7lstvk/image/upload/v1682519207/Medusa%20Docs/Diagrams/create-claim-overview_iqek1f.jpg)
![Create Claim API Route Overview](https://res.cloudinary.com/dza7lstvk/image/upload/v1682519207/Medusa%20Docs/Diagrams/create-claim-overview_iqek1f.jpg)
1. When the idempotency key’s recovery point is `started`, the creation of the claim is started using the `ClaimService`'s [create method](../../references/services/classes/ClaimService.md#create). If the claim is created successfully, the idempotency key’s recovery point is changed to `claim_created`. In the `create` method:
1. If the type of the claim is `refund` and no refund amount is set, the refund amount is calculated based on the items in the claim using the `ClaimService`'s [getRefundTotalForClaimLinesOnOrder method](../../references/services/classes/ClaimService.md#getrefundtotalforclaimlinesonorder).
@@ -63,19 +63,19 @@ The following flow is implemented within the Create Claim endpoint:
If a claim’s type is `replace`, an admin can create a [fulfillment](./fulfillments.md) for the additional items that should be sent to the customer.
A fulfillment can be created either using the [Create Claim Fulfillment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimfulfillments) or the `ClaimService`'s [createFulfillment method](../../references/services/classes/ClaimService.md#createfulfillment).
A fulfillment can be created either using the [Create Claim Fulfillment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimfulfillments) or the `ClaimService`'s [createFulfillment method](../../references/services/classes/ClaimService.md#createfulfillment).
:::note
The endpoint handles updating the inventory and reservations. So, if you choose to use the `createFulfillment` method, you should implement that within your code.
The API Route handles updating the inventory and reservations. So, if you choose to use the `createFulfillment` method, you should implement that within your code.
:::
By default, when a fulfillment is created, the claim’s `fulfillment_status` is set to `fulfilled`. However, if any of the item’s quantity isn’t fulfilled successfully, the `fulfillment_status` is set to `requires_action`.
After creating a fulfillment, you can create a shipment for the fulfillment either using the [Create Claim Shipment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimshipments) or the `ClaimService`'s [createShipment method](../../references/services/classes/ClaimService.md#createshipment). If only some of the items and their quantities are shipped, the `fulfillment_status` of the claim is set to `partially_shipped`. Otherwise, if all items and quantities are shipped, the `fulfillment_status` of the claim is set to `shipped`.
After creating a fulfillment, you can create a shipment for the fulfillment either using the [Create Claim Shipment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimshipments) or the `ClaimService`'s [createShipment method](../../references/services/classes/ClaimService.md#createshipment). If only some of the items and their quantities are shipped, the `fulfillment_status` of the claim is set to `partially_shipped`. Otherwise, if all items and quantities are shipped, the `fulfillment_status` of the claim is set to `shipped`.
You can alternatively cancel a fulfillment either using the [Cancel Claim Fulfillment endpoint](https://docs.medusajs.com/api/admin#tag/Orders/operation/PostOrdersClaimFulfillmentsCancel) or the `ClaimService`'s [cancelFulfillment method](../../references/services/classes/ClaimService.md#cancelfulfillment). This would change the `fulfillment_status` of the claim to `canceled`.
You can alternatively cancel a fulfillment either using the [Cancel Claim Fulfillment API Route](https://docs.medusajs.com/api/admin#tag/Orders/operation/PostOrdersClaimFulfillmentsCancel) or the `ClaimService`'s [cancelFulfillment method](../../references/services/classes/ClaimService.md#cancelfulfillment). This would change the `fulfillment_status` of the claim to `canceled`.
---
@@ -87,7 +87,7 @@ A claim's return can be marked as received, which would adjust the inventory and
## Cancel a Claim
An admin can cancel a claim if it hasn’t been refunded either using the [Cancel Claim endpoint](https://docs.medusajs.com/api/admin#orders_postordersclaimcancel) or the `ClaimService`'s [cancel method](../../references/services/classes/ClaimService.md#cancel).
An admin can cancel a claim if it hasn’t been refunded either using the [Cancel Claim API Route](https://docs.medusajs.com/api/admin#orders_postordersclaimcancel) or the `ClaimService`'s [cancel method](../../references/services/classes/ClaimService.md#cancel).
If any fulfillments were created, they must be canceled first. Similarly, if the claim is associated with a return, the return must be canceled first.
www/apps/docs/content/modules/orders/draft-orders.md
+2 -2
View File
@@ -32,7 +32,7 @@ There are other important attributes discussed in later sections. Check out the
## How Draft Orders Work
You have full freedom in how you choose to implement creating draft orders. This section explains how it’s created in the Medusa backend using the [Create Draft Order](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders) and [Register Payment](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorderregisterpayment) endpoints.
You have full freedom in how you choose to implement creating draft orders. This section explains how it’s created in the Medusa backend using the [Create Draft Order](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders) and [Register Payment](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersdraftorderregisterpayment) API Routes.
A draft order is created using the `DraftOrderService`'s [create method](../../references/services/classes/DraftOrderService.md#create). Within that method, a cart is created along with it. The cart is used to store the order’s details, such as the draft order’s items, shipping options, and more. The cart has the type `draft_order`.
@@ -42,7 +42,7 @@ The payment must be authorized before the cart can be completed, which can be do
:::note
In the Register Payment endpoint, the `system` payment method is used by default as the payment session of the cart. This means that the authorization and capturing of the payment don’t actually trigger any processes with existing payment processors integrated into your Medusa backend. It’s expected that the merchant will handle these processes manually.
In the Register Payment API Route, the `system` payment method is used by default as the payment session of the cart. This means that the authorization and capturing of the payment don’t actually trigger any processes with existing payment processors integrated into your Medusa backend. It’s expected that the merchant will handle these processes manually.
:::
www/apps/docs/content/modules/orders/orders.md
+1 -1
View File
@@ -182,7 +182,7 @@ Medusa provides the necessary infrastructure and tooling that allows automating
The Medusa backend facilitates automating these flows by allowing the customer to submit a [return](https://docs.medusajs.com/api/store#returns_postreturns) or [swap](https://docs.medusajs.com/api/store#swaps_postswaps) requests through the store APIs. The merchant can then review and handle these requests. This eliminates the need for the customer to perform the same action through customer support or other means.
You can also integrate these flows within bigger processes that trigger requesting or creating these flows. It can be done through core APIs, [custom endpoints](../../development/endpoints/overview.mdx), or [custom services](../../development/services/overview.mdx). You can also listen to events related to orders such as [Order](../../development/events/events-list.md#order-events) or [Swap](../../development/events/events-list.md#swap-events) events with [subscribers](../../development/events/subscribers.mdx) to perform asynchronous actions.
You can also integrate these flows within bigger processes that trigger requesting or creating these flows. It can be done through core APIs, [custom API Routes](../../development/api-routes/overview.mdx), or [custom services](../../development/services/overview.mdx). You can also listen to events related to orders such as [Order](../../development/events/events-list.md#order-events) or [Swap](../../development/events/events-list.md#swap-events) events with [subscribers](../../development/events/subscribers.mdx) to perform asynchronous actions.
---
www/apps/docs/content/modules/orders/returns.md
+3 -3
View File
@@ -50,7 +50,7 @@ You can learn more about idempotency keys [here](../../development/idempotency-k
This section explains how the return is created by the customer or any type of client. This is the process created within the Medusa core.
The following process occurs within the Create Return storefront endpoint:
The following process occurs within the Create Return storefront API Route:
![Return Client Process Flowchart](https://res.cloudinary.com/dza7lstvk/image/upload/v1681994516/Medusa%20Docs/Diagrams/return-client-process_evbjf5.jpg)
@@ -63,7 +63,7 @@ After this process, the return will be available for the merchant or the admin t
Marking a return as received would refund the amount to the customer and adjust the store’s inventory for the returned items.
The following process occurs within the [Receive Return admin endpoint](https://docs.medusajs.com/api/admin#returns_postreturnsreturnreceive):
The following process occurs within the [Receive Return admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsreturnreceive):
![Receive Return Process Flowchart](https://res.cloudinary.com/dza7lstvk/image/upload/v1681996834/Medusa%20Docs/Diagrams/return-admin-process_e99skk.jpg)
@@ -79,7 +79,7 @@ The following process occurs within the [Receive Return admin endpoint](https://
### Cancel a Return
The merchant can cancel a return if it hasn’t be marked as `received` before. This can be done either using the `ReturnService`'s [cancel method](../../references/services/classes/ReturnService.md#cancel) or using the [Cancel Return endpoint](https://docs.medusajs.com/api/admin#returns_postreturnsreturncancel).
The merchant can cancel a return if it hasn’t be marked as `received` before. This can be done either using the `ReturnService`'s [cancel method](../../references/services/classes/ReturnService.md#cancel) or using the [Cancel Return API Route](https://docs.medusajs.com/api/admin#returns_postreturnsreturncancel).
Canceling a return would change its status to canceled.
www/apps/docs/content/modules/orders/storefront/create-return.mdx
+4 -4
View File
@@ -57,7 +57,7 @@ When a customer wants to create a return, they must choose the items they want t
### Showing Return Shipping Options
You can optionally allow customers to choose a return shipping option that they’ll use to return the items. To show the customers the available return shipping options, send a request to the Get [Shipping Options endpoint](https://docs.medusajs.com/api/store#shipping-options_getshippingoptions):
You can optionally allow customers to choose a return shipping option that they’ll use to return the items. To show the customers the available return shipping options, send a request to the Get [Shipping Options API Route](https://docs.medusajs.com/api/store#shipping-options_getshippingoptions):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -121,7 +121,7 @@ fetch(`<BACKEND_URL>/store/shipping-options?is_return=true`, {
</TabItem>
</Tabs>
This endpoint allows you to pass the `is_return` query parameter to indicate whether the shipping options should be return shipping options. You can learn about other available filters in the [API reference](https://docs.medusajs.com/api/store#shipping-options_getshippingoptions).
This API Route allows you to pass the `is_return` query parameter to indicate whether the shipping options should be return shipping options. You can learn about other available filters in the [API reference](https://docs.medusajs.com/api/store#shipping-options_getshippingoptions).
The request returns an array of shipping option objects.
@@ -129,7 +129,7 @@ The request returns an array of shipping option objects.
## Step 2: Create Return
You can create the return by sending a request to the [Create Return endpoint](https://docs.medusajs.com/api/store#returns_postreturns):
You can create the return by sending a request to the [Create Return API Route](https://docs.medusajs.com/api/store#returns_postreturns):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -215,7 +215,7 @@ fetch(`<BACKEND_URL>/store/returns`, {
</TabItem>
</Tabs>
This endpoint requires the following request body parameters:
This API Route requires the following request body parameters:
- `order_id`: a string indicating the ID of the order to create the return for.
- `items`: an array of objects, each object being an item from the order to return. Each object must have the following properties:
www/apps/docs/content/modules/orders/storefront/create-swap.mdx
+4 -4
View File
@@ -60,7 +60,7 @@ You can optionally allow customers to choose a return shipping option that they
## Step 2: Create the Swap
After collecting the swap details in step 1, you can create a swap in the Medusa backend by sending a request to the [Create Swap endpoint](https://docs.medusajs.com/api/store#swaps_postswaps):
After collecting the swap details in step 1, you can create a swap in the Medusa backend by sending a request to the [Create Swap API Route](https://docs.medusajs.com/api/store#swaps_postswaps):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -158,7 +158,7 @@ fetch(`<BACKEND_URL>/store/swaps`, {
</TabItem>
</Tabs>
This endpoint requires the following request body parameters:
This API Route requires the following request body parameters:
- `order_id`: a string indicating the ID of the order that this swap is created for.
- `return_items`: an array of objects, each object being the item to return. Each object should have the following properties:
@@ -188,7 +188,7 @@ When you complete the cart, the returned `type` field can be used to indicate th
### Retrieve Swap by Cart ID
During your checkout flow, you might need to retrieve the swap using the cart’s ID. For example, if you want to display the swap’s details after the cart is successfully completed. You can do that using the [Get by Cart ID endpoint](https://docs.medusajs.com/api/store#swaps_getswapsswapcartid):
During your checkout flow, you might need to retrieve the swap using the cart’s ID. For example, if you want to display the swap’s details after the cart is successfully completed. You can do that using the [Get by Cart ID API Route](https://docs.medusajs.com/api/store#swaps_getswapsswapcartid):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -240,7 +240,7 @@ fetch(`<BACKEND_URL>/store/swaps/${cartId}`, {
</TabItem>
</Tabs>
This endpoint requires the ID of the cart as a path parameter.
This API Route requires the ID of the cart as a path parameter.
The request returns the swap as an object.
www/apps/docs/content/modules/orders/storefront/handle-order-edits.mdx
+6 -6
View File
@@ -70,7 +70,7 @@ You must have an existing order edit in the “request” state.
## Retrieve an Order Edit
You can retrieve a single order edit by its ID by sending a request to the [Get Order Edit](https://docs.medusajs.com/api/store#order-edits_getordereditsorderedit) endpoint:
You can retrieve a single order edit by its ID by sending a request to the [Get Order Edit API Route](https://docs.medusajs.com/api/store#order-edits_getordereditsorderedit):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -191,14 +191,14 @@ If `difference_due` is less than 0, then the amount will be refunded to the cust
:::note
This section explains how to authorize the payment using one payment processor and payment session. However, payment collections allow customers to pay in installments or with more than one provider. You can learn more about how to do that using the [batch endpoints of the Payment APIs](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionssessionsbatchauthorize)
This section explains how to authorize the payment using one payment processor and payment session. However, payment collections allow customers to pay in installments or with more than one provider. You can learn more about how to do that using the [batch routes of the Payment APIs](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionssessionsbatchauthorize)
:::
If `difference_due` is greater than 0, then additional payment from the customer is required. In this case, you must implement these steps to allow the customer to authorize the payment:
1. Show the customer the available payment processors. These can be retrieved from the details of [the region of the order](https://docs.medusajs.com/api/store#regions_getregions).
2. When the customer selects the payment processor, initialize the payment session of that provider in the payment collection. You can do that by sending a request to the [Manage Payment Sessions](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionspaymentcollectionsessionsbatch) endpoint, passing it the payment collection’s ID as a path parameter, and the payment processor's ID as a request body parameter:
2. When the customer selects the payment processor, initialize the payment session of that provider in the payment collection. You can do that by sending a request to the [Manage Payment Sessions API Route](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionspaymentcollectionsessionsbatch), passing it the payment collection’s ID as a path parameter, and the payment processor's ID as a request body parameter:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -267,7 +267,7 @@ fetch(
</Tabs>
1. Show the customer the payment details form based on the payment session’s provider. For example, if the provider ID of a payment session is `stripe`, you must show Stripe’s card component to enter the customer’s card details.
2. Authorize the payment using the payment processor. The [Authorize Payment Session](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionssessionssessionauthorize) endpoint accepts the payment collection’s ID and the ID of the payment session as path parameters:
2. Authorize the payment using the payment processor. The [Authorize Payment Session API Route](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionssessionssessionauthorize) accepts the payment collection’s ID and the ID of the payment session as path parameters:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -335,7 +335,7 @@ After performing the above steps, you can [complete the Order Edit](#complete-th
## Complete the Order Edit
To confirm and complete the order edit, send a request to the [Complete Order Edit](https://docs.medusajs.com/api/store#order-edits_postordereditsordereditcomplete) endpoint:
To confirm and complete the order edit, send a request to the [Complete Order Edit API Route](https://docs.medusajs.com/api/store#order-edits_postordereditsordereditcomplete):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -402,7 +402,7 @@ If the payment isn’t authorized first, the order edit completion will fail.
## Decline an Order Edit
If the customer wants to decline the Order Edit, you can do that by sending a request to the Decline Order Edit endpoint:
If the customer wants to decline the Order Edit, you can do that by sending a request to the Decline Order Edit API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/orders/storefront/implement-claim-order.mdx
+2 -2
View File
@@ -77,7 +77,7 @@ In addition, it is assumed you already have a logged-in customer before performi
When the customer wants to claim an order, they must supply its ID.
To allow the customer to claim an order, send a request to the Claim an Order endpoint:
To allow the customer to claim an order, send a request to the Claim an Order API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -135,7 +135,7 @@ The customer at this point will receive an email with a link to verify their cla
The link in the email that the customer receives should be a page in your storefront that accepts a `token` query parameter.
Then, you send a request to the Verify Claim Order endpoint:
Then, you send a request to the Verify Claim Order API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/orders/storefront/retrieve-order-details.mdx
+7 -7
View File
@@ -36,7 +36,7 @@ If you follow the Medusa React code blocks, it's assumed you already have [Medus
Retrieving an order by its ID is useful for different scenarios, such as using an order details page. You can use this method for both logged in and guest customers.
You can retrieve an order by its ID using the [Get Order endpoint](https://docs.medusajs.com/api/store#orders_getordersorder):
You can retrieve an order by its ID using the [Get Order API Route](https://docs.medusajs.com/api/store#orders_getordersorder):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -88,7 +88,7 @@ fetch(`<BACKEND_URL>/store/orders/${orderId}`, {
</TabItem>
</Tabs>
This endpoint requires the order’s ID to be passed as a path parameter. You can utilize the [expand](https://docs.medusajs.com/api/store#expanding-fields) and [fields](https://docs.medusajs.com/api/store#selecting-fields) query parameters to select parameters and relations to return.
This API Route requires the order’s ID to be passed as a path parameter. You can utilize the [expand](https://docs.medusajs.com/api/store#expanding-fields) and [fields](https://docs.medusajs.com/api/store#selecting-fields) query parameters to select parameters and relations to return.
The request returns the order as an object.
@@ -98,7 +98,7 @@ The request returns the order as an object.
Display IDs allow you to show human-readable IDs to your customers. Retrieving an order by its display ID is useful in many situations, such as allowing customers to look up their orders with a search field. This method of retrieving an order can be used for both logged-in customers and guest customers.
You can retrieve an order by its display ID using the [Look Up Order endpoint](https://docs.medusajs.com/api/store#orders_getorders):
You can retrieve an order by its display ID using the [Look Up Order API Route](https://docs.medusajs.com/api/store#orders_getorders):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -158,12 +158,12 @@ fetch(`<BACKEND_URL>/store/orders?display_id=1&email=user@example.com`, {
</TabItem>
</Tabs>
This endpoint requires two query parameters:
This API Route requires two query parameters:
- `display_id`: a string indicating display ID of the order. If you already have an order object, you can retrieve the display ID using `order.display_id`.
- `email`: a string indicating the email associated with the order.
You can pass other query parameters to filter the orders even further, and the endpoint will return the first order that matches the filters. Learn more about available query parameters in the [API reference](https://docs.medusajs.com/api/store#orders_getorders).
You can pass other query parameters to filter the orders even further, and the API Route will return the first order that matches the filters. Learn more about available query parameters in the [API reference](https://docs.medusajs.com/api/store#orders_getorders).
The request returns the order as an object.
@@ -173,7 +173,7 @@ The request returns the order as an object.
In certain scenarios, you may need to retrieve an order’s details using the ID of the cart associated with the order. This can be useful when showing a success page after a cart is completed and an order is placed.
You can retrieve an order by the cart ID using the [Get by Cart ID endpoint](https://docs.medusajs.com/api/store#orders_getordersordercartid):
You can retrieve an order by the cart ID using the [Get by Cart ID API Route](https://docs.medusajs.com/api/store#orders_getordersordercartid):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -225,7 +225,7 @@ fetch(`<BACKEND_URL>/store/orders/cart/${cartId}`, {
</TabItem>
</Tabs>
This endpoint requires the ID of the cart as a path parameter.
This API Route requires the ID of the cart as a path parameter.
The request returns the order as an object.
www/apps/docs/content/modules/orders/swaps.md
+6 -6
View File
@@ -47,7 +47,7 @@ You can learn more about idempotency keys [here](../../development/idempotency-k
### Swap Creation Process
The customer starts by creating their swap, which can be done through the Create Swap endpoint. In this endpoint, the following steps are implemented:
The customer starts by creating their swap, which can be done through the Create Swap API Route. In this API Route, the following steps are implemented:
![Swap Creation Flowchart](https://res.cloudinary.com/dza7lstvk/image/upload/v1681983755/Medusa%20Docs/Diagrams/swap-process_kylqq0.jpg)
@@ -69,7 +69,7 @@ This is all made possible since the swap is linked to a cart, so the same checko
After the swap has been created and completed by the customer, the merchant can then process the payment of the swap. This includes either refunding or capturing an additional payment, which is decided by the value of the `difference_due` attribute as explained in the [Swap Entity section](#swap-entity-overview).
The processing of the swap’s payment can be done either using the `SwapService`'s [processDifference method](../../references/services/classes/SwapService.md#processdifference), or using the [Process Swap Payment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapprocesspayment).
The processing of the swap’s payment can be done either using the `SwapService`'s [processDifference method](../../references/services/classes/SwapService.md#processdifference), or using the [Process Swap Payment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapprocesspayment).
If the swap requires any additional payment, the customer is expected to have authorized the payment during the [swap and cart completion flow explained earlier](#how-are-swaps-created). The merchant can then capture the payment and the `payment_status` of the swap is set to `captured`.
@@ -89,9 +89,9 @@ Although you have freedom in how you implement the process, the recommended proc
![Swap Fulfillment Flowchart](https://res.cloudinary.com/dza7lstvk/image/upload/v1681984933/Medusa%20Docs/Diagrams/swap-fulfillment-process_xfurko.jpg)
1. The fulfillment is created either using the `SwapService`'s [createFulfillment method](../../references/services/classes/SwapService.md#createfulfillment) or using the [Create a Swap Fulfillment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapfulfillments). This would set the `fulfillment_status` of the swap either to `fulfilled` if all items have been fulfilled, or `partially_fulfilled` if only some items were fulfilled.
2. The shipment can then be created using the `SwapService`'s [createShipment method](../../references/services/classes/SwapService.md#createshipment) or using the [Create Swap Shipment endpoint](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapshipments). This would set the `fulfillment_status` of the swap either to `shipped` if all items have been shipped, or `partially_shipped` if only some items were shipped.
3. Alternatively, a fulfillment can be canceled after it has been created using the `SwapService`'s [cancelFulfillment method](../../references/services/classes/SwapService.md#cancelfulfillment) or using the [Cancel Swap’s Fulfillment endpoint](https://docs.medusajs.com/api/admin#orders_postordersswapfulfillmentscancel). This would set the `fulfillment_status` of the swap to `canceled`.
1. The fulfillment is created either using the `SwapService`'s [createFulfillment method](../../references/services/classes/SwapService.md#createfulfillment) or using the [Create a Swap Fulfillment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapfulfillments). This would set the `fulfillment_status` of the swap either to `fulfilled` if all items have been fulfilled, or `partially_fulfilled` if only some items were fulfilled.
2. The shipment can then be created using the `SwapService`'s [createShipment method](../../references/services/classes/SwapService.md#createshipment) or using the [Create Swap Shipment API Route](https://docs.medusajs.com/api/admin#orders_postordersorderswapsswapshipments). This would set the `fulfillment_status` of the swap either to `shipped` if all items have been shipped, or `partially_shipped` if only some items were shipped.
3. Alternatively, a fulfillment can be canceled after it has been created using the `SwapService`'s [cancelFulfillment method](../../references/services/classes/SwapService.md#cancelfulfillment) or using the [Cancel Swap’s Fulfillment API Route](https://docs.medusajs.com/api/admin#orders_postordersswapfulfillmentscancel). This would set the `fulfillment_status` of the swap to `canceled`.
A swap’s fulfillments can be accessed by expanding the `fulfillments` relation and accessing `swap.fulfillments`. A fulfillment is represented by the `Fulfillment` entity.
@@ -105,7 +105,7 @@ A swap's return can be marked as received, which would adjust the inventory and
## Canceling a Swap
A swap can be canceled by the merchant if necessary. It can be done either through the `SwapService`'s [cancel method](../../references/services/classes/SwapService.md#cancel) or the [Cancel Swap endpoint](https://docs.medusajs.com/api/admin#orders_postordersswapcancel).
A swap can be canceled by the merchant if necessary. It can be done either through the `SwapService`'s [cancel method](../../references/services/classes/SwapService.md#cancel) or the [Cancel Swap API Route](https://docs.medusajs.com/api/admin#orders_postordersswapcancel).
A swap can’t be canceled if:
www/apps/docs/content/modules/price-lists/admin/_import-prices.mdx
+3 -3
View File
@@ -137,7 +137,7 @@ You can learn more about [authenticating as an admin user in the API reference](
Before importing the prices, you must have a price list to import them to.
You can use the [Create Price List](https://docs.medusajs.com/api/admin#price-lists_postpricelistspricelist) endpoint, or follow the [how-to guide to learn how to create and manage price lists using the Admin API](./manage-price-lists.mdx).
You can use the [Create Price List API Route](https://docs.medusajs.com/api/admin#price-lists_postpricelistspricelist), or follow the [how-to guide to learn how to create and manage price lists using the Admin API](./manage-price-lists.mdx).
---
@@ -145,7 +145,7 @@ You can use the [Create Price List](https://docs.medusajs.com/api/admin#price-li
The first step is to upload the CSV file to import prices from.
You can do that by sending the following request to the [Upload Files](https://docs.medusajs.com/api/admin#uploads_postuploads) endpoint:
You can do that by sending the following request to the [Upload Files API Route](https://docs.medusajs.com/api/admin#uploads_postuploads):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -219,7 +219,7 @@ This request returns an array of uploads. Each item in the array is an object th
To start a new price import, you must create a batch job.
You can do that by sending the following request to the [Create a Batch Job](https://docs.medusajs.com/api/admin#batch-jobs_postbatchjobs) endpoint:
You can do that by sending the following request to the [Create a Batch Job API Route](https://docs.medusajs.com/api/admin#batch-jobs_postbatchjobs):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/price-lists/admin/manage-price-lists.mdx
+6 -6
View File
@@ -230,7 +230,7 @@ You can check the full list of request body parameters in the [API reference](ht
## Get Price List’s Details
You can retrieve all of a price list’s details using the Get a Price List endpoint:
You can retrieve all of a price list’s details using the Get a Price List API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -294,7 +294,7 @@ curl -L -X GET '<BACKEND_URL>/admin/price-lists/{id}' \
## Update a Price List
After creating a price list, you can update all of its fields including its status, prices, and more using the [Update Price List](https://docs.medusajs.com/api/admin#price-lists_postpricelistspricelistpricelist) endpoint.
After creating a price list, you can update all of its fields including its status, prices, and more using the [Update Price List API Route](https://docs.medusajs.com/api/admin#price-lists_postpricelistspricelistpricelist).
For example, by sending the following request the end date of the price list will be updated:
@@ -381,7 +381,7 @@ For a full list of request body parameters, check out the [API reference](https:
### Add Prices
You can add prices to your price list after creating it using the [Update Prices](https://docs.medusajs.com/api/admin#price-lists_postpricelistspricelistpricesbatch) endpoint.
You can add prices to your price list after creating it using the [Update Prices API Route](https://docs.medusajs.com/api/admin#price-lists_postpricelistspricelistpricesbatch).
You can also set the `override` request body parameter to `true` to replace the existing prices in the price list.
@@ -488,7 +488,7 @@ For a full list of request body parameters, check out the [API reference](https:
### Delete a Product’s Prices
You can delete all the prices of a product’s variants using the [Delete Product Prices](https://docs.medusajs.com/api/admin#price-lists_deletepricelistspricelistpricesbatch) endpoint:
You can delete all the prices of a product’s variants using the [Delete Product Prices API Route](https://docs.medusajs.com/api/admin#price-lists_deletepricelistspricelistpricesbatch):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -562,7 +562,7 @@ This request returns the IDs of the deleted prices.
### Delete a Variant’s Prices
You can delete all the prices of a variant using the [Delete Variant Prices](https://docs.medusajs.com/api/admin#price-lists_deletepricelistspricelistvariantsvariantprices) endpoint:
You can delete all the prices of a variant using the [Delete Variant Prices API Route](https://docs.medusajs.com/api/admin#price-lists_deletepricelistspricelistvariantsvariantprices):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -639,7 +639,7 @@ This request returns the IDs of the deleted prices.
## Delete Price List
You can delete a price list, and subsequently all prices defined in it, using the [Delete Price List](https://docs.medusajs.com/api/admin#price-lists_deletepricelistspricelist) endpoint:
You can delete a price list, and subsequently all prices defined in it, using the [Delete Price List API Route](https://docs.medusajs.com/api/admin#price-lists_deletepricelistspricelist):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/price-lists/backend/override-price-selection-strategy.md
+1 -1
View File
@@ -125,4 +125,4 @@ Run your backend to test it out:
npx medusa develop
```
Then, try out your strategy using any of the [Products](https://docs.medusajs.com/api/store#products) or [Carts](https://docs.medusajs.com/api/store#carts) endpoints which include retrieving product variants and line items respectively. You should then see the prices in the response based on your implemented strategy.
Then, try out your strategy using any of the [Products](https://docs.medusajs.com/api/store#products) or [Carts](https://docs.medusajs.com/api/store#carts) API Routes which include retrieving product variants and line items respectively. You should then see the prices in the response based on your implemented strategy.
www/apps/docs/content/modules/price-lists/price-lists.md
+2 -2
View File
@@ -61,7 +61,7 @@ The original price depends on the selected region or currency code in the curren
The calculated price is the lowest price among all retrieved prices. Retrieved prices can include the original price and the price lists that can be applied. Prices are retrieved based on the [context](./price-selection-strategy.md#context-object).
In the [Get Product](https://docs.medusajs.com/api/store#products_getproductsproduct) and [List Product](https://docs.medusajs.com/api/store#products_getproducts) endpoints, you must pass either the `region_id` or `currency_code` to retrieve the correct prices, as they are part of the price selection strategy context.
In the [Get Product](https://docs.medusajs.com/api/store#products_getproductsproduct) and [List Product](https://docs.medusajs.com/api/store#products_getproducts) API Routes, you must pass either the `region_id` or `currency_code` to retrieve the correct prices, as they are part of the price selection strategy context.
Each variant in the response has the following properties:
@@ -76,7 +76,7 @@ The total of a line item depends on the price of a product variant. When the lin
Then, the `unit_price` of the line item is set to the `calculated_price` property of the product variant.
When creating, retrieving, or updating the line item using the API endpoints, the line item’s totals are calculated. The following properties are returned as part of the endpoints’ responses:
When creating, retrieving, or updating the line item using the API Routes, the line item’s totals are calculated. The following properties are returned as part of the API Routes' responses:
- `unit_price`: The product variant’s calculated price.
- `subtotal`: The `unit_price` multiplied by the quantity of the line item.
www/apps/docs/content/modules/products/admin/import-products.mdx
+2 -2
View File
@@ -868,7 +868,7 @@ You can learn more about [authenticating as an admin user in the API reference](
The first step is to upload the CSV file that you want to import products.
You can do that by sending the following request to the [Upload Files](https://docs.medusajs.com/api/admin#uploads_postuploads) endpoint:
You can do that by sending the following request to the [Upload Files API Route](https://docs.medusajs.com/api/admin#uploads_postuploads):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -943,7 +943,7 @@ Where `<FILE_PATH_1>` is a full path to the file. For example, `/Users/medusa/pr
To start a new product import, you must create a batch job.
You can do that by sending the following request to the [Create a Batch Job](https://docs.medusajs.com/api/admin#batch-jobs_postbatchjobs) endpoint:
You can do that by sending the following request to the [Create a Batch Job API Route](https://docs.medusajs.com/api/admin#batch-jobs_postbatchjobs):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/products/admin/manage-categories.mdx
+7 -7
View File
@@ -51,7 +51,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Categories
You can retrieve available categories by sending a request to the [List Categories](https://docs.medusajs.com/api/admin#product-categories_getproductcategories) endpoint:
You can retrieve available categories by sending a request to the [List Categories API Route](https://docs.medusajs.com/api/admin#product-categories_getproductcategories):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -131,7 +131,7 @@ You can also pass filters and other selection query parameters to the request. C
## Create a Category
You can create a category by sending a request to the [Create a Category](https://docs.medusajs.com/api/admin#product-categories_postproductcategories) endpoint:
You can create a category by sending a request to the [Create a Category API Route](https://docs.medusajs.com/api/admin#product-categories_postproductcategories):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -215,7 +215,7 @@ The request returns the newly created product category.
## Retrieve a Category
You can retrieve a product category by sending a request to the [Get a Product Category](https://docs.medusajs.com/api/admin#product-categories_getproductcategoriescategory) endpoint:
You can retrieve a product category by sending a request to the [Get a Product Category API Route](https://docs.medusajs.com/api/admin#product-categories_getproductcategoriescategory):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -285,7 +285,7 @@ It returns the full object of the product category.
## Edit a Category
You can edit a product category by sending a request to the [Update a Product Category](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriescategory) endpoint:
You can edit a product category by sending a request to the [Update a Product Category API Route](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriescategory):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -380,7 +380,7 @@ You can manage the categories of each product individually using the [product AP
### Add Products to a Category
You can add more than one product to a category using the [Add Products to a Category](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriescategoryproductsbatch) endpoint:
You can add more than one product to a category using the [Add Products to a Category API Route](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriescategoryproductsbatch):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -491,7 +491,7 @@ The request returns the full object of the product category updated with the new
### Remove Products from a Category
You can remove products from a category by sending a request to the [Delete Products](https://docs.medusajs.com/api/admin#product-categories_deleteproductcategoriescategoryproductsbatch) endpoint:
You can remove products from a category by sending a request to the [Delete Products API Route](https://docs.medusajs.com/api/admin#product-categories_deleteproductcategoriescategoryproductsbatch):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -608,7 +608,7 @@ The request returns the full object of the product category updated with the its
## Delete a Category
You can delete a product category by sending a request to the [Delete a Product Category](https://docs.medusajs.com/api/admin#product-categories_deleteproductcategoriescategory) endpoint:
You can delete a product category by sending a request to the [Delete a Product Category API Route](https://docs.medusajs.com/api/admin#product-categories_deleteproductcategoriescategory):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/products/admin/manage-products.mdx
+26 -26
View File
@@ -52,7 +52,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Products
You can list products as an admin using the [List Products endpoint](https://docs.medusajs.com/api/admin#products_getproducts):
You can list products as an admin using the [List Products API Route](https://docs.medusajs.com/api/admin#products_getproducts):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -115,7 +115,7 @@ curl -L -X GET '<BACKEND_URL>/admin/products' \
</TabItem>
</Tabs>
This endpoint does not require any parameters. You can pass parameters to search and filter through the retrieved products. For example, you can pass the `q` parameter which searches through product titles, descriptions, and more. You can learn more about available parameters in the [API reference](https://docs.medusajs.com/api/admin#products_getproducts).
This API Route doesn't require any parameters. You can pass parameters to search and filter through the retrieved products. For example, you can pass the `q` parameter which searches through product titles, descriptions, and more. You can learn more about available parameters in the [API reference](https://docs.medusajs.com/api/admin#products_getproducts).
You can also specify which fields to returns or which relations to expand using the `fields` and `expand` query parameters. You can learn more about them in the [API reference](https://docs.medusajs.com/api/admin#expanding-fields).
@@ -125,7 +125,7 @@ The request returns an array of products along with [pagination parameters](http
## Create a Product
You can create a product by sending a request to the [Create a Product endpoint](https://docs.medusajs.com/api/admin#products_postproducts):
You can create a product by sending a request to the [Create a Product API Route](https://docs.medusajs.com/api/admin#products_postproducts):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -365,7 +365,7 @@ curl -L -X POST '<BACKEND_URL>/admin/products' \
</TabItem>
</Tabs>
This endpoint only requires the `title` body parameter, which is the name of the product. Other parameters passed in the example are optional. They are:
This API Route only requires the `title` body parameter, which is the name of the product. Other parameters passed in the example are optional. They are:
- `is_giftcard`: a boolean value that determines whether a product is a gift card. By default, it’s `false`.
- `is_discountable`: a boolean value that determines whether discounts can be applied on the product. By default, it’s `true`.
@@ -399,7 +399,7 @@ You can learn more about pricing and zero-decimal currencies [here](../products.
## Retrieve a Product
You can retrieve a single product as an admin by sending a request to the [Get a Product endpoint](https://docs.medusajs.com/api/admin#products_getproductsproduct):
You can retrieve a single product as an admin by sending a request to the [Get a Product API Route](https://docs.medusajs.com/api/admin#products_getproductsproduct):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -459,7 +459,7 @@ curl -L -X GET '<BACKEND_URL>/admin/products/<PRODUCT_ID>' \
</TabItem>
</Tabs>
This endpoint requires the product ID to be passed as a path parameter.
This API Route requires the product ID to be passed as a path parameter.
The request returns the product as an object.
@@ -467,7 +467,7 @@ The request returns the product as an object.
## Update a Product
You can update a product by sending a request to the [Update Product endpoint](https://docs.medusajs.com/api/admin#products_postproductsproduct):
You can update a product by sending a request to the [Update Product API Route](https://docs.medusajs.com/api/admin#products_postproductsproduct):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -540,7 +540,7 @@ curl -L -X POST '<BACKEND_URL>/admin/products/<PRODUCT_ID>' \
</TabItem>
</Tabs>
This endpoint requires the product ID as a path parameter. In the request’s body, you can pass any of the product’s fields to update. In the example above, you update the `title` of the product.
This API Route requires the product ID as a path parameter. In the request’s body, you can pass any of the product’s fields to update. In the example above, you update the `title` of the product.
You can learn about other body parameters that you can pass in the [API reference](https://docs.medusajs.com/api/admin#products_postproductsproduct).
@@ -550,15 +550,15 @@ The request returns the updated product as an object.
## Manage Product Options
In this section, you’ll learn how to manage the options of the product. Although you can already do that through the [Create a Product](#create-a-product) and [Update a Product](#update-a-product) endpoints explained above, you can also use endpoints specific to product options.
In this section, you’ll learn how to manage the options of the product. Although you can already do that through the [Create a Product](#create-a-product) and [Update a Product](#update-a-product) API Routes explained above, you can also use API Routes specific to product options.
### Retrieve Product Options
You can retrieve a product’s options by retrieving the product either using the [List Products](#list-products) or the [Retrieve a Product](#retrieve-a-product) endpoints. The options are available under the `options` property.
You can retrieve a product’s options by retrieving the product either using the [List Products](#list-products) or the [Retrieve a Product](#retrieve-a-product) API Routes. The options are available under the `options` property.
### Add a Product Option
You can add a product option to a product by sending a request to the [Add Product Option endpoint](https://docs.medusajs.com/api/admin#products_postproductsproductoptions):
You can add a product option to a product by sending a request to the [Add Product Option API Route](https://docs.medusajs.com/api/admin#products_postproductsproductoptions):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -631,13 +631,13 @@ curl -L -X POST '<BACKEND_URL>/admin/products/<PRODUCT_ID>/options' \
</TabItem>
</Tabs>
This endpoint requires the product’s ID as a path parameter. In the request body parameter, it requires passing the `title` of the option.
This API Route requires the product’s ID as a path parameter. In the request body parameter, it requires passing the `title` of the option.
The request returns the updated product as an option. You can view available options under the `options` property of the product.
### Update a Product Option
You can update a product option by sending a request to the [Update Product Option endpoint](https://docs.medusajs.com/api/admin#products_postproductsproductoptionsoption):
You can update a product option by sending a request to the [Update Product Option API Route](https://docs.medusajs.com/api/admin#products_postproductsproductoptionsoption):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -713,7 +713,7 @@ curl -L -X POST '<BACKEND_URL>/admin/products/<PRODUCT_ID>/options/<OPT_ID>' \
</TabItem>
</Tabs>
This endpoint requires the product’s ID and the product option’s ID to be passed as a path parameter.
This API Route requires the product’s ID and the product option’s ID to be passed as a path parameter.
In the body parameters, you can update the `title` field of the product option.
@@ -721,7 +721,7 @@ The request returns the updated product as an option. You can view available opt
### Delete a Product Option
You can delete a product option by sending a request to the [Delete Product Option endpoint](https://docs.medusajs.com/api/admin#products_deleteproductsproductoptionsoption):
You can delete a product option by sending a request to the [Delete Product Option API Route](https://docs.medusajs.com/api/admin#products_deleteproductsproductoptionsoption):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -782,7 +782,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/products/<PRODUCT_ID>/options/<OPT_ID>' \
</TabItem>
</Tabs>
This endpoint requires the product’s ID and the product option’s ID to be passed as a path parameter.
This API Route requires the product’s ID and the product option’s ID to be passed as a path parameter.
The request returns the following fields:
@@ -795,15 +795,15 @@ The request returns the following fields:
## Manage Product Variants
In this section, you’ll learn how to manage the variants of the product. Although you can already do that through the [Create a Product](#create-a-product) and [Update a Product](#update-a-product) endpoints explained above, you can also use endpoints specific to product variants.
In this section, you’ll learn how to manage the variants of the product. Although you can already do that through the [Create a Product](#create-a-product) and [Update a Product](#update-a-product) API Routes explained above, you can also use API Routes specific to product variants.
### Retrieve Product Variants
You can retrieve a product’s variants by retrieving the product either using the [List Products](#list-products) or the [Retrieve a Product](#retrieve-a-product) endpoints. The product variants are available under the `variants` property.
You can retrieve a product’s variants by retrieving the product either using the [List Products](#list-products) or the [Retrieve a Product](#retrieve-a-product) API Routes. The product variants are available under the `variants` property.
### Create Product Variants
You can create a product variant by sending a request to the [Create Product Variant endpoint](https://docs.medusajs.com/api/admin#products_postproductsproductvariants):
You can create a product variant by sending a request to the [Create Product Variant API Route](https://docs.medusajs.com/api/admin#products_postproductsproductvariants):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -924,7 +924,7 @@ curl -L -X POST '<BACKEND_URL>/admin/products/<PRODUCT_ID>/variants' \
</TabItem>
</Tabs>
This endpoint requires the ID of the product as a path parameter. In the request body parameters, the following parameters are required:
This API Route requires the ID of the product as a path parameter. In the request body parameters, the following parameters are required:
- `title`: A string indicating the title of the product variant.
- `prices`: an array of objects, each object indicating the pricing of the variant in different contexts. For example, you can specify different prices for different currencies or regions. You can learn about other accepted properties within price objects in the API reference. You can also learn about formatting the `amount` property in this section.
@@ -938,7 +938,7 @@ The request returns the updated product. You can access the product’s variants
### Update a Product Variant
You can update a product variant by sending a request to the [Update a Product Variant endpoint](https://docs.medusajs.com/api/admin#products_postproductsproductvariantsvariant):
You can update a product variant by sending a request to the [Update a Product Variant API Route](https://docs.medusajs.com/api/admin#products_postproductsproductvariantsvariant):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -1014,7 +1014,7 @@ curl -L -X POST '<BACKEND_URL>/admin/products/<PRODUCT_ID>/variants/<VARIANT_ID>
</TabItem>
</Tabs>
This endpoint requires the product ID and variant ID to be passed as a path parameter.
This API Route requires the product ID and variant ID to be passed as a path parameter.
In the request body parameters, you can pass any of the variant’s attributes that you want to update. In the example above, you edit the `title` of the variant. You can refer to the [API reference](https://docs.medusajs.com/api/admin#products_postproductsproductvariantsvariant) for other possible parameters.
@@ -1022,7 +1022,7 @@ The request returns the updated product. You can access the product’s variants
### Delete Product Variant
You can delete a product variant by sending a request to the [Delete a Product Variant endpoint](https://docs.medusajs.com/api/admin#products_deleteproductsproductvariantsvariant):
You can delete a product variant by sending a request to the [Delete a Product Variant API Route](https://docs.medusajs.com/api/admin#products_deleteproductsproductvariantsvariant):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -1083,7 +1083,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/products/<PRODUCT_ID>/variants/<VARIANT_I
</TabItem>
</Tabs>
This endpoint requires the product ID and variant ID to be passed as a path parameter.
This API Route requires the product ID and variant ID to be passed as a path parameter.
The request returns the following fields:
@@ -1096,7 +1096,7 @@ The request returns the following fields:
## Delete a Product
You can delete a product by sending a request to the [Delete a Product endpoint](https://docs.medusajs.com/api/admin#products_deleteproductsproduct):
You can delete a product by sending a request to the [Delete a Product API Route](https://docs.medusajs.com/api/admin#products_deleteproductsproduct):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -1155,7 +1155,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/products/<PRODUCT_ID>' \
</TabItem>
</Tabs>
This endpoint requires passing the product ID as a path parameter.
This API Route requires passing the product ID as a path parameter.
The request returns the following fields:
www/apps/docs/content/modules/products/categories.md
+1 -1
View File
@@ -82,7 +82,7 @@ The relation is implemented in the Product entity. You can access the product
The parent-child hierarchy is represented in the `ProductCategory` entity through the following relations:
- You can access the parent of a category by expanding the `parent_category` relation and accessing `category.parent_category`. You can also access the ID of the parent category by accessing `category.parent_category_id`. If a category doesn’t have a parent, the relation and the ID will be `null`.
- You can access the children of a category by expanding the `category_children` relation and accessing `category.category_children`. If a category doesn’t have children, the relation will be an empty array. By default, when expanding this relation in Product Category endpoints, only the immediate child categories are returned. If you want to get the entire hierarchy of child categories, you must pass the `include_descendants_tree` flag to the endpoint setting its value to `true`.
- You can access the children of a category by expanding the `category_children` relation and accessing `category.category_children`. If a category doesn’t have children, the relation will be an empty array. By default, when expanding this relation in Product Category API Routes, only the immediate child categories are returned. If you want to get the entire hierarchy of child categories, you must pass the `include_descendants_tree` flag to the API Route setting its value to `true`.
Aside from these relations, the `mpath` attribute, which is a [Materialized Path](https://typeorm.io/tree-entities#materialized-path-aka-path-enumeration) that is automatically generated by Typeorm, can be used to query deep trees faster.
www/apps/docs/content/modules/products/serverless-module.md
+4 -4
View File
@@ -225,7 +225,7 @@ module.exports = nextConfig
### Step 5: Create API Route
The product module is ready for use now! You can now use it to create API endpoints within your Next.js application.
The product module is ready for use now! You can now use it to create API routes within your Next.js application.
:::note
@@ -251,11 +251,11 @@ export async function GET(request: Request) {
}
```
This creates a `GET` endpoint at the route `/api/products`. You import the `initialize` function, aliased as `initializeProductModule`, from `@medusajs/product`. Then, in the endpoint, you invoke the `initializeProductModule` function, which returns an instance of the `ProductModuleService`. Using the product module service’s `list` method, you retrieve all available products and return them in the response of the endpoint.
This creates a `GET` API route at the path `/api/products`. You import the `initialize` function, aliased as `initializeProductModule`, from `@medusajs/product`. Then, in the API route, you invoke the `initializeProductModule` function, which returns an instance of the `ProductModuleService`. Using the product module service’s `list` method, you retrieve all available products and return them in the response.
### Step 6: Test Next.js Application
To test the endpoint you added, start your Next.js application with the following command:
To test the API route you added, start your Next.js application with the following command:
```bash npm2yarn
npm run dev
@@ -267,7 +267,7 @@ Then, open in your browser the URL `http://localhost:3000/api/products`. If you
## Example Usages
This section includes some examples of the different functionalities or ways you can use the product module. The code snippets are shown in the context of endpoints.
This section includes some examples of the different functionalities or ways you can use the product module. The code snippets are shown in the context of API routes.
### List Products
www/apps/docs/content/modules/products/storefront/show-products.mdx
+8 -8
View File
@@ -56,7 +56,7 @@ If you follow the `@medusajs/product` code blocks, it's assumed you already have
## List Products
You can list available products using the [List Products endpoint](https://docs.medusajs.com/api/store#products_getproducts):
You can list available products using the [List Products API Route](https://docs.medusajs.com/api/store#products_getproducts):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -143,13 +143,13 @@ curl -L -X GET '<BACKEND_URL>/store/products'
</TabItem>
</Tabs>
This endpoint does not require any parameters. You can pass it parameters related to pagination, filtering, and more as explained in the [API reference](https://docs.medusajs.com/api/store#tag/Products/operation/GetProducts).
This API Route doesn't require any parameters. You can pass it parameters related to pagination, filtering, and more as explained in the [API reference](https://docs.medusajs.com/api/store#tag/Products/operation/GetProducts).
The request returns an array of product objects along with [pagination parameters](https://docs.medusajs.com/api/store#section/Pagination).
### Filtering Retrieved Products
The List Products endpoint accepts different query parameters that allow you to filter through retrieved results.
The List Products API Route accepts different query parameters that allow you to filter through retrieved results.
For example, you can filter products by a category ID:
@@ -588,7 +588,7 @@ The Search functionality requires either installing a [search plugin](../../../p
:::
You can search products using the [Search Products endpoint](https://docs.medusajs.com/api/store#tag/Products/operation/PostProductsSearch):
You can search products using the [Search Products API Route](https://docs.medusajs.com/api/store#tag/Products/operation/PostProductsSearch):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -636,7 +636,7 @@ curl -L -X POST '<BACKEND_URL>/store/products/search?q=Shirt' \
</TabItem>
</Tabs>
This endpoint requires the query parameter `q` being the term to search products for. The search plugin or service you’re using determine how `q` will be used to search the products. It also accepts pagination parameters as explained in the [API reference](https://docs.medusajs.com/api/store#products_postproductssearch).
This API Route requires the query parameter `q` being the term to search products for. The search plugin or service you’re using determine how `q` will be used to search the products. It also accepts pagination parameters as explained in the [API reference](https://docs.medusajs.com/api/store#products_postproductssearch).
The request returns a `hits` array holding the result items. The structure of the items depends on the plugin you’re using.
@@ -644,7 +644,7 @@ The request returns a `hits` array holding the result items. The structure of th
## Retrieve a Product by ID
You can retrieve the details of a single product by its ID using the [Get a Product endpoint](https://docs.medusajs.com/api/store#products_getproductsproduct):
You can retrieve the details of a single product by its ID using the [Get a Product API Route](https://docs.medusajs.com/api/store#products_getproductsproduct):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -726,7 +726,7 @@ curl -L -X GET '<BACKEND_URL>/store/products/<PRODUCT_ID>'
</TabItem>
</Tabs>
This endpoint requires the product’s ID to be passed as a path parameter. You can also pass query parameters such as `cart_id` and `region_id` which are relevant for pricing as explained in the [Product Pricing Parameters section](#product-pricing-parameters). You can check the full list of accepted parameters in the [API reference](https://docs.medusajs.com/api/store#products_getproductsproduct).
This API Route requires the product’s ID to be passed as a path parameter. You can also pass query parameters such as `cart_id` and `region_id` which are relevant for pricing as explained in the [Product Pricing Parameters section](#product-pricing-parameters). You can check the full list of accepted parameters in the [API reference](https://docs.medusajs.com/api/store#products_getproductsproduct).
The request returns a product object. You can display its price as explained in the [Display Product Price](#display-product-price) section.
@@ -738,7 +738,7 @@ You can also retrieve the product's categories by passing the `expand` query par
On the storefront, you may use the handle of a product as its page’s path. For example, instead of displaying the product’s details on the path `/products/prod_123`, you can display it on the path `/products/shirt`, where `shirt` is the handle of the product. This type of URL is human-readable and is good for Search Engine Optimization (SEO)
You can retrieve the details of a product by its handle by sending a request to the List Products endpoint, passing the `handle` as a filter:
You can retrieve the details of a product by its handle by sending a request to the List Products API Route, passing the `handle` as a filter:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/products/storefront/use-categories.mdx
+3 -3
View File
@@ -54,7 +54,7 @@ If you follow the `@medusajs/product` code blocks, it's assumed you already have
## List Categories
You can list product categories by sending a request to the [List Product Categories endpoint](https://docs.medusajs.com/api/store#product-categories_getproductcategories):
You can list product categories by sending a request to the [List Product Categories API Route](https://docs.medusajs.com/api/store#product-categories_getproductcategories):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -160,7 +160,7 @@ By default, the categories are not retrieved along with their nested children. T
## Get a Category by ID
You can retrieve a single product category by its ID using the [Get a Product Category endpoint](https://docs.medusajs.com/api/store#product-categories_getproductcategoriescategory):
You can retrieve a single product category by its ID using the [Get a Product Category API Route](https://docs.medusajs.com/api/store#product-categories_getproductcategoriescategory):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -253,7 +253,7 @@ The request returns the category as an object.
On the storefront, you may use the handle of a category as its page’s path. For example, instead of displaying the category's details on the path `/categories/pcat_123`, you can display it on the path `/categories/women`, where `women` is the handle of the category. This type of URL is human-readable and is good for Search Engine Optimization (SEO)
You can retrieve the details of a category by its handle by sending a request to the List Categories endpoint, passing the `handle` as a filter:
You can retrieve the details of a category by its handle by sending a request to the List Categories API Route, passing the `handle` as a filter:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx
+9 -9
View File
@@ -60,7 +60,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Currencies
You can list all available currencies in your system by sending a request to the [List Currencies endpoint](https://docs.medusajs.com/api/admin#currencies_getcurrencies):
You can list all available currencies in your system by sending a request to the [List Currencies API Route](https://docs.medusajs.com/api/admin#currencies_getcurrencies):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -126,7 +126,7 @@ curl -L -X GET '<BACKEND_URL>/admin/currencies' \
</TabItem>
</Tabs>
This endpoint accepts optional filter and search query parameters. For example, you can pass the `code` query parameter to search the list of currencies by a code. You can learn about available query parameters in the [API reference](https://docs.medusajs.com/api/admin#currencies_getcurrencies).
This API Route accepts optional filter and search query parameters. For example, you can pass the `code` query parameter to search the list of currencies by a code. You can learn about available query parameters in the [API reference](https://docs.medusajs.com/api/admin#currencies_getcurrencies).
This request returns an array of currencies along with pagination parameters.
@@ -134,7 +134,7 @@ This request returns an array of currencies along with pagination parameters.
## Update Currencies
You can update a currency by sending a request to the [Update Currency endpoint](https://docs.medusajs.com/api/admin#currencies_postcurrenciescurrency):
You can update a currency by sending a request to the [Update Currency API Route](https://docs.medusajs.com/api/admin#currencies_postcurrenciescurrency):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -205,7 +205,7 @@ curl -L -X GET '<BACKEND_URL>/admin/currencies/<CODE>' \
</TabItem>
</Tabs>
This endpoint requires the currency code as a path parameter.
This API Route requires the currency code as a path parameter.
In the request body parameter, it accepts the field `includes_tax` which is a boolean value that indicates whether tax inclusion is enabled for the currency. This is only available if you’ve enabled the Tax Inclusive feature.
@@ -225,7 +225,7 @@ This section explains how you can manage the currencies of a store.
### List Currencies in a Store
You can list currencies in a store by sending a request to the [Get Store Details endpoint](https://docs.medusajs.com/api/admin#store_getstore):
You can list currencies in a store by sending a request to the [Get Store Details API Route](https://docs.medusajs.com/api/admin#store_getstore):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -303,7 +303,7 @@ This request returns the store as an object. In that object, there are two prope
### Add Currency to the Store
You can add a currency to a store using the [Add a Currency Code endpoint](https://docs.medusajs.com/api/admin#store_poststorecurrenciescode):
You can add a currency to a store using the [Add a Currency Code API Route](https://docs.medusajs.com/api/admin#store_poststorecurrenciescode):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -360,13 +360,13 @@ curl -L -X POST '<BACKEND_URL>/admin/store/currencies/<CODE>' \
</TabItem>
</Tabs>
This endpoint requires the currency code to be passed as a path parameter.
This API Route requires the currency code to be passed as a path parameter.
The request returns the updated store as an object. You can access the new list of currencies under the `store.currencies` property.
### Delete a Currency from the Store
You can remove a currency from a store by sending a request to the [Delete Currency Code endpoint](https://docs.medusajs.com/api/admin#store_deletestorecurrenciescode):
You can remove a currency from a store by sending a request to the [Delete Currency Code API Route](https://docs.medusajs.com/api/admin#store_deletestorecurrenciescode):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -423,7 +423,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/store/currencies/<CODE>' \
</TabItem>
</Tabs>
This endpoint requires the currency code to be passed as a path parameter.
This API Route requires the currency code to be passed as a path parameter.
The request returns the updated store as an object. You can access the new list of currencies under the `store.currencies` property.
www/apps/docs/content/modules/regions-and-currencies/admin/manage-regions.mdx
+6 -6
View File
@@ -60,7 +60,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Regions
You can retrieve regions available on your backend using the [List Regions](https://docs.medusajs.com/api/admin#regions_getregions) endpoint:
You can retrieve regions available on your backend using the [List Regions API Route](https://docs.medusajs.com/api/admin#regions_getregions):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -134,7 +134,7 @@ You can also pass filters and other selection query parameters to the request. C
## Create a Region
You can create a region by sending a request to the [Create a Region](https://docs.medusajs.com/api/admin#regions_postregions) endpoint:
You can create a region by sending a request to the [Create a Region API Route](https://docs.medusajs.com/api/admin#regions_postregions):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -266,9 +266,9 @@ 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](https://docs.medusajs.com/api/admin#regions_postregionsregioncountries) endpoint.
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 Route](https://docs.medusajs.com/api/admin#regions_postregionsregioncountries).
Alternatively, you can update the details of a region using the [Update a Region](https://docs.medusajs.com/api/admin#regions_postregionsregion) endpoint:
Alternatively, you can update the details of a region using the [Update a 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>
@@ -367,7 +367,7 @@ In the example above, the list of countries replace any countries that were prev
## 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](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions) endpoint:
You can add a shipping option to a region by sending a request to the [Create Shipping Option API Route](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -486,7 +486,7 @@ You can also manage shipping options such as list, update, and delete. You can l
## Delete a Region
You can delete a region by sending a request to the [Delete a Region](https://docs.medusajs.com/api/admin#regions_deleteregionsregion) endpoint:
You can delete a region by sending a request to the [Delete a Region API Route](https://docs.medusajs.com/api/admin#regions_deleteregionsregion):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/regions-and-currencies/storefront/use-regions.mdx
+4 -4
View File
@@ -52,7 +52,7 @@ For requests that use the cart, it's also assumed you already have [used CartPro
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](https://docs.medusajs.com/api/store#regions_getregions) endpoint:
You can retrieve available regions by sending a request to the [List Regions API Route](https://docs.medusajs.com/api/store#regions_getregions):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -119,7 +119,7 @@ When a customer selects a region, you should store that region’s ID. You’ll
## 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](https://docs.medusajs.com/api/store#products_getproducts) or [Get a Product](https://docs.medusajs.com/api/store#products_getproductsproduct) endpoints.
To retrieve products with the prices based on the selected regions, you can pass the `region_id` query parameter to the [List Products](https://docs.medusajs.com/api/store#products_getproducts) or [Get a Product](https://docs.medusajs.com/api/store#products_getproductsproduct) API Routes.
For example:
@@ -176,7 +176,7 @@ fetch(`<BACKEND_URL>/store/products?region_id=${regionId}`, {
</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`.
In this example, you send a request to the List Products API Route, 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](https://docs.medusajs.com/api/store#pagination). The prices of the products are based on the selected region.
@@ -251,6 +251,6 @@ fetch(`<BACKEND_URL>/store/carts/${cartId}`, {
</TabItem>
</Tabs>
In this example, you send a request to the [Update Cart](https://docs.medusajs.com/api/store#carts_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`.
In this example, you send a request to the [Update Cart API Route](https://docs.medusajs.com/api/store#carts_postcartscart). 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.
www/apps/docs/content/modules/sales-channels/admin/manage.mdx
+9 -9
View File
@@ -52,7 +52,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## Create Sales Channels
You can create a sales channel by sending a request to the Create a Sales Channel endpoint:
You can create a sales channel by sending a request to the Create a Sales Channel API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -135,7 +135,7 @@ It returns the created sales channel.
## List Sales Channels
You can list all sales channels by sending a request to the List Sales Channels endpoint:
You can list all sales channels by sending a request to the List Sales Channels API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -207,7 +207,7 @@ This request returns an array of all sales channels in your store. You can also
## Retrieve a Sales Channel
You can retrieve a sales channel’s details by its ID using the Get Sales Channel endpoint:
You can retrieve a sales channel’s details by its ID using the Get Sales Channel API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -272,7 +272,7 @@ This request returns the sales channel with the specified ID.
## Update a Sales Channel
You can update a Sales Channel’s details and attributes by sending a request to the Update Sales Channel endpoint:
You can update a Sales Channel’s details and attributes by sending a request to the Update Sales Channel API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -355,7 +355,7 @@ You can check out [the API Reference for a full list of body parameters](https:/
## Delete a Sales Channel
You can delete a sales channel by sending a request to the Delete Sales Channel endpoint with the ID of the sales channel to delete:
You can delete a sales channel by sending a request to the Delete Sales Channel API Route with the ID of the sales channel to delete:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -422,7 +422,7 @@ The ID of the deleted sales channel is returned in the response.
### Add Product to a Sales Channel
To add a product to a sales channel, send a request to the Sales Channel’s Add Products endpoint:
To add a product to a sales channel, send a request to the Sales Channel’s Add Products API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -522,7 +522,7 @@ This request returns the sales channel.
### List Products Available in a Sales Channel
You can list the products available in a sales channel by sending a request to the List Products endpoint and passing the `sales_channel_id` query parameter to filter by a specific sales channel:
You can list the products available in a sales channel by sending a request to the List Products API Route and passing the `sales_channel_id` query parameter to filter by a specific sales channel:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -614,7 +614,7 @@ Deleting a product from a sales channel doesn't delete it completely. It only ma
:::
You can delete a product from a sales channel by sending a request to the Sales Channel’s Delete Products endpoint:
You can delete a product from a sales channel by sending a request to the Sales Channel’s Delete Products API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -720,7 +720,7 @@ This request returns the sales channel.
## List Orders by Sales Channels
You can filter orders by a specific sales channel by sending a request to the List Orders endpoint and passing the `sales_channel_id` query parameter to filter by a specific sales channel:
You can filter orders by a specific sales channel by sending a request to the List Orders API Route and passing the `sales_channel_id` query parameter to filter by a specific sales channel:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/sales-channels/storefront/use-sales-channels.mdx
+1 -1
View File
@@ -53,7 +53,7 @@ For requests that use the cart, it's also assumed you already have [used CartPro
## Filter Products by Sales Channel
To filter products by a specific sales channel, pass the `sales_channel_id` query parameter to the List Products endpoint:
To filter products by a specific sales channel, pass the `sales_channel_id` query parameter to the List Products API Route:
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
www/apps/docs/content/modules/taxes/admin/manage-tax-rates.mdx
+22 -22
View File
@@ -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&region_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:
www/apps/docs/content/modules/taxes/admin/manage-tax-settings.mdx
+6 -6
View File
@@ -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>
www/apps/docs/content/modules/taxes/backend/create-tax-provider.md
+1 -1
View File
@@ -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.
www/apps/docs/content/modules/taxes/inclusive-pricing.md
+2 -2
View File
@@ -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
www/apps/docs/content/modules/taxes/storefront/manual-calculation.md
+24 -19
View File
@@ -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,
www/apps/docs/content/modules/taxes/taxes.md
+1 -1
View File
@@ -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.
---
www/apps/docs/content/modules/users/admin/manage-invites.mdx
+13 -13
View File
@@ -46,7 +46,7 @@ If you follow the Medusa React code blocks, it's assumed you already have [Medus
### Authenticated Admin User
Except for the Accept Invite endpoint, you must be an authenticated admin user before following along with the steps in the tutorial.
Except for the Accept Invite API Route, 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](https://docs.medusajs.com/api/admin#authentication).
@@ -54,7 +54,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Invites
You can list invites by sending a request to the [List Invite endpoint](https://docs.medusajs.com/api/admin#invites_getinvites):
You can list invites by sending a request to the [List Invite API Route](https://docs.medusajs.com/api/admin#invites_getinvites):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -117,15 +117,15 @@ curl -L -X GET '<BACKEND_URL>/admin/invites' \
</TabItem>
</Tabs>
This endpoint does not accept any parameters.
This API Route doesn't accept any parameters.
The request returns an array of invite endpoints.
The request returns an array of invite objects.
---
## Create Invite
You can create an invite by sending a request to the [Create Invite endpoint](https://docs.medusajs.com/api/admin#invites_postinvites):
You can create an invite by sending a request to the [Create Invite API Route](https://docs.medusajs.com/api/admin#invites_postinvites):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -200,7 +200,7 @@ curl -L -X POST '<BACKEND_URL>/admin/invites' \
</TabItem>
</Tabs>
This endpoint requires the following body parameters:
This API Route requires the following body parameters:
- `user`: a string indicating the email of the user.
- `role`: a string indicating the role of the user. Its values can be `admin`, `member`, and `developer`.
@@ -213,7 +213,7 @@ The request does not return any data. If the invite was created successfully, th
A logged-out user can accept an invite, which would create a user for that user.
You can accept an invite by sending a request to the [Accept Invite endpoint](https://docs.medusajs.com/api/admin#invites_postinvitesinviteaccept):
You can accept an invite by sending a request to the [Accept Invite API Route](https://docs.medusajs.com/api/admin#invites_postinvitesinviteaccept):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -303,7 +303,7 @@ curl -L -X POST '<BACKEND_URL>/admin/invites/accept' \
</TabItem>
</Tabs>
This endpoint requires the following request body parameters:
This API Route requires the following request body parameters:
- `token`: a string indicating the invitation’s token.
- `user`: an object that has the following properties:
@@ -317,7 +317,7 @@ The request does not return any data. If the invite was accepted successfully, t
## Resend an Invite
You can resend an invite if it’s not accepted yet. To resend an invite, send a request to the [Resend Invite endpoint](https://docs.medusajs.com/api/admin#invites_postinvitesinviteresend):
You can resend an invite if it’s not accepted yet. To resend an invite, send a request to the [Resend Invite API Route](https://docs.medusajs.com/api/admin#invites_postinvitesinviteresend):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -374,15 +374,15 @@ curl -L -X POST '<BACKEND_URL>/admin/invites/<INVITE_ID>/resend' \
</TabItem>
</Tabs>
This endpoint requires the invite ID as a path parameter.
This API Route requires the invite ID as a path parameter.
The request does not return any data. If the invite was resent successfully, the status code of the response will be `200`.
The request doesn't return any data. If the invite was resent successfully, the status code of the response will be `200`.
---
## Delete an Invite
You can delete an invite by sending a request to the [Delete Invite endpoint](https://docs.medusajs.com/api/admin#invites_deleteinvitesinvite):
You can delete an invite by sending a request to the [Delete Invite API Route](https://docs.medusajs.com/api/admin#invites_deleteinvitesinvite):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -439,7 +439,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/invites/<INVITE_ID>' \
</TabItem>
</Tabs>
This endpoint requires the invite ID as a path parameter.
This API Route requires the invite ID as a path parameter.
It deletes the invite and returns the following fields:
www/apps/docs/content/modules/users/admin/manage-profile.mdx
+14 -14
View File
@@ -42,7 +42,7 @@ If you follow the Medusa React code blocks, it's assumed you already have [Medus
### Authenticated Admin User
Aside from the User Login and Reset Password steps, other endpoints require you to be an authenticated admin user.
Aside from the User Login and Reset Password steps, other API Routes require you to be an authenticated admin user.
You can learn more about [authenticating as an admin user in the API reference](https://docs.medusajs.com/api/admin#authentication).
@@ -52,7 +52,7 @@ You can learn more about [authenticating as an admin user in the API reference](
### User Login
You can log in a user by sending a request to the [User Login endpoint](https://docs.medusajs.com/api/admin#auth_postauth):
You can log in a user by sending a request to the [User Login API Route](https://docs.medusajs.com/api/admin#auth_postauth):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -126,7 +126,7 @@ curl -L -X POST '<BACKEND_URL>/admin/auth' \
</TabItem>
</Tabs>
This endpoint requires the following request body parameters:
This API Route requires the following request body parameters:
- `email`: a string indicating the user’s email.
- `password`: a string indicating the user’s password.
@@ -135,7 +135,7 @@ The request returns the logged-in user as an object.
### User Logout
You can log out a user by sending a request to the [User Logout endpoint](https://docs.medusajs.com/api/admin#auth_deleteauth):
You can log out a user by sending a request to the [User Logout API Route](https://docs.medusajs.com/api/admin#auth_deleteauth):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -192,15 +192,15 @@ curl -L -X DELETE '<BACKEND_URL>/admin/auth' \
</TabItem>
</Tabs>
The endpoint does not require any path or query parameters.
The API Route doesn't require any path or query parameters.
The request does not return any data. The response code will be `200` for successful log out.
The request doesn't return any data. The response code will be `200` for successful log out.
---
## Retrieve User Profile Details
You can retrieve the current user’s details for their profile by sending a request to the [Get Current User endpoint](https://docs.medusajs.com/api/admin#auth_getauth):
You can retrieve the current user’s details for their profile by sending a request to the [Get Current User API Route](https://docs.medusajs.com/api/admin#auth_getauth):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -256,7 +256,7 @@ curl -L -X GET '<BACKEND_URL>/admin/auth' \
</TabItem>
</Tabs>
This endpoint does not require any parameters.
This API Route doesn't require any parameters.
The request returns the current user as an object.
@@ -264,7 +264,7 @@ The request returns the current user as an object.
## Update User’s Profile Details
You can update a user’s details in their profile by sending a request to the [Update User endpoint](https://docs.medusajs.com/api/admin#users_postusersuser):
You can update a user’s details in their profile by sending a request to the [Update User API Route](https://docs.medusajs.com/api/admin#users_postusersuser):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -338,7 +338,7 @@ curl -L -X POST '<BACKEND_URL>/admin/users/<USER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the ID of the user as a path parameter.
This API Route requires the ID of the user as a path parameter.
In the request body, you can pass any of the user’s fields that you want to update as a parameter. In the example above, you pass the `first_name` parameter to update the user’s first name. You can refer to the [API reference](https://docs.medusajs.com/api/admin#users_postusersuser) to learn about other available parameters.
@@ -360,7 +360,7 @@ Sending the password reset email is not handled by default in the Medusa backend
:::
You can request a password reset by sending a request to the [Request Password Reset endpoint](https://docs.medusajs.com/api/admin#users_postusersuserpasswordtoken):
You can request a password reset by sending a request to the [Request Password Reset API Route](https://docs.medusajs.com/api/admin#users_postusersuserpasswordtoken):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -430,7 +430,7 @@ curl -L -X POST '<BACKEND_URL>/admin/users/password-token' \
</TabItem>
</Tabs>
This endpoint requires the `email` parameter in the request body, which is the email of the user requesting to reset their password.
This API Route requires the `email` parameter in the request body, which is the email of the user requesting to reset their password.
The request does not return any data. The response code will be `204` if the request was processed successfully.
@@ -438,7 +438,7 @@ The request does not return any data. The response code will be `204` if the req
After the user resets their password and, typically, receives an email with a link to reset their password, they should enter their new password. The new password, along with the token passed to this page are used to reset the password on the Medusa backend.
You can reset the password by sending a request to the [Reset Password endpoint](https://docs.medusajs.com/api/admin#users_postusersuserpassword):
You can reset the password by sending a request to the [Reset Password API Route](https://docs.medusajs.com/api/admin#users_postusersuserpassword):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -512,7 +512,7 @@ curl -L -X POST '<BACKEND_URL>/admin/users/reset-password' \
</TabItem>
</Tabs>
This endpoint requires the following request body parameters:
This API Route requires the following request body parameters:
- `token`: a string indicating the password reset token.
- `password`: a string indicating the new password for the user.
www/apps/docs/content/modules/users/admin/manage-users.mdx
+9 -9
View File
@@ -53,7 +53,7 @@ You can learn more about [authenticating as an admin user in the API reference](
## List Users
You can retrieve users in a store by sending a request to the [List Users endpoint](https://docs.medusajs.com/api/admin#users_getusers):
You can retrieve users in a store by sending a request to the [List Users API Route](https://docs.medusajs.com/api/admin#users_getusers):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -116,7 +116,7 @@ curl -L -X GET '<BACKEND_URL>/admin/users' \
</TabItem>
</Tabs>
This endpoint does not require any parameters.
This API Route doesn't require any parameters.
The request returns an array of user objects.
@@ -124,7 +124,7 @@ The request returns an array of user objects.
## Create a User
You can create a user by sending a request to the [Create User endpoint](https://docs.medusajs.com/api/admin#users_postusers):
You can create a user by sending a request to the [Create User API Route](https://docs.medusajs.com/api/admin#users_postusers):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -199,12 +199,12 @@ curl -L -X POST '<BACKEND_URL>/admin/users' \
</TabItem>
</Tabs>
This endpoint requires the following request body parameters:
This API Route requires the following request body parameters:
- `email`: a string indicating the email of the user.
- `password`: a string indicating the password of the user.
The endpoint accepts other optional body parameters, such as first name or last name. Check the [API reference](https://docs.medusajs.com/api/admin#users_postusers) for details on optional body parameters.
The API Route accepts other optional body parameters, such as first name or last name. Check the [API reference](https://docs.medusajs.com/api/admin#users_postusers) for details on optional body parameters.
The request returns the created user as an object.
@@ -212,7 +212,7 @@ The request returns the created user as an object.
## Update User
You can update a user’s details by sending a request to the [Update User endpoint](https://docs.medusajs.com/api/admin#users_postusersuser):
You can update a user’s details by sending a request to the [Update User API Route](https://docs.medusajs.com/api/admin#users_postusersuser):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -283,7 +283,7 @@ curl -L -X POST '<BACKEND_URL>/admin/users/<USER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the ID of the user as a path parameter.
This API Route requires the ID of the user as a path parameter.
In the request body, you can pass any of the user’s fields that you want to update as parameters. In the example above, you update the user’s `first_name`. Check the [API reference](https://docs.medusajs.com/api/admin#users_postusersuser) for all the optional parameters.
@@ -293,7 +293,7 @@ The request returns the updated user as an object.
## Delete a User
You can delete a user by sending a request to the [Delete User endpoint](https://docs.medusajs.com/api/admin#users_deleteusersuser):
You can delete a user by sending a request to the [Delete User API Route](https://docs.medusajs.com/api/admin#users_deleteusersuser):
<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>
@@ -350,7 +350,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/users/<USER_ID>' \
</TabItem>
</Tabs>
This endpoint requires the user ID as a path parameter.
This API Route requires the user ID as a path parameter.
It deletes the user and returns the following fields:
www/apps/docs/content/modules/users/backend/rbac.mdx
+78 -103
View File
@@ -333,13 +333,13 @@ This will reflect the entity changes in your database.
## Create Guard Middleware
To ensure that users who have the privilege can access an endpoint, you must create a middleware that guards admin routes. This middleware will run on all authenticated admin requests to ensure that only allowed users can access an endpoint.
To ensure that users who have the privilege can access an API Route, you must create a middleware that guards admin routes. This middleware will run on all authenticated admin requests to ensure that only allowed users can access an API Route.
Since the Medusa backend uses Express, you can create a middleware and attach it to all admin routes.
<DocCard item={{
type: 'link',
href: '/development/endpoints/add-middleware',
href: '/development/api-routes/add-middleware',
label: 'Create a Middleware',
customProps: {
icon: Icons['academic-cap-solid'],
@@ -350,18 +350,26 @@ Since the Medusa backend uses Express, you can create a middleware and attach it
<details>
<summary>Example Implementation</summary>
In this example, you’ll create a middleware that runs on all admin-authenticated routes and checks the logged-in user’s permissions before giving them access to an endpoint.
In this example, you’ll create a middleware that runs on all admin-authenticated routes and checks the logged-in user’s permissions before giving them access to an API Route.
Create the file `src/api/middlewares/permission.ts` with the following content:
Create the file `src/api/middlewares.ts` with the following content:
```ts title=src/api/middlewares/permission.ts
import { UserService } from "@medusajs/medusa"
import { NextFunction, Request, Response } from "express"
```ts title=src/api/middlewares.ts
import type {
MiddlewaresConfig,
UserService,
} from "@medusajs/medusa"
import express from "express"
import type {
MedusaRequest,
MedusaResponse,
MedusaNextFunction,
} from "@medusajs/medusa"
export default async (
req: Request,
res: Response,
next: NextFunction
export const permissions = async (
req: MedusaRequest,
res: MedusaResponse,
next: MedusaNextFunction
) => {
if (!req.user || !req.user.userId) {
next()
@@ -406,48 +414,38 @@ export default async (
// deny access
res.sendStatus(401)
}
export const config: MiddlewaresConfig = {
routes: [
{
matcher: "/admin/*",
middlewares: [permissions],
},
],
}
```
In this middleware, you ensure that there is a logged-in user and the logged-in user has a role. If not, the user is admitted to access the endpoint. Here, you presume that logged-in users who don’t have a role are “super-admin” users who can access all endpoints. You may choose to implement this differently.
In this middleware, you ensure that there is a logged-in user and the logged-in user has a role. If not, the user is admitted to access the API Route. Here, you presume that logged-in users who don’t have a role are “super-admin” users who can access all API Routes. You may choose to implement this differently.
If there’s a logged-in user that has a role, you check that the role’s permissions give them access to the current endpoint. You do that by checking if a permission’s metadata has a key with the same request’s path. It may be better here to check for matching using regular expressions, for example, to check routes with path parameters.
If there’s a logged-in user that has a role, you check that the role’s permissions give them access to the current API Route. You do that by checking if a permission’s metadata has a key with the same request’s path. It may be better here to check for matching using regular expressions, for example, to check routes with path parameters.
Otherwise, if the user’s role doesn’t provide them with enough permissions, you return a `401` response code.
:::tip
Notice that you use `req.path` here to get the current endpoint path. However, in middlewares, this doesn’t include the mount point which is `/admin`. So, for example, if the endpoint path is `/admin/products`, `req.path` will be `/products`. You can alternatively use `req.originalUrl`. Learn more in [Express’s documentation](https://expressjs.com/en/api.html#req.originalUrl).
Notice that you use `req.path` here to get the current API Route path. However, in middlewares, this doesn’t include the mount point which is `/admin`. So, for example, if the API Route path is `/admin/products`, `req.path` will be `/products`. You can alternatively use `req.originalUrl`. Learn more in [Express’s documentation](https://expressjs.com/en/api.html#req.originalUrl).
:::
Next, to ensure that this middleware is used, import it in `src/api/index.ts` and apply it on admin routes:
```ts title=src/api/index.ts
import permissionMiddleware from "./middlewares/permission"
export default (rootDirectory: string): Router | Router[] => {
// ...
const router = Router()
// ...
// use middleware on admin routes
router.use("/admin", permissionMiddleware)
return router
}
```
This assumes you already have a router with all necessary CORS configurations and body parsing middlewares. If not, you can refer to the [Create Endpoint documentation](../../../development/endpoints/create.mdx) for more details.
Make sure to use the permission middleware after all router configurations if you want the middleware to work on your custom admin routes.
After defining the middleware, you apply it on all API Routes starting with `/admin/`.
</details>
---
## Create Endpoints and Services
## Create API Routes and Services
To manage the roles and permissions, you’ll need to create custom endpoints, typically for Create, Read, Update, and Delete (CRUD) operations.
To manage the roles and permissions, you’ll need to create custom API Routes, typically for Create, Read, Update, and Delete (CRUD) operations.
You’ll also need to create a service for each of `Role` and `Permission` entities to perform these operations on them. The entity uses the service within its code.
@@ -456,11 +454,11 @@ Furthermore, you may need to extend core services if you need to perform actions
<DocCardList colSize={4} items={[
{
type: 'link',
href: '/development/endpoints/create',
label: 'Create Endpoint',
href: '/development/api-routes/create',
label: 'Create API Route',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create an endpoint in Medusa.',
description: 'Learn how to create an API Route in Medusa.',
}
},
{
@@ -488,9 +486,9 @@ Furthermore, you may need to extend core services if you need to perform actions
Example Implementation
</summary>
In this example, you’ll only implement two endpoints for simplicity: create role endpoint that create a new role with permissions, and associate user endpoint that associates a user with a role.
In this example, you’ll only implement two API Routes for simplicity: create role API Route that create a new role with permissions, and associate user API Route that associates a user with a role.
You’ll also create basic services for `Role` and `Permission` to perform the functionalities of each of these endpoints and extend the core `UserService` to allow associating roles with users.
You’ll also create basic services for `Role` and `Permission` to perform the functionalities of each of these API Routes and extend the core `UserService` to allow associating roles with users.
Start by creating the file `src/services/permission.ts` with the following content:
@@ -663,15 +661,21 @@ This creates the `RoleService` with three methods:
- `create`: Creates a new role and, if provided, its permissions as well.
- `associateUser`: associates a user with a role.
Now, you can create the endpoints.
Now, you can create the API Routes.
Start by creating the file `src/api/routes/admin/role/create-role.ts` with the following content:
Start by creating the file `src/api/admin/roles/route.ts` with the following content:
```ts title=src/api/routes/admin/role/create-role.ts
import { Request, Response } from "express"
```ts title=src/api/admin/roles/route.ts
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/medusa"
import RoleService from "../../../../services/role"
export default async (req: Request, res: Response) => {
export const POST = async (
req: MedusaRequest,
res: MedusaResponse
) => {
// omitting validation for simplicity
const {
name,
@@ -693,15 +697,21 @@ export default async (req: Request, res: Response) => {
}
```
This creates the Create Role endpoint that uses the `RoleService` to create a new role. Notice that validation of received body parameters is omitted for simplicity.
This creates the Create Role API Route at `/admin/roles` that uses the `RoleService` to create a new role. Notice that validation of received body parameters is omitted for simplicity.
Next, create the file `src/api/routes/admin/role/associate-user.ts` with the following content:
Next, create the file `src/api/routes/admin/roles/[id]/user/[user_id]/route.ts` with the following content:
```ts title=src/api/routes/admin/role/associate-user.ts
import { Request, Response } from "express"
```ts title=src/api/routes/admin/roles/[id]/user/[user_id]/route.ts
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/medusa"
import RoleService from "../../../../services/role"
export default async (req: Request, res: Response) => {
export const POST = async (
req: MedusaRequest,
res: MedusaResponse
) => {
// omitting validation for simplicity purposes
const {
id,
@@ -717,44 +727,9 @@ export default async (req: Request, res: Response) => {
}
```
This creates the Associate User endpoint that uses the `RoleService` to associate a role with a user.
This creates the Associate User API Route at `/admin/roles/[id]/user/[user_id]` that uses the `RoleService` to associate a role with a user.
You now have to register and export these endpoints.
To do that, create the file `src/api/routes/admin/role/index.ts` with the following content:
```ts title=src/api/routes/admin/role/index.ts
import { wrapHandler } from "@medusajs/utils"
import { Router } from "express"
import createRole from "./create-role"
import associateUser from "./associate-user"
const router = Router()
export default (adminRouter: Router) => {
adminRouter.use("/roles", router)
router.post("/", wrapHandler(createRole))
router.post("/:id/user/:user_id", wrapHandler(associateUser))
}
```
This adds the create role endpoint under the path `/admin/roles`, and the associate user endpoint under the path `/admin/roles/:id/user/:user_id`, where `:id` is the ID of the role and `:user_id` is the ID of the user to associate with the role.
Finally, you can either export these routes in `src/api/routes/admin/index.ts` or, if the file is not available in your project, in `src/api/index.ts`:
```ts title=src/api/routes/admin/index.ts
import roleRouter from "./role"
const router = Router()
export function attachAdminRoutes(adminRouter: Router) {
roleRouter(adminRouter)
// ....
}
```
To test it out, run the `build` command in the root directory of your Medusa backend project:
To test the API Routes out, run the `build` command in the root directory of your Medusa backend project:
```bash npm2yarn
npm run build
@@ -766,30 +741,30 @@ Then, start the backend with the following command:
npx medusa develop
```
Try first to log in using the [Admin User Login endpoint](https://docs.medusajs.com/api/admin#auth_postauth) with an existing admin user. Then, send a `POST` request to the `localhost:9000/admin/roles` endpoint with the following request body parameters:
Try first to log in using the [Admin User Login API Route](https://docs.medusajs.com/api/admin#auth_postauth) with an existing admin user. Then, send a `POST` request to the `localhost:9000/admin/roles` API Route with the following request body parameters:
```json
{
"store_id": "store_01H8XPDY8WA1Z650MZSEY4Y0V0",
"name": "Product Manager",
"permissions": [
{
"name": "Allow Products",
"metadata": {
"/products": true
}
}
]
"store_id": "store_01H8XPDY8WA1Z650MZSEY4Y0V0",
"name": "Product Manager",
"permissions": [
{
"name": "Allow Products",
"metadata": {
"/products": true
}
}
]
}
```
Make sure to replace the `store_id`'s value with your store’s ID. You can retrieve the store’s ID using the [Get Store Details endpoint](https://docs.medusajs.com/api/admin#store_getstore).
Make sure to replace the `store_id`'s value with your store’s ID. You can retrieve the store’s ID using the [Get Store Details API Route](https://docs.medusajs.com/api/admin#store_getstore).
This will create a new role with a permission that allows users of this role to access the `/admin/products` endpoint. As mentioned before, because of the middleware’s implementation, you must specify the path without the `/admin` prefix. If you chose to implement this differently, such as with regular expressions, then change the permission’s metadata accordingly.
This will create a new role with a permission that allows users of this role to access the `/admin/products` API Route. As mentioned before, because of the middleware’s implementation, you must specify the path without the `/admin` prefix. If you chose to implement this differently, such as with regular expressions, then change the permission’s metadata accordingly.
Next, create a new user using the [Create User endpoint](https://docs.medusajs.com/api/admin#users_postusers). Then, send a `POST` request to `localhost:9000/admin/roles/<role_id>/user/<user_id>`, where `<role_id>` is the ID of the role you created, and `<user_id>` is the ID of the user you created. This will associate the user with the role you created.
Next, create a new user using the [Create User API Route](https://docs.medusajs.com/api/admin#users_postusers). Then, send a `POST` request to `localhost:9000/admin/roles/<role_id>/user/<user_id>`, where `<role_id>` is the ID of the role you created, and `<user_id>` is the ID of the user you created. This will associate the user with the role you created.
Finally, login with the user you created, then try to access any endpoint other than `/admin/products`. You’ll receive a `401` unauthorized response. Then, try to access the [List Products endpoint](https://docs.medusajs.com/api/admin#products_getproducts), and the user should be able to access it as expected.
Finally, login with the user you created, then try to access any API Route other than `/admin/products`. You’ll receive a `401` unauthorized response. Then, try to access the [List Products API Route](https://docs.medusajs.com/api/admin#products_getproducts), and the user should be able to access it as expected.
</details>
www/apps/docs/content/modules/users/users.md
+4 -4
View File
@@ -26,7 +26,7 @@ Some of the `User` entity attributes include:
- `password_hash`: a string indicating the encrypted password of the user. Passwords are encrypted using the [scrypt-kdf NPM package](https://www.npmjs.com/package/scrypt-kdf). The password hash is nullable, which can be useful if you want to integrate a third-party authentication service that does not require a password.
- `first_name`: a string indicating the user’s first name.
- `last_name`: a string indicating the user’s last name.
- `api_token`: a string that holds the user’s API token. The API token can be used to send authenticated requests to admin endpoints, instead of using cookie session authentication. Check out the [API reference](https://docs.medusajs.com/api/admin#authentication) to learn how to use it.
- `api_token`: a string that holds the user’s API token. The API token can be used to send authenticated requests to admin API Routes, instead of using cookie session authentication. Check out the [API reference](https://docs.medusajs.com/api/admin#authentication) to learn how to use it.
- `role`: a string that indicates the role of the user. Its value can be either `admin`, `member`, or `developer`.
:::note
@@ -61,11 +61,11 @@ You have full freedom in how you choose to implement the invite flow. This secti
The invitation process typically follows these steps in the Medusa backend:
1. A user creates an invite either using the [Create Invite endpoint](https://docs.medusajs.com/api/admin#invites_postinvites) or the `InviteService`'s `create` method. Part of creating an invite includes generating the token and setting the expiry date. By default, the expiry date is set to a week after the date of invitation creation.
2. The new user receives the invite, typically through their email (although this is not implemented by default within the Medusa backend). The new user has to provide their details and password. The invite can be accepted either using the [Accept Invite endpoint](https://docs.medusajs.com/api/admin#invites_postinvitesinviteaccept) or using the `InviteService`'s `accept` method.
1. A user creates an invite either using the [Create Invite API Route](https://docs.medusajs.com/api/admin#invites_postinvites) or the `InviteService`'s `create` method. Part of creating an invite includes generating the token and setting the expiry date. By default, the expiry date is set to a week after the date of invitation creation.
2. The new user receives the invite, typically through their email (although this is not implemented by default within the Medusa backend). The new user has to provide their details and password. The invite can be accepted either using the [Accept Invite API Route](https://docs.medusajs.com/api/admin#invites_postinvitesinviteaccept) or using the `InviteService`'s `accept` method.
3. When the new user accepts the invite, the invitation is validated first to ensure it’s not expired. If it’s not expired, a new user is created using the `UserService`'s [create method](../../references/services/classes/UserService.md#create).
If an invitation is expired, an existing user can resend the invite either using the Resend Invite endpoint or using the `InviteService`'s resend method. This would generate a new token and reset the expiry date.
If an invitation is expired, an existing user can resend the invite either using the Resend Invite API Route or using the `InviteService`'s resend method. This would generate a new token and reset the expiry date.
---