# RevCent MCP Guide: `CreateShippingProfile`

AI/MCP-focused guide for creating Shipping Profiles in RevCent.

This document is meant to be read by AI agents, MCP clients, automation tools, and developers that need to understand how to correctly create a Shipping Profile, how the `rates` array works, and how qualifiers determine when a shipping rate applies.

---

## Related Overview

Before creating a Shipping Profile, AI/MCP clients should read the Shipping Profile overview:

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

The overview explains how Shipping Profiles are used to calculate shipping rates for Sales, trial expirations, and subscription renewals involving shippable products.

---

## Operation Summary

Operation:

```text
CreateShippingProfile
```

Title:

```text
Create A Shipping Profile
```

Purpose:

```text
Create a shipping profile in RevCent.
```

Important:

```text
CreateShippingProfile is a very consequential operation and should only be performed upon explicit confirmation from the user.
```

A Shipping Profile defines settings for calculating shipping rates for shippable-product commerce events.

Shipping Profiles can be used when RevCent needs to calculate shipping for:

- Sales with shippable products when no predefined shipping entry is provided,
- trial expirations with shippable products,
- subscription renewals with shippable products,
- estimate flows that need shipping calculations.

If a Sale API request already includes a predefined shipping entry, such as shipping calculated by WooCommerce or another third-party shop, RevCent uses that predefined entry instead of calculating a new rate from Shipping Profiles.

However, subscription renewals and trial expirations still require matching enabled Shipping Profile rates when they involve shippable products, even if the product originally came from a third-party shop.

---

## Core Concept

A Shipping Profile contains one or more shipping rates.

Each rate answers:

```text
How much should the customer be charged for shipping,
which provider/method should be used,
and when does this rate apply?
```

A rate is made up of:

```text
rate amount
provider
provider_method
qualifiers
```

The qualifiers determine whether the rate applies to a transaction.

---

## Schema Overview

`CreateShippingProfile` input schema:

```text
type: object
additionalProperties: false
required:
  - name
```

Supported top-level fields:

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

Important schema rule:

```text
Do not send unknown fields.
```

Unsupported fields should not be included.

---

## Output Schema

Successful output can include:

| Field | Type | Description |
|---|---:|---|
| `api_call_id` | string | 20-character API call ID. |
| `api_call_unix` | integer | Unix timestamp when the API call was initiated. |
| `code` | integer | API call response code. `1` indicates success. |
| `shipping_profile_id` | string | 20-character Shipping Profile ID. |
| `result` | string | Result message. |

---

## Required User Confirmation

Creating a Shipping Profile can affect live checkout, renewals, trial expirations, and shipping charges.

AI/MCP clients should not create a Shipping Profile casually.

Before calling `CreateShippingProfile`, confirm:

- the user wants to create a new Shipping Profile,
- the profile name is correct,
- the enabled state is intentional,
- each shipping rate is correct,
- provider and provider method IDs are real RevCent IDs,
- qualifiers are correct,
- the profile will not create unintended shipping charges,
- trial and subscription renewal behavior is understood.

Recommended default:

```text
Create the profile disabled unless the user explicitly wants it enabled immediately.
```

This lets the business inspect and test the profile before it affects live shipping calculations.

---

## Top-Level Fields

### `name`

Required.

The Shipping Profile name should clearly describe the profile.

Good examples:

```text
US Supplements Shipping
US Free Shipping Over $75
Canada Shipping - Apparel
Subscription Refills Shipping
Trial Kits Shipping
Heavy Items Domestic Shipping
WooCommerce Renewal Shipping
```

Poor examples:

```text
Shipping
Test
Profile 1
Rate
```

The name should help humans and AI/MCP clients understand when the profile should apply.

---

### `description`

Optional but strongly recommended.

Use the description to explain:

- which products/product groups the profile covers,
- which countries or regions it applies to,
- whether it is for Sales, renewals, trials, or all shipping events,
- whether it is related to a specific shop/brand/campaign,
- whether it is enabled for production or still being tested.

Example:

```text
Shipping rates for US supplement products, including subscription renewals and trial expirations. Uses USPS Ground Advantage for normal shipments and free shipping when shippable product amount is at least $75.
```

---

### `enabled`

Optional boolean.

Use:

```json
"enabled": true
```

when the profile should immediately participate in shipping-rate calculation.

Use:

```json
"enabled": false
```

when the profile should be created as a draft or needs review/testing.

Best practice:

