Inconsistent handling of updated_at across modifiable entities and their API List/Search endpoints

Feature Requests
, , , , , ,
1

Folks:

We’re starting development of a data integration with Square, and my review of your various APIs reveals a (to me) pretty glaring omission: there is no consistent way to request data that has been modified since a given point in time and retrieve it in a manner that is robust to interruptions.

Not all of the modifiable entities have an updated_at timestamp property (for example, Locations and Gift Cards do not), and for those entities that do have an updated_at property the related List or Search API endpoint may or may not support a “modified since {timestamp}” query criteria.

This is a fairly important feature for a data integration to the Square platform; its omission means that a data integration will be retrieving much more data from your APIs than would otherwise occur. This causes unnecessary load on both your infrastructure and the integration’s infrastructure.

Please note that webhooks are not a universal solution for this - there also needs to be a consistent way to query the API for entities modified since some point in time. For example, to catch up after temporary outages.

Further, the List or Search API endpoints that do support a “modified since {timestamp}” query criteria may or may not allow the results to be ordered by the updated_at property. If the results are ordered by some other property like created_at, then the query, if paginated, is not robust to interruptions. If the paginated query is interrupted it cannot reliably determine that it has processed all of the modifications up to time X and can resume polling for changes at that timestamp later on. Persisting the cursor value beyond the brief period of time needed to save the current page of results and ask for the next page is not a reliable workaround as the delay before resuming after an interruption cannot be predicted. To get reliable results, the entire request would have to be restarted from the initial “modified since” date.

I’d like to submit feature requests for the following:

  1. All modifiable entities should have an updated_at timestamp property.
    An action log associated with an entity does not need this, as actions won’t be modified - created_at is sufficient for them.

  2. All modifiable entities’ List or Search API endpoint should consistently support query filter parameters for filtering on updated_at using the existing updated_at.start_at and updated_at.end_at pattern.

  3. All modifiable entities’ List or Search API endpoint should consistently support query parameters for sorting on updated_at so that the modified entities can be paginated from oldest change to newest change or vice-versa as desired.

  4. All modifiable entities’ List or Search API endpoint should consistently support returning the count of matching objects, as the Customers Search API endpoint does.

An example of this miss is Gift Cards. The Gift Card entity does not have an updated_at property. In order to retrieve only recently-modified gift cards, the gift card activities created since the cutoff timestamp must be queried, the GC IDs extracted from that data, and the GCs then queried by ID.

This would be much simpler and less wasteful of API bandwidth if the Gift Card entity had an updated_at property that was updated by activities that modify the gift card, and the Gift Cards List API endpoint had query and sort parameters supporting updated_at.start_at and updated_at.end_at, and sort.field = UPDATED_AT and sort.order = ASC.

Thank you for your attention in this matter. I am looking forward to your response.

2

We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team. :slight_smile: