Turn policy wording into fields your agent can read

A merchant accepts returns within 30 days. Does that mean your agent can promise a refund to the buyer's card? The policy needs to say where the money goes.

return-policy-extract turns supplied return policy text into structured terms. Use it before comparing a merchant's return conditions against a buyer's requirements, or while preparing a return request. Missing scalar terms come back as null, so your caller can preserve what's unknown.

The endpoint costs 0.015 USDC per call, paid through x402 on Base mainnet. Send a POST request to https://x402.agentutility.ai/return-policy-extract using an x402-capable client.

Send the policy text

The request body has a policy_text string. The endpoint also accepts text as an alias, but use the named field in new integrations.

Here's an example input: 

{
  "policy_text": "Returns are accepted within 30 days of delivery. Items must be unused with original tags attached. Final sale items cannot be returned."
}

This policy leaves the refund destination unstated. It also says nothing about restocking fees or whether the buyer needs return authorization.

Keep those gaps visible.

The following illustrative response excerpt shows the extracted terms for that wording. String phrasing can vary; read the fields rather than matching the whole response against this example. 

{
  "truncated": false,
  "return_window_days": 30,
  "restocking_fee": null,
  "condition_requirements": "unused with original tags attached",
  "rma_required": null,
  "exceptions": ["final sale items"],
  "refund_method": null
}

return_window_days gives your caller a number it can compare against a requested window. Keep the original wording alongside it: “30 days of delivery” has a different starting date from “30 days of purchase,” and this field doesn't encode that distinction.

And check the exceptions before applying the general window. A final sale item in this example falls outside the stated return policy even if it arrived yesterday.

Preserve null through the decision

restocking_fee: null means the supplied text doesn't state a fee. Treating it as zero would let your agent quote a return cost the merchant hasn't supplied.

The same distinction applies to rma_required. An RMA is a return merchandise authorization. A false value reports that authorization isn't required; null leaves the requirement unknown. JavaScript truthiness collapses those cases, so compare explicitly.

Here's caller-side logic for reading that field from a successful response: 

function authorizationStep(terms) {
  if (terms.rma_required === null) {
    return "Ask the merchant whether return authorization is required.";
  }

  if (terms.rma_required === true) {
    return "Obtain return authorization before shipping.";
  }

  return "The supplied policy says return authorization isn't required.";
}

Likewise, refund_method: null should keep a comparison tool from labeling the offer “refund to original payment method.” Your interface can display “Refund method unstated” and retain the policy text for follow-up.

List fields have a separate convention. exceptions returns an empty array when no exclusions are extracted. That empty array doesn't establish that every product qualifies. Your caller still needs enough source text to assess the item.

Check how much text was read

Send the policy wording itself. The endpoint accepts text rather than fetching a policy URL, so a routing agent needs to obtain the relevant passage before calling it.

The input must contain at least 20 characters after trimming. Longer text is limited to the first 20,000 characters, and the response reports truncated alongside input_chars, the trimmed input length.

But a cropped policy can lose an exception near the bottom. If truncated is true, review the omitted text before using the extracted terms to prepare a return. Submit the relevant policy section with its qualifications intact.

For a buyer-facing answer, keep unknowns in the wording: “The supplied policy allows returns within 30 days of delivery for unused items with tags attached. Final sale items are excluded. The refund method is unstated.” If the buyer requires a refund to their card, ask the merchant to confirm that term before proceeding.