Affiliate Upsells API V2

3rd Party Upsells API

Version 2
Integration Documentation

About

The Focu5 Commerce 3rd Party Upsells API allows affiliates to process customer upsells to a variety of approved 3rd party vendors via one central location. You will be assigned a unique ‘id’ and ‘key’ set to begin using this tool. The API accepts post data in XML format.

Location

The live API is located at the following URL:
https://api.infocu5.com/upsell/index.php

A test API can be found at the following URL:
https://api.infocu5.com/x_upsell/index.php
*Submissions to the test API will return normal validation responses and confirmation emails while not creating customer records.

CALL FUNCTIONS

Functions are defined in the parent XML wrapper (e.g. <upsellOrder>…</upsellOrder>).The API supports the following functions:

getCampaigns
getBundles
getUpsells
upsellOrder
campaignOrder

CALL FUNCTION: getCampaigns

Fetches a list of all current upsell campaigns.

Variables

The API takes the following variables posted in XML format:

Name

Required

Value

affiliateID

Y

12 character alphanumeric id string assigned to affiliates

affiliateKey

Y

32 character alphanumeric password string assigned to affiliates

Response Codes

The API will return the following response codes in XML format:

Code

Value

1

Success

80

Improperly formatted request (XML format required)

100

Invalid ID and Transaction Key combination

800

Invalid function

900

The interface encountered an error

Example XML format

The following is an example of a properly formatted XML data structure for the API post:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<getCampaigns>
<affiliateID>_ASSIGNED_AFFILIATE_ID_</affiliateID>
<affiliateKey>_ASSIGNED_AFFILIATE_KEY_</affiliateKey>
</getCampaigns>

The following is an example of an XML formatted return result for a successful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>1</responseCode>
<responseMessage>Success</responseMessage> <campaign>
<campaignName>Campaign Name</campaignName>
<campaignID>FC111</campaignID>
</campaign>
</upsellResponse>

The following is an example of an XML formatted return result for an unsuccessful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>100</responseCode>
<responseMessage>Invalid ID and Transaction Key combination</responseMessage>
</upsellResponse>

CALL FUNCTION: getBundles

Fetches a list of all current upsells bundles available.

Variables

The API takes the following variables posted in XML format:

Name

Required

Value

affiliateID

Y

12 character alphanumeric id string assigned to affiliates

affiliateKey

Y

32 character alphanumeric password string assigned to affiliates

Response Codes

The API will return the following response codes in XML format:

Code

Value

1

Success

80

Improperly formatted request (XML format required)

100

Invalid ID and Transaction Key combination

800

Invalid function

900

The interface encountered an error

Example XML format

The following is an example of a properly formatted XML data structure for the API post:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<getBundles>
<affiliateID>_ASSIGNED_AFFILIATE_ID_</affiliateID>
<affiliateKey>_ASSIGNED_AFFILIATE_KEY_</affiliateKey>
</getBundles>

The following is an example of an XML formatted return result for a successful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>1</responseCode>
<responseMessage>Success</responseMessage>
<upsellBundle>
<bundleName>Bundle Name</bundleName>
<bundleID>XXXXX</bundleID>
<bundleCampaigns>1313|FC Test Sale,da111|FC Internal
Sale</bundleCampaigns>
<bundleFormFields>customerNumber,orderNumber,bundleID,billingNameFirst,billingNameLast,billingAddress,billingCity,billingState,billingZip,bi llingCountry,emailAddress,shippingNameFirst,shippingNameLast,shippingAddr ess,shippingCity,shippingState,shippingZip,shippingCountry,ccType,ccNumbe r,ccExpiration,ccCvvCode</bundleFormFields>
<bundleFormDetails>customerNumber{label:Customer Number|type:string|length:64|minimum:1},orderNumber{label:Order Number|type:string|length:64|minimum:1},bundleID{label:Bundle ID|type:string|length:6|minimum:6},agentID{label:Agent ID|type:string|length:30|minimum:1},billingNameFirst{label:Billing Name First|type:string|length:75|minimum:1},billingNameLast{label:Billing Name Last|type:string|length:75|minimum:1},billingAddress{label:Billing Address|type:string|length:75|minimum:1},billingCity{label:Billing City|type:string|length:75|minimum:1},billingState{label:Billing State/Region|type:string|length:50|minimum:2},billingZip{label:Billing ZIP/Postal Code|type:string|length:15|minimum:5},billingCountry{label:Billing Country|type:string|length:2|minimum:2},emailAddress{label:Email Address|type:string|length:150|minimum:1},shippingNameFirst{label:Shippin g Name First|type:string|length:75|minimum:1},shippingNameLast{label:Shipping Name Last|type:string|length:75|minimum:1},shippingAddress{label:Shipping Address|type:string|length:75|minimum:1},shippingCity{label:Shipping City|type:string|length:75|minimum:1},shippingState{label:Shipping State/Region|type:string|length:50|minimum:2},shippingZip{label:Shipping ZIP/Postal Code|type:string|length:15|minimum:5},shippingCountry{label:Shipping Country|type:string|length:2|minimum:2},ccType{label:Credit Card Type|type:string|length:4|minimum:2},ccNumber{label:Credit Card Number|type:int|length:19|minimum:12},ccExpiration{label:Credit Card
Expiration|type:string|length:7|minimum:7},ccCvvCode{label:Credit Card CVV|type:int|length:5|minimum:3}</bundleFormDetails>
<upsell>
<upsellName>Upsell Vendor</upsellName>
<upsellID>XXXXXXXX</upsellID> <product>
<productName>Super Product 1</productName>
<productID>XXXX</productID> </product>
<product>
<productName>Super Product 2</productName>
<productID>XXXX</productID>
</product> </upsell>
</upsellBundle>
</upsellResponse>

* bundleCampaigns is a comma-delimited list of all campaigns associated with each bundle. Each campaign is pipe-delimited (|) containing campaignID & campaignName.

* bundleFormFields is a comma-delimited list of all required fields associated with each bundle.

* bundleFormDetails is a comma-delimited list of all required fields associated with each bundle. Each field contains details within brackets ({…}). Details are pipe-delimited (|).

The following is an example of an XML formatted return result for an unsuccessful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>100</responseCode>
<responseMessage>Invalid ID and Transaction Key combination</responseMessage>
</upsellResponse>

CALL FUNCTION: getUpsells

Fetches a list of all current upsells available for a specified campaign.

Variables

The API takes the following variables posted in XML format:

Name

Required

Value

affiliateID

Y

12 character alphanumeric id string assigned to affiliates

affiliateKey

Y

32 character alphanumeric password string assigned to affiliates

campaignID

Y

Campaign that the product(s) are being sold under

Response Codes

The API will return the following response codes in XML format:

Code

Value

1

Success

80

Improperly formatted request (XML format required)

90

Invalid Dialer ID

100

Invalid ID and Transaction Key combination

800

Invalid function

900

The interface encountered an error

Example XML format

The following is an example of a properly formatted XML data structure for the API post:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<getUpsells>
<affiliateID>_ASSIGNED_AFFILIATE_ID_</affiliateID>
<affiliateKey>_ASSIGNED_AFFILIATE_KEY_</affiliateKey>
<campaignID>da111</campaignID>
</getUpsells>

The following is an example of an XML formatted return result for a successful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>1</responseCode>
<responseMessage>Success</responseMessage>
<upsellBundle>
<bundleName>Big Bundle</bundleName>
<bundleID>XXXXX</bundleID>
<bundleFormFields>customerNumber,orderNumber,bundleID,billingNameFi
rst,billingNameLast,billingAddress,billingCity,billingState,billingZip,billingCountry,emailAddress,shippingNameFirst,shippingNameLast,shippingAddr ess,shippingCity,shippingState,shippingZip,shippingCountry,ccType,ccNumbe r,ccExpiration,ccCvvCode</bundleFormFields>
<bundleFormDetails>customerNumber{label:Customer Number|type:string|length:64|minimum:1},orderNumber{label:Order Number|type:string|length:64|minimum:1},bundleID{label:Bundle ID|type:string|length:6|minimum:6},agentID{label:Agent ID|type:string|length:30|minimum:1},billingNameFirst{label:Billing Name First|type:string|length:75|minimum:1},billingNameLast{label:Billing Name Last|type:string|length:75|minimum:1},billingAddress{label:Billing Address|type:string|length:75|minimum:1},billingCity{label:Billing City|type:string|length:75|minimum:1},billingState{label:Billing State/Region|type:string|length:50|minimum:2},billingZip{label:Billing ZIP/Postal Code|type:string|length:15|minimum:5},billingCountry{label:Billing Country|type:string|length:2|minimum:2},emailAddress{label:Email Address|type:string|length:150|minimum:1},shippingNameFirst{label:Shippin g Name First|type:string|length:75|minimum:1},shippingNameLast{label:Shipping Name Last|type:string|length:75|minimum:1},shippingAddress{label:Shipping Address|type:string|length:75|minimum:1},shippingCity{label:Shipping City|type:string|length:75|minimum:1},shippingState{label:Shipping State/Region|type:string|length:50|minimum:2},shippingZip{label:Shipping ZIP/Postal Code|type:string|length:15|minimum:5},shippingCountry{label:Shipping Country|type:string|length:2|minimum:2},ccType{label:Credit Card Type|type:string|length:4|minimum:2},ccNumber{label:Credit Card Number|type:int|length:19|minimum:12},ccExpiration{label:Credit Card Expiration|type:string|length:7|minimum:7},ccCvvCode{label:Credit Card CVV|type:int|length:5|minimum:3}</bundleFormDetails>
<upsell>
<upsellName>Upsell Vendor</upsellName>
<upsellID>XXXXXXXX</upsellID> <product>
<productName>Super Product 1</productName>
<productID>XXXX</productID> </product>
<product>
<productName>Super Product 2</productName> <productID>XXXX</productID>
</product> </upsell>
</upsellBundle>
</upsellResponse>

* bundleFormFields is a comma-delimited list of all required fields associated with each bundle.

* bundleFormDetails is a comma-delimited list of all required fields associated with each bundle. Each field contains details within brackets ({…}). Details are pipe-delimited (|).

The following is an example of an XML formatted return result for an unsuccessful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>100</responseCode>
<responseMessage>Invalid ID and Transaction Key combination</responseMessage>
</upsellResponse>

CALL FUNCTION: upsellOrder

Places an order for up to 10 products from an individual upsell vendor.

Variables

The API takes the following variables posted in XML format:

Name

Required

Value

affiliateID

Y

12 character alphanumeric id string assigned to affiliates

affiliateKey

Y

32 character alphanumeric password string assigned to affiliates

upsellID

Y

8 character alphanumeric id string assigned to 3rd part upsell vendors

customerNumber

Y

Unique id assigned to customer by user

orderNumber

N

Unique number assigned to transaction by user (can be alphanumeric)

agentID

N

Agent responsible for the sale (can be an alphanumeric code or a proper name)

campaignID

N

Campaign that the product(s) are being sold under

customerPassword

N

Optional customer password for certain 3rd party vendors

productID1

Y

Unique id of product defined by 3rd party vendor

productQuantity1

Y

Quantity of product being purchased

productDescription1

Y

Description of product being purchased

productUnitPrice1

Y

Price per unit of product being purchased

productTaxRate

N

Tax to be applied to total of purchase, if applicable

billingNameFirst

Y

First name of customer

billingNameLast

Y

Last name of customer

billingAddress

Y

Address of customer

billingAddress2

N

Additional address line of customer

billingCity

Y

City of customer

billingState

Y

2 character state abbreviation (example CA for California)

billingZip

Y

Zip code of customer (Minimum 5 digits req.)

billingCountry

Y

2 character country abbreviation (example US for United States) Phone number of customer (Numeric only, 10-14 characters req.)

billingPhone

Y

Phone number of customer (Numeric only, 10-14 characters req.)

emailAddress

Y

Email address of customer

shippingNameFirst

Y

First name of customer

shippingNameLast

Y

Last name of customer

shippingAddress

Y

Address of customer

shippingAddress2

N

Additional address line of customer

shippingCity

Y

City of customer

shippingState

Y

2 character state abbreviation (example CA for California)

shippingZip

Y

Zip code of customer (Minimum 5 digits req.)

shippingCountry

Y

2 character country abbreviation (example US for United States)

shippingPhone

Y

Phone number of customer (Numeric only, 10-14 characters req.)

shippingPrice

N

Send email confirmation to customer with username and password (value ‘y’ / ‘n’)

ccType

Y

Credit card type (VISA, MC, DC, AMEX)

ccNumber

Y

Credit card number

ccExpiration

Y

Credit card expiration date (01/2012)

ccCvvCode

Y

Credit card cvv security code

customField1-5

N

Custom fields 1-5 containing optional data intended for Focus Commerce, not 3rd party vendor

Response Codes

The API will return the following response codes in XML format:

Code

Value

1

Success

80

Improperly formatted request (XML format required)

90

Invalid Dialer ID

100

Invalid ID and Transaction Key combination

110

Required fields

120

No valid leads found in post

130

Invalid list id and/or dialer combination

140

Invalid phone

150

Invalid state/county/region

160

Invalid zip/postal code

170

Invalid country

180

Invalid shipping phone

190

Invalid shipping state

200

Invalid shipping zip

210

Invalid shipping country

220

Error creating customer record

230

All products must have a quantity and description

240

Both username and password must be defined if in use

250

Username contains invalid characters

260

Password contains invalid characters

500

3rd party api error (api specific details)

800

Invalid function

900

The interface encountered an error

Example XML format

The following is an example of a properly formatted XML data structure for the API post:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellOrder>
<affiliateID>_ASSIGNED_AFFILIATE_ID_</affiliateID>
<affiliateKey>_ASSIGNED_AFFILIATE_KEY_</affiliateKey>
<upsellID>_VENDOR_ID_</upsellID>
<customerNumber>111111111</customerNumber>
<orderNumber>4211</orderNumber>
<agentID>Alex</agentID>
<campaignID>Big Value Sale</campaignID>
<customerUsername>username</customerUsername>
<customerPassword>password</customerPassword>
<productID1>131344</productID1>
<productQuantity1>1</productQuantity1>
<productDescription1>Product Description</productDescription1>
<productUnitPrice1>19.74</productUnitPrice1>
<productTaxRate>6.5</productTaxRate>
<billingNameFirst>Test</billingNameFirst>
<billingNameLast>Customer</billingNameLast>
<billingAddress>123 Test St.</billingAddress>
<billingAddress2></billingAddress2>
<billingCity>Testville</billingCity>
<billingState>CA</billingState>
<billingZip>91105</billingZip>
<billingCountry>US</billingCountry>
<billingPhone>8885551212</billingPhone>
<emailAddress>tester@infocu5.com</emailAddress>
<shippingNameFirst>Test</shippingNameFirst>
<shippingNameLast>Customer</shippingNameLast>
<shippingAddress>123 Test St.</shippingAddress>
<shippingAddress2></shippingAddress2>
<shippingCity>Testville</shippingCity>
<shippingState>CA</shippingState>
<shippingZip>91107</shippingZip>
<shippingCountry>US</shippingCountry>
<shippingPhone>8885551212</shippingPhone>
<shippingPrice>4.95</shippingPrice>
<ccType>VISA</ccType>
<ccNumber>4444111122227777</ccNumber>
<ccExpiration>03/2016</ccExpiration>
<ccCvvCode>123</ccCvvCode>
<customField1></customField1>
<customField2></customField2>
<customField3></customField3>
<customField4></customField4>
<customField5></customField5>
</upsellOrder>

* Up to 10 products may be passed at a time for individual vendors. XML value set formatting is as follows:

<productID2>131344</productID2>
<productQuantity2>1</productQuantity2>
<productDescription2>Product Description</productDescription2>
<productUnitPrice2>19.74</productUnitPrice2>
…through…
<productID10>131344</productID10>
<productQuantity10>1</productQuantity10>
<productDescription10>Product Description</productDescription10>
<productUnitPrice10>19.74</productUnitPrice10>

* All products products must contain values for productID, productQuantity, and productDescription.

The following is an example of an XML formatted return result for a successful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>1</responseCode>
<responseMessage>Success</responseMessage>
<customerID>a9e42c4c981f79f7380e012aacffde33</customerID>
<transactionID>20120608110207</transactionID>
</upsellResponse>

The following is an example of an XML formatted return result for an unsuccessful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>120</responseCode>
<responseMessage>A valid email address is required</responseMessage>
</upsellResponse>

CALL FUNCTION: campaignOrder

Places an order for products in a bundle from an individual campaign.

Variables

The API takes the following variables posted in XML format:

Name

Required

Value

affiliateID

Y

12 character alphanumeric id string assigned to affiliates

affiliateKey

Y

32 character alphanumeric password string assigned to affiliates

customerNumber

Y

Unique id assigned to customer by user

customerNumber

Y

Unique id assigned to customer by user

orderNumber

Y

Unique number assigned to transaction by user (can be alphanumeric)

agentID

Y

Agent responsible for the sale (can be an alphanumeric code or a proper name)

campaignID

Y

Campaign that the product(s) are being sold under

bundleID

Y

Product bundle that the product(s) are being sold under

customerUsername

N

Optional customer username for certain 3rd party vendors

customerPassword

N

Optional customer password for certain 3rd party vendors

productTaxRate

N

Tax to be applied to total of purchase, if applicable

billingNameFirst

Y

First name of customer

billingNameLast

Y

Last name of customer

billingAddress

Y

Address of customer

billingAddress2

N

Additional address line of customer

billingCity

Y

City of customer

billingState

Y

