Sprusify

Order sync strategies

Reliable order syncing is essential for correct attribution and timely payouts. This page outlines common strategies, trade-offs, and recovery patterns.

Real-time webhook sync (recommended)

  • Use Shopify orders/create and orders/updated webhooks to process orders as they arrive.
  • Pros: low latency attribution, near real-time reporting.
  • Cons: requires a publicly reachable server and reliable webhook processing.

Batch reconciliation

  • Periodically poll the Shopify API or run a daily job to reconcile orders and fill gaps caused by missed webhooks.
  • Pros: robust against transient webhook failures; simpler to reason about for accounting.
  • Cons: higher latency and potentially more API calls.

Idempotency & failure handling

  • Implement idempotency keys for webhook handling to avoid double-processing.
  • On webhook failure, queue the payload for retry and record delivery errors for monitoring.

Refunds and chargebacks

  • Listen for refunds/create and orders/updated to adjust affiliate balances automatically.
  • Keep an audit record linking refunds to original order IDs and the affiliate earnings affected.

Reconciliation best practices

  • Log the order_id, shopify_order_number, and affiliate_id for every attributed conversion.
  • Keep a reconciliation job that compares attributed orders with Shopify orders to surface mismatches.

Developer notes

  • Use webhook verification and validate the WEBHOOK_SECRET.
  • Provide an admin interface to re-run attribution for specific orders when needed.

Combining real-time webhooks with periodic reconciliation gives the best mix of responsiveness and resilience.

  • Real-time webhooks: preferred for immediate attribution. Sprusify listens to orders/create, orders/paid, and orders/fulfilled events.
  • Periodic reconciliation: scheduled jobs (nightly) to reconcile missed or corrected orders.

Handling partial fulfillments and refunds

  • Attribute on initial paid event, but mark commissions as pending until shipping and returns windows pass if desired.
  • For refunds/chargebacks, create reversal transactions and notify affiliates with an adjustment reason.

Deduplication and idempotency

  • Use the Shopify id field and our internal external_order_id to dedupe incoming events.
  • Retry-safe webhooks should include idempotency keys or be deterministic by order ID.

Recommendations

  • Use webhooks for low-latency attribution and nightly reconciliation to catch missed events.
  • Keep a short buffer window (e.g., 24–72 hours) before finalizing commission payouts to reduce disputes.