---
title: "Preview Promo Codes"
method: GET
path: "/api/v1/admin/reports/promo-codes/preview"
tags: ["Admin APIs", "Admin - Reports"]
---

# Preview Promo Codes

`GET /api/v1/admin/reports/promo-codes/preview`

Preview promo code usage by customer + plan.

Source of truth:
- Local `plans` joined to local `stripe_subscriptions.raw`
- If the subscription discount references a promotion code id, we retrieve the PromotionCode
  from Stripe to get the *human* promo code string (e.g. "SAVE20").

## Query parameters

- `client_id` string, nullable — Filter by client ID
- `has_promo_code` string — Filter by whether a promo code is applied: all|yes|no
- `promo_code` string, nullable — Filter by specific promo code (e.g. SAVE20)
- `start_date` string, nullable — Start date (YYYY-MM-DD)
- `end_date` string, nullable — End date (YYYY-MM-DD)
- `page` integer — Page number
- `per_page` integer — Items per page

## Response `200`

Successful Response

- PromoCodesReportPreviewResponse
  - `data` PromoCodesReportRow[], required
    - `id` string, required
    - `client_id` string, required
    - `client_name` string, required
    - `plan_id` string, required
    - `plan_name` string, required
    - `stripe_subscription_id` string, nullable
    - `subscription_start_date` string, date-time, nullable
    - `subscription_end_date` string, date-time, nullable
    - `promo_code` string, nullable
    - `promotion_code_id` string, nullable
    - `coupon_id` string, nullable
    - `discounts` DiscountDetail[]
      - `discount_id` string, nullable
      - `promo_code` string, nullable
      - `promotion_code_id` string, nullable
      - `coupon_id` string, nullable
      - `coupon_name` string, nullable
      - `percent_off` number, nullable
      - `amount_off` integer, nullable
      - `duration` string, nullable
      - `duration_in_months` integer, nullable
      - `source` string, nullable
      - `start` integer, nullable
      - `end` integer, nullable
      - `first_seen_at` string, nullable
  - `total` integer, required
  - `page` integer, required
  - `per_page` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api.md) · [All operations](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/carbonarc/carbon-arc-client-admin-api/revisions/a8ca30023371/schema)