# RevCent Shipping & Fulfillment Overview for AI/MCP

AI/MCP-focused overview for Shipping and Fulfillment in RevCent.

This document explains what shipments are, how RevCent handles fulfillment integrations, how shipments are created from shippable products, and how ecommerce businesses benefit from RevCent’s shipping/fulfillment lifecycle.

---

## Source Operations

This overview is based on these RevCent MCP operations:

| Operation | Purpose |
|---|---|
| `GetShipments` | Retrieve a bounded operational list of previously created shipments. |
| `GetShipment` | Retrieve one shipment by shipping ID. |
| `EditShipment` | Edit a shipment, including tracking, shipped/delivered status, provider/method, and ship-to details. |
| `SearchShipping` | Search previously created shipments using a full-text search term. |
| `CreateProduct` | Create products, including shippable products that can generate shipments. |
| `CreateShippingProfile` | Create shipping profiles and rates used to determine shipping charges and eligibility. |
| `CreateFulfillmentAccount` | Create the user’s configured account/connection to a RevCent-supported fulfillment provider. |
| `GetUserShop` | Retrieve a connected third-party shop; use `remote_data: ["shipping_methods"]` for WooCommerce shops to retrieve remote shop shipping methods for mapping. |

---

## Related Documentation Links

AI/MCP clients should use these related overview files for deeper setup and automation context:

| Document | URL | Why It Matters |
|---|---|---|
| AI Assistants Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md` | Explains event-triggered AI workflows, Thread Builder steps, filters, delays, AI Memos, and AI automation that can respond to shipment events. |
| AI Voice Agents Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md` | Explains AI Voice Agents that can answer customer calls, perform outbound follow-up, and help customers with order/shipment status when configured with the right tools. |
| Functions Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewFunction.md` | Explains account-event Functions, webhook/URL Functions, external integrations, filter Functions, and custom automation around shipment events. |
| Email Templates Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewEmailTemplate.md` | Explains event-driven SMTP Email Templates, Handlebars, shipping input data, shipment shipped/delivered triggers, and customer/internal notifications. |
| Product Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProduct.md` | Explains product setup, shippable products, shipping attributes, fulfillment accounts, subscription products, trial products, bundles, and Product Groups. |
| Fulfillment Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewFulfillment.md` | Explains Site Fulfillment Centers, Fulfillment Accounts, Secure Forms, credential handling, tracking numbers, delivery updates, and fulfillment/shipping integration. |

Recommended reading order:

```text
OverviewProduct.md
    ↓
OverviewFulfillment.md
    ↓
Shipping & Fulfillment Overview
    ↓
OverviewEmailTemplate.md
    ↓
OverviewFunction.md
    ↓
OverviewAIAssistant.md
    ↓
OverviewAIVoiceAgent.md
```

---

## Core Concept

Shipping in RevCent is not just a tracking number.

A RevCent shipment is a commerce object created when a shippable product needs to be shipped as part of a Sale lifecycle.

A shipment can connect:

- customer details,
- ship-to destination,
- shippable product details,
- Sale and Product Sale IDs,
- shipping amount charged,
- shipping provider and method,
- tracking number and tracking URL,
- fulfillment account,
- shipping profile,
- fulfillment notification status,
- shipped/delivered status,
- customer notification state,
- metadata,
- reporting and profitability.

For ecommerce businesses, this is extremely valuable because selling a physical product does not end at payment approval. The product must be routed to fulfillment, shipped, tracked, and connected back to the customer, support team, and business metrics.

RevCent helps ecommerce businesses connect the payment lifecycle with the fulfillment lifecycle.

---

## Why Shipping Matters for Ecommerce Businesses

For physical-product ecommerce, fulfillment is one of the most important operational systems.

RevCent shipping/fulfillment support helps businesses:

- automatically route shippable products to fulfillment providers,
- automatically notify fulfillment providers for new orders, renewals, and trial expirations involving shippable products,
- reduce manual order entry,
- reduce fulfillment mistakes,
- connect Sales, Product Sales, customers, and shipments,
- support subscription refill shipments,
- support trial expiration shipments,
- track shipped/delivered status,
- store tracking numbers and tracking URLs,
- understand shipping amount, cost, refunds, and profitability,
- notify customers when shipments are shipped or delivered,
- troubleshoot fulfillment-account notification problems,
- support multi-store, multi-brand, multi-warehouse, and multi-provider operations,
- analyze fulfillment performance with BigQuery,
- automate shipment notifications, delivery notifications, and shipment-status support with Email Templates, Functions, AI Assistants, and AI Voice Agents,
- map third-party shop shipping methods so WooCommerce/customer-selected shipping methods route correctly in RevCent.

This makes RevCent especially useful for ecommerce businesses that sell physical products, subscription refills, trial products, bundles, or products fulfilled by third-party fulfillment providers.

---

## What Is a Shipment?

A shipment is a RevCent shipping record related to a commerce event.

Shipment records can include:

| Area | Example Data |
|---|---|
| Identity | `id`, `created_date_unix`, `shipping_status` |
| Customer | customer ID, name, email, address, metadata |
| Ship-to | recipient name, address, email, phone |
| Products | product ID, name, SKU, quantity, price, trial/subscription flags |
| Amounts | shipping amount, original total, gross, net, fees, refunded amount |
| Provider | provider, provider method, tracking number, tracking URL |
| Fulfillment | fulfillment account, fulfillment center, notified status/date |
| Shipping profile | profile ID/name used for shipping configuration |
| Status | shipped, delivered, merged, error |
| Notifications | whether customer was notified shipped/delivered |
| Related objects | Sales, Product Sales, Trials, Subscriptions, Renewals, Transactions, API calls |
| Metadata | custom name/value pairs for filtering and reporting |

