Choosing the Right Pagination Strategy Across FMTC APIs

Understanding Page-Based and Cursor-Based Pagination for Faster, More Reliable Integrations

As your FMTC integration grows, so does the amount of data you’ll need to retrieve. Whether you’re syncing deals, products, merchants, or advertiser programs, efficiently handling large datasets is essential for maintaining fast, reliable applications.

FMTC uses pagination to break large datasets into manageable batches, but not every endpoint uses the same pagination strategy. Understanding why different endpoints use different approaches will help you build more scalable and reliable integrations. 

In this guide, you’ll learn:

• What API pagination is
• Why different FMTC endpoints use different pagination methods
• When to use page-based pagination versus cursor-based pagination
• Best practices for reliable API integrations

---

What Is API Pagination?

Pagination is a common REST API technique for splitting large datasets into smaller groups of records called pages.

Instead of downloading thousands of records in one request, your application retrieves a portion of the dataset, processes it, and then requests the next batch.

This approach provides several advantages:

• Faster response times
• Lower memory usage
• Reduced timeout risk
• Easier recovery if a request fails
• More reliable synchronization of large datasets

For APIs returning large volumes of information, pagination is considered a best practice.

---

Not Every FMTC API Uses the Same Pagination Strategy

Different types of data require different approaches.

A merchant directory behaves very differently from a product catalog that may contain millions of products and changes continuously. 

FMTC uses two pagination models depending on the endpoint.

Endpoint	Pagination Type	Best Used For
Deal Feed API	Page-based	Large collections of deals
Merchant Feed API	Page-based	Merchant metadata
Advertiser Programs API	Page-based	Affiliate program directory
Product Feed API	Cursor-based	Very large product catalogs

---

Page-Based Pagination

Page-based pagination is the most common pagination model used by REST APIs. Your application requests a specific page along with the number of records you’d like returned. 

Your application requests a page number along with the number of records you’d like returned.

Example:

https://s3.fmtc.co/api/4/deals?api_token={api_key}&page=1&page_size=100

To retrieve the next batch:

https://s3.fmtc.co/api/4/deals?api_token={api_key}&page=2&page_size=100

Each response also includes helpful pagination links:

• first
• prev
• next
• last

Rather than calculating page numbers yourself, your application can simply follow the next link until no additional pages remain.

This approach works well for datasets that are relatively stable while being retrieved.

---

Cursor-Based Pagination

The Product Feed API works differently.

Instead of requesting page numbers, each response returns a cursor that points to the next group of products.

Your application simply continues requesting the next cursor until there are no more results.

Instead of this:

https://s3.fmtc.co/api/2.0.0/products?api_token={api_key}&page=2

You’ll use:

https://s3.fmtc.co/api/2.0.0/products?api_token={api_key}&format=json&latest=0&cursor=eyJpZCI6MTcsIl9wb2ludHNUb25leHRJdGVtcyI6dHJ1ZX0

Each response includes a cursor pointing to the next group of products. Your integration simply follows each cursor until no additional cursor is returned. 

---

Why Doesn’t the Product Feed Use Page Numbers?

Product catalogs can be enormous.

Some merchants have:

• 5,000 products
• 50,000 products
• 500,000 products
• Millions of products

Unlike deals, products are constantly being added, removed, or updated.

If traditional page numbers were used, products could shift between pages while your application was downloading them. That can lead to duplicate products or skipped records.

Cursor-based pagination solves this problem by continuing exactly where the previous request ended instead of relying on page numbers.

Benefits include:

• More consistent synchronization
• Faster database queries
• Better performance for very large catalogs
• Reduced risk of duplicate or missing products
• Better scalability as merchant catalogs grow

---

Recommended Synchronization Strategy 

The following recommendations outline the preferred synchronization approach for initial imports and ongoing data updates using the FMTC APIs. For implementation details and additional best practices, see our API documentation.

