AfterShip Post-Purchase

Create one or more return allowlist rules for the authorized org. This is a BATCH call: every element of `allow_rules` becomes a new rule in a single request. BUSINESS RISK — read before every call: an allowlist rule lets matching returns through the merchant's normal return policy. Nothing errors out; the return simply goes through. A broad condition (an entire product_type, product_tag or order_tag, or a discount threshold, rather than one specific order, item or customer) can waive the policy for a large share of orders and create real refund cost. Whenever a rule is broad, spell out its blast radius to the user before creating it. Before calling, show the user the exact rules you are about to create — for each one the `condition`, the `operator` and every entry of `values` — and get their explicit confirmation. Do not invent conditions or values the user did not state. RULE SHAPE — each element is exactly {condition, operator, values[]}. `values` is always an ARRAY, and its length is fixed by `operator`: exactly 1 for is_value / equal_greater_than_value / equal_less_than_value, exactly 2 for between_values (lower bound first). A wrong count is rejected before the call is made. Do NOT send the shape returned by list_return_allowlist (which nests {key, operator, value} under `conditions`) — that is the read shape and the upstream rejects it. MATCHING SEVERAL VALUES — there is no multi-value / "in" / "any of" operator. To allow, say, four product types, send FOUR rules in the same call, each `is_value` with one value. Do not pack several values into one rule and do not invent an operator name; only the four listed operators exist and anything else is rejected before the call is made. The allow-rule `condition` list is NOT the block-rule one: this tool accepts `order_name`, while `order_tag` belongs to add_return_blocklist and is rejected here. That single value is the only difference between the two lists. Use the value list documented on the field; never copy condition values between the two tools. This tool is NOT idempotent — calling it twice creates duplicate rules. If a call appears to have failed, call list_return_allowlist to check whether the rules were already created before you retry.

add_return_allowlist

Create one or more return BLOCKLIST rules for the authorized org. This is a BATCH call: every element of `block_rules` becomes a new rule in a single request, and the call is NOT idempotent — calling it twice creates duplicate rules. If a call appears to have failed, run list_return_blocklist to check whether the rules already exist before retrying. BUSINESS RISK — read before every call: a blocklist rule silently blocks real customers from starting a return. Nothing errors out; the shopper simply cannot file an RMA. A broad condition (an entire product_type, product_tag or order_tag, rather than one specific order, item or customer) can block a large share of legitimate returns. Whenever a rule is broad, spell out its blast radius to the user before creating it. Before calling, show the user a summary of every rule you are about to create — its `condition`, its `operator` and every entry of `values` — and get their explicit confirmation. Never invent a condition or a value the user did not state. RULE SHAPE — each element is exactly {condition, operator, values[]}. `values` is always an ARRAY, and its length is fixed by `operator`: exactly 1 for is_value / equal_greater_than_value / equal_less_than_value, exactly 2 for between_values (lower bound first). A wrong count is rejected before the call is made. Do NOT send the shape returned by list_return_blocklist (which nests {key, operator, value} under `conditions`) — that is the read shape and the upstream rejects it. MATCHING SEVERAL VALUES — there is no multi-value / "in" / "any of" operator. To block, say, four product types, send FOUR rules in the same call, each `is_value` with one value. Do not pack several values into one rule and do not invent an operator name; only the four listed operators exist and anything else is rejected before the call is made. The blocklist condition values are NOT the same as the allowlist ones: the blocklist takes `order_tag` where the allowlist takes `order_name`. That single value is the only difference between the two lists. Use the value list documented on each field; never copy condition values between the two tools.

add_return_blocklist

Post an INTERNAL note on the timeline of one RMA. It is written for the merchant team and is never sent to the shopper. Before calling, show the user the exact comment text you are about to post and the target `rma_number`, and get their explicit confirmation. Do not rewrite, expand, summarise or invent wording the user did not state. The `rma_number` comes from list_returns or get_return — never guess it, never construct it, and never pass an order number in its place. `content` is PLAIN TEXT. Rich text / markdown, @mentions and attachments are not supported in this release; do not attempt them. The server stores the text wrapped in <p>…</p> and echoes it back that way — show it as-is, do not strip the tags and do not escape it again. This tool is NOT idempotent: calling it twice leaves two comments, and there is no tool to edit or delete a comment once posted. If you are unsure whether a previous call succeeded, ask the user — do not retry on your own.

