Updated api-reference from documentation release

commercetools · May 30, 2024 · e96def6 · e96def6
1 parent cf10210
commit e96def6
Show file tree

Hide file tree

Showing 50 changed files with 108 additions and 97 deletions.
diff --git a/api-specs/api/resources/products.raml b/api-specs/api/resources/products.raml
@@ -25,7 +25,7 @@ get:
   is:
     - priceSelecting
   description: |-
-    If [Price selection](ctp:api:type:ProductPriceSelection) query parameters are provided, the selected Prices are added to the response.
+    If [Product price selection query parameters](/../api/pricing-and-discounts-overview#product-price-selection) are provided, the selected Prices are added to the response.
   queryParameters:
     where:
       type: QueryPredicate[]
@@ -54,7 +54,7 @@ post:
   securedBy: [oauth_2_0: { scopes: ['manage_products:{projectKey}'] }]
   description: |
     To create a new Product, send a representation that is going to become the initial _staged_ and _current_ representation of the new Product in the catalog.
-    If [Price Selection](ctp:api:type:ProductPriceSelection) query parameters are provided, selected Prices will be added to the response.
+    If [Product price selection query parameters](/../api/pricing-and-discounts-overview#product-price-selection) are provided, selected Prices will be added to the response.
     Produces the [ProductCreated](/projects/messages#product-created) Message.
   is:
     - priceSelecting
@@ -78,7 +78,7 @@ post:
     is:
       - priceSelecting
     description: |-
-      If [Price selection](ctp:api:type:ProductPriceSelection) query parameters are provided, the selected Prices are added to the response.
+      If [Product price selection query parameters]](/../api/pricing-and-discounts-overview#product-price-selection) are provided, the selected Prices are added to the response.
     responses:
       200:
         body:
@@ -102,7 +102,7 @@ post:
             example: !include ../examples/product.example.json
   delete:
     description: |-
-      If [Price selection](ctp:api:type:ProductPriceSelection) query parameters are provided, the selected Prices are added to the response.
+      If [Product price selection query parameters](/../api/pricing-and-discounts-overview#product-price-selection) are provided, the selected Prices are added to the response.
       Produces the [ProductDeleted](/projects/messages#product-deleted) Message.
     securedBy: [oauth_2_0: { scopes: ['manage_products:{projectKey}'] }]
     is:
@@ -139,7 +139,7 @@ post:
     is:
       - priceSelecting
     description: |-
-      If [Price selection](ctp:api:type:ProductPriceSelection) query parameters are provided, the selected Prices are added to the response.
+      If [Product price selection query parameters](/../api/pricing-and-discounts-overview#product-price-selection) are provided, the selected Prices are added to the response.
     responses:
       200:
         body:
@@ -153,7 +153,7 @@ post:
     is:
       - priceSelecting
     description: |-
-      If [Price selection](ctp:api:type:ProductPriceSelection) query parameters are provided, the selected Prices are added to the response.
+      If [Product price selection query parameters](/../api/pricing-and-discounts-overview#product-price-selection) are provided, the selected Prices are added to the response.
 
       A failed response can return a [DuplicatePriceScope](ctp:api:type:DuplicatePriceScopeError), [DuplicateVariantValues](ctp:api:type:DuplicateVariantValuesError), [DuplicateAttributeValue](ctp:api:type:DuplicateAttributeValueError), or [DuplicateAttributeValues](ctp:api:type:DuplicateAttributeValuesError) error.
     body:
@@ -166,7 +166,7 @@ post:
             example: !include ../examples/product.example.json
   delete:
     description: |-
-      If [Price selection](ctp:api:type:ProductPriceSelection) query parameters are provided, the selected Prices are added to the response.
+      If [Product price selection query parameters](/../api/pricing-and-discounts-overview#product-price-selection) are provided, the selected Prices are added to the response.
       Produces the [ProductDeleted](/projects/messages#product-deleted) Message.
     securedBy: [oauth_2_0: { scopes: ['manage_products:{projectKey}'] }]
     is:

diff --git a/api-specs/api/resources/standalone-prices.raml b/api-specs/api/resources/standalone-prices.raml
@@ -26,7 +26,10 @@ head:
       type: QueryPredicate[]
 post:
   description: |
-    Produces the [StandalonePriceCreated](ctp:api:type:StandalonePriceCreatedMessage) Message.
+    Creating a Standalone Price produces the [StandalonePriceCreated](ctp:api:type:StandalonePriceCreatedMessage) Message.
+
+    - If the Standalone Price has the same price scope as an existing Standalone Price, a [DuplicateStandalonePriceScope](ctp:api:type:DuplicateStandalonePriceScopeError) error is returned.
+    - If the Standalone Price has overlapping validity periods within the same price scope, a [OverlappingStandalonePriceValidity](ctp:api:type:OverlappingStandalonePriceValidityError) error is returned. A Price without validity period does not conflict with a Price defined for a time period.
   securedBy: [oauth_2_0: { scopes: ['manage_standalone_prices:{projectKey}'] }]
   body:
     application/json:

diff --git a/api-specs/api/traits/price-selecting.raml b/api-specs/api/traits/price-selecting.raml
@@ -5,22 +5,22 @@ queryParameters:
     type: CurrencyCode
     required: false
     description: |
-      The currency used for [Price selection](/projects/products#price-selection).
+      The currency used for [Product price selection](/../api/pricing-and-discounts-overview#product-price-selection).
   priceCountry:
     type: CountryCode
     required: false
     description: |
-      The country used for [Price selection](/projects/products#price-selection). Can only be used **in conjunction with** the `priceCurrency` parameter.
+      The country used for [Product price selection](/../api/pricing-and-discounts-overview#product-price-selection). Can only be used **in conjunction with** the `priceCurrency` parameter.
   priceCustomerGroup:
     type: string
     required: false
     description: |
-      `id` of an existing [CustomerGroup](ctp:api:type:CustomerGroup) used for [Price selection](ctp:api:type:ProductPriceSelection). Can only be used **in conjunction with** the `priceCurrency` parameter.
+      `id` of an existing [CustomerGroup](ctp:api:type:CustomerGroup) used for [Product price selection](/../api/pricing-and-discounts-overview#product-price-selection). Can only be used **in conjunction with** the `priceCurrency` parameter.
   priceChannel:
     type: string
     required: false
     description: |
-      `id` of an existing [Channel](ctp:api:type:Channel) used for [Price selection](ctp:api:type:ProductPriceSelection). Can only be used **in conjunction with** the `priceCurrency` parameter.
+      `id` of an existing [Channel](ctp:api:type:Channel) used for [Product price selection](/../api/pricing-and-discounts-overview#product-price-selection). Can only be used **in conjunction with** the `priceCurrency` parameter.
   localeProjection:
     type: Locale[]
     required: false

diff --git a/api-specs/api/types/cart/Cart.raml b/api-specs/api/types/cart/Cart.raml
@@ -32,7 +32,7 @@ properties:
   customerGroup?:
     type: CustomerGroupReference
     description: |
-      [Reference](ctp:api:type:Reference) to the Customer Group of the Customer that the Cart belongs to. Used for [LineItem Price selection](ctp:api:type:LineItemPriceSelection).
+      [Reference](ctp:api:type:Reference) to the Customer Group of the Customer that the Cart belongs to. Used for [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection).
   anonymousId?:
     type: string
     description: |
@@ -170,7 +170,7 @@ properties:
   country?:
     type: CountryCode
     description: |
-      Used for [LineItem Price selection](ctp:api:type:LineItemPriceSelection).
+      Used for [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection).
   locale?:
     type: Locale
     description: |

diff --git a/api-specs/api/types/cart/CartDraft.raml b/api-specs/api/types/cart/CartDraft.raml
@@ -25,7 +25,7 @@ properties:
   customerGroup?:
     type: CustomerGroupResourceIdentifier
     description: |
-      [ResourceIdentifier](ctp:api:type:ResourceIdentifier) to the Customer Group of the Customer that the Cart belongs to. Used for [LineItem Price selection](ctp:api:type:LineItemPriceSelection).
+      [ResourceIdentifier](ctp:api:type:ResourceIdentifier) to the Customer Group of the Customer that the Cart belongs to. Used for [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection).
 
       It is automatically set if the Customer referenced in `customerId` belongs to a Customer Group.
       It can also be set explicitly when no `customerId` is present.
@@ -123,7 +123,7 @@ properties:
   country?:
     type: CountryCode
     description: |
-      Used for [LineItem Price selection](ctp:api:type:LineItemPriceSelection).
+      Used for [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection).
       If used for [Create Cart in Store](ctp:api:endpoint:/{projectKey}/in-store/carts:POST), the provided country must be one of the [Store's](ctp:api:type:Store) `countries`.
   locale?:
     type: Locale

diff --git a/api-specs/api/types/cart/DirectDiscountDraft.raml b/api-specs/api/types/cart/DirectDiscountDraft.raml
@@ -6,11 +6,7 @@ example: !include ../../examples/Cart/CartDirectDiscountDraft.json
 description: |
   Represents a [CartDiscount](ctp:api:type:CartDiscount) that can only be associated with a single Cart or Order.
 
-  Direct Discounts are always active and valid, and have the default `Stacking` [StackingMode](ctp:api:type:StackingMode).
-  They apply in the order in which they are listed in the `directDiscounts` array of [Carts](ctp:api:type:Cart) or [Orders](ctp:api:type:Order), and do not have a sorting order like Cart Discounts.
-
-  If a Direct Discount is present, any matching Cart Discounts in the Project are ignored.
-  Additionally, a Cart or Order supports either Discount Codes or Direct Discounts at the same time.
+  For an introduction to Direct Discounts and to understand how they work in Composable Commerce, see the [Direct Discounts overview](/pricing-and-discounts-overview#direct-discounts).
 properties:
   value:
     type: CartDiscountValueDraft

diff --git a/api-specs/api/types/cart/LineItem.raml b/api-specs/api/types/cart/LineItem.raml
@@ -97,7 +97,7 @@ properties:
   distributionChannel?:
     type: ChannelReference
     description: |
-      Used to [select](ctp:api:type:LineItemPriceSelection) a Product Price. The referenced Channel has the `ProductDistribution` [ChannelRoleEnum](ctp:api:type:ChannelRoleEnum).
+      Used to [select](/../api/pricing-and-discounts-overview#line-item-price-selection) a Product Price. The referenced Channel has the `ProductDistribution` [ChannelRoleEnum](ctp:api:type:ChannelRoleEnum).
   priceMode:
     type: LineItemPriceMode
     description: |

diff --git a/api-specs/api/types/cart/LineItemDraft.raml b/api-specs/api/types/cart/LineItemDraft.raml
@@ -42,7 +42,7 @@ properties:
   distributionChannel?:
     type: ChannelResourceIdentifier
     description: |
-      Used to [select](ctp:api:type:LineItemPriceSelection) a Product Price.
+      Used to [select](/../api/pricing-and-discounts-overview#line-item-price-selection) a Product Price.
       The referenced Channel must have the `ProductDistribution` [ChannelRoleEnum](ctp:api:type:ChannelRoleEnum).
 
       If the Cart is bound to a [Store](ctp:api:type:Store) with `distributionChannels` set,

diff --git a/api-specs/api/types/cart/LineItemPriceMode.raml b/api-specs/api/types/cart/LineItemPriceMode.raml
@@ -10,7 +10,7 @@ enum:
   - ExternalTotal
 (enumDescriptions):
   Platform: |
-    The [price is selected](ctp:api:type:LineItemPriceSelection) from the Product Variant.
+    The price is [selected](/../api/pricing-and-discounts-overview#line-item-price-selection) from the Product Variant.
     This is the default mode.
   ExternalPrice: |
     The Line Item price is set externally.

diff --git a/api-specs/api/types/cart/TaxMode.raml b/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.
diff --git a/api-specs/api/types/cart/updates/CartAddLineItemAction.raml b/api-specs/api/types/cart/updates/CartAddLineItemAction.raml
@@ -8,7 +8,7 @@ description: |
   If the Cart contains a [LineItem](ctp:api:type:LineItem) for a Product Variant with the same [LineItemMode](ctp:api:type:LineItemMode), [Custom Fields](/../api/projects/custom-fields), supply and distribution channel, then only the quantity of the existing Line Item is increased.
   If [LineItem](ctp:api:type:LineItem) `shippingDetails` is set, it is merged. All addresses will be present afterwards and, for address keys present in both shipping details, the quantity will be summed up.
   A new Line Item is added when the `externalPrice` or `externalTotalPrice` is set in this update action.
-  The [LineItem](ctp:api:type:LineItem) price is set as described in [LineItem Price selection](ctp:api:type:LineItemPriceSelection).
+  The [LineItem](ctp:api:type:LineItem) price is set as described in [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection).
 
   If the Tax Rate is not set, a [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError) error is returned.
 
@@ -57,7 +57,7 @@ properties:
   distributionChannel?:
     type: ChannelResourceIdentifier
     description: |
-      Used to [select](ctp:api:type:LineItemPriceSelection) a Product Price.
+      Used to [select](/../api/pricing-and-discounts-overview#line-item-price-selection) a Product Price.
       The Channel must have the `ProductDistribution` [ChannelRoleEnum](ctp:api:type:ChannelRoleEnum).
       If the Cart is bound to a [Store](ctp:api:type:Store) with `distributionChannels` set, the Channel must match one of the Store's distribution channels.
   supplyChannel?:

diff --git a/api-specs/api/types/cart/updates/CartChangeLineItemQuantityAction.raml b/api-specs/api/types/cart/updates/CartChangeLineItemQuantityAction.raml
@@ -15,7 +15,7 @@ description: |
   use this update action in combination with the [Set LineItem ShippingDetails](ctp:api:type:CartSetLineItemShippingDetailsAction) update action
   in a single Cart update command.
 
-  The [LineItem](ctp:api:type:LineItem) price is set as described in [LineItem Price selection](ctp:api:type:LineItemPriceSelection).
+  The [LineItem](ctp:api:type:LineItem) price is set as described in [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection).
 properties:
   lineItemId?:
     type: string
@@ -39,7 +39,7 @@ properties:
       Required when the Line Item uses `ExternalPrice` [LineItemPriceMode](ctp:api:type:LineItemPriceMode).
       Sets the [LineItem](ctp:api:type:LineItem) `price` to the given value when changing the quantity of a Line Item.
 
-      The LineItem price is updated as described in LineItem Price selection.
+      The LineItem price is updated as described in Line Item price selection.
   externalTotalPrice?:
     type: ExternalLineItemTotalPrice
     description: |

diff --git a/api-specs/api/types/cart/updates/CartRemoveLineItemAction.raml b/api-specs/api/types/cart/updates/CartRemoveLineItemAction.raml
@@ -5,7 +5,7 @@ displayName: CartRemoveLineItemAction
 discriminatorValue: removeLineItem
 example: !include ../../../examples/Cart/CartRemoveLineItemAction.json
 description: |
-  The [LineItem](ctp:api:type:LineItem) price is updated as described in [LineItem Price selection](ctp:api:type:LineItemPriceSelection).
+  The [LineItem](ctp:api:type:LineItem) price is updated as described in [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection).
 properties:
   lineItemId?:
     type: string

diff --git a/api-specs/api/types/cart/updates/CartSetCartTotalTaxAction.raml b/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

diff --git a/api-specs/api/types/cart/updates/CartSetLineItemDistributionChannelAction.raml b/api-specs/api/types/cart/updates/CartSetLineItemDistributionChannelAction.raml
@@ -5,7 +5,7 @@ displayName: CartSetLineItemDistributionChannelAction
 discriminatorValue: setLineItemDistributionChannel
 example: !include ../../../examples/Cart/CartSetLineItemDistributionChannelAction.json
 description: |
-  Setting a distribution channel for a [LineItem](ctp:api:type:LineItem) can lead to an updated `price` as described in [LineItem Price selection](ctp:api:type:LineItemPriceSelection).
+  Setting a distribution channel for a [LineItem](ctp:api:type:LineItem) can lead to an updated `price` as described in [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection).
 properties:
   lineItemId?:
     type: string