docs: enhance how references are generated (#5805)
* adjusted configurations * enhancements to tool and configurations * change reference in docs * fixed issue in workflows reference * added project name * more optimizations * fix context error * added a types reference * resolved missing types * fix reference reflection types not having children * add an expand url parameter * added new option to the README * added details about new option
This commit is contained in:
Shahed Nasser
GitHub
@@ -26,13 +26,13 @@ A cart is represented by the `Cart` entity. Some of the `Cart` entity’s attrib
|
||||
- `completed_at`: the date the cart was completed. A completed cart means that it has been used for its main purpose. For example, if the cart is used to place an order, then a completed cart means that the order was placed.
|
||||
- `payment_authorized_at`: the date a payment was authorized.
|
||||
|
||||
There are other important attributes discussed in later sections. Check out the [full Cart entity in the entities reference](../../references/entities/classes/Cart.mdx).
|
||||
There are other important attributes discussed in later sections. Check out the [full Cart entity in the entities reference](../../references/entities/classes/entities.Cart.mdx).
|
||||
|
||||
---
|
||||
|
||||
## Cart Totals Calculation
|
||||
|
||||
By default, the `Cart` entity doesn’t hold any details regarding the totals. These are computed and added to the cart instance using the `CartService`'s [decorateTotals method](../../references/services/classes/CartService.mdx#decoratetotals). There's also a dedicated method in the `CartService`, [retrieveWithTotals](../../references/services/classes/CartService.mdx#retrieveWithTotals), attaching the totals automatically. It is recommended to use this method by default when you need to retrieve the cart.
|
||||
By default, the `Cart` entity doesn’t hold any details regarding the totals. These are computed and added to the cart instance using the `CartService`'s [decorateTotals method](../../references/services/classes/services.CartService.mdx#decoratetotals). There's also a dedicated method in the `CartService`, [retrieveWithTotals](../../references/services/classes/services.CartService.mdx#retrieveWithTotals), attaching the totals automatically. It is recommended to use this method by default when you need to retrieve the cart.
|
||||
|
||||
The cart’s totals are calculated based on the content and context of the cart. This includes the selected region, whether tax-inclusive pricing is enabled, the chosen shipping methods, and more.
|
||||
|
||||
@@ -83,11 +83,11 @@ You can learn how to override the cart completion strategy [here](./backend/cart
|
||||
|
||||
The process is implemented as follows:
|
||||
|
||||
1. When the idempotency key’s recovery point is set to `started`, the tax lines are created for the items in the cart. This is done using the `CartService`'s [createTaxLines method](../../references/services/classes/CartService.mdx#createtaxlines). If that is completed with no errors, the recovery point is set to `tax_lines_created` and the process continues.
|
||||
2. When the idempotency key’s recovery point is set to `tax_lines_created`, the payment is authorized using the `CartService`'s method [authorizePayment](../../references/services/classes/CartService.mdx#authorizepayment). If the payment requires more action or is pending authorization, then the tax lines that were created in the previous steps are deleted and the cart completion process is terminated. Once the payment is authorized, the process can be restarted.
|
||||
3. When the idempotency key’s recovery point is set to `payment_authorized`, tax lines are created again the same way as the first step. Then, the inventory of each of the items in the cart is confirmed using the `ProductVariantInventoryService`'s method [confirmInventory](../../references/services/classes/ProductVariantInventoryService.mdx#confirminventory). If an item is in stock, the quantity is reserved using the `ProductVariantInventoryService`'s method [reserveQuantity](../../references/services/classes/ProductVariantInventoryService.mdx#reservequantity). If an item is out of stock, any item reservations that were created are deleted, the payment is canceled, and an error is thrown, terminating the cart completion process. If all item quantities are confirmed to be available:
|
||||
1. If the cart belongs to a swap (the `type` attribute is set to `swap`), the swap is registered as completed using the `SwapService`'s [registerCartCompletion method](../../references/services/classes/SwapService.mdx#registercartcompletion) and the inventory item reservations are removed using the Inventory module. The process ends successfully here for a swap.
|
||||
2. If the cart belongs to an order, the order is created using the `OrderService`'s method [createFromCart](../../references/services/classes/OrderService.mdx#createfromcart). The order is then retrieved and sent in the response.
|
||||
1. When the idempotency key’s recovery point is set to `started`, the tax lines are created for the items in the cart. This is done using the `CartService`'s [createTaxLines method](../../references/services/classes/services.CartService.mdx#createtaxlines). If that is completed with no errors, the recovery point is set to `tax_lines_created` and the process continues.
|
||||
2. When the idempotency key’s recovery point is set to `tax_lines_created`, the payment is authorized using the `CartService`'s method [authorizePayment](../../references/services/classes/services.CartService.mdx#authorizepayment). If the payment requires more action or is pending authorization, then the tax lines that were created in the previous steps are deleted and the cart completion process is terminated. Once the payment is authorized, the process can be restarted.
|
||||
3. When the idempotency key’s recovery point is set to `payment_authorized`, tax lines are created again the same way as the first step. Then, the inventory of each of the items in the cart is confirmed using the `ProductVariantInventoryService`'s method [confirmInventory](../../references/services/classes/services.ProductVariantInventoryService.mdx#confirminventory). If an item is in stock, the quantity is reserved using the `ProductVariantInventoryService`'s method [reserveQuantity](../../references/services/classes/services.ProductVariantInventoryService.mdx#reservequantity). If an item is out of stock, any item reservations that were created are deleted, the payment is canceled, and an error is thrown, terminating the cart completion process. If all item quantities are confirmed to be available:
|
||||
1. If the cart belongs to a swap (the `type` attribute is set to `swap`), the swap is registered as completed using the `SwapService`'s [registerCartCompletion method](../../references/services/classes/services.SwapService.mdx#registercartcompletion) and the inventory item reservations are removed using the Inventory module. The process ends successfully here for a swap.
|
||||
2. If the cart belongs to an order, the order is created using the `OrderService`'s method [createFromCart](../../references/services/classes/services.OrderService.mdx#createfromcart). The order is then retrieved and sent in the response.
|
||||
4. Once the process detailed above is done, the idempotency key’s recovery point is set to `finished`.
|
||||
|
||||
---
|
||||
|
||||
@@ -58,7 +58,7 @@ It’s important to enable a payment processor in a region, or else the payment
|
||||
|
||||
### PaymentProvider Entity Overview
|
||||
|
||||
The [`PaymentProvider`](../../references/entities/classes/PaymentProvider.mdx) entity only has 2 attributes: `is_installed` which is a boolean value indicating whether the Payment Processor is installed; and `id` which is the unique identifier that you define in the Payment Processor service.
|
||||
The [`PaymentProvider`](../../references/entities/classes/entities.PaymentProvider.mdx) entity only has 2 attributes: `is_installed` which is a boolean value indicating whether the Payment Processor is installed; and `id` which is the unique identifier that you define in the Payment Processor service.
|
||||
|
||||
---
|
||||
|
||||
@@ -82,7 +82,7 @@ Among the Payment Sessions available only one will be selected based on the cust
|
||||
|
||||
### PaymentSession Entity Overview
|
||||
|
||||
The [`PaymentSession`](../../references/entities/classes/PaymentSession.mdx) entity belongs to a `Cart`. This is the customer‘s cart that was used for checkout which lead to the creation of the Payment Session.
|
||||
The [`PaymentSession`](../../references/entities/classes/entities.PaymentSession.mdx) entity belongs to a `Cart`. This is the customer‘s cart that was used for checkout which lead to the creation of the Payment Session.
|
||||
|
||||
The `PaymentSession` instance also belongs to a `PaymentProvider` instance. This is the Payment Processor that was used to create the Payment Session and that controls it for further actions like authorizing the payment.
|
||||
|
||||
@@ -116,7 +116,7 @@ When the store operator then chooses to capture the order from the Medusa Admin,
|
||||
|
||||
### Payment Entity Overview
|
||||
|
||||
The [`Payment`](../../references/entities/classes/Payment.mdx) entity belongs to the `Cart` that it was originally created from when the customer’s payment was authorized. It also belongs to an `Order` once it’s placed. Additionally, it belongs to a `PaymentProvider` which is the payment processor that the customer chose on checkout.
|
||||
The [`Payment`](../../references/entities/classes/entities.Payment.mdx) entity belongs to the `Cart` that it was originally created from when the customer’s payment was authorized. It also belongs to an `Order` once it’s placed. Additionally, it belongs to a `PaymentProvider` which is the payment processor that the customer chose on checkout.
|
||||
|
||||
In case a `Swap` is created for an order, `Payment` will be associated with that swap to handle payment operations related to it.
|
||||
|
||||
|
||||
@@ -49,7 +49,7 @@ Once the Fulfillment Provider is added to the backend, the store operator will b
|
||||
|
||||
### FulfillmentProvider Entity Overview
|
||||
|
||||
The [`FulfillmentProvider`](../../references/entities/classes/FulfillmentProvider.mdx) entity only has 2 attributes: `is_installed` to indicate if the fulfillment provider is installed and its value is a boolean; and `id` which is the unique identifier that you define in the Fulfillment Provider Service.
|
||||
The [`FulfillmentProvider`](../../references/entities/classes/entities.FulfillmentProvider.mdx) entity only has 2 attributes: `is_installed` to indicate if the fulfillment provider is installed and its value is a boolean; and `id` which is the unique identifier that you define in the Fulfillment Provider Service.
|
||||
|
||||
---
|
||||
|
||||
@@ -73,7 +73,7 @@ For example, shipping heavy items might be more expensive than others, which wou
|
||||
|
||||
### ShippingProfile Entity Overview
|
||||
|
||||
The [`ShippingProfile`](../../references/entities/classes/ShippingProfile.mdx) entity can have a set of `Product` instances. These would be the products the shipping profile is providing shipping options for.
|
||||
The [`ShippingProfile`](../../references/entities/classes/entities.ShippingProfile.mdx) entity can have a set of `Product` instances. These would be the products the shipping profile is providing shipping options for.
|
||||
|
||||
The `ShippingProfile` has a `type` attribute that can be `default`, `gift_card`, or `custom`.
|
||||
|
||||
@@ -101,7 +101,7 @@ Think of a shipping option as a template defined by the admin that indicates wha
|
||||
|
||||
### ShippingOption Entity Overview
|
||||
|
||||
The [`ShippingOption`](../../references/entities/classes/ShippingOption.mdx) entity belongs to the `ShippingProfile` entity.
|
||||
The [`ShippingOption`](../../references/entities/classes/entities.ShippingOption.mdx) entity belongs to the `ShippingProfile` entity.
|
||||
|
||||
The `ShippingOption` entity also belongs to a `FulfillmentProvider`. This can be either a custom third-party provider or one of Medusa’s default fulfillment providers.
|
||||
|
||||
@@ -139,7 +139,7 @@ This separation allows for developers to implement the custom integration with t
|
||||
|
||||
A lot of the shipping method’s attributes are similar to the shipping option’s attribute.
|
||||
|
||||
The [`ShippingMethod`](../../references/entities/classes/ShippingMethod.mdx) entity belongs to a `ShippingOption`.
|
||||
The [`ShippingMethod`](../../references/entities/classes/entities.ShippingMethod.mdx) entity belongs to a `ShippingOption`.
|
||||
|
||||
Similar to the `data` attribute explained for the `ShippingOption` entity, a `ShippingMethod` has a similar `data` attribute that includes all the data to be sent to the fulfillment provider when fulfilling the order.
|
||||
|
||||
@@ -153,5 +153,5 @@ The `ShippingMethod` instance holds a `price` attribute, which will either b
|
||||
|
||||
## See Also
|
||||
|
||||
- [Create a Fulfillment Provider](../../references/fulfillment/classes/AbstractFulfillmentService.mdx)
|
||||
- [Create a Fulfillment Provider](../../references/fulfillment/classes/fulfillment.AbstractFulfillmentService.mdx)
|
||||
- [Available shipping plugins](https://github.com/medusajs/medusa/tree/master/packages)
|
||||
|
||||
@@ -24,7 +24,7 @@ The customer groups feature can be used in a variety of use cases including:
|
||||
|
||||
## CustomerGroup Entity Overview
|
||||
|
||||
A customer group is stored in the database as a [CustomerGroup](../../references/entities/classes/CustomerGroup.mdx) entity. This entity has two attributes other than the `id`: `name` and `metadata`.
|
||||
A customer group is stored in the database as a [CustomerGroup](../../references/entities/classes/entities.CustomerGroup.mdx) entity. This entity has two attributes other than the `id`: `name` and `metadata`.
|
||||
|
||||
Similar to all entities in Medusa, you can use the `metadata` object attribute to store any custom data you want. For example, you can add some flag or tag to the customer group for a custom use case:
|
||||
|
||||
|
||||
@@ -191,9 +191,9 @@ This request accepts [many request-body parameters](https://docs.medusajs.com/ap
|
||||
|
||||
- `code`: This parameter is required. It is a unique code. The customer redeems the discount using this code.
|
||||
- `rule`: This parameter is required. It is an object having at least the following fields:
|
||||
- `type`: A string indicating the type of discount. It can be `fixed`, `percentage`, or `free_shipping`. When using the Medusa JS Client, you must use the enum type [DiscountRuleType](../../../references/js-client/internal/enums/internal.internal.DiscountRuleType.mdx) for the value.
|
||||
- `type`: A string indicating the type of discount. It can be `fixed`, `percentage`, or `free_shipping`. When using the Medusa JS Client, you must use the enum type [DiscountRuleType](../../../references/entities/enums/entities.DiscountRuleType.mdx) for the value.
|
||||
- `value`: A number indicating the value of the discount. If the discount type is `fixed`, then it will be the fixed amount to discount from the cart’s totals or its items. If the discount type is `percentage`, then it will be the percentage to discount from the items in the cart. If the type is `free_shipping`, it has no effect and can be set to `0`.
|
||||
- `allocation`: A string indicating how the discount should be applied. Can be `item` or `total`. If the type is not `fixed`, then this has no effect. When using the Medusa JS Client, you must use the enum type [AllocationType](../../../references/js-client/internal/enums/internal.internal.AllocationType.mdx) for the value.
|
||||
- `allocation`: A string indicating how the discount should be applied. Can be `item` or `total`. If the type is not `fixed`, then this has no effect. When using the Medusa JS Client, you must use the enum type [AllocationType](../../../references/entities/enums/entities.AllocationType.mdx) for the value.
|
||||
- `regions`: An array of region IDs this discount can be used in. If the type of discount is `fixed`, only one region can be passed.
|
||||
|
||||
This request returns the full `discount` object.
|
||||
|
||||
@@ -32,7 +32,7 @@ Discounts can be used in many use cases including:
|
||||
|
||||
## Discount Entity Overview
|
||||
|
||||
A discount is represented by the [`Discount`](../../references/entities/classes/Discount.mdx) entity. Some of its important attributes are:
|
||||
A discount is represented by the [`Discount`](../../references/entities/classes/entities.Discount.mdx) entity. Some of its important attributes are:
|
||||
|
||||
- `code` is a unique code that you specify when you create the discount. Customers use this code to apply the discount during checkout. The code can only include upper-case letters and numbers.
|
||||
- `rule_id` is the ID of the rule of this discount. The `rule` attribute is the expanded object of the `DiscountRule` entity. You can use the `rule` attribute to get details regarding the discount type. You can learn more about this in the [`DiscountRule` entity overview](#discountrule-entity-overview) later.
|
||||
@@ -54,7 +54,7 @@ The `is_dynamic` attribute in the `Discount` entity is a boolean value that dete
|
||||
|
||||
## DiscountRule Entity Overview
|
||||
|
||||
Every `Discount` entity belongs to a [`DiscountRule`](../../references/entities/classes/DiscountRule.mdx) entity. `DiscountRule` includes details such as the type of discount, the amount to be discounted, and more.
|
||||
Every `Discount` entity belongs to a [`DiscountRule`](../../references/entities/classes/entities.DiscountRule.mdx) entity. `DiscountRule` includes details such as the type of discount, the amount to be discounted, and more.
|
||||
|
||||
Some of the `DiscountRule` entity’s important attributes are:
|
||||
|
||||
@@ -71,7 +71,7 @@ Some of the `DiscountRule` entity’s important attributes are:
|
||||
|
||||
A discount can optionally have discount conditions. Discount conditions are used to further add limitations on when the discount can be applied.
|
||||
|
||||
A [`DiscountCondition`](../../references/entities/classes/DiscountCondition.mdx) belongs to a `DiscountRule` entity. The `discount_rule_id` attribute indicates the ID of the `DiscountRule` it belongs to.
|
||||
A [`DiscountCondition`](../../references/entities/classes/entities.DiscountCondition.mdx) belongs to a `DiscountRule` entity. The `discount_rule_id` attribute indicates the ID of the `DiscountRule` it belongs to.
|
||||
|
||||
Discount conditions have an attribute `type` that indicates the condition’s type. Its value must be one of the following:
|
||||
|
||||
@@ -92,11 +92,11 @@ Discount conditions also have an attribute `operator` that indicates how the con
|
||||
|
||||
Based on the value of `type`, one of the following relations can be used to retrieve the condition’s items:
|
||||
|
||||
- `products` is an array of products that this condition applies to if the condition’s `type` is `products`. Each item of the array would be a [`DiscountConditionProduct`](../../references/entities/classes/DiscountConditionProduct.mdx).
|
||||
- `product_types` is an array of product types that this condition applies to if the condition’s `type` is `product_types`. Each item of the array would be a [`DiscountConditionProductType`](../../references/entities/classes/DiscountConditionProductType.mdx).
|
||||
- `product_collections` is an array of product collections that this condition applies to if the condition’s `type` is `product_collections`. Each item of the array would be a [`DiscountConditionProductCollection`](../../references/entities/classes/DiscountConditionProductCollection.mdx).
|
||||
- `product_tags` is an array of product tags that this condition applies to if the condition’s `type` is `product_tags`. Each item of the array would be a [`DiscountConditionProductTag`](../../references/entities/classes/DiscountConditionProductTag.mdx).
|
||||
- `customer_groups` is an array of customer groups that this condition applies to if the condition’s `type` is `customer_groups`. Each item of the array would be a [`DiscountConditionCustomerGroup`](../../references/entities/classes/DiscountConditionCustomerGroup.mdx).
|
||||
- `products` is an array of products that this condition applies to if the condition’s `type` is `products`. Each item of the array would be a [`DiscountConditionProduct`](../../references/entities/classes/entities.DiscountConditionProduct.mdx).
|
||||
- `product_types` is an array of product types that this condition applies to if the condition’s `type` is `product_types`. Each item of the array would be a [`DiscountConditionProductType`](../../references/entities/classes/entities.DiscountConditionProductType.mdx).
|
||||
- `product_collections` is an array of product collections that this condition applies to if the condition’s `type` is `product_collections`. Each item of the array would be a [`DiscountConditionProductCollection`](../../references/entities/classes/entities.DiscountConditionProductCollection.mdx).
|
||||
- `product_tags` is an array of product tags that this condition applies to if the condition’s `type` is `product_tags`. Each item of the array would be a [`DiscountConditionProductTag`](../../references/entities/classes/entities.DiscountConditionProductTag.mdx).
|
||||
- `customer_groups` is an array of customer groups that this condition applies to if the condition’s `type` is `customer_groups`. Each item of the array would be a [`DiscountConditionCustomerGroup`](../../references/entities/classes/entities.DiscountConditionCustomerGroup.mdx).
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@ As custom gift cards can be used once they’re created, they’re also represen
|
||||
|
||||
## GiftCard Entity Overview
|
||||
|
||||
Some of the [GiftCard](../../references/entities/classes/GiftCard.mdx) entity’s attributes are:
|
||||
Some of the [GiftCard](../../references/entities/classes/entities.GiftCard.mdx) entity’s attributes are:
|
||||
|
||||
- `code`: a unique string of random characters. This is the code that the customer can use during their checkout to redeem the gift card.
|
||||
- `value`: The amount of the gift card. This is the amount the customer purchased, or was gifted in the case of custom gift cards.
|
||||
|
||||
@@ -208,7 +208,7 @@ For example, you can filter the orders by one or more status:
|
||||
|
||||
:::note
|
||||
|
||||
You can check available order statuses [here](../../../references/entities/enums/OrderStatus.mdx).
|
||||
You can check available order statuses [here](../../../references/entities/enums/entities.OrderStatus.mdx).
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@@ -19,12 +19,12 @@ The Medusa core provides the necessary implementation and functionalities that a
|
||||
A claim is represented by the `ClaimOrder` entity. Some of its attributes include:
|
||||
|
||||
- `type`: a string indicating the type of the claim. Its value can be either `refund` or `replace`.
|
||||
- `payment_status`: a string indicating the status of the claim’s payment. Its possible values are indicated by the [ClaimPaymentStatus enum](../../references/entities/enums/ClaimPaymentStatus.mdx). This attribute is useful to check the status of the payment if the claim’s type is `refund`.
|
||||
- `fulfillment_status`: a string indicating the status of the claim’s fulfillment. Its possible values are indicated by the [ClaimFulfillmentStatus enum](../../references/entities/enums/ClaimFulfillmentStatus.mdx). This attribute is useful to check the status of the fulfillment if the claim’s type is `replace`.
|
||||
- `payment_status`: a string indicating the status of the claim’s payment. Its possible values are indicated by the [ClaimPaymentStatus enum](../../references/entities/enums/entities.ClaimPaymentStatus.mdx). This attribute is useful to check the status of the payment if the claim’s type is `refund`.
|
||||
- `fulfillment_status`: a string indicating the status of the claim’s fulfillment. Its possible values are indicated by the [ClaimFulfillmentStatus enum](../../references/entities/enums/entities.ClaimFulfillmentStatus.mdx). This attribute is useful to check the status of the fulfillment if the claim’s type is `replace`.
|
||||
- `refund_amount`: an integer used to indicate the amount that should be refunded to the customer. This is only useful if the claim’s type is `refund`.
|
||||
- `canceled_at`: a date indicating when the claim was canceled.
|
||||
|
||||
There are other important attributes discussed in later sections. Check out the [full ClaimOrder entity in the entities reference](../../references/entities/classes/ClaimOrder.mdx).
|
||||
There are other important attributes discussed in later sections. Check out the [full ClaimOrder entity in the entities reference](../../references/entities/classes/entities.ClaimOrder.mdx).
|
||||
|
||||
---
|
||||
|
||||
@@ -32,7 +32,7 @@ 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 API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaims) or using the `ClaimService`'s [create method](../../references/services/classes/ClaimService.mdx#create). This section explains the process within the Create Claim API Route, 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/services.ClaimService.mdx#create). This section explains the process within the Create Claim API Route, with a focus on the `create` method.
|
||||
|
||||
### Idempotency Key
|
||||
|
||||
@@ -46,16 +46,16 @@ The following flow is implemented within the Create Claim API Route:
|
||||
|
||||
|
||||
|
||||
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.mdx#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.mdx#getrefundtotalforclaimlinesonorder).
|
||||
2. If new items are specified to send to the customer, new line items, which are represented by the `LineItem` entity, are generated using the `LineItemService`'s [generate method](../../references/services/classes/LineItemService.mdx#generate). These line items are later attached to the claim when it’s created under the `additional_items` relation. Also, the quantity of these items are reserved from the product variant’s inventory using the `ProductVariantInventoryService`'s [reserveQuantity method](../../references/services/classes/ProductVariantInventoryService.mdx#reservequantity).
|
||||
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/services.ClaimService.mdx#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/services.ClaimService.mdx#getrefundtotalforclaimlinesonorder).
|
||||
2. If new items are specified to send to the customer, new line items, which are represented by the `LineItem` entity, are generated using the `LineItemService`'s [generate method](../../references/services/classes/services.LineItemService.mdx#generate). These line items are later attached to the claim when it’s created under the `additional_items` relation. Also, the quantity of these items are reserved from the product variant’s inventory using the `ProductVariantInventoryService`'s [reserveQuantity method](../../references/services/classes/services.ProductVariantInventoryService.mdx#reservequantity).
|
||||
3. The claim is created and saved.
|
||||
4. If there were additional items attached to the claim, tax lines are created for these items using the `TaxProviderService`'s [createTaxLines method](../../references/services/classes/TaxProviderService.mdx#createtaxlines).
|
||||
5. If a shipping method was chosen to send the additional items to the customer, the shipping method is created using the `ShippingOptionService`'s [createShippingMethod method](../../references/services/classes/ShippingOptionService.mdx#createshippingmethod) or updated if it already exists using the `ShippingOptionService`'s [updateShippingMethod method](../../references/services/classes/ShippingOptionService.mdx#updateshippingmethod).
|
||||
6. A claim item is created for each of the items specified in the claim. These are the items that were originally in the order and that the claim was created for. The claim items are created using the `ClaimItemService`'s [create method](../../references/services/classes/ClaimItemService.mdx#create).
|
||||
7. If a return shipping method is specified, a return is created using the `ReturnService`'s [create method](../../references/services/classes/ReturnService.mdx#create).
|
||||
2. When the idempotency key’s recovery point is `claim_created`, if the claim’s type is `refund`, the refund is processed using the `ClaimService`'s [processRefund method](../../references/services/classes/ClaimService.mdx#processrefund). If the method is refunded successfully, the `payment_status` attribute of the claim is set to `refunded`. The refund is created directly on the order the claim belongs to. The recovery point of the idempotency key is changed to `refund_handled` at the end of this process.
|
||||
3. When the idempotency key’s recovery point is `refund_handled`, if the claim is associated with a return, the return is automatically fulfilled using the `ReturnService`'s [fulfill method](../../references/services/classes/ReturnService.mdx#fulfill) as it will be handled by the customer. The order associated with the claim is then returned and the idempotency key is set to `finished`.
|
||||
4. If there were additional items attached to the claim, tax lines are created for these items using the `TaxProviderService`'s [createTaxLines method](../../references/services/classes/services.TaxProviderService.mdx#createtaxlines).
|
||||
5. If a shipping method was chosen to send the additional items to the customer, the shipping method is created using the `ShippingOptionService`'s [createShippingMethod method](../../references/services/classes/services.ShippingOptionService.mdx#createshippingmethod) or updated if it already exists using the `ShippingOptionService`'s [updateShippingMethod method](../../references/services/classes/services.ShippingOptionService.mdx#updateshippingmethod).
|
||||
6. A claim item is created for each of the items specified in the claim. These are the items that were originally in the order and that the claim was created for. The claim items are created using the `ClaimItemService`'s [create method](../../references/services/classes/services.ClaimItemService.mdx#create).
|
||||
7. If a return shipping method is specified, a return is created using the `ReturnService`'s [create method](../../references/services/classes/services.ReturnService.mdx#create).
|
||||
2. When the idempotency key’s recovery point is `claim_created`, if the claim’s type is `refund`, the refund is processed using the `ClaimService`'s [processRefund method](../../references/services/classes/services.ClaimService.mdx#processrefund). If the method is refunded successfully, the `payment_status` attribute of the claim is set to `refunded`. The refund is created directly on the order the claim belongs to. The recovery point of the idempotency key is changed to `refund_handled` at the end of this process.
|
||||
3. When the idempotency key’s recovery point is `refund_handled`, if the claim is associated with a return, the return is automatically fulfilled using the `ReturnService`'s [fulfill method](../../references/services/classes/services.ReturnService.mdx#fulfill) as it will be handled by the customer. The order associated with the claim is then returned and the idempotency key is set to `finished`.
|
||||
|
||||
---
|
||||
|
||||
@@ -63,7 +63,7 @@ The following flow is implemented within the Create Claim API Route:
|
||||
|
||||
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 API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimfulfillments) or the `ClaimService`'s [createFulfillment method](../../references/services/classes/ClaimService.mdx#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/services.ClaimService.mdx#createfulfillment).
|
||||
|
||||
:::note
|
||||
|
||||
@@ -73,9 +73,9 @@ The API Route handles updating the inventory and reservations. So, if you choose
|
||||
|
||||
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 API Route](https://docs.medusajs.com/api/admin#orders_postordersorderclaimsclaimshipments) or the `ClaimService`'s [createShipment method](../../references/services/classes/ClaimService.mdx#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/services.ClaimService.mdx#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 API Route](https://docs.medusajs.com/api/admin#tag/Orders/operation/PostOrdersClaimFulfillmentsCancel) or the `ClaimService`'s [cancelFulfillment method](../../references/services/classes/ClaimService.mdx#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/services.ClaimService.mdx#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 API Route](https://docs.medusajs.com/api/admin#orders_postordersclaimcancel) or the `ClaimService`'s [cancel method](../../references/services/classes/ClaimService.mdx#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/services.ClaimService.mdx#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.
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ Some of the `DraftOrder`'s attributes include:
|
||||
- `completed_at`: a date indicating when the draft order was completed.
|
||||
- `no_notification_order`: a boolean indicating whether the customer should receive notifications when the order is updated.
|
||||
|
||||
There are other important attributes discussed in later sections. Check out the [full DraftOrder entity in the entities reference](../../references/entities/classes/DraftOrder.mdx).
|
||||
There are other important attributes discussed in later sections. Check out the [full DraftOrder entity in the entities reference](../../references/entities/classes/entities.DraftOrder.mdx).
|
||||
|
||||
---
|
||||
|
||||
@@ -34,11 +34,11 @@ There are other important attributes discussed in later sections. Check out the
|
||||
|
||||
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.mdx#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`.
|
||||
A draft order is created using the `DraftOrderService`'s [create method](../../references/services/classes/services.DraftOrderService.mdx#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`.
|
||||
|
||||
Since the draft order is associated with a cart, the process implemented in the Medusa backend around completing the draft order is pretty similar to that of completing a cart.
|
||||
|
||||
The payment must be authorized before the cart can be completed, which can be done using the `CartService`'s [authorizePayment method](../../references/services/classes/CartService.mdx#authorizepayment). Once the payment is authorized, the order can be created using the `OrderService`'s [createFromCart method](../../references/services/classes/OrderService.mdx#createfromcart).
|
||||
The payment must be authorized before the cart can be completed, which can be done using the `CartService`'s [authorizePayment method](../../references/services/classes/services.CartService.mdx#authorizepayment). Once the payment is authorized, the order can be created using the `OrderService`'s [createFromCart method](../../references/services/classes/services.OrderService.mdx#createfromcart).
|
||||
|
||||
:::note
|
||||
|
||||
@@ -46,7 +46,7 @@ In the Register Payment API Route, the `system` payment method is used by defaul
|
||||
|
||||
:::
|
||||
|
||||
The draft order can then be completed using the `DraftOrderService`'s [registerCartCompletion method](../../references/services/classes/DraftOrderService.mdx#registercartcompletion). This would update its status to `completed` and would set the `order_id` attribute of the draft order. Finally, you can capture the payment of the order that was created using the `OrderService`'s [capturePayment method](../../references/services/classes/OrderService.mdx#capturepayment).
|
||||
The draft order can then be completed using the `DraftOrderService`'s [registerCartCompletion method](../../references/services/classes/services.DraftOrderService.mdx#registercartcompletion). This would update its status to `completed` and would set the `order_id` attribute of the draft order. Finally, you can capture the payment of the order that was created using the `OrderService`'s [capturePayment method](../../references/services/classes/services.OrderService.mdx#capturepayment).
|
||||
|
||||
Once the order is created and the draft order is completed, the created order can be processed and handled the same as orders created by customers.
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ In this document, you’ll learn about Fulfillments, how they’re used in your
|
||||
|
||||
Fulfillments are used to ship items, typically to a customer. Fulfillments can be used in orders, returns, swaps, and more.
|
||||
|
||||
Fulfillments are processed within Medusa by a [fulfillment provider](../../references/fulfillment/classes/AbstractFulfillmentService.mdx). The fulfillment provider handles creating, validating, and processing the fulfillment, among other functionalities. Typically, a fulfillment provider would be integrated with a third-party service that handles the actual shipping of the items.
|
||||
Fulfillments are processed within Medusa by a [fulfillment provider](../../references/fulfillment/classes/fulfillment.AbstractFulfillmentService.mdx). The fulfillment provider handles creating, validating, and processing the fulfillment, among other functionalities. Typically, a fulfillment provider would be integrated with a third-party service that handles the actual shipping of the items.
|
||||
|
||||
When a fulfillment is created for one or more item, shipments can then be created for that fulfillment. These shipments can then be tracked using tracking numbers, providing customers and merchants accurate details about a shipment.
|
||||
|
||||
@@ -27,7 +27,7 @@ Some of the `Fulfillment` entity’s attributes include:
|
||||
- `shipped_at`: a date indicating when the fulfillment was shipped.
|
||||
- `canceled_at`: a date indicating when the fulfillment was canceled.
|
||||
|
||||
There are other important attributes discussed in later sections. Check out the [full Fulfillment entity in the entities reference](../../references/entities/classes/Fulfillment.mdx).
|
||||
There are other important attributes discussed in later sections. Check out the [full Fulfillment entity in the entities reference](../../references/entities/classes/entities.Fulfillment.mdx).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ Some of the attributes of the `Order` entity include:
|
||||
- `no_notification`: a boolean value indicating whether the customer should receive notifications when the order is updated.
|
||||
- `external_id`: a string indicating an ID of the order in an external system. This can be useful if you’re migrating your orders from another commerce system or you’re linking your order to a third-party service.
|
||||
|
||||
There are other important attributes discussed in later sections. Check out the full [Order entity in the entities reference](../../references/entities/classes/Order.mdx).
|
||||
There are other important attributes discussed in later sections. Check out the full [Order entity in the entities reference](../../references/entities/classes/entities.Order.mdx).
|
||||
|
||||
---
|
||||
|
||||
@@ -52,15 +52,15 @@ You have full freedom in how you create your orders. Within the Medusa backend,
|
||||
|
||||
## Payments in Orders
|
||||
|
||||
In the cart completion process, or when you use the `OrderService`'s method [createFromCart](../../references/services/classes/OrderService.mdx#createfromcart), the cart’s payment is also associated with the order by setting the `order_id` of the payment to the newly created order’s ID.
|
||||
In the cart completion process, or when you use the `OrderService`'s method [createFromCart](../../references/services/classes/services.OrderService.mdx#createfromcart), the cart’s payment is also associated with the order by setting the `order_id` of the payment to the newly created order’s ID.
|
||||
|
||||
An order can have more than one payment. You can access the order’s payments by expanding the `payments` relation and accessing `order.payments`.
|
||||
|
||||
By default, the payment will be authorized but not captured. Some payment processor plugins, such as the Stripe plugin, allow changing this behavior to automatically capture the payment. You can also do that within your custom payment processor.
|
||||
|
||||
In the default scenario, the merchant would have to capture that payment manually, which would change the `payment_status` of the order. The payment can be captured using the `PaymentService`'s [capture method](../../references/services/classes/PaymentService.mdx#capture).
|
||||
In the default scenario, the merchant would have to capture that payment manually, which would change the `payment_status` of the order. The payment can be captured using the `PaymentService`'s [capture method](../../references/services/classes/services.PaymentService.mdx#capture).
|
||||
|
||||
After a payment has been captured, it can be refunded either fully or a specific amount of it. This is useful if items of an order has been returned or swapped, or if an order has been edited. The payment can be refunded using the `PaymentService`'s [refund method](../../references/services/classes/PaymentService.mdx#refund).
|
||||
After a payment has been captured, it can be refunded either fully or a specific amount of it. This is useful if items of an order has been returned or swapped, or if an order has been edited. The payment can be refunded using the `PaymentService`'s [refund method](../../references/services/classes/services.PaymentService.mdx#refund).
|
||||
|
||||
The Medusa backend also provides payment admin APIs that you can use to retrieve, capture, and refund the payment.
|
||||
|
||||
@@ -80,13 +80,13 @@ A fulfillment can instead be canceled, changing the `fulfillment_status` to `can
|
||||
|
||||
If one or some items in an order are returned, the `fulfillment_status` is set to `partially_returned`. If all items were returned, the `fulfillment_status` is set to `returned`.
|
||||
|
||||
The Medusa backend provides these functionalities through the admin APIs. You can also use the `OrderService`'s methods to perform these functionalities in a custom flow, such as the [createFulfillment](../../references/services/classes/OrderService.mdx#createfulfillment) or [createShipment](../../references/services/classes/OrderService.mdx#createshipment) methods.
|
||||
The Medusa backend provides these functionalities through the admin APIs. You can also use the `OrderService`'s methods to perform these functionalities in a custom flow, such as the [createFulfillment](../../references/services/classes/services.OrderService.mdx#createfulfillment) or [createShipment](../../references/services/classes/services.OrderService.mdx#createshipment) methods.
|
||||
|
||||
---
|
||||
|
||||
## Order Totals Calculations
|
||||
|
||||
By default, the `Order` entity doesn’t hold any details regarding the totals. These are computed and added to the order instance using the `OrderService`'s [decorateTotals method](../../references/services/classes/OrderService.mdx#decoratetotals). There's also a dedicated method in the `OrderService`, [retrieveWithTotals](../../references/services/classes/OrderService.mdx#retrievewithtotals), attaching the totals to the order instance automatically. It is recommended to use this method by default when you need to retrieve the order.
|
||||
By default, the `Order` entity doesn’t hold any details regarding the totals. These are computed and added to the order instance using the `OrderService`'s [decorateTotals method](../../references/services/classes/services.OrderService.mdx#decoratetotals). There's also a dedicated method in the `OrderService`, [retrieveWithTotals](../../references/services/classes/services.OrderService.mdx#retrievewithtotals), attaching the totals to the order instance automatically. It is recommended to use this method by default when you need to retrieve the order.
|
||||
|
||||
The order’s totals are calculated based on the content and context of the order. This includes the order’s region, whether tax-inclusive pricing is enabled, the chosen shipping methods, and more.
|
||||
|
||||
@@ -133,7 +133,7 @@ A merchant may also choose to force the edit on the order, by-passing the custom
|
||||
|
||||
Although this process is implemented in this flow within the Medusa backend, there is no requirement for you to actually follow it. For example, you can allow the customer or a third-party service to create and manage the order edit.
|
||||
|
||||
The Medusa backend provides the [order edit admin APIs](https://docs.medusajs.com/api/admin#order-edits), but you can also use the [OrderEditService](../../references/services/classes/OrderEditService.mdx) to perform the same functionalities in a custom flow.
|
||||
The Medusa backend provides the [order edit admin APIs](https://docs.medusajs.com/api/admin#order-edits), but you can also use the [OrderEditService](../../references/services/classes/services.OrderEditService.mdx) to perform the same functionalities in a custom flow.
|
||||
|
||||
Order edits are represented by the `OrderEdit` entity. This entity is linked to the order through the `order_id` attribute. You can access an order’s edits by expanding the `edits` relation and accessing `order.edits`. Notice that an order can have multiple edits during its lifecycle, but it can’t have more than one ongoing edit.
|
||||
|
||||
@@ -145,7 +145,7 @@ Some of the `OrderEdit`'s other attributes include:
|
||||
- `confirmed_by`: a string that typically should hold the ID of who confirmed the order edit. Similar to the `created_by` attribute, there are no restrictions on what value this attribute can actually hold.
|
||||
- `declined_by`: a string that typically should hold the ID of who declined the order edit. Similar to the `created_by` attribute, there are no restrictions on what value this attribute can actually hold.
|
||||
|
||||
There are other attributes explained in other sections. You can also check out the full [OrderEdit entity in the entities reference](../../references/entities/classes/OrderEdit.mdx).
|
||||
There are other attributes explained in other sections. You can also check out the full [OrderEdit entity in the entities reference](../../references/entities/classes/entities.OrderEdit.mdx).
|
||||
|
||||
### Item Changes
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@ Some of the `Return` entity’s attributes include:
|
||||
- `no_notification`: a boolean value indicating whether the customer should receive notification updates when there are any changes in the return.
|
||||
- `shipping_data`: this is a JSONB object that can hold any data related to the fulfillment associated with the return.
|
||||
|
||||
There are other important attributes discussed in later sections. Check out the [full Return entity in the entities reference](../../references/entities/classes/Return.mdx).
|
||||
There are other important attributes discussed in later sections. Check out the [full Return entity in the entities reference](../../references/entities/classes/entities.Return.mdx).
|
||||
|
||||
---
|
||||
|
||||
@@ -54,8 +54,8 @@ The following process occurs within the Create Return storefront API Route:
|
||||
|
||||
|
||||
|
||||
1. The customer creates a return, specifying the items they want to return and optionally the shipping option they want to use to return the items. This is done using the `ReturnService`'s [create method](../../references/services/classes/ReturnService.mdx#create).
|
||||
2. If they specify the return shipping option they want to use, a shipping method is created from the chosen shipping option and the return is automatically fulfilled in the backend using the `ReturnService`'s [fulfill method](../../references/services/classes/ReturnService.mdx#fulfill).
|
||||
1. The customer creates a return, specifying the items they want to return and optionally the shipping option they want to use to return the items. This is done using the `ReturnService`'s [create method](../../references/services/classes/services.ReturnService.mdx#create).
|
||||
2. If they specify the return shipping option they want to use, a shipping method is created from the chosen shipping option and the return is automatically fulfilled in the backend using the `ReturnService`'s [fulfill method](../../references/services/classes/services.ReturnService.mdx#fulfill).
|
||||
|
||||
After this process, the return will be available for the merchant or the admin to view and handle it. The merchant can either mark the return as received or cancel the return.
|
||||
|
||||
@@ -71,15 +71,15 @@ The following process occurs within the [Receive Return admin API Route](https:/
|
||||
1. The return’s status is checked to ensure it’s not canceled or received. If so, the process is terminated with an error.
|
||||
2. The received items are validated to ensure they match the items that were previously requested to be returned. If there’s a mismatch, the return’s status is set to `requires_more`. This is useful in situations where a custom refund amount is requested, but the returned items don’t match the requested items.
|
||||
3. If there’s no mismatch issue, the return’s status is set to `received`.
|
||||
4. The inventory of the returned items is adjusted using the `ProductVariantInventoryService`'s [method adjustInventory](../../references/services/classes/ProductVariantInventoryService.mdx#adjustinventory)
|
||||
2. After the return is marked as received, if the return is associated with a swap, the `SwapService`'s [registerReceived method](../../references/services/classes/SwapService.mdx#registerreceived) is used to validate the return, emit the swap event `received`, and return the swap.
|
||||
3. On the other hand, after the return is marked as received, if the return is associated with an order, the `OrderService`'s [registerReturnReceived method](../../references/services/classes/OrderService.mdx#registerreturnreceived). In this method:
|
||||
4. The inventory of the returned items is adjusted using the `ProductVariantInventoryService`'s [method adjustInventory](../../references/services/classes/services.ProductVariantInventoryService.mdx#adjustinventory)
|
||||
2. After the return is marked as received, if the return is associated with a swap, the `SwapService`'s [registerReceived method](../../references/services/classes/services.SwapService.mdx#registerreceived) is used to validate the return, emit the swap event `received`, and return the swap.
|
||||
3. On the other hand, after the return is marked as received, if the return is associated with an order, the `OrderService`'s [registerReturnReceived method](../../references/services/classes/services.OrderService.mdx#registerreturnreceived). In this method:
|
||||
1. If the amount that is expected to be refunded is greater than the amount that can be refunded, the `fulfillment_status` of the order is set to `requires_action`. And the process is terminated.
|
||||
2. If there are no validation issues, the payment is refunded and the fulfillment status is set to `returned` if all items of the order were returned, or `partially_returned` if only some items were returned.
|
||||
|
||||
### 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.mdx#cancel) or using the [Cancel Return API Route](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/services.ReturnService.mdx#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.
|
||||
|
||||
|
||||
@@ -18,8 +18,8 @@ The Medusa core provides the necessary implementation and functionalities that a
|
||||
|
||||
Some of the attributes of the `Swap` entity include:
|
||||
|
||||
- `fulfillment_status`: a string indicating the status of the swap’s fulfillment. Its possible values indicated by the [SwapFulfillmentStatus enum](../../references/entities/enums/SwapFulfillmentStatus.mdx) can determine whether all items have been fulfilled, shipped, or canceled.
|
||||
- `payment_status`: a string indicating the status of the swap’s payment. Its possible values indicated by the [SwapPaymentStatus enum](../../references/entities/enums/SwapFulfillmentStatus.mdx) can determine whether the payment of the swap has been captured or refunded.
|
||||
- `fulfillment_status`: a string indicating the status of the swap’s fulfillment. Its possible values indicated by the [SwapFulfillmentStatus enum](../../references/entities/enums/entities.SwapFulfillmentStatus.mdx) can determine whether all items have been fulfilled, shipped, or canceled.
|
||||
- `payment_status`: a string indicating the status of the swap’s payment. Its possible values indicated by the [SwapPaymentStatus enum](../../references/entities/enums/entities.SwapFulfillmentStatus.mdx) can determine whether the payment of the swap has been captured or refunded.
|
||||
- `difference_due`: An integer indicating the difference amount between the order’s original total and the new total imposed by the swap.
|
||||
- If the value of `difference_due` is negative, that means the customer should be refunded.
|
||||
- If it’s positive, that means the customer must authorize additional payment.
|
||||
@@ -29,7 +29,7 @@ Some of the attributes of the `Swap` entity include:
|
||||
- `no_notification`: a boolean value indicating whether the customer should receive notifications when the order is updated.
|
||||
- `allow_backorder`: a boolean value indicating whether a swap can be created and completed with items that are out of stock.
|
||||
|
||||
There are other important attributes discussed in later sections. Check out the full [Swap entity in the entities reference](../../references/entities/classes/Swap.mdx).
|
||||
There are other important attributes discussed in later sections. Check out the full [Swap entity in the entities reference](../../references/entities/classes/entities.Swap.mdx).
|
||||
|
||||
---
|
||||
|
||||
@@ -51,12 +51,12 @@ The customer starts by creating their swap, which can be done through the Create
|
||||
|
||||
|
||||
|
||||
1. The swap’s creation is initiated with the `SwapService`'s [create method](../../references/services/classes/SwapService.mdx#create):
|
||||
1. The swap’s creation is initiated with the `SwapService`'s [create method](../../references/services/classes/services.SwapService.mdx#create):
|
||||
1. The order is first validated to see if a swap can be created. This includes checking the `payment_status` of the order to ensure the payment has already been captured, and the `fulfillment_status` of the order to ensure the status isn’t `not_fulfilled`. If any of these conditions aren’t met, the process is terminated with an error.
|
||||
2. The items that the customer chose to return are then validated. If any item has been previously canceled, meaning that its order, swap, or claim have been previously canceled, the process is terminated with an error.
|
||||
3. If all the conditions above are met, the swap is then created and associated with the order using the `order_id` attribute.
|
||||
4. A return is created and linked to the swap. The return’s items are set to the items that the customer chose to return.
|
||||
2. After the swap has been created, a cart is then created for the swap using the `SwapService`'s [createCart method](../../references/services/classes/SwapService.mdx#createcart). The cart is used to finalize the process of the swap creation process, but more on that later. The swap is associated with the cart using the `cart_id` attribute.
|
||||
2. After the swap has been created, a cart is then created for the swap using the `SwapService`'s [createCart method](../../references/services/classes/services.SwapService.mdx#createcart). The cart is used to finalize the process of the swap creation process, but more on that later. The swap is associated with the cart using the `cart_id` attribute.
|
||||
3. The return associated with the swap is marked as fulfilled, as this is taken care of by the customer.
|
||||
|
||||
After the swap has been created, the customer should undergo a swap-completion process similar to the checkout process where they provide shipping and billing addresses, choose shipping and payment methods, authorize any additional payment required, then finally completing the cart.
|
||||
@@ -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.mdx#processdifference), or using the [Process Swap Payment API Route](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/services.SwapService.mdx#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
|
||||
|
||||
|
||||
|
||||
1. The fulfillment is created either using the `SwapService`'s [createFulfillment method](../../references/services/classes/SwapService.mdx#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.mdx#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.mdx#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`.
|
||||
1. The fulfillment is created either using the `SwapService`'s [createFulfillment method](../../references/services/classes/services.SwapService.mdx#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/services.SwapService.mdx#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/services.SwapService.mdx#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.mdx#cancel) or the [Cancel Swap API Route](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/services.SwapService.mdx#cancel) or the [Cancel Swap API Route](https://docs.medusajs.com/api/admin#orders_postordersswapcancel).
|
||||
|
||||
A swap can’t be canceled if:
|
||||
|
||||
|
||||
+1
-1
@@ -262,7 +262,7 @@ You can learn more about optional properties and the meaning behind every proper
|
||||
},
|
||||
{
|
||||
name: "prices",
|
||||
type: "[MoneyAmount](../../../references/entities/classes/MoneyAmount.mdx)[]",
|
||||
type: "[MoneyAmount](../../../references/entities/classes/entities.MoneyAmount.mdx)[]",
|
||||
description: "The prices of the variant retrieved using the `context` object. It can include its original price and its price lists if there are any.",
|
||||
optional: false
|
||||
}
|
||||
|
||||
@@ -20,7 +20,7 @@ Price lists can be used for a variety of use cases including:
|
||||
|
||||
### Price List Entity Overview
|
||||
|
||||
A price list is stored in the database as a [PriceList](../../references/entities/classes/PriceList.mdx) entity. Some of its important attributes are:
|
||||
A price list is stored in the database as a [PriceList](../../references/entities/classes/entities.PriceList.mdx) entity. Some of its important attributes are:
|
||||
|
||||
- `type`: The price list's type. Can be either a `sale` or an `override`.
|
||||
- `status`: The status of the price list. Can be `active` or `draft`. If a price list is a `draft`, its prices won't be applied even if its conditions are met.
|
||||
|
||||
@@ -43,7 +43,7 @@ There is no limit on how many regions you can create, and regions can share simi
|
||||
|
||||
## Region Entity Overview
|
||||
|
||||
A region is stored in the database as a [Region](../../references/entities/classes/Region.mdx) entity. Some of its important attributes are:
|
||||
A region is stored in the database as a [Region](../../references/entities/classes/entities.Region.mdx) entity. Some of its important attributes are:
|
||||
|
||||
- `name`: The name of the region. Customers will see this name on the storefront.
|
||||
- `tax_rate`: A number that indicates the tax rate. The tax rate is a percentage.
|
||||
|
||||
@@ -24,7 +24,7 @@ The sales channel feature can be used in a variety of use cases including:
|
||||
|
||||
## SalesChannel Entity Overview
|
||||
|
||||
A sales channel is stored in the database as a [SalesChannel](../../references/entities/classes/SalesChannel.mdx) entity. Some of its important attributes are:
|
||||
A sales channel is stored in the database as a [SalesChannel](../../references/entities/classes/entities.SalesChannel.mdx) entity. Some of its important attributes are:
|
||||
|
||||
- `name`: The name of the sales channel.
|
||||
- `is_disabled`: A boolean value indicating of the Sales Channel is disabled or not.
|
||||
@@ -37,13 +37,13 @@ A sales channel is stored in the database as a [SalesChannel](../../references/e
|
||||
|
||||
A store has a default sales channel. When you first run your Medusa backend or seed your database, a default sales channel is created, if it doesn’t exist, and associated with the store.
|
||||
|
||||
The relation is implemented in the [Store](../../references/entities/classes/Store.mdx) entity. You can access the default sales channel of a store by expanding the `default_sales_channel` relation and using `store.default_sales_channel`. You can also access the ID of the default sales channel using `store.default_sales_channel_id`.
|
||||
The relation is implemented in the [Store](../../references/entities/classes/entities.Store.mdx) entity. You can access the default sales channel of a store by expanding the `default_sales_channel` relation and using `store.default_sales_channel`. You can also access the ID of the default sales channel using `store.default_sales_channel_id`.
|
||||
|
||||
### Product
|
||||
|
||||
Products can be available in more than one sales channel. You can then filter products by a sales channel using the Storefront and Admin APIs.
|
||||
|
||||
The relation is implemented in the [Product](../../references/entities/classes/Product.mdx) entity. You can access the sales channels a product is available in by expanding the `sales_channels` relation and using `product.sales_channels`.
|
||||
The relation is implemented in the [Product](../../references/entities/classes/entities.Product.mdx) entity. You can access the sales channels a product is available in by expanding the `sales_channels` relation and using `product.sales_channels`.
|
||||
|
||||
### Cart
|
||||
|
||||
@@ -51,13 +51,13 @@ When you create a cart, you can optionally specify the sales channel it belongs
|
||||
|
||||
A cart can belong to only one sales channel. Only products that belong to the same sales channel as the cart can be added to it.
|
||||
|
||||
The relation is implemented in the [Cart](../../references/entities/classes/Cart.mdx) entity. You can access the sales channel a cart is associated with by expanding the `sales_channel` relation and using `cart.sales_channel`. You can also access the ID of the sales channel using `cart.sales_channel_id`.
|
||||
The relation is implemented in the [Cart](../../references/entities/classes/entities.Cart.mdx) entity. You can access the sales channel a cart is associated with by expanding the `sales_channel` relation and using `cart.sales_channel`. You can also access the ID of the sales channel using `cart.sales_channel_id`.
|
||||
|
||||
### Order
|
||||
|
||||
Orders can optionally be associated with a sales channel. You can filter orders by a sales channel using the Storefront and Admin APIs.
|
||||
|
||||
The relation is implemented in the [Order](../../references/entities/classes/Order.mdx) entity. You can access the sales channel an order is associated with by expanding the `sales_channel` relation and using `order.sales_channel`. You can also access the ID of the sales channel using `order.sales_channel_id`.
|
||||
The relation is implemented in the [Order](../../references/entities/classes/entities.Order.mdx) entity. You can access the sales channel an order is associated with by expanding the `sales_channel` relation and using `order.sales_channel`. You can also access the ID of the sales channel using `order.sales_channel_id`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -89,8 +89,8 @@ If automatic tax calculation is disabled, then the tax calculation strategy will
|
||||
|
||||
The `calculate` method expects three parameters:
|
||||
|
||||
- `items`: the first parameter is an array of [line item](../../../references/entities/classes/LineItem.mdx) objects.
|
||||
- `taxLines`: the second parameter is an array of either [shipping method tax line](../../../references/entities/classes/ShippingMethodTaxLine.mdx) or [line item tax line](../../../references/entities/classes/LineItemTaxLine.mdx) objects.
|
||||
- `items`: the first parameter is an array of [line item](../../../references/entities/classes/entities.LineItem.mdx) objects.
|
||||
- `taxLines`: the second parameter is an array of either [shipping method tax line](../../../references/entities/classes/entities.ShippingMethodTaxLine.mdx) or [line item tax line](../../../references/entities/classes/entities.LineItemTaxLine.mdx) objects.
|
||||
- `calculationContext`: an object holding the context of the tax calculation. The object has the following properties:
|
||||
- `shipping_address`: an optional address object used for shipping.
|
||||
- `customer`: an optional customer object.
|
||||
|
||||
@@ -63,7 +63,7 @@ The invitation process typically follows these steps in the Medusa backend:
|
||||
|
||||
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.mdx#create).
|
||||
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/services.UserService.mdx#create).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user