Skip to main content
Most integrations do not need the whole data set on every run. They need the records that changed since the last run, to reconcile what their webhooks did not deliver. The sort parameter gives you that.

​
The sort parameter

sort selects one column, and that column does two jobs: from and to filter it, and the result comes back ordered by it. A request that does not send sort uses created_at.
Two endpoints accept sort: Clients and Sales Associates. Their records change after they are created.The other endpoints answer 422 when a request sends sort. Their records do not change after they are created, so their updated_at repeats their created_at.

​
The recipe

1

Keep a watermark

Store the highest updated_at that you processed. On your first run, use a time far enough in the past to cover the period that you need.
2

Ask for the changes

Send sort=updated_at and from=<your watermark>.
Subtract a few minutes from your watermark. A record is stamped when the database writes it, and becomes visible when the transaction commits. A slow transaction can therefore become visible after you read past its time, and the overlap collects it.
3

Read the next page with from, not with page

Take the updated_at of the last record that you received, send it as the from of your next call, and ask for page=1 again.
Repeat until a call returns fewer records than your per_page.
4

Save each record with an upsert

Upsert on bspk_id. Never insert without a check.The same record can arrive more than once. The from bound includes the given time, so every call after the first returns the record that you used as the cursor, and a record that changes again during your pull is returned again.
5

Move the watermark last

Move your watermark to the highest updated_at that you received, and only after the whole pull succeeds. If a call fails, run the pull again from the old watermark.

​
Paginating a delta safely

Do not use page=2, page=3 and so on with sort=updated_at. Ask for page=1 every time, and move from forward instead.
Adding a to bound does not make page safe for a delta.
The default sort=created_at is not affected. A creation time never changes, so page=2, page=3 and so on are stable. Use page for a full export, and from for a delta.

​
Sizing the job

x-total-count tells you how many records match your filter. When the first call reports a count at or below your per_page, that one call is the whole delta. per_page accepts up to 1000.

​
What moves updated_at

On a client, updated_at moves for more reasons than an edit to the profile. An appointment, an email, a call, a wishlist, a store visit, a special order and a rating all touch the record. Your delta therefore includes clients whose own fields did not change.