List payments

curl --request GET \
  --url https://{host}/primula/api/v3/payments \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/primula/api/v3/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/primula/api/v3/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/primula/api/v3/payments"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{host}/primula/api/v3/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "payment_id": "66666666-6666-4666-8666-666666666666",
    "family_id": "77777777-7777-4777-8777-777777777777",
    "family_name": "Example family",
    "transaction_date": "2026-01-15",
    "amount": 100,
    "total_amount": 100,
    "state": "paid"
  }
]

Payments

List payments

Scoped to company_id; the handler does not restrict this read to the session school assignments. Without group_by, returns sparse payment rows. With group_by and metrics, returns nested PaymentAggregate rows. school_id and school_ids are both applied when provided (their intersection); omitted school filters read the company scope. Row queries support family_id/family_ids; these IDs do not filter the aggregate representation. fields and pagination apply only to rows. Aggregate responses use limit, X-Total-Count and X-Truncated, without Link.

An explicit date range requires both bounds and date_to >= date_from. These date checks occur in the data layer; failures currently produce HTTP 500 rather than 400. last_n_days and explicit bounds can both restrict the result. Item and collection school filters are independent of the session school assignments.

GET

payments

List payments

curl --request GET \
  --url https://{host}/primula/api/v3/payments \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/primula/api/v3/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/primula/api/v3/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/primula/api/v3/payments"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{host}/primula/api/v3/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "payment_id": "66666666-6666-4666-8666-666666666666",
    "family_id": "77777777-7777-4777-8777-777777777777",
    "family_name": "Example family",
    "transaction_date": "2026-01-15",
    "amount": 100,
    "total_amount": 100,
    "state": "paid"
  }
]

Authorizations

Authorization

string

header

required

Access token issued by POST /sessions and associated with a valid server-side session.

Query Parameters

company_id

string<uuid>

required

Company UUID. Must equal the authenticated session company when that session has a company assigned; the equality check is skipped for sessions without one.

school_id

string<uuid>

School UUID. Omit to use the operation's documented company/session scope.

school_ids

string<uuid>[]

Optional school UUID filter. When school_id is also supplied, both filters apply. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

family_id

string<uuid>

Row view only: optional family UUID. When family_ids is also supplied, the reader first restricts to this family; family_ids cannot widen that scope.

family_ids

string<uuid>[]

Optional family UUIDs; row view only. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

family_name

string

Case-insensitive family-name substring filter.

date_from

string<date>

Inclusive start date in YYYY-MM-DD. Optional; both date bounds must be supplied together and date_to must not precede date_from.

date_to

string<date>

Inclusive end date in YYYY-MM-DD. Optional; both date bounds must be supplied together and date_to must not precede date_from.

last_n_days

integer

Rolling lookback on payment created_at (not transaction_date). Positive values add this filter; zero/negative values do not. May be combined with a transaction-date range.

state

string

Case-insensitive payment state filter.

is_posted

boolean

Filter by posted state; omit for both states. Accepts true/1 and false/0, case-insensitive.

successful_only

boolean

default:false

Include payments that are posted or whose normalized state is success, succeeded, completed, paid, posted, processed, settled or state_success. Only true/1 enables the filter; other values disable it.

payment_mode

string

Case-insensitive payment mode filter.

payment_method_sub_kind

string

Case-insensitive payment method subtype filter.

min_amount

number

Inclusive minimum payment amount.

max_amount

number

Inclusive maximum payment amount.

fields

enum<string>[]

Select response properties. Unknown names return 400. Default: payment_id, family_id, family_name, transaction_date, amount, total_amount, state. Row view only. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

Available options:

payment_id,

transaction_id,

school_id,

family_id,

family_name,

transaction_date,

amount,

fee_amount,

total_amount,

balance,

state,

receipt_number,

payment_mode,

payment_method_sub_kind,

description,

is_posted,

payd_online,

auto_billing,

created_at

sort_by

string

Rows: transaction_date, amount, total_amount, created_at or family_name with _asc/_desc (default transaction_date_desc). Aggregates: group or any supported metric with _asc/_desc. Unrecognized sort keys fall back to the backend default. Aggregate default: count_desc.

group_by

enum<string>

Select an aggregate representation; metrics must also be supplied.

Available options:

school_id,

family_id,

month,

state,

payment_mode,

payment_method_sub_kind

metrics

enum<string>[]

Metrics to calculate; required with group_by and invalid without it. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

Available options:

count,

sum_amount,

sum_total_amount,

sum_fee_amount,

avg_amount,

avg_total_amount,

avg_fee_amount

limit

integer

default:50

Aggregate result limit. Defaults to 50 and clamps values above 200 to 200. Zero and negative values use the default.

page

integer

default:1

One-based page number. Row view only.

Required range: x >= 1

per_page

integer

default:100

Items per page; values greater than 200 are clamped to 200. Row view only.

Required range: x >= 1

Response

Successful response.

Option 1 · object[]
Option 2 · object[]

A sparse row containing only the selected fields. Default fields: payment_id, family_id, family_name, transaction_date, amount, total_amount, state.

payment_id

string

Payment id.

transaction_id

string

Transaction id.

school_id

string

School id.

family_id

string

Family id.

family_name

string

transaction_date

string<date>

amount

number

fee_amount

number | null

total_amount

number

balance

number

state

string

receipt_number

string

payment_mode

string

payment_method_sub_kind

string

description

string

is_posted

boolean

payd_online

boolean

auto_billing

boolean

created_at

string

Local timestamp in YYYY-MM-DD HH:mm:ss format; no timezone suffix.

Example:

"2026-01-15 09:30:00"

Overview

Sessions

Schools

Companies

Rooms

Users

Leads

Students

Payments

Enrollments

Family balances

Pre registration fallout

Absences

Waitlist

Billing plans

Spaces

Enrollment tracker

Efficiency ratios

Procare messages

Attendances

Billing attendance audits

Classroom attendance

Activities summary

Activity details

Data refresh

Sibling discounts

New start tracker

Withdrawal tracker

Transition tracker

Gusto companies

Gusto employees

Gusto contractors

Gusto payrolls

Procare staff

List payments

Authorizations

Query Parameters

Response