# RevCent MCP Guide: `EditShipment` AI/MCP-focused guide for the RevCent `EditShipment` operation. --- ## Operation Summary Operation: ```text EditShipment ``` Purpose: ```text Edit the details of a specific Shipment using the Shipment / Shipping ID. ``` Important live-operation behavior: ```text Changes to the ship-to address will be updated at fulfillment where applicable. ``` Use `EditShipment` when the user needs to update an existing RevCent Shipment record, such as tracking details, shipped/delivered state, provider/method details, or ship-to destination details. --- ## Related Documentation | Guide | Link | Why It Matters | |---|---|---| | Shipping Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShipping.md` | Explains shipments, fulfillment lifecycle, shipping profiles, WooCommerce shipping method mapping, AI, voice, and email automation. | | Fulfillment Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewFulfillment.md` | Explains fulfillment accounts, provider integrations, credentials, and fulfillment status updates. | | GetShipment | `https://revcent.com/documentation/markdown/mcp/operation/GetShipment.md` | Retrieve the Shipment before and after editing. | | GetShipments | `https://revcent.com/documentation/markdown/mcp/operation/GetShipments.md` | Bounded operational retrieval when Shipment ID is unknown. Not for reporting. | | SearchShipping | `https://revcent.com/documentation/markdown/mcp/operation/SearchShipping.md` | Search for a Shipment when the Shipment ID is unknown, then retrieve with `GetShipment`. | | RefundShipment | `https://revcent.com/documentation/markdown/mcp/operation/RefundShipment.md` | Refund the shipping/shipment amount. | | Email Template Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewEmailTemplate.md` | Shipment shipped/delivered notifications can be handled by Email Templates. | | AI Assistant Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md` | AI Assistants can monitor shipment changes and support automation. | | AI Voice Agent Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIVoiceAgent.md` | AI Voice Agents can support customer shipment questions. | | BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct operation for shipment reporting, metrics, aggregation, and data mining. | --- ## When to Use Use `EditShipment` when the user wants to update a specific Shipment. Common reasons: - add or update tracking number, - add or update tracking URL, - update shipping provider, - update provider method / shipping method, - mark a Shipment as shipped, - mark a Shipment as delivered, - correct shipped or delivered status, - update ship-to name, email, phone, or address, - correct fulfillment/shipping details before or during fulfillment, - fix shipment details after support review. Example user intent: ```text Add the tracking number to this shipment. Mark this shipment as shipped. Mark this shipment as delivered. Update the ship-to address before fulfillment. Correct the shipping provider/method. ``` --- ## When Not to Use Do not use `EditShipment` when another operation matches the task better. | User Intent | Correct Operation | |---|---| | Retrieve one Shipment | `GetShipment` | | Find a Shipment when ID is unknown | `SearchShipping`, then `GetShipment` | | Retrieve a bounded operational list | `GetShipments` | | Refund shipping amount | `RefundShipment` | | Refund a Product Sale | `RefundProductSale` | | Refund Tax | `RefundTax` | | Refund raw credit-card funds | `RefundTransaction` | | Update product shipping configuration | `EditProduct` | | Update Shipping Profile/rates | `EditShippingProfile` | | Update Fulfillment Account credentials/settings | `EditFulfillmentAccount` | | Shipment reporting / metrics / analytics | `BigQueryRunQuery` | Do not use `EditShipment` for reporting, metrics, aggregation, data mining, or broad analysis. --- ## Required Field `EditShipment` requires the Shipment / Shipping ID. | Field | Type | Required | Description | |---|---:|---:|---| | `shipping_id` | string | Yes | 20-character Shipment / Shipping ID. | Example minimal shape: ```json { "shipping_id": "SSSSSSSSSSSSSSSSSSSS" } ``` In practice, include at least one editable field in addition to `shipping_id`. --- ## Editable Areas The live operation documentation describes `EditShipment` as supporting edits to: - tracking, - shipped/delivered status, - provider/method, - ship-to details. AI/MCP clients should follow the exact field names exposed by the live MCP schema. Conceptually editable areas include: | Area | Typical Purpose | |---|---| | Tracking details | Tracking number and/or tracking URL. | | Provider details | Shipping provider and provider method. | | Shipment status | Shipped or delivered state. | | Ship-to details | Recipient name, email, phone, and address. | | Fulfillment-facing details | Address changes may be updated at fulfillment where applicable. | --- --- ## `notify_customer` Guidance `notify_customer` should almost always be: ```json { "notify_customer": false } ``` unless the user explicitly instructs AI/MCP to notify the customer. Default recommendation: ```text Do not notify the customer from EditShipment unless explicitly told to do so. ``` Reason: ```text EditShipment is mainly for correcting or updating shipment details, especially ship-to address updates. ``` RevCent has separate customer notification workflows through Email Templates, shipment status triggers, AI Assistants, AI Voice Agents, and other configured automation. Accidentally setting `notify_customer = true` during a simple address correction or internal shipment update can create unnecessary or confusing customer notifications. Use `notify_customer = true` only when: - the user explicitly asks to notify the customer, - the edit is intended to trigger a customer-facing shipment update, - the business workflow requires customer notification, - the AI/MCP client has confirmed the edited details are accurate and safe to send. When in doubt: ```text notify_customer = false ``` ## Tracking Updates Use tracking-related fields when the shipment has a tracking number or tracking URL that should be saved in RevCent. Example conceptual request: ```json { "shipping_id": "SSSSSSSSSSSSSSSSSSSS", "tracking_number": "1Z999AA10123456784", "tracking_url": "https://carrier.example/track/1Z999AA10123456784" } ``` Use the exact field names from the live schema. After updating tracking: ```text GetShipment ↓ Confirm tracking number / tracking URL saved correctly ``` Depending on account configuration, shipment tracking updates may also support customer notification workflows through Email Templates, AI Assistants, Functions, or Voice Agents. --- ## Provider / Method Updates Use provider/method fields when the shipment should reflect the correct carrier or shipping service. Examples: ```text UPS Ground FedEx 2Day USPS Priority Mail DHL Express ``` Provider/method edits may be important when: - a fulfillment provider returns tracking details, - a remote shop method was mapped incorrectly, - manual fulfillment used a different carrier, - support needs the shipment record to match the actual shipping method. If the Shipment came from WooCommerce or another third-party shop, verify that remote shop shipping method mapping is correct in the User Shop configuration. Do not use `EditShipment` as the long-term fix for incorrect shop shipping method mapping. --- ## Shipped Status Updates Use shipped-status fields when the Shipment has actually shipped. Before marking shipped, confirm: - the correct Shipment, - tracking number if available, - provider/method if available, - ship-to details, - whether customer should be notified, - whether fulfillment already updated the shipment automatically. Do not mark a Shipment as shipped unless it has actually shipped or the business explicitly wants that status reflected. Recommended workflow: ```text GetShipment ↓ Confirm shipment and customer/order context ↓ EditShipment with shipped status/tracking details ↓ GetShipment to verify ↓ Customer/internal notification if appropriate ``` --- ## Delivered Status Updates Use delivered-status fields when the Shipment has actually been delivered. Before marking delivered, confirm: - the correct Shipment, - carrier delivery confirmation, - delivered date/time if applicable, - whether customer should be notified, - whether fulfillment/carrier already updated delivery automatically. Do not mark a Shipment as delivered unless delivery is confirmed or the business explicitly wants that status reflected. --- ## Ship-To Address Updates Use ship-to fields when the recipient or delivery address needs correction. Important live-operation behavior: ```text Changes to the ship-to address will be updated at fulfillment where applicable. ``` This means RevCent may attempt to push the changed address to the fulfillment provider when supported and applicable. Primary use case: ```text EditShipment is mainly intended for shipment corrections such as ship-to address updates. ``` When the ship-to address is updated, RevCent will notify the appropriate fulfillment center where applicable. This should affect the shipping destination unless the package has already shipped or the fulfillment provider/carrier can no longer accept address changes. However, AI/MCP should not assume every fulfillment provider or every fulfillment state can accept address updates. Before changing ship-to details, verify: - shipment is the correct one, - customer/order relationship is verified, - shipment has not already shipped if address affects delivery, - fulfillment provider can still accept changes where applicable, - user/customer confirmed the corrected address, - the correction is safe to push to fulfillment. If the shipment has already shipped, changing the address in RevCent may not change the carrier delivery destination. --- ## Fulfillment Update Warning Address changes may be updated at fulfillment where applicable, but there are practical constraints. AI/MCP should be careful when editing a shipment that has already been: - sent to fulfillment, - picked/packed, - shipped, - assigned a tracking number, - delivered. Recommended warning: ```text This shipment may already be in fulfillment. Address changes will be updated at fulfillment where applicable, but may not be accepted if the provider has already processed or shipped the order. ``` Use `GetShipment` before editing to inspect fulfillment notified status, shipped state, delivered state, tracking, and related fulfillment context. --- ## Recommended Workflow ```text 1. If Shipment ID is unknown, use SearchShipping or GetShipments for operational lookup. 2. Use GetShipment to retrieve the exact Shipment. 3. Verify the customer/order/shipment context. 4. Confirm the exact fields that should change. 5. If public/customer-facing, verify customer identity with a secondary value from the retrieved Shipment. 6. If editing address, confirm fulfillment/shipped state and warn about provider limitations. 7. Call EditShipment with only intended fields, and set `notify_customer = false` unless the user explicitly requested customer notification. 8. Use GetShipment again to verify the edit. 9. Trigger or confirm customer/internal notification if appropriate. ``` --- ## Partial Edit Guidance Treat `EditShipment` as a targeted edit operation. Best practice: ```text Only include the fields that should change. ``` Do not send unchanged fields unless the schema requires them. Do not include `notify_customer = true` unless explicitly requested. Use `notify_customer = false` for normal internal shipment/address edits. This avoids accidentally overwriting correct shipment data or notifying customers unintentionally. --- ## Customer-Facing AI Verification Warning Shipment records can expose sensitive customer/order/address/tracking details. If `EditShipment` 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 making changes. Recommended rule: ```text Do not edit a Shipment based only on a visitor-provided Shipment ID, tracking number, name, address, or search term. ``` Safe flow: ```text Visitor provides shipment/search input ↓ AI uses SearchShipping and/or GetShipment ↓ AI retrieves the Shipment ↓ AI verifies a secondary value from the retrieved Shipment record such as customer email or phone ↓ Only after verification: provide limited appropriate details or perform an allowed edit after confirmation ``` Important: ```text The secondary verification value should come from the retrieved RevCent record, not only from the visitor's original input. ``` For example, if a visitor provides a tracking number, verify against the customer email returned by `GetShipment` before discussing or changing the Shipment. For consequential actions, such as changing a delivery address, marking shipped/delivered, or changing tracking details, require explicit confirmation. --- ## Reporting Rule `EditShipment` is not a reporting operation. Do not use shipment mutation or lookup operations for: - shipping metrics, - delivery-rate reports, - fulfillment performance reports, - shipment refund reports, - provider/method performance reports, - campaign/shop/product shipping analytics, - bulk export, - data mining. Use: ```text BigQueryRunQuery ``` for shipment reporting, metrics, aggregation, and analysis. If AI/MCP initially intended to use shipment lookup operations for reporting and realizes BigQuery is correct, it should simply use `BigQueryRunQuery` instead without explaining the correction to the user. --- ## Common Examples ### Add Tracking Number ```json { "shipping_id": "SSSSSSSSSSSSSSSSSSSS", "tracking_number": "1Z999AA10123456784", "notify_customer": false } ``` Use exact live-schema field names. --- ### Mark Shipped With Tracking ```json { "shipping_id": "SSSSSSSSSSSSSSSSSSSS", "tracking_number": "1Z999AA10123456784", "shipped": true, "notify_customer": false } ``` Use exact live-schema field names. --- ### Mark Delivered ```json { "shipping_id": "SSSSSSSSSSSSSSSSSSSS", "delivered": true, "notify_customer": false } ``` Use exact live-schema field names. --- ### Update Ship-To Details ```json { "shipping_id": "SSSSSSSSSSSSSSSSSSSS", "ship_to_address_line_1": "123 New Street", "ship_to_city": "Miami", "ship_to_state": "FL", "ship_to_zip": "33101", "ship_to_country": "USA", "notify_customer": false } ``` Use exact live-schema field names. Address changes may be pushed to fulfillment where applicable. --- --- ### Notify Customer Only When Explicitly Requested Only set `notify_customer = true` when the user explicitly asks to notify the customer. ```json { "shipping_id": "SSSSSSSSSSSSSSSSSSSS", "tracking_number": "1Z999AA10123456784", "notify_customer": true } ``` Do not use this for normal address corrections or internal shipment edits. ## Pre-Edit Checklist Before calling `EditShipment`, confirm: - correct Shipment / Shipping ID, - current Shipment was retrieved with `GetShipment`, - customer/order relationship is verified where needed, - user explicitly confirmed the edit, - only intended fields are included, - address changes are still possible if fulfillment/shipping has started, - tracking/provider/method changes match actual carrier data, - shipped/delivered status reflects reality, - whether `notify_customer` should remain false; it should be true only with explicit user instruction, - the edit is not being used as a workaround for bad Product, Shipping Profile, Fulfillment Account, or User Shop mapping configuration. --- ## Best Practices 1. Always retrieve the Shipment with `GetShipment` before editing. 2. Edit only fields that should change. 3. Verify customer identity in customer-facing AI flows. 4. Require explicit confirmation before changing address, tracking, or delivery status. 5. Be careful editing address after fulfillment has been notified. 6. Do not mark shipped or delivered unless accurate. 7. Use `RefundShipment` for shipping refunds. 8. Use `EditShippingProfile` for rate/rule changes. 9. Use `EditFulfillmentAccount` for fulfillment account configuration changes. 10. Use `BigQueryRunQuery` for reporting and analytics. 11. Retrieve the Shipment again after editing to verify the result. 12. Keep `notify_customer = false` unless the user explicitly tells AI/MCP to notify the customer. 13. Treat address updates as the primary/common use case for `EditShipment`. 14. Remember RevCent notifies the appropriate fulfillment center about address changes where applicable. 15. Address changes should affect the destination unless the package already shipped or fulfillment/carrier can no longer accept changes. --- ## Common Mistakes to Avoid Do not: - set `notify_customer = true` without explicit instruction, - notify the customer during routine address/internal shipment corrections, - assume an address update can change delivery destination after the package has already shipped, - edit a Shipment without retrieving it first, - edit based only on public visitor input, - disclose address/tracking details without customer verification, - change an address after shipping without warning about provider limitations, - mark a Shipment shipped/delivered without confirmation, - use `EditShipment` to fix long-term shipping method mapping problems, - use `EditShipment` to refund shipping, - use `EditShipment` for reporting or metrics, - send unrelated unchanged fields that could overwrite correct data. --- ## Final AI/MCP Instruction Use `EditShipment` to update a specific Shipment by `shipping_id`. It is especially useful for ship-to address updates. RevCent will notify the appropriate fulfillment center about address changes where applicable, which should affect the shipping destination unless the package has already shipped or the fulfillment provider/carrier can no longer accept changes. `notify_customer` should almost always be `false` unless the user explicitly instructs AI/MCP to notify the customer. Always retrieve with `GetShipment` before editing, verify customer relationship in public-facing flows, edit only intended fields, and retrieve again after editing to confirm the result. --- 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.