{"templateId":"markdown","versions":[{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/shipping/shipping-rules-guide","default":false,"active":false,"folderId":"58c9a61d"},{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/docs/shipping/shipping-rules-guide","default":true,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/shipping/shipping-rules-guide","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Shipping Rules Guide","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"shipping-rules-guide","__idx":0},"children":["Shipping Rules Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For each shipment, ShipStation API will evaluate the rule statements against the shipment details and apply the appropriate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]}," to the shipment for you."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Shipping Rules Endpoints Coming Soon"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-shipping-rule","__idx":1},"children":["Create a Shipping Rule"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a shipping rule:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log into your account dashboard and go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Shipping Rules"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create rule"]}," button."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Choose the type of rule you wish to create, condition or service group."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter a name for your rule (each rule requires a unique name)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create the statements with the conditions you require (see below sections for details on creating each type of rule)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"condition-based-rules","__idx":2},"children":["Condition-based Rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a condition-based rule:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fill in the first condition for Statement 1."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add more conditions if needed. Remember, additional conditions behave as AND statements."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set the carrier and service that should apply to shipments meeting the statement conditions in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["allocate"]}," fields."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add more statements if needed. Remember, additional statements behave as ELSE IF statements."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set the default carrier and service that will apply if the shipment does not meet the conditions for any of the rule statements."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Save the rule."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"service-group-rules","__idx":3},"children":["Service Group Rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With service group rules, you first create a list of services in a prioritized order. Then, you create \"exclusion statements\" with conditions that will ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["exclude"]}," a service from the shipment if the shipment meets the statement conditions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a service group rule:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Choose a carrier and select which of that carrier's services to include in your priority list."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add to list"]}," button to add this set of services to the list."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["(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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fill in the first condition for Statement 1."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add more conditions if needed. Remember, additional conditions behave as AND statements."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Choose which services to exclude from shipments that meet the statement conditions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add more statements if needed. Remember, additional statements behave as ELSE IF statements."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Save the rule."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"apply-rules-to-your-shipments","__idx":4},"children":["Apply Rules to Your Shipments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have created your shipping rules, you will use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping_rule_id"]}," as a path parameter in the dedicated endpoint to purchase labels. For creating shipments, you can include the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping_rule_id"]}," in the shipment object for the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/shipments/create"},"children":["Create Shipment"]}," endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When purchasing a label with a shipping rule, you must NOT include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping_rule_id"]}," in the shipment object — the shipping rule determines these automatically."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ShipStation API will evaluate the shipping rule provided in the request to determine the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]}," that should apply to the shipment. Both will then be included in the corresponding response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-shipment-example-request","__idx":5},"children":["Create Shipment Example Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is an example of the shipment object in a request for ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/shipments/create"},"children":["Creating a Shipment"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v2/shipments"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v2/shipments HTTP/1.1\nHost: api.shipstation.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n \"shipments\": [\n  {\n   \"shipping_rule_id\": \"se-49\",\n   \"ship_to\": {\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"name\": \"Jane Doe\",\n      \"phone\": \"+1 444-444-4444\"\n    },\n   \"ship_from\": {\n      \"address_line1\": \"4301 Bull Creek Rd\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78731\",\n      \"country_code\": \"US\",\n      \"name\": \"John Doe\",\n      \"phone\": \"+1 555-555-5555\"\n    },\n   \"packages\": [\n     {\n      \"weight\": {\n        \"value\": 20,\n        \"unit\": \"ounce\"\n       },\n      \"dimensions\": {\n        \"height\": 6,\n        \"width\": 12,\n        \"length\": 24,\n        \"unit\": \"inch\"\n      }\n    }\n   ]\n  }\n ]\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"purchase-label-example-request","__idx":6},"children":["Purchase Label Example Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is an example of the request for ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/create-labels"},"children":["Purchasing a Label"]}," using a shipping rule. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping_rule_id"]}," is passed as a path parameter, and the shipment object must NOT include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping_rule_id"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v2/labels/shipping_rules/{shipping_rule_id}"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v2/labels/shipping_rules/se-49 HTTP/1.1\nHost: api.shipstation.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n \"shipment\": {\n   \"ship_to\": {\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"name\": \"Jane Doe\",\n      \"phone\": \"+1 444-444-4444\"\n    },\n   \"ship_from\": {\n      \"address_line1\": \"4301 Bull Creek Rd\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78731\",\n      \"country_code\": \"US\",\n      \"name\": \"John Doe\",\n      \"phone\": \"+1 555-555-5555\"\n    },\n   \"packages\": [\n     {\n      \"weight\": {\n        \"value\": 20,\n        \"unit\": \"ounce\"\n       },\n      \"dimensions\": {\n        \"height\": 6,\n        \"width\": 12,\n        \"length\": 24,\n        \"unit\": \"inch\"\n      }\n    }\n   ]\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"available-condition-properties","__idx":7},"children":["Available Condition Properties"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following identifiers are currently available to use in your statement conditions:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Identifier"},"children":["Identifier"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value Type"},"children":["Value Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Available Operators"},"children":["Available Operators"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["To address residential indicator"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["is, is not"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether this is a residential address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["From address residential indicator"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["is, is not"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether this is a residential address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["To country"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["is, is not"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://en.wikipedia.org/wiki/ISO_3166-1"},"children":["two-letter ISO 3166-1"]}," country code"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["From country"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["is, is not"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://en.wikipedia.org/wiki/ISO_3166-1"},"children":["two-letter ISO 3166-1"]}," country code"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Warehouse ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["list"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["in, not in"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The warehouse that the shipment is being shipped from"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["To postal code"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["list"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["in, not in, starts with"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List of postal codes, separated by a comma"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["From postal code"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["list"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["in, not in, starts with"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List of postal codes, separated by a comma"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of packages"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["is, is less than, is less or equal to, is greater than, is greater than or equal to"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of packages of a shipment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total weight"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["decimal"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["is, is less than, is less or equal to, is greater than, is greater than or equal to"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Weight of a shipment. Available units: Gram, Kilogram, Pound, Ounce"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Max dimension"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["decimal"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["is, is less than, is less or equal to, is greater than, is greater than or equal to"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dimension filter of any of the available dimensions of a shipment (height, width, length). Available units: centimeter, inch"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shipment value"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["decimal"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["is, is less than, is less or equal to, is greater than, is greater than or equal to"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shipment's product value sum"]}]}]}]}]}]},"headings":[{"value":"Shipping Rules Guide","id":"shipping-rules-guide","depth":1},{"value":"Create a Shipping Rule","id":"create-a-shipping-rule","depth":2},{"value":"Condition-based Rules","id":"condition-based-rules","depth":3},{"value":"Service Group Rules","id":"service-group-rules","depth":3},{"value":"Apply Rules to Your Shipments","id":"apply-rules-to-your-shipments","depth":2},{"value":"Create Shipment Example Request","id":"create-shipment-example-request","depth":3},{"value":"Purchase Label Example Request","id":"purchase-label-example-request","depth":3},{"value":"Available Condition Properties","id":"available-condition-properties","depth":2}],"frontmatter":{"slug":"/shipping-rules-guide","seo":{"title":"Shipping Rules Guide"}},"lastModified":"2026-05-20T15:46:34.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/shipping-rules-guide","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}