Promotions

Promotions are a mechanism to reward accounts for completing certain actions.

Promotion Model

Attributes

id
string
The unique identifier for the Promotion.
accountId
string
The ID of the Account that owns the Promotion.
name
string
The display name of the Promotion.
programId
string
The ID of the Loyalty Program that the Promotion belongs to.
summary
string
The display summary for the Promotion.
mediaUploadId
string
The ID of the Media Upload image of the Promotion.
img
string
The img URL of the Promotion.
startsAt
timestamp
The timestamp of when the Promotion starts.
endsAt
timestamp
The timestamp of when the Promotion ends.
rewards
arraydeprecated
Use params.rewards instead. A flattened list of Rewards that the account will receive upon completing the Promotion. Retained on responses for backwards compatibility.
eventType
string
The type of Event that will trigger increments and completions of the Promotion.
params
object
Type-specific parameters for the Promotion. See Promotion Params Model.
target
objectdeprecated
Use params.target instead. Retained on responses for backwards compatibility. See Promotion Target.
type
string
The type of Promotion. Can be challenge or draw. challenge rewards the account once, after the challenge target is met. draw collects entrants and selects winner(s) once the entrant count is within the configured bounds.
conditions
array
The list of Conditions that need to be met when incrementing/completing the Promotion.
description
string
Displayable description for the Promotion.
createdAt
string
The timestamp of when the Promotion was created.
createdBy
crn
The User or API Key that created the Promotion.

Promotion Params Model

The shape of params depends on the Promotion's type.

Challenge Params

Attributes

target
object
Describes how to complete the promotion. See Promotion Target.
rewards
object
Describes the rewards the account will receive upon completing the Promotion. See Promotion Rewards Model.

Draw Params

Attributes

rewards
object
Describes the rewards that will be issued to the drawn winner(s). See Promotion Rewards Model.
progress
objectrequired
The entrant bounds for the draw. See Promotion Progress Model.

Promotion Progress Model

Attributes

minimum
number
The minimum progress required to be eligible for the rewards.
maximum
number
The maximum progress a single account can get.

Promotion Target Model

Attributes

type
string
Can be count, shared or sum. count if the progress should be incremented by 1 each time. sum if the progress should be summed from the specified field property. shared if the progress should be shared with other accounts that have memberships to the same Promotion.
field
string
Only supplied if type is sum. This denotes which field to sum on the Event to reach the target amount.
amount
number
The chosen number to reach for completion of the Promotion.
progress
number
The shared progress of the Promotion.

Promotion Rewards Model

Rewards are expressed as a tree of and/or groups rather than a flat list, so that rewards can be grouped for conditional logic. Each item in the group's array is either a leaf Promotion Reward or another nested Promotion Rewards group. For challenge promotions, every leaf reward in the tree is issued when the Promotion is completed, so only and is allowed. For draw promotions, or is also allowed, to be used once winner selection logic decides which branch of rewards is issued; a group must have exactly one of and or or.

Attributes

and
array
A list of Promotion Rewards and/or nested Promotion Rewards groups, all of which are issued. Mutually exclusive with or.
or
array
A list of Promotion Rewards and/or nested Promotion Rewards groups, of which one branch is issued. Only supplied if the Promotion's type is draw. Mutually exclusive with and.

Promotion Reward Model

Attributes

assetType
string
The assetType to reward.
collectionId
string
The ID of the Token Collection that should be rewarded. Only supplied if assetType is centrapay.token.test or centrapay.token.main.
name
string
The name of the Token Collection that is being rewarded.
img
string
The image of the Token Collection that is being rewarded.
amount
number
The amount of the chosen asset to reward. Only supplied if Promotion is type challenge.
totalSupply
string
The total number of rewards to be issued.
remainingSupply
string
The remaining number of rewards to be issued.
issued
boolean
When the promotion is completed, issued shows whether the reward was issued to the account.
issuedToAccountIds
array
The IDs of the accounts this reward was issued to. Only supplied once the draw for a draw Promotion has been run. An empty array means the reward went unclaimed. Where a reward is grouped with and, every reward in the group lists the same accounts, since a winner of that group receives all of them.

