TAtalon
Achievements

Create achievement

Changed on

[!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.

Create a new achievement in a specific campaign.

post/v1/applications/{applicationId}/campaigns/{campaignId}/achievements

Request

Path parameters

applicationIdinteger required

The ID of the Application. It is displayed in your Talon.One deployment URL.

campaignIdinteger required

The ID of the campaign. It is displayed in your Talon.One deployment URL.

Request body

namestring required

The internal name of the achievement used in API requests.

Note: The name should start with a letter. This cannot be changed after the achievement has been created.

titlestring required

The display name for the achievement in the Campaign Manager.

descriptionstring string required

A description of the achievement.

targetnumber required

The required number of actions or the transactional milestone to complete the achievement.

periodstring

The relative duration after which the achievement ends and resets for a particular customer profile.

Note: The period does not start when the achievement is created.

The period is a positive real number followed by one letter indicating the time unit.

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 also round certain units down to the beginning of period and up to the end of period.:

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

Note: You can either use the round down and round up option or set an absolute period.

recurrencePolicy'no_recurrence' | 'on_expiration' | 'on_completion'

The policy that determines if and how the achievement recurs.

  • no_recurrence: The achievement can be completed only once.
  • on_expiration: The achievement resets after it expires and becomes available again.
  • on_completion: When the customer progress status reaches completed, the achievement resets and becomes available again.
activationPolicy'user_action' | 'fixed_schedule'

The policy that determines how the achievement starts, ends, or resets.

  • user_action: The achievement ends or resets relative to when the customer started the achievement.
  • fixed_schedule: The achievement starts, ends, or resets for all customers following a fixed schedule.
fixedStartDatestring date-time

The achievement's start date when activationPolicy is set to fixed_schedule.

Note: It must be an RFC3339 timestamp string.

endDatestring date-time

The achievement's end date. If defined, customers cannot participate in the achievement after this date.

Note: It must be an RFC3339 timestamp string.

allowRollbackAfterCompletionboolean

When true, customer progress can be rolled back in completed achievements.

Example request

{
  "name": "Order50Discount",
  "title": "50% off on 50th purchase.",
  "description": "50% off for every 50th purchase in a year.",
  "target": 50,
  "period": "1Y",
  "periodEndOverride": {
    "month": 11,
    "dayOfMonth": 23,
    "hour": 23,
    "minute": 59,
    "second": 59
  },
  "recurrencePolicy": "no_recurrence",
  "activationPolicy": "fixed_schedule",
  "fixedStartDate": "2024-01-15T15:04:05Z07:00",
  "endDate": "2024-02-15T15:04:05Z07:00"
}

Response

Created

idinteger required

The internal ID of this entity.

createdstring date-time required

The time this entity was created.

namestring required

The internal name of the achievement used in API requests.

Note: The name should start with a letter. This cannot be changed after the achievement has been created.

titlestring required

The display name for the achievement in the Campaign Manager.

descriptionstring string required

A description of the achievement.

targetnumber required

The required number of actions or the transactional milestone to complete the achievement.

periodstring

The relative duration after which the achievement ends and resets for a particular customer profile.

Note: The period does not start when the achievement is created.

The period is a positive real number followed by one letter indicating the time unit.

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 also round certain units down to the beginning of period and up to the end of period.:

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

Note: You can either use the round down and round up option or set an absolute period.

recurrencePolicy'no_recurrence' | 'on_expiration' | 'on_completion'

The policy that determines if and how the achievement recurs.

  • no_recurrence: The achievement can be completed only once.
  • on_expiration: The achievement resets after it expires and becomes available again.
  • on_completion: When the customer progress status reaches completed, the achievement resets and becomes available again.
activationPolicy'user_action' | 'fixed_schedule'

The policy that determines how the achievement starts, ends, or resets.

  • user_action: The achievement ends or resets relative to when the customer started the achievement.
  • fixed_schedule: The achievement starts, ends, or resets for all customers following a fixed schedule.
fixedStartDatestring date-time

The achievement's start date when activationPolicy is set to fixed_schedule.

Note: It must be an RFC3339 timestamp string.

endDatestring date-time

The achievement's end date. If defined, customers cannot participate in the achievement after this date.

Note: It must be an RFC3339 timestamp string.

allowRollbackAfterCompletionboolean

When true, customer progress can be rolled back in completed achievements.

campaignIdinteger required

The ID of the campaign the achievement belongs to.

userIdinteger required

ID of the user that created this achievement.

createdBystring

Name of the user that created the achievement.

Note: This is not available if the user has been deleted.

hasProgressboolean

Indicates if a customer has made progress in the achievement.

status'inprogress' | 'expired' | 'not_started' | 'completed'

The status of the achievement.

Example response

{
  "id": 6,
  "created": "2020-06-10T09:05:27.993483Z",
  "name": "Order50Discount",
  "title": "50% off on 50th purchase.",
  "description": "50% off for every 50th purchase in a year.",
  "target": 50,
  "period": "1Y",
  "periodEndOverride": {
    "month": 11,
    "dayOfMonth": 23,
    "hour": 23,
    "minute": 59,
    "second": 59
  },
  "recurrencePolicy": "no_recurrence",
  "activationPolicy": "fixed_schedule",
  "fixedStartDate": "2024-01-15T15:04:05Z07:00",
  "endDate": "2024-02-15T15:04:05Z07:00",
  "campaignId": 1,
  "userId": 1234,
  "createdBy": "John Doe",
  "status": "inprogress"
}

Changes