Updated api-reference from documentation release

commercetools · Jun 10, 2024 · 984a769 · 984a769
1 parent 5c2fffd
commit 984a769
Show file tree

Hide file tree

Showing 124 changed files with 183 additions and 140 deletions.
diff --git a/api-specs/api/resources/in-store.raml b/api-specs/api/resources/in-store.raml
@@ -391,6 +391,9 @@ uriParameters:
 
       Creating an Order produces the [OrderCreated](ctp:api:type:OrderCreatedMessage) Message.
 
+      If a server-side problem occurs, indicated by a 500 Internal Server Error HTTP response, the Order creation may still successfully complete after the error is returned.
+      If you receive this error, you should verify the status of the Order by querying a unique identifier supplied during the creation request, such as the Order number.
+
       Specific Error Codes:
 
       - [OutOfStock](ctp:api:type:OutOfStockError)

diff --git a/api-specs/api/resources/me.raml b/api-specs/api/resources/me.raml
@@ -457,6 +457,9 @@ delete:
 
       Creating an Order produces the [OrderCreated](ctp:api:type:OrderCreatedMessage) Message.
 
+      If a server-side problem occurs, indicated by a 500 Internal Server Error HTTP response, the Order creation may still successfully complete after the error is returned.
+      If you receive this error, you should verify the status of the Order by querying a unique identifier supplied during the creation request, such as the Order number.
+
       Specific Error Codes:
 
       - [OutOfStock](ctp:api:type:OutOfStockError)

diff --git a/api-specs/api/resources/orders.raml b/api-specs/api/resources/orders.raml
@@ -34,6 +34,9 @@ post:
 
     Creating an Order produces the [OrderCreated](ctp:api:type:OrderCreatedMessage) Message.
 
+      If a server-side problem occurs, indicated by a 500 Internal Server Error HTTP response, the Order creation may still successfully complete after the error is returned.
+      If you receive this error, you should verify the status of the Order by querying a unique identifier supplied during the creation request, such as the Order number.
+
     Specific Error Codes:
 
     - [OutOfStock](ctp:api:type:OutOfStockError)

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/annotations.raml b/api-specs/api/types/annotations.raml
@@ -102,3 +102,6 @@ enumGroups:
     //:
       description: |
         Specifies the group for the enum value given by the key.
+expandable:
+  type: boolean
+  allowedTargets: TypeDeclaration
diff --git a/api-specs/api/types/associate-role/AssociateRoleKeyReference.raml b/api-specs/api/types/associate-role/AssociateRoleKeyReference.raml
@@ -4,7 +4,7 @@ displayName: AssociateRoleKeyReference
 type: KeyReference
 discriminatorValue: associate-role
 description: |
-  [Reference](ctp:api:type:Reference) to an [AssociateRole](ctp:api:type:AssociateRole) by its key.
+  [KeyReference](ctp:api:type:KeyReference) to an [AssociateRole](ctp:api:type:AssociateRole).
 properties:
   key:
     type: string

diff --git a/api-specs/api/types/business-unit/Associate.raml b/api-specs/api/types/business-unit/Associate.raml
@@ -1,6 +1,8 @@
 #%RAML 1.0 DataType
 (package): BusinessUnit
 displayName: Associate
+type: object
+(expandable): true
 properties:
   associateRoleAssignments:
     type: AssociateRoleAssignment[]

diff --git a/api-specs/api/types/business-unit/AssociateRoleAssignment.raml b/api-specs/api/types/business-unit/AssociateRoleAssignment.raml
@@ -1,6 +1,7 @@
 #%RAML 1.0 DataType
 (package): BusinessUnit
 displayName: AssociateRoleAssignment
+type: object
 properties:
   associateRole:
     type: AssociateRoleKeyReference

diff --git a/api-specs/api/types/business-unit/BusinessUnitKeyReference.raml b/api-specs/api/types/business-unit/BusinessUnitKeyReference.raml
@@ -4,7 +4,7 @@ displayName: BusinessUnitKeyReference
 type: KeyReference
 discriminatorValue: business-unit
 description: |
-  [Reference](ctp:api:type:Reference) to a [BusinessUnit](ctp:api:type:BusinessUnit) by its key.
+  [KeyReference](ctp:api:type:KeyReference) to a [BusinessUnit](ctp:api:type:BusinessUnit).
 properties:
   key:
     type: string

diff --git a/api-specs/api/types/business-unit/InheritedAssociate.raml b/api-specs/api/types/business-unit/InheritedAssociate.raml
@@ -1,6 +1,8 @@
 #%RAML 1.0 DataType
 (package): BusinessUnit
 displayName: InheritedAssociate
+type: object
+(expandable): true
 properties:
   associateRoleAssignments:
     type: InheritedAssociateRoleAssignment[]

diff --git a/api-specs/api/types/business-unit/InheritedAssociateRoleAssignment.raml b/api-specs/api/types/business-unit/InheritedAssociateRoleAssignment.raml
@@ -1,6 +1,7 @@
 #%RAML 1.0 DataType
 (package): BusinessUnit
 displayName: InheritedAssociateRoleAssignment
+type: object
 properties:
   associateRole:
     type: AssociateRoleKeyReference

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/CustomLineItem.raml b/api-specs/api/types/cart/CustomLineItem.raml
@@ -2,6 +2,7 @@
 (package): Cart
 displayName: CustomLineItem
 type: object
+(expandable): true
 description: |
   A generic item that can be added to the Cart but is not bound to a Product that can be used for discounts (negative money), vouchers, complex cart rules, additional services, or fees.
   You control the lifecycle of this item.

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/DiscountCodeInfo.raml b/api-specs/api/types/cart/DiscountCodeInfo.raml
@@ -1,6 +1,7 @@
 #%RAML 1.0 DataType
 (package): Cart
 displayName: DiscountCodeInfo
+(expandable): true
 type: object
 properties:
   discountCode:

diff --git a/api-specs/api/types/cart/DiscountedTotalPricePortion.raml b/api-specs/api/types/cart/DiscountedTotalPricePortion.raml
@@ -2,6 +2,7 @@
 (package): Cart
 displayName: DiscountedTotalPricePortion
 type: object
+(expandable): true
 properties:
   discount:
     type: CartDiscountReference

diff --git a/api-specs/api/types/cart/LineItem.raml b/api-specs/api/types/cart/LineItem.raml
@@ -2,6 +2,7 @@
 (package): Cart
 displayName: LineItem
 type: object
+(expandable): true
 description: |
   The representation of a [Line Item](/../api/carts-orders-overview#line-items) in a [Cart](ctp:api:type:Cart) or in an [Order](ctp:api:type:Order).
 properties:
@@ -97,7 +98,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/ShippingInfo.raml b/api-specs/api/types/cart/ShippingInfo.raml
@@ -2,6 +2,7 @@
 (package): Cart
 displayName: ShippingInfo
 type: object
+(expandable): true
 properties:
   shippingMethodName:
     type: string

diff --git a/api-specs/api/types/cart/ShippingMethodState.raml b/api-specs/api/types/cart/ShippingMethodState.raml
@@ -3,7 +3,7 @@
 displayName: ShippingMethodState
 type: string
 description: |
-  Determines whether a [ShippingMethod](ctp:api:type:ShippingMethod) is allowed for a Cart.
+  Determines whether the selected [ShippingMethod](ctp:api:type:ShippingMethod) is allowed for the Cart. For more information, see [Predicates](/shipping-delivery-overview#predicates).
 enum:
   - DoesNotMatchCart
   - MatchesCart

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.