Go to home page
Docs

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  API  that owns the Promotion.

  • name

    string

    The display name of the Promotion.

  • programId

    string

    The ID of the Loyalty Program  API  that the Promotion belongs to.

  • description

    string

    The display description for the Promotion.

  • mediaUploadId

    string

    The ID of the Media Upload  API  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  API  that the account will receive upon completing the Promotion.

  • eventType

    string

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

  • target

    object

    Describes how to complete the promotion. See Promotion Target  API .

  • 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  API  that need to be met when incrementing/completing 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  API  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  API  to reward.

  • collectionId

    string

    The ID of the Token Collection  API  that should be rewarded. Only supplied if assetType is centrapay.token.test or centrapay.token.main.

  • 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  API  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

    stringrequired

    The display name of the Promotion.

  • description

    string

    The display description for the Promotion.

  • mediaUploadId

    string

    The ID of the Media Upload  API  image of the Promotion.

  • startsAt

    timestamp

    The timestamp of when the Promotion starts.

  • endsAt

    timestamp

    The timestamp of when the Promotion ends.

  • rewards

    arrayrequired

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

  • eventType

    stringrequired

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

  • target

    object

    Describes how to complete the promotion. See Promotion Target  API .

  • type

    stringrequired

    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  API  that need to be met when incrementing/completing the Promotion.

Errors

  • PROMOTION_REWARDS_INVALID

    403

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

Request
POST/api/loyalty-programs/WRhAxxWpTKb5U7pXyxQjjY/promotions
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",
 "description": "Make a payment of $1 or more",
 "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"
  }
 ]
}
'
Response
{
  "id": "8aoMfscvtuewsuJzmzBzAs",
  "accountId": "57SyRRgZ1U8Kq2wKpCnSR5",
  "programId": "WRhAxxWpTKb5U7pXyxQjjY",
  "name": "Spend a Buck",
  "description": "Make a payment of $1 or more",
  "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"
}
GET/api/accountId/{id}/promotions

List Promotions by Account experimental

Returns a paginated  API  list of Promotions for an Account  API .

Request
GET/api/accounts/57SyRRgZ1U8Kq2wKpCnSR5/promotions
curl -X GET \
 https://service.centrapay.com/api/accounts/57SyRRgZ1U8Kq2wKpCnSR5/promotions \
 -H 'x-api-key: <TOKEN>'
Response
{
  "items": [
    {
      "id": "8aoMfscvtuewsuJzmzBzAs",
      "accountId": "57SyRRgZ1U8Kq2wKpCnSR5",
      "programId": "WRhAxxWpTKb5U7pXyxQjjY",
      "name": "Spend a Buck",
      "description": "Make a payment of $1 or more",
      "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"
    }
  ]
}