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

docs for tax-inclusive pricing (#2159)

Browse Source 
* docs for tax-inclusive pricing

* changes based on feedback

* changes based on feedback

* fix link

* fix: make prices optional param when updating a variant (#2155)

**Why**
- It should be possible to update variant props without having to send the prices array with every update

* feat(medusa): Tax-inclusive pricing (#2131)

* add feature flag for tax inclusive pricing

* update db model for TIP

* add migration

* set featureflag column decorators

* remove unused prop

* update tests to reflect feature_flags as any array

* fix types

* reference key from featureFlag file

* use feature flag key in models

* fix copy paste mistake

* unify spelling

* Create gorgeous-experts-guess.md

* feat(medusa): create/update endpoints of currency/region/price-lists/shipping-options should allow to pass includes_tax

* test(integration): continue to add some integration test

* test(integration): continue to add some integration test

* test(unit): Fix region service tests

* fix(medusa): API unit tests flags management

* feat(medusa): Minor cleanup

* style(medusa): Fix typo

* fix(medusa): rebase

* feat(medusa): Replace old tag with the new one

* feat(medusa): revert flag

* feat(medusa): Cleanup

* feat(medusa): feedback

* feat(medusa): Rename currency retrieve method

* test(medudsa): fix unit tests

* chore(medusa): fix oas

* feat(medusa): ShippingMethod should include tax setting from parent option (#2021)

* feat(medusa): Shipping method should includes tax from parent options

* feat(medusa): Condition the includes tax flag to the availability of the feature and add some other tests

* test(integration): Move cart/order ff test in separate files

* fix: snapshots folder

* fix(integration): snapshots

* Create calm-baboons-sit.md

* test(integration): file naming

Co-authored-by: Carlos R. L. Rodrigues <rodrigolr@gmail.com>

* Feat/tax inclusive pricing extend price selection strategy (#2087)

* initial changes to price selection strategy including unit tests

* typing for tax calculation

* update types and remove region and currency from prices results

* fix casing

* include tax calculation in priceselectionstrategy

* integration tests for tax inclusive pricing price calculations

* fix build

* include tax inclusive considerations when calculating tax fields for variants

* include only "includes_tax" fields from currency and region joins

* test to see errors in pipelines

* conditionally join featureflagged fields

* add "includes_tax" to price list factory

* add tests for tax inclusive price list prices and currency prices

* fix unit tests

* refactor pricing array checks to expect arraycontaining

* undo error handler

* Feat/tax inclusive pricing flag on generated lineitems (#2108)

* include tax inclusive pricing flag on generated lineitems

* initial addition of tax inclusivity for lineitem service

* add generate test to ensure that includes_tax is set when returned from price selection strategy

* add integration test for generating lineitem including tax

* add test for negative tax inclusion

* add tests for mixed pricing

* add negative test for setting tax exclusivity

* restructure the setting of includes_tax on lineitems

* fix: update cwd to be correct in cart test

* feat(medusa): Line item totals calculations (#2123)

* feat(medusa): Update totals and tax calculation way to calculate the totals

* feat(medusa): remove region feetching from decorate total

* feat(medusa): cleanup

* test(medusa): fix tax calculation tests

* comment

* test(integration): cleanup

* test(integration): cleanup

* fix(medusa): return service missing await

* feat(medusa): cleanup

* feat(medusa): cleanup

* test(integration): fix data

* feat(medusa): improve tax calculation readability

* test(medusa): improve tax calculation structure case

Co-authored-by: Sebastian Rindom <skrindom@gmail.com>

* Feat(medusa): tax inclusive pricing in shipping method tax (#2125)

* initial implementation and test

* include tax inclusive calculations for getting shipping options

* remove inaccurate comment

* remove console log

* refactor how prices and taxes are set for shipping methods

* fix integration tests

* remove verbose flag

* fix integration tests

* remove console log

* format util

* use util in price service and tax strategy

* fix faulty integration test

* undo tax calculation strategy changes in favor or Carlos' pr

* undo changes to tax calculation strategy tests

* round tax amount

* feat(medusa): cleanup calculate tax amount utils and its usage (#2136)

* feat(medusa): Refund line totals calculation (#2139)

Rely on the update of the following pr https://github.com/medusajs/medusa/pull/2136

**WIP Missing integration tests**

**What**

Update the totals calculation on the refund line to include the notion of tax inclusive

**Test**

- Update and add new tests around the refund


Fixes CORE-482

* feat(medusa): Tax inclusive discounts calculations (#2137)

**What**

- Calculate line adjustments correctly taking into account the tax inclusivity
- fix totals getLineItemTotals by adjusting the sub total with the original tax amount instead of the tax amount when the unit price includes the taxes

**Tests**
- The tests create a cart with a percentage discount of 15%, the cart includes 2 items mixing the tax inclusive and validate the items on the result cart as well as the totals on each item. I ve based my calculation validation based on what we have done + some articles around discount apply on price without taxes to validate the output.,
FIXES CORE-477

* Chore: shipping methods tax inclusive total (#2130)

* chore: calculate tax inclusive shipping methods

* chore: additional tests and check undefined tax_rate (#2157)

* chore: additional tests and check undefined tax_rate

* fix: naming + correct price type check

* fix: remove price_includes_tax from type

* fix: remove price_includes_tax from type

Co-authored-by: Philip Korsholm <philip.korsholm@hotmail.com>
Co-authored-by: adrien2p <adrien.deperetti@gmail.com>
Co-authored-by: Carlos R. L. Rodrigues <rodrigolr@gmail.com>
Co-authored-by: Philip Korsholm <88927411+pKorsholm@users.noreply.github.com>
Co-authored-by: Sebastian Rindom <skrindom@gmail.com>
Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>

* Remove unused QueryBuilderService (#2104)

**Issue number:** #2068

**What:**
- removed unused query-builder service files
  - medusa/src/services/query-builder.js
  - medusa/src/services/__mocks__/query-builder.js
- deleted export from medusa/src/services/index.ts
- (extra) deleted documentation files related to QueryBuilderService (QueryBuilderService.md)

* docs for tax-inclusive pricing

* changes based on feedback

* changes based on feedback

* feat(medusa-fulfillment-webshipper): Support personal customs no in orders (#2167)

* feat(webshipper): support personal customs no in orders

* docs: update readme with personal customs number info

* fix(medusa-file-spaces): return `fileKey` for Spaces upload (#2171)

**What**
- return `fileKey` in the response after the file is uploaded to Spaces

Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>

* fix(medusa): Export/import fixes including export fields that contains new line char (#2150)

* feat(medusa-js,medusa-react,medusa): Add missing Currency endpoints (#2185)

* fix(medusa): Resent notification replaces parent notification

* chore: Bump medusa-file-minio

* fix(medusa): allow address updates on carts w/o existing address (#2176)

* chore: Bump minor version of plugins

* chore: Centralise ESLint rules (#2162)

* chore: centrilize eslint rules

* feat: order editing data model (#2184)

**What**
- add order editing entities
- add repositories
- add a feature flag for the order editing feature
- add the migrations file

RESOLVES CORE-490

* fix link

* fix(medusa): Check for Sales Channel on product import (#2202)

* docs: change title in Create a Service documentation (#2201)

Change title in Create a Service documentation

* chore(release): Publish

* added links to sidebar

Co-authored-by: Sebastian Rindom <skrindom@gmail.com>
Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>
Co-authored-by: Philip Korsholm <philip.korsholm@hotmail.com>
Co-authored-by: adrien2p <adrien.deperetti@gmail.com>
Co-authored-by: Carlos R. L. Rodrigues <rodrigolr@gmail.com>
Co-authored-by: Philip Korsholm <88927411+pKorsholm@users.noreply.github.com>
Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>
Co-authored-by: Dorian <46839236+DorianMazur@users.noreply.github.com>
Co-authored-by: Frane Polić <16856471+fPolic@users.noreply.github.com>
Co-authored-by: Kasper Fabricius Kristensen <45367945+kasperkristensen@users.noreply.github.com>
Co-authored-by: Bhargava Prabu Reddy <prabu0reddy777@gmail.com>
Co-authored-by: olivermrbl <oliver@mrbltech.com>
Co-authored-by: sabakhilji <52318459+sabakhilji@users.noreply.github.com>
This commit is contained in:
Shahed Nasser
2022-09-20 10:34:53 +03:00
committed by GitHub
parent e1e41f5ef2
commit c19788d872
3 changed files with 286 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
docs/content/advanced/backend/taxes/inclusive-pricing.md Normal file
View File

@@ -0,0 +1,188 @@
# Tax Inclusive Pricing
In this document, you’ll learn how tax-inclusive pricing works in Medusa.
:::note
Tax Inclusive Pricing is currently in beta mode and guarded by a feature flag. To enable it, set the environment variable `MEDUSA_FF_TAX_INCLUSIVE_PRICING` to `true`, and [run migrations](../migrations/index.md#run-migration).
:::
## Introduction
Tax Inclusive pricing allows you to set the final prices for products and shipping options regardless of the customer's applicable tax rates. When tax-inclusive prices are used, Medusa automatically calculates the tax amount for a given price.
This can be useful when some countries have the same currency but have different tax rates. If you want your prices to be the same across these countries, you have to manage two price lists to account for the tax differences. Using tax-inclusive pricing you only have to specify the price once.
Then, Medusa handles calculating the tax amount using the tax rate and the tax-inclusive price. This is managed in the backend and relayed to accounting and analytics tools.
## How is Tax Inclusivity Defined?
Tax inclusivity can be toggled for regions, currencies, price lists, and shipping options either during creation or while editing. This is represented by the boolean attribute `includes_tax` available in the entities `Region`, `Currency`, `PriceList`, and `ShippingOption`. By default, this attribute is set to `false`.
If you want to enable or disable this attribute for any of these entities, you can use the create or update endpoints related to these entities as shown in the [Admin API reference](https://docs.medusajs.com/api/admin/).
The value set for these entities can affect whether line items and shipping methods are tax inclusive or not.
### How is Tax Inclusivity Defined for Line Items?
:::info
When a product is added to the cart, a line item is created to represent that product in the cart.
:::
The `LineItem` entity also has the `includes_tax` attribute. The value of this flag is set to `true` if:
- The region of the line item has the `includes_tax` attribute set to `true`;
- Or the currency of the line item has the `includes_tax` attribute set to `true`;
- Or a price list that includes the product variant associated with the line item has the `includes_tax` attribute set to `true`, and the tax-inclusive amount of one of the variant’s prices in the price list is less than the original price of the variant;
- Or one of the variant’s prices in the price list uses a currency or region that has the `includes_tax` attribute set to `true`, and the tax-inclusive amount of the price is less than the original price of the variant.
### How is Tax Inclusivity Defined for Shipping Methods?
:::info
When a shipping option is selected, a shipping method is created based on that shipping option. You can learn more about this in the [Shipping Architecture documentation](../shipping/overview.md).
:::
The `ShippingMethod` entity also has the `includes_tax` attribute. Its value is the same as the value of `includes_tax` of the shipping option the method is associated with.
## Tax Amount Calculation Formula
When a price is tax-inclusive, the tax amount is calculated using the following formula:
```jsx
const taxAmount = (taxRate * taxInclusivePrice) / (1 + taxRate)
```
Where `taxRate` is the tax rate to be applied to the price, and `taxInclusivePrice` is the price entered by the store operator.
For example, if the tax rate is `0.25` and the price of a product is `100`, the resulting tax amount calculated by Medusa will be `0.25 * 100 / 1.25 = 20`.
## Retrieving Tax Amounts
This section covers at which point tax amounts are calculated for different entities, how they are calculated when the price is tax inclusive, and what fields can be returned in the endpoints relative to each of the entities.
:::note
If you have disabled the automatic calculation of taxes in a region, you must [manually calculate the taxes of the line items and the cart](manual-calculation.md). Otherwise, taxes will not be calculated or retrieved during checkout for each entity mentioned here.
:::
### Products
Taxes are calculated for each product variant either when a [single product is retrieved](https://docs.medusajs.com/api/store/#tag/Product/operation/GetProductsProduct) or a [list of products is retrieved](https://docs.medusajs.com/api/store/#tag/Product/operation/GetProducts).
Among the pricing fields retrieved for each variant, the following fields are relevant to taxes:
- `original_price`: The original price of the variant.
- `calculated_price`: The calculated price, which can be based on prices defined in a price list.
- `original_tax`: The tax amount applied to the original price.
- `calculated_tax`: The tax amount applied to the calculated price.
- `original_price_incl_tax`: The price after applying the tax amount on the original price.
- `calculated_price_incl_tax`: The price after applying the tax amount on the calculated price
- `original_price_includes_tax`: a boolean value indicating whether the amount in `original_price` includes the tax amount by default or not.
- `calculated_price_includes_tax`: a boolean value indicating whether the amount in `calculated_price` includes the tax amount by default or not.
If tax inclusivity is enabled for the current region or currency (based on whether the default price is specified for the region or currency, with region taking a higher precedence):
- `original_price` will include the tax amount by default.
- `original_price_includes_tax` will be set to `true`.
- `original_price_incl_tax` will have the same amount as `original_price`.
- `original_tax` is automatically calculated by Medusa.
Also, for each of the product variant’s prices in a price list, if tax inclusivity is enabled (either if the price list itself has the `includes_tax` attribute set to `true`, or the variant’s price in the price list uses a currency or region that has the `includes_tax` attribute set to `true`), and the amount of the price is less than the original price of the variant:
- `calculated_tax` will include the tax amount by default.
- `calculated_price_includes_tax` will be set to `true`.
- `calculated_price_incl_tax` will have the same amount as `calculated_price`.
:::info
Price lists include a list of prices that can be used to override the original price of a product’s variants.
Each variant’s price in the price list is compared to the variant’s original price using the following condition:
```jsx
amount < (1 + taxRate) * calculatedPrice
```
Where `amount` is the amount of the variant’s price in the price list, `taxRate` is the applied rate, and `calculatedPrice` is the original price of the variant.
:::
Here is an example of these fields when tax inclusivity is enabled for both the currency and the price list:
```jsx
{
original_price: 110,
calculated_price: 100,
calculated_price_type: "sale",
original_price_includes_tax: true,
calculated_price_includes_tax: true,
calculated_price_incl_tax: 100,
calculated_tax: 20,
original_price_incl_tax: 110,
original_tax: 22,
}
```
### Line Item
The taxes of line items are calculated and retrieved whenever the [cart is retrieved or updated](https://docs.medusajs.com/api/store/#tag/Cart).
Each line item returned in any of the cart’s requests has total fields related to the price of the line item and its taxes. Among those fields, the following are relevant to tax-inclusive pricing:
- `unit_price`: The original price of the variant associated with the line item.
- `tax_total`: The total tax amount applied on the original price taking into account any applied discounts as well.
- `original_tax_total`: The total tax amount applied on the original price without taking into account any applied discounts.
- `subtotal`: The total of the line item’s price subtracting the amount in `original_tax_total`.
- `origial_total`: The `subtotal` including the `original_tax_total` amount.
If tax inclusivity is enabled for the line item, `unit_price` will include the tax amount. The tax amount, which will also be the value of `tax_total`, is calculated using [Medusa’s formula for tax inclusive pricing](#tax-amount-calculation-formula) based on the line item’s tax rates. The calculation takes into account any discounts applied on the item, which means the discount amount is deducted from the original price.
Then, the `subtotal` is calculated by subtracting the `tax_total` from the total of the line item’s price. `original_total` has the same value as `subtotal`.
:::info
The total of the line item’s price is the variant’s `unit_price` multiplied by its quantity in the cart.
:::
Finally, `original_tax_total` undergoes the same `tax_total` calculation, however, any discounts applied on the line item are not taken into account. This means the discount amount is not deducted from the original price.
### Shipping Options
Taxes for Shipping Options are calculated and retrieved when the [list of shipping options is retrieved](https://docs.medusajs.com/api/store/#tag/Shipping-Option).
Among the returned fields for each shipping option, the following are relevant to each of their pricing and taxes:
- `amount`: The original price of the shipping option.
- `price_incl_tax`: The price of the shipping option with tax included.
- `tax_amount`: The tax amount applied to the shipping option.
If tax inclusivity is enabled for the shipping option, `amount` and `price_incl_tax` have the same value. Also, the value of `tax_amount` is calculated using [Medusa’s formula for tax inclusive pricing](#tax-amount-calculation-formula).
### Carts and Orders
Carts and Orders have the same total fields relevant for taxes.
A cart’s totals, including its taxes, are calculated and retrieved whenever the cart is [updated or retrieved](https://docs.medusajs.com/api/store/#tag/Cart).
An order’s totals, including its taxes, are calculated and retrieved whenever the order is retrieved both on the [storefront](https://docs.medusajs.com/api/store/#tag/Order) and on the [admin](https://docs.medusajs.com/api/admin/#tag/Order).
The relevant fields are:
- `shipping_total`: The total tax-exclusive price of the shipping methods used in the cart or order without any applied taxes.
- `tax_total`: The total of the taxes applied on the cart or order, including taxes applied on line items and shipping methods.
- `subtotal`: The subtotal of line items including taxes, but without shipping total.
- `total`: The total of the cart or order, including the subtotal, shipping total, and taxes applied.
During the calculation of the totals of different components of the cart or order, such as shipping or line items, if tax inclusivity is enabled on that component, a process similar to those explained above will be applied to retrieve the total.
## What’s Next 🚀
- Learn how to [calculate taxes manually](manual-calculation.md).
- [Check out the API reference](https://docs.medusajs.com/api/store/).

88
docs/content/advanced/backend/taxes/manual-calculation.md Normal file
View File

@@ -0,0 +1,88 @@
# Calculate Taxes Manually in Checkout
In this document, you’ll learn how to manually calculate taxes during checkout if you have automatic tax calculation disabled in a region.
## Overview
By default, taxes are automatically calculated by Medusa during checkout. This behavior can be disabled for a region using the Admin APIs or the Medusa admin to limit the requests being sent to a tax provider.
If you disable this behavior, you must manually trigger taxes calculation. When taxes are calculated, this means that requests will be sent to the tax provider to retrieve the tax rates.
## How to Manually Calculate Taxes in Checkout?
This section explores different ways you can calculate taxes based on your purpose.
### Use Calculate Cart Taxes Endpoint
The [Calculate Cart Taxes](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartTaxes) endpoint forces the calculation of taxes for a cart during checkout. This bypasses the option set in admin to not calculate taxes automatically, which results in sending requests to the tax provider.
This calculates and retrieves the taxes on the cart and each of the line items in that cart.
### Use CartService
The `CartService` class has a method `retrieve` that gets a cart by ID. In that method, taxes are calculated only if automatic taxes calculation is enabled for the region the cart belongs to.
You can, however, force calculating the taxes of the cart by passing in the third parameter an option containing the key `force_taxes` with its value set to `true`.
For example:
```jsx
cartService.retrieve('cart_01G8Z...', { }, { force_taxes: true });
```
:::tip
You can learn how to [retrieve and use services](../services/create-service.md#using-your-custom-service) in this documentation.
:::
### Use decorateLineItemsWithTotals function in Endpoints
If you want to calculate the taxes of line items on the storefront in an endpoint and return the necessary fields in the result, you can use the `decorateLineItemsWithTotals` method in your endpoint:
```jsx
//at the beginning of the file
import { decorateLineItemsWithTotals } from "@medusajs/medusa/dist/api/routes/store/carts/decorate-line-items-with-totals"
export default () => {
//...
router.get("/store/line-taxes", async (req, res) => {
//example of retrieving cart
const cartService = req.scope.resolve("cartService");
const cart = await cartService.retrieve(cart_id)
//...
//retrieve taxes of line items
const data = await decorateLineItemsWithTotals(cart, req, {
force_taxes: true
});
return res.status(200).json({ cart: data });
})
}
```
The `decorateLineItemsWithTotals` method accepts an options object as a third parameter. If you set `force_taxes` to `true` in that object, the totals of the line items can be retrieved regardless of whether the automatic calculation is enabled in the line item’s region.
### Use TotalsService
You can calculate and retrieve taxes of line items using the `getLineItemTotals` method available in the `TotalService` class. All you need to do is pass in the third argument to that method an options object with the key `include_tax` set to true:
```jsx
const itemTotals = await totalsService
.getLineItemTotals(item, cart, {
include_tax: true
})
```
:::tip
You can learn how to [retrieve and use services](../services/create-service.md#using-your-custom-service) in this documentation.
:::
## What’s Next 🚀
- Learn about [tax-inclusive pricing](inclusive-pricing.md).
- Learn about available methods in [CartsService](../../../references/services/classes/CartService.md) and [TotalsService](../../../references/services/classes/TotalsService.md).

10
www/docs/sidebars.js
View File

@@ -262,6 +262,11 @@ module.exports = {
id: "advanced/admin/import-products",
label: "Import Products"
},
{
type: "doc",
id: "advanced/backend/taxes/manual-calculation",
label: "Calculate Taxes Manually"
},
]
},
]
@@ -315,6 +320,11 @@ module.exports = {
id: "advanced/backend/batch-jobs/index",
label: "Batch Jobs"
},
{
type: "doc",
id: "advanced/backend/taxes/inclusive-pricing",
label: "Tax Inclusive Pricing"
},
]
},
{