UltraCart Affiliate Management Web Service Developers Guide

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 DAILY = 1 WEEKLY = 2 MONTHLY = 3 PER_ORDER = 4
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 ACTIVE = 1 PENDING = 2 DENIED = 3
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.
AffiliateTierRelationship[] relationships	The relationship to other affiliates if this affiliate was recruited

AffiliateTierRelationship

This object represents a relationship to another affiliate.

Field	Description
int tierNumber	The tier of the affiliate that referred this affiliate.
int affiliateOid	The OID of the affiliate that referred this affiliate.

AffiliateLedger

This object represents a transaction associated with an affiliate and an order.

Field	Description
int affiliateOid	The OID of the affiliate associated with this ledger record.
String assignedByUser	The name of the user that generated a manual ledger entry.
String itemId	The item ID that this ledger record is associated with
String orderId	The order ID that this ledger record is associated with
Calendar originalTransactionDts	The date of the original transaction if this ledger is a refund entry.
String subId	The sub ID used by the affiliate on their tracking link.
int tierNumber	The tier number of this commission.
BigDecimal transactionAmount	The amount of commission earned.
BigDecimal transactionAmountPaid	The amount of commission recorded as paid to the affiliate.
Calendar transactionDts	The date of the transaction.
String transactionMemo	The text memo of the transaction.
BigDecimal transactionPercentage	The percentage of the transaction
String transactionState	The state of the transaction state of the ledger record.

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.

getLedgersForAffiliateOrder

Method Signature AffiliateLedger[] getLedgersForAffiliateOrder(Credentials c, int affiliateOid, String orderId);
Description Fetches all the ledger records for an order associated with a given affiliate.
Parameters Credentials c – The credentials of the API user that is making the call. int affiliateOid – the affiliate identifier. String orderId - the order ID to return records for.
Result AffiliateLedger[] - an array of the ledger records associated with the order and affiliate.

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