Documentation

Quickstart

Sign in, connect a cloud provider, and create your first purchase order. The console and the SDKs call the same /v1 API, which you can also call with a scoped API key (see AI agents for minting one). Some actions always need a person signed in to Pleaxy, never an API key: approving, changing approval flows or autonomy, and recording a payment.

import { Pleaxy } from "@pleaxy/sdk";

// The base URL is the origin only: the SDK adds /v1/workspaces/<Workspace ID>.
const pleaxy = new Pleaxy({
  baseUrl: "https://api.pleaxy.ai",
  apiKey: process.env.PLEAXY_API_KEY, // "<keyId>.<secret>"
  workspaceId: process.env.PLEAXY_WORKSPACE_ID, // Company profile → Workspace ID
});

// AWS: start the connection, run the returned setup script in your own
// account, then pass back the read-only IAM role it created.
const setup = await pleaxy.cloudConnections.initAws();
await pleaxy.cloudConnections.create({
  provider: "aws",
  accountLabel: "Production payer",
  awsConnectionId: setup.connectionId,
  roleArn: "arn:aws:iam::912345678901:role/PleaxyBillingRead",
});

const po = await pleaxy.purchaseOrders.create({
  supplier: "Amazon Web Services",
  provider: "aws",
  lineItems: [
    {
      scopeType: "sku",
      scopeId: "AWS-EC2-M5LG",
      name: "EC2 m5.large",
      ruleType: "quantity",
      unit: "hr",
      unitPrice: 0.096,
      qty: 5_000,
      nteAmount: 0,
      paymentTerms: "Net 30",
      validFrom: "2026-01-01",
      validUntil: "2026-12-31",
    },
  ],
});

// po.status is "pending_approval" while your approval flow runs, then
// "awaiting_fulfillment". Autonomy, if on, can approve it straight away.

Purchase orders & line items

A PO is built from one or more line items, each independently priced and tracked:

• SKU lines — a specific item from a supplier's catalog, billed by quantity × unit price. When the supplier publishes a catalog in Pleaxy, the item id on the line is validated on the server.
• Service or account blanket lines — a not-to-exceed cap covering a whole service or an entire cloud account.
• Custom lines — for anything not on a supplier's catalog, either quantity-based or a flat not-to-exceed amount.

Every line is in the region currency, carries its own payment terms and validity period, and tracks a live balance — consumed vs. remaining — against that period, flagging lines on pace to exhaust early.

Cloud connections

Pleaxy connects read-only to Amazon Web Services (AWS), Google Cloud, Microsoft Azure and Oracle Cloud Infrastructure (OCI) billing, through access you create in your own account with a setup script, and you can revoke it anytime. Pleaxy keeps every purchase order as its own record and doesn't write purchase orders into any cloud provider:

• Amazon Web Services (AWS) — a cross-account IAM role Pleaxy assumes. It reads your issued invoices and Cost Explorer. To have AWS print a Pleaxy PO number on its invoices, add it under Purchase orders in the AWS Billing and Cost Management console.
• Google Cloud — Workload Identity Federation to a service account that can only read your BigQuery billing export. Google has no invoice API, so Pleaxy uses the export's month total.
• Microsoft Azure — a federated credential on an app in your own tenant. It reads your billing profile's invoices and month-to-date cost. Pleaxy doesn't attach PO numbers to EA invoices.
• Oracle Cloud Infrastructure (OCI) — an API signing key Pleaxy generates; you upload only the public key. It reads usage invoices where your account has them, and otherwise each closed month's cost.

Approvals & autonomy

Each region has one approval flow for purchase orders and one for invoice payments, which you edit under Workflows in Pleaxy. A new region starts with a single step routed to a region administrator. You build a flow from three kinds of step:

• Approver — one person signs off.
• Parallel approvers — several different people each sign off, in any order.
• Conditional approver — runs only when all of its conditions match. Conditions can check the amount (in the region's currency), the supplier or the requester.

Every step names one specific person, and only that person can act on it. Mark a step Only above the high-value threshold and amounts at or below the threshold skip it. A flow needs at least one step with no conditions, so every order and invoice reaches a person. If you raised the document yourself, your step goes to another administrator. You can approve it yourself only when nobody else in the region could, and it is then marked Self-approved.

On the Autonomous plan you can turn on autonomy, also under Workflows. Pleaxy then approves a purchase order or invoice up to your auto-approve amount by itself, as Pleaxy Autonomy, with the same audit trail. It never does so when a conditional or high-value step applies, or when a purchase order goes over its requester's spend limit. For invoices it's stricter: only an invoice matched against an issued AWS invoice can be auto-approved, and never one a buyer entered or one in another currency. Automation rules let you treat one supplier differently: always send its documents to a person or, on the Autonomous plan, auto-approve them up to an amount.

An API key can read approval flows and autonomy settings, but only a person signed in to Pleaxy can change them, and an API key never approves a step.

const flow = await pleaxy.approvalChains.get("purchase_order"); // or "invoice_payment"

const autonomy = await pleaxy.settlement.getAutonomy();
// { enabled, maxAutoApproveAmount, approvalThreshold }
// approvalThreshold is the high-value threshold. Change these in Pleaxy, under Workflows.

Invoice matching

An invoice billed against a purchase order, for a cloud provider you have a live billing connection to, starts in pending match status. Running the match compares the invoiced amount with the usage the provider reported:

• Within 3% → matched, and it goes to your invoice approval flow.
• More than 3% off, or in a different currency → discrepancy. Pleaxy doesn't convert currencies. Someone checks it against the provider's bill, then resolves it into the approval flow or rejects it. If autonomy is on and the difference is within your auto-approve amount, Pleaxy approves it itself instead, within the invoice limits described under Approvals & autonomy.

An invoice with no purchase order, or no billing connection to check it against, is unverified. A person signed in to Pleaxy reviews it, then sends it to the approval flow or rejects it.

Payments

Pleaxy doesn't pay invoices. Once an invoice's approval flow completes, the buyer pays it in its own payment run (approved invoices can be exported for it) and records the payment in Pleaxy. Recording moves no money. The supplier sees the payment as recorded by the buyer and gets a remittance advice. Recording a payment needs a person signed in to Pleaxy, never an API key. Paying an invoice through Pleaxy, by bank transfer with Stripe, isn't available yet.

AI agents (MCP)

The Pleaxy MCP server exposes purchase orders and invoices as tools for Claude or any other MCP-compatible agent. It's a thin wrapper: every tool call is one authenticated request to the same /v1 API the console and SDKs use, so an agent can do exactly what its API key allows — nothing more.

1. Mint a scoped API key with POST /v1/workspaces/:regionId/api-keys while signed in as yourself — an existing API key can't mint another (see API keys). The key takes your own role in the workspace, buyer or supplier, and only an administrator can mint one. A buyer key is read-only unless you give it a procurementRole, such as requisitions to create purchase orders. The response contains the key (shown only once). Then copy the workspace's Workspace ID from Company profile in the Pleaxy console — you need both below.
2. Build the server (Node.js 22.18 or later). The MCP server isn't published to npm yet — ask your Pleaxy contact for the pleaxy-mcp source, then:

   cd <mcp source folder>
   npm install
   npm run build

3. Add it to your MCP client. For Claude Desktop or Claude Code, add this to your MCP config. The base URL is the origin only — the server adds /v1 itself.

   {
     "mcpServers": {
       "pleaxy": {
         "command": "node",
         "args": ["/absolute/path/to/<mcp source folder>/dist/index.js"],
         "env": {
           "PLEAXY_API_BASE_URL": "https://api.pleaxy.ai",
           "PLEAXY_API_KEY": "<keyId>.<secret>",
           "PLEAXY_WORKSPACE_ID": "<Company profile → Workspace ID>"
         }
       }
     }
   }

One server process serves one workspace — one API key, one Workspace ID. Buyer and supplier keys see the same tool list, but a call outside the key's role (a supplier key calling create_purchase_order, say) is rejected by the API exactly as it would be over REST.