Updated api-reference from documentation release

commercetools · Aug 5, 2024 · f8c14ad · f8c14ad
1 parent 66f1b6f
commit f8c14ad
Show file tree

Hide file tree

Showing 21 changed files with 801 additions and 241 deletions.
diff --git a/api-specs/api/resources/in-store.raml b/api-specs/api/resources/in-store.raml
diff --git a/api-specs/api/resources/me.raml b/api-specs/api/resources/me.raml
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/LineItemPriceMode.raml b/api-specs/api/types/cart/LineItemPriceMode.raml
@@ -20,5 +20,5 @@ enum:
     The Line Item price with the total is set externally.
     Cart Discounts are deactivated for Line Items with this price mode, despite a matching [CartDiscountLineItemsTarget](ctp:api:type:CartDiscountLineItemsTarget) or [MultiBuyLineItemsTarget](ctp:api:type:MultiBuyLineItemsTarget).
     Although a Line Item with this price mode has both `price` and `totalPrice` set externally, only `totalPrice` is used to calculate the total price of a Cart.
-    All update actions that change the quantity of a Line Item with this price mode can set the new price with the `externalTotal` field.
-    If the `externalTotal` field is not given in the update actions, the external price is unset and the price mode is set to `Platform`.
+    All update actions that change the quantity of a Line Item with this price mode can set the new price with the `externalTotalPrice` field.
+    If the `externalTotalPrice` field is not given in the update actions, the external price is unset and the price mode is set to `Platform`.
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/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/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
diff --git a/api-specs/api/types/subscription/AzureEventGridDestination.raml b/api-specs/api/types/subscription/AzureEventGridDestination.raml
@@ -5,8 +5,8 @@ displayName: AzureEventGridDestination
 discriminatorValue: EventGrid
 example: !include ../../examples/Subscription/SubscriptionAzureEventGridDestination.json
 description: |
