Order Forge

Safe agentic commerce: AI understands the order, deterministic code verifies stock and pricing, PayPal authorizes the exact amount, and the merchant makes the final decision.

Comment

Inspiration

Custom and small-batch orders are often agreed through messages. That creates three expensive failure points: the price can drift from what the customer accepted, the requested stock may no longer be available, and a payment retry can create a duplicate charge.

AI can understand a customer’s request, but it should not become the authority for inventory, pricing or payment. We built OrderForge to give AI a useful role while keeping every commercial decision inside deterministic, testable systems.

What it does

OrderForge turns a natural-language request into an exact, PayPal-authorized order.

A customer can describe an order such as:

“We need 20 welcome boxes with notebooks, no food and our logo. Keep it under $40 per box.”

The AI converts that message into structured requirements and proposes a suitable configuration. OrderForge then:

  1. Validates every product against the shop’s catalog and current stock.
  2. Calculates every amount in integer cents using deterministic code.
  3. Creates an immutable, versioned quote.
  4. Requires the customer to accept one exact quote version.
  5. Sends that exact amount to PayPal for authorization.
  6. Lets the merchant accept and capture the payment or decline and release the authorization.
  7. Creates one preparation job from the accepted quote.

The demo also shows a stock change. Twenty boxes can include a steel bottle, but thirty cannot because only twenty-four bottles are available. OrderForge identifies the blocker and proposes a desk organizer instead. The revised price is calculated as $36 per box and $1,080 total.

The customer is charged only after the merchant confirms the order.

Agent-facing interface

OrderForge also exposes a small public interface for buyer agents.

An agent can submit only five structured requirements:

  • Number of boxes
  • Whether the order must contain no food
  • Whether a logo is required
  • Maximum price per box
  • Optional requested pickup date

The agent cannot submit a price, choose a payable total, accept a quote or make a payment. OrderForge’s code selects from the shop’s catalog, validates stock and returns a deterministic offer.

A person must open the returned customer link, review the box, accept the exact price and approve it on PayPal. The merchant still makes the final decision.

How we built it

OrderForge is a Next.js 16 application written in TypeScript and deployed on Vercel.

Supabase provides PostgreSQL, authentication, row-level security, scheduled reconciliation and the application’s transactional data. Stock reservations use database transactions and row locks to prevent concurrent orders from overselling the same inventory.

The AI intake uses OpenRouter with strict Zod schemas. Model output is treated as untrusted input. Code validates the extracted requirements before they affect the catalog, quote or payment workflow.

Pricing uses integer minor units rather than floating-point values. Quote versions are immutable and bound to canonical data, so a payment authorization cannot silently move to a changed quote.

Payments use the PayPal Orders v2 and Payments v2 APIs with the AUTHORIZE flow. Stable PayPal request identifiers make capture and void operations idempotent. Verified PayPal responses and webhooks determine whether money moved; browser redirects and AI-generated text are never treated as payment evidence.

A reconciliation process checks uncertain operations directly with PayPal. Webhooks are verified, deduplicated and safe to process when they arrive late or out of order.

The entire project uses synthetic shops, products and customers with PayPal Sandbox. No real money moves.

Challenges we ran into

Keeping AI useful without trusting it with money

The model needed enough freedom to interpret natural language and explain alternatives, while remaining unable to control prices, stock, permissions or payment state. We solved this with strict schemas, a small tool surface and deterministic validation after every model response.

Handling stock changes during a conversation

A configuration that works for twenty units may fail for thirty. We built a catalog engine that returns coded blockers such as INSUFFICIENT_STOCK, then searches a bounded set of valid alternatives and recalculates the complete quote.

Building a safe authorize-then-capture flow

The customer approves the exact amount before the merchant commits to production. This required separate authorization, capture and void states, along with safe recovery when a network request returns an uncertain outcome.

Delayed and out-of-order webhooks

PayPal Sandbox webhooks can arrive several seconds later and sometimes in a different order from the underlying payment events. We treat webhooks as signals, deduplicate them and confirm uncertain state directly with PayPal.

Preventing duplicate charges and duplicate work

Every payment operation has a stable idempotency key. Database constraints ensure that one paid purchase creates only one preparation job, even when requests or events are replayed.

Accomplishments that we are proud of

  • Completed the full hosted journey against the real PayPal Sandbox.
  • Separated AI interpretation from authoritative pricing and payment decisions.
  • Built both customer and merchant experiences, including an explicit capture-or-release decision.
  • Added an agent-facing API that can request and read offers but cannot accept or pay.
  • Added immutable quote versions, transactional stock reservations, idempotent payments and reconciliation.
  • Passed 1,675 unit checks, 1,414 database checks and 172 end-to-end checks in the recorded proof run, with zero failures.
  • Published the implementation, specifications, test evidence and known limitations in the repository.

What we learned

Safe agentic commerce depends on boundaries more than prompts. A strong prompt can guide a model, but money and inventory require deterministic validation, database constraints and verified payment evidence.

We also learned that payment success is a distributed-systems problem. Redirects, retries, delayed webhooks and uncertain network outcomes all need explicit states and recovery paths.

Finally, visible proof matters. We kept mocked, replayed and real-sandbox evidence clearly labeled so judges and developers can see exactly what each test demonstrates.

What’s next for OrderForge

The next step is to test OrderForge with real merchants who currently manage custom orders through messages.

We would also add:

  • More product categories and merchant-defined configuration rules
  • Multiple currencies, delivery and partial-payment workflows
  • Distributed API rate limiting
  • More buyer-agent integrations
  • Merchant analytics based on measured production data
  • External security and accessibility reviews
  • Production PayPal onboarding after the sandbox workflow is validated

OrderForge demonstrates a practical foundation for agent-assisted commerce: AI interprets the request, code protects the agreement, PayPal protects the payment and the merchant keeps control.

Built With

Share this project:

Updates

Submission history