Updated API from documentation release

commercetools · Aug 1, 2024 · e1917c6 · e1917c6
1 parent 216db1b
commit e1917c6
Show file tree

Hide file tree

Showing 47 changed files with 251 additions and 67 deletions.
diff --git a/api-specs/api/api.raml b/api-specs/api/api.raml
@@ -16,6 +16,7 @@ baseUriParameters:
       - eu-central-1.aws
       - australia-southeast1.gcp
       - api.cn-northwest-1.aws.commercetools.cn
+      - eastus.azure
     description: |
       [Region](/../api/general-concepts#hosts) in which the Project is hosted.
 version: v1

diff --git a/api-specs/api/examples/Cart/CartChangeLineItemsOrderAction.json b/api-specs/api/examples/Cart/CartChangeLineItemsOrderAction.json
@@ -0,0 +1,4 @@
+{
+  "action": "changeLineItemsOrder",
+  "lineItemOrder": ["{{lineItemId2}}", "{{lineItemId}}"]
+}
diff --git a/api-specs/api/resources/in-store.raml b/api-specs/api/resources/in-store.raml
@@ -65,7 +65,7 @@ uriParameters:
       ]
     description: |
       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, or if the Shipping Method is not active, an [InvalidOperation](ctp:api:type:InvalidOperationError) error is returned.
 
       Specific Error Codes:

diff --git a/api-specs/api/resources/orders.raml b/api-specs/api/resources/orders.raml
@@ -334,7 +334,9 @@ post:
             type: OrderPagedSearchResponse
   head:
     securedBy: [oauth_2_0: { scopes: ['view_orders:{projectKey}'] }]
-    description: Checks whether a search index for the Project's Orders exists.
+    description: |
+      Checks whether a search index for the Project's Orders exists.
+      Returns a `200 OK` status if the index exists or a `404 Not Found` error otherwise.
     responses:
       200:
         description: The index exists and the Search Orders endpoint can be used.

diff --git a/api-specs/api/resources/product-projections-suggest.raml b/api-specs/api/resources/product-projections-suggest.raml
@@ -4,21 +4,36 @@ description: The source of data for suggestions is the searchKeyword field in a
 get:
   displayName: Get suggestion keywords
   queryParameters:
-    fuzzy?:
-      type: boolean
-      description: Whether to apply fuzzy search on the text to analyze.
-    #TODO clarify correct syntax
     /searchKeywords\.[a-z]{2}(-[A-Z]{2})?/:
+      type: string[]
+      required: false
       (placeholderParam):
         paramName: searchKeywords
         template: searchKeywords.<locale>
         placeholder: locale
