# Shipping Rules Guide

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.

Shipping Rules Endpoints Coming Soon
We will soon be adding a shipping rules endpoint so you can also create rules programmatically. Check back soon for details on using this new endpoint.

## 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](/shipments/create) 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](/shipments/create).

**POST /v2/shipments**


```http
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](/create-labels) 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}**


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

| Identifier | Value Type | Available Operators | Description |
|  --- | --- | --- | --- |
| To address residential indicator | string | is, is not | Indicates whether this is a residential address. |
| From address residential indicator | string | is, is not | Indicates whether this is a residential address. |
| To country | string | is, is not | The [two-letter ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code |
| From country | string | is, is not | The [two-letter ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code |
| Warehouse ID | list | in, not in | The warehouse that the shipment is being shipped from |
| To postal code | list | in, not in, starts with | List of postal codes, separated by a comma |
| From postal code | list | in, not in, starts with | List of postal codes, separated by a comma |
| Number of packages | integer | is, is less than, is less or equal to, is greater than, is greater than or equal to | Number of packages of a shipment |
| Total weight | decimal | is, is less than, is less or equal to, is greater than, is greater than or equal to | Weight of a shipment. Available units: Gram, Kilogram, Pound, Ounce |
| Max dimension | decimal | is, is less than, is less or equal to, is greater than, is greater than or equal to | Dimension filter of any of the available dimensions of a shipment (height, width, length). Available units: centimeter, inch |
| Shipment value | decimal | is, is less than, is less or equal to, is greater than, is greater than or equal to | Shipment's product value sum |