Skip to main content

Placing orders

The order flow typically spans product selection, shipping choice, payment initiation, and webhook-driven confirmation.

Flow​

  1. Search products.
  2. Fetch details for the chosen listing.
  3. Create an order with quantity and delivery address.
  4. Initiate payment with a regional provider.
  5. Confirm status by webhook or payment status endpoint.

Order creation example​

{
  "productId": "prod_123",
  "quantity": 12,
  "deliveryAddressId": "addr_456",
  "shippingOption": "direct"
}

Operational note​

Treat order.created as the request acceptance point and order.confirmed as the commercial confirmation point.

Cart concurrency note​

If your client uses the cart APIs before checkout:

  • treat the cart as availability-checked but non-reserving
  • send expectedItemVersion on cart item updates and removals
  • send expectedSnapshotVersion when clearing the cart
  • refresh cart state before retrying a 409 Conflict, because that usually means another tab or device changed the cart first
  • expect cart mutation to be blocked while checkout has reserved the same cart snapshot for payment handoff
  • if you maintain a client outside the ProcureIQ web or mobile apps, validate this concurrency contract explicitly before rollout
  • validate real 409 Conflict handling in those external clients before production launch, including cart refresh and user-facing retry guidance

These version fields are now part of the supported public contract, not optional hints for first-party clients only. Keep buyer-facing copy honest too: the cart remains a planning surface until payment handoff succeeds, not a hard inventory reservation.

The in-repo web and mobile clients already honor this contract. Any external SDK, partner integration, or private client outside this repository should be treated as pending validation until it has been tested against the same optimistic-concurrency rules explicitly.