2 character state abbreviation (example CA for California)

billingZip

Y

Zip code of customer (Minimum 5 digits req.)

billingCountry

Y

2 character country abbreviation (example US for United States) Phone number of customer (Numeric only, 10-14 characters req.)

billingPhone

Y

Phone number of customer (Numeric only, 10-14 characters req.)

emailAddress

Y

Email address of customer

shippingNameFirst

Y

First name of customer

shippingNameLast

Y

Last name of customer

shippingAddress

Y

Address of customer

shippingAddress2

N

Additional address line of customer

shippingCity

Y

City of customer

shippingState

Y

2 character state abbreviation (example CA for California)

shippingZip

Y

Zip code of customer (Minimum 5 digits req.)

shippingCountry

Y

2 character country abbreviation (example US for United States)

shippingPhone

Y

Phone number of customer (Numeric only, 10-14 characters req.)

shippingPrice

N

Send email confirmation to customer with username and password (value ‘y’ / ‘n’)

ccType

Y

Credit card type (VISA, MC, DC, AMEX)

ccNumber

Y

Credit card number

ccExpiration

Y

Credit card expiration date (01/2012)

ccCvvCode

Y

Credit card cvv security code

customField1-5

N

Custom fields 1-5 containing optional data intended for Focus Commerce, not 3rd party vendor

Response Codes

The API will return the following response codes in XML format:

Code

Value

1

Success

80

Improperly formatted request (XML format required)

100

Invalid ID and Transaction Key combination

110

Required fields

120

No valid leads found in post

130

Invalid list id and/or dialer combination

140

Invalid phone

150

Invalid state/county/region

160

Invalid zip/postal code

170

Invalid country

180

Invalid shipping phone

190

Invalid shipping state

200

Invalid shipping zip

200

Invalid shipping zip

210

Invalid shipping country

210

Invalid shipping country

220

Error creating customer record

220

Error creating customer record

240

Both username and password must be defined if in use

250

Username contains invalid characters

260

Password contains invalid characters

300

Invalid Campaign ID

310

Invalid Bundle ID

500

3rd party api error (api specific details)

800

Invalid function

900

The interface encountered an error

Example XML format

The following is an example of a properly formatted XML data structure for the API post:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<campaignOrder>
<affiliateID>_ASSIGNED_AFFILIATE_ID_</affiliateID>
<affiliateKey>_ASSIGNED_AFFILIATE_KEY_</affiliateKey>
<customerNumber>111111111</customerNumber>
<orderNumber>4211</orderNumber>
<agentID>Alex</agentID>
<campaignID>XXXXX</campaignID>
<bundleID>XXXXX</bundleID>
<customerUsername>username</customerUsername>
<customerPassword>password</customerPassword>
<productTaxRate>6.5</productTaxRate>
<billingNameFirst>Test</billingNameFirst>
<billingNameLast>Customer</billingNameLast>
<billingAddress>123 Test St.</billingAddress>
<billingAddress2></billingAddress2>
<billingCity>Testville</billingCity>
<billingState>CA</billingState>
<billingZip>91105</billingZip>
<billingCountry>US</billingCountry>
<billingPhone>8885551212</billingPhone>
<emailAddress>tester@infocu5.com</emailAddress>
<shippingNameFirst>Test</shippingNameFirst>
<shippingNameLast>Customer</shippingNameLast>
<shippingAddress>123 Test St.</shippingAddress>
<shippingAddress2></shippingAddress2>
<shippingCity>Testville</shippingCity>
<shippingState>CA</shippingState>
<shippingZip>91107</shippingZip>
<shippingCountry>US</shippingCountry>
<shippingPhone>8885551212</shippingPhone>
<shippingPrice>4.95</shippingPrice>
<ccType>VISA</ccType>
<ccNumber>4444111122227777</ccNumber>
<ccExpiration>03/2016</ccExpiration>
<ccCvvCode>123</ccCvvCode>
<customField1></customField1>
<customField2></customField2>
<customField3></customField3>
<customField4></customField4>
<customField5></customField5>
</campaignOrder>

The following is an example of an XML formatted return result for a successful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>1</responseCode>
<responseMessage>Success</responseMessage>
<customerID>a9e42c4c981f79f7380e012aacffde33</customerID>
<transactionID>20120608110207</transactionID>
</upsellResponse>

The following is an example of an XML formatted return result for an unsuccessful transaction:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<upsellResponse>
<responseCode>120</responseCode>
<responseMessage>A valid email address is required</responseMessage>
</upsellResponse>