```text
Create new Shipping Profiles disabled first.
Enable only after verifying rates, qualifiers, provider methods, and test calculations.
```

Enabled profiles can be considered by RevCent when calculating shipping rates.

Disabled profiles should not be treated as active shipping calculation rules.

---

### `rates`

Array of shipping rate objects.

The schema says:

```text
At least one rate must be present in a Shipping Profile.
```

A profile without rates is not useful for shipping calculation.

Each rate must include:

```text
rate
provider
provider_method
qualifiers
```

---

## Shipping Rate Object

Each item in `rates` has:

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

Conceptual meaning:

```text
Charge this shipping amount using this provider/method when these qualifiers match.
```

---

## `rate`

Required number.

This is the shipping amount charged to the customer.

Examples:

```json
"rate": 6.95
```

```json
"rate": 0
```

Use `0` for free shipping rates.

Do not confuse `rate` with product price, tax, fulfillment cost, or actual carrier cost. It is the shipping amount charged to the customer.

---

## `provider`

Required string.

A 20-character site shipping provider ID.

This is not a free-form carrier name.

Correct:

```json
"provider": "XXXXXXXXXXXXXXXXXXXX"
```

Incorrect:

```json
"provider": "USPS"
```

Use provider IDs from RevCent shipping provider operations such as:

```text
GetShippingProviders
GetShippingProvider
```

Do not guess provider IDs.

---

## `provider_method`

Required string.

A 20-character site shipping provider method ID.

This is the provider method/service used for the rate.

Correct:

```json
"provider_method": "YYYYYYYYYYYYYYYYYYYY"
```

Incorrect:

```json
"provider_method": "Priority Mail"
```

Use provider method IDs from RevCent shipping provider operations.

Do not guess provider method IDs.

---

## `qualifiers`

Required object.

Qualifiers determine if the rate applies to a transaction.

Qualifier groups:

| Group | Purpose |
|---|---|
| `products` | Match specific products and quantity rules. |
| `product_groups` | Match product groups. |
| `countries` | Match destination countries. |
| `revenue_rules` | Match purchase amount rules. |

Critical rule:

```text
There must be at least one enabled qualifier for the shipping rate within products, product_groups, countries, or revenue_rules.
```

A shipping rate cannot contain zero enabled qualifiers.

This means at least one of the following must contain an object with `enabled: true`:

```text
qualifiers.products
qualifiers.product_groups
qualifiers.countries
qualifiers.revenue_rules
```

---

## Qualifier Matching Concept

RevCent evaluates enabled Shipping Profiles and rates, then finds the best match based on the number of matched qualifiers.

More specific rates can win over more generic rates when they match more qualifying dimensions.

Example:

| Rate | Qualifiers | Match Count |
|---|---|---:|
| Generic USA shipping | country = USA | 1 |
| Supplement USA shipping | product group = Supplements, country = USA | 2 |
| Supplement USA free shipping over $75 | product group = Supplements, country = USA, revenue rule >= 75 | 3 |

If all qualify, the most specific matching rate is expected to be selected because it has the most matched qualifiers.

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

---

## `qualifiers.products`

Product qualifiers are used when a rate should apply to one or more specific Product IDs.

Schema:

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

Allowed `quantity_rule` values:

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

Example:

```json
{
  "id": "AAAAAAAAAAAAAAAAAAAA",
  "enabled": true,
  "quantity_rule": "any",
  "quantity_value": 0
}
```

Use product qualifiers when shipping rate logic depends on specific products.

Examples:

- a specific starter kit has a flat rate,
- a heavy item has a special shipping amount,
- a product ships free when quantity is greater than 2,
- a product requires a specific provider method.

### Product Quantity Rules

Quantity rules allow rate logic to depend on product quantity.

Examples:

```text
any
```

The product only needs to be present. `quantity_value` is not meaningful.

```text
equal_to 1
```

The product quantity must equal 1.

```text
greater_than_equal_to 2
```

The product quantity must be at least 2.

```text
less_than_equal_to 3
```

The product quantity must be 3 or fewer.

Best practice:

```text
Use Product Group qualifiers when possible; use Product qualifiers only when the rate truly depends on a specific Product ID.
```

---

## `qualifiers.product_groups`

Product Group qualifiers are used when a rate should apply to products in one or more Product Groups.

Schema:

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

Example:

```json
{
  "id": "PPPPPPPPPPPPPPPPPPPP",
  "enabled": true
}
```

Product Group qualifiers are recommended for ecommerce shipping rules because they are easier to maintain than product-by-product rates.

Examples:

- Supplements
- Apparel
- Heavy Items
- Starter Kits
- Trial Kits
- Subscription Refills
- US Warehouse Products
- EU Warehouse Products
- WooCommerce Shop Products

Best practice:

```text
For a shop's products, use Product Groups to organize products and create Shipping Profile rates around those groups.
```

---

## `qualifiers.countries`

Country qualifiers match the shipment destination country.

Schema:

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

Example:

```json
{
  "iso_code": "USA",
  "enabled": true
}
```

Country qualifier behavior:

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

The schema says:

```text
Leave empty to apply to all countries.
```

Use country qualifiers for:

- US shipping rates,
- Canada shipping rates,
- international rates,
- region-specific provider methods,
- countries the merchant ships to.

Use ISO3 country codes, such as:

```text
USA
CAN
GBR
AUS
```

Do not use two-letter codes in this field.

---

## `qualifiers.revenue_rules`

Revenue rules allow a rate to apply based on amount thresholds.

Schema:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `enabled` | boolean | Yes | Whether the revenue rule is enabled. |
| `source` | enum | Yes | Which amount to evaluate. |
| `rule` | enum | Yes | Comparison rule. |
| `rule_value` | number | Yes | Amount used for comparison. |

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

Example:

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

Use revenue rules for:

- free shipping over a threshold,
- discounted shipping above a threshold,
- special rates for lower-value orders,
- shipping based only on shippable product total,
- subscription renewal shipping tiers,
- trial expiration shipping tiers.

### Choosing the Right Revenue Source

| Source | Meaning |
|---|---|
| `total_amount` | Total amount of the associated purchase. |
| `transaction_amount` | Transaction amount of the associated purchase. |
| `shippable_products` | Total amount for shippable products in the transaction. |

Use `shippable_products` when the shipping threshold should only consider physical/shippable items.

Example:

```text
Free shipping when shippable product subtotal is at least $75.
```

Use `total_amount` when the full purchase total should qualify the customer.

Use `transaction_amount` when the actual payment/transaction amount should qualify the rate.

---

## Minimal Valid Request

The schema only requires `name` at the top level.

However, a Shipping Profile should include rates to be useful.

Schema-minimum request:

```json
{
  "name": "US Shipping"
}
```

AI/MCP guidance:

```text
Do not create a name-only Shipping Profile unless the user explicitly wants a draft placeholder.
```

Recommended practical minimum:

```json
{
  "name": "US Supplements Shipping",
  "description": "Flat-rate US shipping for supplement products.",
  "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": []
      }
    }
  ]
}
```

---

## Example: Flat-Rate US Shipping

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

This rate applies broadly to USA shipments because it uses only a country qualifier.

---

## Example: Product Group Shipping

```json
{
  "name": "US Supplements Shipping",
  "description": "Shipping for supplement products in 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": []
      }
    }
  ]
}
```

This is a strong pattern because product groups make shipping rules easier to maintain.

---

## Example: Free Shipping Over $75

```json
{
  "name": "US Supplements Free Shipping Over 75",
  "description": "Free shipping for US supplement orders where shippable product amount is 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
          }
        ]
      }
    }
  ]
}
```

This rate should be more specific than a generic USA supplement rate because it matches product group, country, and revenue rule.

---

## Example: Multiple Rates in One Profile

```json
{
  "name": "US Supplements Shipping Rates",
  "description": "Flat-rate and free-shipping threshold for US supplement products.",
  "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": [
          {
            "enabled": true,
            "source": "shippable_products",
            "rule": "less_than",
            "rule_value": 75
          }
        ]
      }
    },
    {
      "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
          }
        ]
      }
    }
  ]
}
```

This profile creates:

```text
$6.95 shipping below $75
free shipping at $75 or above
```

based on shippable product amount.

---

## Third-Party Shop Guidance

For third-party shops such as WooCommerce:

```text
Initial Sale shipping may already be calculated by the shop and sent in the Sale request.
```

If the initial Sale API request includes a predefined shipping entry, RevCent uses that entry instead of calculating a new Shipping Profile rate.

However:

```text
Subscription renewals and trial expirations still require matching enabled Shipping Profile rates when shippable products need to ship.
```

This is true even when the product originally came from WooCommerce or another third-party shop.

RevCent does not use the initial Sale shipping amount as the rate source for future subscription renewals or trial expirations.

