---
title: "List products"
method: GET
path: "/api/products"
tags: ["products"]
---

# List products

`GET /api/products`

## Request

- Base URL: `https://api.depixapp.com`
- URL: `https://api.depixapp.com/api/products`
- Auth: HTTP bearer

Paginated product list with checkout aggregates, filtered to the key's mode. Requires scope `merchant_read` on the API-key path.

## Query parameters

- `kind` 'product' | 'charge' | 'all'
- `active` '1' | '0' | 'true' | 'false'
- `q` string
- `limit` integer
- `offset` integer

## Response `200`

Product list.

- ProductListResponse: Paginated product list.
  - `products` ProductListItem[], required: Product rows.
    - `id` string, required: Product id (prd_*).
    - `slug` string, required: URL slug.
    - `name` string, nullable, required: Product name.
    - `amount` integer, required: Price in cents.
    - `description` string, nullable, required: Product description.
    - `image_url` string, nullable, required: Product image URL.
    - `active` 0 | 1, required: 1 = active (purchasable), 0 = deactivated (raw SQLite boolean).
    - `is_live` 0 | 1, required: 1 = live, 0 = sandbox (raw SQLite boolean).
    - `expires_in` integer, required: Checkout QR lifetime in seconds.
    - `created_at` string, required: Creation timestamp (RFC 3339 UTC).
    - `position` integer, nullable, required: Pinned position on the public page (null = not pinned).
    - `kind` 'product' | 'charge', required: 'product' or 'charge'.
    - `due_date` string, nullable, required: First due date (charges; null for products).
    - `recurrence` string, nullable, required: Recurrence (charges; null = one-time and for products).
    - `late_fine_bps` integer, required: One-time late fine in basis points (0 for products).
    - `late_interest_monthly_bps` integer, required: Monthly interest in basis points (0 for products).
    - `total_checkouts` integer, required: Total checkouts created from this product.
    - `completed_checkouts` integer, required: Completed checkouts.
    - `completed_amount` integer, required: Sum of completed amounts in cents.
    - `settled_count` integer, required: Checkouts that EVER reached approved or completed — for charges, the number of settled cycles (the FIFO position). A checkout cancelled AFTER being approved still counts: the position is monotonic by design, so a reversal never rewinds the series onto a competência that is still paid. Re-billing a reversed cycle is the merchant's decision, not the API's.
    - `processing_count` integer, required: Checkouts currently processing (Pix paid, settling).
    - `charge_state` ChargeState: Derived payable state of a charge (kind='charge' product). Settlement is FIFO over the due-date series: the current cycle is selected by the number of cycles that EVER settled (a checkout that reached approved or completed — a later reversal does not rewind the series; re-billing a reversed cycle is the merchant's decision, not the API's) PLUS un-expired pending QRs, since a minted QR reserves the cycle it was priced for and two open QRs must never bill the same competência; the total is base + one-time fine + linear pro-rata interest (base × monthlyBps/10000 × daysLate/30), computed on the América/São_Paulo calendar (the due date itself is not late; lateness starts the next day) and clamped at the R$ 6.000 per-transaction cap.
      - `settled` boolean, required: True when a one-time charge is fully paid (every other field is then absent).
      - `cycle_due_date` string: Due date (YYYY-MM-DD) of the current — oldest unsettled — cycle.
      - `days_late` integer: Days past the due date on the São Paulo calendar (0 = not late).
      - `base_cents` integer: Configured base amount in cents.
      - `fine_cents` integer: One-time late fine in cents (0 when not late).
      - `interest_cents` integer: Accrued pro-rata interest in cents (0 when not late).
      - `total_today_cents` integer: What a QR created now charges: base + fine + interest, capped at 600000.
      - `capped` boolean: True when base + encargos exceeded the per-transaction cap and the total was clamped.
      - `status` 'late' | 'due_today' | 'upcoming': Cycle status.
      - `open_past_due_cycles` integer: Cycles already due and still unpaid (>1 means competências accumulated).
      - `in_flight` boolean: True when a processing checkout exists (Pix paid, settling) — present on list rows only.
    - `payment_url` string: Public payment URL — present on charge rows only (pay.depixapp.com/c/{id}).
  - `limit` integer, required: Applied page size (1–100).
  - `offset` integer, required: Applied offset.

## Other responses

- `401`: Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.
- `403`: The API key lacks the `merchant_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.
- `429`: Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).

---

[API](https://skmtc.dev/depixapp/apis/depix-api.md) · [All operations](https://skmtc.dev/depixapp/apis/depix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/depixapp/apis/depix-api/revisions/04094536dd0f?raw)