---
title: "Approved samples by variant"
method: POST
path: "/samples/approved-by-variant"
tags: ["Samples"]
---

# Approved samples by variant

`POST /samples/approved-by-variant`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/samples/approved-by-variant`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

Approved sample counts broken down by variant (SKU), for every product with approvals in the window. Each product's `approved_total` is the sum of its own `variants` rows, guaranteed by construction because both read the same approval definition as the portal's Samples approved card and `/samples/daily-by-product` — except that endpoint keeps only its most recent 92 days for any longer window, while this endpoint does not clamp, so the two can diverge on a window longer than that — and briefly if `/samples/daily-by-product` itself degrades to a slower fallback source for that window, which it reports via its own `stage_sources`. It will NOT generally equal a status count from `/samples/list`, which reflects each request's CURRENT status rather than counting every approval event.

`sku_id` and `sku_desc` are null for applies made with no variant selected (the product-level default). Set `x-shop-id` to a single shop.

Pagination is over PRODUCTS, not variants.

## Request body

- SamplesApprovedByVariantRequest: POST /samples/approved-by-variant request body (CORE-9059). Dates are REQUIRED, matching ``/samples/daily-by-product``.
  - `start_date` string, date, required: First day of the window (inclusive).
  - `end_date` string, date, required: Last day of the window (inclusive).
  - `product_ids` string[], nullable: Restrict to these products. Omit for every product with approvals in the window.
  - `page` integer: Page over PRODUCTS (rows), not variants.
  - `page_size` integer

## Response `200`

Successful Response

- SamplesApprovedByVariantResponse: Approved sample counts by (product, variant) for one shop (CORE-9059).
  - `data` SampleApprovedByProductItem[], required
    - `product_id` string, required
    - `product_name` string, nullable: Catalog name; falls back to the product_id when the catalog has no row.
    - `approved_total` integer, required
    - `variants` SampleApprovedVariantItem[], required
      - `sku_id` string, nullable: Null for applies with no variant selected (the product-level default).
      - `sku_desc` string, nullable: Variant label from the product catalog, when known.
      - `approved` integer, required
  - `pagination` PublicApiCorePaginationPaginationMeta, required: Pagination metadata returned in responses.
    - `total_count` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_pages` integer, required
  - `date_range` DateRange, required
    - `start_date` string, nullable
    - `end_date` string, nullable

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-21** `2c951b1851c2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/samples/approved-by-variant/post.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)