API Documentation

API DOCUMENTATION

Last Update: July 2025



Premiere Access Enterprise-Level API Calls API Calls Overview Clients (Businesses) Account - Update Account - Info Dashboard - Info Custom Fields Customer Field - Create Customer Fields - List Customer Field - Update Customer Field - Delete Transaction Field - Create Transaction Fields - List Transaction Field - Update Transaction Field - Delete Reward Custom Field - Create Reward Custom Fields - List Reward Custom Field - Update Reward Custom Field - Delete Users (Business Employees) User - New User - Update Users - List User - Info User - Delete Users - Add to Campaign Users - Rem. from Campaign Loyalty Programs Campaign - New Campaign Campaign - New Reward Campaign - New Promo Campaign - New BuyX Item Campaign - New Depreciation Campaign - New Fee Campaign - Update Campaign Campaign - Update Reward Campaign - Update Promo Campaign - Update BuyX Item Campaign - Update Depreciation Campaign - Update Fee Campaign - List Campaigns Campaign - List Deactivated Campaign - List Rewards Campaign - List Promotions Campaign - List Depreciations Campaign - List Fees Campaign - List BuyX Items Campaign - Delete Campaign Campaign - Delete Reward Campaign - Delete Promo Campaign - Delete BuyX Item Campaign - Delete Depreciation Campaign - Delete Fee Campaign - Deactivate Campaign - Reactivate Customers Customer - New/Register Customer - Update Customer - Generate Card # Customer - Batch Customer - Search Customer - Find Customer - Information Customer - Exists Customer - Balance & History Customer - Delete Customer - Validate Card Replace Transactions Transaction - Record Transaction - Redeem Transaction - Batch Transaction - Delete Misc. Calls: Token - Get Token - Validate Audit Reports All Transactions All Redeemed Transactions Campaign Totals Customer Balances Marketing Reports All Customers New Customers Frequent Customers Missing Customers Birthdays Custom Date Range Customer Search Reference Currency Codes Country Codes Timezones Available Languages User Permission Levels Replacement Codes Premium APIs Email Templates Email Template - New Email Template - Update Email Template - Information Email Templates - List Email Template - Delete SMS Templates SMS List Service Providers SMS Add Credentials SMS Update Credentials SMS Template - New SMS Template - Update SMS Template - Information SMS Templates - List SMS Template - Delete Memberships Membership Program - New Membership Program - Update Membership Program - Info Membership Programs - List Membership Program - Delete Membership Level - New Membership Level - Update Membership Level - Info Membership Levels - List Membership Level - Delete Boost Promos Fixed Boost - New Fixed Boost - Update Temporary Boost - New Temporary Boost - Update Recurring Boost - New Recurring Boost - Update Boost - Info Boost - List Boost - Delete

Redemption Transaction

Record a redemption transaction for a customer account.

Headers

		Key		Value		Note
		api_access_key		user_api_key		Optional

The data to be submitted to the API is composed of the following fields:

Fields common to all campaign types:

field	Example	Note
user_id	john1970	Required
user_password	1959caadac9b13dcb3	Required if not included in the headers
type	redeem	Required
account_id	greatwidgets	Required
code	1234567890123456	Required

Output Format:
output	JSON or XML	Optional. If not provided, defaults to XML
callback	someFunctionName	Optional: JSONP format
condensed	yes	Optional (No white space) Applies only to JSON(P) output

Fields for Points-Based Campaigns:

field	Example	Note
campaign_id	111234567890123456	Required
custom_points_redeem	100	\ \ Required: At least / one of these three ./
custom_dollars_redeem	9.95 or 9,95
reward_to_redeem	98
authorization	Custom description	Optional

Note: Use the campaign_rewards API call to list the available rewards and their IDs

Fields for Gift-Card Campaigns:

field	Example	Note
campaign_id	2234567890123456456	Required
reward_to_redeem	9.95 or 9,95	Required
authorization	Custom description	Optional

Fields for Buy-X-Get-One-Free / Membership Campaigns:

field	Example	Note
campaign_id	3334567890123456456	Required
reward_to_redeem	96 (the item_id) or [item_identifier]	Required See note below
authorization	Custom description	Optional

Note: Use the buyx_items_list API call to list available items and their IDs.

Fields for Events (Visits) Based Campaigns:

field	Example	Note
campaign_id	4444567890123456456	Required
reward_to_redeem	41	Required See note below
authorization	Custom description	Optional

Note: Use the campaign_rewards API call to list the available rewards and their IDs

Fields for Earn-per-Event (Visits) Campaigns:

field	Example	Note
campaign_id	55567890123456456	Required
reward_to_redeem	9.95 or 9,95	Required
authorization	Custom description	Optional

Notes:

Headers: the user_api_key value can be included in either the header section or the body of the request. If the key is provided in both locations, the API will process and validate only the value provided in the headers.
'When using this call, the 'code' MUST be the unique Customer ID that was either
- passed as 'code' by your program when the customer record was created previously, or
- the 16-digit number that was generated by us and returned to you in the API response.
Before making this call, you should check whether the customer balance is greater than the amount to be redeemed.
The reward_to_redeem field value is the <id> parameter that is returned in the response of the Campaign Rewards call -- OR the optional <reward_id> that is defined in the Campaign - New BuyX Item and Campaign - Edit BuyX Item API calls.
For coalition accounts, the balance for each campaign will be the coalition balance, not the individual campaign balance. Hence the totals of the transactions for each campaign may not add up to the coalition balance, since the customer may have multiple transactions in multiple campaign(s).

Example PHP Requests:

If you are using PHP, the $data array would look like this:

Points-Based Campaign - Pre-defined Reward:

$data['user_id'] = 'john1970';
$data['user_password'] = '1959caadac9b13dcb3';
$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '111234567890123456';
$data['reward_to_redeem'] = '98';
$data['authorization'] = 'Custom description';

Points-Based Campaign - Custom Points:

$data['user_id'] = 'john1970';
$data['user_password'] = '1959caadac9b13dcb3';
$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '111234567890123456';
$data['custom_points_redeem'] = '100';
$data['authorization'] = 'Custom description';

Points-Based Campaign - Monetary Amount:

Note: This capability is available ONLY if you have set a Spend-to-Reward Ratio in the point campaign's preferences.

$data['user_id'] = 'john1970';
$data['user_password'] = '1959caadac9b13dcb3';
$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '111234567890123456';
$data['custom_dollars_redeem'] = '9.95';
$data['authorization'] = 'Custom description';

Points-Based Campaign - Combination of reward types:

Note: Only one of each type can be used per call, abs the custom_dollars_redeem capability is available ONLY if you have set a Spend-to-Reward Ratio in the point campaign's preferences.

$data['user_id'] = 'john1970';
$data['user_password'] = '1959caadac9b13dcb3';
$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '111234567890123456';
$data['reward_to_redeem'] = '98';
$data['custom_points_redeem'] = '100';
$data['custom_dollars_redeem'] = '9.95';
$data['authorization'] = 'Custom description';

Gift Card Campaign:

$data['user_id'] = 'john1970';
$data['user_password'] = '1959caadac9b13dcb3';
$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '2234567890123456456';
$data['reward_to_redeem'] = '9.95';
$data['authorization'] = 'Custom description';

Buy-X-Get-One-Free Campaign:

$data['user_id'] = 'john1970';
$data['user_password'] = '1959caadac9b13dcb3';
$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '3334567890123456456';
$data['reward_to_redeem'] = '96';
$data['authorization'] = 'Custom description';

Events-Based Campaign:

$data['user_id'] = 'john1970';
$data['user_password'] = '1959caadac9b13dcb3';
$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '4444567890123456456';
$data['reward_to_redeem'] = '41';
$data['authorization'] = 'Custom description';

Earn-per-Event Campaign:

$data['user_id'] = 'john1970';
$data['user_password'] = '1959caadac9b13dcb3';
$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '55567890123456456';
$data['reward_to_redeem'] = '9.95';
$data['authorization'] = 'Custom description';

Success XML Responses

Note: The response XML will include information that can be used to print a receipt.

For Points Campaign:

<response status="success">
<receipt>
<account_name>Demo Business</account_name>
<agency>
<id>acmemktg</id>
<name>ACME Marketing</name>
<email>server@acmemarkting.com</email>
</agency>
<campaign>
<id>111234567890123456</id>
<name>Widget Rewards</name>
</campaign>
<customer>
<first_name>Jane</first_name>
<last_name>Doe</last_name>
<card_number>11112222</card_number>
<phone>555-5555</phone>
<email>jdoe@workemail.com</email>
<custom_field>She likes cheese</custom_field>
<custom_date>1970-07-14</custom_date>
</customer>
<transaction>
<id>1234</id>
<description>Optional note here</description>
<reward>
<id>98</id>
<points>100</points>
<description>Free Widget!</description>
</reward>
<custom>
<points>150</points>
</custom>
<monetary>
<amount>9.90</points>
<currency>USD</currency>
<points>1990</points>
</monetary>
<balance>
<points>4590</points>
<monetary>4.75</monetary>
<currency>USD</currency>
</balance>
<cumulative_balance>
<points>78390</points>
<monetary>43.50</monetary>
<currency>USD</currency>
</cumulative_balance>
</transaction>
</receipt>
</response>

