Shipping Agent

Overview

Pelcro’s Shipping Agent uses AI to dynamically calculate shipping costs based on your defined business rules and real-time cart data. It interprets natural-language shipping rules (like “If the total weight of cart items is between 0 and 0.1 kg and the currency is GBP, the rate is 3.95”) and returns structured, validated rates directly at checkout.

This guide explains how to create and manage shipping rules, and how the AI agent processes them behind the scenes.

Why It’s Useful

• Automates shipping rate calculations using AI
• Lets you define flexible, human-readable rules
• Supports multiple currencies
• Removes the need for manual table-rate maintenance
• Scales easily for global stores

How to Set It Up

• Log in to the Pelcro Platform.
• Go to Settings → Account Settings → Shipping Rules.
• Click Create Rule.
• Enter your rule in natural language — for example:

“If the total weight of cart items is between 0 and 0.1 kg, and the currency is GBP, the rate is 3.95.”

• Save the rule. The AI automatically parses and stores both the text and the structured JSON representation.
• (Optional) Add multiple rules for different currencies or weight ranges.

💡

Tip: Each product SKU must have a defined weight (in kilograms) for the Shipping Agent to calculate rates.

How It Works

The Shipping Agent processes your rules and checkout data in four main stages — from rule creation to rate application.

1. Rule Definition & Storage

You can define shipping rules in plain language using three key attributes — currency, weight, and rate. These rules describe how shipping costs should be calculated based on the total weight of items and the order currency.

For example:

“If cart weight between 0–5 kg and currency = CAD, rate = 5 CAD.”

Each attribute plays a specific role in determining the final shipping rate:

When you create a rule, Pelcro automatically parses and stores it in two forms:

• The original prompt (your natural-language input)
• The structured JSON rule (machine-readable format used by the AI for validation and processing)

Example Stored Rule (JSON)

{
  "rate": 500, // Cents
  "weight": {
    "max": 5,
    "min": 0,
    "unit": "KG"
  },
  "currency": "CAD"
}

2. Checkout Trigger

When a customer checks out, Pelcro automatically:

• Collects the order currency
• Aggregates the total SKU weight
• Sends this data, along with your stored rules and the internal AI instructions, to the AI model

Example Checkout Input Sent to AI

{
  "currency": "CAD",
  "weight": 3.5,
  "rules": [
    {
      "rate": 250,
      "weight": {
        "min": 0,
        "max": 5,
        "unit": "KG"
      },
      "currency": "CAD"
    }
  ]
}

3. AI Evaluation

The AI Shipping Agent evaluates all provided rules. It matches the rule where min ≤ weight ≤ max and the currency align, validates the format of each field, and rejects any invalid or ambiguous input.

If validation passes, the AI returns a success response containing the matching rule and the applicable rate.

Example Success Response

{
  "status": 200,
  "message": "Rate applied successfully",
  "instructions": [
    {
      "rate": 250,
      "weight": {
        "min": 0,
        "max": 5,
        "unit": "KG"
      },
      "currency": "CAD"
    }
  ]
}

If validation fails (for example, if the weight is missing), the AI returns a structured error response.

{
  "status": 422,
  "message": "Invalid shipping rule: weight is missing or improperly formatted.",
  "instructions": null
}

4. Rate Application

Once a valid response is returned:

• Pelcro reads the rate from the response (rate: 250 = 2.50 CAD)
• The rate is automatically applied to the checkout
• The total shipping cost is displayed to the customer and stored in the order details

Example Final Applied Response

{
  "status": 200,
  "message": "Shipping rate calculated and applied",
  "applied_rate": 250,
  "currency": "CAD",
  "weight": 3.5
}

Example Prompts & Responses

The following examples demonstrate how the Shipping Agent interprets different rule inputs and returns structured JSON responses based on validation results.

Case 1: Valid New Rule

Input phrase:

If content of the cart weighs between 0 and 5 kg, charge 2.5 CAD

Expected output:

{
  "status": 200,
  "message": "Rule inserted successfully",
  "instructions": {
    "rate": 250,
    "weight": {
      "max": 5,
      "min": 0,
      "unit": "KG"
    },
    "currency": "CAD"
  },
  "reason": "No existing rules found, rule inserted successfully."
}

Case 2: Duplicate Rule

Input phrase:

If the total weight of cart items is between 0 and 0.1 kg, and the currency is GBP, the rate is 1.49

Expected output:

{
  "status": 422,
  "message": "Similar rule already exists.",
  "instructions": null,
  "reason": "Rule conflicts with existing one."
}

Case 3: Unsupported Currency

Input phrase:

If the total weight of cart items is between 0 and 0.1 kg, and the currency is EUR, the rate is 1.49

Expected output:

{
  "status": 422,
  "message": "Unsupported currency EUR, please create SKUs in this currency first.",
  "instructions": null,
  "reason": "EUR not listed among supported currencies."
}

Best Practices & Use Cases

To achieve consistent and flexible shipping behavior, consider the following practices:

• Multiple Currencies: Define separate rules for each supported currency to ensure accurate and localized shipping rates across regions.

• Weight Tiers: Use tiered shipping ranges (e.g., 0–5 kg, 5–10 kg, 10–20 kg) to scale rates progressively for different order weights.

• Promotional Offers: Incorporate zero-cost or discounted shipping rules to support marketing campaigns, loyalty tiers, or time-limited promotions.

These patterns help standardize shipping logic, improve customer transparency, and maintain predictable rate structures across markets.

Next Steps

• Contact Support: Email [email protected] or reach out to your Account Manager to enable the Beta and ensure you have the latest Pelcro React UI version.
• Test Thoroughly: Because this Shipping Agent is in Beta, we recommend thorough testing on staging environments before enabling it on your live site.