API Integration Checklist for Businesses

Integrations fail in the gaps: nobody named a data owner, the sandbox token expired, pagination was “we’ll fetch page 1,” and webhooks were accepted without a signature check. This checklist is what Palmate Solutions walks through before and during API integration work. Use it to brief a vendor, audit an existing zap, or prepare for a build.

For why this work is worth doing, see how API integration can automate business operations. For the failure modes this list is designed to prevent, see common mistakes when integrating third-party APIs.

To bound scope before a workshop, run the API project estimator. It will not replace this checklist. It will stop you from estimating “the Shopify API” as if it were one flow.

1. Business ownership

• Each flow has a named operator (warehouse, finance, sales) who can answer mapping questions in a working day.
• You have written which system is the authority for each field (on-hand stock, customer email, invoice status). Dual writers are how loops start.
• Success is defined as behaviour (“oversell rate,” “time to tracking number”), not “API connected.”
• There is a pause switch: who can disable outbound updates during a vendor outage.

If ownership is “IT will figure it out,” stop. Mappings are product decisions.

2. Inventory of systems and flows

• List systems, environments (sandbox/production), and whether each is source, destination, or both.
• List objects: orders, SKUs, packs, customers, payments, shipments, refunds.
• For each object, list events: created, updated, cancelled, partially fulfilled.
• Note volume and peaks (festival, month-end, marketplace sale windows).
• Note legal and tax fields that must survive the hop (GSTIN, HSN, place of supply) rather than disappearing into a notes field.

The estimator is built around counting these. A spreadsheet of flows is a better RFP than a paragraph.

3. Contracts and samples

• Official docs, OpenAPI if it exists, and real sandbox payloads — not a blog screenshot.
• Sample JSON saved in version control. Validate and pretty-print with the JSON formatter so “almost JSON” does not waste a day.
• Field dictionary: your name, their name, type, nullability, enums.
• Pack and unit mapping (1 box = 6 units) written down before code.
• Error bodies: what a 4xx looks like, and whether 200 can still mean “accepted but not applied.”

If the vendor cannot provide a sandbox, treat production-first as a risk item, not a flex.

4. Authentication and secrets

• Auth type: API key, OAuth2 (auth code vs client credentials), mutual TLS, signed requests.
• Token lifetime, refresh path, and clock skew tolerance.
• Where secrets live (not git, not a shared chat). Rotation procedure.
• JWT-shaped tokens inspected with the JWT decoder so claims, expiry, and audience are visible — decode in the browser, do not paste production secrets into random websites.
• Least privilege: a key that can only write what the flow needs.

OAuth “we logged in once in Postman” is not a production design. Apps need refresh; cron jobs need a client-credentials path or a securely stored refresh token with alerting on failure.

5. Webhooks and inbound events

• Signature verification (HMAC or vendor-specific) with a secret that can be rotated.
• Idempotency keys or event IDs stored so retries do not double-decrement stock or double-email.
• Fast acknowledgement; slow work in a queue.
• Out-of-order and delayed events: do you apply last-write-wins, or version vectors, or “ignore if older than local”?
• Replay tool for operators after a mapping fix.

Unsigned webhooks are an open write API on your public URL.

6. Pagination, filtering, and rate limits

• Pagination style documented (offset, cursor, Link headers) and a complete crawl tested, not page 1.
• updated_since or cursors for incremental sync; full snapshot only when required.
• Rate limits and backoff: status codes, Retry-After, daily caps.
• Burst behaviour during a sale: queue, don’t tight-loop.

“It worked for 40 orders” is not a pagination test.

7. Time, money, and identity

• Timezone of each vendor vs UTC storage. Order “date” vs payment “captured at.”
• Currency and rounding; tax-inclusive vs exclusive.
• Identity mapping: email vs customer id vs GSTIN collisions.
• Soft-deleted and merged customers.

Timestamp mistakes show up as “yesterday’s orders missing” and duplicate invoices. Treat time as a first-class field.

8. Environments and cutover

• Separate keys for sandbox and production.
• A rule that sandbox data never reaches production customers (and vice versa).
• Cutover checklist: DNS, webhook URLs, feature flags, who watches logs for the first 48 hours.
• Rollback: disable outbound adapters without corrupting the authority system.

9. Observability and operations

• Structured logs with correlation ids (your order id and their id).
• Metrics: lag, success rate, 4xx mapping errors vs 5xx vendor errors.
• Dead-letter queue and a human UI or runbook to replay.
• Alerts that page a person, not a dashboard nobody opens.
• Runbook: vendor down, auth expired, poison payload.

A nightly job that “usually works” is an operational hazard.

10. Security and compliance extras

• PII minimisation: do not sync fields you do not use.
• Access logs for who can replay or export.
• Vendor subprocessors and data residency if a customer or regulator will ask.
• No production data in tickets, screenshots, or AI tools without a policy.

How to use this list with Palmate

Bring a filled inventory (section 2) and any vendor docs you have. We will challenge dual authority, missing signatures, and “we’ll handle errors later.” API integration at Palmate includes contracts, retries, and what happens when a vendor is down — not a happy-path demo.

Use the API project estimator to count flows, the JWT decoder to inspect token claims during design, and the JSON formatter to keep samples honest. Then implement one flow to production with monitoring before connecting the rest.

A checklist is complete when an operator can pause, replay, and explain a mismatch. If you cannot tick that, you do not have an integration yet. You have a script.