Updated API from documentation release

api-specs/api/types/cart/TaxMode.raml

@@ -11,24 +11,33 @@ enum:
   - Disabled
 (enumDescriptions):
   Platform: |
-    Tax Rates are selected automatically from the [TaxCategories](ctp:api:type:TaxCategory) based on the [Cart](ctp:api:type:Cart) `shippingAddress`.
+    - Tax Rates are selected automatically from the [TaxCategories](ctp:api:type:TaxCategory) based on the [Cart](ctp:api:type:Cart) `shippingAddress`.
     This is the default tax mode for a new Cart.
 
-    `totalNet`, `totalGross`, and `taxPortions` fields are calculated based on the `taxRoundingMode`.
+    - The `totalNet`, `totalGross`, and `taxPortions` fields are calculated based on the `taxRoundingMode`.
   External: |
-    Tax Rates are set externally per [ExternalTaxRateDraft](ctp:api:type:ExternalTaxRateDraft).
+    - Tax Rates are set externally with [ExternalTaxRateDraft](ctp:api:type:ExternalTaxRateDraft).
     A Cart can be ordered only if all Line Items, Custom Line Items, and the Shipping Method have an external Tax Rate set.
 
-    `totalNet`, `totalGross`, and `taxPortions` fields are calculated based on the `taxRoundingMode`.
+    - The `totalNet`, `totalGross`, and `taxPortions` fields are calculated based on the `taxRoundingMode`.
   ExternalAmount: |
-    Tax amounts, Tax Rates, and tax portions are set externally per [ExternalTaxAmountDraft](ctp:api:type:ExternalTaxAmountDraft).
+    - Tax amounts, Tax Rates, and tax portions are set externally with [ExternalTaxAmountDraft](ctp:api:type:ExternalTaxAmountDraft).
     A Cart can be ordered only if the Cart and all Line Items, Custom Line Items, and the Shipping Method have an external tax amount and rate set.
 
-    Price-specific update actions on Carts require external recalculation of the total gross price.
-    Hence, the `externalTaxAmount` is removed in these cases and must be reset with [Set LineItem TaxAmount](ctp:api:type:CartSetLineItemTaxAmountAction), [Set CustomLineItem TaxAmount](ctp:api:type:CartSetCustomLineItemTaxAmountAction), or [Set ShippingMethod TaxAmount](ctp:api:type:CartSetShippingMethodTaxAmountAction) update actions.
-    Also the Cart `taxedPrice` field must be explicitly set via [Set Cart Total Tax](ctp:api:type:CartSetCartTotalTaxAction).
-    Since the API currently does not offer an update action for setting the `taxedShippingPrice` field of a Cart with `ExternalAmount` tax mode, it will always be empty.
-  Disabled: |
-    No taxes are added to the Cart.
+    - The Cart `taxedPrice` field must be set using [Set Cart Total Tax](ctp:api:type:CartSetCartTotalTaxAction). The Cart `taxedShippingPrice` field is always empty in this tax mode.
+
+    - Price-affecting update actions on Carts require external recalculation of the total gross price. In these cases, `taxedPrice` and `taxRate` are removed and must be set again. The order in which the individual update actions are issued is important:
+      1. Issue the price-affecting update action(s).
+      2. Update the tax amounts using [Set LineItem TaxAmount](ctp:api:type:CartSetLineItemTaxAmountAction), [Set CustomLineItem TaxAmount](ctp:api:type:CartSetCustomLineItemTaxAmountAction), or [Set ShippingMethod TaxAmount](ctp:api:type:CartSetShippingMethodTaxAmountAction).
+
+          - If the update action changes the Line Item price, for Line Items with `Platform` [LineItemPriceMode](ctp:type:LineItemPriceMode), you must issue [Set LineItem TaxAmount](ctp:api:type:CartSetLineItemTaxAmountAction) in a _separate_ request.
+
+          - If the update action removes the externally set tax amount for the Shipping Method, you must issue [Set ShippingMethod TaxAmount](ctp:api:type:CartSetShippingMethodTaxAmountAction) in a _separate_ request.
 
-    Note that this tax mode cannot be set on the [My Carts](/../api/projects/me-carts) API.
+      3. Update the `taxedPrice` on Cart using [Set Cart Total Tax](ctp:api:type:CartSetCartTotalTaxAction).
+
+    - Tax-inclusive pricing should be avoided when using TaxMode `ExternalAmount` because `taxedItemPrice.totalNet` is automatically set by the platform to the Line Item's `totalPrice`.
+
+  Disabled: |
+    - No taxes are added to the Cart.
+    - This tax mode cannot be set on the [My Carts](/../api/projects/me-carts) API.

api-specs/api/types/cart/updates/CartSetCartTotalTaxAction.raml

@@ -5,7 +5,8 @@ displayName: CartSetCartTotalTaxAction
 discriminatorValue: setCartTotalTax
 example: !include ../../../examples/Cart/CartSetCartTotalTaxAction.json
 description: |
-  This update action results in the `taxedPrice` field being added to the Cart when the `ExternalAmount` [TaxMode](ctp:api:type:TaxMode) is used.
+  Can be used if the Cart has the `ExternalAmount` [TaxMode](ctp:api:type:TaxMode). This update action adds the `taxedPrice` field to the Cart and must be used after any price-affecting change occurs within the Cart.
+
 properties:
   externalTotalGross:
     type: Money

api-specs/api/types/cart/updates/CartSetLineItemTaxAmountAction.raml

@@ -5,7 +5,8 @@ displayName: CartSetLineItemTaxAmountAction
 discriminatorValue: setLineItemTaxAmount
 example: !include ../../../examples/Cart/CartSetLineItemTaxAmountAction.json
 description: |
-  Can be used if the Cart has the `ExternalAmount` [TaxMode](ctp:api:type:TaxMode).
+  Can be used if the Cart has the `ExternalAmount` [TaxMode](ctp:api:type:TaxMode). This update action sets the `taxedPrice` and `taxRate` on a Line Item and must be used after any price-affecting change occurs.
+
 properties:
   lineItemId?:
     type: string

api-specs/api/types/order-edit/updates/StagedOrderSetLineItemTaxAmountAction.raml

@@ -5,7 +5,8 @@ type: StagedOrderUpdateAction
 displayName: StagedOrderSetLineItemTaxAmountAction
 discriminatorValue: setLineItemTaxAmount
 description: |
-  Can be used if the Cart has the `ExternalAmount` [TaxMode](ctp:api:type:TaxMode).
+  Can be used if the Cart has the `ExternalAmount` [TaxMode](ctp:api:type:TaxMode). This update action sets the `taxedPrice` and `taxRate` on a Line Item and must be used after any price-affecting change occurs.
+
 properties:
   lineItemId?:
     type: string