Rewards
Rewards in Allpage: its screens, what you can do there and its operations.
Availability. Works when the business has it turned on and its plan includes it. Otherwise its tools answer needs (kind module) with how to turn it on: business.useTool, or a plan that includes it.
Screens
- Rewards (/rewards)
What you can do
- Set up a loyalty program: the assistant asks you first
- Use a reward: the assistant can do it on its own
- Adjust a customer’s rewards balance: the assistant can do it on its own
- Pause or restart a rewards program: the assistant asks you first
Automations you can turn on
- Reward earned: Tells customers when they’ve earned a reward
For apps
Tools
- rewards_saveProgram (Set up a loyalty program): customers see it: waits for the owner’s approval unless they chose Just do it for your app
- rewards_redeem (Use a reward): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
- rewards_adjust (Adjust a customer’s rewards balance): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
- rewards_setActive (Pause or restart a rewards program): customers see it: waits for the owner’s approval unless they chose Just do it for your app
Reads
- rewards_summary (What’s going on)
The owner’s screens
- Rewards (/rewards)
Automations the owner can turn on
- Reward earned: Tells customers when they’ve earned a reward
Operations
Each one's input and output, as JSON Schema. Ids are typed (typed ids).
loyalty.adjust
Adjust a customer’s rewards balance
- Kind
- Change
- Tool
rewards_adjust- Scope
loyalty:write- Reached by
- API, MCP
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"slug": {
"type": "string",
"maxLength": 40
},
"customerId": {
"type": "string",
"pattern": "^cus_[0-9a-hjkmnp-tv-z]{26}$",
"description": "A customer id: cus_ and 26 letters and digits."
},
"amount": {
"type": "integer",
"minimum": -100000,
"maximum": 100000
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"slug",
"customerId",
"amount",
"reason"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}loyalty.redeem
Use a reward
- Kind
- Change
- Tool
rewards_redeem- Scope
loyalty:write- Reached by
- API, MCP
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"grantId": {
"type": "string",
"pattern": "^grt_[0-9a-hjkmnp-tv-z]{26}$",
"description": "A grant id: grt_ and 26 letters and digits."
}
},
"required": [
"grantId"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}loyalty.saveProgram
Set up a loyalty program
- Kind
- Change
- Tool
rewards_saveProgram- Scope
loyalty:write- Reached by
- API, MCP
customers see it: waits for the owner’s approval unless they chose Just do it for your app
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"slug": {
"type": "string",
"maxLength": 40
},
"params": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"earn": {
"type": "object",
"properties": {
"on": {
"type": "string",
"enum": [
"visit",
"spend"
]
},
"amount": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"productIds": {
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"pattern": "^prd_[0-9a-hjkmnp-tv-z]{26}$",
"description": "A product id: prd_ and 26 letters and digits."
}
},
"when": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"on",
"amount"
],
"additionalProperties": false
},
"threshold": {
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"reward": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"productId": {
"type": "string",
"pattern": "^prd_[0-9a-hjkmnp-tv-z]{26}$",
"description": "A product id: prd_ and 26 letters and digits."
},
"validDays": {
"type": "integer",
"minimum": 1,
"maximum": 3650
}
},
"required": [
"label"
],
"additionalProperties": false
}
},
"required": [
"name",
"earn",
"threshold",
"reward"
],
"additionalProperties": false
}
},
"required": [
"params"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "object",
"properties": {
"all": {
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
}
},
"required": [
"all"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"any": {
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
}
},
"required": [
"any"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"not": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"not"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"count": {
"type": "object",
"properties": {
"event": {
"type": "string",
"minLength": 1
},
"since": {
"anyOf": [
{
"type": "object",
"properties": {
"event": {
"type": "string",
"minLength": 1
}
},
"required": [
"event"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"days": {
"type": "integer",
"minimum": 1,
"maximum": 3650
}
},
"required": [
"days"
],
"additionalProperties": false
}
]
},
"where": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
}
}
},
"required": [
"event"
],
"additionalProperties": false
},
"gte": {
"type": "number"
},
"lte": {
"type": "number"
},
"eq": {
"type": "number"
}
},
"required": [
"count"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sum": {
"type": "object",
"properties": {
"event": {
"type": "string",
"minLength": 1
},
"since": {
"anyOf": [
{
"type": "object",
"properties": {
"event": {
"type": "string",
"minLength": 1
}
},
"required": [
"event"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"days": {
"type": "integer",
"minimum": 1,
"maximum": 3650
}
},
"required": [
"days"
],
"additionalProperties": false
}
]
},
"where": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
}
},
"field": {
"type": "string",
"minLength": 1
}
},
"required": [
"event",
"field"
],
"additionalProperties": false
},
"gte": {
"type": "number"
},
"lte": {
"type": "number"
},
"eq": {
"type": "number"
}
},
"required": [
"sum"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"daysSince": {
"type": "object",
"properties": {
"event": {
"type": "string",
"minLength": 1
}
},
"required": [
"event"
],
"additionalProperties": false
},
"gte": {
"type": "number"
},
"lte": {
"type": "number"
},
"eq": {
"type": "number"
}
},
"required": [
"daysSince"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"visited": {
"type": "object",
"properties": {
"offeringId": {
"description": "One offering’s visits only.",
"type": "string",
"pattern": "^off_[0-9a-hjkmnp-tv-z]{26}$"
},
"kind": {
"description": "One kind of offering only: class, appointment, workshop.",
"type": "string",
"pattern": "^[a-z_]{1,40}$"
},
"since": {
"type": "object",
"properties": {
"days": {
"type": "integer",
"minimum": 1,
"maximum": 3650
}
},
"required": [
"days"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"gte": {
"type": "number"
},
"lte": {
"type": "number"
},
"eq": {
"type": "number"
}
},
"required": [
"visited"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"daysSinceVisit": {
"type": "object",
"properties": {
"offeringId": {
"description": "One offering’s visits only.",
"type": "string",
"pattern": "^off_[0-9a-hjkmnp-tv-z]{26}$"
},
"kind": {
"description": "One kind of offering only: class, appointment, workshop.",
"type": "string",
"pattern": "^[a-z_]{1,40}$"
}
},
"additionalProperties": false
},
"gte": {
"type": "number"
},
"lte": {
"type": "number"
},
"eq": {
"type": "number"
}
},
"required": [
"daysSinceVisit"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"hasGrant": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"productId": {
"type": "string"
},
"benefit": {
"description": "A membership or pack by its benefit name: membership:gold.",
"type": "string",
"pattern": "^(membership|pack|pass):[a-z0-9][a-z0-9_-]{0,62}$"
}
},
"additionalProperties": false
}
},
"required": [
"hasGrant"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"balance": {
"type": "object",
"properties": {
"unit": {
"type": "string",
"minLength": 1
}
},
"required": [
"unit"
],
"additionalProperties": false
},
"gte": {
"type": "number"
},
"lte": {
"type": "number"
},
"eq": {
"type": "number"
}
},
"required": [
"balance"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"tag": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 40
}
},
"required": [
"name"
],
"additionalProperties": false
}
},
"required": [
"tag"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"channel": {
"type": "object",
"properties": {
"is": {
"type": "string",
"pattern": "^[a-z0-9_-]{1,40}$"
}
},
"required": [
"is"
],
"additionalProperties": false
}
},
"required": [
"channel"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"record": {
"type": "string",
"const": "customer"
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 40
}
},
"required": [
"record",
"key"
],
"additionalProperties": false
},
"is": {
"type": [
"string",
"number",
"boolean"
]
},
"gte": {
"type": "number"
},
"lte": {
"type": "number"
},
"exists": {
"type": "boolean"
}
},
"required": [
"field"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
}
},
"required": [
"key"
],
"additionalProperties": false
},
"is": {
"type": [
"string",
"number",
"boolean"
]
},
"gte": {
"type": "number"
},
"lte": {
"type": "number"
},
"exists": {
"type": "boolean"
}
},
"required": [
"state"
],
"additionalProperties": false
}
]
}
}
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}loyalty.setActive
Pause or restart a rewards program
- Kind
- Change
- Tool
rewards_setActive- Scope
loyalty:write- Reached by
- API, MCP
customers see it: waits for the owner’s approval unless they chose Just do it for your app
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"slug": {
"type": "string",
"maxLength": 40
},
"active": {
"type": "boolean"
}
},
"required": [
"slug",
"active"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}loyalty.summary
What’s going on
- Kind
- Read
- Tool
rewards_summary- Scope
loyalty:read- Reached by
- API, MCP
Read-only.
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}Output
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"facts": {
"type": "array",
"items": {
"type": "string"
},
"description": "One-line facts, e.g. \"3 bookings today\"."
},
"attention": {
"description": "Things that need the owner, each with a plain reason.",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"href": {
"type": "string"
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
}
},
"happening": {
"description": "What’s on today, each at its time.",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"at": {
"type": "number",
"description": "Epoch milliseconds."
},
"text": {
"type": "string"
},
"href": {
"type": "string"
}
},
"required": [
"id",
"at",
"text"
],
"additionalProperties": false
}
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"value": {
"type": "number"
},
"prior": {
"type": "number"
},
"unit": {
"type": "string",
"enum": [
"count",
"money"
]
},
"href": {
"type": "string"
}
},
"required": [
"id",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"title",
"facts"
],
"additionalProperties": false
}
},
"required": [
"status",
"title",
"change",
"result"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "refused"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
},
"required": [
"status",
"title",
"change",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "needs"
},
"kind": {
"type": "string",
"enum": [
"module",
"portal",
"business",
"limit",
"paused",
"reauth"
]
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
},
"required": [
"status",
"kind",
"title",
"change",
"message"
],
"additionalProperties": {}
}
]
}