Skip to end of metadata
Go to start of metadata

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