Recording pipeline

handle(), sync(), replay() and the queued job share one recording core. It routes a result by type() — refunds become a PurchaseRefund, purchases a Purchase, subscriptions a Subscription — and dispatches the matching events. A Notification or Unknown result is informational: recorded nowhere, it fires nothing and can never overwrite a subscription’s status. What differs is the audit row around it:

Idempotent by design

Every record is keyed on the unique (provider, provider_id) pair, so a store that redelivers a notification updates the same row instead of duplicating it. Line items are re-synced whenever the result carries any; a null price leaves the stored price untouched; the raw payload is kept in the model’s meta column. A new subscription without a name from the store is named after the product id, then the provider id; a later event without a name leaves the stored one alone.

Ordered by event time

Recording is ordered by occurredAt(). Each purchase, subscription and refund stores the time of the latest event applied to it (last_event_at): an older event — a redelivery, an out-of-order delivery, a replay — changes nothing and fires nothing, and a refunded row stays refunded unless an event provably newer than the refund reverses it (Apple’s REFUND_REVERSED, a won Stripe dispute). A result that cannot say when it happened (occurredAt() null — a GenericResult you built without one) is applied as before, but never un-refunds anything. The row is locked while this is decided, so two deliveries racing each other cannot interleave. A row you soft-deleted is still kept up to date by later notifications (it stays deleted), but fires no lifecycle event.

Recording a result you obtained yourself

Use Purchases::sync() — or its action, SyncProviderResultAction — for a result that didn’t arrive as a webhook; see The Purchases facade and DI and actions. The Record* actions behind the core are @internal — they skip the audit row that sync() writes and marks processed.