For Gift Card Campaign:

<response status="success">
<receipt>
<account_name>Demo Business</account_name>
<agency>
<id>acmemktg</id>
<name>ACME Marketing</name>
<email>server@acmemarkting.com</email>
</agency>
<campaign>
<id>2234567890123456456</id>
<name>Gift Card</name>
</campaign>
<customer>
<first_name>Jane</first_name>
<last_name>Doe</last_name>
<card_number>11112222</card_number>
<phone>555-5555</phone>
<email>jdoe@workemail.com</email>
<custom_field>She likes cheese</custom_field>
<custom_date>1970-07-14</custom_date>
</customer>
<transaction>
<id>1234</id>
<deduct>
<amount>14.95</amount>
<currency>USD</currency>
<description>Optional note here</description>
</deduct>
<balance>
<amount>40.75</amount>
<currency>USD</currency>
</balance>
<cumulative_balance>
<amount>413.50</amount>
<currency>USD</currency>
</cumulative_balance>
</transaction>
</receipt>
</response>

For Events Campaign:

<response status="success">
<receipt>
<account_name>Demo Business</account_name>
<agency>
<id>acmemktg</id>
<name>ACME Marketing</name>
<email>server@acmemarkting.com</email>
</agency>
<campaign>
<id>4444567890123456456</id>
<name>Frequent Shopper</name>
</campaign>
<customer>
<first_name>Jane</first_name>
<last_name>Doe</last_name>
<card_number>11112222</card_number>
<phone>555-5555</phone>
<email>jdoe@workemail.com</email>
<custom_field>She likes cheese</custom_field>
<custom_date>1970-07-14</custom_date>
</customer>
<transaction>
<id>1234</id>
<description>Optional note here</description>
<reward>
<id>41</id>
<amount>9</amount>
<description>Free Widget!</description>
</reward>
<balance>
<events>12</events>
</balance>
<cumulative_balance>
<events>25</events>
</cumulative_balance>
</transaction>
</receipt>
</response>

For Earn-per-Event Campaign:

<response status="success">
<receipt>
<account_name>Demo Business</account_name>
<agency>
<id>acmemktg</id>
<name>ACME Marketing</name>
<email>server@acmemarkting.com</email>
</agency>
<campaign>
<id>55567890123456456</id>
<name>GateKeeper Rewards</name>
</campaign>
<customer>
<first_name>Jane</first_name>
<last_name>Doe</last_name>
<card_number>11112222</card_number>
<phone>555-5555</phone>
<email>jdoe@workemail.com</email>
<custom_field>She likes cheese</custom_field>
<custom_date>1970-07-14</custom_date>
</customer>
<transaction>
<id>1234</id>
<deduct>
<amount>14.95</amount>
<currency>USD</currency>
<description>Optional note here</description>
</deduct>
<balance>
<amount>22.50</amount>
<currency>USD</currency>
</balance>
<cumulative_balance>
<amount>45.00</amount>
<currency>USD</currency>
</cumulative_balance>
</transaction>
</receipt>
</response>

For Buy-X-Get-One-Free Campaign:

<response status="success">
<receipt>
<account_name>Demo Business</account_name>
<agency>
<id>acmemktg</id>
<name>ACME Marketing</name>
<email>server@acmemarkting.com</email>
</agency>
<campaign>
<id>3334567890123456456</id>
<name>Frequent Buyer Rewards</name>
</campaign>
<customer>
<first_name>Jane</first_name>
<last_name>Doe</last_name>
<card_number>11112222</card_number>
<phone>555-5555</phone>
<email>jdoe@workemail.com</email>
<custom_field>She likes cheese</custom_field>
<custom_date>1970-07-14</custom_date>
</customer>
<transaction>
<id>1234</id>
<description>Optional note here</description>
<reward>
<service_product>Books</service_product>
<deduct>10</deduct>
</reward>
<balances>
<item>
<name>Books</name>
<current>14</current>
<cumulative>14</cumulative>
</item>
<item>
<name>Coffees & Teas</name>
<current>6</current>
<cumulative>43</cumulative>
</item>
<item>
<name>Cakes & Cookies</name>
<current>2</current>
<cumulative>12</cumulative>
</item>
...
</balances>
</transaction>
</receipt>
</response>

Error XML Response:

<response status="error">
<error>Error message</error>
</response>