UltraCart Affiliate Management Web Service Developers Guide
Written by UltraCart Support
Copyright© 2011 BPS Info Solutions, Inc.
Last Updated 3/30/2011
Background
The affiliate management web service is a standard SOAP interface designed to allow merchants to build custom affiliate signup applications.
Prerequisite skills for using the API
In order to program against this API you need to be very familiar with SOAP programming within your desired developer language. This is not for people that have never coded web services before.
Support
Due to the complex nature of implanting custom checkouts, all support related to building or troubleshooting a custom application that utilizes this service is considered premium support which has an hourly cost associated with it. All questions related to using this API are beyond the scope of regular free email or phone support. You should factor this in when considering whether to build a custom application.
WSDL Location
The WSDL for this web service is located at:
https://secure.ultracart.com/axis/services/AffiliateServiceV1?wsdl
Object Model
There are lots of simple objects that comprise the API. Below we will list out the names of each object and describe what it is. Then on subsequent pages we will detail all the fields on the object.
Class |
Description |
Affiliate |
Objet that represents an affiliate. |
Credentials |
The user credentials that you are going to use to make the API call. |
Affilate
This object represents a single affiliate within the UltraCart account.
Field |
Description |
String address1 |
Mailing address line 1 |
String address2 |
Mailing address line 2 |
String affiliateGroup |
Name of the affiliate group they belong to. This must be a valid group name from the commissions tab under Affiliate Management |
integer affiliateOid |
Record identifier of the affiliate. |
boolean allowGoogleAdwordsTracking |
Whether or not the affiliate is allowed to use their Google Adwords tracking on your receipt page. If this is set to true you need to populate the googleConversionId for it to actually work. |
boolean allowYahooSearchMarketingTracking |
Whether or not the affiliate is allowed to use their Yahoo Search Marketing tracking on your receipt page. If this is set to true you need to populate the ysmAccountId for it to actually work. |
String autoApplyCoupon |
Coupon code to automatically to the customers account if they are referred by this affiliate. |
boolean autoApproveCommissions |
True if the commissions for sales by this affiliate should automatically be approved |
String checkPayableTo |
Name to make checks payable to. |
String city |
Mailling address city |
String companyName |
Name of the affiliate company for corporations |
String country |
Mailing address country |
Calendar dob |
Date of birth of the affiliate |
String email |
Email address of the affiliate |
integer emailPreference |
NONE = 0 |
String fax |
Fax number |
String firstName |
First name |
String googleConversionId |
The google adwords conversion id |
boolean htmlPermitted |
Set to true if you will allow the affiliate to utilize arbitrary conversion HTML on your receipt. This should only be allowed for the most trusted affiliates. |
String lastName |
Last name |
String marketingStrategy |
Description of their marketing strategy. |
String password |
Password |
BigDecimal paymentAdjustment |
(deprecated) |
String paypalEmail |
Email address to send their PayPal payments to |
boolean payViaPayPal |
True if the affiliate wants to receive payment via PayPal. You have to have PayPal Express checkout configured with MassPay to utilize this feature. |
String phone |
Phone number |
String postalCode |
Mailing address postal code (zip) |
String state |
Mailing address state |
integer status |
DISABLED = 0 |
String taxId |
The social security number of FEIN of the affiliate. |
boolean usingAdNetwork |
True if they are using an ad network |
boolean usingAdware |
True if they are using adware |
boolean usingBlog |
True if they are using their blog |
boolean usingOther |
True if they are using an other form of advertising |
boolean usingPerAcquistion |
True if they are using a pay per acquisition system |
boolean usingPpc |
True if they are using a pay per click advertising system |
boolean usingSeo |
True if they are utilizing a website with only SEO techniques. |
boolean usingWebsite |
True if they are using their website |
String websiteName |
The name of their website if applicable |
String websiteUrl |
The URL of their website if applicable. |
String ysmAccountId |
Yahoo Search Marketing account ID. |
Credentials
This object represents a the credentials used to make the API call.
Field |
Description |
String login |
The API user's login |
String merchantId |
The merchant ID of the account |
String password |
The password of the user |
API Methods
createAffiliate
Method Signature Affiliate createAffiliate(Credentials c, Affiliate affiliate);
Description
This method will create a new affiliate within the UltraCart account. If the affiliate already exists (email is how we identify affiliates) than an exception will be thrown.
Parameters Credentials c - The credentials of the API user that is making the call.Affiliate affiliate - The affiliate record to create within the UltraCart account
Result Affiliate - The returned affiliate object will contain a populated affiliateOid value. You may want to consider databasing this value within your internal system.
getAffiliate
Method Signature Affiliate getAffiliate(Credentials c, int affiliateOid);
Description
Fetches a specific affiliate using the affiliateOid returned from a call to createAffiliate.
Parameters Credentials c - The credentials of the API user that is making the call. int affiliateOid - the affiliate identifier returned from a call to createAffiliate
Result Affiliate - If the affiliate is found then their record will be returned. If there is no affiliate with the affiliate identifier then a null value will be returned.
getAffiliateByEmail
Method Signature Affiliate getAffiliateByEmail(Credentials c, String email);
Description
Fetches an affiliate record using their email address.
Parameters Credentials c - The credentials of the API user that is making the call. String email - emai address of the affiliate.
Result Affiliate - if the affiliate is found then their record will be returned. If there is no affiliate with a matching email address then a null value will be returned.
getAffiliates
Method Signature Affiliate[] getAffiliates(Credentials c);
Description
Fetches a copy of all the affiliates within the UltraCart account.
Parameters Credentials c - The credentials of the API user that is making the call.
Result Affiliate[] - an array of all the affiliates within the UltraCart account.
updateAffiliates
Method Signature void updateAffiliate(Credentials c, Affiliate affiliate);
Description
This method will update an affiliate record within the UltraCart system. If the affiliate does not exist an exception will be thrown.
Parameters Credentials c - The credentials of the API user that is making the call.Affiliate affiliate - the affiliate record to update.
Result None