AI/MCP clients should treat shipments as first-class ecommerce records.

---

## Shipping vs Shipment Naming

RevCent operations use both “shipping” and “shipment” language.

For AI/MCP purposes:

```text
shipping_id = shipment ID
shipping item = shipment record
shipment = ecommerce fulfillment/shipping object
```

Examples:

- `GetShipment` retrieves a shipment.
- `EditShipment` edits a shipment.
- `SearchShipping` searches shipments.
- `GetShipments` lists shipment records.

---

## How Shipments Are Created

Shipments are created when RevCent has a commerce event involving shippable products and shipping/fulfillment context.

Common sources:

| Source | Shipment Context |
|---|---|
| Initial Sale | Customer buys a shippable product. |
| Pending Sale processing | A pending Sale with shippable products is processed. |
| Subscription renewal | Renewal of a shippable subscription product can create a refill shipment. |
| Trial expiration | A trial expiration involving a shippable product can create shipment context based on trial shipping settings. |
| Shippable bundle Sale | Bundle or bundled products may create shipment context for shippable components. |
| Third-party shop order | WooCommerce/custom shop Sale can create shipment context when products are mapped as shippable. |

High-level flow:

```text
Product is configured as shippable
    ↓
Product has shipping attributes and fulfillment account
    ↓
Customer buys product / renewal occurs / trial expires
    ↓
RevCent creates Sale/Product Sale context
    ↓
RevCent creates shipment/shipping item
    ↓
RevCent can notify fulfillment account/provider
    ↓
Tracking and shipment status can be updated
    ↓
Customer/support/reporting systems can see fulfillment lifecycle
```

---

## Shippable Products

A product must be configured as shippable for RevCent to treat it as requiring shipment.

In `CreateProduct`, shipping-related fields include:

| Field | Purpose |
|---|---|
| `is_shippable` | Whether the product requires shipping. |
| `shipping_attributes` | Shipping details required when the product is shippable. |
| `shipping_attributes.fulfillment_account` | Fulfillment Account ID used to route fulfillment for the shippable product. |
| `trial_shipping_setting` | Controls when a trial product should ship. |

Before selling a shippable product live, verify:

1. `is_shippable` is true.
2. Shipping attributes are accurate.
3. A valid Fulfillment Account is assigned.
4. The assigned Fulfillment Account is enabled.
5. Shipping Profile/rates are configured where needed.
6. The product’s trial/subscription behavior is correct.
7. The business has verified fulfillment should actually occur.

---

## Trial Shipping Behavior

`CreateProduct` supports trial shipping behavior.

Relevant values include:

| Setting | Meaning |
|---|---|
| `trial_expiration` | Shipment occurs when the trial expires/converts. |
| `trial_creation` | Shipment occurs when the trial is created. |
| `both_trial_expiration_creation` | Shipment can occur at both trial creation and trial expiration. |

This is important for trial-based ecommerce.

Examples:

- A free trial starter kit may ship immediately at trial creation.
- A replenishment product may ship when the trial converts at expiration.
- Some products may require shipment at both trial creation and expiration.

AI/MCP clients should not assume all trial products ship immediately.

---

## Subscription Renewal Shipments

If a product is both shippable and subscription-based, subscription renewals can create recurring shipment/refill fulfillment context.

Example:

```text
Customer buys monthly supplement subscription
    ↓
Initial Sale creates first shipment
    ↓
Subscription renewal occurs each month
    ↓
Renewal charge creates new shipment/refill context
    ↓
Fulfillment account is notified
    ↓
Customer receives refill
```

This is critical for subscription ecommerce because recurring billing is only half the workflow. The business also needs recurring fulfillment.

---

## Fulfillment Accounts

A Fulfillment Account is the user’s configured connection to a RevCent-supported fulfillment center/provider.

Conceptually:

```text
Site Fulfillment Center = RevCent-supported provider/integration definition
Fulfillment Account = user’s configured account/credentials for that provider
```

A Fulfillment Account tells RevCent which provider/account should receive shipment/order data for physical products.

A business may have multiple Fulfillment Accounts for:

- different stores,
- different brands,
- different warehouses,
- different regions,
- different product types,
- test vs production,
- different 3PL providers.

---

## Creating Fulfillment Accounts

Use `CreateFulfillmentAccount` to create a user Fulfillment Account.

Required fields:

| Field | Required | Purpose |
|---|---:|---|
| `name` | Yes | Unique Fulfillment Account name. |
| `fulfillment_center` | Yes | 20-character Site Fulfillment Center ID. |

Optional fields:

| Field | Purpose |
|---|---|
| `description` | Notes about provider/store/warehouse/purpose. |
| `enabled` | Whether the account is enabled. |
| `secure_form_id` | Secure Form ID for securely saved provider credentials/configuration. |

Recommended workflow:

```text
Get available Site Fulfillment Centers
    ↓
Select correct provider/fulfillment center
    ↓
Create Secure Form for credentials
    ↓
User completes Secure Form
    ↓
CreateFulfillmentAccount with secure_form_id
    ↓
Verify configuration
    ↓
Enable account when ready
    ↓
Assign shippable products to the Fulfillment Account
```

### Secure Form Requirement

Fulfillment credentials are sensitive.

AI/MCP clients should never ask the user to paste provider credentials into chat.

Use a Secure Form workflow for:

- API keys,
- passwords,
- account IDs,
- warehouse IDs,
- tokens,
- provider-specific configuration.

### Fulfillment Account Must Be Enabled for Live Products

If products are actively sold and assigned to a Fulfillment Account, the Fulfillment Account must be enabled.

A disabled Fulfillment Account can prevent fulfillment provider notification and may prevent products from shipping.

Before active selling, verify:

- product is shippable,
- Fulfillment Account exists,
- Fulfillment Account is enabled,
- required credentials/configuration are saved,
- provider setup is verified,
- product is assigned to the correct account.

---

## Shipping Profiles

A Shipping Profile defines shipping rates and when those rates apply.

Use `CreateShippingProfile` to create a shipping profile.

Important schema behavior:

- `name` is required.
- At least one shipping rate must be present.
- Each rate must include `rate`, `provider`, `provider_method`, and `qualifiers`.
- A rate must have at least one enabled qualifier across products, product groups, countries, or revenue rules.
- Shipping profile creation is consequential and should require explicit user confirmation.

### Shipping Rate Fields

| Field | Purpose |
|---|---|
| `rate` | Amount charged to the customer for shipping. |
| `provider` | Site shipping provider ID. |
| `provider_method` | Site shipping provider method ID. |
| `qualifiers` | Rules that determine whether the rate applies. |

### Rate Qualifiers

Shipping rates can qualify based on:

| Qualifier | Purpose |
|---|---|
| `products` | Product IDs and quantity rules. |
| `product_groups` | Product Group IDs. |
| `countries` | Destination ISO3 country codes. |
| `revenue_rules` | Total amount, transaction amount, or shippable-product amount rules. |

Examples:

- Free shipping above $75.
- Flat-rate US shipping.
- Higher international rate.
- Product-group-specific rate.
- Heavy-item shipping rate.
- Subscription refill shipping rate.

---

## Product Groups for Shipping Rules

Shipping Profiles can use Product Group qualifiers.

Best practice:

```text
Organize a shop’s products into Product Groups and use those groups for shipping-rate qualification where appropriate.
```

This is cleaner than managing shipping rules one product at a time.

Examples:

```text
Product Group: Supplements
Shipping Rate: $6.95 for US orders
```

```text
Product Group: Heavy Items
Shipping Rate: $14.95
```

---

## Third-Party Shops and Shipping Methods

Third-party shops, especially WooCommerce stores, require special attention for shipping setup.

When a shop is connected to RevCent, the shop may already have shipping methods configured in the remote ecommerce platform. RevCent needs those remote shipping methods to be added and mapped correctly inside the RevCent third-party shop configuration so shipments can use the correct carrier/provider and provider method.

This is critical because a customer may select a shipping method in the remote shop checkout, but RevCent still needs to understand how that remote method maps to RevCent-supported shipping providers/methods.

The key operation is:

```text
GetUserShop
```

with:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "remote_data": ["shipping_methods"]
}
```

The `remote_data.shipping_methods` option applies to WooCommerce stores and retrieves shipping methods from the remote shop. This helps the AI/MCP client see which shipping methods exist in the remote shop and ensure they are properly added/mapped in RevCent.

---

## Why Third-Party Shop Shipping Method Mapping Matters

Shipping method mapping matters because it connects the remote shop checkout experience to RevCent fulfillment/shipping execution.

Without proper mapping:

- a customer may select a shipping method in WooCommerce,
- RevCent may not know which carrier/provider method it corresponds to,
- fulfillment may not use the correct shipping service,
- shipments may fail or route incorrectly,
- tracking/provider data may be incomplete,
- support teams may have less reliable shipment context,
- fulfillment integrations may not receive the expected shipping method.

Correct mapping helps ensure:

```text
Remote shop shipping method
    ↓
RevCent third-party shop shipping method mapping
    ↓
RevCent provider + provider method
    ↓
Shipment created with correct shipping context
    ↓
Fulfillment provider receives correct shipping/method information
```

---

## `GetUserShop` Remote Shipping Method Workflow

Recommended workflow for a connected WooCommerce shop:

```text
1. Get or confirm the user shop ID.
2. Call GetUserShop with remote_data: ["shipping_methods"].
3. Review remote_data.shipping_methods.
4. Compare remote shipping methods against user_shop.shipping_methods already saved in RevCent.
5. Map each remote shipping method to the correct RevCent shipping provider and provider method.
6. Use the appropriate shop edit workflow, such as EditUserShop, to save mappings where needed.
7. Verify the shop shipping methods are saved and mapped.
8. Test a Sale/order using each important shipping method.
9. Confirm the resulting shipment uses the expected provider/method.
```

Example request:

```json
{
  "user_shop_id": "XXXXXXXXXXXXXXXXXXXX",
  "remote_data": [
    "shipping_methods"
  ]
}
```

---

## Remote vs Saved Shop Shipping Methods

`GetUserShop` can expose two related concepts:

| Concept | Meaning |
|---|---|
| `remote_data.shipping_methods` | Shipping methods retrieved live from the remote shop, such as WooCommerce. These may not yet be saved or mapped in RevCent. |
| `shipping_methods` | Shipping methods already saved to the RevCent user shop configuration. These should be mapped to RevCent provider/provider method objects. |

AI/MCP clients should compare these sections.

If a remote method exists but is not saved/mapped in RevCent, it should be added through the appropriate user shop edit workflow.

If a saved method exists in RevCent but the remote shop no longer uses it, the AI/MCP client should ask whether it should remain, be disabled, or be updated.

---

## Remote Shipping Method Fields

Remote shipping methods returned by `remote_data.shipping_methods` can include:

| Field | Meaning |
|---|---|
| `id` | Shipping method ID from the third-party shop. Use as the third-party shipping ID when saving/mapping the method in RevCent. |
| `name` | Shipping method name from the remote shop. |
| `description` | Shipping method description from the remote shop. |
| `enabled` | Whether the shipping method is enabled in the remote shop. |

Saved RevCent shop shipping methods can include:

| Field | Meaning |
|---|---|
| `third_party_shipping_id` | The shipping method ID from the third-party shop. Must be accurate to correctly ship remote-shop purchases. |
| `third_party_shipping_name` | Shipping method name from the third-party shop. |
| `method_title` | Shipping method title from the third-party shop. |
| `provider` | RevCent shipping provider mapped to this remote method. |
| `provider_method` | RevCent shipping provider method mapped to this remote method. |

Mapping requires accurate provider/provider method IDs.

Use shipping provider operations, such as `GetShippingProviders` and `GetShippingProvider`, when the AI/MCP client needs to identify the correct provider and provider method.

---

## Third-Party Shop Shipping Setup Checklist

For WooCommerce or other supported third-party shops:

1. Confirm the user shop is connected and enabled.
2. Call `GetUserShop` with `remote_data: ["shipping_methods"]`.
3. Review all remote shipping methods.
4. Identify which methods are enabled in the remote shop.
5. Map each active remote method to the correct RevCent provider.
6. Map each active remote method to the correct RevCent provider method.
7. Save the mapped methods to the RevCent user shop using the appropriate shop edit workflow.
8. Confirm saved `shipping_methods` include the expected `third_party_shipping_id`, provider, and provider method.
9. Confirm shippable products have fulfillment accounts.
10. Confirm Shipping Profiles/rates exist where needed.
11. Test a real or test checkout using each major remote shipping method.
12. Confirm resulting RevCent shipment has correct provider/method/tracking behavior.

---

## Third-Party Shop Shipping Mistakes to Avoid

Do not:

- assume WooCommerce shipping methods are automatically mapped correctly,
- ignore `remote_data.shipping_methods` during shop setup,
- use remote shipping method names without preserving the remote method ID,
- map a remote method to the wrong RevCent provider,
- map a remote method to the wrong provider method,
- leave active remote shop shipping methods unmapped,
- forget to test each major shipping method after mapping,
- confuse third-party shop shipping method mapping with Shipping Profile rates,
- create shippable products from remote shop products without assigning the correct Fulfillment Account.

The remote shop shipping method controls what the customer selected at checkout. RevCent provider/provider method mapping controls how RevCent understands and routes that shipping choice.

---

## Fulfillment Lifecycle

Typical lifecycle:

```text
Product created as shippable
    ↓
Fulfillment Account created and enabled
    ↓
Shipping Profile created with rates/qualifiers
    ↓
Customer buys product or renewal/trial event occurs
    ↓
Sale/Product Sale created
    ↓
Shipment created
    ↓
RevCent automatically notifies fulfillment account
    ↓
Provider ships package
    ↓
Tracking number and URL added
    ↓
Shipment marked shipped
    ↓
Customer may be notified
    ↓
Shipment marked delivered
    ↓
Customer may be notified
    ↓
Shipment is available for support, metrics, refunds, and reporting
```

---

## Shipment Statuses

Known `shipping_status` values include:

```text
Shipped
Not Shipped
Merged
Delivered
Error
```

Related fields:

| Field | Meaning |
|---|---|
| `is_shipped` | Shipment has shipped. |
| `is_delivered` | Shipment has delivered. |
| `is_merged` | Shipment was merged with another fulfillment shipment. |
| `is_merged_with` | Shipping ID this shipment was merged with. |

---

## Tracking and Provider Fields

Shipment records can include:

| Field | Purpose |
|---|---|
| `provider` | Shipping provider. |
| `provider_method` | Shipping method. |
| `provider_tracking` | Tracking number. |
| `provider_tracking_url` | Tracking URL. |
| `ship_date_unix` | Date shipped. |
| `provider_delivered_date_unix` | Date delivered. |

These fields help with support, delivery confirmation, refund/chargeback evidence, and customer communication.

---

## Customer Notifications

Shipment records can indicate whether the customer was notified when:

- the item shipped,
- the item was delivered.

This helps support teams understand whether the customer received shipment updates.

---

## RevCent Automatically Notifies Fulfillment

RevCent automatically handles fulfillment notification for shippable products when the Sale lifecycle creates a shipment.

When a shippable product is sold, renewed, or trial-expired in a way that requires shipping, RevCent uses the product’s configured Fulfillment Account to notify the fulfillment provider/account.

This means RevCent already takes care of the core fulfillment handoff.

Common fulfillment-triggering events include:

| Commerce Event | Fulfillment Outcome |
|---|---|
| New order / initial Sale | RevCent creates shipment context and notifies fulfillment for shippable products. |
| Processed pending Sale | RevCent creates shipment context and notifies fulfillment when shippable products are processed. |
| Subscription renewal | RevCent can create recurring shipment/refill context and notify fulfillment for shippable subscription products. |
| Trial expiration | RevCent can create shipment context and notify fulfillment when trial shipping settings require it. |

Conceptual flow:

```text
Shippable product is sold / renewed / trial-expired
    ↓
RevCent creates Sale/Product Sale/shipment context
    ↓
RevCent uses the Product's Fulfillment Account
    ↓
RevCent notifies fulfillment provider/account
    ↓
Fulfillment provider processes shipment
    ↓
RevCent receives tracking/status updates from fulfillment where supported
    ↓
Shipment status, tracking, customer notifications, support, and reporting can use the updated shipment data
```

---

## RevCent Receives Fulfillment Status Updates

RevCent can receive shipment status updates from the fulfillment provider/account after fulfillment has been notified.

Depending on the fulfillment provider/integration and tracking setup, RevCent shipment records may receive updates such as:

- provider,
- provider method,
- tracking number,
- tracking URL,
- shipped status,
- ship date,
- delivery status where delivery visibility is configured,
- fulfillment notification status,
- fulfillment provider/account context.

This means RevCent is not only sending orders to fulfillment. It can also store fulfillment response/status information back on the shipment record.

This is what allows RevCent to power:

- customer shipment notifications,
- delivery notifications where delivery data is available,
- support answers about shipment status,
- AI Assistant shipment review,
- AI Voice Agent shipment-status inquiries,
- Function-based supplemental notifications,
- BigQuery reporting.

---

## Functions and External Fulfillment Notification Are Usually Unnecessary

AI/MCP clients must not suggest a Function or external method as the primary way to notify fulfillment for normal shippable product orders.

RevCent already notifies fulfillment through the configured Fulfillment Account.

Using a Function or external system to separately notify fulfillment is unnecessary for the normal fulfillment handoff and may create duplicate shipments, duplicate warehouse requests, inconsistent status records, or operational confusion.

Correct interpretation:

```text
Core fulfillment notification = RevCent Fulfillment Account
Supplemental/custom automation = Functions, external systems, AI Assistants, Email Templates
```

Use Functions or external systems only when the business needs supplemental workflow, such as:

- notify Slack or an internal operations channel,
- sync shipment data to a CRM or ERP,
- create a support ticket,
- send a custom internal webhook,
- route an exception to a custom dashboard,
- notify a secondary non-fulfillment system,
- add custom logging or metadata,
- handle a provider-specific edge case not covered by the normal fulfillment integration.

Do **not** use Functions/external methods to duplicate the fulfillment-provider notification that RevCent already performs.

---

## Correct Automation Boundary

The correct boundary is:

| Need | Correct Tool |
|---|---|
| Send shippable product order to fulfillment provider | Built-in RevCent Fulfillment Account handling. |
| Receive fulfillment/tracking/status updates | Built-in RevCent fulfillment/shipment update handling, depending on provider/integration. |
| Send customer shipped/delivered email | Email Template. |
| Notify support/ops that a shipment has an issue | Function, Email Template, or AI Assistant. |
| Sync shipment record to CRM/ERP | Function. |
| Review shipment exception and summarize issue | AI Assistant. |
| Answer customer call about shipment status | AI Voice Agent. |
| Report on fulfillment/shipping metrics | BigQueryRunQuery. |

AI/MCP clients should clearly explain that Functions and external systems enhance shipment workflows, but they should not be positioned as required for normal fulfillment notification.

---

## Automating Shipment Events

RevCent shipping is highly useful because shipment records can trigger automated customer communication, internal operations, external integrations, AI review, and customer support workflows.

Shipment-related automation can be built with:

- Email Templates,
- Functions,
- AI Assistants,
- AI Voice Agents.

These tools allow an ecommerce business to move beyond simply creating shipments. The business can automatically notify customers, notify support teams, send data to external systems, answer customer questions, and create post-shipment workflows.

---

## Email Templates for Shipment Notifications

Email Templates are the primary customer-facing automation tool for shipment notifications.

The Email Templates overview includes shipping event triggers such as:

| Email Template Trigger | Common Use |
|---|---|
| Shipping Item Created | Notify warehouse, fulfillment team, or internal operations that a shipment was created. |
| Shipping Item Shipped | Send tracking number and tracking URL to the customer. |
| Shipping Item Delivered | Send delivery confirmation or post-delivery follow-up. |
| Shipping Item Voided | Notify warehouse/support that a shipment was cancelled or should not be fulfilled. |

Shipping-related Email Templates receive Shipping input data. This makes it possible to use Handlebars values from the shipment object, such as customer details, ship-to address, products, tracking number, tracking URL, provider, provider method, and shipping status.

Common customer emails:

```text
Your order has shipped.
Your tracking number is ready.
Your package was delivered.
There was an update to your shipment.
Your shipment was cancelled or changed.
```

Common internal emails:

```text
New shipment created.
Fulfillment provider was not notified.
Shipment status changed to Error.
High-value shipment delivered.
Shipment address changed.
```

Best practices:

- Use Shipping Item Shipped for tracking emails.
- Use Shipping Item Delivered for delivery confirmation when delivery events are available.
- Use clear subject lines that include order/shipment context.
- Include `provider_tracking_url` when available.
- Include support contact information.
- Use Product/Product Group filters when different products need different shipping instructions.
- Use Third Party Shop filters when different shops/brands need different email copy.
- Use Function-generated `custom_data` for dynamic support routing or custom tracking/help content.

Reference:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewEmailTemplate.md
```

