---
title: "List purchases for provider"
method: GET
path: "/v1/sdk/purchases"
tags: ["Purchases"]
---

# List purchases for provider

`GET /v1/sdk/purchases`

Retrieves all purchases for the authenticated provider with optional filtering by status, product, or customer.

## Query parameters

- `status` 'pending' | 'active' | 'trialing' | 'past_due' | 'cancelled' | 'expired' | 'suspended' | 'refunded'
- `productRef` string
- `customerRef` string
- `includeFree` boolean

## Response `200`

Purchases retrieved successfully

- object
  - `purchases` SdkPurchaseResponse[]
    - `amount` number, required — Amount in USD cents (normalised for aggregation)
    - `autoRenew` boolean — Auto-renew enabled
    - `billingCycle` 'weekly' | 'monthly' | 'quarterly' | 'yearly' — Billing cycle
    - `cancellationReason` string — Cancellation reason
    - `cancelledAt` string — Cancelled at
    - `createdAt` string, required — Created at
    - `currency` string, required — Original payment currency code
    - `customerEmail` string, required — Customer email
    - `customerRef` string, required — Customer reference
    - `endDate` string — End date
    - `exchangeRate` number — Exchange rate from original currency to USD
    - `isRecurring` boolean, required — Is recurring
    - `metadata` object — Arbitrary metadata attached to the purchase
    - `nextBillingDate` string — Next billing date
    - `originalAmount` number — Original amount in the payment currency (cents/pence)
    - `paidAt` string — Paid at timestamp
    - `planSnapshot` SdkPlanSnapshotDto
      - `billingCycle` string, nullable — Billing cycle
      - `creditsPerUnit` number — Credits per usage unit (integer, >= 1)
      - `currency` string, required — Currency code
      - `features` object, nullable — Plan features
      - `freeUnits` number — Number of free units included
      - `limit` number — Usage limit for the meter
      - `limits` object, nullable — Usage limits
      - `meterRef` string — Meter reference
      - `name` string — Plan name captured at purchase time
      - `planType` string, required — Plan type
      - `price` number, required — Plan price in cents
      - `reference` string — Plan reference
    - `productName` string — Product name
    - `productRef` string, required — Product reference
    - `reference` string, required — Purchase reference
    - `startDate` string, required — Start date
    - `status` string, required — Purchase status
    - `usage` UsageBillingDto
      - `overageCost` number, required — Overage cost in cents
      - `overageUnits` number, required — Units exceeding the plan limit
      - `periodEnd` string — Period end date
      - `periodStart` string — Period start date
      - `used` number, required — Units consumed in current period

---

[API](https://skmtc.net/solvapay/apis/solvapay-rest-api.md) · [All operations](https://skmtc.net/solvapay/apis/solvapay-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/solvapay/solvapay-rest-api/versions/bbc2ff2bc849/schema)