Updated API from documentation release

commercetools · Jul 9, 2024 · 067176d · 067176d
1 parent ecedddf
commit 067176d
Show file tree

Hide file tree

Showing 34 changed files with 261 additions and 80 deletions.
diff --git a/api-specs/api/examples/ShoppingList/ShoppingListSetAnonymousIdAction.json b/api-specs/api/examples/ShoppingList/ShoppingListSetAnonymousIdAction.json
@@ -1,4 +1,4 @@
 {
   "action": "setAnonymousId",
-  "anonymousId": "ThisIsMyID"
-}
+  "anonymousId": "anonymousId"
+}
diff --git a/api-specs/api/resources/as-associate.raml b/api-specs/api/resources/as-associate.raml
@@ -257,6 +257,14 @@ type: base
         description: |
           Creates a [Cart](ctp:api:type:Cart) in the [BusinessUnit](ctp:api:type:BusinessUnit) referenced by `businessUnitKey`. As such, the `businessUnit` field on [CartDraft](ctp:api:type:CartDraft) is ignored for this request.
           Creating a Cart can fail with an [InvalidOperation](ctp:api:type:InvalidOperationError) if the referenced [ShippingMethod](ctp:api:type:ShippingMethod) in the [CartDraft](ctp:api:type:CartDraft) has a predicate that does not match the Cart.
+
+          Specific Error Codes:
+
+          - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
+          - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
+          - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+          - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
+
         body:
           application/json:
             example: !include ../examples/cart-create.example.json
@@ -365,6 +373,12 @@ type: base
             The new Cart does not contain Payments or Deliveries. The [State](ctp:api:type:ItemState) of Line Items and Custom Line Items is reset to `initial`.
 
             If the Cart exists in the [Project](ctp:api:type:Project) but does not reference the requested [BusinessUnit](ctp:api:type:BusinessUnit), this method returns an [InvalidOperation](ctp:api:type:InvalidOperationError) error.
+
+            Specific Error Codes:
+
+            - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+            - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
+
           body:
             application/json:
               example: !include ../examples/cart-replicate.example.json
@@ -408,6 +422,16 @@ type: base
           Creates an Order from a [Cart](ctp:api:type:Cart) in a [BusinessUnit](ctp:api:type:BusinessUnit).
           The Cart must have a shipping address set before creating an Order.
           Creating an Order fails with an [InvalidOperation](ctp:api:type:InvalidOperationError) if the Cart does not reference the same BusinessUnit as the `businessUnitKey` path parameter.
+
+          Specific Error Codes:
+
+          - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
+          - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
+          - [OutOfStock](ctp:api:type:OutOfStockError)
+          - [PriceChanged](ctp:api:type:PriceChangedError)
+          - [ShippingMethodDoesNotMatchCart](ctp:api:type:ShippingMethodDoesNotMatchCartError)
+          - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+          - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
         body:
           application/json:
             example: !include ../examples/order-create.example.json
@@ -426,6 +450,11 @@ type: base
           description: |
             Creates an Order from a [Quote](ctp:api:type:Cart) in a [BusinessUnit](ctp:api:type:BusinessUnit).
             Creating an Order fails with an [InvalidOperation](ctp:api:type:InvalidOperationError) if the Quote does not reference the same BusinessUnit as the `businessUnitKey` path parameter.
+
+            Specific Error Codes:
+
+            - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
+            - [OutOfStock](ctp:api:type:OutOfStockError)
           body:
             application/json:
               example: !include ../examples/order-from-quote.example.json

diff --git a/api-specs/api/resources/carts.raml b/api-specs/api/resources/carts.raml
@@ -28,6 +28,14 @@ post:
     Creating a Cart fails with an [InvalidOperation](ctp:api:type:InvalidOperationError) error if the
     [ShippingMethod](ctp:api:type:ShippingMethod) referenced in the CartDraft
     has a `predicate` that does not match the Cart.
+
+    Specific Error Codes:
+
+    - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
+    - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
+    - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+    - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
+
   body:
     application/json:
       example: !include ../examples/cart-create.example.json
@@ -46,6 +54,11 @@ post:
       The replicated Cart preserves Customer information, Line Items and Custom Line Items, Custom Fields, Discount Codes, and other settings of the Cart or Order. If the Line Items become invalid, for example, due to removed Products or Prices, they are removed from the new Cart. If the Customer switches to another Customer Group, the new Cart is updated with the new value. It has up-to-date Tax Rates, Prices, and Line Item product data and is in `Active` [CartState](ctp:api:type:CartState).
 
       The new Cart does not contain Payments or Deliveries. The [State](ctp:api:type:ItemState) of Line Items and Custom Line Items is reset to `initial`.
