Durable delivery — API/SDK advanced

The outbox and retry sequence on this page applies entirely to API/SDK advanced. Native Stripe merchants should not build an AffiHQ outbox for connected Stripe events: AffiHQ receives, verifies, checks the Stripe mode, retries and processes those deliveries. For native delivery issues, see the troubleshooting guide.

For API/SDK advanced, store every outgoing AffiHQ message in your own database. A delivery process can then retry the same message until AffiHQ accepts it or returns an error that needs review.

Store and send each advanced-mode message

1. Validate the local DTO.
2. Insert it into your durable outbox in the same database transaction as the signup, Checkout or webhook update.
3. Optionally attempt a short direct delivery.
4. Complete the signup, Checkout or webhook whether AffiHQ responds or not.
5. Let the delivery process retry pending messages.

Configure the API/SDK advanced outbox

Store a unique idempotency key, attempt count, next-attempt date and final rejection state with each message. Ensure that only one delivery attempt is active for a message at a time.

Do not copy payloads into logs. Record only the message ID, safe error code, AffiHQ request ID and attempt count.

Retry behavior

For API/SDK advanced delivery, the SDK uses exponential backoff with jitter and a one-hour cap. Keep a stable event identity for every retry. Generating a new provider event ID changes a replay into a second financial fact.

Test delivery recovery

Before enabling an API/SDK advanced integration for customers, stop delivery to AffiHQ and complete a test signup and payment. Confirm that both actions succeed and leave pending messages. Restore delivery, then confirm that the messages arrive without duplicating the attribution or commission.