Promotion Condition Model

Attributes

field
string
The field to look at in the Event object. Required unless type is set, in which case it is not allowed.
value
string
The value that the field must satisfy depending on the operator. Must be an array of strings when using the in operator.
operator
string
The operator to use when looking at the value of the field. Can be equals, not, in, greater-than, less-than.
type
string
The type of condition. Can be participation-limit, merchantId, or merchantAccountId.

Promotion Activity Model

Attributes

id
string
The unique identifier for the Promotion Activity.
activityType
string
The type of activity.
promotionId
string
The ID of the Promotion that the activity belongs to.
programId
string
The ID of the Loyalty Program that the Promotion belongs to.
accountId
string
The ID of the Account that triggered the activity.
targetProgress
string
The shared progress of the Promotion at the time of the activity.
status
string
The status of the Promotion at the time of the activity.
createdAt
timestamp
The timestamp of when the activity was created.
createdBy
crn
The User or API Key that created the activity.

Create Promotion experimental

Attributes

name
stringrequired
The display name of the Promotion.
summary
string
The display summary for the Promotion.
mediaUploadId
string
The ID of the Media Upload image of the Promotion.
startsAt
timestamp
The timestamp of when the Promotion starts.
endsAt
timestamp
The timestamp of when the Promotion ends.
eventType
stringrequired
The type of Event that will trigger increments and completions of the Promotion.
params
objectrequired
Type-specific parameters for the Promotion. See Promotion Params Model.
type
stringrequired
The type of Promotion. Can be challenge or draw. challenge rewards the account once, after the challenge target is met. draw collects entrants and selects winner(s) once the entrant count is within the configured bounds.
conditions
array
The list of Conditions that need to be met when incrementing/completing the Promotion.
description
string
Displayable description for the Promotion.
repeatable
boolean
Flag indicating that the promotion will reward itself upon completion. This will mean that members can complete the promotion an unlimited number of times.

Errors

PROMOTION_REWARDS_INVALID
403
One or more of the rewards ledgers does not exist or permissions are invalid.

curl -X POST https://service.centrapay.com/api/loyalty-programs/WRhAxxWpTKb5U7pXyxQjjY/promotions \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "name": "Spend a Buck",
  "summary": "Make a payment",
  "mediaUploadId": "26yUWG6wFgmva8UaDiCTWq",
  "startsAt": "2023-02-16T00:47:54.131Z",
  "endsAt": "2024-02-16T00:47:54.131Z",
  "eventType": "payment",
  "params": {
    "target": {
      "type": "count",
      "amount": "1"
    },
    "rewards": {
      "and": [
        {
          "assetType": "centrapay.nzd.main",
          "amount": "500"
        }
      ]
    }
  },
  "type": "challenge",
  "conditions": [
    {
      "field": "amount",
      "value": "99",
      "operator": "greater-than"
    },
    {
      "type": "merchantId",
      "value": "5ee0c486308f590260d9a07f",
      "operator": "equals"
    }
  ],
  "description": "The amount of the payment must be greater than $1.",
  "repeatable": true
}'

{
  "id": "8aoMfscvtuewsuJzmzBzAs",
  "accountId": "57SyRRgZ1U8Kq2wKpCnSR5",
  "programId": "WRhAxxWpTKb5U7pXyxQjjY",
  "name": "Spend a Buck",
  "summary": "Make a payment",
  "mediaUploadId": "26yUWG6wFgmva8UaDiCTWq",
  "img": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743",
  "startsAt": "2023-02-16T00:47:54.131Z",
  "endsAt": "2024-02-16T00:47:54.131Z",
  "rewards": [
    {
      "assetType": "centrapay.nzd.main",
      "amount": "500"
    },
    {
      "promotionId": "8aoMfscvtuewsuJzmzBzAs"
    }
  ],
  "eventType": "payment",
  "target": {
    "type": "count",
    "amount": "1"
  },
  "params": {
    "target": {
      "type": "count",
      "amount": "1"
    },
    "rewards": {
      "and": [
        {
          "assetType": "centrapay.nzd.main",
          "amount": "500"
        },
        {
          "promotionId": "8aoMfscvtuewsuJzmzBzAs"
        }
      ]
    }
  },
  "type": "challenge",
  "conditions": [
    {
      "field": "amount",
      "value": "99",
      "operator": "greater-than"
    },
    {
      "type": "merchantId",
      "field": "merchantId",
      "value": "5ee0c486308f590260d9a07f",
      "operator": "equals"
    }
  ],
  "description": "The amount of the payment must be greater than $1.",
  "createdAt": "2023-02-08T04:04:27.426Z",
  "createdBy": "crn::user:1234",
  "updatedAt": "2023-02-08T04:04:27.426Z",
  "updatedBy": "crn::user:1234",
  "repeatable": true
}

