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
@@ -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:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user