Hi,
I am trying to understand and I will appreciate your help.
Using sdk php Version 42.1.0.20250416 and API version 2025-04-16
Say a large set of payments exists.
From the API explorer, if you request a list with a cursor, the responds is a list of payments and a cursor to get the next page.
{
payments : { … },
cursor : “SDfsdlkjflsdkjf”
}
From the api, requesting a list of payments,
$payments = $square->payments->list(
new ListPaymentsRequest([
“limit”=> 50
]),
);
it returns
Square\Core\Pagination\CursorPager {#3533 ▼ // app/Classes/SquareClass.php:594
-request:
Square\Payments\Requests
ListPaymentsRequest
{#3538 
}
-getNextPage: Closure(ListPaymentsRequest $request) {#3534 }
-setCursor: Closure(ListPaymentsRequest $request, ?string $cursor) {#3535 }
-getNextCursor: Closure(ListPaymentsResponse $response) {#3536 }
-getItems: Closure(ListPaymentsResponse $response) {#3537 }
}
getNextCursor() is private so not accessible. So how to the get the next page using the cursor
And using the page iterator is getting the call too slow on large set of data
foreach ($payments->getPages() as $page) {
foreach($payment as $page->getItems()) {
echo sprintf(
“customer: ID: %s Version: %s, Given name: %s, Family name: %s\n”,
$payment->getId(),
$payment->getVersion(),
$payment->getGivenName(),
$payment->getFamilyName()
);
}
}
Many thanks.
I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:
Additional Documentation
Take Payments
Payments API
Take Payments
If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.
Documentation has not helped me figure out this issue.
The Square paginated endpoints now support auto-pagination with an iterator. Callers don’t need to manually fetch the next page. You can now iterate over the entire list and the client automatically fetches the next page behind the scenes. 
Ok, than say I want to display 100 customers of 99 000 000 customers. If I call $customers->getPages(), it would download all pages but not yet fetch customers on each page right?
That way, I can know the total number of page by doing : right?
$totalpages = 0;
foreach ($customers->getPages() as $page){
$totalpages++;
}
If I need the second page, I would loop the pages and access the getItems only if the key is 2 right?
$customer_list_of_page_2 = [];
foreach ($customers->getPages() as $key => $page) {
if ($key == 2){
$customer_list_of_page_2 = $page->getItems();
break;
}
}
So in this case, I would need to loop 2 pages before getting the required set.
If I want to get page 1399, I need to loop and download the first 1398 pages before I get to page 1399?
I list the last page of 69, 100 lines each page. It takes 30 seconds to load the last batch. It was instantaneous with older api where I was using getPaymentApi.
What Am I doing wrong?
Thanks
Your understanding about getPages() is partially correct, but there are some important nuances:
getPages() doesn’t download all pages immediately- Pages are fetched lazily (on-demand) as you iterate
- However, you’re correct that accessing page 1399 would require iterating through previous pages
Let me show you how to effectively use getPages() to get paginated results with specific limits and continue through the results later.
Getting First 100 Results (10 per page)
// Initialize the request with a limit of 10 per page
$request = new \Square\Customers\Requests\ListCustomersRequest([
'limit' => 10 // Set page size to 10
]);
// Get the paginated result
$customerPages = $client->customers->list($request);
// Initialize counters
$totalCustomers = 0;
$currentPage = 0;
$lastCursor = null;
// Iterate through pages until we have 100 customers or run out of results
foreach ($customerPages->getPages() as $page) {
$currentPage++;
// Get customers from this page
$customers = $page->getItems();
// Process customers in this page
foreach ($customers as $customer) {
$totalCustomers++;
// Process your customer data here
echo sprintf(
"Customer %d: ID: %s, Name: %s\n",
$totalCustomers,
$customer->getId(),
$customer->getGivenName()
);
// Store the cursor for the last processed page
$lastCursor = $page->getCursor();
// Break if we've reached 100 customers
if ($totalCustomers >= 100) {
break 2; // Break both loops
}
}
}
// Store the last cursor for later use
// You might want to save this to a database or file
$savedCursor = $lastCursor;
Continuing Pagination Later
// When you want to continue from where you left off
function continueCustomerPagination($client, $savedCursor, $limit = 10) {
$request = new \Square\Customers\Requests\ListCustomersRequest([
'cursor' => $savedCursor,
'limit' => $limit
]);
$customerPages = $client->customers->list($request);
$totalProcessed = 0;
$currentPage = 0;
$newCursor = null;
foreach ($customerPages->getPages() as $page) {
$currentPage++;
$customers = $page->getItems();
foreach ($customers as $customer) {
$totalProcessed++;
// Process your customer data here
echo sprintf(
"Continuing - Customer %d: ID: %s, Name: %s\n",
$totalProcessed,
$customer->getId(),
$customer->getGivenName()
);
// Store the cursor for the next continuation
$newCursor = $page->getCursor();
// Optional: Break after processing another batch
if ($totalProcessed >= 100) {
break 2;
}
}
}
return $newCursor; // Return the cursor for next continuation
}
// Usage example
try {
// Continue from where we left off
$nextCursor = continueCustomerPagination($client, $savedCursor);
// Save the new cursor for next time
$savedCursor = $nextCursor;
} catch (Exception $e) {
echo "Error continuing pagination: " . $e->getMessage();
}
Complete Example with Error Handling and State Management
class PaginationManager {
private $client;
private $pageSize;
private $savedCursor;
public function __construct($client, $pageSize = 10) {
$this->client = $client;
$this->pageSize = $pageSize;
$this->savedCursor = null;
}
public function getInitialBatch($batchSize = 100) {
$request = new \Square\Customers\Requests\ListCustomersRequest([
'limit' => $this->pageSize
]);
$customerPages = $this->client->customers->list($request);
$processed = 0;
try {
foreach ($customerPages->getPages() as $page) {
foreach ($page->getItems() as $customer) {
$processed++;
// Process customer
yield $customer;
// Save cursor after each customer
$this->savedCursor = $page->getCursor();
if ($processed >= $batchSize) {
return;
}
}
}
} catch (Exception $e) {
throw new Exception("Error processing initial batch: " . $e->getMessage());
}
}
public function continuePagination($batchSize = 100) {
if (!$this->savedCursor) {
throw new Exception("No saved cursor found to continue pagination");
}
$request = new \Square\Customers\Requests\ListCustomersRequest([
'cursor' => $this->savedCursor,
'limit' => $this->pageSize
]);
$customerPages = $this->client->customers->list($request);
$processed = 0;
try {
foreach ($customerPages->getPages() as $page) {
foreach ($page->getItems() as $customer) {
$processed++;
// Process customer
yield $customer;
// Save cursor after each customer
$this->savedCursor = $page->getCursor();
if ($processed >= $batchSize) {
return;
}
}
}
} catch (Exception $e) {
throw new Exception("Error continuing pagination: " . $e->getMessage());
}
}
public function getSavedCursor() {
return $this->savedCursor;
}
}
// Usage Example
try {
// Initialize pagination manager
$paginationManager = new PaginationManager($client);
// Get first 100 results
echo "Processing initial batch:\n";
foreach ($paginationManager->getInitialBatch(100) as $customer) {
echo sprintf("Customer ID: %s\n", $customer->getId());
}
// Save cursor for later
$savedCursor = $paginationManager->getSavedCursor();
// Later... continue pagination
echo "\nContinuing pagination:\n";
foreach ($paginationManager->continuePagination(100) as $customer) {
echo sprintf("Customer ID: %s\n", $customer->getId());
}
} catch (Exception $e) {
echo "Error: " . $e->getMessage();
}
1 Like
Thanks
Using square/square-php-sdk Version 42.1.0.20250416
When I fetch the cursor, like so, I get this exception : Call to undefined method Square\Core\Pagination\Page::getCursor()
$payments = $client->payments->list(
new ListPaymentsRequest([
"limit" => 10,
]),
);
foreach ($payments->getPages() as $page) {
$items = $page->getItems();
$Nextcursor = $page->getCursor();
}
Thanks for your help
Confirmed by Square Support, Square\Core\Pagination\Page::getCursor() is not supported on square/square-php-sdk Version 42.1.0.20250416. It is quite unfortunate the online documents is not reflecting this.