Vectorwyse
Back to Work
Direct-to-consumer Retail

Vibes

Order intake and fulfilment integration API

A partner-facing order API that accepts purchases from a ticketing platform, guarantees they can't be double-counted, and hands them to a fulfilment warehouse without human involvement.

Four Vibes screens: an order payload and ShipStation response, the product inventory, the partner API docs, and the orders list
3
External systems integrated
21
Automated tests
121
Commits on main
2 yrs
In production

Figures measured directly from the project repository.

The problem

Selling through someone else’s checkout is a good way to reach customers and a hard way to run an operation. Vibes sells product through AXS, the live-event ticketing platform — the customer buys at the point they’re already transacting, which is excellent for conversion and means the order originates in a system Vibes doesn’t own, in a format their fulfilment warehouse has never heard of.

That leaves a gap that is usually filled by a person with a spreadsheet: someone exporting orders from one system, reformatting them, and pasting them into another. It works until volume rises or attention lapses, and its failure modes are the expensive kind — an order shipped twice, an order never shipped at all, a product sold after it ran out.

The three specific risks were duplicate submissions from network retries on the partner’s side, inventory drifting away from reality between systems, and the manual handoff to fulfilment.

What we built

A small, deliberately narrow API that sits between the ticketing platform and the warehouse.

Two endpoints, tightly scoped

The public surface is intentionally minimal: a product lookup and an order intake endpoint. Authentication uses Sanctum tokens with per-ability scoping, so being authenticated isn’t enough on its own: each partner credential can do only what it’s been explicitly granted. A partner integration gets exactly the reach it needs.

Both endpoints carry inline documentation annotations — parameter descriptions, types, and worked example payloads — so the partner’s engineers had a real reference to build against rather than a Slack thread.

Idempotency as a schema constraint

The duplicate-order problem is solved at the point where it can’t be circumvented. Every incoming order carries a unique request identifier from the partner, and the order record is keyed on it. A retried request — a timeout on the partner’s side, a network blip, an over-eager client — resolves to the same order record rather than a second one.

This is a small amount of code doing a disproportionate amount of work. It means the partner can retry freely, which is exactly what you want a partner to feel safe doing.

Validation is otherwise strict about anything that would cause a downstream failure, so an order the warehouse couldn’t act on never gets accepted in the first place.

Everything downstream hangs off one event

Order creation dispatches an OrderCreated event, and the consequences are listeners rather than inline procedure. One sends the customer’s confirmation email through Postmark. Another decrements the product’s available inventory with an atomic database decrement — not a read-modify-write, so concurrent orders can’t both read the same stock level and both succeed.

Adding a consequence to an order means adding a listener. Nothing in the controller changes.

Handoff to fulfilment

Orders are transformed into ShipStation’s format — order number, customer, billing and shipping addresses, line item, store routing — and submitted through a dedicated service. The raw ShipStation response is stored on the order either way, so a failed submission leaves a diagnosable record instead of a silent gap, and the order can be resubmitted rather than reconstructed.

Submission runs as an Artisan command for scheduled batch processing, and the same command is exposed as a one-click action in the Filament admin, so staff can push orders through on demand without a developer or a terminal.

How we approached it

This project is a good illustration of scope discipline. The temptation with an integration like this is to build a commerce platform: a cart, a catalogue manager, a customer account system. None of that was needed, because the storefront was AXS and the warehouse was ShipStation. What was needed was a reliable, well-documented seam between them.

So the codebase is small — seven models, two public endpoints, 21 tests — and the effort went into the properties that matter for a system nobody watches: idempotent intake, atomic inventory, stored integration responses, and an admin surface that lets a non-engineer see and act on what the API did. Two engineers built and ran it over two years.

Where it stands

Active development concluded in late 2022. It’s included here as an example of integration work done at the right size — the smallest thing that could sit between two systems and be trusted to keep working unattended.

How it's put together

The system as it actually runs in production.

Vibes order API architectureOrders arrive from the AXS ticketing checkout at a token-authenticated API with scoped abilities. Each order is keyed on a unique request ID, so a retried request resolves to the same order record. Order creation dispatches an event whose listeners send the confirmation email and atomically decrement inventory, while a command submits the order to ShipStation and stores the raw response.PARTNERAPIPERSISTENCECONSEQUENCESAXSTicketing checkoutOrder intakeProduct lookupAPI gatewayREJECTS BEFORE IT ACCEPTSSanctum tokenPer-ability token scopesUnique request IDSKU must existAddress & quantity checkedOrder recordKeyed on therequest IDa retry is not a new orderOrderCreated listenersConfirmation email — PostmarkAtomic inventory decrementShipStationScheduled Artisan commandOne-click admin actionRaw response storedfulfilmentPLATFORM SERVICESFilament admin · Annotated API documentation · Error monitoring · PHPUnit suite · CI pipeline

Technologies used

Backend

  • Laravel
  • Laravel Sanctum
  • MySQL
  • Event-driven listeners

API

  • Token-scoped authentication
  • JSON resources
  • CORS handling
  • Annotated API docs

Integrations

  • AXS (order source)
  • ShipStation (fulfilment)
  • Postmark (transactional mail)

Admin

  • Filament
  • Laravel Jetstream (Teams)

Quality

  • PHPUnit
  • PHP CS Fixer
  • Husky commit hooks
  • CI pipeline
  • Sentry
Ready when you are

Let's build something great.

Whether you have a fully-formed spec or just an idea on a napkin, we'll help you turn it into a product your users love.