Updated api-reference from documentation release

commercetools · May 27, 2024 · 4d22983 · 4d22983
1 parent dc1bdf3
commit 4d22983
Show file tree

Hide file tree

Showing 45 changed files with 80 additions and 81 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/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/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

diff --git a/api-specs/api/types/cart/updates/CartSetShippingAddressAction.raml b/api-specs/api/types/cart/updates/CartSetShippingAddressAction.raml
@@ -7,7 +7,7 @@ example: !include ../../../examples/Cart/CartSetShippingAddressAction.json
 description: |
   Setting the shipping address also sets the [TaxRate](ctp:api:type:TaxRate) of Line Items and calculates the [TaxedPrice](ctp:api:type:TaxedPrice).
 
-  If a matching price cannot be found for the given shipping address during [Line Item Price selection](ctp:api:type:LineItemPriceSelection),
+  If a matching price cannot be found for the given shipping address during [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection),
   a [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError) error is returned.
 
   If you want to allow shipping to states inside a country that are not explicitly covered by a TaxRate,

diff --git a/api-specs/api/types/channel/ChannelRoleEnum.raml b/api-specs/api/types/channel/ChannelRoleEnum.raml
@@ -15,7 +15,7 @@ enum:
     Channel can be used to track inventory entries (for example, Channels with this role can be treated as warehouses).
   ProductDistribution: |
     Channel can be used to expose Products to a specific distribution Channel.
-    The Channel can be used by a Cart to [select](ctp:api:type:LineItemPriceSelection) a Product Price.
+    The Channel can be used by a Cart to [select](/../api/pricing-and-discounts-overview#line-item-price-selection) a Product Price.
   OrderExport: |
     Channel can be used to track order export activities.
   OrderImport: |

diff --git a/api-specs/api/types/common/Price.raml b/api-specs/api/types/common/Price.raml
@@ -45,7 +45,7 @@ properties:
     type: DiscountedPrice
     description: |
       Is set if a [ProductDiscount](ctp:api:type:ProductDiscount) has been applied.
-      If set, the API uses the DiscountedPrice value for the [Line Item Price selection](ctp:api:type:LineItemPriceSelection).
+      If set, the API uses the DiscountedPrice value for the [Line Item price selection](/../api/pricing-and-discounts-overview#line-item-price-selection).
       When a [relative discount](ctp:api:type:ProductDiscountValueRelative) has been applied and the fraction part of the DiscountedPrice `value` is 0.5, the `value` is rounded in favor of the customer with [half-down rounding](https://en.wikipedia.org/wiki/Rounding#Round_half_down).
   tiers?:
     type: PriceTier[]

diff --git a/api-specs/api/types/common/ReferenceTypeId.raml b/api-specs/api/types/common/ReferenceTypeId.raml
@@ -93,7 +93,7 @@ enum:
   product-discount: |
     References a [ProductDiscount](ctp:api:type:ProductDiscount).
   product-price: |
-    References an [Embedded Price](/projects/products#embedded-price).
+    References an [Embedded Price](ctp:api:type:Price).
   product-selection: |
     References a [ProductSelection](ctp:api:type:ProductSelection).
   product-tailoring: |

diff --git a/api-specs/api/types/common/ScopedPrice.raml b/api-specs/api/types/common/ScopedPrice.raml
@@ -4,7 +4,7 @@ displayName: ScopedPrice
 type: object
 description: |
   Scoped Price is contained in a [ProductVariant](ctp:api:type:ProductVariant) which is returned in response to a
-  [Product Projection Search](ctp:api:type:ProductProjectionSearchFilterScopedPrice) request when [Scoped Price Search](ctp:api:type:ScopedPriceSearch) is used.
+  [Product Projection Search](ctp:api:type:ProductProjectionSearchFilterScopedPrice) request when [Scoped Price Search](/../api/pricing-and-discounts-overview#scoped-price-search) is used.
 properties:
   id:
     type: string

diff --git a/api-specs/api/types/me/MyCartDraft.raml b/api-specs/api/types/me/MyCartDraft.raml
@@ -70,7 +70,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/me/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/me/MyLineItemDraft.raml b/api-specs/api/types/me/MyLineItemDraft.raml
@@ -47,7 +47,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,