REST API
The primary production path. Use API keys, direct requests, and webhooks for authenticated control-plane operations and execution flow.
Default production integration path
Agent integration
Build against the merchant path Pivota exposes on top of existing merchant stacks.
Pivota is the builder surface for the commerce decision and order execution layer that sits on top of existing storefront, checkout, and payment systems.
Some merchants start with discovery, feeds, or link-out. When a merchant is ready for deeper flows, builders use the REST path or MCP to work with checkout, orders, events, and webhooks.
Why this matters
Merchant onboarding and rollout choice come first. This page describes the builder surface that sits on top of that merchant path, whether the merchant is starting with lighter discovery flows or deeper merchant-native checkout.
Start in 4 steps
Make the first call path obvious before login.
1
Create a developer account and get a production or test API key.
2
Send a first authenticated request against the branded API domain.
3
Create the first order or checkout flow and confirm response shape.
4
Configure webhook delivery and validate execution updates before promoting traffic.
Test and production keys are supported. Validate the first authenticated request and webhook loop before promoting traffic.
Public quickstart
Start with the branded REST path
Use the public API base and the X-API-Key header to validate access before building deeper order or checkout flows.
curl https://api.pivota.cc/agent/v1/merchants \
-H "X-API-Key: YOUR_API_KEY"Choose your integration mode
REST is the default. MCP adds tool access; there is no maintained SDK.
SDK
The pivota-agent 1.0.0 package on PyPI is not maintained and does not work as published: its default API host is retired and its README names the wrong install package. There is no supported Python SDK today; build against the REST contract.
Not maintained; use REST
MCP
A hosted remote MCP server at https://commerce.mcp.pivota.cc/mcp with OAuth, for MCP clients that support remote servers; confirm your client supports remote MCP with OAuth before relying on it. The open door at https://mcp.pivota.cc/mcp exposes four read-only tools. The keyed door adds scoped capabilities; some advertised tools are not wired through. Check the verification page before relying on checkout or order tools.
Open research tools; scoped authenticated execution
What can be called today
Choose request families by their verified scope and access requirements.
Not every merchant uses every request family on day one. Search, recommendation, and lighter handoff paths may come before deeper checkout and order flows.
Merchant-native checkout does not mean every agent surface completes checkout fully inside chat. Depending on merchant readiness and the surface, execution may continue through link-out or another merchant-controlled handoff while staying in merchant-controlled systems.
Search and recommendation
Query merchant data, resolve products and offers, and support downstream shopping workflows without crawling fragmented sites.
Cart and checkout intents
Validate item paths and create merchant-native checkout flows that carry execution forward.
Orders and order status
Create, inspect, and manage order flows while keeping merchant systems in control.
Order events and execution signals
Observe order lifecycle events and operational state instead of guessing from front-end surfaces alone.
Webhooks and delivery health
Configure destination URLs, subscribe to events, verify signatures, and inspect or retry delivery history.
Merchant-native payment flow
Route execution into payment-aware flows with write-back and sync rather than isolated checkout fragments.
Verify the public read-only tools · UCP Insights specification · Capability and funds-flow boundaries
Sandbox request and response limits
Show builders the execution shape, not just the category story.
Public docs should make the request contract visible before login so a builder can understand the next action, the merchant-native path, and the event model without guessing.
Request example
curl -X POST "https://api.pivota.cc/agent/v1/checkout/intents" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"items": [
{
"merchant_id": "merch_...",
"product_id": "prod_...",
"variant_id": "var_...",
"quantity": 1,
"currency": "USD"
}
]
}'The example shows only the API key. Purchase calls such as checkout intents and order creation also need verified buyer identity; an API key alone is not purchase authority. The OpenAPI lists the buyer headers each endpoint accepts, such as X-Agent-User-JWT.
Response contract limits
The published OpenAPI declares an untyped 200 response.
Inspect the returned result; do not assume a checkout URL, payment,
or order success from HTTP 200 alone.
Schema checked: 7 October 2026. Example IDs are placeholders.
Run only with a coordinated sandbox merchant and test credentials.Execution boundaries
Make the handoff and execution model explicit.
Pivota resolves structured commerce requests instead of forcing agents to crawl merchant pages.
Merchant-native checkout begins when the executable checkout path is created or returned.
Checkout hands off to the merchant's own payment providers, which authorize and process the payment; downstream status sync keeps merchant systems current.
Write-back and post-purchase signals continue through APIs and webhooks after execution begins.
What stays public vs what is in the console
Public docs for activation. Console for operational control.
Builders should be able to understand the contract, auth, and execution model without login. Account-specific controls and telemetry stay in the developer console.
Visible without login
First call quickstart and branded API base
Request families and example request shapes
Auth model, webhook model, and execution boundaries
Protocol positioning and merchant-onboarding dependency
Inside the developer console
Create and revoke API keys
Inspect usage, delivery history, and retries
Manage webhook destinations and signing secrets
Review order activity and account-specific operational state
Trust and proof
Public contract, not just conceptual positioning.
The public API schema and MCP discovery describe available interfaces. Their publication does not establish paid orders, fulfillment, or SDK compatibility.
OpenAPI is live on https://api.pivota.cc/openapi.json
The branded API base is https://api.pivota.cc
The hosted remote MCP endpoint is https://commerce.mcp.pivota.cc/mcp (streamable HTTP + OAuth, RFC 9728 discovery)
The PyPI package pivota-agent 1.0.0 is not maintained; use the REST contract
Verify remote MCP capabilities before selecting a client or local wrapper
Webhook receiver setup is account-scoped; confirm its current contract in the portal
Ready to evaluate the callable surface directly?
Start with API access and the first call, then move into request types, auth, webhooks, and protocol positioning as the integration deepens.