Shipping Rules Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Shipping Rules provide ShipStation API with a set of criteria to determine which carrier and service to apply to a shipment. This allows you to automate the selection of carrier and service according to your specific business needs.

Currently, you must create your shipping rules in your account dashboard. Once created, each rule will have a shipping rule ID that you can use to automate carrier and service selection when creating shipments or purchasing labels.

For each shipment, ShipStation API will evaluate the rule statements against the shipment details and apply the appropriate carrier_id and service_code to the shipment for you.

Create a Shipping Rule

To create a shipping rule:

1. Log into your account dashboard and go to Shipping Rules.
2. Click the Create rule button.
3. Choose the type of rule you wish to create, condition or service group.
4. Enter a name for your rule (each rule requires a unique name).
5. Create the statements with the conditions you require (see below sections for details on creating each type of rule).

Condition-based Rules

With condition based rules, you define explicit sets of conditions the shipment must meet for the service defined in the statement to be allocated to that shipment.

To create a condition-based rule:

1. Fill in the first condition for Statement 1.
2. Add more conditions if needed. Remember, additional conditions behave as AND statements.
3. Set the carrier and service that should apply to shipments meeting the statement conditions in the allocate fields.
4. Add more statements if needed. Remember, additional statements behave as ELSE IF statements.
5. Set the default carrier and service that will apply if the shipment does not meet the conditions for any of the rule statements.
6. Save the rule.

Service Group Rules

With service group rules, you first create a list of services in a prioritized order. Then, you create "exclusion statements" with conditions that will exclude a service from the shipment if the shipment meets the statement conditions.

To create a service group rule:

1. Choose a carrier and select which of that carrier's services to include in your priority list.
2. Click the Add to list button to add this set of services to the list.
3. (Optional) Continue to add services to your priority list, a carrier at a time, until you have the full list of services you wish this rule to contain.
4. Arrange the priority of the services in your list. You can drag and drop the services into the desired order, or use the up/down arrows to adjust the position of a service in the list.
5. Fill in the first condition for Statement 1.
6. Add more conditions if needed. Remember, additional conditions behave as AND statements.
7. Choose which services to exclude from shipments that meet the statement conditions.
8. Add more statements if needed. Remember, additional statements behave as ELSE IF statements.
9. Save the rule.

Apply Rules to Your Shipments

Once you have created your shipping rules, you will use the shipping_rule_id as a path parameter in the dedicated endpoint to purchase labels. For creating shipments, you can include the shipping_rule_id in the shipment object for the Create Shipment endpoint.

When purchasing a label with a shipping rule, you must NOT include carrier_id, service_code, or shipping_rule_id in the shipment object — the shipping rule determines these automatically.

ShipStation API will evaluate the shipping rule provided in the request to determine the carrier_id and service_code that should apply to the shipment. Both will then be included in the corresponding response.

Create Shipment Example Request

This is an example of the shipment object in a request for Creating a Shipment.

POST /v2/shipments

POST /v2/shipments HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "shipments": [
  {
   "shipping_rule_id": "se-49",
   "ship_to": {
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "name": "Jane Doe",
      "phone": "+1 444-444-4444"
    },
   "ship_from": {
      "address_line1": "4301 Bull Creek Rd",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78731",
      "country_code": "US",
      "name": "John Doe",
      "phone": "+1 555-555-5555"
    },
   "packages": [
     {
      "weight": {
        "value": 20,
        "unit": "ounce"
       },
      "dimensions": {
        "height": 6,
        "width": 12,
        "length": 24,
        "unit": "inch"
      }
    }
   ]
  }
 ]
}

Purchase Label Example Request

This is an example of the request for Purchasing a Label using a shipping rule. The shipping_rule_id is passed as a path parameter, and the shipment object must NOT include carrier_id, service_code, or shipping_rule_id.

POST /v2/labels/shipping_rules/{shipping_rule_id}

POST /v2/labels/shipping_rules/se-49 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "shipment": {
   "ship_to": {
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "name": "Jane Doe",
      "phone": "+1 444-444-4444"
    },
   "ship_from": {
      "address_line1": "4301 Bull Creek Rd",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78731",
      "country_code": "US",
      "name": "John Doe",
      "phone": "+1 555-555-5555"
    },
   "packages": [
     {
      "weight": {
        "value": 20,
        "unit": "ounce"
       },
      "dimensions": {
        "height": 6,
        "width": 12,
        "length": 24,
        "unit": "inch"
      }
    }
   ]
  }
}

Available Condition Properties

The following identifiers are currently available to use in your statement conditions: