Multi-vendor number ordering with asynchronous provisioning
US telecom number-management platform (name withheld)
Built before Veldway. Delivered by the people behind Veldway as engineers on another company's team, not as a Veldway engagement. Client, product, and partner names are withheld; the role and period are stated below.
The problem
Phone-number inventory sits with several upstream vendors, each with its own API, data, and timing. Orders often don't complete instantly, large orders take minutes, and a mistake in live ordering means real numbers bought or lost. Customers and staff still need one search, one checkout, and a clear status for every order.
Requirements
- Search numbers across multiple vendors with enrichment, filters, and pagination
- Reserve numbers in a cart with timeouts, then place vendor orders at checkout
- Complete large orders asynchronously and keep their status accurate
- Be able to stop live vendor ordering instantly without a deploy
- Give staff internal desks for porting, numbers, customers, and vendor orders
The solution
A Rails 8 and React application in which each upstream vendor sits behind its own adapter. Checkout creates vendor orders; small orders complete inline, while large ones are handed to background jobs that poll the vendor and accept webhook updates, whichever arrives first. Live ordering sits behind a kill switch, and staff tools ship behind feature flags.
Architecture
Vendor adapters normalise each upstream API into one search and ordering interface. Sidekiq jobs poll pending orders while webhook endpoints accept vendor callbacks; both update the same order record, so status stays correct whichever path completes it. A feature switch gates live ordering, and request and domain specs plus browser tests run in CI.
Challenges & resolutions
Vendor orders complete minutes later, and either a webhook or a poll may report it first.
Resolution — Both paths update the same order record, so status stays correct regardless of which arrives first.
A fault in live ordering buys or loses real numbers.
Resolution — Live ordering sits behind a kill switch that can be turned off instantly, without a deploy.
Access-control gaps can let one customer's data appear in another's view.
Resolution — Queries were scoped to the authorised account and covered by request specs.
Why this matters for your integrations
Any business that orders, provisions, or syncs through someone else's API faces the same three problems: every vendor is different, responses arrive late or twice, and a mistake costs real money.
Normalise at the edge. One adapter per vendor keeps vendor quirks out of the rest of the application, so adding a vendor doesn't mean rewriting search or checkout.
Let either signal win. Webhooks are fast but can be missed; polling is reliable but slow. Writing both to the same record — idempotently — keeps the status right no matter which arrives first.
Keep a hand on the switch. A kill switch for anything that spends money or changes real inventory is cheap to build and invaluable on the day something upstream misbehaves.
How we apply this
These patterns apply to payment providers, fulfilment and 3PL APIs, ERP and accounting syncs, and Shopify order flows alike. See Veldway's API and billing integration service.
What was delivered
- Numbers from multiple vendors searchable and orderable in one place
- Large orders processed in the background, with status updated by webhook or polling
- Live vendor ordering can be switched off instantly without a deploy
Have a similar problem?
Describe the problem in plain language — broken, slow, manual, or missing. We'll tell you honestly whether and how we can help.
- 01We reply within one business day
- 02A short call to understand the problem
- 03A written scope and fixed quote — no obligation