A common mistake is performing a complete download every time your application runs. After your initial import, incremental update parameters are usually much faster and significantly reduce the amount of data transferred.

---

Deal Feed Pagination

The Deal Feed API uses page-based pagination.

By default, each request returns 100 deals, although you can request larger batches by specifying a larger page_size.

Example:

https://s3.fmtc.co/api/4.2.0/deals?api_token={api_key}&page=1&page_size=1000

Continue following the next link until all available pages have been processed.

For recurring synchronizations, however, pagination is often unnecessary.

Instead, use incremental updates with the sincedate parameter to retrieve only deals that have changed since your previous synchronization.

This dramatically reduces processing time and API usage.

---

Merchant Feed & Advertiser Programs

The Merchant Feed API and Advertiser Programs API follow the same page-based model as the Deal Feed.

Both support:

• page
• page_size
• first
• prev
• next
• last

Because the Merchant Feed defaults vary depending on subscription status, we recommend always specifying page_size explicitly so your application receives predictable batch sizes.

---

Product Feed Synchronization

The Product Feed is designed differently because product catalogs change continuously.

A typical synchronization looks like this:

Initial Import

1. Request the first batch of products.
2. Process the returned products.
3. Follow the next cursor.
4. Repeat until no additional cursor exists.

Daily Synchronization

After the initial import, you generally don’t need to retrieve the entire catalog again.

Instead, request only recently verified products using parameters such as:

latest=1

or

latest_days=7

This returns only products that have recently changed, making synchronization dramatically faster than downloading every product again.

---

Visualizing the Difference

Deal Feed

Page 1

   ↓

Process Deals

   ↓

Page 2

   ↓

Process Deals

   ↓

Page 3

   ↓

Complete

Product Feed

Request Products

      ↓

Receive Next Cursor

      ↓

Request Next Cursor

      ↓

Receive Next Cursor

      ↓

Repeat Until Next = Null

Although the workflows look different, both accomplish the same goal: efficiently retrieving large datasets while keeping requests manageable.

---

Pagination Best Practices

Whether you’re using page numbers or cursors, a few best practices will make your integration more reliable.

Always specify your batch size

Explicitly setting page_size provides predictable responses regardless of endpoint defaults.

Follow the links provided

Rather than calculating pages yourself, follow the next link (or cursor) returned by the API.

Use incremental updates whenever possible

Follow our API documentation for best practices for full vs incremental calls.

Build retry logic

Network interruptions happen. Design your integration so failed requests can be safely retried without creating duplicate or missing records.

---

Sample Deal Feed Response

{

  “data”: [

    {

      “id”: 48401446,

      “merchant_name”: “Alibris”,

      “status”: “active”

    }

  ],

  “links”: {

    “prev”: null,

    “next”: “https://s3.fmtc.co/api/4.2.0/deals?page=2&page_size=100”

  },

  “meta”: {

    “current_page”: 1,

    “last_page”: 471,

    “per_page”: 100,

    “total”: 47064

  }

}

Notice that your application doesn’t need to calculate how many pages remain—it can simply continue following the next link until no additional pages are returned.

---

Which FMTC Endpoints Don’t Require Pagination?

Several FMTC endpoints return their complete dataset in a single response and therefore don’t require pagination.

These include:

• Networks
• Categories
• Deal Types
• Deal Changes
• Logos

Always refer to the endpoint documentation to determine whether pagination or incremental update parameters are supported.

---

Choosing the Right Strategy 

Pagination is more than a way to split large datasets—it’s a key part of building fast, reliable API integrations. 

Understanding when to use page-based pagination, when to use cursor-based pagination, and when to use incremental updates can significantly improve synchronization speed while reducing API requests and processing time.

Refer to our API documenation for the most up-to-date strategy for your feed.

For additional implementation examples, explore our Tech Corner articles covering incremental Deal Feed updates, Product Feed synchronization strategies, and other FMTC API best practices.