/
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
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
19
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
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")
}
Create and manage custom messages
Learn how to 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:
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.