NOTE: THIS IS AN OLD ARTICLE. OUR FULL API CAN BE FOUND AT HTTP://API.CLIENTTOOLBOX.COM

QUESTION

I have an e-commerce site where I want to offer a rewards program. Is there a way to have it automatically update with the customer purchases from my site?

SOLUTION

Although the official answer is "no", technically, there are ways this can be achieved, depending on a few factors.

The program is made for manual entry, but we are working very hard on an "API" that will standardize this type of link with a REST-type of framework through XML.

That said, there are two way around the problem right now:

1) You can send us files to be batch-uploaded periodically. You can read more about this at: http://support.stickystreet.com/forums/16257/entries/10077

2) We have a sort of Quasi-API that can do some basic transaction recording -- with the caveat that its implementation will become obsolete when the new API is implemented. If you are able to send a GET request to a URL and ignore/throw away the output (in PHP, using "curl" and sending the resulting output to a variable that is then ignored.) Here are some instructions below, if you want to play around.

Again, however you implement the request on your end, make sure to ignore/discard any response from our server, which will attempt to return a fully formed HTML page.

=========== THE QUASI-PRE-API =========== 

When inserting a new account, create two requests: One to create the customer's account info, and a second to record the activity in a particular campaign.

If you aren't sure if a transaction is for a new or existing account, err on the side of send both requests. In fact, unless you have a way to know for sure that a transaction has had the customer info created, and there has been no changes to that info since, we would recommend that every transaction request is accompanied with a customer account info update request.

For Recording an account's user info

Use this to both record a new account or to edit an existing account's info.

Put together a URL on a _single line_ with the following elements:

https://www.scanandgorewards.com/admin.php?
user_id=AAAAA
&
user_password=BBBBB
&
campaign_id=CCCCC
&
card_number=EEEEE
&
type=record_customer
&
first_name=FFFFF
&
last_name=GGGGG
&
phone=HHHHH
&
email=IIIII
&
custom_date=JJJJJ
&
street1=KKKKK
&
street2=LLLLL
&
city=MMMMM
&
state=NNNNN
&
postal_code=OOOOO
&
country=PPPPP
&
custom1=QQQQQ
 

Where:

• BBBBB = MD5 Hash of your password. You can also get it by viewing the HTML source code of any page once you have logged in and are in SSL mode.
• CCCCC = Campaign name, escaped if it has spaces and other non-alphanumeric characters. ie: spaces are replaced by "%20" -- Ex: "Your%20Points"
• EEEEE = A unique identifier for this customer, such as a plastic card number, and email address, or identifier else that is unique to this customer -- This is NOT an optional field when using the API, since this unique identifier will be needed for transaction requests below to identify which customer to add a transaction to. Escape this value if it has spaces and other non-alphanumeric characters.
• FFFFF = OPTIONAL: The customer's First Name (escaped, since it may contain two names with a space, or international characters)
• GGGGG = OPTIONAL: The customer's Last Name (escaped, since it may contain two names with a space, or international characters)
• HHHHH = OPTIONAL: The customer's phone number (escaped, since it may contain parentheses, spaces and other characters. Please validate on your end first.)
• IIIII = OPTIONAL: The Customer's email address (no need to be escaped if validated on your end)
• JJJJJ through QQQQQ = OPTIONAL: Custom information about the customer. (escaped since it may contain spaces, etc.)

For recording Points campaign activity & creating new accounts

New customer accounts are automatically created when a record_activity request is received and the account/card code is not in the system already.

Put together a URL on a _single line_ with the following elements:

https://www.scanandgorewards.com/admin.php?
user_id=AAAAA
&
user_password=BBBBB
&
campaign_id=CCCCC
&
code=EEEEE
&
type=record_activity
&
amount=FFFFF
&
promo_id=GGGGG
&
authorization=HHHHH

Where:

• BBBBB = MD5 Hash of your password. You can also get it by viewing the HTML source code of any page once you have logged in and are in SSL mode.
• CCCCC = Campaign name, escaped if it has spaces and other non-alphanumeric characters. ie: spaces are replaced by "%20" -- Ex: "Your%20Points"
• EEEEE =  The unique identifier for this customer -- This has to be the same unique identifier that was set when the customer account was created in the request above. Escape this value if it has spaces and other non-alphanumeric characters.
• FFFFF = the amount, in dollars, without the $ sign (numeric value only)
• GGGGG = "none" is default, otherwise, the # of the promo. ex: Double Points Tuesday promo: 384 (contact me if you can't fid the promo IDs--they are part of the HTML page when promos are selectable.)
• HHHHH = OPTIONAL: A comment / authorization to be recorded with the transaction. Must be escaped.

For deducting / redeeming points

 Because there is no built-in way to check on your end if a customer's current point balance is greater than the amount to be redeemed, I would not recomment using this call, or do so very carefully in situations where it may be very certain that a customer has enough points for the transaction.

Put together a URL on a _single line_ with the following elements:

https://www.scanandgorewards.com/admin.php?
user_id=AAAAA
&
user_password=BBBBB
&
campaign_id=CCCCC
&
code=EEEEE
&
type=redeem
&
custom_points_redeem_max=FFFFF
&
custom_points_redeem=GGGGG
&
custom_dollars_redeem=HHHHH
&
reward_to_redeem=JJJJJ
&
authorization=KKKKK

Where:

• BBBBB = MD5 Hash of your password. You can also get it by viewing the HTML source code of any page once you have logged in and are in SSL mode.
• CCCCC = Campaign name, escaped if it has spaces and other non-alphanumeric characters. ie: spaces are replaced by "%20" -- Ex: "Your%20Points"
• EEEEE = The unique identifier for this customer -- This has to be the same unique identifier that was set when the customer account was created in the first request above "Recording an account's user info". Escape this value if it has spaces and other non-alphanumeric characters.
• FFFFF = the program usually passes on this information as a hidden variable so that a person can't deduct more than there is available. Without a normal API, there's no way to query for the customers current balance to insert here as a max. In this case, you'll probably have to enter the same amount as the quantity to be deducted.
• Use ONE of the following:
  
  • GGGGG = the exact number of points to be deducted.
  • HHHHH = the amount, in dollars, without the $ sign (numeric only)
  • JJJJJ = the reward code: 1231 = 500 points - Free Widget (and more if you define them) (contact me if you can't fid the reward IDs--they are part of the HTML page when rewards are selectable.)
• KKKKK = OPTIONAL: A comment / authorization to be recorded with the transaction. Must be escaped.

=========== END OF QUASI-PRE-API ===========