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 account-level achievement.

post/v2/achievements

Request

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.

subscribedApplicationsinteger[]

A list containing the IDs of all applications that are subscribed to A list containing the IDs of all Applications that are connected to this achievement.

sandboxboolean required

Indicates if this achievement is a live or sandbox achievement. Achievements of a given type can only be connected to Applications of the same type.

timezonestring required

A string containing an IANA timezone descriptor.

Example request

{
  "name": "Order50Discount",
  "title": "50% off on 50th purchase.",
  "description": "50% off for every 50th purchase in a year.",
  "target": 50,
  "period": "1Y",
  "recurrencePolicy": "no_recurrence",
  "activationPolicy": "fixed_schedule",
  "fixedStartDate": "2024-01-15T15:04:05+07:00",
  "endDate": "2024-01-15T15:04:05+07:00",
  "subscribedApplications": [
    132,
    97
  ],
  "sandbox": true,
  "timezone": "Europe/Berlin"
}

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' required

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' required

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.

subscribedApplicationsinteger[] required

A list containing the IDs of all applications that are subscribed to A list containing the IDs of all Applications that are connected to this achievement.

userIdinteger required

The 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'active' | 'scheduled' | 'expired'

The status of the achievement.

  • active: The achievement is available to customers.
  • scheduled: The achievement has a fixedStartDate set in the future.
  • expired: The achievement's endDate is in the past.
sandboxboolean required

Indicates if this achievement is a live or sandbox achievement. Achievements of a given type can only be connected to Applications of the same type.

timezonestring required

A string containing an IANA timezone descriptor.

campaignIdinteger

This property is deprecated. Use referencedByCampaigns instead. This field contains the first campaign ID from the related referencedByCampaigns, and is omitted when referencedByCampaigns is empty.

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",
  "recurrencePolicy": "no_recurrence",
  "activationPolicy": "fixed_schedule",
  "fixedStartDate": "2024-01-15T15:04:05+07:00",
  "endDate": "2024-01-15T15:04:05+07:00",
  "subscribedApplications": [
    132,
    97
  ],
  "userId": 1234,
  "createdBy": "John Doe",
  "periodEndOverride": {
    "month": 11,
    "dayOfMonth": 23,
    "hour": 23,
    "minute": 59,
    "second": 59
  },
  "status": "active",
  "sandbox": true,
  "timezone": "Europe/Berlin",
  "campaignId": 3,
  "referencedByCampaigns": [
    {
      "id": 1,
      "applicationId": 2
    }
  ]
}

Changes