Integration recipes

Patterns that reuse the conventions and webhooks.

Keep an external system in sync

Combine a one-time backfill (paginate the resource) with ongoing webhooks (react to changes). Don’t poll.

// 1) Backfill
let page = 1;
for (;;) {
  const { products, pagination } = await cartisto(`/products?limit=100&page=${page}`);
  await upsertAll(products);
  if (page >= pagination.pages) break;
  page++;
}
// 2) Then subscribe to product_created / product_updated webhooks and upsert on
//    each delivery (verify the signature; dedupe by product id).

React to orders

Subscribe to order_created and payment_received. On delivery, verify the signature, enqueue, and return 2xx immediately:

app.post("/hooks/cartisto", (req, res) => {
  if (!verify(req)) return res.status(401).end();
  res.status(202).end();               // ack fast
  queue.add(req.body.event, req.body.payload); // process async, idempotently
});

Respect rate limits on bulk work

Cap concurrency and back off on 429:

async function withRetry(fn, tries = 5) {
  for (let i = 0; i < tries; i++) {
    try { return await fn(); }
    catch (e) {
      if (e.status !== 429 || i === tries - 1) throw e;
      await sleep(2 ** i * 500);
    }
  }
}

Time-box a contractor’s access

Issue a scoped API key with an expiry and only the permissions the job needs; revoke it when done. For a theme developer, issue a Theme Access key (scoped to themes) instead of dashboard access.