add_return_comment

Approve ONE submitted return (RMA), moving it to the `approved` state. Requires an `rma_number` obtained from list_returns or get_return — never guess or construct one. Precondition: the RMA must currently be `submitted` (Pending approval). The RMA lifecycle cannot skip steps (the three allowed paths are listed in the server instructions). Call get_return first to verify the current state instead of assuming it; approving an RMA that is not `submitted` is refused upstream. This is a write that this server cannot undo — there is no un-approve tool. Show the user a summary (which RMA, its current state, the state it will move to, and who it affects) and get their explicit confirmation before calling. Approval only opens the return; it does NOT receive items, resolve the return, or move any money. Never tell the user or the shopper that a refund or an exchange has been completed. Returns `{ rma_number, rma_status, note }`. `note` is null on a normal success; when the upstream does not echo the new state, `rma_status` is null and `note` says the action was executed and to read the current state via get_return instead of retrying. Render `rma_status` as its label, never the raw code: `submitted`→Pending approval, `approved`→Approved, `done`→Resolved, `rejected`→Rejected, `expired`→Expired.

approve_return

Return the available values (with display labels) for ONE filter dimension. Two kinds of field, do not confuse them: **org-derived** fields return only the values this org actually has, each with a `count`; **dictionary** fields return AfterShip's global catalogue — stable values + labels, NO count, and NOT an indication of what this org uses. Call this FIRST (facets-first), before a list tool, so you filter with valid values and avoid empty results — and so you can show the human label instead of the raw code. One `field` per call, and every field name carries its own product prefix — `tracking.` for shipment dimensions, `returns.` for RMA dimensions — so the prefix is all that selects the source. The full option set is returned in a single call — there is no pagination, so you can pick from the complete list (tracking fields are capped at the upstream maximum of 1500 values; if the response carries `truncated: true`, narrow with `q`). Only pass `q` when the list is large and you already know roughly what to look for; it is a case-insensitive substring match over value and label. `tracking.status`, `tracking.sub_status` and `tracking.carrier_slug` are the dictionary fields (no `count`); every other field is org-derived (has `count`). In particular `tracking.carrier_slug` lists ~1500 carriers AfterShip supports, most of which this org has never shipped with — never present it as "the carriers you use", and never pick from it to answer "which carriers does my org have". To answer that, call the list tool and aggregate by carrier instead. Name mismatch to watch: the prefix belongs to THIS tool only — the list tools take the bare name, and sometimes a different one: values from `field=tracking.status` go into the list_shipments parameter named `latest_status`. Discovery-only fields (not accepted as list_shipments filter inputs): `tracking.sub_status`, `tracking.order_tags`, `tracking.store_slug`, `tracking.custom_field_keys`. Read-only.

get_field_options

Return the curated full detail of ONE RMA by its `rma_number` (from list_returns): identity, approval/shipping/refund status, outcome, order, return_items, exchange, receivings, restocks, shipments, amounts (cost_of_return / estimated_refund_total / refunded_total), and key timestamps incl. updated_at. Use list_returns FIRST to obtain a valid rma_number (List→Detail); do not guess RMA numbers. Status fields are enum-coded — render their labels (per the list_returns filter map) when showing them. A foreign/unknown rma_number fails closed as not found. Read-only. Output enum display labels (render the label, never the raw code): - rma_status / shipping_status / refund_status / outcome / return_method / grade / exception: reuse the same value→label maps from the matching list_returns filter. - approval_status: `submitted`→Pending approval, `approved`→Approved, `rejected`→Rejected, `expired`→Expired, `done`→Resolved. - refund_destination: `original_payment`→Refund to original payment method, `store_credit`→Refund to store credit. - refund_methods: render the value directly (no mapping).

get_return

Return the full definition of ONE return workflow by its `id`. This is the only place where the trigger `conditions` are visible — the list view deliberately omits them — so use this whenever the user asks WHEN or WHY a workflow fires, on top of id, name, priority, status, applied_status, action_type, errors, action and timestamps. The `id` must come from list_return_workflow (List→Detail). Do not guess it, do not construct it, and do not pass a workflow name — resolve the id first. An id that belongs to another organization fails closed and is reported as not found, exactly like an id that does not exist; do not read anything into the distinction and do not retry with variations of the id. Read-only: this tool inspects configuration and never changes anything.

