# RevCent MCP Guide: `GetShipments`

Brief AI/MCP-focused guide for retrieving a bounded operational list of RevCent Shipments.

---

## Operation Summary

Operation:

```text
GetShipments
```

Purpose:

```text
Return a bounded list of previously created Shipments.
```

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

Use `GetShipments` for narrow operational retrieval over a known date range and small page/limit.

Do not use it for reporting or analytics.

---

## 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` |
| GetShipment | `https://revcent.com/documentation/markdown/mcp/operation/GetShipment.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 `GetShipments` only for bounded operational retrieval.

Good uses:

- show recent Shipments for a specific customer,
- retrieve Shipments in a narrow date window,
- review Shipments for a specific campaign/shop/status,
- locate a Shipment ID before using `GetShipment`,
- operational support review with a strict date range, page, and limit,
- inspect a short list of Shipments before a support or fulfillment workflow.

Do not use this operation for reporting or analytics.

---

## Input Schema

Required fields:

| Field | Type | Description |
|---|---:|---|
| `date_start` | integer | Unix timestamp in seconds for start of date range. |
| `date_end` | integer | Unix timestamp in seconds for end of date range. |
| `limit` | integer | Number of records to return. Range 1 to 25. |
| `page` | integer | Pagination page. |

Common optional filters may include:

| Field | Purpose |
|---|---|
| `campaign_filter` | Filter by Campaign IDs. |
| `currency_filter` | Filter by ISO 4217 currency codes. |
| `shop_filter` | Filter by User Shop IDs. |
| `status_filter` | Filter by Shipment status where available. |
| `metadata_filter` | Filter by metadata name/value pairs. |
| `customer_id` | Filter by a specific Customer ID. |

Example:

```json
{
  "date_start": 1761955200,
  "date_end": 1764547200,
  "limit": 25,
  "page": 1,
  "customer_id": "CCCCCCCCCCCCCCCCCCCC"
}
```

---

## Output Summary

`GetShipments` can return:

| Field | Meaning |
|---|---|
| `current_count` | Current number of items in this response. |
| `current_page` | Current page. |
| `total_count` | Total number of matching items for the operational query. |
| `total_pages` | Total pages for the operational query. |
| `results` | Array of Shipment objects. |

Shipment result objects can include shipment status, tracking, provider/method, fulfillment account context, ship-to details, customer context, product context, amount fields, metadata, and related record IDs.

---

## Customer-Facing AI Verification Warning

This operation may return sensitive customer, order, shipment, address, fulfillment, tracking, payment, subscription, trial, or lifecycle context across multiple Shipments.

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(s) before providing details or taking action.

Recommended rule:

```text
Do not provide Shipment details to a public-facing visitor based only on visitor-provided filters or lookup input.
```

Even if the visitor provides a customer name, email, tracking number, date range, address, order reference, product name, or other lookup detail, that alone should not be treated as authorization to disclose Shipment information.

Safe customer-facing flow:

```text
Visitor provides lookup/filter input
    ↓
AI uses GetShipments for a narrow operational lookup
    ↓
AI identifies likely Shipment(s)
    ↓
AI uses GetShipment for the specific selected Shipment when needed
    ↓
AI verifies the visitor against a secondary value from the retrieved record
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Recommended secondary verification values:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| Date range or recent shipment request | Customer email from the retrieved Shipment. |
| Customer name | Email, phone, or another value already on the retrieved customer record. |
| Customer email | Secondary phone, order-related value, or another record-backed verification value where available. |
| Tracking number | Customer email or phone from the retrieved Shipment. |
| Address / zip code | Customer email from the retrieved Shipment. |
| Shop/order/product context | Customer email or phone from the retrieved Shipment/Sale context. |

Important:

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

For example, if the visitor asks about shipments for a name, product, tracking number, or date range, verify against the customer email returned by `GetShipment` or the retrieved Shipment details before discussing a specific 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.


---

## Built-In Usage Warning

`GetShipments` is for operational retrieval, not analysis.

Correct split:

| Need | Correct Operation |
|---|---|
| Retrieve bounded recent Shipments | `GetShipments` |
| Retrieve one known Shipment | `GetShipment` |
| Search for a Shipment by term | `SearchShipping` |
| Edit a Shipment | `EditShipment` after verification and confirmation. |
| Refund a Shipment / shipping charge | `RefundShipment` after verification and confirmation. |
| Count shipments | `BigQueryRunQuery` |
| Calculate delivery/shipping performance | `BigQueryRunQuery` |
| Report fulfillment, refunds, campaign/shop/product/shipping-method performance | `BigQueryRunQuery` |

---

## Example: Correct Operational Use

```text
User: Show recent Shipments for customer C over the last 7 days.
```

Correct:

```text
Use GetShipments with customer_id, date_start, date_end, limit, and page.
```

---

## Example: Incorrect Reporting Use

```text
User: How many shipments were delivered last month by fulfillment provider?
```

Incorrect:

```text
Loop through GetShipments pages and calculate manually.
```

Correct:

```text
Use BigQueryRunQuery.
```

AI/MCP should simply run `BigQueryRunQuery` and not explain that it almost used `GetShipments`.

---

## Best Practices

1. Use tight date ranges.
2. Use filters whenever possible.
3. Keep `limit` small and within schema limits.
4. Use `GetShipment` for detail review after selecting a Shipment.
5. Do not loop through pages to build metrics.
6. Do not use this operation for reporting or data mining.
7. Verify customer identity before sharing Shipment details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for all analytics.

---

## Final AI/MCP Instruction

Use `GetShipments` only for bounded operational retrieval of Shipments.

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

Never use it for reporting, metrics, aggregation, counting, broad analysis, data mining, or bulk export. If the user intent is analytical, silently switch to `BigQueryRunQuery`.


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