Promotions - Centrapay Docs

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 cashback or challenge. challenge rewards the account once, after the challenge target is met. cashback gives a reward based on the payment amount, which can be completed an unlimited number of times.
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 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.
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.

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.
exchangeRate
number

The rate of exchange from payment amount to reward. Only supplied if Promotion is type cashback.

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.

POST /api/loyalty-programs/{id}/promotions

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 cashback or challenge. challenge rewards the account once, after the challenge target is met. cashback gives a reward based on the payment amount, which can be completed an unlimited number of times.
conditions
array

The list of Conditions that need to be met when incrementing/completing the Promotion.
description
string

Displayable description for the Promotion.

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."
}
'

{
  "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"
    }
  ],
  "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"
}

GET /api/accountId/{id}/promotions

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"
    }
  ]
}

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

Promotion Reward Model

Attributes

assetType

collectionId

name

img

amount

exchangeRate

Promotion Condition Model

Attributes

field

value

operator

Create Promotion experimental

Attributes

name

summary

mediaUploadId

startsAt

endsAt

rewards

eventType

target

type

conditions

description

Errors

PROMOTION_REWARDS_INVALID

List Promotions by Account experimental