ai.commercestudio.b2b.purchase_order (payment handler)

Draft, version 2026-10-19. A UCP payment handler (UCP 2026-08-25). Schema: https://b2b.commercestudio.ai/ucp/schemas/purchase_order_handler.json.

Most B2B orders are paid on account. The buyer quotes a purchase order (PO) number, and the seller invoices the company under its payment terms. There's no card, no token and no payment credential. The PO number is a reference the buyer's accounts-payable team matches against the invoice.

This handler lets an agent pay that way through UCP's standard payment flow.

Advertising and negotiating

• The business lists the handler in its profile, with handler id purchase_order:

  "payment_handlers": {
    "ai.commercestudio.b2b.purchase_order": [
      { "id": "purchase_order", "version": "2026-10-19",
        "available_instruments": [{ "type": "purchase_order" }] }
    ]
  }
  

• The platform lists the same handler name in its own profile's payment_handlers to say it can submit PO instruments.
• A platform that doesn't list it can't pay on account. Its checkouts carry payment_handler_unavailable (error, requires_buyer_input) and have status requires_escalation, so the buyer completes at continue_url.

Instrument

Complete Checkout carries exactly one instrument:

{
  "payment": {
    "instruments": [{
      "id": "pi_po",
      "handler_id": "purchase_order",
      "type": "purchase_order",
      "credential": { "type": "purchase_order", "po_number": "BCC-PO-2026-117" }
    }]
  }
}

The PO number isn't secret and carries no PCI scope. The business shows it back in payment.instruments[].display.description and in b2b_terms.po_number.

Rules

• Exactly one instrument, on this handler. Anything else is refused with payment_failed (error, recoverable).
• A missing PO number, when one is required, is refused with missing at $.payment.instruments[0].credential.po_number.
• On-account rules still apply. Credit and approval are checked as usual (see the terms and approval extensions). The payment schedule is the account's term, in dev.ucp.common.payment.terms.
• Quotes. When a quote carries a PO number (b2b_quote.po_number), the business suggests it at checkout with a quote_po message.

Callisto on BigCommerce

The order is placed with status 7 (Awaiting Payment) and payment method "Purchase Order", and the PO number is set on B2B Edition's copy of the order. BigCommerce's Payments API can't record offline payments, so the payment method is set on the order itself.