List Purchases

Lists one-off plan purchases across customers, live or expired. Filter by customer, entity, plan, or status. Pages may hold fewer than limit rows while has_more is true.

POST /v1/purchases.list

Typescript (SDK)

TypeScript

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.customers.listPurchases({
  customerId: "cus_123",
  statuses: [
    "active",
    "expired",
  ],
});

200

{
  "list": [
    {
      "id": "cus_prod_123",
      "plan_id": "credit_pack",
      "status": "expired",
      "expires_at": null,
      "started_at": 1768817161016,
      "quantity": 1,
      "scope": "customer",
      "customer_id": "cus_123",
      "entity_id": null,
      "created_at": 1768817161016
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Lists one-off plan purchases. By default only live purchases are returned; pass statuses: ["expired"] to see purchases that have ended.

A page can hold fewer than limit rows (even zero) while has_more is true. Keep paginating until has_more is false.

Body Parameters

Response

200

{
  "list": [
    {
      "id": "cus_prod_123",
      "plan_id": "credit_pack",
      "status": "expired",
      "expires_at": null,
      "started_at": 1768817161016,
      "quantity": 1,
      "scope": "customer",
      "customer_id": "cus_123",
      "entity_id": null,
      "created_at": 1768817161016
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-api-version · string · default: 2.4.0 · required

Body

application/json

customer_id · string

Only return rows for this customer. Omit to list across every customer.

entity_id · string

Only return rows for this entity. Requires customer_id.

limit · integer · default: 50

Number of items to return. Default 50, hard ceiling 200.

Required range: 1 <= x <= 200

start_cursor · string · default: ""

Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages.

statuses · enum<string>[]

Statuses to include. Defaults to active and scheduled. past_due matches plans with overdue payments, which read as status active with past_due true.

Minimum array length: 1

Available options: active, scheduled, past_due, expired

plan_id · string

Only return rows for this plan.

Response

200 - application/json

OK

list · object[] · required

Rows on this page.

Show child attributes

has_more · boolean · required

Whether more results exist. A page may hold fewer than limit items (even zero) while has_more is true, so paginate until has_more is false.

next_cursor · string | null · required

Pass as start_cursor to fetch the next page. Null when has_more is false.