-  [Azure Event Grid](https://azure.microsoft.com/en-us/products/event-grid/) can be used to push messages to Azure Functions, HTTP endpoints (webhooks), and several other Azure tools. Event Grid can only be used with the [CloudEventsFormat](ctp:api:type:CloudEventsFormat).
-  To set up a Subscription with Azure Event Grid, first create a topic in the [Azure Portal](https://azure.microsoft.com/en-us/get-started/azure-portal/). To allow Composable Commerce to push messages to your topic, provide an [access key](https://docs.microsoft.com/en-us/azure/event-grid/get-access-keys).
+  [Azure Event Grid](https://azure.microsoft.com/en-us/products/event-grid/) can be used to push notifications to Azure Functions, HTTP endpoints (webhooks), and several other Azure tools. Event Grid can only be used with the [CloudEventsFormat](ctp:api:type:CloudEventsFormat).
+  To set up a Subscription with Azure Event Grid, first create a topic in the [Azure Portal](https://azure.microsoft.com/en-us/get-started/azure-portal/). To allow Composable Commerce to push notifications to your topic, provide an [access key](https://docs.microsoft.com/en-us/azure/event-grid/get-access-keys).
 properties:
   uri:
     type: string

diff --git a/api-specs/api/types/subscription/AzureServiceBusDestination.raml b/api-specs/api/types/subscription/AzureServiceBusDestination.raml
@@ -5,7 +5,7 @@ displayName: AzureServiceBusDestination
 discriminatorValue: AzureServiceBus
 example: !include ../../examples/Subscription/SubscriptionAzureServiceBusDestination.json
 description: |
-  [Azure Service Bus](https://azure.microsoft.com/en-us/products/service-bus/) can be used as a pull-queue with [Queues](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#queues), or to fan-out messages with [Topics and Subscriptions](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions).
+  [Azure Service Bus](https://azure.microsoft.com/en-us/products/service-bus/) can be used as a pull-queue with [Queues](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#queues), or to fan-out notifications with [Topics and Subscriptions](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions).
   To set up a Subscription with Azure Service Bus, first create a queue/topic in the [Azure Portal](https://azure.microsoft.com/en-us/get-started/azure-portal/) with a Shared Access Policy including the `Send` permission.
 properties:
   connectionString:

diff --git a/api-specs/api/types/subscription/ChangeSubscriptionResourceTypeId.raml b/api-specs/api/types/subscription/ChangeSubscriptionResourceTypeId.raml
@@ -79,7 +79,7 @@ enum:
   key-value-document: |
     Changes to [CustomObjects](ctp:api:type:CustomObject).
   order: |
-    Changes to [Orders](ctp:api:type:Order). Changes to Orders via [Order Edits](/../api/projects/order-edits) do not trigger a Message. To achieve this, a [MessageSubscription](ctp:api:type:MessageSubscription) to [OrderEditApplied](ctp:api:type:OrderEditAppliedMessage) Message is necessary.
+    Changes to [Orders](ctp:api:type:Order). Modifying Orders via [Order Edits](/../api/projects/order-edits) does not trigger a notification. To achieve this, a [MessageSubscription](ctp:api:type:MessageSubscription) to the [OrderEditApplied](ctp:api:type:OrderEditAppliedMessage) Message is necessary.
   order-edit: |
     Changes to [OrderEdits](ctp:api:type:OrderEdit).
   payment: |

diff --git a/api-specs/api/types/subscription/CloudEventsPayload.raml b/api-specs/api/types/subscription/CloudEventsPayload.raml
@@ -5,7 +5,7 @@ displayName: CloudEventsPayload
 discriminatorValue: CloudEvents
 example: !include ../../examples/Subscription/cloudevents-payload.example.json
 description: |
-  The [CloudEventsFormat](ctp:api:type:CloudEventsFormat) represents event data in a way that conforms to a common specification. The message payload can be found inside the `data` field.
+  The [CloudEventsFormat](ctp:api:type:CloudEventsFormat) represents event data in a way that conforms to a common specification. The payload can be found inside the `data` field.
 properties:
   specversion:
     type: string

diff --git a/api-specs/api/types/subscription/ConfluentCloudDestination.raml b/api-specs/api/types/subscription/ConfluentCloudDestination.raml
@@ -5,9 +5,9 @@ displayName: ConfluentCloudDestination
 discriminatorValue: ConfluentCloud
 example: !include ../../examples/Subscription/SubscriptionConfluentCloudDestination.json
 description: |
-  This destination can be used to push events and messages to [Confluent Cloud](https://www.confluent.io/confluent-cloud/).
+  This destination can be used to push notifications to [Confluent Cloud](https://www.confluent.io/confluent-cloud/).
   To set up a Subscription of this type, first, create a topic in Confluent Cloud.
-  Then, to allow Composable Commerce to push events and messages to your topic, generate [API keys](https://docs.confluent.io/cloud/current/access-management/authenticate/api-keys/api-keys.html) for your topic, and create the Subscription destination using the generated credentials.
+  Then, to allow Composable Commerce to push notifications to your topic, generate [API keys](https://docs.confluent.io/cloud/current/access-management/authenticate/api-keys/api-keys.html) for your topic, and create the Subscription destination using the generated credentials.
 
   The Composable Commerce producer uses the following values: `SASL_SSL` for`security.protocol`, `PLAIN` for`sasl.mechanism`, and the default value (1048576) for `max.request.size`.
 properties:

diff --git a/api-specs/api/types/subscription/DeliveryPayload.raml b/api-specs/api/types/subscription/DeliveryPayload.raml
@@ -10,15 +10,15 @@ properties:
     type: string
     description: |
       `key` of the [Project](ctp:api:type:Project).
-      Useful in message processing if the Destination receives events from multiple Projects.
+      Useful for processing notifications if the Destination receives them from multiple Projects.
   notificationType:
     type: string
     description: |
       Identifies the payload.
   resource:
     type: Reference
     description: |
-      Reference to the resource that triggered the message.
+      Reference to the resource that triggered the notification.
   resourceUserProvidedIdentifiers?:
     type: UserProvidedIdentifiers
     description: |

diff --git a/api-specs/api/types/subscription/GoogleCloudPubSubDestination.raml b/api-specs/api/types/subscription/GoogleCloudPubSubDestination.raml
@@ -8,7 +8,7 @@ description: |
   Destination for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/) that can be used
   for [Pull subscriptions](https://cloud.google.com/pubsub/docs/pull) as well as for [Push subscriptions](https://cloud.google.com/pubsub/docs/push).
   The `topic` must give the `pubsub.topics.publish` permission to the service account `[email protected]`.
-  If used with the [CloudEventsFormat](#cloudeventsformat), the message conforms to the [PubSub Protocol Binding](https://github.com/google/knative-gcp/blob/master/docs/spec/pubsub-protocol-binding.md) of the [Structured Content Mode](https://github.com/google/knative-gcp/blob/master/docs/spec/pubsub-protocol-binding.md#32-structured-content-mode).
+  If used with the [CloudEventsFormat](#cloudeventsformat), the notification conforms to the [PubSub Protocol Binding](https://github.com/google/knative-gcp/blob/master/docs/spec/pubsub-protocol-binding.md) of the [Structured Content Mode](https://github.com/google/knative-gcp/blob/master/docs/spec/pubsub-protocol-binding.md#32-structured-content-mode).
 properties:
   projectId:
     type: string

diff --git a/api-specs/api/types/subscription/MessageDeliveryPayload.raml b/api-specs/api/types/subscription/MessageDeliveryPayload.raml
@@ -34,7 +34,7 @@ properties:
     type: number
     format: int64
     description: |
-      Version of the resource on which the change was performed.
+      Version of the resource on which the update was performed.
   payloadNotIncluded?:
     type: PayloadNotIncluded
     description: |

diff --git a/api-specs/api/types/subscription/SnsDestination.raml b/api-specs/api/types/subscription/SnsDestination.raml
@@ -7,7 +7,7 @@ example: !include ../../examples/Subscription/SubscriptionSnsDestination.json
 description: |
   [AWS SNS](https://aws.amazon.com/sns/) can be used to push messages to AWS Lambda, HTTP endpoints (webhooks), or fan-out messages to SQS queues. The SQS queue must be a [Standard](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/standard-queues.html) queue type.
 
-  We recommend setting `authenticationMode` to `IAM`, to avoid unnecessary key management. For IAM authentication and before creating the Subscription, give permissions to the following user account: `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). Otherwise, a test message will not be sent.
+  We recommend setting `authenticationMode` to `IAM`, to avoid unnecessary key management. For IAM authentication and before creating the Subscription, give permissions to the following user account: `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). Otherwise, a test notification will not be sent.
 
   If you prefer to use `Credentials` for authentication, we recommend [creating an IAM user](https://docs.aws.amazon.com/sns/latest/dg/sns-setting-up.html#create-iam-user) with an `accessKey` and `accessSecret` pair specifically for each Subscription.
 

diff --git a/api-specs/api/types/subscription/Subscription.raml b/api-specs/api/types/subscription/Subscription.raml
@@ -36,11 +36,11 @@ properties:
   changes:
     type: ChangeSubscription[]
     description: |
-      Change notifications subscribed to.
+      Changes subscribed to.
   destination:
     type: Destination
     description: |
-      Messaging service to which the messages are to be sent.
+      Messaging service to which the notifications are sent.
   key?:
     type: string
     description: |

diff --git a/api-specs/api/types/subscription/SubscriptionDraft.raml b/api-specs/api/types/subscription/SubscriptionDraft.raml
@@ -9,11 +9,11 @@ properties:
   changes?:
     type: ChangeSubscription[]
     description: |
-      Change notifications to be subscribed to.
+      Changes to be subscribed to.
   destination:
     type: Destination
     description: |
-      Messaging service to which the messages are sent.
+      Messaging service to which the notifications are sent.
   key?:
     type: string
     description: |

diff --git a/api-specs/api/types/subscription/SubscriptionHealthStatus.raml b/api-specs/api/types/subscription/SubscriptionHealthStatus.raml
@@ -2,14 +2,14 @@
 (package): Subscription
 displayName: SubscriptionHealthStatus
 description: |
-  The health status of the Subscription that indicates whether messages are being delivered.
+  The health status of the Subscription that indicates whether notifications are being delivered.
 type: string
 (enumDescriptions):
-  Healthy: Delivers messages as expected.
-  ConfigurationError: Messages cannot be delivered with the current configuration. Common causes are deleting the Destination queue, deleting access credentials, or removing the necessary permissions. The configuration can be fixed by re-creating the configuration on the Destination side, or by setting a new configuration with the [Change Destination](/../api/projects/subscriptions#change-destination) update action. If the configuration is fixed, undelivered messages will be delivered and the `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus). `ConfigurationError` is automatically turned into `ConfigurationErrorDeliveryStopped` after some time. For more information, see [Delivery Guarantees](#delivery-guarantees).
-  ConfigurationErrorDeliveryStopped: Does not deliver messages with the current configuration and the delivery of the messages is no longer attempted. If the configuration is fixed, undelivered messages are not retained and will not be delivered. The `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus) as soon as new messages can be delivered.
-  TemporaryError: Does not deliver messages temporarily due to reasons other than a configuration error. For example, the Destination has a temporary outage.
-  ManuallySuspended: Does not deliver messages with the current configuration and the delivery of the messages is no longer attempted. Undelivered messages are not retained and will not be delivered. The `status` will not automatically change to [Healthy](ctp:api:type:SubscriptionHealthStatus). To return your subscriptions to a [Healthy](ctp:api:type:SubscriptionHealthStatus) status, contact the [Composable Commerce support team](https://support.commercetools.com/).
+  Healthy: Delivers notifications as expected.
+  ConfigurationError: Notifications cannot be delivered with the current configuration. Common causes are deleting the Destination queue, deleting access credentials, or removing necessary permissions. You can fix the configuration by re-creating the configuration on the Destination side, or by setting a new configuration with the [Change Destination](/../api/projects/subscriptions#change-destination) update action. After the configuration is fixed, undelivered notifications will be delivered and the `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus). `ConfigurationError` is automatically turned into `ConfigurationErrorDeliveryStopped` after some time. For more information, see [Delivery Guarantees](#delivery-guarantees).
+  ConfigurationErrorDeliveryStopped: Does not deliver notifications with the current configuration and the delivery of the notifications is no longer attempted. After the configuration is fixed, undelivered notifications are not retained and will not be delivered. The `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus) as soon as new notifications can be delivered.
+  TemporaryError: Does not deliver notifications temporarily due to reasons other than a configuration error. For example, the Destination has a temporary outage.
+  ManuallySuspended: Does not deliver notifications with the current configuration and the delivery of the notifications is no longer attempted. Undelivered notifications are not retained and will not be delivered. The `status` will not automatically change to [Healthy](ctp:api:type:SubscriptionHealthStatus). To return your subscriptions to a [Healthy](ctp:api:type:SubscriptionHealthStatus) status, contact the [Composable Commerce support team](https://support.commercetools.com/).
 
 enum:
   - Healthy

diff --git a/api-specs/api/types/subscription/updates/SubscriptionChangeDestinationAction.raml b/api-specs/api/types/subscription/updates/SubscriptionChangeDestinationAction.raml
@@ -5,7 +5,7 @@ displayName: SubscriptionChangeDestinationAction
 discriminatorValue: changeDestination
 example: !include ../../../examples/Subscription/SubscriptionChangeDestinationAction.json
 description: |
-  A test message is sent to ensure the correct configuration of the Destination. If the message cannot be delivered, the update will fail. The payload of the test message is a notification of type [ResourceCreated](ctp:api:type:ResourceCreatedDeliveryPayload) for the `resourceTypeId` `subscription`. The `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus), if it isn't already.
+  A test notification is sent to ensure the correct configuration of the Destination. If the notification cannot be delivered, the update will fail. The payload of the test notification is of type [ResourceCreated](ctp:api:type:ResourceCreatedDeliveryPayload) for the `resourceTypeId` `subscription`. The `status` will change to [Healthy](ctp:api:type:SubscriptionHealthStatus), if it isn't already.
 properties:
   destination:
     type: Destination

diff --git a/api-specs/api/types/type/CustomFieldReferenceValue.raml b/api-specs/api/types/type/CustomFieldReferenceValue.raml
@@ -13,6 +13,7 @@ enum:
   - category
   - channel
   - customer
+  - customer-group
   - key-value-document
   - order
   - product
@@ -38,6 +39,8 @@ enum:
     [Channel](ctp:api:type:Channel)
   customer: |
     [Customer](ctp:api:type:Customer)
+  customer-group: |
+    [CustomerGroup](ctp:api:type:CustomerGroup)
   key-value-document: |
     [CustomObject](ctp:api:type:CustomObject)
   order: |