If your support team uses an AI agent that's connected to Onward, it can file Checkout+ package protection claims for customers right from a support conversation. This article is the procedure that agent should follow. You can paste the Agent instructions section at the bottom straight into your agent's handbook, playbook or system prompt.

To connect Onward to an AI agent in the first place, see Introduction to Onward MCP.

The three claim actions

Your helpdesk may label these actions differently. Whatever they're called, they map to these Onward tools, and the agent should always use them in this order.

Action	Onward tool	What it does
1. Find order	`find_order`	Read. Looks up a single order using the customer's email and order number, and only returns an exact match. Returns Onward's order ID (needed for the next two steps) and whether the order is protected.
2. Check claim eligibility	`prepare_claim_for_order`	Read. Confirms whether a claim can be filed and returns the claimable items and quantities, the causes available for this order, and your shop's resolution options. Creates nothing.
3. Submit claim	`submit_claim_for_order`	Write. Files a real claim and starts claim processing.

Step 1: Find the order

Use find_order. Ask the customer for both their order number and the email they ordered with. find_order works like the order lookup on Onward's claim page: it only returns an order when both match exactly, so the agent can't mix up one customer's order with another.

If no order is found, ask the customer to double-check both details and try again. The agent shouldn't try to find the order any other way, such as by name or tracking number.

If the order isn't protected by Onward, tell the customer and hand the conversation to your normal support process. Don't attempt a claim.

Step 2: Always check eligibility next

Check eligibility by calling prepare_claim_for_order with the order ID from Step 1. Do this on every order, even one that shows as protected. find_order only tells you the order is protected; it doesn't check the claim window or anything else.

prepare_claim_for_order runs the same checks as filing a claim from the Onward dashboard. When an order isn't eligible, the response includes a plain-English reason, such as:

The order isn't protected, or its protection was refunded
The order has been fully refunded
The order hasn't been fulfilled yet
It's too soon to file (the customer needs to wait a set number of days after delivery)
The order is outside the claim window
There's an open return on the order
There's an active or won payment dispute on the order
Every item on the order has already been claimed

If the order is ineligible, the agent should explain the reason to the customer in plain language and stop. It should not try to submit. (Submitting re-runs the same checks, so an ineligible order can't get through anyway.)

For how the claim window works, see What Are Claims & When Can Customers File?

Step 3: Pick the cause

Only use a cause that prepare_claim_for_order returned for this order. Any other cause is rejected. Map what the customer describes to one of these:

The customer says…	Cause	Notes
The package hasn't arrived and tracking hasn't moved	`stuck_in_transit`	Only offered when the package isn't confirmed delivered.
Tracking says delivered, but they never received it	`stolen`
The package arrived, but an item was missing from it	`missing`
An item arrived damaged	`damaged`	Ask for photos (see below).
They received the wrong item	`wrong_item`	Ask for photos (see below).
The package was returned to the sender	`returned`
The package arrived late	`late_delivery`	Only offered when the customer paid for shipping.
They're unhappy with the product's quality	`not_satisfied`	Only offered when the product is covered by Satisfaction Guarantee.

The agent should never use chargeback. It's reserved for payment disputes and isn't a customer-filed claim.

Cause details. Put the customer's own description of what happened in cause_details. This is what the claims team reads when reviewing the claim.

Photos. Filing a claim through an AI agent doesn't require photo evidence the way the dashboard does. For damaged or wrong items, the agent should still ask the customer for photos, keep them on the support ticket, and note in cause_details that photos were provided and what they show.

Step 4: Pick the resolution

Only use a resolution option prepare_claim_for_order returned. Your shop's claim settings control which options are offered (for example, whether refunds or store credit are available).

If more than one option is offered, ask the customer which they prefer.
late_delivery claims can only be resolved with refund_shipping.
reorder needs the items to be in stock. If submitting fails because an item is out of stock, offer the customer a refund or store credit instead (whichever is offered) and submit again.

Step 5: Confirm with the customer before submitting

Submitting files a real claim, so the agent should read back a summary and get a clear "yes" from the customer first:

Items and quantities affected. Quantities can't be more than each item's claimable quantity from prepare_claim_for_order.
What happened (the cause) and their description of it.
How they'd like it resolved (the resolution).
Shipping address and contact details, if they're choosing a reorder. The claim uses the order's shipping address, email, name and phone by default. If the replacement should go somewhere else, collect the new address and pass it with the claim.

Step 6: Submit the claim

Call submit_claim_for_order with the order ID, line items and quantities, cause, cause_details and resolution preference.

Submit once per claim. Don't resubmit after a successful submission.
If submitting returns a missing-field error, ask the customer for that information and try again.
Set send_email_confirmation based on your choice in the section below.

Step 7: Tell the customer what happens next

The agent should tell the customer their claim has been submitted for review, not that it's approved. If the order's tracking is still updating when the claim is filed, the claim can be withdrawn shortly afterward if the updated tracking puts the order outside the claim window.

The customer will get an email from Onward when their claim is resolved. For what each claim status means, see Claim Statuses & Lifecycle.

Choosing who sends the confirmation email

Onward only sends its "claim submitted" email to the customer when send_email_confirmation is set to true. It's false by default. Decide this once and write it into your agent's instructions:

Set it to true if you want the customer to get Onward's standard claim confirmation email.
Leave it false if your agent or helpdesk already sends the customer its own confirmation, so they don't get two.

Either way, Onward always emails the customer when the claim is resolved.

Agent instructions (copy into your agent's handbook)

Edit the line marked [CHOOSE] before you paste this in.

Filing Onward package protection claims

Use these three Onward actions, always in this order:
- Find Order (find_order)
- Check Claim Eligibility (prepare_claim_for_order)
- Submit Claim (submit_claim_for_order)

1. Find the order with find_order. Ask the customer for both their order number and the email they ordered with. find_order only returns an exact match. If nothing is found, ask the customer to double-check both and try again. Do not look the order up any other way. If the order is not protected by Onward, tell the customer and hand off to the normal support process. Do not file a claim.

2. Always check eligibility next by calling prepare_claim_for_order with the order ID from find_order, even if the order is protected. If the order is not eligible, explain the reason it gives in plain language and stop. Never call submit_claim_for_order on an ineligible order.

3. Choose the cause only from the causes prepare_claim_for_order returned:
- Hasn't arrived, tracking not moving: stuck_in_transit
- Tracking says delivered but not received: stolen
- Package arrived but an item was missing: missing
- Item arrived damaged: damaged
- Wrong item received: wrong_item
- Returned to sender: returned
- Arrived late: late_delivery
- Unhappy with product quality: not_satisfied
Never use chargeback. Put the customer's own description in cause_details. For damaged or wrong items, ask for photos, keep them on the ticket, and note in cause_details that photos were provided and what they show.

4. Choose the resolution only from the options prepare_claim_for_order returned. If more than one is offered, ask the customer which they prefer. late_delivery can only use refund_shipping. If a reorder fails because an item is out of stock, offer refund or store credit instead.

5. Before submitting, read back and get the customer's explicit confirmation of: the items and quantities (no more than each item's claimable quantity), what happened, the resolution they chose, and, for a reorder, the shipping address. The claim uses the order's address and contact details unless the customer gives different ones.

6. Submit the claim once with submit_claim_for_order. [CHOOSE] Set send_email_confirmation to true / false. If it returns a missing-field error, ask the customer for that information and retry.

7. Tell the customer the claim has been submitted for review. Do not say it is approved. Onward will email them when the claim is resolved.

Filing claims with a helpdesk AI agent