PCAT-831 - updates to /skus public docs for reseller integration (updating example section and error codes)

.generator/schemas/v2/openapi.yaml

@@ -86884,8 +86884,17 @@ components:
           $ref: '#/components/schemas/ProductCatalogSKUOnDemandOption'
         number_of_units_included_in_price:
           description: |-
-            The number of billable usage units included in the price. `0` for SKUs that are not
-            priced per unit of usage, such as those whose `pricing_type` is `percent`.
+            The number of billable usage units that one unit of price covers. Divide measured
+            usage by this value before multiplying by the price. For example, a SKU priced at `18.00` with
+            `number_of_units_included_in_price` of `1` costs `18.00` per host, while a SKU priced
+            at `12.00` with `number_of_units_included_in_price` of `10000` costs `12.00` per
+            10,000 requests. It is a scaling factor on the price, not a free allotment; included
+            quantities are in `allotments`. The same factor applies to the price of a tier in
+            `on_demand_tiered` whose `pricing_unit_type` is `unit`. It does not apply to a tier
+            whose `pricing_unit_type` is `block`: that tier's `price` is charged for the whole
+            block bounded by `min_usage_quantity` and `max_usage_quantity`, however much of the
+            block is used. `0` for SKUs that are not priced per unit of usage, such as those
+            whose `pricing_type` is `percent`.
           example: 1
           format: int64
           type: integer
@@ -86904,7 +86913,7 @@ components:
           $ref: '#/components/schemas/ProductCatalogSKUPricingType'
         sku_name:
           description: The human-readable name of the SKU.
-          example: Infra Pro
+          example: Infra Host (Pro)
           type: string
       required:
         - billing_dimension
@@ -186462,7 +186471,10 @@ paths:
         this endpoint is not paginated.
       operationId: ListProductCatalogSKUs
       parameters:
-        - description: The version of the product catalog contract to return. `v1` is the latest.
+        - description: |-
+            The version of the product catalog response contract to return. `v1` is the latest.
+            This is independent of the `/api/v2` path segment, which is the version of the
+            Datadog API itself.
           example: v1
           in: query
           name: version
@@ -186472,7 +186484,8 @@ paths:
         - description: |-
             The date the returned prices, allotments, and pricing tiers are effective as of, in
             `YYYY-MM-DD` format. Defaults to the date of the request, and must not be later
-            than it.
+            than it. Set it to a date in a past billing period to reconcile that period against
+            the prices that were in effect then, rather than today.
           example: "2026-07-01"
           in: query
           name: as_of_date
@@ -186531,15 +186544,11 @@ paths:
                           on_demand_list_price: "18.00"
                           on_demand_tiered:
                           pricing_type: usage
-                          sku_name: Infra Pro
+                          sku_name: Infra Host (Pro)
                         id: HOSTS-PRO
                         type: Sku
                       - attributes:
-                          allotments:
-                            - child_sku_code: SDS
-                              hourly_quantity: 1
-                              monthly_quantity: 1
-                              parent_sku_code: LLM-OBSERVABILITY-MIN-SPEND
+                          allotments: []
                           billing_dimension: llm_observability_min_spend
                           billing_units: requests
                           currency: USD
@@ -186566,18 +186575,43 @@ paths:
         "400":
           content:
             application/json:
+              examples:
+                default:
+                  value:
+                    errors:
+                      - detail: as_of_date must not be later than the date of the request
+                        source:
+                          parameter: as_of_date
+                        status: "400"
+                        title: Bad Request
               schema:
                 $ref: '#/components/schemas/JSONAPIErrorResponse'
           description: Bad Request - version is missing or invalid, or as_of_date is malformed or in the future
         "403":
           content:
             application/json:
+              examples:
+                default:
+                  value:
+                    errors:
+                      - detail: this endpoint requires the billing_read or usage_read permission
+                        status: "403"
+                        title: Forbidden
               schema:
                 $ref: '#/components/schemas/JSONAPIErrorResponse'
           description: Forbidden - the caller has neither the billing_read nor the usage_read permission
         "404":
           content:
             application/json:
+              examples:
+                default:
+                  value:
+                    errors:
+                      - detail: the requested product catalog version is not supported
+                        source:
+                          parameter: version
+                        status: "404"
+                        title: Not Found
               schema:
                 $ref: '#/components/schemas/JSONAPIErrorResponse'
           description: Not Found - the requested catalog version is not supported

src/main/java/com/datadog/api/client/v2/api/ProductCatalogApi.java

