Pagination

Presscart’s list endpoints use a uniform envelope. pypresscart models it as Paginated[T].

The envelope

from pypresscart import Paginated, OutletListing

page: Paginated[OutletListing] = client.outlets.list(limit=25, page=1)

page.records         # list[OutletListing]
page.total_records   # int  — total across all pages
page.total_pages     # int
page.current_page    # int  — 1-indexed
page.next_page       # int | None — None on the last page
page.previous_page   # int | None — None on the first page

Common query parameters

Every paginated endpoint in pypresscart accepts at least:

Param	Default	Notes
limit	25	Items per page
page	1	1-indexed page number
sort_by	varies	Field name (see endpoint docs)
order_by	"desc"	"asc" or "desc"

Many endpoints also accept a filters= dict — see Outlets for a filter-rich example.

Iterating all pages

There’s no built-in paginator today. Page manually:

def all_records(endpoint_callable, **kwargs):
    page = 1
    while True:
        result = endpoint_callable(page=page, **kwargs)
        yield from result.records
        if result.next_page is None:
            return
        page = result.next_page

for outlet in all_records(client.outlets.list, limit=100, filters={"country": "United States"}):
    print(outlet.outlet_name)

Paginated vs bare-array endpoints

A few endpoints return a naked JSON array instead of the paginated envelope. pypresscart returns list[Model] for those, not Paginated[Model]:

Endpoint	Return type
GET /profiles/{id}/order-items	list[ProfileOrderItem]
GET /products/categories	list[ProductCategoryCount]
GET /outlets/locations/countries	CountriesResponse (wrapped {"countries": [...]})
GET /outlets/locations/states	StatesResponse
GET /outlets/locations/cities	CitiesResponse

Check each resource page for the exact return type.

JSON mode

With as_json=True (or response_mode="json"), Paginated[T] collapses to the raw envelope dict:

raw = client.outlets.list(as_json=True)
raw["records"]        # list of dicts
raw["next_page"]      # int | None

See Dual-Mode I/O.

Tips

• Start with limit=100 rather than the default of 25 if you’re reading a lot.

• Use total_pages to plan work before iterating (e.g., for a progress bar).

• Server may cap limit — check the returned records length rather than trusting your requested limit.

• Stable ordering matters. If you’re crawling pages over time, sort by a monotonic field (e.g. created_at) to avoid skips or duplicates when rows change under you.