DOCS

Managing rules

/

Advanced rules

COMING SOON

Zonos supports advanced customization of how calculations happen in your account through the use of rules. Rules can be used to add buffers to different parts of the calculation, customize fees, and more. For a full breakdown of how Zonos handles rules, including a list of all possible rule types, see our rules breakdown doc. Rules can be managed via Zonos Dashboard or through the GraphQL API.

Important: Rules are an advanced feature, and misuse can cause a variety of unintended consequences with how Zonos behaves and calculates for you.

View rules

Dashboard
GraphQL

To manage rules within the Dashboard:

  1. Log in to your Zonos Dashboard account.
  2. Navigate to Settings -> Rules.

On the “Rules” page, you can view all rules associated with your Zonos account, filter rules, and quickly enable or disable rules.

Create rules

Dashboard
GraphQL

To create a new rule within the Dashboard:

  1. Log in to your Zonos Dashboard account.
  2. Navigate to Settings -> rules.
  3. Click Create rule.
  4. Add a name to your rule so you can identify it later. These are only visible to team members in your organization.
  5. Follow the steps in the “Specify rule condition” section below to add a condition to your rule.
  6. Follow the steps in the “Specify rule action” section below to add an action to your rule.
  7. Optionally, you may add a comment for additional context. These are only visible to team members in your organization.
  8. Follow the steps below to add a specific start and/or end date for your rule (optional).
  9. Either set your rule to Enabled or Disabled.
  10. Click Save.

Specify start and end dates

Rules can optionally have a start date, an end date, or both. Start and end dates control when and how your rule becomes active and can be used to create rules that are only active for specific periods, such as seasonal discounts or other time-sensitive situations.

Rule behavior

DatesBehavior
Start and end dateRule will be active between the specified start and end date.
Only a start date, no end dateRule will become active after the specified start date and must be manually disabled.
No start or end dateRule will always be active unless manually disabled.

Specify rule condition

Every rule requires a condition to be specified to determine what it applies to and which variables are available at the time the rule runs. In other words, the condition determines if the rule should run at all and when. Different conditions have different options available.

For example, if you pick “Shipping carrier” as the condition, it allows you to additionally select which carrier is part of the condition, which you might use if you are setting up a buffer for only a specific carrier.

Rules only support one condition each, and do not support complex logic such as “else if”, “and/or”, or similar terms. If you want to chain rules, it is best to think of how you might achieve the same logic with multiple rules compared to one giant, complex rule.

Specify rule action

A rule’s action is what happens once its condition is met. Just like conditions, there are a variety of actions possible, each with different options.

For example, if you wanted to add a buffer to only a specific shipping carrier, you would set the action to “apply a buffer” and enter the amount of your buffer and what it applies to. You can then control which carrier exactly the buffer applies to by specifying that in the rule’s condition.

Just like conditions, rules only support one action each. If you want multiple actions, it is best to think of how you might achieve the same logic with multiple rules compared to one giant, complex rule.

Update rules

Updating rules in place is not possible with how our system works. This is because we need to keep a traceable history of which rules were applied in which situations and what the rule did when it ran. Alternatively, you can archive and recreate a rule, passing in the changed values, effectively achieving an “update” to the rule.

This example mutation shows how you might combine the archiveRule and createRule mutations to achieve this behavior:

Mutation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
mutation UpdateRule(
  $ruleId: ID!
  $action: String!
  $condition: String!
  $context: String!
  $description: String!
  $name: String!
) {
  archiveRule(id: $ruleId)
  createRule(
    input: {
      action: $action
      condition: $condition
      context: $context
      name: $name
      description: $description
    }
  ) {
    id
    action
    context
    condition
  }
}

Variables

1
2
3
4
5
6
7
8
{
  "ruleId": "rule_935ee1ca-0c4d-4147-826a-1cb0894d9f43",
  "action": "amount = amount + 5 % amount",
  "condition": "ship_to_country == CA",
  "context": "SHIPMENT_RATING_BUFFER",
  "description": "test",
  "name": "test"
}

Archive rules

Dashboard
GraphQL

Once added, rules can be easily enabled or disabled to determine if they should affect your calculations. Manually enabling or disabling a rule will override any start and end date-based logic contained within the rule.

Rules can be enabled or disabled on a one-by-one basis from the “Edit a rule” screen, or in bulk by using the checkboxes next to each rule on the “All rules” screen.

List all possible rule contexts

We offer some global queries for dealing with rules which are useful for discovering how rules work under the hood, creating UIs on top of rules, etc. These apply to all users, are not organization-specific, and are offered for convenience. This query returns a list of all possible contexts to which rules can belong. A rule context determines when a rule runs and what variables are available.

Query

1
2
3
4
5
6
7
8
9
10
query {
  ruleContexts {
    name
    context
    variables {
      ruleTokenType
      value
    }
  }
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  "data": {
    "ruleContexts": [
      {
        "name": "SHIPMENT_RATING_BUFFER",
        "context": "buffer",
        "variables": [
          {
            "ruleTokenType": "MONEY",
            "value": "amount"
          },
          {
            "ruleTokenType": "NUMBER",
            "value": "item_count"
          },
          {
            "ruleTokenType": "MONEY",
            "value": "items_total"
          },
          {
            "ruleTokenType": "COUNTRY",
            "value": "ship_from_country"
          },
          {
            "ruleTokenType": "COUNTRY",
            "value": "ship_to_country"
          },
          {
            "ruleTokenType": "WEIGHT",
            "value": "weight"
          },
          {
            "ruleTokenType": "STRING",
            "value": "service_level"
          },
          {
            "ruleTokenType": "STRING",
            "value": "carrier"
          }
        ]
      }
    ]
  }
}

Was this page helpful?