OpenSRS Offers API Command Reference · • $25 credit to the customer and $25 bounty per new...

OpenSRS OffersAPI Command Reference

June 20, 2013

Table of ContentsIntroduction.......................................................................................3

Fotolia...................................................................................................3Host Merchant Services...........................................................................3MightyCall ClickConnect...........................................................................4Ting......................................................................................................4

Accepting terms and condition.....................................................................5generate_codes.........................................................................................6

Request parameters for generate_codes....................................................6Response parameters for generate_codes..................................................7Examples for generate_codes...................................................................8

set_status...............................................................................................16Request parameters for set_status..........................................................16Response parameters for set_status........................................................16Examples for set_status.........................................................................17

view_codes..............................................................................................19Request parameters for view_codes........................................................19Response parameters for view_codes......................................................19Examples for view_codes.......................................................................20

Revisions and updates........................................................................24

2

IntroductionOpenSRS gives you the ability to generate codes that represent credits that you can give to your customers as an incentive or reward for signing up with you.

OpenSRS has partnered with the following companies to offer coupon codes:

• Fotolia

• Host Merchant Services

• MightyCall

• Ting

FotoliaFotolia has over 18 million royalty-free photos, vectors and HD videos, and helps more than 3 million customers find the right images for their creative needs. Spanning the globe in 12 languages and 20 countries, Fotolia is the first to offer both crowdsourced and professional images on one site.

You can generate up to 250 Fotolia codes per day, and each code is worth 10 Fotolia credits.

To redeem their coupon codes, direct your customers to http://www.fotolia.com/to

For more information about Fotolia, see http://www.fotolia.com

Host Merchant ServicesHost Merchant Services (HMS) provides complete credit card processing and financial transaction services for its customers.

You can generate promotional coupon codes for Host Merchant Services, worth $75 USD each, that you can distribute to your customers to use toward HMS payment processing services. You benefit by earning a percent of the net revenue that is generated by the customer's processing fees to HMS.

Note: To take advantage of the HMS offer, customers must either be in the U.S. or have a U.S. bank account.

For more information about Host Merchant Services, see http://www.hostmerchantservices.com/

To redeem their HMS promotional codes, direct your customers to http://www.hostmerchantservices.com/hms-promotional-offer/.

3

http://www.hostmerchantservices.com/hms-promotional-offer/

http://www.hostmerchantservices.com/

http://www.fotolia.com/

http://www.fotolia.com/to

MightyCall ClickConnectMightyCall ClickConnect enables website owners to add "in-browser" calling to improve customer ordering and customer support. The MightyCall ClickConnect service integrates several web technologies, telephony services and web applications into a simple to install, simple to use solution for just about any website. Visitors simply click a button and a web-dialer opens and immediately calls your pre-programmed phone number.

You can generate up to 100 MightyCall codes per day, and each code is worth 30 minutes of MightyCall ClickConnect service.

To redeem their coupon codes direct your customers to http://mightycall.com/clickconnect_signup.html

For more information about MightyCall, see http:// www.mightycall.com

TingTing is a mobile phone service that brings clarity, usability, and significant monthly savings to U.S. small businesses and families.

You can generate partner codes/URLs for credits towards the purchase of a Ting mobile device. When the customer purchases their first Ting device using this code/URL, they get a discount off the retail price and, depending on the Ting offer that you choose, you receive either a one-time bounty or a share of the net revenue from that customer's recurring fees during their first 24 months of service.

There are currently two Ting offers available:

• $25 credit to the customer and 10% gross margin to the Reseller.

• $25 credit to the customer and $25 bounty per new account to the Reseller.

Note: You can only generate one Ting partner code/URL per offer; however, that one code can be distributed to an unlimited number of customers.

To redeem this offer, your customers can visit the unique URL generated through offers (yourcode.ting.com), and the discount will be applied to their purchase automatically. Alternatively, you can direct your customers to http://www.ting.com and they can enter the partner code on checkout.