+
+      Specific Error Codes:
+
+      - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+      - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
     body:
       application/json:
         example: !include ../examples/cart-replicate.example.json

diff --git a/api-specs/api/resources/in-store.raml b/api-specs/api/resources/in-store.raml
@@ -67,6 +67,15 @@ uriParameters:
       Creates a [Cart](ctp:api:type:Cart) in the [Store](ctp:api:type:Store) specified by `storeKey`.
       When using this endpoint the Cart's `store` field is always set to the [Store](ctp:api:type:Store) specified in the path parameter.
       If the referenced [ShippingMethod](ctp:api:type:ShippingMethod) in the [CartDraft](ctp:api:type:CartDraft) has a predicate that does not match, an [InvalidOperation](ctp:api:type:InvalidOperationError) error is returned.
+
+      Specific Error Codes:
+
+      - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
+      - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
+      - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+      - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
+      - [CountryNotConfiguredInStore](ctp:api:type:CountryNotConfiguredInStoreError)
+
     body:
       application/json:
         example: !include ../examples/cart-create.example.json
@@ -215,6 +224,11 @@ uriParameters:
         The replicated Cart preserves Customer information, Line Items and Custom Line Items, Custom Fields, Discount Codes, and other settings of the Cart or Order. If the Line Items become invalid, for example, due to removed Products or Prices, they are removed from the new Cart. If the Customer switches to another Customer Group, the new Cart is updated with the new value. It has up-to-date Tax Rates, Prices, and Line Item product data and is in `Active` [CartState](ctp:api:type:CartState).
 
         The new Cart does not contain payments or deliveries. The [State](ctp:api:type:ItemState) of Line Items and Custom Line Items is reset to `initial`.
+
+        Specific Error Codes:
+
+        - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+        - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
       body:
         application/json:
           example: !include ../examples/cart-replicate.example.json
@@ -390,7 +404,6 @@ uriParameters:
       The shipping address is used for tax calculation for a Cart with `Platform` [TaxMode](ctp:api:type:TaxMode).
 
       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.
 
@@ -701,7 +714,14 @@ uriParameters:
 
         The `store` field in the created [Cart](ctp:api:type:Cart) is set to the Store specified by the `storeKey` path parameter.
 
-        Specific Error Codes: [CountryNotConfiguredInStore](ctp:api:type:CountryNotConfiguredInStoreError)
+        Specific Error Codes:
+
+        - [CountryNotConfiguredInStore](ctp:api:type:CountryNotConfiguredInStoreError)
+        - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
+        - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
+        - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+        - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
+
       body:
         application/json:
           example: !include ../examples/cart-create.example.json
@@ -868,11 +888,15 @@ uriParameters:
 
         Specific Error Codes:
 
+        - [AssociateMissingPermission](ctp:api:type:AssociateMissingPermissionError)
+        - [CountryNotConfiguredInStore](ctp:api:type:CountryNotConfiguredInStoreError)
+        - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
+        - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
+        - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+        - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
         - [OutOfStock](ctp:api:type:OutOfStockError)
         - [PriceChanged](ctp:api:type:PriceChangedError)
