TAtalon
Loyalty

Import loyalty points

[!note] Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Upload a CSV file containing the loyalty points you want to import into a given loyalty program.

Send the file as multipart data.

Depending on the type of loyalty program, you can import points into a given customer profile or loyalty card.

The CSV file contains the following columns:

  • customerprofileid (optional): For profile-based loyalty programs, the integration ID of the customer profile where the loyalty points are imported. Note: If the customer profile does not exist, it will be created. The profile will not be visible in any Application until a session or profile update is received for that profile.

  • identifier (optional): For card-based loyalty programs, the identifier of the loyalty card where the loyalty points are imported.

  • amount: The amount of points to award to the customer profile.

  • startdate (optional): The earliest date when the points can be redeemed. The points are active from this date until the expiration date. This parameter accepts one of the following values:

    • A timestamp string in RFC3339 format.
    • immediate
    • on_action Note: Empty or missing values default to immediate.

  • expirydate (optional): The latest date when the points can be redeemed. The points are expired after this date. Note: It must be an RFC3339 timestamp string or string unlimited. Empty or missing values are considered unlimited. If passed, validityDuration should be omitted.

  • validityDuration (optional): The duration for which the points remain active, relative to the activation date. The time format is an integer followed by one letter indicating the time unit.<br /> Examples: 30s, 40m, 1h, 5D, 7W, 10M, 15Y.

    Available units:

    • s: seconds
    • m: minutes
    • h: hours
    • D: days
    • W: weeks
    • M: months
    • Y: years

    You can round certain units up or down:

    • _D for rounding down days only. Signifies the start of the day.
    • _U for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.

    If passed, expirydate should be omitted.

  • subledgerid (optional): The ID of the subledger that should received the points.

  • reason (optional): The reason why these points are awarded.

You can use the time zone of your choice. It is converted to UTC internally by Talon.One.

[!note] For existing customer profiles and loyalty cards, the imported points are added to any previous active or pending points, depending on the value provided for startdate. If startdate matches the current date, the imported points are active. If it is later, the points are pending until the date provided for startdate is reached.

[!note] We recommend limiting your file size to 500 MB.

Example for profile-based programs

customerprofileid,amount,startdate,expirydate,subledgerid,reason
URNGV8294NV,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement

Example for card-based programs

identifier,amount,startdate,expirydate,subledgerid,reason
summer-loyalty-card-0543,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement
post/v1/loyalty_programs/{loyaltyProgramId}/import_points

Request

Path parameters

loyaltyProgramIdinteger required

Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint.

Query parameters

notificationsEnabledboolean

Indicates whether the points import triggers notifications about its effects. For example, a notification is sent if the import upgrades a customer's tier or offsets their negative points balance.

This parameter is optional and defaults to true.

Request body multipart/form-data

upFilestring binary

The CSV file containing the data that is being imported.

Response

OK

idinteger required

The internal ID of this entity.

createdstring date-time required

The time this entity was created.

accountIdinteger required

The ID of the account that owns this entity.

userIdinteger required

The ID of the user associated with this entity.

entitystring required

The name of the entity that was imported.

amountinteger required

The number of values that were imported.

Example response

{
  "id": 6,
  "created": "2020-06-10T09:05:27.993483Z",
  "accountId": 3886,
  "userId": 388,
  "entity": "AttributeAllowedList",
  "amount": 10
}

Changes

No recorded changes to this operation across all 2 revisions of this API.