...
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 |
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