Get Promotion experimental

Allows the user to get a Promotion

curl -X GET https://service.centrapay.com/api/promotions/8aoMfscvtuewsuJzmzBzAs \
-H 'x-api-key: <TOKEN>'

{
  "id": "8aoMfscvtuewsuJzmzBzAs",
  "accountId": "57SyRRgZ1U8Kq2wKpCnSR5",
  "programId": "WRhAxxWpTKb5U7pXyxQjjY",
  "name": "Spend a Buck",
  "summary": "Make a payment",
  "description": "The amount of the payment must be greater than $1.",
  "mediaUploadId": "26yUWG6wFgmva8UaDiCTWq",
  "img": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743",
  "startsAt": "2023-02-16T00:47:54.131Z",
  "endsAt": "2024-02-16T00:47:54.131Z",
  "rewards": [
    {
      "assetType": "centrapay.nzd.main",
      "amount": "500"
    }
  ],
  "eventType": "payment",
  "target": {
    "type": "count",
    "amount": 1
  },
  "params": {
    "target": {
      "type": "count",
      "amount": 1
    },
    "rewards": {
      "and": [
        {
          "assetType": "centrapay.nzd.main",
          "amount": "500"
        }
      ]
    }
  },
  "type": "challenge",
  "conditions": [
    {
      "field": "amount",
      "value": "100",
      "operator": "greater-than"
    }
  ],
  "createdAt": "2023-02-08T04:04:27.426Z",
  "createdBy": "crn::user:1234",
  "updatedAt": "2023-02-08T04:04:27.426Z",
  "updatedBy": "crn::user:1234"
}

List Promotions by Account experimental

Returns a paginated list of Promotions for an Account.

curl -X GET https://service.centrapay.com/api/accounts/57SyRRgZ1U8Kq2wKpCnSR5/promotions \
-H 'x-api-key: <TOKEN>'

{
  "items": [
    {
      "id": "8aoMfscvtuewsuJzmzBzAs",
      "accountId": "57SyRRgZ1U8Kq2wKpCnSR5",
      "programId": "WRhAxxWpTKb5U7pXyxQjjY",
      "name": "Spend a Buck",
      "summary": "Make a payment",
      "description": "The amount of the payment must be greater than $1.",
      "mediaUploadId": "26yUWG6wFgmva8UaDiCTWq",
      "img": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743",
      "startsAt": "2023-02-16T00:47:54.131Z",
      "endsAt": "2024-02-16T00:47:54.131Z",
      "rewards": [
        {
          "assetType": "centrapay.nzd.main",
          "amount": "500"
        }
      ],
      "eventType": "payment",
      "target": {
        "type": "count",
        "amount": 1
      },
      "params": {
        "target": {
          "type": "count",
          "amount": 1
        },
        "rewards": {
          "and": [
            {
              "assetType": "centrapay.nzd.main",
              "amount": "500"
            }
          ]
        }
      },
      "type": "challenge",
      "conditions": [
        {
          "field": "amount",
          "value": "99",
          "operator": "greater-than"
        }
      ],
      "createdAt": "2023-02-08T04:04:27.426Z",
      "createdBy": "crn::user:1234",
      "updatedAt": "2023-02-08T04:04:27.426Z",
      "updatedBy": "crn::user:1234"
    }
  ]
}

List Promotions by Loyalty Program experimental

