# RevCent MCP Guide: `GetShipment`

Brief AI/MCP-focused guide for retrieving one RevCent Shipment.

---

## Operation Summary

Operation:

```text
GetShipment
```

Purpose:

```text
Retrieve the details of a specific Shipment.
```

A Shipment is a RevCent shipping/fulfillment record created when a shippable product needs to be shipped as part of a Sale, Subscription Renewal, Trial Expiration, or related commerce event.

Use `GetShipment` when the exact 20-character Shipment / Shipping ID is known and the user needs to inspect one Shipment record.

---

## Related Links

| Guide | Link |
|---|---|
| Shipping Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShipping.md` |
| Fulfillment Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewFulfillment.md` |
| GetShipments | `https://revcent.com/documentation/markdown/mcp/operation/GetShipments.md` |
| SearchShipping | `https://revcent.com/documentation/markdown/mcp/operation/SearchShipping.md` |
| EditShipment | `https://revcent.com/documentation/markdown/mcp/operation/EditShipment.md` |
| RefundShipment | `https://revcent.com/documentation/markdown/mcp/operation/RefundShipment.md` |
| Product Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProduct.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetShipment` for one known Shipment.

Good uses:

- review one shipment's current status,
- inspect shipped/delivered state,
- retrieve tracking number and tracking URL,
- inspect provider and provider method,
- review fulfillment account/fulfillment notification context,
- review ship-to details,
- inspect related customer, Sale, Product Sale, Trial, Subscription, or Subscription Renewal context,
- verify context before `EditShipment` or `RefundShipment`,
- support a customer asking about a specific shipment.

---

## Input Schema

Required:

| Field | Type | Description |
|---|---:|---|
| `shipping_id` | string | 20-character Shipping/Shipment ID. |

Example:

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

---

## Useful Output Areas

`GetShipment` can return detailed Shipment context, including:

| Area | Examples |
|---|---|
| Status | shipping status, shipped/delivered flags, shipped/delivered timestamps, customer notification flags. |
| Tracking | provider, provider method, tracking number, tracking URL. |
| Fulfillment | Fulfillment Account, Fulfillment Center, fulfillment notified status/date, fulfillment errors where applicable. |
| Ship-to | recipient name, email, phone, address, city, state, postal code, country. |
| Customer | Customer ID, name, email, phone, address, metadata. |
| Product | Product ID/name, SKU/internal ID, quantity, shippable/trial/subscription context. |
| Amounts | shipping amount, refunded amount, gross/net/fee fields where available. |
| Related records | Sales, Product Sales, Trials, Subscriptions, Subscription Renewals, Transactions, PayPal Transactions, Offline Payments, Tax, Pending Refunds, Chargebacks, Fraud Detections, AI Threads, AI Assistants, API Calls. |

Use related record IDs to retrieve the full lifecycle when needed.

---

## Customer-Facing AI Verification Warning

This operation may expose sensitive customer, order, shipment, address, fulfillment, tracking, payment, subscription, trial, or lifecycle context.

If this operation is used inside a customer-facing AI flow, such as:

- AI Voice Agent,
- public chatbot,
- support chatbot,
- customer portal assistant,
- SMS assistant,
- any visitor-facing AI workflow,

the AI/MCP client should verify the visitor is actually related to the Shipment before providing details or taking action.

Recommended rule:

```text
Do not provide Shipment details to a public-facing visitor based only on the Shipment ID, tracking number, or a value the visitor supplied.
```

Use a secondary value from the retrieved Shipment response to verify identity.

Recommended verification examples:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| Shipment ID | Customer email from `GetShipment.customer.email`. |
| Tracking number | Customer email or phone from the retrieved Shipment. |
| Customer name | Customer email or phone from the retrieved Shipment. |
| Address / zip code | Customer email from the retrieved Shipment. |
| Order/shop/product context | Customer email from the retrieved Shipment or related Sale. |
| Metadata/external ID | Customer email or phone from the retrieved Shipment. |

Example safe flow:

```text
Visitor provides shipment/search input
    ↓
AI uses SearchShipping and/or GetShipment
    ↓
AI retrieves the Shipment
    ↓
AI asks the visitor to verify a secondary value from the retrieved record, such as customer email
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Important:

```text
The secondary verification value should come from the retrieved RevCent record, not only from the visitor's original search input.
```

For example, if the visitor provides a tracking number, verify against the customer email returned by `GetShipment` before discussing the Shipment.

Do not disclose sensitive details such as:

- full customer address,
- unrelated order details,
- payment details,
- internal fulfillment errors,
- fraud/risk logic,
- unrelated customer records,
- internal notes not meant for customers,
- other related records unless the visitor is verified and authorized.

For consequential actions, such as editing shipment status, changing delivery/shipping details, refunding shipping, or triggering support/fulfillment action, require explicit confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This Shipment lookup/search operation is **not** a reporting tool.

Do not use this operation for:

- counting,
- aggregations,
- metrics,
- reporting,
- data mining,
- bulk retrieval,
- broad analysis,
- document property searches,
- shipping performance reports,
- shipment status reports,
- fulfillment provider performance reports,
- delivery-rate reports,
- shipment refund reports,
- campaign/shop/product/shipping-method performance metrics.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If the AI/MCP client intended to use this operation for reporting, metrics, aggregation, or data mining and then realizes BigQueryRunQuery is the correct operation, it does not need to tell the user about the correction.

It should simply use BigQueryRunQuery instead.
```

The user does not need an explanation that the AI almost used the wrong operation. The correct behavior is to quietly choose the correct operation.


---

## Correct Use vs Incorrect Use

| User Intent | Correct Action |
|---|---|
| “Show me this Shipment ID.” | Use `GetShipment`. |
| “What is the tracking number for this shipment?” | Use `GetShipment`, then verify customer identity if customer-facing. |
| “Can I edit this shipment?” | Use `GetShipment` first, then confirm and use `EditShipment` if appropriate. |
| “Can I refund this shipping charge?” | Use `GetShipment` first, then confirm and use `RefundShipment` if appropriate. |
| “How many shipments were delivered last month?” | Use `BigQueryRunQuery`, not `GetShipment`. |
| “Show shipping performance by fulfillment provider.” | Use `BigQueryRunQuery`, not `GetShipment`. |

---

## Best Practices

1. Use this only for one known Shipment / Shipping ID.
2. Use `SearchShipping` when the Shipment ID is unknown.
3. Retrieve before `EditShipment` or `RefundShipment`.
4. Verify customer and related Sale/Product Sale/Subscription context when needed.
5. Do not expose full address or sensitive shipment details in public AI flows without verification.
6. Verify customer identity before sharing Shipment details in customer-facing AI flows.
7. Use `BigQueryRunQuery` for all reporting and analytics.

---

## Final AI/MCP Instruction

Use `GetShipment` to retrieve one specific Shipment by Shipping ID.

In customer-facing AI flows, verify the visitor is related to the Shipment using a secondary value from the retrieved record, such as `customer.email`, before providing details or taking action.

Do not use this operation for reporting, metrics, counting, aggregation, data mining, or broad analysis. If the task is reporting-related, silently use `BigQueryRunQuery` instead.


---
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.