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

A list of Rewards that the account will receive upon completing the Promotion.
eventType
string

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

Describes how to complete the promotion. See Promotion Target .
type
string

The type of Promotion. Can be challenge. challenge rewards the account once, after the challenge target is met.
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 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 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.

Promotion Condition Model

Attributes

field
string

The field to look at in the Event object.
value
string

The value that the field must satisfy depending on the operator.
operator
string

The operator to use when looking at the value of the field. Can be equals, not, greater-than, less-than.
type
string

The type of condition. Can be participation-limit.

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.
rewards
array

A list of Rewards that the account will receive upon completing the Promotion.
eventType
string required

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

Describes how to complete the promotion. See Promotion Target . Only supplied if type is challenge.
type
string required

The type of Promotion. Can be challenge. challenge rewards the account once, after the challenge target is met.
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",
 "rewards": [
  {
   "assetType": "centrapay.nzd.main",
   "amount": "500"
  }
 ],
 "eventType": "payment",
 "target": {
  "type": "count",
  "amount": "1"
 },
 "type": "challenge",
 "conditions": [
  {
   "field": "amount",
   "value": "99",
   "operator": "greater-than"
  }
 ],
 "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"
  },
  "type": "challenge",
  "conditions": [
    {
      "field": "amount",
      "value": "99",
      "operator": "greater-than"
    }
  ],
  "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
  },
  "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
      },
      "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
      },
      "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"
    }
  ]
}

Promotion Model

Attributes

id

accountId

name

programId

summary

mediaUploadId

img

startsAt

endsAt

rewards

eventType

target

type

conditions

description

createdAt

createdBy

Promotion Target Model

Attributes

type

field

amount

progress

Promotion Reward Model

Attributes

assetType

collectionId

name

img

amount

totalSupply

remainingSupply

issued

Promotion Condition Model

Attributes

field

value

operator

type

Create Promotion experimental

Attributes

name

summary

mediaUploadId

startsAt

endsAt

rewards

eventType

target

type

conditions

description

repeatable

Errors

PROMOTION_REWARDS_INVALID

Get Promotion experimental

List Promotions by Account experimental

List Promotions by Loyalty Program experimental