@@ -55,7 +55,8 @@ public static class ListProductCatalogSKUsOptionalParameters {
      *
      * @param asOfDate The date the returned prices, allotments, and pricing tiers are effective as
      *     of, in <code>YYYY-MM-DD</code> format. Defaults to the date of the request, and must not
-     *     be later than it. (optional)
+     *     be later than it. Set it to a date in a past billing period to reconcile that period
+     *     against the prices that were in effect then, rather than today. (optional)
      * @return ListProductCatalogSKUsOptionalParameters
      */
     public ListProductCatalogSKUsOptionalParameters asOfDate(OffsetDateTime asOfDate) {
@@ -69,8 +70,9 @@ public ListProductCatalogSKUsOptionalParameters asOfDate(OffsetDateTime asOfDate
    *
    * <p>See {@link #listProductCatalogSKUsWithHttpInfo}.
    *
-   * @param version The version of the product catalog contract to return. <code>v1</code> is the
-   *     latest. (required)
+   * @param version The version of the product catalog response contract to return. <code>v1</code>
+   *     is the latest. This is independent of the <code>/api/v2</code> path segment, which is the
+   *     version of the Datadog API itself. (required)
    * @return ProductCatalogSKUsResponse
    * @throws ApiException if fails to make API call
    */
@@ -86,8 +88,9 @@ version, new ListProductCatalogSKUsOptionalParameters())
    *
    * <p>See {@link #listProductCatalogSKUsWithHttpInfoAsync}.
    *
-   * @param version The version of the product catalog contract to return. <code>v1</code> is the
-   *     latest. (required)
+   * @param version The version of the product catalog response contract to return. <code>v1</code>
+   *     is the latest. This is independent of the <code>/api/v2</code> path segment, which is the
+   *     version of the Datadog API itself. (required)
    * @return CompletableFuture&lt;ProductCatalogSKUsResponse&gt;
    */
   public CompletableFuture<ProductCatalogSKUsResponse> listProductCatalogSKUsAsync(
@@ -105,8 +108,9 @@ version, new ListProductCatalogSKUsOptionalParameters())
    *
    * <p>See {@link #listProductCatalogSKUsWithHttpInfo}.
    *
-   * @param version The version of the product catalog contract to return. <code>v1</code> is the
-   *     latest. (required)
+   * @param version The version of the product catalog response contract to return. <code>v1</code>
+   *     is the latest. This is independent of the <code>/api/v2</code> path segment, which is the
+   *     version of the Datadog API itself. (required)
    * @param parameters Optional parameters for the request.
    * @return ProductCatalogSKUsResponse
    * @throws ApiException if fails to make API call
@@ -122,8 +126,9 @@ public ProductCatalogSKUsResponse listProductCatalogSKUs(
    *
    * <p>See {@link #listProductCatalogSKUsWithHttpInfoAsync}.
    *
-   * @param version The version of the product catalog contract to return. <code>v1</code> is the
-   *     latest. (required)
+   * @param version The version of the product catalog response contract to return. <code>v1</code>
+   *     is the latest. This is independent of the <code>/api/v2</code> path segment, which is the
+   *     version of the Datadog API itself. (required)
    * @param parameters Optional parameters for the request.
    * @return CompletableFuture&lt;ProductCatalogSKUsResponse&gt;
    */
@@ -150,8 +155,9 @@ public CompletableFuture<ProductCatalogSKUsResponse> listProductCatalogSKUsAsync
    * by that code in ascending order. The whole catalog is returned in a single response, so this
    * endpoint is not paginated.
    *
-   * @param version The version of the product catalog contract to return. <code>v1</code> is the
-   *     latest. (required)
+   * @param version The version of the product catalog response contract to return. <code>v1</code>
+   *     is the latest. This is independent of the <code>/api/v2</code> path segment, which is the
+   *     version of the Datadog API itself. (required)
    * @param parameters Optional parameters for the request.
    * @return ApiResponse&lt;ProductCatalogSKUsResponse&gt;
    * @throws ApiException if fails to make API call
@@ -218,8 +224,9 @@ public ApiResponse<ProductCatalogSKUsResponse> listProductCatalogSKUsWithHttpInf
    *
    * <p>See {@link #listProductCatalogSKUsWithHttpInfo}.
    *
-   * @param version The version of the product catalog contract to return. <code>v1</code> is the
-   *     latest. (required)
+   * @param version The version of the product catalog response contract to return. <code>v1</code>
+   *     is the latest. This is independent of the <code>/api/v2</code> path segment, which is the
+   *     version of the Datadog API itself. (required)
    * @param parameters Optional parameters for the request.
    * @return CompletableFuture&lt;ApiResponse&lt;ProductCatalogSKUsResponse&gt;&gt;
    */

src/main/java/com/datadog/api/client/v2/model/ProductCatalogSKUDataAttributesResponse.java

@@ -243,9 +243,18 @@ public ProductCatalogSKUDataAttributesResponse numberOfUnitsIncludedInPrice(
   }
 
   /**
-   * The number of billable usage units included in the price. <code>0</code> for SKUs that are not
-   * priced per unit of usage, such as those whose <code>pricing_type</code> is <code>percent</code>
-   * .
+   * The number of billable usage units that one unit of price covers. Divide measured usage by this
+   * value before multiplying by the price. For example, a SKU priced at <code>18.00</code> with
+   * <code>number_of_units_included_in_price</code> of <code>1</code> costs <code>18.00</code> per
+   * host, while a SKU priced at <code>12.00</code> with <code>number_of_units_included_in_price
+   * </code> of <code>10000</code> costs <code>12.00</code> per 10,000 requests. It is a scaling
+   * factor on the price, not a free allotment; included quantities are in <code>allotments</code>.
+   * The same factor applies to the price of a tier in <code>on_demand_tiered</code> whose <code>
+   * pricing_unit_type</code> is <code>unit</code>. It does not apply to a tier whose <code>
+   * pricing_unit_type</code> is <code>block</code>: that tier's <code>price</code> is charged for
+   * the whole block bounded by <code>min_usage_quantity</code> and <code>max_usage_quantity</code>,
+   * however much of the block is used. <code>0</code> for SKUs that are not priced per unit of
+   * usage, such as those whose <code>pricing_type</code> is <code>percent</code>.
    *
    * @return numberOfUnitsIncludedInPrice
    */