Proof-of-Delivery Records for Paid Agent APIs

Proof-of-delivery records help paid API sellers answer a simple but important question: after an AI agent paid for an API call, what exactly was delivered?

That question becomes more important when the buyer is software. A human customer might remember clicking a checkout button, downloading a file, or reading a result on screen. An AI agent may receive an `HTTP 402 Payment Required` response, pay in USDC, submit proof, receive a JSON result, and immediately continue a workflow. If a seller later needs to explain the charge, reconcile revenue, review a refund request, or investigate a failed integration, a normal payment receipt is not enough.

For Apiosk sellers, proof-of-delivery records sit between payment infrastructure and business operations. The seller gets paid by AI agents with x402-style flows, accepts crypto in through supported stablecoin rails such as USDC on Base, keeps non-custodial seller controls, bundles micropayments, prepares euro-facing settlement records, and preserves enough context to reconcile what happened.

Why payment proof is not delivery proof

Payment proof shows that a buyer satisfied a payment requirement. In an x402 flow, the protected API can challenge the agent, verify the payment proof, and authorize the request. That is the commercial gate.

Delivery proof is different. It records what happened after the gate opened. Did the API execute? Which endpoint and price version applied? Was the result delivered successfully? Was the response complete, partial, empty, delayed, cached, or failed after payment? Did the item enter a settlement bundle, a hold queue, or a refund workflow?

Sellers should keep those concepts separate. If every payment record is treated as proof that a service was delivered, exceptions become hard to handle. If every execution log is disconnected from payment evidence, finance and support teams have to reconstruct transactions manually. A proof-of-delivery record connects both sides without pretending they match.

What proof of delivery should include

A useful record does not need to store sensitive payloads or private customer data. It should store enough structured metadata to make the paid event understandable.

At minimum, include:

• Request ID and idempotency key.
• Seller, endpoint, operation, and API version.
• Price version, quote ID, amount, token, and network.
• Payment proof reference and verification status.
• Execution start time, completion time, and final execution state.
• Response classification, such as delivered, empty, partial, cached, failed, or pending.
• Delivery reference, such as result ID, export ID, webhook delivery ID, or response hash.
• Bundle, settlement, payout, or reconciliation reference.
• Hold, refund, or review status when the record is not ready for normal settlement.

The goal is traceability. A seller should be able to start from a USDC payment and find the API result. A buyer or agent operator should be able to start from an API result and find the payment context. A finance workflow should be able to start from a euro settlement packet and find the paid requests behind it.

Use response classifications instead of vague success flags

A boolean success field is too weak for paid agent APIs. It hides important differences between commercial and technical outcomes.

For example, a payment may be valid while the API result is empty because no matching data exists. That can still be a delivered service if the endpoint promised a lookup, not a guaranteed match. A request may be served from cache, which can be valid delivery if the seller documents that behavior. A long-running enrichment job may be accepted after payment but not complete until a later webhook or polling result.

Proof-of-delivery records should classify the result in language that operations teams and agent developers can understand. Useful states include:

• `delivered`: the paid API action completed and a result was returned or made available.
• `empty_result`: the API completed successfully but found no matching content.
• `partial_result`: the API produced a limited result under documented conditions.
• `cached_result`: the buyer received a valid cached response.
• `accepted_async`: the paid job was accepted and will complete through another channel.
• `execution_failed`: payment verified, but the protected work failed.
• `delivery_unknown`: the system cannot yet prove the final delivery state.

Those states make refund rules, support review, and settlement decisions easier to automate. They also prevent buyers from confusing "no match" with "nothing was delivered."

Make the record agent-readable

Human support teams need searchable records, but AI agents also benefit from machine-readable delivery evidence. An agent that manages its own spend may need to decide whether to retry, request a refund, continue a workflow, or report a completed purchase.

A response can include a compact delivery summary without exposing internal settlement details. For example, the API can return a receipt reference, delivery state, request ID, endpoint ID, amount paid, token, network, and next action. If the result is asynchronous, the response should include the polling or webhook reference and a clear status.

Connect delivery evidence to settlement

Settlement should not rely only on wallet activity. A USDC payment on Base can show that value moved, but it does not explain whether the API delivered the service, whether the request was retried, or whether the seller should include the item in a normal payout bundle.

Proof-of-delivery records give settlement workflows better inputs. Delivered, empty-result, cached-result, and documented partial-result states may be eligible for normal bundling. Execution failures may move to a refund or review queue. Unknown delivery states may require a temporary hold until logs, webhook acknowledgements, or downstream processing catch up.

For euro-facing operations, the delivery record should follow the payment into the settlement packet. The packet does not need every log line, but it should preserve references that connect the payout total back to individual paid requests.

Handle retries and duplicate payments carefully

Delivery proof is tightly connected to idempotency. If an agent times out after paying, it may retry the call. Without stable identifiers, the seller may accidentally deliver twice, charge twice, or lose the connection between the original payment and the result.

For paid actions, require an idempotency key or request identifier that survives retries. If payment was verified and the result was delivered, a retry should return the existing delivery reference where possible. If payment was verified but execution is pending, the retry should report that state instead of asking the agent to pay again.

The proof-of-delivery record should show which attempts belong together. That helps the seller distinguish a duplicate proof, a duplicate execution attempt, and a legitimate new purchase.

A practical Apiosk-oriented pattern

A practical proof-of-delivery flow starts when the API returns an x402 payment requirement. The agent pays in the supported asset and network, such as USDC on Base where configured, then submits proof. Apiosk verifies payment context and helps the seller keep a structured paid-request record.

After verification, the protected endpoint executes. The seller records the execution state and response classification against the same request ID, quote ID, and payment reference. If the result is delivered, the item becomes eligible for bundling and later euro settlement preparation. If the result fails after payment, the item moves to review, refund, retry, or hold handling according to the seller's policy.

Delivery evidence should be useful, but it should not become an unmanaged archive of customer payloads. Many APIs handle sensitive inputs or commercially valuable outputs. Store identifiers, hashes, classifications, timestamps, and references to policy-controlled storage instead of full request and response bodies unless the business case requires more. Finance usually needs to know what was sold, when it was sold, how it was paid, whether it was delivered, and how it settled.

What to publish for buyers and agents

Sellers should document how delivery evidence works before agents start buying. The documentation should explain what counts as delivery, which response states are possible, how retries work, whether cached or empty results are billable, how asynchronous results are retrieved, and what references appear in receipts.

Clear documentation helps both sides. Agents can avoid unnecessary retries. Human buyers can inspect what their agents purchased. Sellers can reconcile stablecoin revenue into euro-facing operations with fewer gaps between payment, delivery, and settlement.

Proof-of-delivery records become important once AI agents can buy API calls directly. Sellers need a dependable way to show what was paid, what was delivered, and how that event moved through settlement. Apiosk is built for that operating model: payment-native API access for agents, stablecoin payment rails, seller-controlled policies, bundled micropayments, and records that make crypto in to euros out easier to understand.