An SMS order needs more than a success flag

Published by OPEN RAMBO. The engineering patterns and pseudocode illustrate designs, not a documented product API. Numerical examples are illustrative.

Separate the lifecycle

Start with requested, allocating and waiting states. Allocation failure is different from a waiting order that expires. Record message receipt as an event; do not infer that the customer completed verification. A delivery system generally cannot observe the target application’s final decision.

Make transitions conditional

Use a compare-and-set update with the current version. If cancellation and a delivery callback race, one transition wins and the other enters reconciliation. Never let a late timeout blindly overwrite a received message. Store both event time and processing time to explain delayed callbacks.

Keep money in a separate record

The order lifecycle can reference a debit or refund identifier without owning the balance itself. A cancelled order may still have a pending refund. Display that distinction instead of marking every cancellation as money returned. Keep an immutable transition history with safe order references.

Illustrative implementation

allowed = {
  "allocating": {"waiting", "allocation_failed"},
  "waiting": {"received", "cancel_requested", "expired"}
}
# Reconciliation decides raced terminal outcomes.

Acceptance check

Test duplicate receipt, cancellation versus receipt, and a timeout delivered after receipt. Check the history and ledger, not only the final label.

Read next

• Calculate SMS receipt rates without hiding failures
• Poll SMS orders without creating a request storm