AI/MCP clients should verify:

- third-party shop shipping methods are mapped in RevCent for initial Sales,
- shippable subscription products have matching Shipping Profile rates for renewals,
- shippable trial products have matching Shipping Profile rates for trial expirations,
- Product Group qualifiers are used where possible to keep rules maintainable.

---

## Required Pre-Checks Before Calling `CreateShippingProfile`

Before creating a Shipping Profile, verify:

- User explicitly confirmed creation.
- Profile does not already exist.
- Name is clear.
- Description explains purpose.
- Enabled state is intentional.
- At least one rate is included unless user explicitly wants a placeholder draft.
- Each rate has `rate`, `provider`, `provider_method`, and `qualifiers`.
- Provider ID is real.
- Provider method ID is real.
- Each rate has at least one enabled qualifier.
- Product IDs are real when product qualifiers are used.
- Product Group IDs are real when group qualifiers are used.
- Country codes are ISO3.
- Revenue rules use the correct `source`, `rule`, and `rule_value`.
- Overlapping rate specificity is intentional.
- Trial expiration and subscription renewal scenarios are covered where needed.
- Third-party shop initial Sale behavior is understood where relevant.

---

## Best Practices

1. Create profiles disabled by default unless the user explicitly requests enabled.
2. Use clear names and descriptions.
3. Prefer Product Group qualifiers over many individual Product qualifiers.
4. Use country qualifiers for destination-specific rates.
5. Use `shippable_products` revenue source for free-shipping thresholds based only on physical goods.
6. Do not guess provider/provider method IDs.
7. Avoid overly broad enabled rates that accidentally match too many transactions.
8. Design rates so best-match behavior is predictable.
9. Use Shipping Profiles for trial expirations and subscription renewals involving shippable products.
10. Do not rely on initial Sale shipping entries for future renewals/trials.
11. Validate with `EstimateSale` or a controlled test flow where appropriate.
12. Keep shop products in Product Groups for cleaner shipping-rule management.

---

## Common Mistakes to Avoid

Do not:

- create a rate with zero enabled qualifiers,
- create a profile enabled before rates are reviewed,
- send provider names instead of provider IDs,
- send provider method names instead of provider method IDs,
- use two-letter country codes instead of ISO3 country codes,
- create many product-specific rules when Product Groups would be better,
- forget trial expirations may need shipping-rate calculation,
- forget subscription renewals may need shipping-rate calculation,
- assume WooCommerce initial Sale shipping applies to future renewals or trial expirations,
- confuse Shipping Profiles with Fulfillment Accounts,
- confuse Shipping Profiles with third-party shop shipping-method mapping,
- use unsupported fields in the request body,
- create duplicate profiles without checking existing Shipping Profiles first.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Create shipping-rate calculation rules | Use `CreateShippingProfile`. |
| Create draft rules for later review | Use `enabled: false`. |
| Create live rules immediately | Use `enabled: true` only after explicit confirmation. |
| Rate applies to a specific product | Use `qualifiers.products`. |
| Rate applies to product category/group | Use `qualifiers.product_groups`. |
| Rate applies to destination country | Use `qualifiers.countries`. |
| Rate applies above/below threshold | Use `qualifiers.revenue_rules`. |
| Need free shipping | Use `rate: 0` with appropriate qualifiers. |
| Need subscription renewal shipping | Create matching enabled Shipping Profile rate. |
| Need trial expiration shipping | Create matching enabled Shipping Profile rate. |
| Initial Sale already has shipping from WooCommerce | Use predefined shipping entry in Sale request; do not rely on profile calculation for that initial Sale. |

---

## Final AI/MCP Instruction

Use `CreateShippingProfile` to create Shipping Profiles that define shipping-rate calculation rules for shippable-product transactions in RevCent.

Every useful Shipping Profile should include one or more rates. Every rate must include a shipping amount, provider ID, provider method ID, and qualifiers. Each rate must have at least one enabled qualifier across products, Product Groups, countries, or revenue rules.

Shipping Profiles are especially important for subscription renewals and trial expirations involving shippable products, including products that originally came from third-party shops such as WooCommerce. Initial Sales may use predefined shipping entries from third-party shop checkout, but future renewals and trial expirations need matching enabled Shipping Profile rates.

Create Shipping Profiles only after explicit user confirmation, prefer disabled profiles until tested, use Product Group qualifiers where possible, and do not guess provider/provider method IDs.


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