get_return_workflow

Return the curated full detail of ONE shipment by its `id` (the `tracking_id` from list_shipments). Fields follow the upstream Tracking API names: status / substatus / substatus_message, return_to_sender / damaged / lost, order_date / shipment_pickup_date / shipment_delivery_date, flat origin_* and destination_* address fields, service_type {name, code, standardized_name}, latest_estimated_delivery_date / order_promised_delivery_date objects, on_time_status, customers (when permitted), and the full `checkpoints` timeline (each with status / substatus / checkpoint_time / city / state / country_region / checkpoint_hash). `id` is NOT a tracking number, last-mile number, order number/id, shipment title, customer name/email/phone, SKU, or any note/custom-field value. If the user supplies any of those, call list_shipments FIRST to resolve the `tracking_id`, then call this tool; if list_shipments returns multiple candidates, ask the user to choose (do not guess). A foreign/unknown id fails closed as not found. Read-only. Output enum display labels (render the label, never the raw code): - status: display `status_label` — the upstream's human-readable label — never the raw code. checkpoints[].status uses the same 9 status codes; resolve their labels via get_field_options(field=tracking.status). - on_time_status: `on-time`→On time, `early`→Early, `late`→Late, `overdue`→Overdue, `trending-on-time`→Trending-On-Time, `trending-late`→Trending late, `trending-early`→Trending early. - substatus / checkpoints[].substatus: resolve value→label via get_field_options(field=tracking.sub_status). When displaying results, resolve human labels for the get_field_options-sourced coded fields (carrier_slug, service_type, shipping_method, origin/destination country_region/state/city, sub_status) by calling get_field_options(field=tracking.…), and show the label, not the raw code.

get_shipment

List the return allowlist rules configured for the authorized org (AfterShip Admin: Return policy > General > Blocklist and allowlist). Each rule is flat: a `condition` type (what is matched), an `operator` (how it is matched) and `values` (an array — one element for single-value operators, two for `between_values`). Always quote the `operator` and `values` back to the user when describing a rule; the `condition` alone does not tell them what the rule actually matches. Filter by `q` — an EXACT match on one complete rule value, where a prefix or substring matches nothing and an empty result does not prove the rule is absent — and/or by a `condition` type. Paginated: `page` is 1-based (upstream default 1, declared maximum 10) and `limit` is the page size (upstream default 60, declared maximum 200). The response reports `has_next_page` but the upstream returns NO total count — never state, estimate, or compute how many allowlist rules exist in total; if `has_next_page` is true, say that more pages are available and offer to fetch the next page. Each rule's `id` is the identifier that remove_return_allowlist requires: always take it from this tool's output, never construct or guess it (List→Write). Read-only.

list_return_allowlist

List the return BLOCKLIST rules configured for the authorized org (AfterShip Admin: Return policy > General > Blocklist and allowlist). A blocklist rule PREVENTS the matching orders / items / customers from starting a return. This is a separate list from the return allowlist, and the two do NOT share the same condition values — the blocklist takes `order_tag` where the allowlist takes `order_name`. Never copy condition values between the two tools. Each rule is flat: a `condition` type (what is matched), an `operator` (how it is matched) and `values` (an array — one element for single-value operators, two for `between_values`). Always quote the `operator` and `values` back to the user when describing a rule; the `condition` alone does not tell them what the rule actually matches, and remove_return_blocklist needs the user to be able to tell two same-condition rules apart. Filter by `q` — an EXACT match on one complete rule value, where a prefix or substring matches nothing and an empty result does not prove the rule is absent — and/or by a `condition` type. Paginated: `page` is 1-based (upstream default 1, declared maximum 10) and `limit` is the page size (upstream default 60, declared maximum 200). The response reports `has_next_page` but the upstream returns NO total count — never state, estimate, or compute how many blocklist rules exist in total; if `has_next_page` is true, say that more pages are available and offer to fetch the next page. Each rule's `id` is the identifier that remove_return_blocklist requires, and this tool is its only source: always take the id verbatim from this output, never construct or guess it (List→Write). Read-only.

list_return_blocklist