logo
API docs by Redocly

triple API (v1.20.137)

Download OpenAPI specification:Download

E-mail: apiteam@tripleup.com License: Commercial Terms of Service
Find out more about triple

Overview

The triple API enables Partners to integrate with the triple platform and Customers (consumers or card holders) to access offer content.

Connecting to our environment requires proper credentials. See the Authentication section for more details.

Additionally, triple content will be placed on a client-specific S3 bucket for ingestion. Please contact your triple client engagement manager for more information and to setup access.

Conventions

For a PATCH operation, any field marked required should always be passed and any other fields are optional and will not be updated if no field value is passed.

Concepts

Partner Types

Portfolio Managers are, generally, companies that provide services to multiple separate financial institutions such as regional banks, credit unions, or companies running open-enrollment rewards programs. These partners manage a portfolio of Publishers.

Publishers are, generally, banks or companies that offer one or more payment Card Programs to individuals.

Content Providers are the companies that publish Offers on the triple platform.

Card Programs

Card Programs represent a logical grouping of issued payment cards. A Publisher will create a Card Program for each debit or credit card offering, such as miles or cash back. For Publishers that are not Banks/Card Issuers (for example, a third-party rewards program), Card Programs can provide a simple way to organize Card Accounts.

Card Accounts represent the account connected to a payment card. Multiple physical cards may be associated with a single Card Account, such as when there are multiple authorized users or cards are replaced as lost, stolen, or expired. Each Transaction reported to triple must specify the Card Account to which it belongs.

Consumers represent individual card holders. A Consumer may be associated with multiple Card Accounts across a Publisher's Card Programs, such as when an individual has both a "miles" and a "cash back" card with the same bank. Multiple Consumers may be associated with the same Card Account, such as when there are multiple authorized users.

External IDs

triple requires Partners to specify IDs for the entities they create through the triple API. Generally, these "external" IDs only need to be unique within the scope of an object's parent entity, but we encourage the use of UUIDs to avoid confusion. External IDs must be stable and never sensitive, as they cannot be updated through the API.

triple will also create a unique ID for each entity created through the API.

Partner API

Most integration effort will focus on calls to endpoints under the /partner path. These endpoints will allow Content Providers to create and update Offer content and Publishers to register card holders, retrieve Offer content for display, and submit Transactions for Rewards.

The exposed APIs allow developers to authenticate to the triple service, register and unregister (delete) cards, retrieve affiliate offer URLs, submit transactions, and see user notifications delivered over webhooks.

Card Accounts

Operations related to managing Card Accounts.

A Card Account represents the account for which payment cards (credit or debit cards) are issued. A Transaction will belong to a single Card Account.

If a card is replaced or reissued (because it was lost or stolen), the Card Account itself should not change.

Card Accounts may have a status of "unenrolled" or "enrolled" for Rewards. A Card Account may only receive a Reward if it has a status of "enrolled" on the day of the eligible Transaction.

Get Card Account External

Returns a CardAccount instance using one or more of its associated external IDs:

  • external card account ID
  • external card program ID
  • external publisher ID

The receiver returns the same object as calling the /card-accounts/{id} endpoint with the triple card account ID if a matching CardAccount exists.