Returns a list of Promotions for a Loyalty Program.

curl -X GET https://service.centrapay.com/api/loyalty-programs/WRhAxxWpTKb5U7pXyxQjjY/promotions \
-H 'x-api-key: <TOKEN>'

{
  "items": [
    {
      "id": "8aoMfscvtuewsuJzmzBzAs",
      "accountId": "57SyRRgZ1U8Kq2wKpCnSR5",
      "programId": "WRhAxxWpTKb5U7pXyxQjjY",
      "name": "Spend a Buck",
      "summary": "Make a payment",
      "description": "The amount of the payment must be greater than $1.",
      "mediaUploadId": "26yUWG6wFgmva8UaDiCTWq",
      "img": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743",
      "startsAt": "2023-02-16T00:47:54.131Z",
      "endsAt": "2024-02-16T00:47:54.131Z",
      "rewards": [
        {
          "assetType": "centrapay.nzd.main",
          "amount": "500"
        }
      ],
      "eventType": "payment",
      "target": {
        "type": "count",
        "amount": 1
      },
      "params": {
        "target": {
          "type": "count",
          "amount": 1
        },
        "rewards": {
          "and": [
            {
              "assetType": "centrapay.nzd.main",
              "amount": "500"
            }
          ]
        }
      },
      "type": "challenge",
      "conditions": [
        {
          "field": "amount",
          "value": "100",
          "operator": "greater-than"
        }
      ],
      "createdAt": "2023-02-08T04:04:27.426Z",
      "createdBy": "crn::user:1234",
      "updatedAt": "2023-02-08T04:04:27.426Z",
      "updatedBy": "crn::user:1234"
    }
  ]
}

List Activities for Promotion experimental

Returns a paginated list of Promotion Activities for a Promotion.

curl -X GET https://service.centrapay.com/api/promotions/8aoMfscvtuewsuJzmzBzAs/activities \
-H 'x-api-key: <TOKEN>'

{
  "items": [
    {
      "id": "WRhAxxWpTKb5U7pXyxQjjY",
      "activityType": "promotion:created",
      "promotionId": "8aoMfscvtuewsuJzmzBzAs",
      "programId": "WRhAxxWpTKb5U7pXyxQjjY",
      "createdAt": "2023-02-08T04:04:27.426Z"
    },
    {
      "id": "26yUWG6wFgmva8UaDiCTWq",
      "activityType": "promotion:shared-progress-incremented",
      "promotionId": "8aoMfscvtuewsuJzmzBzAs",
      "programId": "WRhAxxWpTKb5U7pXyxQjjY",
      "accountId": "57SyRRgZ1U8Kq2wKpCnSR5",
      "targetProgress": "1",
      "createdAt": "2023-06-14T12:30:00.000Z"
    },
    {
      "id": "DKTs3U38hdhfEqwF1JKoT2",
      "activityType": "promotion:ended",
      "promotionId": "8aoMfscvtuewsuJzmzBzAs",
      "createdBy": "crn::user:1234",
      "createdAt": "2024-02-16T00:47:54.131Z",
      "status": "ended"
    }
  ],
  "nextPageKey": "DKTs3U38hdhfEqwF1JKoT2"
}

Promotion Model

Attributes

id

accountId

name

programId

summary

mediaUploadId

img

startsAt

endsAt

rewards

eventType

params

target

type

conditions

description

createdAt

createdBy

Promotion Params Model

Challenge Params

Attributes

target

rewards

Draw Params

Attributes

rewards

progress

Promotion Progress Model

Attributes

minimum

maximum

Promotion Target Model

Attributes

type

field

amount

progress

Promotion Rewards Model

Attributes

and

or

Promotion Reward Model

Attributes

assetType

collectionId

name

img

amount

totalSupply

remainingSupply

issued

issuedToAccountIds

Promotion Condition Model

Attributes

field

value

operator

type

Promotion Activity Model

Attributes

id

activityType

promotionId

programId

accountId

targetProgress

status

createdAt

createdBy

Create Promotion experimental

Attributes

name

summary

mediaUploadId

startsAt

endsAt

eventType

params