Order Receipt Delivery: SMS Timeout Retry Idempotency and Status Polling

An order receipt is evidence of a settled payment, so the sending process cannot be allowed to reinterpret the order or quietly render a newer template after a timeout. The application should own an immutable receipt intent: order ID, payment-settlement event ID, recipient, template version, render data, and one idempotency key. A timeout then means unknown outcome, not failed delivery.

Short answer: persist that intent before dispatch, reuse its idempotency key for every retry, poll the same attempt after an ambiguous response, and permit a new send only after the state machine reaches a terminal retryable outcome.

This is less convenient than wrapping an SMS call in a generic retry helper. Good. Convenience at this boundary is how one settled payment becomes two receipts.

How should event notifications handle SMS timeout, retry, idempotency, and status polling?

Start by separating four facts that are often collapsed into one status string: the payment settled; the application recorded a notification intent; a transport accepted an attempt; and the recipient's network reported a delivery outcome. None implies the next. In particular, a client-side timeout says only that the caller stopped waiting. It doesn't establish whether the transport accepted the message.

Use a state machine whose transitions are narrower than the provider vocabulary. pending may dispatch. submitting has an unresolved attempt and must be polled, not resent. accepted may still need status polling. delivered and permanent_failure are terminal. A bounded retryable_failure can return to pending while preserving the same logical idempotency key. If the upstream system has a dozen delivery labels, map them at the adapter boundary; don't let those labels leak into order processing.

The invariant is compact: one payment-settlement event creates one receipt intent, and every transport attempt points back to it. Put a unique constraint on the event identity or on a deterministic key such as order_receipt:<payment_event_id>. The database write that acknowledges the payment event should also create the outbox record. Otherwise a process crash can leave either an acknowledged event with no receipt or a receipt with no durable record of why it exists.

This does not promise exactly-once delivery. It gives the system a place to contain ambiguity.

No resend yet.

Template ownership is a data-contract decision

For an order receipt, template ownership belongs with the team that owns order semantics, even if a communications service performs rendering or delivery. The durable intent should name an immutable template version rather than a mutable alias such as latest. Its data should already contain the settled amount, currency, order reference, and recipient values authorized for that receipt. A retry hours later must not re-read a changed cart, a corrected product title, or a newly deployed template and then produce a materially different document for the same payment event.

The limitation is operational ownership: version retention, schema validation, and privacy-aware storage become application concerns. This model is not suitable when the message is promotional, its content is deliberately campaign-managed, and business users must change it independently of application deployment. Keep campaign templates in the campaign system in that case. The trade-off is deliberate: a transactional order receipt favors replay fidelity over editing speed, while a campaign favors delegated editing and audience policy.

Treat rendering as a pure function of (template_version, render_data). Validate the data before the intent becomes dispatchable, record a content fingerprint, and keep transport metadata separate from the business payload. This split also prevents a status webhook or poller from gaining permission to alter receipt content.

Make the ambiguous branch explicit in code

The following Python sketch is intentionally a state transition function, not a provider client. That keeps invented endpoints out of the design and makes the dangerous decision testable. A Node.js Express service can apply the same transition after loading the intent under a row lock; the language is incidental, while the persisted compare-and-set boundary is not.

from dataclasses import dataclass, replace
from enum import Enum


class State(str, Enum):
    PENDING = "pending"
    SUBMITTING = "submitting"
    ACCEPTED = "accepted"
    DELIVERED = "delivered"
    RETRYABLE_FAILURE = "retryable_failure"
    PERMANENT_FAILURE = "permanent_failure"


@dataclass(frozen=True)
class ReceiptIntent:
    payment_event_id: str
    template_version: str
    idempotency_key: str
    state: State
    attempt_count: int
    transport_message_id: str | None = None


def after_submit(
    intent: ReceiptIntent,
    *,
    timed_out: bool,
    accepted_message_id: str | None,
) -> ReceiptIntent:
    if intent.state is not State.SUBMITTING:
        raise ValueError("submit result applied outside submitting state")

    if timed_out:
        # Preserve ambiguity: the poller resolves this attempt before any resend.
        return intent

    if accepted_message_id is None:
        return replace(intent, state=State.RETRYABLE_FAILURE)

    return replace(
        intent,
        state=State.ACCEPTED,
        transport_message_id=accepted_message_id,
    )

The important line is the one that appears to do nothing. Consider the concrete sequence: worker A atomically changes intent order_receipt:pay_157 from pending to submitting, records attempt 1, sends the request, and reaches its local timeout before receiving the response. The process then exits. Worker B later loads the durable row and sees submitting, so it does not create attempt 2; it asks the adapter to resolve attempt 1 using the stored correlation data, and it keeps polling according to the adapter contract until the outcome becomes explicit or the local resolution policy expires. Only a confirmed retryable outcome can move the intent back toward dispatch. An HTTP 200 from a submission call, by contrast, should normally mean accepted for processing rather than delivered to a handset, so it still cannot close the receipt workflow unless that is the adapter's explicit contract. This longer path is intentional: collapsing any of those observations into “send failed” would discard the distinction between an absent response and an absent side effect.

There is another sharp edge. Two workers may both read pending before either writes submitting. Claim work with a conditional update, transaction, or queue lease, and increment the attempt counter in the same atomic operation. The idempotency key protects the logical operation at a cooperative downstream boundary; it does not replace concurrency control in your own storage. I would test this with two workers released by the same barrier, because a single-threaded happy-path test cannot expose the duplicate-send race.

What should be compared before choosing the boundary?

Compare ownership models, not logo grids. The useful question is where the immutable intent, template version, idempotency record, and delivery mapping live, and which team can repair each one without changing payment code.

I'm not sure a universal retention period is defensible; tax, support, privacy, and dispute requirements differ. Resolve that uncertainty with the teams that own those policies, then encode the result separately for receipt content, transport metadata, and logs. Keeping everything forever is not an architecture.

Email deserves one adjacent boundary. RFC 8058 defines a one-click unsubscribe mechanism for list mail through specific headers and an HTTPS POST. An order receipt and a marketing follow-up should therefore remain different intents, templates, and policy paths; do not let a receipt retry become an excuse to blend transactional and promotional content. The RFC is useful for the marketing path, not as evidence that a carrier delivered an SMS.

Roll out from observation to enforcement

Begin by generating the deterministic idempotency key and logging it beside the payment event without changing dispatch. Next, persist receipt intents and compare shadow state transitions with current outcomes. Then move one narrow receipt type to the outbox worker, with alerts for intents stuck in submitting, attempts that exceed the retry budget, terminal failures, and duplicate key conflicts. Finally, enforce immutable template versions and remove the old direct-send path.

Rollback should stop new claims while preserving queued intents; deleting them destroys the evidence needed for recovery. Keep the migration boring.

Test the failure modes, not just the message text: crash after the intent commit, timeout after downstream acceptance, duplicated payment events, concurrent workers, late status updates, and out-of-order status updates. For an agent or tool-driven dispatcher, use a narrow schema with explicit fields and enum values; the tool-definition guidance in Anthropic's documentation is a useful example of why detailed parameter descriptions and unambiguous names improve correct tool selection, though it does not define SMS delivery semantics.

The final acceptance rule is simple: payment code emits one durable, versioned intent; dispatch code never guesses that a timeout is a failure; and status processing can move state only along declared transitions. That design will not erase the distributed-system uncertainty. It will stop the uncertainty from turning into duplicate order receipts.

References

• https://datatracker.ietf.org/doc/html/rfc8058
• https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview