# RevCent Shipping Profiles Overview for AI/MCP

AI/MCP-focused overview for Shipping Profiles in RevCent.

This document explains how Shipping Profiles work, why they matter, how RevCent calculates shipping rates for shippable products, and how AI/MCP clients should use the related Shipping Profile operations safely and correctly.

---

## Source Operations

This overview is based on the following RevCent MCP operations:

| Operation | Purpose |
|---|---|
| `GetShippingProfiles` | Retrieve a paginated list of Shipping Profiles. |
| `GetShippingProfile` | Retrieve one Shipping Profile by ID. |
| `CreateShippingProfile` | Create a new Shipping Profile. |
| `EditShippingProfile` | Edit an existing Shipping Profile. |

Related operations/concepts:

| Related Area | Why It Matters |
|---|---|
| Products / `CreateProduct` / `EditProduct` | Products must be shippable for shipping-rate calculation to matter. |
| Product Groups | Product Group qualifiers are one of the best ways to organize shipping rules. |
| Sales / `CreateSale` / `EstimateSale` | Sales may use profile-calculated shipping or predefined shipping entries. |
| Trial expirations | Trial expiration charges involving shippable products may need RevCent to calculate shipping. |
| Subscription renewals | Subscription renewal charges involving shippable products may need RevCent to calculate shipping. |
| Fulfillment Accounts | Fulfillment handles fulfillment/provider routing, while Shipping Profiles handle shipping-rate calculation. |
| Shipping Providers | Rates require RevCent site shipping provider and provider method IDs. |

---

## What Is a Shipping Profile?

A Shipping Profile defines settings for calculating shipping rates in RevCent.

A Shipping Profile can contain one or more shipping rates. Each rate defines:

```text
how much to charge for shipping
which shipping provider/method applies
when the rate qualifies
```

Shipping Profiles are used when RevCent needs to calculate a shipping rate for a transaction involving shippable products.

Common calculation contexts:

- Sales with shippable products when no predefined shipping entry is supplied.
- Trial expirations involving shippable products.
- Subscription renewals involving shippable products.
- Estimate flows that need shipping calculation.
- Automated recurring commerce where there is no third-party checkout shipping amount supplied at the moment of renewal/expiration.

Core concept:

```text
Shipping Profile = rules for calculating shipping charges.
Fulfillment Account = where/how to fulfill the shippable product.
Shipment = the shipping/fulfillment record created from a commerce event.
```

Do not confuse these objects.

---

## Why Shipping Profiles Matter

Shipping is critical for ecommerce because physical products need accurate shipping charges and fulfillment context.

Shipping Profiles help ecommerce businesses:

- charge the correct shipping amount,
- support different shipping rates for different products,
- support product group-based shipping rules,
- support country-specific shipping rates,
- support free shipping thresholds,
- support heavy-item or special-product shipping,
- support subscription renewal shipping,
- support trial expiration shipping,
- avoid manual shipping calculation,
- create more predictable customer-facing totals,
- keep RevCent’s Sale, renewal, trial, shipment, and reporting lifecycle connected.

Shipping Profiles are especially important when shipping cannot be calculated by a third-party shop at checkout. This is common for subscription renewals and trial expirations because those are automated future commerce events, not normal customer checkout events.

---

## When RevCent Calculates Shipping Rates

RevCent calculates shipping rates using enabled Shipping Profiles when the transaction requires shipping and no predefined shipping entry should override the calculation.

Typical cases:

| Situation | Shipping Behavior |
|---|---|
| Sale has shippable product and no predefined shipping entry | RevCent can calculate a shipping rate using enabled Shipping Profiles. |
| Sale API request includes a predefined `shipping` entry | RevCent uses the provided shipping entry instead of calculating a new Shipping Profile rate. |
| WooCommerce/third-party shop calculates shipping at checkout and sends shipping in the initial Sale request | RevCent uses the shipping entry from the request instead of recalculating, but the shop shipping methods must already be mapped in RevCent. |
| Trial expiration has shippable product and requires shipping | RevCent needs a matching enabled Shipping Profile rate. RevCent will not use the initial Sale shipping amount as the trial expiration rate source. |
| Subscription renewal has shippable product and requires shipping | RevCent needs a matching enabled Shipping Profile rate. RevCent will not use the initial Sale shipping amount as the subscription renewal rate source. |

Critical initial Sale rule:

```text
If an initial Sale request includes a predefined shipping entry, RevCent uses that entry instead of calculating a new rate from Shipping Profiles.
```

This matters for third-party shops such as WooCommerce. If WooCommerce calculates shipping at checkout and the initial Sale request includes that shipping entry, RevCent should not recalculate shipping through profiles for that initial Sale.

Critical renewal/trial rule:

```text
For subscription renewals and trial expirations, RevCent requires enabled Shipping Profiles with matching rates for shippable products.
```

Even if the product originated from WooCommerce or another third-party shop, RevCent will not use the initial Sale shipping as the rate source for future subscription renewals or trial expirations.

---

## Why Shipping Profiles Are Necessary for Trials and Renewals

Trial expirations and subscription renewals are not normal customer checkout events.

There may be no third-party shop checkout page calculating shipping at the moment the automated charge occurs.

That means RevCent needs configured Shipping Profiles so it can calculate shipping for shippable products when:

```text
trial expires and product requires shipping
```

or:

```text
subscription renews and product requires shipping
```

Without Shipping Profiles, RevCent may not have enough information to determine the correct shipping charge for automated shippable-product events.

This is true even when the original product was sold through WooCommerce or another third-party shop. The initial Sale may have had shipping calculated by the shop, but future subscription renewals and trial expirations must have a RevCent Shipping Profile rate that matches the shippable product context.

Examples:

```text
Monthly supplement renewal
    ↓
Shippable product renews
    ↓
RevCent calculates shipping from enabled Shipping Profiles
    ↓
Renewal creates payment/product sale/shipment context
```

```text
Trial product expires
    ↓
Trial expiration charge includes shippable product
    ↓
RevCent calculates shipping from enabled Shipping Profiles
    ↓
Trial expiration creates shipment context if product settings require shipping
```

---

## How RevCent Chooses the Best Shipping Rate

RevCent analyzes all enabled Shipping Profiles and their enabled/valid rates.

It then finds the best matching shipping rate based on the number of matched qualifiers.

Conceptually:

```text
Transaction with shippable products
    ↓
RevCent reviews enabled Shipping Profiles
    ↓
RevCent reviews rates inside enabled profiles
    ↓
RevCent evaluates rate qualifiers:
        - products
        - product groups
        - countries
        - revenue rules
    ↓
RevCent counts matched qualifiers
    ↓
Best matching rate is selected
```

Important:

```text
The best match is based on number of matched qualifiers.
```

This means more specific rates can win over more generic rates when they match more of the transaction context.

Example:

| Rate | Matching Qualifiers | Match Strength |
|---|---:|---|
| Generic US shipping | Country only | 1 match |
| Supplement US shipping | Product Group + Country | 2 matches |
| Supplement US free shipping over $75 | Product Group + Country + Revenue Rule | 3 matches |

In this example, if all three rates qualify, the third rate is likely the best match because it matches the most qualifiers.

AI/MCP clients should design Shipping Profiles so specificity is intentional and predictable.

---

## Rate Qualifiers

Shipping rates use qualifiers to determine whether they apply.

A rate must have at least one enabled qualifier across:

```text
products
product_groups
countries
revenue_rules
```

A shipping rate cannot contain zero enabled qualifiers.

Qualifier groups:

| Qualifier Group | Purpose |
|---|---|
| `products` | Rate applies based on matching Product IDs and quantity rules. |
| `product_groups` | Rate applies based on matching Product Group IDs. |
| `countries` | Rate applies based on destination country. |
| `revenue_rules` | Rate applies based on total amount, transaction amount, or shippable-product amount. |

---

## Product Qualifiers

Product qualifiers match specific Product IDs.

Each product qualifier includes:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `id` | string | Yes | 20-character Product ID. |
| `enabled` | boolean | Yes | Whether the qualifier is enabled. |
| `quantity_rule` | enum | Yes | Quantity comparison rule. |
| `quantity_value` | integer | Yes | Quantity value used with the rule. |

Allowed `quantity_rule` values:

```text
any
equal_to
greater_than
greater_than_equal_to
less_than
less_than_equal_to
```

Use product qualifiers when a rate should apply to specific products.

Example use cases:

- Product A ships for $4.95.
- Product B is heavy and ships for $19.95.
- Product C qualifies only when quantity is greater than 2.
- A fragile item requires a special provider method.

---

## Product Group Qualifiers

Product Group qualifiers match Product Group IDs.

Each product group qualifier includes:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `id` | string | Yes | 20-character Product Group ID. |
| `enabled` | boolean | Yes | Whether this Product Group qualifier is enabled. |

Product Group qualifiers are often the best way to manage shipping rates.

Best practice:

```text
Put a shop's products into meaningful Product Groups and use Product Groups for Shipping Profile qualifiers.
```

Examples:

- Supplements
- Heavy Items
- Starter Kits
- Apparel
- Digital Products excluded from shipping
- Subscription Refills
- Trial Kits
- US Warehouse Products
- EU Warehouse Products

Product Group qualifiers are easier to maintain than one rate per product.

---

## Country Qualifiers

Country qualifiers match the destination country.

Each country qualifier includes:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `iso_code` | string | Yes | ISO3 country code. |
| `enabled` | boolean | Yes | Whether this country qualifier is enabled. |

Country qualifier behavior:

```text
The shipment destination country must match at least one enabled country code in the array.
```

If the countries array is empty, the schema describes it as applying to all countries.

Use country qualifiers for:

- US-only rates,
- international rates,
- Canada-specific rates,
- EU region rates,
- countries the business ships to,
- different provider methods by destination.

Example:

```json
{
  "countries": [
    {
      "iso_code": "USA",
      "enabled": true
    }
  ]
}
```

---

## Revenue Rule Qualifiers

Revenue rules allow/disallow a rate based on revenue thresholds.

Each revenue rule includes:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `enabled` | boolean | Yes | Whether the revenue rule is enabled. |
| `source` | enum | Yes | Which amount source to evaluate. |
| `rule` | enum | Yes | Comparison operator. |
| `rule_value` | number | Yes | Value to compare against. |

Allowed `source` values:

```text
total_amount
transaction_amount
shippable_products
```

Allowed `rule` values:

```text
equal_to
greater_than
greater_than_equal_to
less_than
less_than_equal_to
```

Use revenue rules for:

- free shipping over $75,
- shipping discount thresholds,
- high-order-value rates,
- shipping based only on shippable product total,
- special rules for trial/renewal charges.

Example:

```json
{
  "revenue_rules": [
    {
      "enabled": true,
      "source": "shippable_products",
      "rule": "greater_than_equal_to",
      "rule_value": 75
    }
  ]
}
```

---

## Shipping Rate Schema

Each rate includes:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `rate` | number | Yes | Shipping amount charged to the customer. |
| `provider` | string | Yes | 20-character site shipping provider ID. |
| `provider_method` | string | Yes | 20-character site shipping provider method ID. |
| `qualifiers` | object | Yes | Rules that determine whether the rate applies. |

A rate should be treated as:

```text
charge this amount using this provider/method when these qualifiers match
```

Example rate:

```json
{
  "rate": 6.95,
  "provider": "XXXXXXXXXXXXXXXXXXXX",
  "provider_method": "YYYYYYYYYYYYYYYYYYYY",
  "qualifiers": {
    "products": [],
    "product_groups": [
      {
        "id": "PPPPPPPPPPPPPPPPPPPP",
        "enabled": true
      }
    ],
    "countries": [
      {
        "iso_code": "USA",
        "enabled": true
      }
    ],
    "revenue_rules": []
  }
}
```

---

## Shipping Provider and Provider Method

Every rate requires:

```text
provider
provider_method
```

These are RevCent site shipping provider/provider method IDs, not arbitrary carrier names.

AI/MCP clients must not guess these IDs.

Use the appropriate Shipping Provider operations, such as:

```text
GetShippingProviders
GetShippingProvider
```

to retrieve available provider and method IDs.

Conceptually:

```text
provider = carrier/provider family
provider_method = specific service/method
```

Example:

```text
USPS
USPS Priority
```

or:

```text
UPS
UPS Ground
```

Use actual IDs from RevCent, not display labels.

---

## CreateShippingProfile

`CreateShippingProfile` creates a new Shipping Profile.

This is a consequential operation and should only be performed upon explicit confirmation from the user.

Schema behavior:

```text
additionalProperties: false
```

Do not send unsupported fields.

Top-level fields:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | Shipping Profile name. |
| `description` | string | No | Shipping Profile description. |
| `enabled` | boolean | No | Whether the profile is enabled. |
| `rates` | array<object> | Expected for usable profile | Shipping rates for the profile. At least one rate must be present in a Shipping Profile. |

Although the schema's top-level required list contains `name`, the profile is not practically useful without rates.

Best practice:

```text
Create a Shipping Profile disabled until rates have been configured and verified.
```

Example:

```json
{
  "name": "US Supplements Shipping",
  "description": "Shipping rates for US supplement orders.",
  "enabled": false,
  "rates": [
    {
      "rate": 6.95,
      "provider": "XXXXXXXXXXXXXXXXXXXX",
      "provider_method": "YYYYYYYYYYYYYYYYYYYY",
      "qualifiers": {
        "products": [],
        "product_groups": [
          {
            "id": "PPPPPPPPPPPPPPPPPPPP",
            "enabled": true
          }
        ],
        "countries": [
          {
            "iso_code": "USA",
            "enabled": true
          }
        ],
        "revenue_rules": []
      }
    }
  ]
}
```

---

## GetShippingProfiles

`GetShippingProfiles` retrieves a paginated list of Shipping Profiles.

Input:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `limit` | integer | Yes | 1 to 25. |
| `page` | integer | Yes | Pagination page. |

Use it to:

- list existing Shipping Profiles,
- check whether a profile already exists before creating one,
- find profile IDs,
- review enabled/disabled state,
- see high-level rates.

Example:

```json
{
  "limit": 25,
  "page": 1
}
```

Best practice:

```text
Always list or search existing Shipping Profiles before creating a new one to avoid duplicates.
```

---

## GetShippingProfile

`GetShippingProfile` retrieves one Shipping Profile by ID.

Input:

```json
{
  "shipping_profile_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

Use it to:

- inspect a profile before editing,
- retrieve the full current rates array,
- verify qualifiers,
- debug rate selection,
- confirm enabled/disabled state,
- confirm provider/provider method IDs,
- prepare a safe `EditShippingProfile` request.

Best practice:

```text
Always call GetShippingProfile before editing rates.
```

---

## EditShippingProfile

`EditShippingProfile` edits an existing Shipping Profile.

This is a consequential operation and should only be performed upon explicit confirmation from the user.

Required field:

| Field | Type | Required |
|---|---:|---:|
| `shipping_profile_id` | string | Yes |

Optional editable fields:

| Field | Description |
|---|---|
| `name` | Shipping Profile name. |
| `description` | Shipping Profile description. |
| `enabled` | Whether the profile is enabled. |
| `rates` | Full array of rates to associate with the profile. |

Important patch behavior:

```text
Only provide fields that should be edited.
```

Example name-only edit:

```json
{
  "shipping_profile_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "US Shipping - Supplements"
}
```

This changes only the name.

---

## Critical Edit Rule: Rates Array Is Replaced

When editing `rates`, you must provide the full array of shipping rates that should remain associated with the Shipping Profile.

If the profile currently has two rates and you provide only one rate, the profile will end up with only that one rate. The omitted rate will be removed.

Critical rule:

```text
EditShippingProfile.rates is a replacement array, not a patch array.
```

Safe workflow:

```text
GetShippingProfile
    ↓
Copy existing rates
    ↓
Modify intended rate(s)
    ↓
Send full updated rates array to EditShippingProfile
```

Never edit rates by sending only the rate you want to change.

---

## Enabled Profiles and Enabled Qualifiers

RevCent analyzes enabled Shipping Profiles.

AI/MCP clients should remember:

- Disabled Shipping Profiles should not be treated as active.
- Each rate needs at least one enabled qualifier.
- Disabled qualifiers do not help a rate match.
- Empty qualifier arrays mean “do not require that qualifier type” where the schema says so.
- A rate with no enabled qualifier is invalid and should not be created.

Best practice:

```text
Create or edit profiles disabled until the profile has been reviewed and tested.
Enable only after rates and qualifiers are correct.
```

---

## Predefined Sale Shipping Entry vs Shipping Profile Calculation

Sales can include a predefined shipping entry in the API request.

When shipping is already provided in the request, RevCent uses that entry instead of calculating a new rate from Shipping Profiles.

This is common when:

- a third-party shop calculated shipping at checkout,
- WooCommerce sent the selected shipping method/amount,
- a custom storefront calculated shipping externally,
- the business intentionally wants to override shipping for a Sale.

Conceptual flow:

```text
Sale API request includes shipping entry
    ↓
RevCent uses provided shipping entry
    ↓
Shipping Profile rate calculation is not needed for that Sale
```

By contrast:

```text
Renewal/trial expiration with shippable product
    ↓
No customer checkout shipping calculation at that moment
    ↓
RevCent uses enabled Shipping Profiles to calculate shipping
```

AI/MCP clients must distinguish these paths.

---

## Shipping Profiles vs Third-Party Shop Shipping Methods

Shipping Profiles and third-party shop shipping method mapping are related but different.

| Concept | Purpose |
|---|---|
| Shipping Profile | Calculates shipping rates inside RevCent. |
| Third-party shop shipping method mapping | Maps remote shop shipping method IDs to RevCent providers/provider methods. |
| Predefined shipping entry | Shipping amount/method already supplied in the Sale API request. |

For WooCommerce:

- The shop may calculate shipping at initial checkout.
- The initial Sale request may include a shipping entry from WooCommerce.
- RevCent uses that provided entry for the initial Sale.
- The shop shipping method still needs to be mapped correctly so RevCent understands the provider/method context for initial Sale shipments.
- Shipping Profiles are required for automated future events such as subscription renewals and trial expirations when shippable products need to ship.
- RevCent will not use the initial Sale shipping amount as the rate source for subscription renewals or trial expirations.

---

## Critical Third-Party Shop Rule: Initial Sale Shipping vs Renewal/Trial Shipping

AI/MCP clients must clearly distinguish between **initial Sales from a third-party shop** and **future automated subscription renewal or trial expiration events**.

For a third-party shop such as WooCommerce:

```text
Initial Sale shipping is usually determined by the third-party shop checkout.
Subscription renewal and trial expiration shipping must be calculated by RevCent using Shipping Profiles.
```

This distinction is critical.

---

## Initial Sales From WooCommerce / Third-Party Shops

When an initial Sale comes from a third-party shop such as WooCommerce, the customer usually selected a shipping method during checkout.

That means the initial Sale request may already include a predefined shipping entry.

In that case:

```text
WooCommerce / third-party shop calculates shipping
    ↓
Customer selects shipping method at checkout
    ↓
Sale request includes predefined shipping entry
    ↓
RevCent uses the provided shipping entry
    ↓
RevCent does not calculate a new Shipping Profile rate for that initial Sale
```

However, this only works correctly when the third-party shop shipping methods have already been mapped in RevCent.

For WooCommerce and other supported third-party shops, the remote shop shipping methods must be retrieved and mapped to RevCent shipping providers/provider methods.

Use:

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

with:

```text
GetUserShop
```

The remote shop shipping methods need to be mapped so RevCent understands the shipping method selected in the third-party shop checkout.

Important:

```text
Initial Sale shipping can come from the third-party shop,
but the shop shipping methods must already be mapped in RevCent.
```

If the remote shop shipping methods are not mapped, RevCent may not correctly understand the provider/method context for shipments created from those third-party shop Sales.

---

## Subscription Renewals From Third-Party Shop Products

A product can originate from a third-party shop, such as WooCommerce, and still be a RevCent subscription product.

For subscription renewals, RevCent cannot rely on the original initial Sale shipping entry as the future renewal shipping-rate source.

The renewal is a new future commerce event.

There is no active WooCommerce checkout session where the customer selects shipping again.

Therefore:

```text
Third-party shop product has subscription settings
    ↓
Initial Sale may use WooCommerce-provided shipping
    ↓
Subscription renewal occurs later
    ↓
RevCent must calculate shipping for the renewal
    ↓
A matching enabled Shipping Profile rate is required
```

Critical rule:

```text
Even if the product came from WooCommerce or another third-party shop,
a Shipping Profile with a matching rate is required for subscription renewal shipments.
```

RevCent will not use the initial Sale shipping amount as the rate source for future subscription renewals.

---

## Trial Expirations From Third-Party Shop Products

A product can also originate from a third-party shop and have trial settings in RevCent.

For trial expirations, RevCent cannot rely on the initial Sale shipping entry as the future trial expiration shipping-rate source.

The trial expiration is also a new future commerce event.

Therefore:

```text
Third-party shop product has trial settings
    ↓
Initial Sale may use WooCommerce-provided shipping
    ↓
Trial expiration occurs later
    ↓
RevCent must calculate shipping for the trial expiration if shipping is required
    ↓
A matching enabled Shipping Profile rate is required
```

Critical rule:

```text
Even if the product came from WooCommerce or another third-party shop,
a Shipping Profile with a matching rate is required for trial expiration shipments.
```

RevCent will not use the initial Sale shipping amount as the rate source for future trial expirations.

---

## Why Initial Sale Shipping Cannot Be Reused for Renewals or Trials

Initial Sale shipping is tied to a specific checkout event.

It may depend on:

- customer-selected shipping method,
- cart contents at checkout,
- promotional shipping rules,
- address at checkout,
- third-party shop shipping plugins,
- live rates from a remote shop,
- one-time checkout context.

Subscription renewals and trial expirations happen later and are separate RevCent commerce events.

They may involve:

- different shipment timing,
- different shippable products,
- different subscription renewal price,
- different trial expiration price,
- different destination data,
- different product group,
- different shipping threshold,
- no active third-party checkout calculation.

For this reason, Shipping Profiles are required to define how RevCent should calculate shipping for those automated future events.

---

## Third-Party Shop Subscription/Trial Setup Checklist

When a third-party shop sells products that have subscription or trial behavior in RevCent, AI/MCP clients must verify both shop shipping mappings and Shipping Profiles.

Checklist:

1. Confirm the third-party shop is connected.
2. Use `GetUserShop` with `remote_data: ["shipping_methods"]`.
3. Confirm the remote shop shipping methods are mapped to RevCent provider/provider method IDs.
4. Confirm products imported from the shop have correct `third_party_shop` and `internal_id` values.
5. Confirm shippable products are marked `is_shippable = true`.
6. Confirm shippable products have a valid Fulfillment Account.
7. If products have subscription settings, confirm an enabled Shipping Profile has a matching rate for renewals.
8. If products have trial settings and trial shipping can occur at expiration, confirm an enabled Shipping Profile has a matching rate for trial expirations.
9. Use Product Group qualifiers where possible so renewal/trial shipping rules remain maintainable.
10. Test or estimate the renewal/trial shipping scenario before relying on it in production.

---

## Incorrect Assumption to Avoid

Do not assume:

```text
Because WooCommerce calculated shipping on the initial Sale,
RevCent can reuse that same shipping amount for every future subscription renewal or trial expiration.
```

That is incorrect.

Correct rule:

```text
Initial third-party shop Sale → use predefined shipping entry from the Sale request.
Future subscription renewal / trial expiration → use enabled Shipping Profiles to calculate shipping.
```

If there is no matching Shipping Profile rate for the renewal or trial expiration, the future shipment flow may not have a correct shipping rate.

---

## Best-Practice Profile Design

Good Shipping Profiles are intentional and easy to reason about.

Best practices:

1. Use clear profile names.
2. Use descriptions that explain when the profile should apply.
3. Prefer Product Group qualifiers over many individual Product qualifiers when possible.
4. Use country qualifiers for destination-specific rates.
5. Use revenue rules for free shipping or order-value thresholds.
6. Keep rates specific enough that the best-match logic is predictable.
7. Avoid overlapping rates that unintentionally tie in matched qualifier count.
8. Create profiles disabled while configuring.
9. Test rate calculation before enabling.
10. Use `GetShippingProfile` before editing rates.
11. Send the full `rates` array when editing rates.
12. Keep shippable products organized into Product Groups.
13. For third-party shop subscription/trial products, always create matching Shipping Profile rates for renewals/trial expirations.
14. Do not rely on initial Sale shipping entries as future renewal/trial rate sources.

---

## Examples

### Example: Flat US Shipping for Product Group

```json
{
  "name": "US Supplements Flat Rate",
  "description": "Flat-rate shipping for supplement products shipping to the USA.",
  "enabled": true,
  "rates": [
    {
      "rate": 6.95,
      "provider": "XXXXXXXXXXXXXXXXXXXX",
      "provider_method": "YYYYYYYYYYYYYYYYYYYY",
      "qualifiers": {
        "products": [],
        "product_groups": [
          {
            "id": "PPPPPPPPPPPPPPPPPPPP",
            "enabled": true
          }
        ],
        "countries": [
          {
            "iso_code": "USA",
            "enabled": true
          }
        ],
        "revenue_rules": []
      }
    }
  ]
}
```

### Example: Free Shipping Over $75

```json
{
  "name": "US Supplements Free Shipping Threshold",
  "description": "Free shipping for US supplement orders with shippable product total of at least $75.",
  "enabled": true,
  "rates": [
    {
      "rate": 0,
      "provider": "XXXXXXXXXXXXXXXXXXXX",
      "provider_method": "YYYYYYYYYYYYYYYYYYYY",
      "qualifiers": {
        "products": [],
        "product_groups": [
          {
            "id": "PPPPPPPPPPPPPPPPPPPP",
            "enabled": true
          }
        ],
        "countries": [
          {
            "iso_code": "USA",
            "enabled": true
          }
        ],
        "revenue_rules": [
          {
            "enabled": true,
            "source": "shippable_products",
            "rule": "greater_than_equal_to",
            "rule_value": 75
          }
        ]
      }
    }
  ]
}
```

### Example: Quantity-Specific Product Rate

```json
{
  "name": "Two or More Starter Kits Shipping",
  "description": "Special shipping rate when two or more starter kits are included.",
  "enabled": true,
  "rates": [
    {
      "rate": 9.95,
      "provider": "XXXXXXXXXXXXXXXXXXXX",
      "provider_method": "YYYYYYYYYYYYYYYYYYYY",
      "qualifiers": {
        "products": [
          {
            "id": "AAAAAAAAAAAAAAAAAAAA",
            "enabled": true,
            "quantity_rule": "greater_than_equal_to",
            "quantity_value": 2
          }
        ],
        "product_groups": [],
        "countries": [
          {
            "iso_code": "USA",
            "enabled": true
          }
        ],
        "revenue_rules": []
      }
    }
  ]
}
```

---

## AI/MCP Setup Workflow

When a user wants to create Shipping Profiles:

```text
1. Understand the business's shipping strategy.
2. Identify shippable products.
3. Organize products into Product Groups where useful.
4. Identify countries/regions the business ships to.
5. Identify shipping provider/provider method IDs.
6. Determine flat rates, free shipping thresholds, and special rules.
7. Create profile disabled first, unless user explicitly wants immediate activation.
8. Add rates with at least one enabled qualifier each.
9. Test with EstimateSale or controlled Sale/trial/renewal scenarios.
10. Enable profile when verified.
```

When a user wants to edit Shipping Profiles:

```text
1. Use GetShippingProfile.
2. Review current rates and qualifiers.
3. Make only intended changes.
4. If editing simple fields, send only those fields.
5. If editing rates, send the full final rates array.
6. Confirm with the user before calling EditShippingProfile.
7. Verify the updated profile after edit.
```

---

## Troubleshooting Shipping Rate Calculation

If RevCent did not calculate the expected shipping rate, check:

- Is the Shipping Profile enabled?
- Is the relevant rate present?
- Does the rate have at least one enabled qualifier?
- Does the destination country match the country qualifier?
- Do the products match product/product group qualifiers?
- Does the quantity rule pass?
- Does the revenue rule pass?
- Are provider and provider_method valid?
- Did another enabled rate match more qualifiers?
- Did the Sale request already include a predefined shipping entry?
- Is this an initial third-party shop Sale where shipping came from the shop checkout?
- Is this a subscription renewal or trial expiration that requires a Shipping Profile rate?
- Is this a third-party shop subscription/trial product where no matching Shipping Profile exists?
- Is the transaction a trial expiration or subscription renewal where profile calculation is required?
- Is the product actually marked shippable?
- Does the product have a Fulfillment Account?
- Are Product Groups correctly assigned?

---

## Common Mistakes to Avoid

Do not:

- create a shipping rate with zero enabled qualifiers,
- guess provider/provider_method IDs,
- forget to include a provider method,
- create profiles enabled before testing,
- confuse Shipping Profiles with Fulfillment Accounts,
- confuse Shipping Profiles with third-party shop shipping-method mapping,
- expect Shipping Profiles to override an initial Sale request that already includes a predefined shipping entry,
- rely on a third-party shop initial Sale shipping entry for future subscription renewals or trial expirations,
- forget that third-party shop shipping methods must be mapped for initial Sales,
- forget that Shipping Profiles are still required for third-party shop products with subscription or trial behavior,
- forget that trial expirations and subscription renewals may depend on Shipping Profiles,
- create many product-specific rates when Product Groups would be cleaner,
- edit `rates` by sending only the one rate being changed,
- omit existing rates during `EditShippingProfile`,
- leave overlapping rules that make best-match results hard to predict,
- forget to call `GetShippingProfile` before modifying rates.

---

## AI/MCP Decision Guide

| User Intent | Correct Operation / Approach |
|---|---|
| List Shipping Profiles | `GetShippingProfiles` |
| Inspect one profile | `GetShippingProfile` |
| Create a new profile | `CreateShippingProfile` after explicit confirmation |
| Rename or enable/disable profile | `EditShippingProfile` with only those fields |
| Modify rates | `GetShippingProfile`, edit full rates array, then `EditShippingProfile` |
| Calculate checkout preview | `EstimateSale` using shippable products and shipping context |
| Third-party shop initial Sale shipping | Provide shipping entry in Sale request; RevCent uses it instead of recalculating, assuming shop shipping methods are mapped |
| Third-party shop subscription renewal shipping | Configure matching enabled Shipping Profile rates; do not rely on initial Sale shipping |
| Third-party shop trial expiration shipping | Configure matching enabled Shipping Profile rates; do not rely on initial Sale shipping |
| Support subscription renewal shipping | Configure enabled Shipping Profiles with matching qualifiers |
| Support trial expiration shipping | Configure enabled Shipping Profiles with matching qualifiers |
| Organize rates by product type | Use Product Groups and Product Group qualifiers |

---

## Validation Checklist Before Creating or Editing

Before creating or editing a Shipping Profile, verify:

- User explicitly confirmed the operation.
- Profile name is clear.
- Description explains purpose.
- Enabled state is intentional.
- At least one rate exists.
- Each rate has `rate`, `provider`, `provider_method`, and `qualifiers`.
- Provider and provider method IDs are real RevCent IDs.
- Every rate has at least one enabled qualifier.
- Product IDs are correct.
- Product Group IDs are correct.
- Country ISO3 codes are correct.
- Revenue rules use the correct source and comparison.
- Overlapping rates are intentional.
- Best-match qualifier behavior is understood.
- If editing rates, the full rates array is included.
- If the user relies on WooCommerce/custom shop checkout shipping, the initial Sale request shipping-entry behavior is understood.
- If initial Sales come from a third-party shop, shop shipping methods have been mapped in RevCent.
- If products came from a third-party shop and have subscription/trial behavior, matching Shipping Profile rates exist for renewals/trial expirations.
- Trial and subscription renewal scenarios are covered for shippable products.

---

## Final AI/MCP Instruction

Shipping Profiles define how RevCent calculates shipping rates for shippable products.

RevCent analyzes enabled Shipping Profiles and chooses the best matching shipping rate based on the number of matched qualifiers. Qualifiers can match products, Product Groups, destination countries, and revenue rules.

Shipping Profiles are especially important for trial expirations and subscription renewals because those future automated commerce events may involve shippable products without a third-party checkout page calculating shipping at that moment.

If an initial Sale API request already includes a predefined shipping entry, such as shipping calculated by a third-party shop, RevCent uses that shipping entry instead of calculating a new Shipping Profile rate. For third-party shop initial Sales, the shop shipping methods must already be mapped in RevCent so the selected shipping method is understood correctly.

For subscription renewals and trial expirations involving shippable products, RevCent requires a matching enabled Shipping Profile rate even if the product originally came from WooCommerce or another third-party shop. RevCent will not use the initial Sale shipping amount as the rate source for future renewals or trial expirations.

Create Shipping Profiles carefully, prefer Product Group qualifiers where possible, test before enabling, and always retrieve the full existing profile before editing rates because `EditShippingProfile.rates` replaces the full rate array.


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