Skip to main content

Order address resolution

Two HTTP entries on the order controller:

MethodPathService
POST/v1/commerce/orders/:id/address-resolution/triggertriggerAddressResolution
POST/v1/commerce/orders/:id/address-conflict/resolveresolveAddressConflict

Trigger​

triggerAddressResolution loads the order and its shipping address. It rejects the call unless addressValidationStatus is AWAITING_CUSTOMER_RESOLUTION (order.error.notAwaitingResolution).

It then enqueues outbox order.address.resolution_triggered and returns success. It does not validate the address inside the HTTP call.

The worker listener is WhatsAppAddressResolutionListener. It loads the order and shipping address. Missing order or address is logged and the handler returns, so the outbox event is treated as processed. No active WhatsApp agent (status: ACTIVE, deletedAt: null) is a warning and a return. No phone on the shipping address is an error and a return. None of those returns retry.

When an agent and a phone exist, the listener finds or creates an AgentSession for that phone (24 hour expiry), sets the session state to ADDRESS_RESOLUTION_PENDING, and sends a WhatsApp address form. The body text includes address-validation warnings when that JSON array is present. Country defaults to IN when the address has no country code. A throw from send or decrypt is logged and rethrown, so the outbox retries.

An order with no WhatsApp agent does not get another channel’s address form from this listener. Bharat Address validation remains the separate validate-pending-order job.

Conflict resolve​

POST /v1/commerce/orders/:id/address-conflict/resolve → resolveAddressConflict. Two actions exist.

CANCEL_SHIPMENT_AND_ACCEPT sets every active shipment to CANCELLED, copies the shipping snapshot (or the current shipping address) onto the order address and each fulfillment-order address, moves fulfillment orders in LABEL_CREATED or READY_TO_SHIP back to PACKED, clears the order exception and the override flags, and writes an order note. These writes are separate Prisma calls. They are not one $transaction. A failure after the first shipment cancel can leave some shipments cancelled and the address unchanged.

DISMISS clears the exception, sets isShippingAddressOverridden, stores who overrode it and when, snapshots the current shipping address, and writes a note that the order continues to the current fulfillment destination. It does not cancel shipments.

Neither action enqueues an outbox event in this method. Neither changes order status.

Create path​

Create writes addressValidationStatus from orderAddressHandler.validateAndCreateAddresses inside the same transaction as the order. A failed address check that throws rolls the order back. Statuses that are stored and do not throw are not fully listed on this page.