This guide provides information about the commands that are specific to the OpenSRS Offers Service:

• generate_codes —Generates a list of offer codes.

• set_status —Changes the status of an offer.

• view_codes —Displays all of the codes that you generated.

4

http://www.mightycall.com/

http://www.mightycall.com/

http://mightycall.com/clickconnect_signup.html

Accepting terms and conditionBefore you can generate and distribute offer codes, you need to accept the terms and conditions of each offer.

Note: You need to do this for each offer.

To accept terms and conditions

1. In the Control Panel, click the Offers Manager tab, and then click View Offers.Any offers for which you have not yet accepted the terms and conditions have a status of Available.

2. Click the offer that you're interested in.

3. On the Offer Details page, review the Terms and Conditions, then click to put a checkmark in the box beside I agree to the Terms and Conditions, and then click ACCEPT OFFER. The status of the offer changes to Accepted.

You can now generate codes for the offer.

5

generate_codes

Description

Action & objectaction = generate_codes

object = offers

UsageGenerates a list of offer codes that you can give to your customers.

Request parameters for generate_codes

Standard parametersaction = generate_codes

object = offers

attributes

AttributesParameters within the attributes associative array are described below.

Parameter name

Obligation Definition/Value

offer Required The type of offer for which you want to generate codes.

Allowed value for Fotolia:

fotolia_10_credits—Fotolia coupon code worth 10 free Fotolia credits.

Allowed value for HMS

hms_payment_processing—HMS promotional coupon codes that are worth $75 USD.

Allowed value for MightyCall

mightycall_30_min—MightyCall coupon code worth 30 minutes of free service.

Allowed values for Ting:

ting_25_credit_25_rev_share—Ting coupon code that is worth $25 USD to customer and gives the Reseller 25% revenue share for 24 months.

ting_25_credit_50_bounty—Ting coupon code that is worth $25 USD to customer and gives the Reseller $50 USD bounty.

6

Parameter name


quantity Required The number of unique codes that you want to generate for the specified offer type.

Fotolia—maximum is 250 codes per day.

HMS—maximum is 100 codes per offer per day.

MightyCall—maximum is 100 codes per day.

Ting—this number must be 1.

Response parameters for generate_codes

Standard parametersaction = reply

object = offers

is_success = a Boolean is returned, indicating success or failure of the request

response_code = response code indicating outcome of the request

response_text = message describing the outcome of the request


Parameter name

Obligation Definition / Value

codes Returned if success = true

The list of codes and their properties. For more information, see the Codes table.

CodesParameters within the codes associative array are described below.

Parameter name


code Always returned The code for the offer.

company_name Always returned The name of the company issuing the offer. Allowed values are: Fotolia, Host Merchant Services, MightyCall, or Ting.

creation_date Always returned The date that the code was generated, in the form, YYYY-MM-DDThh-mm-ssZ. The T indicates the start of

7

Parameter name


the time component and the Z indicates that it is UTC.

offer_name Always returned Description of the offer.

status Always returned The current status of the offer. The initial status is always available.

Examples for generate_codes

Example 1Generates a code for Fotolia.

Request<?xml version='1.0' encoding="UTF-8" standalone="no" ?>

<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">

<OPS_envelope>

<header>

<version>0.9</version>

</header>

<body>

<data_block>

<dt_assoc>

<item key="protocol">XCP</item>

<item key="action">GENERATE_CODES</item>

<item key="object">OFFERS</item>

<item key="attributes">

<dt_assoc>

<item key="offer">fotolia_10_credits</item>

<item key="quantity">1</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

8

Response<?xml version='1.0' encoding="UTF-8" standalone="no" ?>


<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">GENERATE_CODES:REPLY</item>


<item key="response_text">Successfully generated codes</item>

<item key="response_code">200</item>


<dt_assoc>

<item key="codes">

<dt_array>

<item key="0">

<dt_assoc>

<item key="offer_name">10 Free Fotolia Credits</item>

<item key="creation_date">2012-11-12T18:46:59Z</item>

<item key="offer">fotolia_10_credits</item>

<item key="status">available</item>

<item key="company_name">Fotolia</item>

<item key="code">TEST-FOTOLIA-0284-5702-33A4</item>

</dt_assoc>

</item>

</dt_array>

</item>

</dt_assoc>

</item>

<item key="is_success">1</item>

9

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

Example 2Generates a single code for Host Merchant Services.



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>





<dt_assoc>


<item key="offer">hms_payment_processing</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>



10

<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">REPLY</item>






<dt_assoc>

<item key="codes">

<dt_array>

<item key="0">

<dt_assoc>


<item key="company_name">Host Merchant Services</item>


<item key="offer_name">HMS Payment Processing</item>


<item key="code">HMSTEST-A04B-F5AF-391F</item>

</dt_assoc>

</item>

</dt_array>

</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

11

Example 3Generates a code for MightyCall ClickConnect.



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>





<dt_assoc>

<item key="offer">mightycall_30_min</item>


</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>



<OPS_envelope>

<header>


</header>

<body>

12

<data_block>

<dt_assoc>


<item key="action">GENERATE_CODES:REPLY</item>





<dt_assoc>

<item key="codes">

<dt_array>

<item key="0">

<dt_assoc>

<item key="offer_name">30 Free MightyCall Minutes</item>


<item key="offer">mightycall_30_min</item>


<item key="company_name">MightyCall</item>

<item key="code">TEST-D3B0-78B9-61AB</item>

</dt_assoc>

</item>

</dt_array>

</item>

</dt_assoc>

</item>


</dt_assoc>

</data_block>

</body>

</OPS_envelope>

13

Example 4Generates a code (URL) for Ting.

Request<?xml version="1.0"?>

<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>





<dt_assoc>


<item key="offer">ting_25_credit_50_bounty</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

Response<?xml version="1.0"?>

<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>

14


<item key="action">SET_STATUS</item>



<dt_assoc>

<item key="status">issued</item>

<item key="codes">

<dt_array>

<item key="0">

<dt_assoc>


<item key="company_name">Ting</item>

<item key="offer_name">$25 Credit ($50 bounty)</item>


<item key="code">https://ting.com/r/offer-5b7eca8da2f-4</item>

</dt_assoc>

</item>

</dt_array>

</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

15

set_status

Description

Action & objectaction = set_status

object = offers

UsageAllows you to change the status of an offer once you issue it to a customer.

Request parameters for set_status

Standard parametersaction = set_status

object = offers

attributes


Parameter name


codes Required The list of codes whose status you want to change.

status Required The status that you want to apply to the specified codes. Allowed values are:

available—Code is available and can be issued to a customer.

issued—Code has been provided to a customer.

redeemed—Code has been used by a customer to set up an account.

Response parameters for set_status


object = offers


16



Examples for set_status



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">SET_STATUS</item>



<dt_assoc>


<item key="codes">

<dt_array>

<item key="0">

<dt_assoc>

<item key="code">HMSTEST-A04B-F5AF-391F</item>


</dt_assoc>

</item>

<item key="1">

<dt_assoc>

<item key="code">HMSTEST-2F01-C820-5C6A</item>


</dt_assoc>

</item>

17

</dt_array>

</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Successfully set status on codes</item>



</dt_assoc>

</data_block>

</body>

</OPS_envelope>

18

view_codes

Description

Action & objectaction = view_codes

object = offers

UsageAllows you to view all of the Offer codes that you generated.

Request parameters for view_codes

Standard parametersaction = view_codes

object = offers

Response parameters for view_codes


object = offers




Attributes

Parameters within the attributes associative array are described below.

Parameter name

Obligation Definition / Value

codes Returned if success = true

The list of codes and their properties. For more information, see the Codes table.

19

CodesParameters within the codes associative array are described below.

Parameter name


code Always returned The unique code for the offer.

company_name Always returned The name of the company issuing the offer. Allowed values are: Fotolia, Host Merchant Services, MightyCall, or Ting.

creation_date Always returned The date that the code was generated, in the form, YYYY-MM-DDThh-mm-ssZ. The T indicates the start of the time component and the Z indicates that it is UTC.

offer_name Always returned Description of the offer.

status Always returned The current status of the offer. Allowed values are:

available—Code is available and can be issued to a customer.

issued—Code has been provided to a customer.

redeemed—Code has been used by a customer to set up an account.

Examples for view_codes



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">VIEW_CODES</item>


</dt_assoc>

</data_block>

</body>

20

</OPS_envelope>



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Successfully retrieved codes</item>




<dt_assoc>

<item key="codes">

<dt_array>

<item key="0">

<dt_assoc>




<item key="creation_date">2012-04-15T14-59-38Z</item>

<item key="code">HMSTEST-2F01-C820-5C6A</item>

</dt_assoc>

</item>

<item key="1">

<dt_assoc>



21



<item key="code">HMSTEST-6DDF-6B26-FE44</item>

</dt_assoc>

</item>

<item key="2">

<dt_assoc>





<item key="code">HMSTEST-1D4D-5685-0850</item>

</dt_assoc>

</item>

<item key="3">

<dt_assoc>





<item key="code">HMSTEST-A05E-10FE-B9A3</item>

</dt_assoc>

</item>

...

<item key="98">

<dt_assoc>





<item key="code">HMSTEST-9061-159F-B036</item>

</dt_assoc>

</item>

<item key="99">

22

<dt_assoc>


<item key="company_name">Ting</item>

<item key="offer_name">$25 Credit (25% rev share)</item>


<item key="code">http://ting.com/r/offer-5b7ec5d91ch-2</item>

</dt_assoc>

</item>

</dt_array>

</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

23

Revisions and updates

June 20, 2013

• Revised the Ting offers, which are now:• $25 credit to the customer and 10% gross margin to the Reseller.• $25 credit to the customer and $25 bounty per new account to the

Reseller.

December 13, 2012• Revised the Ting offers, which are now:

• $25 credit to the customer and 25% revenue share to the reseller.• $25 credit to the customer and $50 bounty to the reseller.

November 15, 2012• You can now generate coupon codes for Fotolia that are worth 10 free Fotolia

credits, and MightyCall codes that are worth 30 minutes of MightyCall ClickConnect service.

July 5, 2012• Added the following Ting offers:

• $25 credit to the customer and 30% revenue share to the Reseller.• $25 credit to the customer and $75 bounty to the Reseller.• $50 credit to the customer and $50 bounty to the Reseller.

May 8, 2012

• Removed Google AdWords and AdWords Express as these codes are no longer available.

• You can now generate a Ting coupon code worth $50 USD that your customers can use toward the purchase of a Ting mobile device. You receive a share of the net revenue that is generated by the fees that the customer pays during their first 24 months of service.

• Incremented version to 4.0.5.

March 29, 2012

• You can now generate Offer codes that your customers can use toward payment processing services with Host Merchant Services (HMS). Each coupon is worth $75 USD and you benefit by earning a percent of the net revenue that is generated by the customer's processing fees to HMS.

• Incremented version to 4.0.3.

February 7, 2012 Added code for AdWords Express valued at $100 USD.

24

November 1. 2011 In addition to Google AdWords, you can now generate Offer codes for Google

AdWords Express.

September 29, 2011 Added the following commands to support Google AdWords:

generate_codes—Generates a list of unique offer codes for Google AdWords credits.

set_status—Allows you to change the status of an offer once you issue it to a customer.

view_codes—Allows you to view all of the codes that you generated.

25

OpenSRS Offers API Command Reference · • $25 credit to the customer and $25 bounty per new...

Documents

Transcript of OpenSRS Offers API Command Reference · • $25 credit to the customer and $25 bounty per new...