Accept header is omitted.
Use the HTTP status to decide whether to correct your request or retry it.
Query parameter nesting
When query parameter names exceed the supported nesting depth, the request returns400 with the message Reduce query parameter nesting to the supported limit. Correct the query before retrying.
This limit applies to parameter names. Square brackets inside a parameter value remain supported.
Validation errors
message summarizes the failure. The errors object identifies each invalid field; messages can differ depending on the request.
A rejected V2 location update does not save a subset of its fields.
Empty hours and incomplete weeks
"hours": {} is valid and leaves hours unchanged. "hours": [] is invalid: hours must be a weekday object.
A nonempty POST or PUT hours object must include all seven days. Use PATCH to update selected days instead:
{"open":"09:00","close":"17:00"}. See opening hours.
Rate limits and retries
The current shared API limit is 1,000 requests per minute. ReadX-RateLimit-Limit and X-RateLimit-Remaining on responses; a 429 also includes Retry-After.
Wait for that interval before retrying, and space subsequent requests out.
Retrying a POST can create another location if the original request succeeded before the connection failed. Check whether the location already exists before retrying a create.
Addresses and coordinates
lat must be between -90 and 90; lng must be between -180 and 180. Zero is valid. The returned address field is address.
POST and PUT can geocode synchronously when either coordinate is missing or zero. Both accept zero during validation but retain this older geocoding behavior.
Changing an address moves the pin. When an update changes address, address_line_1, address_line_2, city, state, postcode or country and sends neither lat nor lng, StoreRocket looks up the new address. The pin moves when the new address is more than 100 meters from the old one. A reworded address in the same place, such as St to Street or a new suite number, keeps the existing pin, including one placed by hand. If the new address cannot be found, or geocoding is temporarily unavailable, the pin and the location’s visibility stay as they were.
An address found only roughly counts as not found. For an address the geocoder cannot find, it often returns something rougher instead of no result: the whole country, the town, the postcode area, the road or a nearby business. When the geocoder marks its answer as a partial match and it is only the country or region, or the address names a street and the answer is only such a rough match, the pin and visibility stay as they were. The new address itself is still saved. A misspelled street that still finds the building moves the pin. Updates to a location that is only a town, such as "city": "Uppsala" with no street, still move the pin to the new town.
- V2 PUT moves the pin during the request. The response contains the new coordinates and a
geocodingobject saying what the lookup found. - V2 PATCH and V1 PUT move the pin shortly after the response, which still shows the previous coordinates.
lat and lng to place the pin yourself; the address is then not looked up. Sending the location’s current coordinates with a new address keeps the pin where it is. To let StoreRocket place the pin from the address, omit lat and lng, or send "lat": null, "lng": null to clear the pin and geocode the address as for a new location. If a cleared pin’s address cannot be found, the coordinates stay null and the location is hidden (visible: false) until it has coordinates.
A PATCH affecting address or coordinate fields also queues geocoding when a coordinate is missing; it preserves supplied zero coordinates. The immediate response can still have null coordinates. Changing a phone or other unrelated field does not trigger geocoding.
The geocoding object
Every V2 create, PUT and PATCH response includesgeocoding next to data. It describes the address lookup made by that request, and is null when the request looked nothing up.
match says what was matched: address, road, place (a business or landmark), postcode, city, region or country. It is null for not_found, unavailable and queued.