List Entities

Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.entities.list({
  limit: 10,
});

curl --request POST \
  --url https://api.useautumn.com/v1/entities.list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "start_cursor": "",
  "limit": 10
}
'

{
  "list": [
    {
      "id": "seat_42",
      "name": "Seat 42",
      "customer_id": "cus_123",
      "feature_id": "seats",
      "created_at": 1771409161016,
      "env": "sandbox",
      "subscriptions": [
        {
          "plan_id": "pro_plan",
          "auto_enable": true,
          "add_on": false,
          "status": "active",
          "past_due": false,
          "canceled_at": null,
          "expires_at": null,
          "trial_ends_at": null,
          "started_at": 1771431921437,
          "current_period_start": 1771431921437,
          "current_period_end": 1771999921437,
          "quantity": 1
        }
      ],
      "purchases": [],
      "balances": {
        "messages": {
          "feature_id": "messages",
          "granted": 100,
          "remaining": 72,
          "usage": 28,
          "unlimited": false,
          "overage_allowed": false,
          "max_purchase": null,
          "next_reset_at": 1773851121437,
          "breakdown": [
            {
              "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
              "plan_id": "pro_plan",
              "included_grant": 100,
              "prepaid_grant": 0,
              "remaining": 72,
              "usage": 28,
              "unlimited": false,
              "reset": {
                "interval": "month",
                "resets_at": 1773851121437
              },
              "price": null,
              "expires_at": null
            }
          ]
        }
      },
      "invoices": []
    }
  ],
  "next_cursor": null
}

POST

entities.list

Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.entities.list({
  limit: 10,
});

curl --request POST \
  --url https://api.useautumn.com/v1/entities.list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "start_cursor": "",
  "limit": 10
}
'

{
  "list": [
    {
      "id": "seat_42",
      "name": "Seat 42",
      "customer_id": "cus_123",
      "feature_id": "seats",
      "created_at": 1771409161016,
      "env": "sandbox",
      "subscriptions": [
        {
          "plan_id": "pro_plan",
          "auto_enable": true,
          "add_on": false,
          "status": "active",
          "past_due": false,
          "canceled_at": null,
          "expires_at": null,
          "trial_ends_at": null,
          "started_at": 1771431921437,
          "current_period_start": 1771431921437,
          "current_period_end": 1771999921437,
          "quantity": 1
        }
      ],
      "purchases": [],
      "balances": {
        "messages": {
          "feature_id": "messages",
          "granted": 100,
          "remaining": 72,
          "usage": 28,
          "unlimited": false,
          "overage_allowed": false,
          "max_purchase": null,
          "next_reset_at": 1773851121437,
          "breakdown": [
            {
              "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
              "plan_id": "pro_plan",
              "included_grant": 100,
              "prepaid_grant": 0,
              "remaining": 72,
              "usage": 28,
              "unlimited": false,
              "reset": {
                "interval": "month",
                "resets_at": 1773851121437
              },
              "price": null,
              "expires_at": null
            }
          ]
        }
      },
      "invoices": []
    }
  ],
  "next_cursor": null
}

Body Parameters

Response

{
  "list": [
    {
      "id": "seat_42",
      "name": "Seat 42",
      "customer_id": "cus_123",
      "feature_id": "seats",
      "created_at": 1771409161016,
      "env": "sandbox",
      "subscriptions": [
        {
          "plan_id": "pro_plan",
          "auto_enable": true,
          "add_on": false,
          "status": "active",
          "past_due": false,
          "canceled_at": null,
          "expires_at": null,
          "trial_ends_at": null,
          "started_at": 1771431921437,
          "current_period_start": 1771431921437,
          "current_period_end": 1771999921437,
          "quantity": 1
        }
      ],
      "purchases": [],
      "balances": {
        "messages": {
          "feature_id": "messages",
          "granted": 100,
          "remaining": 72,
          "usage": 28,
          "unlimited": false,
          "overage_allowed": false,
          "max_purchase": null,
          "next_reset_at": 1773851121437,
          "breakdown": [
            {
              "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
              "plan_id": "pro_plan",
              "included_grant": 100,
              "prepaid_grant": 0,
              "remaining": 72,
              "usage": 28,
              "unlimited": false,
              "reset": {
                "interval": "month",
                "resets_at": 1773851121437
              },
              "price": null,
              "expires_at": null
            }
          ]
        }
      },
      "invoices": []
    }
  ],
  "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.3.0

required

Body

application/json

start_cursor

string

default:""

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

limit

integer

default:50

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

Required range: 1 <= x <= 5000

plans

object[]

Filter by plan ID and version. Returns entities with active subscriptions to this plan, including plans inherited from the parent customer.

Show child attributes

subscription_status

enum<string>

Filter customer products used for entity hydration and plan matching. Defaults to active and scheduled.

Available options:

active,

scheduled

string

Search entities by id or name.

processors

enum<string>[]

Filter by parent customer processor type (stripe, revenuecat, vercel).

Available options:

stripe,

revenuecat,

vercel

customer_id

string

Restrict the response to entities owned by this customer id. Use to bulk-fetch all entities for one customer in a single paginated call instead of iterating entities.get.

Minimum string length: 1

Response

200 - application/json

list

object[]

required

Items for current page.

Show child attributes

next_cursor

string | null

required

Opaque cursor for the next page. Null when there are no more results.

⌘I

Billing

Balances

Customers

Authorization

Events

Entities

Plans

Features

Rewards & Referrals

Webhook Events

Platform (Beta)

Body Parameters

Response

Authorizations

Headers

Body

Response

​Body Parameters

​Response

Authorizations

Headers

Body

Response

Body Parameters

Response