Idempotency for Location API Calls

An operation is idempotent when doing it twice has the same effect as doing it once. In integrations this matters because networks fail, users double-click and background jobs retry. Designing for repeatability prevents duplicate rows and confusing orders.

UPCS is naturally repeatable

Coordinates map to a grid cell and the cell maps to a code. Calling generate twice with the same point returns the same upcs_code, with is_existing indicating that the cell's code was already there. Lookup is a read, so repeating it is harmless apart from using your hourly allowance.

The documented API does not include a separate idempotency key header, so the guarantees you rely on are the deterministic code and your own handling.

Where duplicates actually come from

The risky part is usually your side:

• A form submitted twice creates two order_locations rows.
• A retried job inserts the same code twice.
• A webhook from your payment provider fires again.

Make your writes idempotent

Use a unique key and an upsert:

ALTER TABLE order_locations
  ADD CONSTRAINT uq_order_location UNIQUE (order_id);

INSERT INTO order_locations (order_id, upcs_code, latitude, longitude)
VALUES (1001, 'PK-1A2B-3C4D', 31.520400, 74.358700)
ON DUPLICATE KEY UPDATE
  upcs_code = VALUES(upcs_code),
  latitude  = VALUES(latitude),
  longitude = VALUES(longitude);

The syntax above is MySQL; PostgreSQL uses ON CONFLICT (order_id) DO UPDATE. Frameworks offer equivalents such as Laravel's updateOrCreate, used in saving the code with an order.

Retry rules

1. Retry reads and generation freely, within limits: rate limits and backoff.
2. Do not retry 4xx validation or auth errors; fix the cause.
3. Disable the submit button after the first click and make the server tolerant anyway.
4. Use a stable business key (order id) to deduplicate, never a random value generated per attempt.

Test it

Write a test that submits the same order location twice and asserts a single row; see testing a location integration.