6f1b49af03
* Fix issue on fixed total amount discount when using includes tax (#3472) The calculation of the fixed discount amount breaks when having includes_tax setting active, due to the line item totals are incorrect and returning everything as 0, thus the totalItemPercentage will be Infinitiy due to the division by a subtotal of 0 * chore: Add missing changeset for @medusajs/medusa * feat(medusa): Improve performance of Products domain (#3417) * feat(medusa): Improve product update performances * fix tests and update * update mock repo * improve repo * cleanup * fix * cleanup + bulk emit + unit test fix * improvements * improve * fix unit tests * fix export * fix product update handler * enhance mock repo * fix import integration * fix end point tests * revert mock repo product variant * fix unit * cleanup * cleanup * address feedback * fix quotes in tests * address feedback * Create new-tips-mate.md * use types * chore: Remove integration-tests from changeset * chore(release): v1.7.14 * chore(docs): Generated Docs Announcement Bar (automated) (#3489) Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com> * fix(medusa): EventBusService.emit using Redis mock (#3491) * Fix eventBusService.emit using redis mock * revert gitignore * enqueuer * unit test add redis_url * fix test * chore(docs): Generated Services Reference (automated) (#3490) Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com> * docs: publish restructure (#3496) * docs: added features and guides overview page * added image * added version 2 * added version 3 * added version 4 * docs: implemented new color scheme * docs: redesigned sidebar (#3193) * docs: redesigned navbar for restructure (#3199) * docs: redesigned footer (#3209) * docs: redesigned cards (#3230) * docs: redesigned admonitions (#3231) * docs: redesign announcement bar (#3236) * docs: redesigned large cards (#3239) * docs: redesigned code blocks (#3253) * docs: redesigned search modal and page (#3264) * docs: redesigned doc footer (#3268) * docs: added new sidebars + refactored css and assets (#3279) * docs: redesigned api reference sidebar * docs: refactored css * docs: added code tabs transition * docs: added new sidebars * removed unused assets * remove unusued assets * Fix deploy errors * fix incorrect link * docs: fixed code responsivity + missing icons (#3283) * docs: changed icons (#3296) * docs: design fixes to the sidebar (#3297) * redesign fixes * docs: small design fixes * docs: several design fixes after restructure (#3299) * docs: bordered icon fixes * docs: desgin fixes * fixes to code blocks and sidebar scroll * design adjustments * docs: restructured homepage (#3305) * docs: restructured homepage * design fixes * fixed core concepts icon * docs: added core concepts page (#3318) * docs: restructured homepage * design fixes * docs: added core concepts page * changed text of different components * docs: added architecture link * added missing prop for user guide * docs: added regions overview page (#3327) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page (#3331) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page * fix link * resolve link issues * docs: updated regions architecture image * docs: second-iteration fixes (#3347) * docs: redesigned document * design fixes * docs: added products overview page (#3354) * docs: added carts overview page (#3363) * docs: added orders overview (#3364) * docs: added orders overview * added links in overview * docs: added vercel redirects * docs: added soon badge for cards (#3389) * docs: resolved feedback changes + organized troubleshooting pages (#3409) * docs: resolved feedback changes * added extra line * docs: changed icons for restructure (#3421) * docs: added taxes overview page (#3422) * docs: added taxes overview page * docs: fix sidebar label * added link to taxes overview page * fixed link * docs: fixed sidebar scroll (#3429) * docs: added discounts overview (#3432) * docs: added discounts overview * fixed links * docs: added gift cards overview (#3433) * docs: added price lists overview page (#3440) * docs: added price lists overview page * fixed links * docs: added sales channels overview page (#3441) * docs: added sales overview page * fixed links * docs: added users overview (#3443) * docs: fixed sidebar border height (#3444) * docs: fixed sidebar border height * fixed svg markup * docs: added possible solutions to feedback component (#3449) * docs: added several overview pages + restructured files (#3463) * docs: added several overview pages * fixed links * docs: added feature flags + PAK overview pages (#3464) * docs: added feature flags + PAK overview pages * fixed links * fix link * fix link * fixed links colors * docs: added strategies overview page (#3468) * docs: automated upgrade guide (#3470) * docs: automated upgrade guide * fixed vercel redirect * docs: restructured files in docs codebase (#3475) * docs: restructured files * docs: fixed eslint exception * docs: finished restructure loose-ends (#3493) * fixed uses of backend * docs: finished loose ends * eslint fixes * fixed links * merged master * added update instructions for v1.7.12 * docs: fixed discount details (#3499) * docs: fix trailing slash causing 404 (#3508) * docs: fix error during navigation (#3509) * docs: removed the gatsby storefront guide (#3527) * docs: removed the gatsby storefront guide * docs: fixed query value * chore(docs): Removed Docs Announcement Bar (automated) (#3536) Co-authored-by: shahednasser <shahednasser@users.noreply.github.com> * fix(medusa): Variant update should include the id for the listeners to be able to identify the entity (#3539) * fix(medusa): Variant update should include the id for the listeners to be able to identify the entity * fix unit tests * Create brave-seahorses-film.md * docs: fix admin redirects (#3548) * chore(release): v1.7.15 * chore(docs): Generated Docs Announcement Bar (automated) (#3550) Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com> * chore(docs): Generated Services Reference (automated) (#3551) Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> * chore: updated READMEs of plugins (#3546) * chore: updated READMEs of plugins * added notice to plugins * docs: added a deploy guide for next.js storefront (#3558) * docs: added a deploy next.js guide * docs: fix image zoom * docs: fixes to next.js deployment guide to vercel (#3562) * chore(workflows): Enable manual workflow in pre-release mode (#3566) * chore(docs): Removed Docs Announcement Bar (automated) (#3598) Co-authored-by: shahednasser <shahednasser@users.noreply.github.com> * fix(medusa): Rounding issues on line item adjustments (#3446) * chores(medusa): Attempt to fix discount rounding issues * add migration * update entities * apply multipler factor properly * fix discount service * WIP * fix rounding issues in discounts * fix some tests * Exclude raw_discount_total from responses * fix adjustments * cleanup response * fix * fix draft order integration * fix order integration * fix order integration * address feedback * fix test * Create .changeset/polite-llamas-sit.md * remove comment --------- Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> * chore(workflows): Add release notification (#3629) --------- Co-authored-by: pepijn-vanvlaanderen <pepijn@webbers.com> Co-authored-by: olivermrbl <oliver@mrbltech.com> Co-authored-by: Adrien de Peretti <adrien.deperetti@gmail.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com> Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com> Co-authored-by: shahednasser <shahednasser@users.noreply.github.com> Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>
11 KiB
description
| description |
|---|
| Learn how the shipping architecture is implemented in the Medusa backend. This includes an overview of what the Fulfillment Provider, Shipping Profile, Shipping Option, and Shipping Methods. |
Shipping Architecture Overview
This document gives an overview of the shipping architecture and its four most important components.
Introduction
In Medusa, the Shipping architecture relies on 4 components: Fulfillment Provider, Shipping Profiles, Shipping Options, and Shipping Methods.
The distinction between the four is important. It has been carefully planned and put together to support all the different ecommerce use cases and shipping providers that can be integrated.
It’s also constructed to support multiple regions, provide different shipment configurations and options for different product types, provide promotional shipments for your customers, and much more.
Summary
- Fulfillment Provider: Fulfillment providers are plugins or Services used to ship the products to your customers, whether physically or virtually. An example of a fulfillment provider would be FedEx.
- Shipping Profiles: created by the admin. They are used to group products that should be shipped in a different manner than the default. Shipping profiles can have multiple shipping options.
- Shipping Options: created by the admin and belong to a shipping profile. They are specific to certain regions and can have cart conditions. They use an underlying fulfillment provider. Once a customer checks out, they can choose the shipping option that’s available and most relevant to them.
- Shipping Method: created when the customer chooses a shipping option on checkout. The shipping method is basically a copy of the shipping option, but with values specific to the customer and the cart it’s associated with. When the order is placed, the shipping method will then be associated with the order and fulfilled based on the integration with the fulfillment provider.
Fulfillment Provider
A Fulfillment Provider in Medusa is a method to handle shipping products in selected regions. It is not associated with a cart, customer, or order in particular.
It provides the necessary implementation to create Fulfillments for orders and ship items to customers. They can also be used for order returns and swaps.
Fulfillment Providers can be integrated with third-party services that handle the actual shipment of products. An example of a Fulfillment Provider is FedEx.
Fulfillment Providers can also be related to a custom way of handling fulfillment operations. An example of that is Medusa’s manual fulfillment provider plugin which provides a minimal implementation of a fulfillment provider and allows store operators to manually handle order fulfillments.
How Fulfillment Provider is Created
A Fulfillment Provider is essentially a Medusa Service with a unique identifier, and it extends the FulfillmentService provided by the medusa-interfaces package. It can be created as part of a plugin, or it can be created just as a Service file in your Medusa backend.
As a developer, you will mainly work with the Fulfillment Provider when integrating a fulfillment method in Medusa.
When you run your Medusa backend, the Fulfillment Provider will be registered on your backend if it hasn’t been already.
Once the Fulfillment Provider is added to the backend, the store operator will be able to associate on the Medusa Admin the Fulfillment Provider with shipping options.
FulfillmentProvider Entity Overview
The FulfillmentProvider 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.
Shipping Profile
Shipping profiles are the highest in the hierarchy in the shipping architecture.
Shipping profiles are created by the admin. The admin can specify the name of the shipping profile which will be a name that the customer can see.
A shipping profile is not associated with any fulfillment providers. It has multiple shipping options that can be associated with different providers.
Purpose of Shipping Profile
Shipping profiles are used to group products that can be shipped in the same manner.
The default shipping profile is one that groups all of your store’s products. You also get a shipping profile that’s specific to gift cards. This is because, generally speaking, all products would be delivered similarly, whereas gift cards would be delivered in different behavior.
Although this might be the general case, there are still some use cases where you will have a set of products that should be shipped differently than others.
For example, shipping heavy items might be more expensive than others, which would enforce different price rates. In that case, you can create a new shipping profile that groups together heavy products. This would allow you to give these products more suitable price rates when creating their shipping options.
ShippingProfile Entity Overview
The ShippingProfile 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.
The ShippingProfile entity also has an array of ShippingOption instances.
Shipping Option
After the admin adds a shipping profile, they can add shipping options that belong to that shipping profile from the admin dashboard.
Shipping options have a set of conditions like the region they’re available in or cart-specific conditions. For example, if your company operates in the United States as well as Germany, you might use a different shipping option for each of the two countries.
Among the configurations that the admin has to set when creating a shipping option is specifying the fulfillment provider it uses. This means that when you create a plugin for a fulfillment provider, that provider needs to be chosen as the fulfillment provider of a shipping option to be used in the store.
Shipping options are only shown to a customer during checkout if their cart satisfies the option’s conditions. Also, as they belong to a shipping profile, they’re only shown when products that belong to the same shipping profile are in the cart.
Purpose of Shipping Option
The first purpose that a shipping option has is showing the customer during checkout what shipping options are available for them.
Then, once the customer chooses a shipping option, that shipping option is used to create a shipping method with details specific to the customer and their cart. Then, the shipping method is associated with the cart, and the shipping option remains untouched.
Think of a shipping option as a template defined by the admin that indicates what data and values the shipping method should have when it’s chosen by the customer during checkout.
ShippingOption Entity Overview
The ShippingOption 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.
It has the price_type attribute to indicate whether the shipping option’s rate is calculated by the provider or a fixed flat_rate price. It also has the amount attribute to set an amount for the shipping option if the price_type is flat_rate.
ShippingOption also belongs to a Region, which resembles one or more countries. This defines where the shipping option is available.
ShippingOption has a set of ShippingOptionRequirement instances. The ShippingOptionRequirement entity allows defining cart rules which determine whether the shipping option will be available or not for a customer during checkout. For example, you can set a minimum subtotal amount for a shipping option to be available for a customer’s cart.
The is_return attribute is used to indicate whether the shipping option is used for shipping orders or returning orders. Shipping options can only be used for one or the other.
The data attribute is used to specify any data necessary for fulfilling the shipment based on the underlying fulfillment provider. When you integrate a fulfillment provider, you can check in that provider’s documentation for any data necessary when creating a new shipment.
The data attribute does not have any specific format. It’s up to you to choose whatever data is included here.
Shipping Method
Unlike the previous two components, a shipping method is not created by the admin. It’s created when a POST request is sent to /store/carts/:id/shipping-methods after the customer chooses a shipping option.
The shipping method will be created based on the chosen shipping option and it’ll be associated with the customer’s cart. Then, when the order is placed, the shipping method is associated with the order.
A shipping method can be fulfilled automatically or manually through the admin dashboard. This is based on the fulfillment provider associated with the shipping option the shipping method is based on.
Shipping Method Purpose
It’s important to understand the distinction between shipping methods and shipping options. Shipping options are templates created by the admin to indicate what shipping options should be shown to a customer. This provides customization capabilities in a store, as an admin is free to specify configurations for that option such as what fulfillment provider it uses or what are its rates.
When handling the order and fulfilling it, you, as a developer, will be mostly interacting with the shipping method.
This separation allows for developers to implement the custom integration with third-party fulfillment providers as necessary while also ensuring that the admin has full control of their store.
ShippingMethod Entity Overview
A lot of the shipping method’s attributes are similar to the shipping option’s attribute.
The ShippingMethod 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.
The ShippingMethod belongs to a Cart. This is the cart the customer is checking out with.
The ShippingMethod also belongs to the Order entity. This association is accomplished when the order is placed.
The ShippingMethod instance holds a price attribute, which will either be the flat rate price or the calculated price.