Skip to main content
POST
/
v1
/
contracts
/
seatBalances
/
list
List seat balances
curl --request POST \
  --url https://api.metronome.com/v1/contracts/seatBalances/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
  "subscription_ids": [
    "8deed800-1b7a-495d-a207-6c52bac54dc9"
  ],
  "include_credits_and_commits": true,
  "include_ledgers": true,
  "covering_date": "2024-03-01T00:00:00.000Z",
  "limit": 25
}'
{
  "data": [
    {
      "seat_id": "seat_1",
      "balance": 50000,
      "commits": [
        {
          "id": "62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35",
          "balance": 30000,
          "start_date": "2024-01-01T00:00:00.000Z",
          "end_date": "2024-02-01T00:00:00.000Z",
          "ledger_entries": [
            {
              "type": "PREPAID_COMMIT_SEGMENT_START",
              "amount": 50000,
              "timestamp": "2024-01-01T00:00:00.000Z"
            },
            {
              "type": "PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION",
              "amount": -20000,
              "timestamp": "2024-01-31T00:00:00.000Z"
            }
          ]
        }
      ],
      "credits": [
        {
          "id": "fa411f5b-fb85-4755-9d4d-530717be083c",
          "balance": 20000,
          "start_date": "2024-01-01T00:00:00.000Z",
          "end_date": "2024-02-01T00:00:00.000Z",
          "ledger_entries": [
            {
              "type": "CREDIT_SEGMENT_START",
              "amount": 25000,
              "timestamp": "2024-01-01T00:00:00.000Z"
            },
            {
              "type": "CREDIT_AUTOMATED_INVOICE_DEDUCTION",
              "amount": -5000,
              "timestamp": "2024-01-31T00:00:00.000Z"
            }
          ]
        }
      ]
    },
    {
      "seat_id": "seat_2",
      "balance": 45000,
      "commits": [
        {
          "id": "62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35",
          "balance": 45000,
          "start_date": "2024-01-01T00:00:00.000Z",
          "end_date": "2024-02-01T00:00:00.000Z",
          "ledger_entries": [
            {
              "type": "PREPAID_COMMIT_SEGMENT_START",
              "amount": 45000,
              "timestamp": "2024-01-01T00:00:00.000Z"
            }
          ]
        }
      ],
      "credits": []
    }
  ],
  "pagination": {
    "next_page": "eyJsYXN0X3NlYXRfaWQiai",
    "seats_included": 2,
    "seats_available_for_next_page": 8
  }
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json

List seat-level balances for commits and credits.

​
customer_id
string<uuid>
required

The customer ID to retrieve seat balances for

​
contract_id
string<uuid>
required

The contract ID to retrieve seat balances for

​
subscription_ids
string<uuid>[]

Optional filter to only include seats from specific subscriptions. If subscriptions ids are not mapped to SEAT_BASED subscriptions, error will be returned.

​
seat_ids
string<uuid>[]

Optional filter to only include specific seats

​
include_credits_and_commits
boolean
default:false

Include credits and commits in the response

​
include_ledgers
boolean
default:false

Include ledger entries for each commit and commit. include_credits_and_commits must be set to true for include_ledgers=true to apply.

​
starting_at
string<date-time>

Include only commits or credits with access effective on or after this date (cannot be used with covering_date).

​
effective_before
string<date-time>

Include only commits or credits with access effective on or before this date (cannot be used with covering_date).

​
covering_date
string<date-time>

Include only commits or credits with access that cover this specific date (cannot be used with starting_at or ending_before).

​
limit
integer

Maximum number of seats to return. Range: 1-100. Default: 25. When include_credits_and_commits = true, if the total commits/credits across all seats exceeds 100, a limit of 100 applies to the total credits and commits. Seats are included greedily to maximize the number of seats returned. Example: if seat 1 has 98 commits and seat 2 has 10 commits, both seats will be returned (total: 108 commits). Each returned seat includes all of its associated credits and commits.

​
cursor
string

Page token from a previous response to retrieve the next page

Response

Success

​
data
object[]
required
​
pagination
object
required
⌘I