Authorizations:
triple_auth
Request Body schema: application/json
card_account_external_id
required
string (Card Account External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Account.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Card Account within the scope of its parent Card Program.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

card_program_external_id
string (Card Program External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Program.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Card Program within the scope of its parent Publisher.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

publisher_external_id
string (Publisher External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Publisher.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Publisher within the scope of its parent Portfolio Manager.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

Responses

Request samples

Content type
application/json
{
  • "card_account_external_id": "string",
  • "card_program_external_id": "string",
  • "publisher_external_id": "string"
}

Response samples

Content type
application/json
{
  • "card_program_id": "triple-abc-123",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "status": "ENROLLED",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

List Card Accounts

Returns a list of Card Accounts, optionally filtered.

Currently, this endpoint has a hard limit of returning up to 1,000 results. Future API releases may support paging results.

Authorizations:
triple_auth
query Parameters
publisher_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID of a Publisher. This parameter is ignored unless the client is a Portfolio Manager.

card_program_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

card_account_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

Responses

Response samples

Content type
application/json
{
  • "card_accounts": [
    ],
  • "total": 0
}

Create a Card Account

Creates a card account.

default_country_code may be set to the country associated with the card account. It defaults to US if it is not specified.

default_postal_code may be set to a postal code associated with the card account (e.g. domicile, other). The actual value is left to the discretion of the caller.

NB: The default_postal_code will be used in lieu of proximity_target if one is not specified during a CardAccount instance request for associated offers. If default_postal_code is not set for the card account, the CardProgram default_postal_code for the program will be used instead.

Authorizations:
triple_auth
Request Body schema: application/json
card_program_external_id
required
string (Card Program External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Program.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Card Program within the scope of its parent Publisher.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

default_country_code
string (CountryCode) = 2 characters ^[A-Z]{2}$

2-letter ISO-3166 country code

default_postal_code
string (PostalCode) [ 1 .. 15 ] characters

ZIP Code™, ZIP+4, or postal code

external_id
required
string (Card Account External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Account.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Card Account within the scope of its parent Card Program.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

publisher_external_id
string (Publisher External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Publisher.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Publisher within the scope of its parent Portfolio Manager.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

status
string (CardAccountEnrollmentStatus)
Default: "ENROLLED"
Enum: "ENROLLED" "NOT_ENROLLED" "CLOSED"
  • ENROLLED - The account is enrolled for rewards
  • NOT_ENROLLED - The account is not enrolled for rewards
  • CLOSED - The account is closed and cannot receive rewards

Responses

Request samples

Content type
application/json
{
  • "card_program_external_id": "string",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "publisher_external_id": "string",
  • "status": "ENROLLED"
}

Response samples

Content type
application/json
{
  • "card_program_id": "triple-abc-123",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "status": "ENROLLED",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Upsert Card Accounts in Bulk (Beta)

This endpoint provides significant performance advantages, over POSTing and PATCHing single Card Accounts, when creating or updating large numbers of Card Accounts. The behavior of this endpoint is similar to that of those endpoints except for some minor differences in how errors are handled.

Card Accounts that are not found, as resolved by their external_id and card_program_external_id (and publisher_external_id when applicable), are created. Existing objects are updated as though they were PATCHed.

You should check the result_type of the response to handle errors for individual items. If the top-level request returns a Client Error response (response codes 400-499), no Card Accounts from the batch were created or updated.

This endpoint is currently rate limited at 50 requests per minute.

Authorizations:
triple_auth
Request Body schema: application/json
action
required
string
Value: "upsert"

The action to take

required
Array of objects (CardAccountPost) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "action": "upsert",
  • "card_accounts": [
    ]
}

Response samples

Content type
application/json
{
  • "failures": [
    ],
  • "result_summary": { },
  • "result_type": "COMPLETE_FAILURE"
}

Get a Card Account

Get Card Account details.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "card_program_id": "triple-abc-123",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "status": "ENROLLED",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Card Account

(Alpha - this endpoint is subject to breaking change)

Enroll, un-enroll, or close a Card Account.

Card Accounts must be enrolled at the time of a transaction and not closed at the time of distribution in order to receive Rewards.

The date of enrollment defaults to the current date at UTC-12. The date of un-enrollment defaults to the current date at UTC+12. (This is to accommodate the possibility of a customer's current local date being different than the server's.)

A future API release will address the edge case of unenrolling and then re-enrolling an account within the same day.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
default_country_code
string (CountryCode) = 2 characters ^[A-Z]{2}$

2-letter ISO-3166 country code

default_postal_code
string (PostalCode) [ 1 .. 15 ] characters

ZIP Code™, ZIP+4, or postal code

status
string (CardAccountEnrollmentStatusPatch)
Enum: "ENROLLED" "NOT_ENROLLED" "CLOSED"
  • ENROLLED - The account is enrolled for rewards
  • NOT_ENROLLED - The account is not enrolled for rewards
  • CLOSED - The account is closed and cannot receive rewards

Responses

Request samples

Content type
application/merge-patch+json
{
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "status": "ENROLLED"
}

Response samples

Content type
application/json
{
  • "card_program_id": "triple-abc-123",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "status": "ENROLLED",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Get a cardholder reward statement.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

query Parameters
minimum_reward_status
required
string (MinimumRewardStatus)
Enum: "PENDING_MERCHANT_APPROVAL" "PENDING_MERCHANT_FUNDING" "PENDING_TRANSFER_TO_PUBLISHER" "DISTRIBUTED_TO_PUBLISHER" "DISTRIBUTED_TO_CARDHOLDER"

The minimum reward status to be returned in the list of rewards. From lowest to highest, these values are:

  • PENDING_MERCHANT_APPROVAL
  • PENDING_MERCHANT_FUNDING
  • PENDING_TRANSFER_TO_PUBLISHER
  • DISTRIBUTED_TO_PUBLISHER
  • DISTRIBUTED_TO_CARDHOLDER

If you use PENDING_MERCHANT_FUNDING, you will get all rewards with that value through DISTRIBUTED_TO_CARDHOLDER, but no rewards PENDING_MERCHANT_APPROVAL.

page
integer
Default: 1

The page of results for returned Objects.

date_range
required
string (RewardStatementDateRange)
Enum: "REWARDS_EARNED_LAST_90_DAYS" "REWARDS_EARNED_LAST_180_DAYS" "REWARDS_EARNED_LAST_365_DAYS" "REWARDS_EARNED_YEAR_TO_DATE" "REWARDS_EARNED_LIFETIME"

The time period for which you would like to retrieve rewards.

Responses

Response samples

Content type
application/json
{
  • "rewards": [
    ],
  • "rewards_earned_last_90_days": "string",
  • "rewards_earned_last_180_days": "string",
  • "rewards_earned_year_to_date": "string",
  • "rewards_earned_365_days": "string",
  • "rewards_earned_lifetime": "string"
}

Card Programs

A Card Program is logical grouping of Card Accounts. Typically, this is a specific type of card offering by a Publisher - a debit or credit card with its own rewards, such as miles or cash back.

Alternatively, for Publishers that are not Banks or Card Issuers (for example, a third-party rewards program), this is simply a way to organize Card Accounts.

Card Accounts may not move between Card Programs and should not be represented in more than one Card Program.

List Card Programs

Returns a list of Card Programs, optionally filtered. This list can be used to find Card Programs' ID given an external ID.

Authorizations:
triple_auth
query Parameters
publisher_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID of a Publisher. This parameter is ignored unless the client is a Portfolio Manager.

card_program_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

Responses

Response samples

Content type
application/json
{
  • "card_programs": [
    ],
  • "total": 0
}

Create a Card Program

Creates a card program.

default_country_code may be set to the country associated with the card program. It defaults to US if it is not specified.

default_postal_code must be set to a postal code associated with the card program (e.g. domicile, other). The actual value is left to the discretion of the caller.

NB: The default_postal_code will be used in lieu of proximity_target if one is not specified during a CardAccount instance request for associated offers. If default_postal_code is not set for the card account, the CardProgram default_postal_code for the program will be used instead.

Authorizations:
triple_auth
Request Body schema: application/json
card_bins
Array of strings (CardProgramCardBins) <= 100 items [^\d{6}$]

The Bank Identification Numbers for cards in this Card Program.

Providing these values helps triple validate Transactions during reward processing and enforce card requirements during purchases through Affiliate Offers.

default_country_code
string (USDefaultedCountryCode) = 2 characters ^[A-Z]{2}$
Default: "US"

2-letter ISO-3166 country code

default_postal_code
required
string (PostalCode) [ 1 .. 15 ] characters

ZIP Code™, ZIP+4, or postal code

external_id
required
string (Card Program External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Program.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Card Program within the scope of its parent Publisher.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

name
required
string (CardProgramName) [ 1 .. 100 ] characters ^(?!\s)[\.]+(?<!\s)$

Display name of the Card Program

description
string (CardProgramDescription) <= 2000 characters

Description of the Card Program

hosted_ui_subdomain
string (HostedUiSubdomain) <= 60 characters

The subdomain for Triple hosted user interfaces.

program_currency
required
string (CurrencyCode) = 3 characters ^[A-Z]{3}$
Default: "USD"

3-character ISO-4217 currency code. Only USD is currently supported.

Contact your Triple representative for support with additional currencies. Note that some values are not supported, particularly test and fund codes.

loyalty_unit
string (CardProgramLoyaltyUnit)
Enum: "POINTS" "MILES"

The unit used to pay with loyalty. Currently only POINTS and MILES are supported.

loyalty_conversion_rate
number <double> (CardProgramLoyaltyConversionRate) > 0

The rate of loyalty units earned per reward dollar earned.

For example, setting this to 100 would earn customers 100 loyalty miles for every reward dollar earned.

publisher_external_id
string (Publisher External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Publisher.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Publisher within the scope of its parent Portfolio Manager.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

Responses

Request samples

Content type
application/json
{
  • "card_bins": [
    ],
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "name": "string",
  • "description": "string",
  • "hosted_ui_subdomain": "mybanque",
  • "program_currency": "USD",
  • "loyalty_unit": "POINTS",
  • "loyalty_conversion_rate": 100,
  • "publisher_external_id": "string"
}

Response samples

Content type
application/json
{
  • "card_bins": [
    ],
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "description": "string",
  • "external_id": "string",
  • "hosted_ui_subdomain": "mybanque",
  • "id": "triple-abc-123",
  • "loyalty_unit": "POINTS",
  • "loyalty_conversion_rate": 100,
  • "name": "string",
  • "program_currency": "USD",
  • "publisher_id": "triple-abc-123",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Get a Card Program

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "card_bins": [
    ],
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "description": "string",
  • "external_id": "string",
  • "hosted_ui_subdomain": "mybanque",
  • "id": "triple-abc-123",
  • "loyalty_unit": "POINTS",
  • "loyalty_conversion_rate": 100,
  • "name": "string",
  • "program_currency": "USD",
  • "publisher_id": "triple-abc-123",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Card Program

Updates a Card Program.

Only fields "name", and "card_bins" may be updated for a Card Program.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
name
string (CardProgramName) [ 1 .. 100 ] characters ^(?!\s)[\.]+(?<!\s)$

Display name of the Card Program

card_bins
Array of strings (CardProgramCardBins) <= 100 items [^\d{6}$]

The Bank Identification Numbers for cards in this Card Program.

Providing these values helps triple validate Transactions during reward processing and enforce card requirements during purchases through Affiliate Offers.

description
string (CardProgramDescription) <= 2000 characters

Description of the Card Program

hosted_ui_subdomain
string (HostedUiSubdomain) <= 60 characters

The subdomain for Triple hosted user interfaces.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "card_bins": [
    ],
  • "description": "string",
  • "hosted_ui_subdomain": "mybanque"
}

Response samples

Content type
application/json
{
  • "card_bins": [
    ],
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "description": "string",
  • "external_id": "string",
  • "hosted_ui_subdomain": "mybanque",
  • "id": "triple-abc-123",
  • "loyalty_unit": "POINTS",
  • "loyalty_conversion_rate": 100,
  • "name": "string",
  • "program_currency": "USD",
  • "publisher_id": "triple-abc-123",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Offer Activation

Operations related to Activating Offers for a Customer.

Some Offers are not eligible for Rewards until a Customer activates the Offer. Some Offers may require re-activation after a specified number of days.

Activate Offer By Id

Activate an offer by id for a specified card account

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

offer_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Offer Display

Operations related to displaying Offers to Customers.

Offer Display will generally follow the following flow:

  1. The Customer opens their mobile app or web page. A list of Recommended Offers are displayed to the Customer.
  2. The Customer may search Offers.
  3. As Offers are displayed, "Offer Viewed" Events are reported to triple.
  4. The Customer may tap or click to Activate an Offer, if required.
  5. The Customer may tap or click a thumbnail to View Offer Details.

Affiliate Offers are online Offers that require redirecting the Customer to a custom URL. The URL is specific to that Customer and is generated by calling the "Clicks" endpoint, usually while viewing the Offer Details.

Offer Display Rules can be configured to automatically exclude offers from the result sets.

Get Activated Offers

Lists activated offers for the card account designated in the url path.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/json
expires_within
integer or null
Enum: 1 3 5 10
include_expired
boolean
Default: false
page_offset
integer [ 0 .. 975 ]
Default: 0

The beginning index for the current page of activated offers.

page_size
integer [ 1 .. 100 ]
Default: 25

The number of offers returned for the current page of activated offers.

object (GeoTarget)

The Geo-coordinates for the end-user's location, given as latitude and longitude values or as approximate location parameters.

If providing postal_code, country_code is required and must be set to US, as only US ZIP codes are currently supported.

If providing latitude and longitude, both fields must be set.

If no location is provided, the default postal code for the Card Account or Card Program is used.

Responses

Request samples

Content type
application/json
{
  • "expires_within": 1,
  • "include_expired": false,
  • "page_offset": 0,
  • "page_size": 25,
  • "proximity_target": {
    }
}

Response samples

Content type
application/json
{
  • "activated_offers": [
    ]
}

Get Offer Categories

Get a list of categories with the count of active offers for each offer category that is available to a cardholder.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

query Parameters
exclude_inactive_offers
boolean
Deprecated

Include only categories with active offers

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

Get Offer Recommendations

Get Offer Recommendations.

Get Offer Recommendations, optionally filtering by offer modes and/or offer categories. If include_modes and include_categories are omitted, specified as null or specified as an empty list, the application will default to include all values in the enum.

Providing a latitude and longitude for proximity_target is highly encouraged. Doing so allows Triple to deliver the most relevant Offers and Merchant Locations.

Note that Offer Display Exclusion Rules are enforced against all recommendations.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/json
object (ApplyFilter)

Applies a search filter.

If more than one filter property is specified, the filter condition is expressed as an AND of the specified filter properties.

include_categories
Array of strings (TripleOfferCategory) [ 1 .. 13 ] items
Default: ["AUTOMOTIVE","CHILDREN_AND_FAMILY","ELECTRONICS","ENTERTAINMENT","FINANCIAL_SERVICES","FOOD","HEALTH_AND_BEAUTY","HOME","OFFICE_AND_BUSINESS","RETAIL","SERVICES_AND_SUBSCRIPTIONS","TRAVEL","UTILITIES_AND_TELECOM"]
Items Enum: "AUTOMOTIVE" "CHILDREN_AND_FAMILY" "ELECTRONICS" "ENTERTAINMENT" "FINANCIAL_SERVICES" "FOOD" "HEALTH_AND_BEAUTY" "HOME" "OFFICE_AND_BUSINESS" "RETAIL" "SERVICES_AND_SUBSCRIPTIONS" "TRAVEL" "UTILITIES_AND_TELECOM"
include_modes
Array of strings (OfferMode) [ 1 .. 3 ] items
Default: ["ONLINE","IN_PERSON"]
Items Enum: "ONLINE" "IN_PERSON"
object (GeoTarget)

The Geo-coordinates for the end-user's location, given as latitude and longitude values or as approximate location parameters.

If providing postal_code, country_code is required and must be set to US, as only US ZIP codes are currently supported.

If providing latitude and longitude, both fields must be set.

If no location is provided, the default postal code for the Card Account or Card Program is used.

page_size
integer [ 0 .. 1000 ]
Default: 100

Responses

Request samples

Content type
application/json
{
  • "apply_filter": {
    },
  • "include_categories": [
    ],
  • "include_modes": [
    ],
  • "proximity_target": {
    },
  • "page_size": 100
}

Response samples

Content type
application/json
{
  • "recommended_offers": [
    ],
  • "total": 10000
}

Search Offers

Search for offers, optionally by category.

Providing a latitude and longitude for proximity_target is highly encouraged. Doing so allows Triple to deliver the most relevant Offers and Merchant Locations.

The default behavior of this endpoint is the null query, which fetches triple offers recommendations based on a Customer's geo-location, transaction history, and offer interactions.

However, a Customer can also search directly for offers with ad hoc text queries and/or by faceting on offer category. This action replaces the null query with search terms and/or one or more offer category facets. For example, a Customer may search for 'italian food' in plain text and select the 'FOOD' offer category facet.

Search results are paginated, using the page_size and page_offset parameters. For example, page_size=10 and page_offset=30 corresponds to the 4th page of 10 offers.

Note that Offer Display Rules are enforced against all search results.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/json
object (ApplyFilter)

Applies a search filter.

If more than one filter property is specified, the filter condition is expressed as an AND of the specified filter properties.

object (CrowdingParameters)

Crowding parameters control the maximum number of consecutive offers that may share the same characteristic.

Supported parameters include:

- mode: ONLINE or IN_PERSON

- category: RETAIL, FOOD, etc.

- merchant: 'ACME inc.', 'Big Multinational Brand', etc.

NOTE: Crowding maximums may be exceeded depending on the availability of relevant replacement offers for any given query. Crowding maximums do not apply for a particular offer characteristic if a search query filter is applied to that characterstic. (e.g. Filtering on mode: ONLINE will return exclusively ONLINE results, even if a crowding parameter for mode is specified.)

page_offset
integer [ 0 .. 975 ]
Default: 0

The beginning index for the current page of offers.

page_size
integer [ 1 .. 100 ]
Default: 25

The number of offers returned for the current page of search results.

object (GeoTarget)

The Geo-coordinates for the end-user's location, given as latitude and longitude values or as approximate location parameters.

If providing postal_code, country_code is required and must be set to US, as only US ZIP codes are currently supported.

If providing latitude and longitude, both fields must be set.

If no location is provided, the default postal code for the Card Account or Card Program is used.

text_query
string [ 0 .. 75 ] characters

Text query used to search offers. Text queries over 75 characters will be truncated.

Responses

Request samples

Content type
application/json
{
  • "apply_filter": {
    },
  • "crowding_parameters": {
    },
  • "page_offset": 0,
  • "page_size": 25,
  • "proximity_target": {
    },
  • "text_query": "italian food"
}

Response samples

Content type
application/json
{
  • "offers": [
    ],
  • "total": 10000
}

Get Offer Details by Cardholder

Get details and merchant locations for an offer associated with a card account.

Providing a latitude and longitude for proximity_target is highly encouraged. Doing so allows Triple to deliver the most relevant Offers and Merchant Locations.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/json
offer_id
required
string (EntityId) [ 1 .. 100 ] characters

The triple-defined ID for the entity.

object (GeoTarget)

The Geo-coordinates for the end-user's location, given as latitude and longitude values or as approximate location parameters.

If providing postal_code, country_code is required and must be set to US, as only US ZIP codes are currently supported.

If providing latitude and longitude, both fields must be set.

If no location is provided, the default postal code for the Card Account or Card Program is used.

Responses

Request samples

Content type
application/json
{
  • "offer_id": "triple-abc-123",
  • "proximity_target": {
    }
}

Response samples

Content type
application/json
{
  • "merchant_locations": [
    ],
  • "offer": {
    }
}

Get Offer Details

Get details and merchant locations for an offer.

Authorizations:
triple_auth
path Parameters
offer_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "merchant_locations": [
    ],
  • "offer": {
    }
}

Offer Filters

Alpha - These endpoints are subject to breaking changes!

Exclude Offers from cardholders based on specific Offer properties. Filters apply globally, to all Publishers (if created by a Portfolio Manager) and Card Programs created by the caller. Any Offer matching the filter is immediately excluded from Search results, Recommendations, and Transaction Matching.

Merchants Search

Return a list of Merchants.

Authorizations:
triple_auth
query Parameters
page
integer
Default: 1

The page of results for returned Objects.

page_size
integer
Default: 100

The size of pages for returned Objects.

query
string

Query string for merchant names.

Responses

Response samples

Content type
application/json
{
  • "merchants": [
    ],
  • "total": 12
}

Get Filter

Gets an Offer Filter.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    },
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update Filter

Updates an Offer Filter.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
description
string (OfferFilterDescription) [ 5 .. 500 ] characters

Readable description for this rule.

is_activated
boolean

If true, the filter is applied to offers.

name
string (OfferFilterName) [ 5 .. 50 ] characters

The short name for a filter.

object (OfferFilterOfferCondition)

Summary: Specifies the condition an offer must satisfy for a filter to apply. You may wish to exclude specific merchants or offers by specifying their IDs in the provided fields. Providing one or more category values will exclude all offers from those categories. Triple will not match new transactions against Offers meeting any of these conditions, even if the Offer was previously displayed to the cardholder.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    },
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Delete Filter

Deletes an Offer Filter.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "content": {
    }
}

List Filters

Lists all Offer Filters owned by the caller.

Authorizations:
triple_auth

Responses

Response samples

Content type
application/json
{
  • "filters": [
    ],
  • "total": 0
}

Create Filter

Creates a new Offer Filter.

Authorizations:
triple_auth
Request Body schema: application/json
description
required
string (OfferFilterDescription) [ 5 .. 500 ] characters

Readable description for this rule.

is_activated
boolean (OfferFilterIsActivated)
Default: true

If true, the filter is applied to offers.

name
required
string (OfferFilterName) [ 5 .. 50 ] characters

The short name for a filter.

required
object (OfferFilterOfferCondition)

Summary: Specifies the condition an offer must satisfy for a filter to apply. You may wish to exclude specific merchants or offers by specifying their IDs in the provided fields. Providing one or more category values will exclude all offers from those categories. Triple will not match new transactions against Offers meeting any of these conditions, even if the Offer was previously displayed to the cardholder.

Responses

Request samples

Content type
application/json
{
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    },
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Offer Providers

Operations related to creating and updating Offers and Merchants.

List Card Exclusions

Returns a list of the Content Provider-defined Card Exclusions.

Transactions from payment cards with these identifiers will be excluded from matching the Offers you create.

Authorizations:
triple_auth
query Parameters
page
integer
Default: 1

The page of results for returned Objects.

page_size
integer
Default: 100

The size of pages for returned Objects.

Responses

Response samples

Content type
application/json
{
  • "card_accounts": [
    ],
  • "total": 0
}

Update Card Exclusions

Update the list of Content Provider-defined Card Exclusions.

  • upsert to add card identifiers to the list or set the updated_at of existing items to the current date and time.
  • remove to remove card identifiers from the list
  • remove_not_updated_since to remove card identifiers based on their updated_at timestamp.
Authorizations:
triple_auth
Request Body schema: application/json
action
required
string

The action to take

required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
Example
{
  • "action": "remove",
  • "card_exclusions": [
    ]
}

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "content": {
    }
}

List Merchants

Returns a list of Merchants, optionally filtered.

This list can be used to find a Merchant's ID given an external ID. This endpoint has a limit of up to 100 merchants per page.

Authorizations:
triple_auth
query Parameters
merchant_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

page
integer
Default: 1

The page of results for returned Objects.

page_size
integer
Default: 100

The size of pages for returned Objects.

Responses

Response samples

Content type
application/json
{
  • "merchants": [
    ],
  • "total": 0
}

Create a Merchant

Creates a Merchant.

Authorizations:
triple_auth
Request Body schema: application/json
required
object (StrictAddress)

A physical address in the world, with required fields.

triple uses address validation services to update and standardize addresses on our platform. Address data sent to the API may be updated as we process, validate, and normalize addresses.

assumed_name
required
string (MerchantAssumedName) [ 1 .. 100 ] characters

The (doing-business-as) name of the Merchant.

external_id
required
string (Merchant External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Merchant.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Merchant within the scope of its parent Content Provider.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

merchant_category_code
required
string (MerchantCategoryCode) = 4 characters ^\d{4}$

The 4-digit Merchant Category Code

logo_url
string <url> (MerchantLogoUrl) <= 2000 characters ^https://.+$

A link to the merchant's logo

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "external_id": "string",
  • "merchant_category_code": "7998",
  • "logo_url": "string"
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "merchant_category": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "logo_url": "string",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Get a Merchant

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "merchant_category": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "logo_url": "string",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Merchant

Updates a Merchant with any of the values set in the request. The update takes an object with zero or more value definitions, each can be set to the value described in the spec or null. Invalid values will raise an error condition.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
assumed_name
string (MerchantAssumedName) [ 1 .. 100 ] characters

The (doing-business-as) name of the Merchant.

object (Address)

A physical address in the world. triple uses address validation services to update and standardize addresses on our platform. Address data sent to the API may be updated as we process, validate, and normalize addresses. NOTE: Though not marked as required, the street address, postal code, and country code are required for transaction matching to function properly.

merchant_category_code
string (MerchantCategoryCode) = 4 characters ^\d{4}$

The 4-digit Merchant Category Code

logo_url
string <url> (MerchantLogoUrl) <= 2000 characters ^https://.+$

A link to the merchant's logo

Responses

Request samples

Content type
application/merge-patch+json
{
  • "assumed_name": "string",
  • "address": {
    },
  • "merchant_category_code": "7998",
  • "logo_url": "string"
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "merchant_category": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "logo_url": "string",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

List Merchant Locations

Returns a list of Merchant Locations, optionally filtered.

This list can be used to find a Merchant Location's ID given an external ID.

Authorizations:
triple_auth
query Parameters
merchant_location_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

page
integer
Default: 1

The page of results for returned Objects.

page_size
integer
Default: 100

The size of pages for returned Objects.

parent_merchant_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

Responses

Response samples

Content type
application/json
{
  • "locations": [
    ],
  • "total": 0
}

Create a Merchant Location

Creates a Merchant Location.

Authorizations:
triple_auth
Request Body schema: application/json
object (StrictAddress)

A physical address in the world, with required fields.

triple uses address validation services to update and standardize addresses on our platform. Address data sent to the API may be updated as we process, validate, and normalize addresses.

email
string (MerchantLocationEmail) <= 200 characters ^(([a-zA-Z0-9_\-\.]+)@([a-zA-Z0-9_\-\.]+)\.([...

An email address for the location.

external_id
required
string (Merchant Location External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Merchant Location.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Merchant Location within the scope of its parent Content Provider.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

is_online
required
boolean (MerchantLocationIsOnline)

Indicates whether or not this is an online location.

location_name
string (MerchantLocationName) [ 0 .. 100 ] characters ^(?!\s)(.+)?(?<!\s)$

The name of the Merchant Location. If not specified, the Merchant name is used.

location_website
string (MerchantLocationWebsite) <= 2000 characters ^https:\/\/.+$

A URL for the location or online offer. Required if 'is_online' is true

parent_merchant_external_id
required
string (Merchant Location External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Merchant Location.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Merchant Location within the scope of its parent Content Provider.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

phone_number
string (MerchantLocationPhoneNumber) <= 16 characters ^(([0-9]{3})?[-\s\.]?[(]?[0-9]{3}[)]?[-\s\.]?...

A phone number for the location.

Array of objects (ProcessorMerchantIds)

The Processor Merchant ID (MID) is an unique number used to identify the business for credit and debit card payment processing.

Physical locations and online retailers may have multiple MIDs, even for the same processor network, usually for different departments or checkouts.

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "email": "merchant.location@merchant.com",
  • "external_id": "string",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "parent_merchant_external_id": "string",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "email": "merchant.location@merchant.com",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "parent_merchant_external_id": "string",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ],
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Get a Merchant Location

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "address": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "email": "merchant.location@merchant.com",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "parent_merchant_external_id": "string",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ],
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Merchant Location

Updates a Merchant Location.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
object (Address)

A physical address in the world. triple uses address validation services to update and standardize addresses on our platform. Address data sent to the API may be updated as we process, validate, and normalize addresses. NOTE: Though not marked as required, the street address, postal code, and country code are required for transaction matching to function properly.

email
string (MerchantLocationEmail) <= 200 characters ^(([a-zA-Z0-9_\-\.]+)@([a-zA-Z0-9_\-\.]+)\.([...

An email address for the location.

is_online
boolean (MerchantLocationIsOnline)

Indicates whether or not this is an online location.

location_name
string (MerchantLocationName) [ 0 .. 100 ] characters ^(?!\s)(.+)?(?<!\s)$

The name of the Merchant Location. If not specified, the Merchant name is used.

location_website
string (MerchantLocationWebsite) <= 2000 characters ^https:\/\/.+$

A URL for the location or online offer. Required if 'is_online' is true

phone_number
string (MerchantLocationPhoneNumber) <= 16 characters ^(([0-9]{3})?[-\s\.]?[(]?[0-9]{3}[)]?[-\s\.]?...

A phone number for the location.

Array of objects (ProcessorMerchantIds)

The Processor Merchant ID (MID) is an unique number used to identify the business for credit and debit card payment processing.

Physical locations and online retailers may have multiple MIDs, even for the same processor network, usually for different departments or checkouts.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "address": {
    },
  • "email": "merchant.location@merchant.com",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "email": "merchant.location@merchant.com",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "parent_merchant_external_id": "string",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ],
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Delete a Merchant Location

Deletes a Merchant Location

path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "content": {
    }
}

List Offers

Returns a list of Offers, optionally filtered.

This list can be used to find an Offer's ID given an external ID.

Authorizations:
triple_auth
query Parameters
merchant_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

offer_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

Responses

Response samples

Content type
application/json
{
  • "offers": [
    ],
  • "total": 0
}

Create an Offer

Creates an Offer.

Authorizations:
triple_auth
Request Body schema: application/json
activation_required
required
boolean (OfferActivationIsRequired)

Indicates whether or not a cardholder must activate this offer prior to transacting and qualifying for the offer reward.

If true, transactions that occur prior to the date of the cardholder activating the offer will not qualify for the offer's reward.

activation_duration_in_days
required
number or null (OfferActivationInDays)

If specified, the number of days (inclusive) for which an offer activation is valid.

If a transaction falls outside of this duration, it will not qualify for the offer. The day of activation is considered day 1. So, if a cardholder activates an offer on Monday with a 3 day duration, they must make their transaction on or before Wednesday.

allowed_card_program_ids
Array of strings (OfferAllowedCardProgramIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will only be available for the card program id(s) supplied.

allowed_portfolio_manager_ids
Array of strings (OfferAllowedPortfolioManagerIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will only be available for the portfolio manger id(s) supplied.

allowed_publisher_ids
Array of strings (OfferAllowedPublisherIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will only be available for the publishers id(s) supplied.

category
required
string (TripleOfferCategory)
Enum: "AUTOMOTIVE" "CHILDREN_AND_FAMILY" "ELECTRONICS" "ENTERTAINMENT" "FINANCIAL_SERVICES" "FOOD" "HEALTH_AND_BEAUTY" "HOME" "OFFICE_AND_BUSINESS" "RETAIL" "SERVICES_AND_SUBSCRIPTIONS" "TRAVEL" "UTILITIES_AND_TELECOM"

triple Offer Category

currency_code
required
string (OfferCurrencyCode) = 3 characters ^[A-Z]{3}$
Default: "USD"

The currency for the offer reward, minimum spend requirement, and maximum reward limitations. The value is an ISO-4217 currency code.

denied_card_program_ids
Array of strings (OfferDeniedCardProgramIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will be denied for the card program id(s) supplied.

denied_portfolio_manager_ids
Array of strings (OfferDeniedPortfolioManagerIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will be denied for the portfolio manger id(s) supplied.

denied_publisher_ids
Array of strings (OfferDeniedPublisherIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will be denied for the publishers id(s) supplied.

effective_date
required
string <date> (OfferEffectiveDate)

The first date on which the offer is valid.

excluded_dates
Array of strings <date> (OfferExcludedDates) [ items <date > ]

Dates for which the offer is not valid. Transactions made on these dates will not qualify for a reward.

expiration_date
required
string or null <date> (OfferExpirationDate)

If specified, the last date on which the offer is valid.

external_id
required
string (Offer External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for an Offer.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Offer within the scope of its parent Content Provider.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

description
required
string (OfferDescription) [ 6 .. 65535 ] characters

A long-form text description of or promotional content for an offer

headline
required
string (OfferHeadline) [ 6 .. 100 ] characters

The headline or title for the offer, appropriate for top-level display.

object (OfferInvalidDayParts)

If specified, the days of the week and times during which the offer is invalid.

marketing_fee_currency_code
required
string or null (OfferMarketingFeeCurrencyCode) = 3 characters ^[A-Z]{3}$
Default: "USD"

The ISO-3166 label for marketing currency. Defaults to 'USD' if omitted or null.

marketing_fee_rate
required
number or null (OfferMarketingFeeRate)

The share percentage if this offer has a marketing_fee_type of percentage, the amount will be between 0.0 and 100.0

marketing_fee_type
required
string (OfferMarketingFeeType)
Enum: "FIXED" "PERCENTAGE"
marketing_fee_value
required
number (OfferMarketingFeeValue)

The fixed share value if this offer has a marketing_fee_type of fixed, the amount must be greater than or equal to 0.

maximum_redemptions
required
string or null (OfferMaximumRedemptions) ^\d{1,3}\/\d{1,3}[YMWD]$

The maximum number of times a cardholder may receive a reward for this offer over a given period of time.

The numerator of this value is the number of times a reward can be earned. The numerator must be less than 1000. The denominator is the period of time over which the limit is enforced.

Time periods must conform to the following restrictions:

  • a period of years (Y) must be 1-3
  • a period of months (M) must be 1-36
  • a period of weeks (W) must be 1-156
  • a period of days (D) must be 1-365
maximum_reward_cumulative
required
string or null (OfferMaximumRewardCumulative) ^\d{1,12}\/\d{1,3}[YMWD]$

The maximum monetary value a cardholder may earn for this offer across multiple transactions over a given period of time.

The numerator of this value is the maximum monetary value a reward can earn. The numerator must be less than 1000000000000. The denominator is the period of time over which the limit is enforced.

Time periods must conform to the following restrictions:

  • a period of years (Y) must be 1-3
  • a period of months (M) must be 1-36
  • a period of weeks (W) must be 1-156
  • a period of days (D) must be 1-365
maximum_reward_per_transaction
required
number or null (OfferMaximumRewardPerTransaction) > 0

The maximum monetary value a cardholder may earn for a percentage-based reward on any single transaction.

required
Array of objects or null (OfferMerchantCategories) [ 1 .. 25 ] items

The Merchant Category Codes included for a categorical offer.

merchant_external_id
required
string (EntityId) [ 1 .. 100 ] characters

The triple-defined ID for the entity.

merchant_website
required
string or null <url> (MerchantWebsite) <= 2000 characters ^https://.+$
minimum_spend
required
number (OfferMinimumSpend) >= 0

The minimum monetary value that a cardholder must spend for a transaction to qualify for this offer.

mode
required
string (OfferMode)
Enum: "ONLINE" "IN_PERSON"

The offer delivery mode

object (OfferBudgetRequest)
offer_type
required
string (OfferType)
Enum: "CARD_LINKED" "AFFILIATE" "CATEGORICAL"

The type of offer - card-linked, affiliate, categorical, etc.

reward_rate
required
number or null (OfferRewardRate) > 0

The reward percentage if this offer has a reward_type of percentage, the amount will be between 0.0 and 100.0

reward_type
required
string (OfferRewardType)
Enum: "FIXED" "PERCENTAGE"

Indicates whether this offer is for a fixed or percentage-based amount.

reward_value
required
number or null (OfferRewardValue) > 0

The fixed reward value if this offer has a reward_type of fixed, the amount must be greater than or equal to 0.

terms
required
string or null (OfferTermsAndConditions)

Terms and conditions for the offer, not inclusive of other limits specified by the offer properties, such as minimum spend, excluded dates, or activation requirements.

required
object (OfferValidDayParts)

If specified, the days of the week and times during which the offer is valid. If unspecified, the offer is valid for all days and times during the week.

Responses

Request samples

Content type
application/json
{
  • "activation_required": true,
  • "activation_duration_in_days": 0,
  • "allowed_card_program_ids": [
    ],
  • "allowed_portfolio_manager_ids": [
    ],
  • "allowed_publisher_ids": [
    ],
  • "category": "AUTOMOTIVE",
  • "currency_code": "USD",
  • "denied_card_program_ids": [
    ],
  • "denied_portfolio_manager_ids": [
    ],
  • "denied_publisher_ids": [
    ],
  • "effective_date": "2021-12-01",
  • "excluded_dates": [
    ],
  • "expiration_date": "2021-12-31",
  • "external_id": "string",
  • "description": "string",
  • "headline": "string",
  • "invalid_day_parts": {
    },
  • "marketing_fee_currency_code": "USD",
  • "marketing_fee_rate": 0,
  • "marketing_fee_type": "FIXED",
  • "marketing_fee_value": 0,
  • "maximum_redemptions": "1/3M",
  • "maximum_reward_cumulative": "1/3M",
  • "maximum_reward_per_transaction": 0,
  • "merchant_categories": [
    ],
  • "merchant_external_id": "triple-abc-123",
  • "merchant_website": "string",
  • "minimum_spend": 0,
  • "mode": "ONLINE",
  • "offer_budget": {
    },
  • "offer_type": "CARD_LINKED",
  • "reward_rate": 0,
  • "reward_type": "FIXED",
  • "reward_value": 0,
  • "terms": "string",
  • "valid_day_parts": {
    }
}

Response samples

Content type
application/json
{
  • "activation_duration_in_days": 0,
  • "activation_required": true,
  • "category": "AUTOMOTIVE",
  • "category_tags": "string",
  • "currency_code": "USD",
  • "description": "string",
  • "effective_date": "2021-12-01",
  • "excluded_dates": [
    ],
  • "expiration_date": "2021-12-31",
  • "external_id": "string",
  • "headline": "string",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "invalid_day_parts": {
    },
  • "logo_url": "string",
  • "marketing_fee_currency_code": "USD",
  • "marketing_fee_rate": 0,
  • "marketing_fee_value": 0,
  • "marketing_fee_type": "FIXED",
  • "maximum_redemptions": "1/3M",
  • "maximum_reward_cumulative": "1/3M",
  • "maximum_reward_per_transaction": 0,
  • "merchant_categories": [
    ],
  • "merchant_website": "string",
  • "minimum_spend": 0,
  • "offer_budget": {
    },
  • "offer_mode": "ONLINE",
  • "offer_type": "CARD_LINKED",
  • "reward_rate": 0,
  • "reward_type": "FIXED",
  • "reward_value": 0,
  • "terms_and_conditions": "string",
  • "valid_day_parts": {
    }
}

Get an Offer

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "activation_duration_in_days": 0,
  • "activation_required": true,
  • "category": "AUTOMOTIVE",
  • "category_tags": "string",
  • "currency_code": "USD",
  • "description": "string",
  • "effective_date": "2021-12-01",
  • "excluded_dates": [
    ],
  • "expiration_date": "2021-12-31",
  • "external_id": "string",
  • "headline": "string",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "invalid_day_parts": {
    },
  • "logo_url": "string",
  • "marketing_fee_currency_code": "USD",
  • "marketing_fee_rate": 0,
  • "marketing_fee_value": 0,
  • "marketing_fee_type": "FIXED",
  • "maximum_redemptions": "1/3M",
  • "maximum_reward_cumulative": "1/3M",
  • "maximum_reward_per_transaction": 0,
  • "merchant_categories": [
    ],
  • "merchant_website": "string",
  • "minimum_spend": 0,
  • "offer_budget": {
    },
  • "offer_mode": "ONLINE",
  • "offer_type": "CARD_LINKED",
  • "reward_rate": 0,
  • "reward_type": "FIXED",
  • "reward_value": 0,
  • "terms_and_conditions": "string",
  • "valid_day_parts": {
    }
}

Update an Offer

Updates an Offer.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
category
string (TripleOfferCategory)
Enum: "AUTOMOTIVE" "CHILDREN_AND_FAMILY" "ELECTRONICS" "ENTERTAINMENT" "FINANCIAL_SERVICES" "FOOD" "HEALTH_AND_BEAUTY" "HOME" "OFFICE_AND_BUSINESS" "RETAIL" "SERVICES_AND_SUBSCRIPTIONS" "TRAVEL" "UTILITIES_AND_TELECOM"

triple Offer Category

expiration_date
string or null <date> (OfferExpirationDate)

If specified, the last date on which the offer is valid.

headline
string (OfferHeadline) [ 6 .. 100 ] characters

The headline or title for the offer, appropriate for top-level display.

Array of objects or null (OfferMerchantCategories) [ 1 .. 25 ] items

The Merchant Category Codes included for a categorical offer.

merchant_website
string or null <url> (MerchantWebsite) <= 2000 characters ^https://.+$

Responses

Request samples

Content type
application/merge-patch+json
{
  • "category": "AUTOMOTIVE",
  • "expiration_date": "2021-12-31",
  • "headline": "string",
  • "merchant_categories": [
    ],
  • "merchant_website": "string"
}

Response samples

Content type
application/json
{
  • "activation_duration_in_days": 0,
  • "activation_required": true,
  • "category": "AUTOMOTIVE",
  • "category_tags": "string",
  • "currency_code": "USD",
  • "description": "string",
  • "effective_date": "2021-12-01",
  • "excluded_dates": [
    ],
  • "expiration_date": "2021-12-31",
  • "external_id": "string",
  • "headline": "string",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "invalid_day_parts": {
    },
  • "logo_url": "string",
  • "marketing_fee_currency_code": "USD",
  • "marketing_fee_rate": 0,
  • "marketing_fee_value": 0,
  • "marketing_fee_type": "FIXED",
  • "maximum_redemptions": "1/3M",
  • "maximum_reward_cumulative": "1/3M",
  • "maximum_reward_per_transaction": 0,
  • "merchant_categories": [
    ],
  • "merchant_website": "string",
  • "minimum_spend": 0,
  • "offer_budget": {
    },
  • "offer_mode": "ONLINE",
  • "offer_type": "CARD_LINKED",
  • "reward_rate": 0,
  • "reward_type": "FIXED",
  • "reward_value": 0,
  • "terms_and_conditions": "string",
  • "valid_day_parts": {
    }
}

Delete and Offer

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "content": {
    }
}

Portfolio Management

Operations related to managing Portfolios of Publishers.

Partners who manage Card Programs for multiple Publishers may wish to organize those Publishers into Portfolios. Portfolios allow Offer Exclusions to be applied across multiple Publishers without having to add each Publisher to each Offer Exclusion.

Get a list of Publishers

Returns a list of Publishers, optionally filtered.

Currently, this endpoint has a hard limit of returning up to 1,000 results. Future API releases may support paging results.

Authorizations:
triple_auth
query Parameters
publisher_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID of a Publisher. This parameter is ignored unless the client is a Portfolio Manager.

Responses

Response samples

Content type
application/json
{
  • "publishers": [
    ],
  • "total": 0
}

Create a Publisher

Authorizations:
triple_auth
Request Body schema: application/json
required
object (StrictAddress)

A physical address in the world, with required fields.

triple uses address validation services to update and standardize addresses on our platform. Address data sent to the API may be updated as we process, validate, and normalize addresses.

assumed_name
required
string (PublisherAssumedName) [ 1 .. 100 ] characters ^(?!\s).+(?<!\s)$

Assumed legal name of the Publisher

external_id
required
string (Publisher External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Publisher.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Publisher within the scope of its parent Portfolio Manager.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

revenue_share
number (PublisherRevenueShare) [ 0 .. 100 ]

The percent-based revenue share of this Publisher.

Only Portfolio Managers may set this value for their Publishers. If set, this will override the value set at the Portfolio Manager level.

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "external_id": "string",
  • "revenue_share": 1.125
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "portfolio_manager_id": "triple-abc-123",
  • "revenue_share": 1.125,
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Get a Publisher

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "portfolio_manager_id": "triple-abc-123",
  • "revenue_share": 1.125,
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Publisher

Updates a Publisher.

Currently, only the Publisher name and address may be updated.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
Any of
object (StrictAddress)

A physical address in the world, with required fields.

triple uses address validation services to update and standardize addresses on our platform. Address data sent to the API may be updated as we process, validate, and normalize addresses.

assumed_name
required
string (PublisherAssumedName) [ 1 .. 100 ] characters ^(?!\s).+(?<!\s)$

Assumed legal name of the Publisher

Responses

Request samples

Content type
application/merge-patch+json
{
  • "address": {
    },
  • "assumed_name": "string"
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "portfolio_manager_id": "triple-abc-123",
  • "revenue_share": 1.125,
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Rewards

Operations for Partners to approve, deny, or aggregate Rewards.

List Rewards

Lists Rewards and associated Transaction details that triple has matched to active Offers in the last 90 days.

Authorizations:
triple_auth
query Parameters
status
string
Default: "PENDING_MERCHANT_APPROVAL"
Enum: "REJECTED" "PENDING_REVIEW" "PENDING_MERCHANT_APPROVAL" "DENIED_BY_MERCHANT" "PENDING_MERCHANT_FUNDING" "PENDING_TRANSFER_TO_PUBLISHER" "DISTRIBUTED_TO_PUBLISHER" "DISTRIBUTED_TO_CARDHOLDER"

The Reward status.

  • REJECTED - The Transaction did not meet the offer terms.
  • PENDING_REVIEW - The Transaction is pending a manual review. The reward may be deleted if it is determined to be an invalid match to this merchant's offer.
  • PENDING_MERCHANT_APPROVAL - The Transaction is waiting for the Merchant or Content Provider to approve or deny the Reward.
  • DENIED_BY_MERCHANT - The Merchant or Content Provider denied the Reward. A reason will be included in reward_details.
  • PENDING_MERCHANT_FUNDING - The Reward was approved and is awaiting funding by the Merchant.
  • PENDING_TRANSFER_TO_PUBLISHER - The Reward is funded and funds are awaiting distribution to the Publisher.
  • DISTRIBUTED_TO_PUBLISHER - Reward funds have been sent to the Publisher.
  • DISTRIBUTED_TO_CARDHOLDER - The Publisher has reported that the Reward has been given to the cardholder.
page
integer
Default: 1

The page of results for returned Objects.

page_size
integer
Default: 1000

The size of pages for returned Objects.

Responses

Response samples

Content type
application/json
{
  • "rewards": [
    ],
  • "total": 0
}

Update Reward Statuses in Bulk

This endpoint provides significant performance advantages, over PATCHing single rewards, when updating large numbers of reward statuses.

This endpoint is currently rate limited at 5 requests per minute.

Request Semantics:

This endpoint uses all-or-nothing semantics. If even one reward fails to update, the entire request will return a failure response.

Constraints:

  • Content Providers may only update rewards with a status of PENDING_MERCHANT_APPROVAL to DENIED_BY_MERCHANT or PENDING_MERCHANT_FUNDING.
    • When updating reward statuses to DENIED_BY_MERCHANT, the notes field must be populated with an explanation for the denial.
  • Publishers (and Portfolio Managers) may only update rewards with a status of DISTRIBUTED_TO_PUBLISHER to DISTRIBUTED_TO_CARDHOLDER.
  • Only Triple may set the rejection and notification fields.
  • Updates to the same allowed status are also accepted. (e.g. PENDING_MERCHANT_FUNDING to PENDING_MERCHANT_FUNDING)
Authorizations:
triple_auth
Request Body schema: application/json
action
required
string
Value: "update_status"

The action to take

required
Array of objects (RewardStatusPatchBulkItem) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "action": "update_status",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "result": "SUCCESS"
}

Update Reward Statuses in Bulk Deprecated

This endpoint provides significant performance advantages, over PATCHing single rewards, when updating large numbers of reward statuses. The behavior of the two endpoints is nearly the same except for some minor differences in how errors are handled.

You should check the result_type of the response to handle errors for individual items. If the top-level request returns a Client Error response (response codes 400-499), no rewards from the batch were updated.

This endpoint is currently rate limited at 5 requests per minute.

Constraints:

  • Content Providers may only update rewards with a status of PENDING_MERCHANT_APPROVAL to DENIED_BY_MERCHANT or PENDING_MERCHANT_FUNDING.
    • When updating reward statuses to DENIED_BY_MERCHANT, the notes field must be populated with an explanation for the denial.
  • Publishers (and Portfolio Managers) may only update rewards with a status of DISTRIBUTED_TO_PUBLISHER to DISTRIBUTED_TO_CARDHOLDER.
  • Only Triple may set the rejection and notification fields.
Authorizations:
triple_auth
Request Body schema: application/json
action
required
string
Value: "update_status"

The action to take

reward_ids
required
Array of strings (EntityId) [ 1 .. 1000 ] items [ items [ 1 .. 100 ] characters ]
required
object (RewardStatusPatch)

Responses

Request samples

Content type
application/json
{
  • "action": "update_status",
  • "reward_ids": [
    ],
  • "reward_status": {
    }
}

Response samples

Content type
application/json
{
  • "failures": [
    ],
  • "result_summary": { },
  • "result_type": "COMPLETE_FAILURE"
}

Update the status of a Reward

Transitions a Reward from its current status to a new status.

Content Providers may only update rewards with a status of PENDING_MERCHANT_APPROVAL to DENIED_BY_MERCHANT or PENDING_MERCHANT_FUNDING.

When updating a reward to DENIED_BY_MERCHANT, the notes field must be populated with an explanation for the denial.

Publishers (and Portfolio Managers) may only update rewards with a status of DISTRIBUTED_TO_PUBLISHER to DISTRIBUTED_TO_CARDHOLDER.

Only Triple may set the rejection and notification fields.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
status
required
string (RewardStatus)
Enum: "REJECTED" "PENDING_REVIEW" "PENDING_MERCHANT_APPROVAL" "DENIED_BY_MERCHANT" "PENDING_MERCHANT_FUNDING" "PENDING_TRANSFER_TO_PUBLISHER" "DISTRIBUTED_TO_PUBLISHER" "DISTRIBUTED_TO_CARDHOLDER"

The Reward status.

  • REJECTED - The Transaction did not meet the offer terms.
  • PENDING_REVIEW - The Transaction is pending a manual review. The reward may be deleted if it is determined to be an invalid match to this merchant's offer.
  • PENDING_MERCHANT_APPROVAL - The Transaction is waiting for the Merchant or Content Provider to approve or deny the Reward.
  • DENIED_BY_MERCHANT - The Merchant or Content Provider denied the Reward. A reason will be included in reward_details.
  • PENDING_MERCHANT_FUNDING - The Reward was approved and is awaiting funding by the Merchant.
  • PENDING_TRANSFER_TO_PUBLISHER - The Reward is funded and funds are awaiting distribution to the Publisher.
  • DISTRIBUTED_TO_PUBLISHER - Reward funds have been sent to the Publisher.
  • DISTRIBUTED_TO_CARDHOLDER - The Publisher has reported that the Reward has been given to the cardholder.
rejection
string (RewardRejection)
Enum: "PURCHASE_AMOUNT_TOO_LOW" "ACTIVATION_REQUIRED" "MAX_USES_MET" "MAX_REWARD_MET" "DAY_OF_WEEK_RESTRICTION" "TIME_OF_WEEK_RESTRICTION" "EXCLUDED_DATE" "NON_PARTICIPATING_LOCATION" "OFFER_FILTER" "OTHER"

The Reward rejection type.

  • PURCHASE_AMOUNT_TOO_LOW - The Transaction amount wasn't enough to meet the minimum spend of the Offer.
  • ACTIVATION_REQUIRED - The Offer required activation beforehand in order to receive the Reward.
  • MAX_USES_MET - The Card Account already reached the maximum redemption limit of the Offer.
  • MAX_REWARD_MET - The Card Account already reached the maximum reward limit of the Offer.
  • DAY_OF_WEEK_RESTRICTION - The Offer wasn't available during the day of the week the Card Account attempted to redeem the Offer.
  • TIME_OF_WEEK_RESTRICTION - The Offer wasn't available during the time of the week the Card Account attempted to redeem the Offer.
  • EXCLUDED_DATE - The Offer wasn't available on the date the Card Account attempted to redeem the Offer.
  • NON_PARTICIPATING_LOCATION - The Card Account attempted to redeem the Offer at a location for which the offer does not apply.
  • OFFER_FILTER - The Card Account was not allowed to redeem the Offer due to filters applied by the Content Provider.
  • OTHER - Any other reason for rejection that isn't listed above.
notes
string (RewardRejectionNotes) <= 512 characters

A text description or additional information about why the Offer was rejected or denied by the merchant. This field is not intended to be displayed to cardholders.

notification
boolean (RewardNotification)
Default: true

Whether to publish a notification about a reward status update or not.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "status": "REJECTED",
  • "rejection": "PURCHASE_AMOUNT_TOO_LOW",
  • "notes": "string",
  • "notification": true
}

Response samples

Content type
application/json
{
  • "amount": 0,
  • "currency_code": "USD",
  • "notes": "string",
  • "offer_id": "triple-abc-123",
  • "rejection": "PURCHASE_AMOUNT_TOO_LOW",
  • "reward_id": "triple-abc-123",
  • "status": "REJECTED",
  • "status_updated_at": "2021-12-01T01:59:59.000Z"
}

Get the details of a reward.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "reward_id": "triple-abc-123",
  • "transaction_id": "triple-abc-123",
  • "offer_id": "triple-abc-123",
  • "offer_external_id": "string",
  • "transaction_timestamp": "2021-12-01T01:59:59.000Z",
  • "card_bin": "444789",
  • "card_last_4": "0001",
  • "transaction_amount": 12,
  • "transaction_currency_code": "USD",
  • "reward_amount": 0,
  • "reward_currency_code": "USD",
  • "offer_headline": "string",
  • "merchant_name": "string",
  • "merchant_complete_address": "7370 BAKER ST, STE 100\nPITTSBURGH, PA 15206",
  • "status": "REJECTED"
}

Tools

API utility endpoints

Healthcheck

Checks to see if the API is healthy. Returns information about the API version.

Responses

Response samples

Content type
application/json
{
  • "api_version": "string",
  • "build": "string"
}

Identity of logged in user

Returns information about the API logged in user

This endpoint is for internal use only and will change between versions. Use at your own risk.

Responses

Response samples

Content type
application/json
{
  • "client_id": "string",
  • "content_provider": "string",
  • "portfolio_manager": "string",
  • "publisher": "string"
}

Transactions

Overview

Operations related to reporting Transactions and checking related reward eligibility and status.

All Transactions for Purchases and Returns must be uploaded for Card Accounts, and Transaction amounts should not include "cash back".

Reward Lifecycle

A Transaction that matches an Offer will go through the following stages:

  • Matching - triple determines whether the Transaction matches any active Offers and potentially meets the Offer terms.
  • Qualification - The Merchant or Content Provider reviews matched Transactions and approves or denies the Reward.
  • Funding - The Merchant or Content Provider transfers funds to pay for approved Rewards.
  • Distribution - triple sends Reward funds to the Publisher, which then issues the appropriate Reward (cash back, points, miles, etc.) to the cardholder. The Publisher then informs triple that the cardholder has received the Reward.

Automatic Creation of Card Accounts

Each Transaction uploaded to triple must be linked to a Card Account. If a Card Account does not exist, a best effort will be made to create one with a "NOT_ENROLLED" status. For this to succeed, the Card Program must be resolvable based on the external ID(s) provided in the request.

Old Transactions

Transactions must be uploaded within 7 days of the transaction date to be eligible for a Reward. Historic Transactions may be uploaded to improve Offer Recommendations and targeting but are not eligible for Rewards.

Get a list of Transactions

Authorizations:
triple_auth
query Parameters
publisher_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID of a Publisher. This parameter is ignored unless the client is a Portfolio Manager.

card_program_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

card_account_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

transaction_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

start_date
string <date> ^\d{4}-\d{2}-\d{2}
Example: start_date=2022-06-01

Include only transactions starting from this date (YYYY-mm-dd)

end_date
string <date> ^\d{4}-\d{2}-\d{2}
Example: end_date=2022-06-30

Include only transactions through this date (YYYY-mm-dd)

matched
boolean

Include only transactions matched to an active offer. See the Reward Details for more information, such as whether an award is approved.

Responses

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "total": 0
}

Create a Transaction

Important notes:

  • Do not submit authorizations as purchases.
  • The amount for a Purchase transaction should not include cashback if it was part of the transaction.
  • Transactions must be uploaded within 7 days of when they take place.
  • Triple leverages these fields to generate rewards on the transaction
    • card_bin
    • card_last_4
    • processor_mid
    • processor_mid_type
    • merchant_address.postal_code
    • merchant_address.country_subdivision_code
    • merchant_category_code

Note: Triple will make every effort to match transactions with any information that is submitted. However, without the above fields, we make no guarantee that a transaction will be matched and/or submitted for a cardholder reward or marketing fee.

Authorizations:
triple_auth
Request Body schema: application/json
amount
required
number (TransactionAmount) > 0

The amount of the transaction. An error will be returned if the field contains fractional amounts smaller than those allowed by the transaction's currency code.

card_account_external_id
required
string (Card Account External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Account.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Card Account within the scope of its parent Card Program.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

card_bin
required
string (CardBIN) = 6 characters ^\d{6}$

The Bank Identification Number (BIN) of a payment card.

card_last_4
required
string (CardLast4) = 4 characters ^\d{4}$

The last four digits of the Primary Account Number (PAN) of a card.

card_program_external_id
required
string (Card Program External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Program.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Card Program within the scope of its parent Publisher.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

currency_code
string (CurrencyCode) = 3 characters ^[A-Z]{3}$
Default: "USD"

3-character ISO-4217 currency code. Only USD is currently supported.

Contact your Triple representative for support with additional currencies. Note that some values are not supported, particularly test and fund codes.

debit
required
boolean (TransactionIsDebit)

Whether this is a debit or credit

description
required
string (TransactionDescription) [ 1 .. 256 ] characters

The transaction description, usually the merchant name

external_id
required
string (Transaction External ID) [ 1 .. 255 ] characters ^[a-z0-9]([-_\.a-z0-9]{0,48}[a-z0-9])?$

Partner-provided, external ID.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for Transactions within the scope of the associated Card Account.

merchant_category_code
string (MerchantCategoryCode) = 4 characters ^\d{4}$

The 4-digit Merchant Category Code

object (Address)

A physical address in the world. triple uses address validation services to update and standardize addresses on our platform. Address data sent to the API may be updated as we process, validate, and normalize addresses. NOTE: Though not marked as required, the street address, postal code, and country code are required for transaction matching to function properly.

processor_mid
string (ProcessorMIDValue) [ 1 .. 50 ] characters

The Merchant ID (MID) value

processor_mid_type
string (ProcessorMIDType)
Enum: "AMEX_SE_NUMBER" "DISCOVER_MID" "MC_AUTH_LOC_ID" "MC_AUTH_ACQ_ID" "MC_AUTH_ICA" "MC_CLEARING_LOC_ID" "MC_CLEARING_ACQ_ID" "MC_CLEARING_ICA" "MERCHANT_PROCESSOR" "NCR" "VISA_VMID" "VISA_VSID"

The type of Merchant ID

publisher_external_id
string (Publisher External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Publisher.

External IDs should be stable and never sensitive.

External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Publisher within the scope of its parent Portfolio Manager.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

timestamp
required
string <date-time> (Timestamp)

RFC 3339 date time used for creation and mod times

transaction_type
required
string (TransactionType)
Enum: "CHECK" "DEPOSIT" "FEE" "PAYMENT" "PURCHASE" "REFUND" "TRANSFER" "WITHDRAWAL"

The type of transaction. triple will only calculate offers based on a history of Purchases and Refunds.

Responses

Request samples

Content type
application/json
{
  • "amount": 12,
  • "card_account_external_id": "string",
  • "card_bin": "444789",
  • "card_last_4": "0001",
  • "card_program_external_id": "string",
  • "currency_code": "USD",
  • "debit": true,
  • "description": "Pittsburgh Zoo",
  • "external_id": "string",
  • "merchant_category_code": "7998",
  • "merchant_address": {
    },
  • "processor_mid": "9000012345",
  • "processor_mid_type": "VISA_VMID",
  • "publisher_external_id": "string",
  • "timestamp": "2021-12-01T01:59:59.000Z",
  • "transaction_type": "PURCHASE"
}

Response samples

Content type
application/json
{
  • "amount": 12,
  • "card_account_id": "triple-abc-123",
  • "card_account_external_id": "string",
  • "card_bin": "444789",
  • "card_last_4": "0001",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "currency_code": "USD",
  • "debit": true,
  • "description": "Pittsburgh Zoo",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "matching_status": "HISTORIC_TRANSACTION",
  • "merchant_address": {
    },
  • "merchant_category": {
    },
  • "processor_mid": "9000012345",
  • "processor_mid_type": "VISA_VMID",
  • "reward_details": [
    ],
  • "timestamp": "2021-12-01T01:59:59.000Z",
  • "transaction_type": "PURCHASE",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Create Transactions in Bulk (Beta)

Important notes:

  • Do not submit authorizations as purchases.
  • The amount for a Purchase transaction should not include cashback if it was part of the transaction.
  • Transactions must be uploaded within 7 days of when they take place.
  • Triple leverages these fields to generate rewards on the transaction
    • card_bin
    • card_last_4
    • processor_mid
    • processor_mid_type
    • merchant_address.postal_code
    • merchant_address.country_subdivision_code
    • merchant_category_code

Note: Triple will make every effort to match transactions with any information that is submitted. However, without the above fields, we make no guarantee that a transaction will be matched and/or submitted for a cardholder reward or marketing fee.

This endpoint provides significant performance advantages, over POSTing single transactions, when creating large numbers of transactions. The behavior of the two endpoints is nearly the same except for some minor differences in how errors are handled.

You should check the result_type of the response to handle errors for individual items. If the top-level request returns a Client Error response (response codes 400-499), no transactions from the batch were created.

This endpoint is currently rate limited at 100 requests per minute.

Authorizations:
triple_auth
Request Body schema: application/json
action
required
string
Value: "create"

The action to take

required
Array of objects (TransactionPost) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "action": "create",
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "failures": [
    ],
  • "result_summary": { },
  • "result_type": "COMPLETE_FAILURE"
}

Get a Transaction

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "amount": 12,
  • "card_account_id": "triple-abc-123",
  • "card_account_external_id": "string",
  • "card_bin": "444789",
  • "card_last_4": "0001",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "currency_code": "USD",
  • "debit": true,
  • "description": "Pittsburgh Zoo",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "matching_status": "HISTORIC_TRANSACTION",
  • "merchant_address": {
    },
  • "merchant_category": {
    },
  • "processor_mid": "9000012345",
  • "processor_mid_type": "VISA_VMID",
  • "reward_details": [
    ],
  • "timestamp": "2021-12-01T01:59:59.000Z",
  • "transaction_type": "PURCHASE",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

User Events

User Events and Preferences

Post User Events

Post User Events

For the best user experience, post user events to the triple API as they occur. This allows triple to provide users with a more personalized user experience by responding to user preference signals in near-real time.

Payload Descriptions

event_type description
HIDE_OFFER User requests to never see an offer again
LESS_LIKE_THIS_OFFER User dislikes an offer
MORE_LIKE_THIS_OFFER User likes an offer
OFFER_ENTERS_VIEWPORT Offer details enter the user's viewport
OFFER_EXITS_VIEWPORT Offer details exit the user's viewport
Request Body schema: application/json
event_timestamp
required
string <date-time> (Timestamp)

RFC 3339 date time used for creation and mod times

event_type
required
string

Identifies the Event type

object

Geo-political locality, given as a country code and postal code

object

GeoCoordinates given as latitude, longitude pair

card_account_id
required
string (EntityId) [ 1 .. 100 ] characters

The triple-defined ID for the entity.

user_interface
required
string (UserInterface)
Enum: "WEB" "MOBILE" "POINT_OF_SALE"

Enum of User Interfaces

offer_id
required
string (EntityId) [ 1 .. 100 ] characters

The triple-defined ID for the entity.

Responses

Request samples

Content type
application/json
Example
{
  • "event_timestamp": "2021-12-01T01:59:59.000Z",
  • "event_type": "HIDE_OFFER",
  • "user_postal_code_location": {
    },
  • "user_coordinates": {
    },
  • "card_account_id": "triple-abc-123",
  • "user_interface": "WEB",
  • "offer_id": "triple-abc-123"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Get User Preferences

Get user preferences for a card account.

path Parameters
card_account_id
required
string
Example: triple-card-123

The triple card account id to get preferences for.

query Parameters
preference
string
Enum: "HIDE_OFFER" "LESS_LIKE_THIS_OFFER" "MORE_LIKE_THIS_OFFER" "OFFER_ACTIVATION"
Example: preference=LESS_LIKE_THIS_OFFER

Filter the response to this single preference.

Responses

Response samples

Content type
application/json
{
  • "user_preferences": [
    ]
}

Delete User Preferences

Delete one or all user preferences for a card account.

path Parameters
card_account_id
required
string
Example: triple-card-123

The triple card account id to delete preferences for.

query Parameters
offer_id
string
Example: offer_id=triple-offer-123

A specific triple offer id to delete a preference for.

Responses

Response samples

Content type
application/json
{
  • "total": 17
}

Webhooks

Manage notifications subscriptions and an example notification from Triple.

Notifications

Note: This is not a valid triple API endpoint.

If a Publisher or Portfolio Manager subscribes to receive notifications we will send reward status messages to the registered endpoint. This describes what our outbound webhook call will provide to the triple partner.

The payload is contained as a string within the Message key sent by AWS SNS.

The transaction_amount and reward_amount fields are passed as strings but always contain decimal numerics.

Request Body schema: application/json

The Transaction webhook payload is contained within a Notification type SNS message. The AWS documentation on this format is available in AWS SNS Message and JSON formats.

publisher_external_id
string

The external identifier for the publisher

card_program_external_id
required
string

The external identifier for the card program

card_account_external_id
required
string

The external identifier for the card account

transaction_external_id
required
string

The matching transaction which caused the reward to be triggered

offer_id
required
string

The identifier for the offer

reward_id
required
string

The identifier for the reward

merchant_name
string

The full name of the merchant offering the reward

reward_status
required
string

The status of the reward which currently is one of PENDING_MERCHANT_APPROVAL and DENIED_BY_MERCHANT with more statuses in the pipeline.

reward_amount
string

The amount of the reward earned

reward_currency_code
required
string

The currency code of the reward

transaction_timestamp
required
string

The timestamp of the initial transaction

transaction_amount
required
string

The amount of initial transaction

transaction_currency_code
required
string

The currency code of the initial transaction

notes
string

A text description or additional information about why the Offer was rejected or denied by the merchant. This field is not intended to be displayed to cardholders.

rejection
string
Enum: "ACTIVATION_REQUIRED" "DAY_OF_WEEK_RESTRICTION" "EXCLUDED_DATE" "MAX_REWARD_MET" "MAX_USES_MET" "NON_PARTICIPATING_LOCATION" "OTHER" "PURCHASE_AMOUNT_TOO_LOW" "TIME_OF_WEEK_RESTRICTION"

Responses

Request samples

Content type
application/json
Example
{
  • "publisher_external_id": "pub-1231231",
  • "card_program_external_id": "card-program-1234-5678",
  • "card_account_external_id": "card-account-1234-5678",
  • "transaction_external_id": "tx-12314",
  • "offer_id": "34",
  • "reward_id": "reward-1231231",
  • "merchant_name": "Acme Tools",
  • "reward_status": "PENDING_MERCHANT_APPROVAL",
  • "reward_amount": "0.120",
  • "reward_currency_code": "USD",
  • "transaction_timestamp": "2022-07-30T00:43:00Z",
  • "transaction_amount": "12.340",
  • "transaction_currency_code": "USD"
}

Subscribe To Notifications

Subscribe to notifications using a user-supplied webhook.

Triple notifications are implemented using AWS SNS. The AWS documentation for subscription confirmation message details is available in AWS SNS Message and JSON formats.

After receiving a successful response from this endpoint, you will receive a confirmation POST to the supplied webhook similar to the following to validate your subscription:

{
  "Type": "SubscriptionConfirmation",
  "MessageId": "...",
  "TopicArn": "arn:aws:sns:region:account-id:sns-topic-arn",
  "Message": "You have chosen to subscribe to the topic arn:aws:sns:region:account-id:sns-topic-arn.\n
  To confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL": "https://sns.region.amazonaws.com/?Action=ConfirmSubscription&TopicArn=...",
  "Timestamp" :"2022-01-01T00:00:00.000Z",
  "SignatureVersion": "1",
  "Signature": "...",
  "SigningCertURL": "..."
}

After issuing a GET request for the SubscribeURL you will receive a response like the following:

<ConfirmSubscriptionResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
  <ConfirmSubscriptionResult>
    <SubscriptionArn>...</SubscriptionArn>
  </ConfirmSubscriptionResult>
  <ResponseMetadata>
    <RequestId>...</RequestId>
  </ResponseMetadata>
</ConfirmSubscriptionResponse>

The SubscriptionArn in the response can be used to unsubscribe from the topic by hitting the DELETE /notifications/$SubscriptionArn link in the API. Alternatively for received messages they also contain an UnsubscribeURL which will do the same.

For several reward statuses you'll get an SNS message from AWS for example:

{
  "Type": "Notification",
  "MessageId": "...",
  "TopicArn": "...",
  "Subject": "Reward Pending Merchant Approval",
  "Message": "{\"publisher_external_id\": null, \"card_program_external_id\": null, \"card_account_external_id\": null, \"transaction_external_id\": \"tx-1\", \"merchant_name\": \"L'Osteria\", \"reward_status\": \"PENDING_MERCHANT_APPROVAL\", \"reward_amount\": \"0.00\", \"currency_code\": \"USD\", \"transaction_timestamp\": \"2022-08-03T01:00:00Z\", \"transaction_amount\": \"20\", \"transaction_currency_code\": \"USD\"}",
  "Timestamp": "2022-01-01T00:00:00.000Z",
  "SignatureVersion": "1",
  "Signature": "...",
  "SigningCertURL": "...",
  "UnsubscribeURL": "...",
  "MessageAttributes": {
    "publisher_id": {
      "Type": "String",
      "Value": "2"
    }
  }
}

If you subscribe with a publisher account, you will receive any applicable statuses for that publisher that occur.

When you subscribe with a portfolio manager account you will receive notifications on statuses for all publishers in a single subscription.

Authorizations:
triple_auth
Request Body schema: application/json
endpoint
required
string

The webhook endpoint you'd like subscriptions to go to

Responses

Request samples

Content type
application/json
{
  • "endpoint": "string"
}

Response samples

Content type
application/json
{
  • "endpoint": "string",
  • "message": "Subscription to https://my.webhook.numo.com successfully added"
}

Unsubscribe Notification

Authorizations:
triple_auth
path Parameters
subscriptionArn
required
string (SubscriptionArn) >= 25 characters
Example: arn:aws:sns:us-east-1:1234567890:transaction-matching-notifications:7689338f-f44f-4400-a72f-16e09be41268

The AWS ARN for the SNS Subscription

Responses

Response samples

Content type
application/json
{
  • "message": "Successfully unsubscribed a4d2f2a2-9d68-4d5f-b840-b5dee436cdfd",
  • "subscriptionArn": "string"
}

Get Webhook Subscription

Authorizations:
triple_auth
path Parameters
subscriptionArn
required
string (SubscriptionArn) >= 25 characters
Example: arn:aws:sns:us-east-1:1234567890:transaction-matching-notifications:7689338f-f44f-4400-a72f-16e09be41268

The AWS ARN for the SNS Subscription

Responses

Response samples

Content type
application/json
{
  • "portfolio_manager_id": "string",
  • "publisher_id": "string"
}
Footer