ShipEngine's shipping rules allow you to define a set of conditions that determine which carrier and service a shipment will use, rather than assigning the carrier and service values within the shipment object of a Create Shipment or Purchase Label call.
This allows you to automate carrier and service selection for your shipments based on the criteria you've set for your specific workflow.
After creating your shipping rules, you'll use the shipping_rule_id property in the shipment object in place of both the carrier_id and service_code properties in your relevant API calls.
There are two types of shipping rules you can create:
-
Condition-based rules
-
Service group rules
Both types of rules use If/Then logic. The difference is how each type of shipping rule executes this logic.
In both cases, you create Statements where you define rule conditions. A statement can contain multiple conditions and a rule can contain multiple statements.
When a statement has multiple conditions, these conditions are additive, as in, they behave like AND statements. When a rule has multiple statements, each statement behaves like an ELSE IF statement. For condition-based rules, this means subsequent statements are only evaluated if the prior statement does not apply. For service group rules, all statements in a rule are evaluated.
With condition-based rules, you define explicit sets of conditions the shipment must meet for the service set in the statement to be allocated to that shipment.
Example statement:
-
IF total shipment weight is less than 2 kg
-
AND destination country equals GB (Great Britain)
-
AND if the maximum dimension is less than 1m
-
THEN allocate Yodel Next Day as the shipment's carrier and service
Condition-based rules also include a default service option (i.e., an ELSE statement). This means that if none of the statements in the rule are true then allocate the default carrier and service to the shipment instead.
With service group rules, you first create a list of services in a prioritized order. Then, you create statements with conditions that will exclude a service from the shipment if the shipment meets the statement conditions.
For example, your prioritized list of services includes service A (highest priority service), service B, service C, and service D (lowest priority service). You then define the following statements to exclude services from consideration:
-
If shipment weight is greater than 3kg, exclude service A
-
If shipment weight is greater than 5kg, exclude service D
-
If shipment destination is GB AND max dimension is greater than 1m, exclude service C.
If all three of these statements are true for a specific shipment, service B will be allocated to that shipment. If, after a rule is evaluated, there is more than one service in the priority list that could be applied, the highest priority service remaining in the list will be allocated to the shipment.
Currently, you must create and manage your shipping rules in the ShipEngine dashboard. However, we will soon be adding a shipping rules endpoint so you can create and manage your shipping rules programmatically.
Once created, each rule will have a shipping rule ID you can add to the shipment object for either Create Shipment or Purchase Label calls. For each shipment, ShipEngine will evaluate the rule statements against the shipment details and apply the appropriate carrier_id and service_code to the shipment for you.
To create a shipping rule:
-
Log in to your ShipEngine account and go to Shipping Rules.
-
Click Create rule.
-
Choose the type of rule you wish to create, condition or service group.
-
Enter a name for your rule (each rule requires a unique name).
-
Create the statements with the conditions you require (see below sections for details on creating each type of rule).
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.
-
Fill in the first condition for Statement 1.
-
Add more conditions if needed. Remember, additional conditions behave as AND statements.
-
Set the carrier and service that should apply to shipments meeting the statement conditions in the allocate fields.
-
Add more statements if needed. Remember, additional statements behave as ELSE IF statements.
-
Set the default carrier and service that will apply if the shipment does not meet the conditions for any of the rule statements.
-
Save the rule.
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.
-
Choose a carrier and select which of that carrier's services to include in your priority list.
-
Click the Add to list button to add this set of services to the list.
(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.
-
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.
-
Fill in the first condition for Statement 1.
-
Add more conditions if needed. Remember, additional conditions behave as AND statements.
-
Choose which services to exclude from shipments that meet the statement conditions.
-
Add more statements if needed. Remember, additional statements behave as ELSE IF statements.
-
Save the rule.
Once you have created your shipping rules, you will use the shipping_rule_id property in place of the carrier_id and service_code properties in your shipment object for any shipment you want the rule to apply to. You can use the shipping_rule_id property for both the Create Shipment and Purchase Label endpoints.
ShipEngine 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.
