Updated API from documentation release

Author: ct-sdks[bot]

api-specs/api/resources/in-store/product-projections-in-store.raml

@@ -18,14 +18,22 @@
           },
       ]
     description: |
-      Gets the current or staged representation of a [Product](ctp:api:type:Product) by its key in the specified [Store](ctp:api:type:Store).
+      Retrieves the [projected](/../api/projects/productProjections#projection-dimensions) representation of a [Product](ctp:api:type:Product) by its Key in the specified [Store](ctp:api:type:Store).
+
       If the Store has defined some languages, countries, distribution, supply Channels, and/or Product Selection,
       they are used for projections based on [locale](ctp:api:type:ProductProjectionLocales), [price](ctp:api:type:ProductProjectionPrices),
       and [inventory](ctp:api:type:ProductProjectionInventoryEntries).
       If [ProductSelection](ctp:api:type:ProductSelection) is used, it affects the [availability of the Product](/api/project-configuration-overview#products-available-in-store) in the specified Store.
       If a [ProductTailoring](ctp:api:type:ProductTailoring) exists for the Product with the given `key` and the given Store, this endpoint returns the ProductProjection with tailored data.
-      When used with an API Client that has the `view_published_products:{projectKey}` scope, this endpoint only returns published (current) Product Projections.
 
+      By default, this endpoint returns the `current` representation of Products where the `published` flag is `true`.
+      If a Product is unpublished (`published=false`), the endpoint returns a [Not Found](/../api/errors#404-not-found) error.
+
+      Required access scopes:
+
+      - To retrieve the current representation of published Products (published data), the `view_published_products:{projectKey}` scope is required.
+
+      - To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the `view_products:{projectKey}` scope.
     is:
       - projectionSelectingTailoring
       - priceSelecting
@@ -65,14 +73,22 @@
           },
       ]
     description: |
-      Gets the current or staged representation of a [Product](ctp:api:type:Product) by its ID in the specified [Store](ctp:api:type:Store).
+      Retrieves the [projected](/../api/projects/productProjections#projection-dimensions) representation of a [Product](ctp:api:type:Product) by its ID in the specified [Store](ctp:api:type:Store).
+
       If the Store has defined some languages, countries, distribution, supply Channels, and/or Product Selection,
       they are used for projections based on [locale](ctp:api:type:ProductProjectionLocales), [price](ctp:api:type:ProductProjectionPrices),
       and [inventory](ctp:api:type:ProductProjectionInventoryEntries).
       If [ProductSelection](ctp:api:type:ProductSelection) is used, it affects the [availability of the Product](/api/project-configuration-overview#products-available-in-store) in the specified Store.
-      If a [ProductTailoring](ctp:api:type:ProductTailoring) exists for the Product with the given `id` and the given Store, this endpoint returns the ProductProjection with tailored data.
-      When used with an API Client that has the `view_published_products:{projectKey}` scope, this endpoint only returns published (current) Product Projections.
+      If a [ProductTailoring](ctp:api:type:ProductTailoring) exists for the Product with the given `key` and the given Store, this endpoint returns the ProductProjection with tailored data.
+
+      By default, this endpoint returns the `current` representation of Products where the `published` flag is `true`.
+      If a Product is unpublished (`published=false`), the endpoint returns a [Not Found](/../api/errors#404-not-found) error.
+
+      Required access scopes:
+
+      - To retrieve the current representation of published Products (published data), the `view_published_products:{projectKey}` scope is required.
 
+      - To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the `view_products:{projectKey}` scope.
     is:
       - projectionSelectingTailoring
       - priceSelecting

api-specs/api/resources/product-projections.raml

@@ -22,9 +22,16 @@ get:
         },
     ]
   description: |
-    Use the Product Projections query endpoint to get the current or staged representations of Products.
-    When used with an API Client that has the `view_published_products:{projectKey}` scope,
-    this endpoint only returns published (current) Product Projections.
+    Retrieves the [projected](/../api/projects/productProjections#projection-dimensions) representation of [Products](ctp:api:type:Product) by [query predicates](/../api/predicates/query).
+
+    By default, this endpoint returns the `current` representation of Products where the `published` flag is `true`.
+    If a Product is unpublished (`published=false`), the endpoint returns a [Not Found](/../api/errors#404-not-found) error.
+
+    Required access scopes:
+
+    - To retrieve the current representation of published Products (published data), the `view_published_products:{projectKey}` scope is required.
+
+    - To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the `view_products:{projectKey}` scope.
   is:
     - projectionSelecting
     - priceSelecting
@@ -75,9 +82,16 @@ head:
           },
       ]
     description: |
-      Gets the current or staged representation of a [Product](ctp:api:type:Product) found by Key.
-      When used with an API Client that has the `view_published_products:{projectKey}` scope,
-      this endpoint only returns published (current) Product Projections.
+      Retrieves the [projected](/../api/projects/productProjections#projection-dimensions) representation of a [Product](ctp:api:type:Product) by its Key.
+
+      By default, this endpoint returns the `current` representation of Products where the `published` flag is `true`.
+      If a Product is unpublished (`published=false`), the endpoint returns a [Not Found](/../api/errors#404-not-found) error.
+
+      Required access scopes:
+
+      - To retrieve the current representation of published Products (published data), the `view_published_products:{projectKey}` scope is required.
+
+      - To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the `view_products:{projectKey}` scope.
     is:
       - projectionSelecting
       - priceSelecting
@@ -123,7 +137,16 @@ head:
           },
       ]
     description: |
-      Gets the current or staged representation of a [Product](ctp:api:type:Product) by its ID. When used with an API Client that has the `view_published_products:{projectKey}` scope, this endpoint only returns published (current) Product Projections.
+      Retrieves the [projected](/../api/projects/productProjections#projection-dimensions) representation of a [Product](ctp:api:type:Product) by its ID.
+
+      By default, this endpoint returns the `current` representation of Products where the `published` flag is `true`.
+      If a Product is unpublished (`published=false`), the endpoint returns a [Not Found](/../api/errors#404-not-found) error.
+
+      Required access scopes:
+
+      - To retrieve the current representation of published Products (published data), the `view_published_products:{projectKey}` scope is required.
+
+      - To retrieve the staged representation of Products (draft data) or access unpublished Products, the API Client must have the `view_products:{projectKey}` scope.
     is:
       - projectionSelecting
       - priceSelecting

api-specs/api/types/product-tailoring/ProductTailoring.raml

@@ -55,11 +55,11 @@ properties:
   current:
     type: ProductTailoringData
     description: |
-      Current (published) data of the ProductTailoring.
+      Current data of the ProductTailoring returned in the [Product Projection](/projects/productProjections) response when the ProductTailoring is published.
   staged:
     type: ProductTailoringData
     description: |
-      Staged (unpublished) data of the ProductTailoring.
+      Staged data of the ProductTailoring. This data is not returned in the Product Projection response by default.
   hasStagedChanges:
     type: boolean
     description: |

api-specs/api/types/product/ProductCatalogData.raml

@@ -8,7 +8,7 @@ properties:
   published:
     type: boolean
     description: |
-      `true` if the Product is published.
+      If `true`, the `current` representation of the Product is retrievable in the [Product Projection](/projects/productProjections) endpoints and indexed for [Product Search](/../api/projects/product-search).
   current:
     type: ProductData
     description: |

api-specs/api/types/product/ProductDraft.raml

@@ -74,7 +74,9 @@ properties:
   publish?:
     type: boolean
     description: |
-      If `true`, the Product is published immediately to the current projection.
+      If `true`, the platform sets the `published` flag on the resulting [ProductCatalogData](ctp:api:type:ProductCatalogData) to `true`.
+      This makes the current representation retrievable in [Product Projection](/projects/productProjections) endpoints and indexes it for [Product Search](/../api/projects/product-search).
+      You can also set this flag later using the [Publish](/projects/products#publish) update action.
     default: false
   priceMode?:
     type: ProductPriceModeEnum

api-specs/api/types/product/ProductPublishScope.raml

@@ -8,5 +8,5 @@ enum:
   - All
   - Prices
 (enumDescriptions):
-  All: Publishes a Product that causes the _staged_ projection of the Product to override the _current_ projection. If the Product is published for the first time, the _current_ projection is created. This is the default scope.
+  All: Publishes a Product that causes the _staged_ projection of the Product to override the _current_ projection. This is the default scope.
   Prices: Publishes the Prices of the Product (only if the Product is already published). All Product Variants' Prices in the _staged_ projection are published into the _current_ projection with the same `id`. Prices in a _staged_ Product Variant that has no _current_ projection are not published. Prices in a _current_ Product Variant that has no _staged_ projection are unchanged. The `hasStagedChanges` [flag](ctp:api:type:ProductCatalogData) is updated according to whether the _staged_ and _current_ projections still differ after the prices are published.

api-specs/api/types/product/updates/ProductPublishAction.raml

@@ -4,7 +4,9 @@ type: ProductUpdateAction
 displayName: ProductPublishAction
 discriminatorValue: publish
 description: |-
-  Publishes product data from the Product's staged projection to its current projection.
+  Copies the product data from the Product's staged representation to its current representation and sets the `published` flag on the resulting [ProductCatalogData](ctp:api:type:ProductCatalogData) to `true`.
+  This makes the current representation retrievable in [Product Projection](/projects/productProjections) endpoints and indexes it for [Product Search](/../api/projects/product-search).
+
   Produces the [ProductPublished](ctp:api:type:ProductPublishedMessage) Message.
 example: !include ../../../examples/Product/ProductPublishAction.json
 properties:

api-specs/api/types/product/updates/ProductUnpublishAction.raml

@@ -5,7 +5,11 @@ displayName: ProductUnpublishAction
 discriminatorValue: unpublish
 example: !include ../../../examples/Product/ProductUnpublishAction.json
 description: |
-  Removes the current [projection](/../api/projects/productProjections#current--staged) of the Product. The staged projection is unaffected. To retrieve unpublished Products, the `staged` parameter must be set to `false` when [querying](ctp:api:endpoint:/{projectKey}/product-projections:GET)/[searching](/projects/product-projection-search#product-projection-search) Product Projections. Produces the [ProductUnpublished](ctp:api:type:ProductUnpublishedMessage) Message.
+  Sets the `published` flag on the [ProductCatalogData](ctp:api:type:ProductCatalogData) to `false`.
+  This makes the [current](/../api/projects/productProjections#current--staged) representation of a Product unavailable in [Product Projection](/projects/productProjections) endpoints by default, and excludes it from [Product Search](/../api/projects/product-search).
+  To retrieve unpublished Products on Product Projection endpoints, set parameter `staged=true`.
+
+  Produces the [ProductUnpublished](ctp:api:type:ProductUnpublishedMessage) Message.
 
   When a Product is unpublished, any associated Line Items already present in a Cart remain unaffected and can still be ordered. To prevent this, do the following: