Machine-Readable Refund Rules for Paid APIs

Machine-readable refund rules help AI agents understand what happens when a paid API call does not go perfectly. A human developer can read a refund policy page, ask a support team, or interpret product wording. An agent needs clearer signals at the moment it decides whether to pay.

That is especially important for APIs protected by an x402-style payment flow. The agent may request an endpoint, receive an `HTTP 402 Payment Required` response, submit payment proof, and retry the call within seconds. If the call times out, returns no match, fails validation, or is retried, the agent needs to know whether the payment is still chargeable.

For Apiosk sellers, the goal is practical: get paid by AI, accept USDC on Base, keep non-custodial seller controls, bundle small payments, and preserve the records needed for euro settlement and reconciliation. Refund rules are one part of making that payment path understandable to buyers and operable for sellers.

Start with the paid unit

Machine-readable refund rules only work when the paid unit is clear. If a seller charges for "enrichment," the rule needs to say what counts as one paid enrichment. Is it one submitted domain, one normalized company profile, one successful match, or one processed request regardless of match quality?

Agents cannot reliably infer that from endpoint names. A path such as `/v1/enrich` describes a technical route, not a commercial unit. The refund rule should be tied to the paid unit:

• `unit`: one company enrichment request
• `chargeBasis`: valid processed request
• `emptyResult`: chargeable when no matching company is found
• `sellerError`: refundable or held for review
• `duplicateIdempotencyKey`: not charged twice

The exact field names can vary, but the semantics should not be vague. If a valid empty result is chargeable, say so. If seller-side timeouts are reviewed before settlement, say so. If invalid input is not refundable, explain that in plain documentation as well.

Publish rules in more than one place

Refund metadata can appear in several locations because agents interact with paid APIs in more than one phase.

OpenAPI or tool metadata is useful during discovery. It lets an agent decide whether an endpoint is appropriate before sending a request. The metadata can describe the paid unit, expected charge basis, idempotency requirement, and refund categories.

The live x402 payment challenge is useful at purchase time. It should return the current price, token, network, recipient, expiry, and payment proof instructions. It can also include a compact reference to the active refund rule version. The live challenge should remain the payment source of truth because prices, wallet settings, and availability can change.

Post-payment records are useful after the call. A receipt, webhook event, or seller dashboard record should include the request identifier, payment reference, endpoint, execution status, refund status, settlement status, and any review reason. This is what keeps support, finance, and engineering aligned.

Use stable refund categories

Agents and sellers benefit from a small, predictable set of categories. Too many categories make automation brittle. Too few categories force buyers to guess.

A practical structure can start with:

• `chargeable_success`: the API performed the paid work and returned the promised response.
• `chargeable_empty_result`: the API performed the paid work and returned a valid empty result.
• `chargeable_invalid_input`: the buyer supplied input that the endpoint documentation disallowed.
• `not_paid`: payment proof was missing, invalid, expired, wrong amount, wrong token, or wrong network.
• `refund_review`: payment was accepted, but the result needs seller review before settlement.
• `refundable_seller_error`: payment was accepted, but the seller system failed before delivering the paid work.
• `duplicate_review`: a retry or duplicate idempotency key may map to an existing paid request.

These categories are not a substitute for business judgment. They are a shared vocabulary. A seller can attach exact behavior to each category, and an agent can reason about likely outcomes.

Keep idempotency visible

Retry behavior is where many refund disputes begin. Agents retry because networks fail, responses time out, and payment-required flows include at least two attempts: the unpaid request and the paid retry. Without idempotency, a buyer may accidentally create more than one paid operation.

Machine-readable refund rules should state whether the endpoint expects an `Idempotency-Key` header, how long the key remains active, and what happens when the same key appears again. A seller might return the original result, return a status reference, reject the duplicate, or hold a later payment for review.

This is not only a developer convenience. It is a payment control. The idempotency rule connects the agent's intent to the seller's payment and settlement records. If a duplicate payment appears, the seller can tie it back to the original request instead of treating it as an unrelated transaction.

Tie refund status to settlement status

Refund rules become much more useful when they connect to settlement. Many paid API calls are small enough that sellers do not want each payment to become a separate finance event. Bundling micropayments lets sellers group eligible USDC receipts before payout, conversion, export, or euro reconciliation.

That creates an important timing question: has the payment already joined a settlement bundle?

A machine-readable record should expose settlement state in a simple way:

• `not_settled`: the payment has not joined a bundle.
• `held_for_review`: the payment is excluded from normal bundling until a decision is made.
• `bundled`: the payment is part of a settlement batch.
• `settled`: the payment has moved through the seller's settlement process.
• `adjustment_required`: a refund or credit decision affects a prior bundle or euro-facing record.

This helps both sides. The buyer can reference a refund status. The seller can reconcile revenue without losing request-level detail.

Example: a paid validation endpoint

Imagine a seller offers a paid API that validates business registration data. An agent pays a small USDC amount on Base for each processed validation request.

The refund rule says one paid unit is one processed validation for one submitted company identifier. Invalid input is chargeable only when the validation rules were clear and the request passed the schema layer. Empty or "not found" results are chargeable because they are valid outcomes. Seller-side `5xx` failures are held for review before settlement. Duplicate requests with the same idempotency key are linked to the first paid operation.

In practice, that means the agent can decide whether the paid call is appropriate before spending. If the result is "not found," it knows that outcome was part of the product. If the service fails after payment, the receipt can show `refund_review` and `held_for_review` instead of leaving the buyer to guess.

How Apiosk fits

Apiosk is built for the operating layer around paid agent APIs. It helps sellers expose payment-required access, accept x402-style payments, receive USDC, keep seller-controlled payment settings, bundle micropayments, and connect paid calls to settlement and reconciliation records.

Machine-readable refund rules make that flow easier for agents and humans to use. Agents can understand what they are buying. Developers can debug retry behavior. Sellers can keep exception handling out of normal bundles. Finance teams can trace euro-facing records back to the paid requests that created or adjusted them.

The result is not a louder refund policy. It is a cleaner payment contract between software systems: clear paid units, clear failure states, clear settlement status, and clear records when a paid call needs review.