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>