---

## Functions for Shipment Automation and External Integrations

Functions are ideal when shipment events need supplemental custom business logic or external system integration beyond RevCent's built-in fulfillment notification.

The Functions overview explains that account-event Functions can run automatically when RevCent account events occur, including shipment events. It also shows shipment event examples such as:

```text
shipping.updated.shipped
```

Functions can be used to:

- notify Slack or Discord when a shipment is created or delayed,
- sync shipment data to an external ERP, CRM, dashboard, or secondary system,
- sync tracking numbers to an external CRM,
- notify a custom support dashboard,
- create webhooks for external operations/support systems,
- receive fulfillment-provider webhook callbacks,
- update external order records when a shipment ships,
- create custom delivery follow-up workflows,
- send internal alerts for `shipping_status = Error`,
- route shipment events by product group, shop, country, provider, or fulfillment account,
- generate custom data for shipment Email Templates.

Correct event-driven external pattern:

```text
Shipment event occurs
    ↓
RevCent account-event Function runs
    ↓
Function receives event.data.item_id and event.data.item_details
    ↓
Function sends HTTP POST to external system
    ↓
External system stores shipping_id and event_id
    ↓
External system uses targeted lookup such as GetShipment only when needed
```

External systems should not poll `GetShipments` or `SearchShipping` to discover new or updated shipments. Use Functions/account events for supplemental notifications and BigQuery for reporting. Do not use external polling or duplicate Function workflows to replace RevCent's built-in fulfillment notification.

Reference:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewFunction.md
```

---

## AI Assistants for Shipment Review and Support Automation

AI Assistants can automate reasoning-based shipment workflows.

AI Assistants are useful when the workflow requires judgment, summarization, branching, or a customer-support-style response.

Shipment-related AI Assistant use cases:

| Use Case | Example |
|---|---|
| Late shipment review | Review shipments still `Not Shipped` after X days and create an AI Memo. |
| Shipment error review | Analyze `shipping_status = Error` and notify operations. |
| Customer support summary | Summarize shipment status, product details, tracking, and fulfillment account for a support rep. |
| Post-shipment follow-up | Trigger a customer email after shipped/delivered status. |
| Delivery issue escalation | Review delivered shipments with customer complaints and create a note or memo. |
| Subscription refill monitoring | Review recurring subscription shipments for fulfillment delays. |
| Trial shipment monitoring | Review trial-related shipments based on trial shipping behavior. |
| Fulfillment failure routing | Branch based on provider, fulfillment account, country, product group, or metadata. |
| External workflow control | Trigger a Function to send shipment context to a third-party system. |

Useful AI Assistant event concepts include shipment-created or shipment-updated events, such as shipped events. The AI Assistant overview includes `shipping.updated.shipped` as an event example.

Recommended AI Assistant pattern:

```text
Shipment event occurs
    ↓
AI Assistant starts, optionally after event delay
    ↓
Assistant retrieves/reviews shipment context
    ↓
Assistant checks status, tracking, provider, fulfillment account, ship-to, products, and customer
    ↓
Assistant branches:
        - tracking available → send/update customer message
        - fulfillment not notified → create AI Memo or trigger Function
        - shipment error → notify operations
        - delivery issue → escalate to support
    ↓
Assistant records outcome with note, memo, metadata, Function, or email
```

Best practices:

- Use event filters to limit AI runs to relevant shipping statuses.
- Use Product/Product Group/campaign/shop filters where appropriate.
- Use max-runs-per-item to prevent repeated runs on the same shipment.
- Use event delay when tracking details may arrive shortly after shipment creation.
- Use AI Memos for urgent fulfillment issues.
- Use Functions for external API calls instead of asking the AI to manage integration details directly.
- Use BigQuery to report on AI-driven shipment outcomes.

Reference:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md
```

---

## AI Voice Agents for Shipment Status and Customer Support

AI Voice Agents can help ecommerce businesses handle shipment-related customer support.

Common voice-agent use cases:

- Customer asks, “Where is my order?”
- Customer asks for a tracking number.
- Customer asks if an item has shipped.
- Customer asks whether a package was delivered.
- Customer says the package was not received.
- Customer wants to correct a shipping address before fulfillment.
- Customer wants a support update about a delayed shipment.
- Business wants an outbound call for a high-value delivery issue or failed fulfillment event.

An AI Voice Agent can be configured to use shipment-related tools and workflows, such as:

- searching for a shipment,
- retrieving a shipment,
- reading tracking information,
- explaining the current shipment status,
- confirming ship-to details,
- routing to support,
- creating notes,
- triggering a Function,
- sending an Email Template follow-up,
- escalating unresolved delivery issues.

Recommended voice-agent shipment support flow:

```text
Customer calls or outbound workflow starts
    ↓
Voice Agent verifies customer identity
    ↓
Voice Agent searches/retrieves shipment
    ↓
Voice Agent explains status:
        - Not Shipped
        - Shipped
        - Delivered
        - Merged
        - Error
    ↓
If tracking exists, provide tracking number/URL
    ↓
If issue exists, create support note, trigger Function, or escalate
    ↓
If needed, send follow-up Email Template
```

Important guidance:

- Voice Agents should not invent shipment status.
- If tracking is missing, say it is not available yet.
- If delivery visibility is not configured, do not claim delivered status is known.
- If a ship-to address change is requested, only update it through approved workflows and before fulfillment when applicable.
- If the shipment has an Error status or fulfillment was not notified, escalate to support or operations.
- Use Functions for custom external support ticket creation.
- Use Email Templates for written tracking follow-up.

Reference:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md
```

---

## Delivery Notifications and Delivery Visibility

Shipment shipped notifications and shipment delivered notifications are different.

A tracking number/tracking URL usually comes from the fulfillment provider through the Fulfillment Account. Delivery-level visibility may require additional delivery tracking integration.

The Fulfillment overview notes that delivery-specific updates, such as knowing when a package was delivered, require an EasyPost or Shippo third-party integration if the user wants delivery visibility in RevCent.

AI/MCP guidance:

```text
Tracking number available ≠ delivery confirmed.
```

Use delivery notifications only when RevCent has delivery status available.

If delivery visibility is configured, businesses can automate:

- delivered email confirmations,
- post-delivery satisfaction requests,
- review requests,
- AI Assistant post-delivery workflows,
- support follow-up,
- product-not-received investigation,
- chargeback evidence workflows,
- BigQuery delivery reporting.

Reference:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewFulfillment.md
```

---

## Customer Support Inquiries About Shipment Status

RevCent shipment records are valuable for support because they connect product, customer, Sale, fulfillment, tracking, and status in one record.

A support workflow can use:

| Tool / Feature | Support Use |
|---|---|
| `SearchShipping` | Find shipment by customer name/email/search term. |
| `GetShipment` | Retrieve exact shipment status and tracking details. |
| `EditShipment` | Correct ship-to address or update tracking/status when appropriate. |
| Email Templates | Send written follow-up or tracking details. |
| AI Assistants | Summarize shipment issue or create AI Memo. |
| AI Voice Agents | Answer customer questions by phone. |
| Functions | Create external support tickets or notify operations. |
| BigQuery | Analyze support patterns and fulfillment performance. |

Recommended support workflow:

```text
Customer asks about shipment
    ↓
SearchShipping or GetShipment
    ↓
Review shipping_status, tracking, ship_to, products, fulfillment notification
    ↓
Answer customer or escalate
    ↓
Send Email Template follow-up if needed
    ↓
Create note/memo/ticket using AI Assistant or Function
```

This reduces support time and improves customer experience.

---

## Fulfillment Notification

Shipment records include fulfillment notification fields:

| Field | Meaning |
|---|---|
| `fulfillment_account` | Fulfillment account associated with the shipment. |
| `fulfillment_account_notified` | Whether the fulfillment provider was notified. |
| `fulfillment_account_notified_date` | Date fulfillment was notified. |

This is critical for troubleshooting. A Sale may be paid, but if fulfillment was not notified, the product may not ship.

---

## Editing Shipments

Use `EditShipment` to update a specific shipment.

Required:

| Field | Required |
|---|---:|
| `shipping_id` | Yes |

Optional editable fields:

| Field | Purpose |
|---|---|
| `provider` | Shipping provider. |
| `provider_method` | Shipping method. |
| `provider_tracking` | Tracking number. |
| `shipped` | Mark shipment shipped. |
| `delivered` | Mark shipment delivered. |
| `ship_to` | Update shipping destination. |

Important:

```text
Changes to the ship-to address will be updated at fulfillment where applicable.
```

Example:

```json
{
  "shipping_id": "XXXXXXXXXXXXXXXXXXXX",
  "provider": "USPS",
  "provider_method": "Priority",
  "provider_tracking": "9400111899223857420000",
  "shipped": true
}
```

---

## Retrieving and Searching Shipments

### `GetShipment`

Use when the shipping ID is known.

Use cases:

- support asks about one shipment,
- check tracking,
- check if fulfillment was notified,
- check shipped/delivered status,
- inspect related Sale/Product Sale IDs.

### `GetShipments`

Use for small bounded operational lists.

Required inputs:

| Field | Purpose |
|---|---|
| `date_start` | Start date Unix timestamp. |
| `date_end` | End date Unix timestamp. |
| `limit` | 1 to 25. |
| `page` | Pagination page. |

Optional filters include campaign, currency, shop, shipping status, provider, fulfillment account, metadata, and customer ID.

Important:

```text
Do not use GetShipments for reporting, metrics, aggregation, bulk retrieval, or data mining.
Use BigQueryRunQuery instead.
```

### `SearchShipping`

Use when the user has a search term but not a shipping ID.

Example:

```json
{
  "search_term": "jane@example.com"
}
```

Use for support lookup, customer email/name search, metadata search, or quick operational search.

Do not use `SearchShipping` for bulk discovery or reporting.

---

## Reporting and Metrics

Use `BigQueryRunQuery` for shipping metrics.

Do not use `GetShipments` or `SearchShipping` for reporting.

Useful reports:

- shipments by date,
- shipments by status,
- shipped vs not shipped,
- delivered vs undelivered,
- fulfillment account performance,
- fulfillment notification success/failure,
- shipping revenue,
- shipping cost and margin,
- subscription shipment performance,
- trial shipment performance,
- shipping by product/product group,
- shipping by campaign/shop,
- shipping by country/state,
- delivery time analysis,
- fulfillment errors,
- customer notification performance.

---

## Setup Checklist

