# RevCent MCP Guide: `RefundShipment`

Brief AI/MCP-focused guide for the RevCent `RefundShipment` operation.

---

## Operation Summary

Operation:

```text
RefundShipment
```

Purpose:

```text
Refund a Shipment using the Shipment / Shipping ID.
```

Use `RefundShipment` when the refund target is specifically the shipping/shipment amount connected to a Sale, Product Sale, Trial, Subscription Renewal, or other shippable commerce event.

This is preferred over raw transaction-level refunding when the business wants the refund tied cleanly to the Shipment for shipping lifecycle tracking, fulfillment context, and item-specific reporting.

---

## When to Use

Use `RefundShipment` when:

- the shipping/shipment charge itself is the refund target,
- the user provides or confirms the Shipment / Shipping ID,
- shipping was charged incorrectly,
- the shipment was delayed, failed, cancelled, or otherwise eligible for a shipping refund,
- the business wants clean shipping refund metrics,
- the refund should be attributed to the shipping/shipment record instead of being treated as a raw credit card refund.

Example user intent:

```text
Refund the shipping charge on this shipment.
Refund $5 from this shipment.
Refund shipping for this subscription renewal shipment.
Refund shipping because the order was delayed.
```

---

## When Not to Use

Do not use `RefundShipment` when the refund target is a different item.

Prefer the operation that matches the item being refunded:

| Refund Intent | Preferred Operation |
|---|---|
| Void or fully refund an entire Sale | `VoidSale` |
| Refund a Product Sale line item | `RefundProductSale` |
| Refund Tax | `RefundTax` |
| Refund a Subscription Renewal | `RefundSubscriptionRenewal` |
| Refund raw credit card funds without item context | `RefundTransaction` |
| Refund shipping/shipment amount | `RefundShipment` |

Best practice:

```text
Use the most specific refund operation for the item being refunded.
```

This preserves better item-specific reporting and metrics.

---

## Input Schema

| Field | Type | Required | Description |
|---|---:|---:|---|
| `shipping_id` | string | Yes | 20-character Shipment / Shipping ID. |
| `amount` | number | No | Amount to refund. If omitted, the entire Shipment amount is refunded. |

---

## Full Shipment Refund

If `amount` is omitted, the entire Shipment amount is refunded.

Example:

```json
{
  "shipping_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

Use this only when the user intends to refund the full shipping/shipment amount.

---

## Partial Shipment Refund

If `amount` is provided, only that amount is refunded.

Example:

```json
{
  "shipping_id": "SSSSSSSSSSSSSSSSSSSS",
  "amount": 5.00
}
```

Use this when the user intends to refund only part of the shipping/shipment amount.

---

## Output Schema

Successful output can include:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp of the API call. |
| `code` | API response code. `1` indicates success. |
| `amount` | Amount refunded. |
| `shipping_id` | Shipment / Shipping ID that was refunded. |
| `pending_refund` | Pending Refund IDs created as a result of the refund, if applicable. |
| `result` | Result message. |

---

## Pre-Refund Checklist

Before calling `RefundShipment`, confirm:

- the correct Shipment / Shipping ID,
- the customer/order/shipment context,
- whether the refund is full or partial,
- the exact `amount` if partial,
- whether the shipment has already been refunded,
- whether a broader order/item refund operation is more appropriate,
- the user explicitly confirmed the refund.

---

## Customer-Facing AI Safety

If `RefundShipment` is used in a customer-facing AI flow, such as a chatbot, AI Voice Agent, customer portal assistant, or SMS assistant:

```text
Verify the visitor is related to the Shipment before discussing details or taking action.
```

Use a secondary value from the retrieved Shipment record, such as customer email or phone, before providing shipment details or processing a refund.

Do not refund a Shipment based only on a visitor-provided Shipment ID, tracking number, name, or search term.

---

## Reporting Guidance

Use `RefundShipment` to perform the shipment/shipping refund.

Use:

```text
BigQueryRunQuery
```

for shipment refund reporting, shipping metrics, aggregation, or analysis.

Do not use operational refund or retrieval operations to build shipping refund reports.

---

## Final AI/MCP Instruction

Use `RefundShipment` when the refund target is specifically a Shipment / Shipping record.

If `amount` is omitted, the entire shipment amount is refunded. If `amount` is provided, only that amount is refunded. For other refund scenarios, prefer the operation that matches the root item being refunded, such as `VoidSale`, `RefundProductSale`, `RefundTax`, `RefundSubscriptionRenewal`, or `RefundTransaction`.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.