Handle order updates

Snapcaster sends one signed order.updated event for each change in the table below. Its data is the order that GET /orders/{orderId} returns, as of the moment Snapcaster queued the event, plus a reason.

Branch on the reasons you handle, and ignore any new ones. Events can arrive out of order, so compare the envelope created_at or read the order again when you need the latest state.

Print shipping labels from ship_to. It holds the newest correction, or the customer address if there is none, and customer keeps the address the buyer typed at checkout.

Your platform can correct the address itself with POST /orders/{orderId}/corrections while the order is created or accepted. Send source: "suggested" with the address_verification.suggested_address to accept it as it is, or source: "manual" with an address you confirmed with the buyer. The province and country cannot change. Snapcaster ignores case, extra spaces and an empty line2 when it compares addresses, so a correction that differs from ship_to only in those returns HTTP 422 CORRECTION_UNCHANGED. After a correction, Snapcaster emails the buyer and sends order.updated with reason address_corrected.

When address_verification.status is pending or failed, run the check again with POST /orders/{orderId}/address-verification/retry. You can retry a failed check once a minute, and you cannot retry a check that already has a verdict.

Before shipping, a seller who cannot send a line as ordered can file a fulfillment report that offers the buyer a different version of the same card from their own listings. When the buyer accepts, the line keeps its line_ref, quantity and unit_price, and its sku_id, external_ref, name, and card details switch to the substitute. Pick and pack from lines in this event. order.created still describes the line as bought at checkout, even on a retry, so a warehouse that packs from it picks the original card.

Stock change for each event gives the stock to move for the substitution. If the buyer refuses the offer or cancels the order instead, those outcomes arrive as the cancellation events you already handle.

A seller can return part of a line’s price to the buyer as a credit when they substitute it. The line’s substitution_credit_cents is that credit per unit, summed over every substitution of the line, and 0 on a line never substituted. unit_price never changes, so the line is now worth unit_price - substitution_credit_cents per unit. The line’s substitution names the fulfillment report that last rewrote it and, in original, the card it carried before.

Each accepted report that substituted a line also appears in substitutions, with the lines it removed or substituted and the credit per unit. Its payment_refund is the money the report returned to the buyer, including the credits, any removed cards, and their share of the purchase fee and tax. Book that refund against substitutions[].id, as you book a cancellation’s against cancellations[].id.

A cancellation, refund or substitution that returns money starts with payment_refund.status set to pending. When the money came in on more than one payment, Snapcaster returns it on each one, and payment_refund reports them together. The status is failed if any of those payments refused the refund, succeeded once every one has settled, and pending otherwise. A status can move back, for example from succeeded to failed when the buyer’s bank returns a settled refund, then to succeeded again if a later retry settles. Each change of status sends order.updated with reason: payment_refund_updated, and the matching cancellations, refunds or substitutions entry carries the new status.