# RevCent MCP Overview: Shipping Providers AI/MCP-focused overview of Shipping Providers in RevCent. --- ## Purpose This guide explains what Shipping Providers are in RevCent, how they relate to Shipping Profiles, Shipping Rates, shipments, fulfillment, and shipping-method mapping, and how AI/MCP clients should use the `GetSiteShippingProviders` and `GetSiteShippingProvider` operations. Shipping Providers are RevCent's static carrier/method mapping list. They identify the valid shipping carriers and carrier methods RevCent can use when creating shipping rates, mapping imported shop shipping methods, creating shipment entries, and sending fulfillment or shipment context. --- ## Source Documentation Read This overview incorporates the relevant behavior from: ```text https://kb.revcent.com/en/revenue/shipping https://kb.revcent.com/en/revenue/shipping#shipping-methods ``` Key KB points reflected in this guide: ```text RevCent contains shipping methods for several providers based on the 3PL Central carrier list. If a provider or provider method is missing, the user should contact RevCent to add it. When creating a sale through the API, AI/MCP should specify the RevCent Provider ID as the provider property. AI/MCP should specify the RevCent Method ID as the provider_method property for shipment entries. AI/MCP should not use external fulfillment codes or external fulfillment codes as provider_method values. ``` --- ## Core Concept A **Shipping Provider** is a RevCent-supported shipping carrier or carrier category. A **Shipping Provider Method** is a delivery service/method under a provider. Simple model: ```text Shipping Provider = carrier Shipping Provider Method = carrier service / delivery method ``` Examples: ```text USPS → Priority Mail UPS → UPS Ground FedEx → FedEx 2Day DHL → Express Worldwide 3PL Central Default → Ground / LTL / FTL ``` Shipping Providers and Shipping Provider Methods are static RevCent site-level mappings. They are not normally created by users. AI/MCP should not attempt to invent or create new providers or methods. If the needed provider or method does not exist: ```text Tell the user to contact RevCent to have the provider or provider method added. ``` --- ## AI/MCP Provider Method Rule AI/MCP should use only RevCent provider IDs and RevCent method IDs when setting or mapping shipping providers/methods. Required mapping shape: ```text provider = RevCent Provider ID provider_method = RevCent Method ID ``` AI/MCP should not use external fulfillment codes, carrier service codes, fulfillment-provider-specific codes, or display names as `provider_method` values. --- ## Provider and Method IDs Shipping methods in RevCent are identified by RevCent provider and method IDs. For shipment entries, AI/MCP should use: ```text provider = RevCent Provider ID provider_method = RevCent Method ID ``` Important: ```text AI/MCP should use provider ID and method ID only. ``` Do not use: ```text external fulfillment codes external fulfillment service codes carrier-specific service codes display names when an ID is required ``` The RevCent Method ID is returned by `GetSiteShippingProvider` in the provider's method option list. --- ## How Shipping Providers Are Used Shipping Providers and Provider Methods are used in several RevCent workflows: ```text Shipping Profile rate setup Shipping Profile rate matching CreateSale shipment entries CreatePendingSale / UpdatePendingSale shipment context WooCommerce shipping method mapping Custom store shipping method mapping Fulfillment account handoff Shipment tracking context AI/MCP onboarding workflows ``` They are especially important when mapping a business/store shipping option to the RevCent carrier/method that should be saved or sent downstream. --- ## Relationship to Shipping Profiles A Shipping Profile is a collection of shipping rates, providers, and rules. The KB explains: ```text A shipping profile contains rates. Each rate contains the provider, provider method, cost, customer rate, and rules. ``` When a shippable purchase, trial expiration, or subscription renewal needs shipping, RevCent compares Shipping Profile rates to the purchase and uses matching rates to determine: ```text shipping price shipping provider shipping provider method ``` Important: ```text A Shipping Profile rate must include a valid Shipping Provider and valid Provider Method. ``` --- ## Shipping Profile Rate Matching Shipping Profile rates can include rules based on: ```text products product groups revenue country restrictions ``` Important KB behavior: ```text All rules within a rate must pass for the rate to be considered valid. At least one rule must exist throughout the rate. If multiple rates match, RevCent uses the most profitable rate. ``` The provider/provider method in the matching rate becomes the shipping provider/method used for the resulting shipping entry. --- ## WooCommerce Initial Sale Distinction For an initial sale coming from WooCommerce, RevCent does not use Shipping Profiles to calculate initial checkout shipping. Instead: ```text RevCent accepts what WooCommerce calculated for shipping at time of purchase. ``` However, Shipping Profiles remain important for: ```text trial expirations subscription renewals future shipments created by RevCent ``` For WooCommerce imports/mapping, AI/MCP may still need to map WooCommerce shipping methods to RevCent Shipping Providers and Provider Methods so RevCent understands the carrier/method context. --- ## Trial and Subscription Importance Shipping Profiles are essential for trial and subscription-based shippable products. Important KB behavior: ```text RevCent must find at least one applicable rate within applicable Shipping Profiles to create a shipping entry for trial expirations and subscription renewals. If no matching rate is found, RevCent will not create a shipping entry and the product will not ship to the customer. ``` Because rates rely on valid providers and provider methods, Shipping Provider mapping is important for recurring and delayed shipment workflows. --- ## Related MCP Operations | Operation | Purpose | |---|---| | `GetSiteShippingProviders` | Retrieve the static list of RevCent-supported shipping providers/carriers. Does not include individual delivery options. | | `GetSiteShippingProvider` | Retrieve one provider and its domestic/international provider method options. | | `CreateShippingProfile` | Create Shipping Profiles that use provider/provider method rates. | | `EditShippingProfile` | Edit Shipping Profiles and their rates. | | `GetShippingProfile` | Inspect a Shipping Profile and its rate/provider/method configuration. | | `GetShippingProfiles` | List Shipping Profiles. | | `CreateSale` | Can include shipment entries where provider and provider_method may be specified. | | `CreatePendingSale` / `UpdatePendingSale` | Can include/update pending sale shipment context before processing. | | `GetShipment` | Retrieve resulting shipment details. | | `EditShipment` | Edit shipment details such as tracking number and shipped/delivered state. | | `GetUserShop` / `EditUserShop` | Used when mapping WooCommerce/third-party shop shipping methods to RevCent providers/methods. | --- # Operation: `GetSiteShippingProviders` ## Purpose ```text Returns a list of site shipping providers. ``` Use this operation when AI/MCP needs to list or identify the available carrier/provider options. Important: ```text GetSiteShippingProviders does not include individual provider delivery options. ``` To get domestic and international delivery options, call `GetSiteShippingProvider` for a specific provider. ## Input Schema This operation takes no input: ```json {} ``` ## Output Highlights Each provider result can include: ```text id name name_lower ``` Field meanings: | Field | Meaning | |---|---| | `id` | 20-character RevCent site shipping provider ID. | | `name` | Display name of the shipping provider. | | `name_lower` | Lowercase provider name, useful for matching. | Use this operation to find the correct provider before retrieving the provider's methods. --- # Operation: `GetSiteShippingProvider` ## Purpose ```text Retrieve the details of a specific site shipping provider. ``` When retrieving a specific provider, domestic and international package options are included. Use this operation after selecting a provider from `GetSiteShippingProviders`. ## Input Schema Required: ```json { "site_shipping_provider_id": "PPPPPPPPPPPPPPPPPPPP" } ``` The `site_shipping_provider_id` is the 20-character ID returned by `GetSiteShippingProviders`. ## Output Highlights The operation can return: ```text id name name_lower domestic_package_options international_package_options ``` Each method option can include: ```text id display_name identifier ``` Field meanings: | Field | Meaning | |---|---| | `id` | 20-character RevCent site shipping provider method ID. | | `display_name` | Human-readable method name. | | `identifier` | Method identifier/code used by RevCent or integrations. | Domestic options and international options are separated because a provider may support different methods depending on destination. --- ## Provider/Method Matching Workflow When AI/MCP needs to map a user-provided shipping method to RevCent: ```text 1. GetSiteShippingProviders. 2. Compare user-provided carrier/service text to provider names. 3. Select the best provider match if clear. 4. GetSiteShippingProvider for that provider. 5. Compare service/method/speed text to domestic_package_options and international_package_options. 6. Select the best provider method match if clear. 7. If only one clear provider/method match exists, use it. 8. If multiple plausible matches exist, ask the user which one to choose. 9. If no match exists, tell the user RevCent may need to add the provider or provider method. ``` Important: ```text Find the best provider first, then find the best provider method under that provider. ``` Do not ask the user to choose from every provider/method unless necessary. --- ## Matching Inputs AI/MCP Should Consider When matching imported or user-provided shipping methods, consider: ```text carrier name shipping method name shipping zone domestic vs international destination delivery speed service level WooCommerce method ID WooCommerce method title fulfillment system carrier/service text keywords such as Ground, Express, Priority, Overnight, 2 Day, Economy, Standard, Local Pickup, Free Shipping ``` Examples: ```text "UPS Ground" → provider likely UPS, method likely UPS Ground. "FedEx 2Day" → provider likely FedEx, method likely FedEx 2Day. "USPS Priority Mail" → provider likely USPS, method likely Priority Mail. "3PL Ground" → provider may be 3PL Central Default, method should be selected by RevCent method ID. ``` If multiple methods are plausible, ask the user to choose. --- ## WooCommerce Shipping Method Mapping When importing/retrieving WooCommerce shipping methods, AI/MCP should map each WooCommerce method to a RevCent Shipping Provider and Provider Method. Recommended flow: ```text GetUserShop with remote_data.shipping_methods ↓ Review WooCommerce shipping methods returned by the store ↓ GetSiteShippingProviders ↓ Find best provider match for each WooCommerce method ↓ GetSiteShippingProvider for selected provider ↓ Find best provider method match ↓ If only one clear match exists, use it ↓ If multiple plausible matches exist, ask the user which one to choose ↓ Build full shipping_methods mapping array ↓ EditUserShop with shipping_methods ↓ GetUserShop to verify saved mappings ``` Important: ```text When editing shipping_methods on a User Shop, include every shipping method that should remain. ``` Do not provide a partial replacement array unless intentionally removing omitted mappings. --- ## Shipping Profile Rate Setup When creating/editing Shipping Profiles, AI/MCP should use Shipping Providers and Provider Methods carefully. Recommended flow: ```text Ask what carrier/service should be used ↓ GetSiteShippingProviders ↓ Find provider ↓ GetSiteShippingProvider ↓ Find method ↓ Use provider/provider_method in Shipping Profile rate ↓ Configure cost, customer_rate, and rules ``` AI/MCP should not guess provider/provider_method when multiple plausible matches exist. Shipping Profile creation/editing is consequential because failed or incorrect rate matching can prevent shipments from being created or can charge the wrong customer shipping amount. --- ## CreateSale / Shipment Entry Use When sending a Sale Create API call or any workflow that needs shipment provider/method values, AI/MCP should specify: ```text provider = RevCent Provider ID provider_method = RevCent Method ID ``` for shipment entries. AI/MCP should not use external fulfillment codes or external fulfillment-provider codes for `provider_method`. Use the provider ID from `GetSiteShippingProviders` and the method ID from `GetSiteShippingProvider`. --- ## Missing Provider or Method If the provider or provider method does not appear in RevCent's list: ```text Do not invent a provider ID. Do not invent a provider_method. Do not use a close-but-wrong method just to continue. ``` Instead: ```text Tell the user the provider/method is not currently available in RevCent and they should contact RevCent to have it added. ``` For onboarding or external-agent workflows, stop safely if provider/method is required and no clear match exists. --- ## Domestic vs International Options `GetSiteShippingProvider` separates: ```text domestic_package_options international_package_options ``` AI/MCP should consider destination when selecting a method. If the user is mapping a generic method that applies to both domestic and international shipments, AI/MCP may need separate mappings or user clarification. Examples: ```text Domestic "UPS Ground" should not be mapped to an international UPS method. International "DHL Express Worldwide" should not be treated as a domestic-only method. ``` --- ## Relationship to Fulfillment Accounts Shipping Providers and Provider Methods help determine what carrier/service information is attached to a shipment and sent to fulfillment where applicable. If using a fulfillment integration, the provider/method selection may determine: ```text carrier service level warehouse shipping method fulfillment routing shipping label/service expectation ``` AI/MCP should treat fulfillment provider/method mappings as consequential and verify ambiguous choices. Even when the fulfillment provider has its own carrier/service codes, AI/MCP should map to the RevCent provider ID and RevCent method ID. --- ## Relationship to Shipment Tracking Shipping Provider/Method selection is separate from tracking-provider setup, but both relate to shipment context. Important distinction: ```text Shipping Provider/Method = carrier/service used for the shipment. Shipment Tracking Integration = third-party service used to receive delivery updates. ``` A business may ship with USPS/UPS/FedEx/etc. while using EasyPost or Shippo as the tracking service integration. --- ## Human-in-the-Loop Guidance When a human is actively working with AI/MCP, ask for confirmation when: ```text multiple provider matches are plausible multiple method matches are plausible the method affects a Shipping Profile rate the method affects WooCommerce shop mapping the method affects fulfillment handoff the method will be used for trial/subscription shipping a provider/method is missing from RevCent ``` Use a single clear match automatically when it is highly obvious, but summarize it before saving in important onboarding/setup workflows. --- ## No-Human-in-the-Loop Guidance For external AI/agent workflows without a human in the loop: ```text Only use a provider/method when the task payload includes explicit IDs/codes or there is exactly one clear provider/method match. ``` Do not guess: ```text provider provider_method domestic vs international method external fulfillment code fulfillment service mapping WooCommerce method mapping ``` If required mapping is ambiguous, stop safely and return the ambiguous options. --- ## Common Mistakes to Avoid Do not: - confuse Shipping Providers with Shipping Profiles, - assume `GetSiteShippingProviders` includes provider methods, - skip `GetSiteShippingProvider` when a method is needed, - invent provider IDs or provider method IDs, - map a provider without also mapping a method where required, - ignore domestic vs international method separation, - use a display name when an ID/code is required, - use an external fulfillment code as a provider_method value, - edit a User Shop `shipping_methods` replacement array with only one mapping unless intentionally removing all others, - use a close-but-wrong method when no exact/clear match exists. --- ## Recommended AI/MCP Summary Format When summarizing a selected provider/method mapping: ```text Shipping Provider Mapping - Source method: [WooCommerce/user/fulfillment method name] - RevCent Provider: [provider name] - RevCent Provider ID: [provider ID or identifier if applicable] - RevCent Method: [method display name] - RevCent Method ID: [method ID returned by GetSiteShippingProvider] - Domestic/International: [domestic/international/both/unknown] - Confidence: [high/medium/needs user choice] - Notes: [why this mapping was selected] ``` --- ## Final AI/MCP Instruction Shipping Providers are RevCent's static carrier/method mapping list. Use `GetSiteShippingProviders` to list available providers and `GetSiteShippingProvider` to retrieve the selected provider's domestic and international method options. Use Shipping Provider and Provider Method values carefully when configuring Shipping Profiles, mapping WooCommerce or custom-store shipping methods, creating shipment entries, and sending fulfillment/shipment context. If the correct provider or method is missing, do not guess. Tell the user to contact RevCent to have it added. --- 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.