From e4157875b5c4adf7e141253f087abe116b3029ef Mon Sep 17 00:00:00 2001
From: Nick Miller <965744+nickmonad@users.noreply.github.com>
Date: Mon, 6 Nov 2023 11:12:56 -0600
Subject: [PATCH] docs(create tax provider): tax line code required (#5540)

While I was developing a custom tax provider, I ran into a pretty frustrating issue related to multiple tax lines and incorrect / unexpected tax total calculations. I outlined the issue in discord, before finding the solution: https://discord.com/channels/876835651130097704/1169705457804398662

After some digging, I found this issue from a while back: https://github.com/medusajs/medusa/pull/1262, where it states there is now a unique constraint on `item_id, code` and `shipping_method_id, code`. But, in the current documentation for creating a custom tax provider, it states these fields as part of the tax line items returned are optional.

If these `code` values are left out, it can cause tax lines to be applied multiple times (as seen here as well: https://github.com/medusajs/medusa/issues/1901)

I'm not entirely sure how this should be phrased in the documentation, so I just wanted to get this up and on your radar for resolution. If it ends up being that `code` truly should not be optional, I suspect some type definitions would need to change as well?
---
 .../modules/taxes/backend/create-tax-provider.md | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/www/apps/docs/content/modules/taxes/backend/create-tax-provider.md b/www/apps/docs/content/modules/taxes/backend/create-tax-provider.md
index ed7a78a954..23e723f187 100644
--- a/www/apps/docs/content/modules/taxes/backend/create-tax-provider.md
+++ b/www/apps/docs/content/modules/taxes/backend/create-tax-provider.md
@@ -127,18 +127,30 @@ The line item tax line object has the following properties:
 
 - `rate`: a number indicating the tax rate.
 - `name`: a string indicating the name of the tax rate.
-- `code`: an optional string indicating the tax code.
+- `code`: a string indicating the tax code.
 - `item_id`: the ID of the line item.
 - `metadata`: an optional object that can hold any necessary additional data to be added to the line item tax lines.
 
+:::note
+
+Tax lines for line item must have a unique `code` and `item_id` combination. Otherwise, the tax lines will be applied multiple times.
+
+:::
+
 The shipping method tax line object has the following properties:
 
 - `rate`: a number indicating the tax rate.
 - `name`: a string indicating the name of the tax rate.
-- `code`: an optional string indicating the tax code.
+- `code`: a string indicating the tax code.
 - `shipping_method_id`: the ID of the shipping method.
 - `metadata`: an optional object that can hold any necessary additional data to be added to the shipping method tax lines.
 
+:::note
+
+Tax lines for a shipping method must have a unique `code` and `shipping_method_id` combination. Otherwise, the tax lines will be applied multiple times.
+
+:::
+
 The returned array would be a combination of both the line item tax lines and shipping method tax lines.
 
 :::note