Before selling shippable products:

1. Create or verify Products.
2. Mark physical products as `is_shippable = true`.
3. Add accurate shipping attributes.
4. If using WooCommerce or a third-party shop, retrieve remote shop shipping methods with `GetUserShop` and `remote_data: ["shipping_methods"]`.
5. Map active remote shop shipping methods to RevCent providers/provider methods.
6. Create or verify Fulfillment Account.
5. Ensure Fulfillment Account is enabled before active selling.
6. Create or verify Shipping Profile.
7. Ensure shipping rates have provider/method.
8. Ensure every rate has at least one enabled qualifier.
9. Use Product Groups for cleaner shipping-rate qualification where appropriate.
10. Configure trial shipping behavior if the product has trial settings.
11. Configure subscription profile if product renews.
12. Test Sale/pending Sale/trial/subscription behavior.
13. Verify shipment record creation.
14. Verify fulfillment provider notification.
15. Verify RevCent automatically notified the configured Fulfillment Account.
16. Verify tracking/status update workflow.
17. Do not create a separate Function/external fulfillment notification unless it is supplemental and will not duplicate RevCent's built-in fulfillment notification.
16. Create Email Templates for shipment shipped and delivered notifications.
17. Configure Functions for external fulfillment/support notifications where needed.
18. Configure AI Assistants for shipment exceptions, fulfillment errors, and support summaries where useful.
19. Configure AI Voice Agents for shipment-status support if the business wants phone automation.
20. Use BigQuery reporting for operational monitoring.

---

## Common Mistakes to Avoid

Do not:

- sell a shippable product without a valid Fulfillment Account,
- assign live products to a disabled Fulfillment Account,
- ask users to paste fulfillment credentials in chat,
- create a Fulfillment Account without secure credential collection,
- create a Shipping Profile rate with no enabled qualifier,
- forget Product Groups can simplify shipping rules,
- assume every trial product ships immediately,
- forget subscription renewals may require recurring shipments,
- use `GetShipments` for reporting,
- use `SearchShipping` for bulk discovery,
- update ship-to address without understanding it may update fulfillment where applicable,
- forget to verify whether fulfillment was notified,
- treat shipments as simple labels instead of first-class fulfillment records,
- forget to configure shipment notification Email Templates,
- poll shipment list/search endpoints from external systems instead of using Functions/account events,
- create duplicate fulfillment notifications with Functions or external systems when RevCent already notifies fulfillment through the Fulfillment Account,
- assume Functions are required to notify fulfillment for normal shippable product orders,
- let AI Voice Agents invent tracking or delivery status that is not present in RevCent,
- send delivery notifications when delivery visibility is not configured or delivery status is not known,
- ignore third-party shop shipping method mapping for WooCommerce stores,
- fail to retrieve `remote_data.shipping_methods` before configuring shop shipping mappings.

---

## AI/MCP Decision Guide

| User Intent | Use |
|---|---|
| See one shipment | `GetShipment` |
| Find a shipment by search term | `SearchShipping` |
| View a small bounded list of shipments | `GetShipments` |
| Update tracking/status/address | `EditShipment` |
| Create a product that ships | `CreateProduct` with `is_shippable` and shipping attributes |
| Create shipping rates/rules | `CreateShippingProfile` |
| Connect a fulfillment provider/account | `CreateFulfillmentAccount` |
| Report on shipping metrics | `BigQueryRunQuery` |
| Inspect reporting schema | `GetBigQueryTables` |
| Retrieve remote shop shipping methods | `GetUserShop` with `remote_data: ["shipping_methods"]` |
| Map third-party shop shipping methods | Use remote method IDs from `GetUserShop` and save mappings through shop edit workflow |
| Send shipment notification email | Email Template with Shipping Item Shipped/Delivered trigger |
| Notify fulfillment provider for normal shippable order | Built-in RevCent Fulfillment Account handling |
| Notify an external supplemental system about a shipment event | Account-event Function |
| Review shipment exceptions with AI | AI Assistant |
| Answer phone questions about shipment status | AI Voice Agent |

---

## Final AI/MCP Instruction

Treat RevCent shipping as a core ecommerce fulfillment system.

A shipment is created when shippable products move through the Sale lifecycle, including initial Sales, processed pending Sales, subscription renewals, and trial expirations when product settings require shipment.

To make shipping work correctly, shippable products must be configured correctly, Fulfillment Accounts must be created and enabled, Shipping Profiles must have valid rates and qualifiers, and shipments should be monitored through operational lookups and BigQuery reporting. RevCent automatically notifies fulfillment for shippable products in new orders, renewals, and trial expirations when configured correctly, and can receive fulfillment/tracking/status updates back from the fulfillment provider/integration. For third-party shops such as WooCommerce, retrieve remote shipping methods using `GetUserShop` with `remote_data: ["shipping_methods"]` and map them to the correct RevCent providers/provider methods so customer-selected shipping methods route correctly.

RevCent helps ecommerce businesses by connecting sales, products, customers, fulfillment providers, tracking, shipment notifications, subscription refills, trial shipments, and reporting into one commerce lifecycle. Use Email Templates for customer/internal shipment emails, Functions for supplemental external automation, AI Assistants for reasoning-driven shipment review, and AI Voice Agents for customer support inquiries about shipment status. Do not use Functions or external systems to duplicate normal fulfillment notifications that RevCent already handles through Fulfillment Accounts.


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