-        - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
-        - [CountryNotConfiguredInStore](ctp:api:type:CountryNotConfiguredInStoreError)
-        - [AssociateMissingPermission](ctp:api:type:AssociateMissingPermissionError)
+        - [ShippingMethodDoesNotMatchCart](ctp:api:type:ShippingMethodDoesNotMatchCartError)
       securedBy:
         [
           oauth_2_0:
@@ -1427,6 +1451,8 @@ uriParameters:
       description: |
         If omitted in the request body, the [Customer](ctp:api:type:Customer) `stores` field is set to the [Store](ctp:api:type:Store) specified in the path parameter.
 
+        A Cart returned in the [CustomerSignInResult](ctp:api:type:CustomerSignInResult) has any invalid Line Items removed and is [updated](/api/carts-orders-overview#cart-updates) with the latest prices, taxes, and discounts. During these updates, the following errors can be returned: [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError) and [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError).
+
         Creating a Customer produces the [CustomerCreated](ctp:api:type:CustomerCreatedMessage) Message.
       securedBy:
         [
@@ -1459,9 +1485,10 @@ uriParameters:
         - If the Customer does not have a Cart, the most recently modified anonymous cart becomes the Customer's Cart.
         - If the Customer already has a Cart, the most recently modified anonymous cart is handled according to [AnonymousCartSignInMode](ctp:api:type:AnonymousCartSignInMode).
 
-        If a Cart is returned as part of [CustomerSignInResult](ctp:api:type:CustomerSignInResult), it has been [recalculated](ctp:api:type:MyCartRecalculateAction) with up-to-date prices, taxes, discounts, and invalid line items removed.
+        A Cart returned in the [CustomerSignInResult](ctp:api:type:CustomerSignInResult) has any invalid Line Items removed and is [updated](/api/carts-orders-overview#cart-updates) with the latest prices, taxes, and discounts. During these updates, the following errors can be returned: [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError) and [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError).
 
         If an account with the given credentials is not found, an [InvalidCredentials](ctp:api:type:InvalidCredentialsError) error is returned.
+
       securedBy:
         [
           oauth_2_0:
@@ -1793,6 +1820,7 @@ uriParameters:
         If the Customer exists in the Project but the `stores` field references a different [Store](ctp:api:type:Store), this method returns a [ResourceNotFound](ctp:api:type:ResourceNotFoundError) error.
 
         Simultaneously updating two Customers with the same email address can return a [LockedField](ctp:api:type:LockedFieldError) error.
+
       securedBy:
         - oauth_2_0:
             scopes:
@@ -1833,9 +1861,12 @@ uriParameters:
     description: |
       Authenticates a Customer associated with a [Store](ctp:api:type:Store). For more information, see [Global versus Store-specific Customers](/../api/customers-overview#global-versus-store-specific-customers).
 
+      A Cart returned in the [CustomerSignInResult](ctp:api:type:CustomerSignInResult) has any invalid Line Items removed and is [updated](/api/carts-orders-overview#cart-updates) with the latest prices, taxes, and discounts. During these updates, the following errors can be returned: [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError) and [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError).
+
       Triggers [Cart merge during sign-in](/../api/customers-overview#cart-merge-during-sign-in).
 
       If the Customer exists in the Project but the `stores` field references a different [Store](ctp:api:type:Store), this method returns an [InvalidCredentials](ctp:api:type:InvalidCredentialsError) error.
+
     securedBy:
       - oauth_2_0:
           scopes:

diff --git a/api-specs/api/resources/login.raml b/api-specs/api/resources/login.raml
@@ -10,7 +10,10 @@ post:
 
     Triggers [Cart merge during sign-in](/../api/customers-overview#cart-merge-during-sign-in).
 
+    A Cart returned in the [CustomerSignInResult](ctp:api:type:CustomerSignInResult) has any invalid Line Items removed and is [updated](/api/carts-orders-overview#cart-updates) with the latest prices, taxes, and discounts. During these updates, the following errors can be returned: [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError) and [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError).
+
     If an account with the given credentials is not found, an [InvalidCredentials](ctp:api:type:InvalidCredentialsError) error is returned.
+
   securedBy: [oauth_2_0: { scopes: ['manage_customers:{projectKey}'] }]
   body:
     application/json:

diff --git a/api-specs/api/resources/me.raml b/api-specs/api/resources/me.raml
@@ -128,9 +128,10 @@ delete:
       - If the Customer does not have a Cart yet, the most recently modified anonymous cart becomes the Customer's Cart.
       - If the Customer already has a Cart, the most recently modified anonymous cart is handled in accordance with [AnonymousCartSignInMode](ctp:api:type:AnonymousCartSignInMode).
 
-      A Cart returned as part of the [CustomerSignInResult](ctp:api:type:CustomerSignInResult) is [recalculated](ctp:api:type:MyCartRecalculateAction) with up-to-date prices, taxes, discounts, and invalid line items removed.
+      A Cart returned in the [CustomerSignInResult](ctp:api:type:CustomerSignInResult) has any invalid Line Items removed and is [updated](/api/carts-orders-overview#cart-updates) with the latest prices, taxes, and discounts. During these updates, the following errors can be returned: [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError) and [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError).
 
       If an account with the given credentials is not found, an [InvalidCredentials](ctp:api:type:InvalidCredentialsError) error is returned.
+
     securedBy: [oauth_2_0: { scopes: ['manage_my_profile:{projectKey}'] }]
     body:
       application/json:
@@ -353,6 +354,14 @@ delete:
       ]
     description: |
       Creates a Cart for a given `customerId` or `anonymousId`.
+
+      Specific Error Codes:
+
+      - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
+      - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
+      - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+      - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
+
     body:
       application/json:
         example: !include ../examples/cart-create.example.json
@@ -510,6 +519,12 @@ delete:
         The new Cart does not contain Payments or Deliveries. The [State](ctp:api:type:ItemState) of Line Items and Custom Line Items is reset to `initial`.
 
         If the Cart or Order to be replicated does not belong to the authenticated Customer, the API returns a [ResourceNotFound](ctp:api:type:ResourceNotFoundError) error
+
+        Specific Error Codes:
+
+        - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+        - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
+
       body:
         application/json:
           type: ReplicaMyCartDraft
@@ -570,10 +585,14 @@ delete:
 
       Specific Error Codes:
 
+      - [AssociateMissingPermission](ctp:api:type:AssociateMissingPermissionError)
+      - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
+      - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
       - [OutOfStock](ctp:api:type:OutOfStockError)
       - [PriceChanged](ctp:api:type:PriceChangedError)
-      - [DiscountCodeNonApplicable](ctp:api:type:DiscountCodeNonApplicableError)
-      - [AssociateMissingPermission](ctp:api:type:AssociateMissingPermissionError)
+      - [ShippingMethodDoesNotMatchCart](ctp:api:type:ShippingMethodDoesNotMatchCartError)
+      - [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError)
+      - [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError)
     securedBy: [oauth_2_0: { scopes: ['manage_my_orders:{projectKey}'] }]
     body:
       application/json:

diff --git a/api-specs/api/resources/orders.raml b/api-specs/api/resources/orders.raml
@@ -89,11 +89,12 @@ post:
 
       Specific Error Codes:
 
-      - [OutOfStock](ctp:api:type:OutOfStockError)
-      - [PriceChanged](ctp:api:type:PriceChangedError)
+      - [CountryNotConfiguredInStore](ctp:api:type:CountryNotConfiguredInStoreError)
       - [InvalidItemShippingDetails](ctp:api:type:InvalidItemShippingDetailsError)
       - [InvalidOperation](ctp:api:type:InvalidOperationError)
-      - [CountryNotConfiguredInStore](ctp:api:type:CountryNotConfiguredInStoreError)
+      - [OutOfStock](ctp:api:type:OutOfStockError)
+      - [PriceChanged](ctp:api:type:PriceChangedError)
+
     securedBy: [oauth_2_0: { scopes: ['manage_quotes:{projectKey}'] }]
     body:
       application/json:

diff --git a/api-specs/api/types/cart/updates/CartFreezeCartAction.raml b/api-specs/api/types/cart/updates/CartFreezeCartAction.raml
@@ -6,4 +6,4 @@ discriminatorValue: freezeCart
 example: !include ../../../examples/Cart/CartFreezeCartAction.json
 description: |
   Changes the [CartState](ctp:api:type:CartState) from `Active` to `Frozen`. Results in a [Frozen Cart](ctp:api:type:FrozenCarts).
-  Fails with [InvalidOperation](ctp:api:type:InvalidOperation) error when the Cart is empty.
+  Fails with [InvalidOperation](ctp:api:type:InvalidOperationError) error when the Cart is empty.
diff --git a/api-specs/api/types/cart/updates/CartSetAnonymousIdAction.raml b/api-specs/api/types/cart/updates/CartSetAnonymousIdAction.raml
@@ -4,6 +4,8 @@ type: CartUpdateAction
 displayName: CartSetAnonymousIdAction
 discriminatorValue: setAnonymousId
 example: !include ../../../examples/Cart/CartSetAnonymousIdAction.json
+description: |
+  If the Cart is already associated with a Customer, an [InvalidOperation](ctp:api:type:InvalidOperationError) error is returned.
 properties:
   anonymousId?:
     type: string

diff --git a/api-specs/api/types/cart/updates/CartSetCustomerGroupAction.raml b/api-specs/api/types/cart/updates/CartSetCustomerGroupAction.raml
@@ -5,10 +5,10 @@ displayName: CartSetCustomerGroupAction
 discriminatorValue: setCustomerGroup
 example: !include ../../../examples/Cart/CartSetCustomerGroupAction.json
 description: |
-  This update action can only be used if a Customer is not assigned to a Cart.
-  If a Customer is already assigned, the Cart has the same Customer Group as the assigned Customer.
+  This update action can only be used if a Customer is not assigned to the Cart.
+  If a Customer is already assigned, the Cart uses the Customer Group of the assigned Customer.
 
-  Setting the Customer Group also updates the [LineItem](ctp:api:type:LineItem) `prices` according to the Customer Group.
+  To reflect the new Customer Group, this update action can result in [updates to the Cart](/api/carts-orders-overview#cart-updates). When this occurs, the following errors can be returned: [MatchingPriceNotFound](ctp:api:type:MatchingPriceNotFoundError) and [MissingTaxRateForCountry](ctp:api:type:MissingTaxRateForCountryError).
 properties:
   customerGroup?:
     type: CustomerGroupResourceIdentifier