-      type: string[]
-      required: false
+      description: |-
+        The input text provided for the language specified as [Locale](ctp:api:type:Locale).
+    limit?:
+      type: number
+      format: int32
+      default: 10
+      maximum: 100
+      description: |
+        Controls how many suggestions per language the [SuggestionResult](ctp:api:type:SuggestionResult) will contain.
+        The default limit is `10` Suggestions per language and the maximum is `100`.
+    fuzzy?:
+      type: boolean
+      description: |
+        Defaults to `false`.
+
+        If set to `true`, [fuzzy search](/../api/projects/products-search#fuzzy-search) is applied on the text to analyze.
+    staged?:
+      type: boolean
+      description: |
+        Defaults to `false`.
+
+        If set to `true` (possible only while using the `view_products` scope), staged projections is queried.
   is:
-    - sortable:
-        sortExample: createdAt asc
-    - paging
     - projectionSelecting
   securedBy:
     [

diff --git a/api-specs/api/resources/subscriptions.raml b/api-specs/api/resources/subscriptions.raml
@@ -34,7 +34,7 @@ post:
   is:
     - deprecatable201
   description: |
-    A test message is sent to ensure the correct configuration of the Destination. If the message cannot be delivered, the Subscription will not be created. The payload of the test message is a notification of type [ResourceCreated](/../api/projects/subscriptions#resourcecreateddeliverypayload) for the `resourceTypeId` `subscription`.
+    A test notification is sent to ensure the correct configuration of the Destination. If the notification cannot be delivered, the Subscription will not be created. The payload of the test notification is of type [ResourceCreated](/../api/projects/subscriptions#resourcecreateddeliverypayload) for the `resourceTypeId` `subscription`.
   body:
     application/json:
       type: SubscriptionDraft

diff --git a/api-specs/api/types/cart/updates/CartChangeLineItemsOrderAction.raml b/api-specs/api/types/cart/updates/CartChangeLineItemsOrderAction.raml
@@ -0,0 +1,11 @@
+#%RAML 1.0 DataType
+(package): Cart
+type: CartUpdateAction
+displayName: CartChangeLineItemsOrderAction
+discriminatorValue: changeLineItemsOrder
+example: !include ../../../examples/Cart/CartChangeLineItemsOrderAction.json
+properties:
+  lineItemOrder:
+    type: string[]
+    description: |
+      All existing [LineItem](ctp:api:type:LineItem) `id`s in the desired new order.
diff --git a/api-specs/api/types/cart/updates/CartSetCustomerIdAction.raml b/api-specs/api/types/cart/updates/CartSetCustomerIdAction.raml
@@ -13,4 +13,6 @@ properties:
   customerId?:
     type: string
     description: |
-      `id` of an existing [Customer](ctp:api:type:Customer). If empty, any value is removed.
+      `id` of an existing [Customer](ctp:api:type:Customer).
+      If the Customer is assigned to a [CustomerGroup](ctp:api:type:CustomerGroup), this update action also sets the value for the `customerGroup` field.
+      If empty, the update action removes the value for both `customerId` and `customerGroup`.
diff --git a/api-specs/api/types/extension/ExtensionResourceTypeId.raml b/api-specs/api/types/extension/ExtensionResourceTypeId.raml
@@ -13,6 +13,7 @@ enum:
   - staged-quote
   - quote
   - business-unit
+  - shopping-list
 (enumDescriptions):
   cart: Extension triggered for operations on [Carts](/../api/projects/carts).
   order: Extension triggered for operations on [Orders](/../api/projects/orders).
@@ -22,3 +23,4 @@ enum:
   staged-quote: Extension triggered for operations on [StagedQuotes](/../api/projects/staged-quotes).
   quote: Extension triggered for operations on [Quotes](/../api/projects/quotes).
   business-unit: Extension triggered for operations on [BusinessUnits](/../api/projects/business-units).
+  shopping-list: Extension triggered for operations on [ShoppingLists](/../api/projects/shoppingLists).
diff --git a/api-specs/api/types/me/updates/MyCartChangeLineItemsOrderAction.raml b/api-specs/api/types/me/updates/MyCartChangeLineItemsOrderAction.raml
@@ -0,0 +1,11 @@
+#%RAML 1.0 DataType
+(package): Me
+type: MyCartUpdateAction
+displayName: MyCartChangeLineItemsOrderAction
+discriminatorValue: changeLineItemsOrder
+example: !include ../../../examples/Cart/CartChangeLineItemsOrderAction.json
+properties:
+  lineItemOrder:
+    type: string[]
+    description: |
+      All existing [LineItem](ctp:api:type:LineItem) `id`s of the [Cart](ctp:api:type:Cart) in the desired new order.
diff --git a/api-specs/api/types/order-search/OrderSearchCustomType.raml b/api-specs/api/types/order-search/OrderSearchCustomType.raml
@@ -0,0 +1,58 @@
+#%RAML 1.0 DataType
+(package): Order
+displayName: OrderSearchCustomType
+description: Possible values for the `customType` property on [query expressions](/../api/projects/order-search#query-expressions) indicating the data type of the `field`.
+type: string
+enum:
+  - BooleanType
+  - StringType
+  - LocalizedStringType
+  - EnumType
+  - LocalizedEnumType
+  - NumberType
+  - DateType
+  - TimeType
+  - DateTimeType
+  - SetType.StringType
+  - SetType.LocalizedStringType
+  - SetType.EnumType
+  - SetType.LocalizedEnumType
+  - SetType.NumberType
+  - SetType.DateType
+  - SetType.TimeType
+  - SetType.DateTimeType
+(enumDescriptions):
+  BooleanType: |
+    For [CustomFieldBooleanType](ctp:api:type:CustomFieldBooleanType) Custom Fields.
+  StringType: |
+    For [CustomFieldStringType](ctp:api:type:CustomFieldStringType) Custom Fields.
+  LocalizedStringType: |
+    For [CustomFieldLocalizedStringType](ctp:api:type:CustomFieldLocalizedStringType) Custom Fields.
+  EnumType: |
+    For [CustomFieldEnumType](ctp:api:type:CustomFieldEnumType) Custom Fields.
+  LocalizedEnumType: |
+    For [CustomFieldLocalizedEnumType](ctp:api:type:CustomFieldLocalizedEnumType) Custom Fields.
+  NumberType: |
+    For [CustomFieldNumberType](ctp:api:type:CustomFieldNumberType) Custom Fields.
+  DateType: |
+    For [CustomFieldDateType](ctp:api:type:CustomFieldDateType) Custom Fields.
+  DateTimeType: |
+    For [CustomFieldDateTimeType](ctp:api:type:CustomFieldDateTimeType) Custom Fields.
+  TimeType: |
+    For [CustomFieldTimeType](ctp:api:type:CustomFieldTimeType) Custom Fields.
+  SetType.StringType: |
+    For [CustomFieldSetType](ctp:api:type:CustomFieldSetType) of `StringType` Custom Fields.
+  SetType.LocalizedStringType: |
+    For [CustomFieldSetType](ctp:api:type:CustomFieldSetType) of `LocalizedStringType` Custom Fields.
+  SetType.EnumType: |
+    For [CustomFieldSetType](ctp:api:type:CustomFieldSetType) of `EnumType` Custom Fields.
+  SetType.LocalizedEnumType: |
+    For [CustomFieldSetType](ctp:api:type:CustomFieldSetType) of `LocalizedEnumType` Custom Fields.
+  SetType.NumberType: |
+    For [CustomFieldSetType](ctp:api:type:CustomFieldSetType) of `NumberType` Custom Fields.
+  SetType.DateType: |
+    For [CustomFieldSetType](ctp:api:type:CustomFieldSetType) of `DateType` Custom Fields.
+  SetType.DateTimeType: |
+    For [CustomFieldSetType](ctp:api:type:CustomFieldSetType) of `DateTimeType` Custom Fields.
+  SetType.TimeType: |
+    For [CustomFieldSetType](ctp:api:type:CustomFieldSetType) of `TimeType` Custom Fields.
diff --git a/api-specs/api/types/order-search/OrderSearchQueryExpressionValue.raml b/api-specs/api/types/order-search/OrderSearchQueryExpressionValue.raml
@@ -10,4 +10,4 @@ properties:
     type: number
     format: int32
   customType?:
-    type: string
+    type: OrderSearchCustomType
diff --git a/api-specs/api/types/order/OrderSearchRequest.raml b/api-specs/api/types/order/OrderSearchRequest.raml
@@ -15,10 +15,10 @@ properties:
     format: int32
     default: 10
     maximum: 100
-    description: The maximum number of search results to be returned.
+    description: The maximum number of search results to be returned on one [page](#pagination).
   offset?:
     type: number
     format: int32
     default: 0
     maximum: 10000
-    description: The number of search results to be skipped in the response for pagination.
+    description: The number of search results to be skipped in the response for [pagination](#pagination).
diff --git a/api-specs/api/types/product-selection/ProductSelectionTypeEnum.raml b/api-specs/api/types/product-selection/ProductSelectionTypeEnum.raml
@@ -13,5 +13,5 @@ enum:
   individual: |
     For this type of Product Selection, the Products are to be assigned individually by using the [Add Product](/projects/product-selections#add-product) update action.
   individualExclusion: |
-    Defines the Product Selection to contain Products that are excluded from the catalog ([BETA](/../offering/api-contract#public-beta)).
+    Defines the Product Selection to contain Products that are excluded from the catalog ([BETA](/../offering/api-compatibility#public-beta)).
     For this type of Product Selection, the Products are to be excluded individually by using the [Exclude Product](/projects/product-selections#exclude-product) update action.
diff --git a/api-specs/api/types/product-type/AttributeReferenceTypeId.raml b/api-specs/api/types/product-type/AttributeReferenceTypeId.raml
@@ -12,6 +12,7 @@ enum:
   - category
   - channel
   - customer
+  - customer-group
   - key-value-document
   - order
   - product
@@ -35,6 +36,8 @@ enum:
     References a [Channel](ctp:api:type:Channel).
   customer: |
     References a [Customer](ctp:api:type:Customer).
+  customer-group: |
+    References a [CustomerGroup](ctp:api:type:CustomerGroup).
   key-value-document: |
     References a [CustomObject](ctp:api:type:CustomObject).
   order: |

diff --git a/api-specs/api/types/product/ProductData.raml b/api-specs/api/types/product/ProductData.raml
@@ -51,4 +51,4 @@ properties:
   searchKeywords:
     type: SearchKeywords
     description: |
-      Used by [Product Suggestions](ctp:api:type:ProductSuggestions), but is also considered for a full text search.
+      Used by [Product Suggestions](/projects/products-suggestions), but is also considered for a [full text search](/projects/products-search#full-text-search).
diff --git a/api-specs/api/types/product/ProductDraft.raml b/api-specs/api/types/product/ProductDraft.raml
@@ -63,7 +63,7 @@ properties:
   searchKeywords?:
     type: SearchKeywords
     description: |
-      Used by [Product Suggestions](ctp:api:type:ProductSuggestions), but is also considered for a [full text search](/projects/products-search#full-text-search).
+      Used by [Product Suggestions](/projects/products-suggestions), but is also considered for a [full text search](/projects/products-search#full-text-search).
   state?:
     type: StateResourceIdentifier
     description: |

diff --git a/api-specs/api/types/product/SearchKeyword.raml b/api-specs/api/types/product/SearchKeyword.raml
@@ -6,7 +6,7 @@ properties:
   text:
     type: string
     description: |
-      Text to return in the result of a [suggest query](ctp:api:type:ProductSuggestionsSuggestQuery).
+      Text to return in the [SuggestionResult](ctp:api:type:SuggestionResult).
   suggestTokenizer?:
     type: SuggestTokenizer
     description: |

diff --git a/api-specs/api/types/product/SearchKeywords.raml b/api-specs/api/types/product/SearchKeywords.raml
@@ -6,7 +6,8 @@ type: object
   key: Locale
   value: SearchKeyword[]
 description: |
-  Search keywords are JSON objects primarily used by [Product Suggestions](ctp:api:type:ProductSuggestions), but are also considered for a full text search. The keys are of type [Locale](ctp:api:type:Locale), and the values are an array of [SearchKeyword](ctp:api:type:SearchKeyword).
+  Search keywords are JSON objects primarily used by [Product Suggestions](/projects/products-suggestions), but are also considered for a [full text search](/projects/products-search#full-text-search).
+  The keys are of type [Locale](ctp:api:type:Locale), and the values are an array of [SearchKeyword](ctp:api:type:SearchKeyword).
 example: !include ../../examples/Product/SearchKeywords.json
 properties:
   /^[a-z]{2}(-[A-Z]{2})?$/:

diff --git a/api-specs/api/types/product/SuggestionResult.raml b/api-specs/api/types/product/SuggestionResult.raml
@@ -1,8 +1,12 @@
 #%RAML 1.0 DataType
 (package): Product
 displayName: SuggestionResult
+example: !include ../../examples/product-projection-suggest.example.json
 type: object
 properties:
   /searchKeywords.[a-z]{2}(-[A-Z]{2})?/:
     type: array
     items: Suggestion
+    description: |
+      The result may contain multiple Suggestions identified by their [Locale](ctp:api:type:Locale).
+      See [Suggestions for two languages](/projects/products-suggestions#suggestions-for-two-languages).
diff --git a/api-specs/api/types/search/SearchFieldType.raml b/api-specs/api/types/search/SearchFieldType.raml
@@ -28,46 +28,47 @@ enum:
   - set_reference
 (enumDescriptions):
   boolean: |
-    For Boolean fields and [AttributeBooleanType](ctp:api:type:AttributeBooleanType) Attributes.
+    For Boolean fields, [AttributeBooleanType](ctp:api:type:AttributeBooleanType) Attributes, and [BooleanType](ctp:api:type:CustomFieldBooleanType) Custom Fields.
   text: |
-    For string fields and [AttributeTextType](ctp:api:type:AttributeTextType) Attributes.
+    For string fields, [AttributeTextType](ctp:api:type:AttributeTextType) Attributes, and [StringType](ctp:api:type:CustomFieldStringType) Custom Fields.
   ltext: |
-    For [LocalizedString](types#localizedstring) fields and [AttributeLocalizableTextType](ctp:api:type:AttributeLocalizableTextType) Attributes.
+    For [LocalizedString](types#localizedstring) fields, [AttributeLocalizableTextType](ctp:api:type:AttributeLocalizableTextType) Attributes,
+    and [LocalizedStringType](ctp:api:type:CustomFieldLocalizedStringType) Custom Fields.
   enum: |
-    For enum fields and [AttributeEnumType](ctp:api:type:AttributeEnumType) Attributes.
+    For enum fields, [AttributeEnumType](ctp:api:type:AttributeEnumType) Attributes, and [EnumType](ctp:api:type:CustomFieldEnumType) Custom Fields.
   lenum: |
-    For localized enum fields and [AttributeLocalizedEnumType](ctp:api:type:AttributeLocalizedEnumType) Attributes.
+    For localized enum fields, [AttributeLocalizedEnumType](ctp:api:type:AttributeLocalizedEnumType) Attributes, and [LocalizedEnumType](ctp:api:type:CustomFieldLocalizedEnumType) Custom Fields.
   number: |
-    For number fields and [AttributeNumberType](ctp:api:type:AttributeNumberType) Attributes.
+    For number fields, [AttributeNumberType](ctp:api:type:AttributeNumberType) Attributes, and [NumberType](ctp:api:type:CustomFieldNumberType) Custom Fields.
   money: |
     For [Money](types#money) fields and [AttributeMoneyType](ctp:api:type:AttributeMoneyType) Attributes.
   date: |
-    For [Date](types#date) fields and [AttributeDateType](ctp:api:type:AttributeDateType) Attributes.
+    For [Date](types#date) fields, [AttributeDateType](ctp:api:type:AttributeDateType) Attributes, and [DateType](ctp:api:type:CustomFieldDateType) Custom Fields.
   datetime: |
-    For [DateTime](types#datetime) fields and [AttributeDateTimeType](ctp:api:type:AttributeDateTimeType) Attributes.
+    For [DateTime](types#datetime) fields, [AttributeDateTimeType](ctp:api:type:AttributeDateTimeType) Attributes, and [DateTimeType](ctp:api:type:CustomFieldDateTimeType) Custom Fields.
   time: |
-    For [Time](types#time) fields and [AttributeTimeType](ctp:api:type:AttributeTimeType) Attributes.
+    For [Time](types#time) fields, [AttributeTimeType](ctp:api:type:AttributeTimeType) Attributes, and [TimeType](ctp:api:type:CustomFieldTimeType) Custom Fields.
   reference: |
     For [Reference](types#reference) fields and [AttributeReferenceType](ctp:api:type:AttributeReferenceType) Attributes.
   set_boolean: |
-    For Set of Boolean fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `boolean` Attributes.
+    For Set of Boolean fields, [AttributeSetType](ctp:api:type:AttributeSetType) of `boolean` Attributes, and [SetType](ctp:api:type:CustomFieldSetType) of `boolean` Custom Fields.
   set_text: |
-    For Set of string fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `text` Attributes.
+    For Set of string fields, [AttributeSetType](ctp:api:type:AttributeSetType) of `text` Attributes, and [SetType](ctp:api:type:CustomFieldSetType) of `text` Custom Fields.
   set_ltext: |
-    For Set of [LocalizedString](types#localizedstring) fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `ltext` Attributes.
+    For Set of [LocalizedString](types#localizedstring) fields, [AttributeSetType](ctp:api:type:AttributeSetType) of `ltext` Attributes, and [SetType](ctp:api:type:CustomFieldSetType) of `ltext` Custom Fields.
   set_enum: |
-    For Set of enum fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `enum` Attributes.
+    For Set of enum fields, [AttributeSetType](ctp:api:type:AttributeSetType) of `enum` Attributes, and [SetType](ctp:api:type:CustomFieldSetType) of `enum` Custom Fields.
   set_lenum: |
-    For Set of localized enum fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `lenum` Attributes.
+    For Set of localized enum fields, [AttributeSetType](ctp:api:type:AttributeSetType) of `lenum` Attributes, and [SetType](ctp:api:type:CustomFieldSetType) of `lenum` Custom Fields.
   set_number: |
-    For Set of number fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `number` Attributes.
+    For Set of number fields, [AttributeSetType](ctp:api:type:AttributeSetType) of `number` Attributes, and [SetType](ctp:api:type:CustomFieldSetType) of `number` Custom Fields.
   set_money: |
     For Set of [Money](types#money) fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `money` Attributes.
   set_date: |
-    For Set of [Date](types#date) fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `date` Attributes.
+    For Set of [Date](types#date) fields, [AttributeSetType](ctp:api:type:AttributeSetType) of `date` Attributes, and [SetType](ctp:api:type:CustomFieldSetType) of `date` Custom Fields.
   set_datetime: |
-    For Set of [DateTime](types#datetime) fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `datetime` Attributes.
+    For Set of [DateTime](types#datetime) fields, [AttributeSetType](ctp:api:type:AttributeSetType) of `datetime` Attributes, and [SetType](ctp:api:type:CustomFieldSetType) of `datetime` Custom Fields.
   set_time: |
-    For Set of [Time](types#time) fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `time` Attributes.
+    For Set of [Time](types#time) fields, [AttributeSetType](ctp:api:type:AttributeSetType) of `time` Attributes, and [SetType](ctp:api:type:CustomFieldSetType) of `time` Custom Fields.
   set_reference: |
     For Set of [Reference](types#reference) fields and [AttributeSetType](ctp:api:type:AttributeSetType) of `reference` Attributes.
diff --git a/api-specs/api/types/subscription/AwsAuthenticationMode.raml b/api-specs/api/types/subscription/AwsAuthenticationMode.raml
@@ -10,5 +10,5 @@ enum:
   Credentials: |
     Subscriptions with `Credentials` authentication mode are authenticated using an `accessKey` and `accessSecret` pair. This is the default authentication mode for backwards compatibility.
   IAM: |
-    Subscriptions with `IAM` authentication mode are authenticated using Identity and Access Management (IAM). For this authentication mode, the following user requires permissions to send messages to the queue or publish to the topic: `arn:aws-cn:iam::417094354346:user/subscriptions` if the Project is hosted in the China (AWS, Ningxia) Region; `arn:aws:iam::362576667341:user/subscriptions` for all other [Regions](/../api/general-concepts#regions). This is the recommended authentication mode, as it doesn't require additional key management.
+    Subscriptions with `IAM` authentication mode are authenticated using Identity and Access Management (IAM). For this authentication mode, the following user requires permissions to send notifications to the queue or publish to the topic: `arn:aws-cn:iam::417094354346:user/subscriptions` if the Project is hosted in the China (AWS, Ningxia) Region; `arn:aws:iam::362576667341:user/subscriptions` for all other [Regions](/../api/general-concepts#regions). This is the recommended authentication mode, as it doesn't require additional key management.
 default: Credentials