DOCS

Custom messages

/
Checkout•
HomeGlobal ecommerce Integration Custom messages

Custom messages

Create and manage custom messages with GraphQL.

COMING SOON

Custom messages allow you to display a message to your shoppers based on a rule that you create. You can create custom messages for any situation, such as:

  • Orders going to a specific country
  • Orders over a certain amount
  • Restricted or prohibited items
  • Shipping delays
  • And more

Custom messages are displayed in Zonos Checkout and Zonos Hello, and can be translated into any language. This guide will show you how to create and manage custom messages via the API.

Create a custom message

To create a custom message via the API, you can create a Rule where the condition is when you want the message to be displayed and the action is to display the message with its content. This allows you to flexibly display all types of messages for different situations.

See our documentation on creating rules for more information on how to specify the condition and what kinds of variables are available.

Custom messages always use the rule context of CUSTOM_MESSAGE and the action of DISPLAY_MESSAGE to display the rule's description as the message. So for example, if you want to display a message for orders going to Canada, you can create a rule like this:

Mutation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
mutation {
  createRule(
    input: {
      action: "DISPLAY_MESSAGE"
      condition: ":countryCode: = CA"
      context: "CUSTOM_MESSAGE"
      description: "This will be seen by your Canadian shoppers"
      endsAt: null
      name: "Custom message for orders going to Canada"
      startsAt: "2023-05-18T00:00:00Z"
    }
  ) {
    rule {
      id
      name
      action
      condition
      context
    }
  }
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "data": {
    "createRule": {
      "rule": {
        "id": "rule_123456",
        "name": "Custom message for orders going to Canada",
        "action": "DISPLAY_MESSAGE",
        "condition": ":countryCode: = CA",
        "context": "CUSTOM_MESSAGE"
      }
    }
  }
}

Retrieve a custom message

To retrieve a custom message via the API, you can query for the Rule by its id:

Query

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
query {
  rule(id: "rule_123456") {
    id
    action
    condition
    context
    createdAt
    createdBy
    description
    endsAt
    mode
    name
    organization
    startsAt
    updatedAt
    updatedBy
  }
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "data": {
    "rule": {
      "id": "rule_123456",
      "action": "DISPLAY_MESSAGE",
      "condition": "order.total > 1000",
      "context": "CUSTOM_MESSAGE",
      "createdAt": "2023-05-18T00:00:00Z",
      "createdBy": "user_123456",
      "description": "Custom message for orders over $1000",
      "endsAt": null,
      "mode": "LIVE",
      "name": "Custom message for high value orders",
      "organization": "org_123456",
      "startsAt": "2023-05-18T00:00:00Z",
      "updatedAt": "2023-05-18T00:00:00Z",
      "updatedBy": "user_123456"
    }
  }
}

List custom messages

To get a list of all custom messages that you've created via the API, you can query for the Rules by their context:

Query

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
query {
  rulesByContext(filter: { context: "CUSTOM_MESSAGE" }) {
    edges {
      node {
        id
        action
        condition
        context
        createdAt
        createdBy
        description
        endsAt
        mode
        name
        organization
        startsAt
        updatedAt
        updatedBy
      }
    }
  }
}

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": {
    "rulesByContext": {
      "edges": [
        {
          "node": {
            "id": "rule_123456",
            "action": "DISPLAY_MESSAGE",
            "condition": "order.total > 1000",
            "context": "CUSTOM_MESSAGE",
            "createdAt": "2023-05-18T00:00:00Z",
            "createdBy": "user_123456",
            "description": "Custom message for orders over $1000",
            "endsAt": null,
            "mode": "LIVE",
            "name": "High Value Order Message",
            "organization": "org_123456",
            "startsAt": "2023-05-18T00:00:00Z",
            "updatedAt": "2023-05-18T00:00:00Z",
            "updatedBy": "user_123456"
          }
        },
        {
          "node": {
            "id": "rule_123457",
            "action": "DISPLAY_MESSAGE",
            "condition": "order.total < 10",
            "context": "CUSTOM_MESSAGE",
            "createdAt": "2023-05-18T00:00:00Z",
            "createdBy": "user_123457",
            "description": "Custom message for small orders",
            "endsAt": "2023-12-31T00:00:00Z",
            "mode": "LIVE",
            "name": "Small Order Message",
            "organization": "org_123457",
            "startsAt": "2023-05-18T00:00:00Z",
            "updatedAt": "2023-05-18T00:00:00Z",
            "updatedBy": "user_123457"
          }
        }
      ]
    }
  }
}

Update a custom message

Rules are immutable, so to update a custom message via the API, you can create a new Rule with the same context and action as the original Rule and archive the original Rule:

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 UpdateCustomMessage {
  createRule(
    input: {
      action: "DISPLAY_MESSAGE"
      condition: "order.total > 500"
      context: "CUSTOM_MESSAGE"
      description: "Updated custom message for orders over $500"
      endsAt: null
      name: "Updated Custom Message for Medium Value Orders"
      startsAt: "2023-05-19T00:00:00Z"
    }
  ) {
    rule {
      id
      name
      action
      condition
      context
    }
  }
  archiveRule(id: "rule_123456") {
    result
  }
}

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
{
  "data": {
    "createRule": {
      "rule": {
        "action": "DISPLAY_MESSAGE",
        "condition": "order.total > 500",
        "context": "CUSTOM_MESSAGE",
        "createdAt": "2023-05-19T00:00:00Z",
        "createdBy": "user_123456",
        "description": "Updated custom message for orders over $500",
        "endsAt": null,
        "id": "rule_123457",
        "mode": "LIVE",
        "name": "Updated Custom Message for Medium Value Orders",
        "organization": "org_123456",
        "startsAt": "2023-05-19T00:00:00Z",
        "updatedAt": "2023-05-19T00:00:00Z",
        "updatedBy": "user_123456"
      }
    },
    "archiveRule": {
      "result": "SUCCESS"
    }
  }
}

Delete a custom message

To delete a custom message via the API, you can archive the Rule by its id:

Mutation

1
2
3
mutation {
  archiveRule(id: "rule_123456")
}

Was this page helpful?

Questions?

Contact us.
© 2024 Zonoszonos.com
On this page:
  • Custom messages
  • Create a custom message
  • Retrieve a custom message
  • List custom messages
  • Update a custom message
  • Delete a custom message