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
array deprecated

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
object deprecated

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
object required

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
string required

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
string required

The type of Event that will trigger increments and completions of the Promotion.
params
object required

Type-specific parameters for the Promotion. See Promotion Params Model .
type
string required

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