Channel Partner API - SOAP Guide

Channel Partner API - SOAP Guide

The SOAP interface for the channel partner API is intended to allow interaction with the API by using the standard SOAP Web Service model available to most programming languages like Java, C#, PHP, etc. Make sure to read the parent page about configuring the custom channel partner before starting coding.

WSDL

The URL for the SOAP WSDL is:

https://secure.ultracart.com/axis/services/ChannelPartnerAPIV1?wsdl

Methods

The SOAP web service has the current methods available:

Method

Description

ImportResult importOrder(Credentials credentials, Order order);

Import an order

CancelResult cancelOrderByUltraCartOrderId(Credentials credentials, String orderId);Cancel an order based upon the UltraCart orderId returned by importOrder.
CancelResult cancelOrderByChannelPartnerOrderId(Credentials credentials, String channelPartnerOrderId);Cancel an order based upon the Channel Partner's orderId passed in to importOrder.

Objects

Credentials

Field

Description

Required

merchantId

UtlraCart Merchant ID

Y

channelPartnerCode

Code of the custom channel partner

Y

channelPartnerPassword

API password

Y

Order

Field

Description

Required

channelPartnerOrderId

A unique order ID from the external system.

Y

paymentMethod

The method of payment. Credit Card or Purchase Order

Y

noRealtimePaymentProcessing

Leaves the order in Accounts Receivable instead of processing the card in real-time.

 

skipPaymentProcessing

Skip over the payment processing and move the order on to shipping.

 

considerRecurringIf set to true, we will pass the recurring flag to gateways that support it (Authorize.Net and PayPal Web Payments Pro) 

autoApprovePurchaseOrder

Automatically approve the purchase order.

 

storeIfPaymentDeclines

Store the order in Accounts Receivable if the credit card declines

Recommend - Y

treatWarningsAsErrorsIf true, the wanrings are considered errors and will prevent the order from importing. Most common warning is the pre-order warning. 
storeCompletedStore the order in the Completed Orders stage.  This is used for importing historical orders. 

creditCardAuthorizationReferenceNumber

If you authorized the order outside of UltraCart, this is the transaction identifier that UltraCart will use to capture the order.

 

creditCardAuthorizationAmount

If you authorized the order outside of UltraCart, this is the amount of the authorization.

 

creditCardAuthorizationDts

If you authorized the order outside of UltraCart, this is the timestamp of the authorization.

 

creditCardType

Visa, MasterCard, AMEX, or Discover

Y - CC Orders

creditCardNumber

15 or 16 digit credit card number (spaces or dashes OK)

Y - CC Orders

creditCardToken

Token of the credit card (Stripe.com or other tokenizing gateway supported by UltraCart).

 

creditCardExpirationMonth

Month 1 through 12  (January = 1, December = 12)

Y - CC Orders

creditCardExpirationYear

Four Digit Year

Y - CC Orders

creditCardVerificationNumber

 

 

rotatingTransactionGatewayCodeThe rotating transaction gateway code to use for this order. 

purchaseOrderNumber

The purchase order number.

Y- Purchase Order

billToFirstName

 

Y

billToLastName

 

Y

billToTitle

 

 

billToCompany

 

 

billToAddress1

 

Y

billToAddress2

 

 

billToCity

 

Y

billToState

 

Y

billToPostalCode

 

Y

billToCountry

Use the full spelling that UltraCart uses or provide the ISO-3166 two letter country code.

Y

billToDayPhone

 

 

billToEveningPhone

 

 

email

 

 

ccEmail

 

 

associatedWithCustomerProfileIfPresent

If this is yes, the order will be associated with the customer profile that has the same email (if it exists) and they will receive their discounted pricing.

This will fail if the customer profile has a null or empty string password. Some merchants will create customer profiles with such passwords to prevent actual logins. However, the order creation process does simulate a customer login during the creation and this will fail silently with an invalid password. If you are creating orders and they are not being tied to an existing customer profile when this value is set to 'Y', the customer password may be the issue.

 

shipToFirstName

 

Y - physical goods

shipToLastName

 

Y - physical goods

shipToTitle

 

 

shipToCompany

 

 

shipToAddress1

 

Y - physical goods

shipToAddress2

 

 

shipToCity

 

Y - physical goods

shipToState

 

Y - physical goods

shipToPostalCode

 

Y - physical goods

shipToCountry

Use the full spelling that UltraCart uses or provide the ISO-3166 two letter country code.

Y - physical goods

shipToPhone

 

Y - physical goods

shipToEveningPhone

 

 

shippingMethod

If the order requires shipping then you either need to specify the name of the method in this field, or pass order.leastCostRoute = true and let UltraCart pick the method of shipment

Maybe

arbitraryTax

The tax charged by the external system

 

arbitraryTaxableSubtotal

The taxable subtotal the tax was based upon by the external system

 

arbitraryTaxRate

The tax rate used by the external system

 

arbitraryShippingHandlingTotal

The shipping/handling cost charged by the external system

 

taxExempt

 

 

giftMessage

 

 

deliveryDate

If specified, use the format MM/DD/YYYY

 

shipOnDate

 

 

ipAddress

The IP address of the remote customer (pass 127.0.0.1) if not available

Y

shipToResidential

Will default to a business if not specified

Recommended

mailingListOptIn

Will default to opted out if not specified

Recommended

specialInstructions

Special instructions from the customer about shipment

 

screenBrandingThemeCode

The screen branding theme code to associate the order with. 

Y

advertisingSource

 

 

customField1

Custom value such as the DNIS of the caller up to 50 characters.

 

customField2

Custom value up to 50 characters.

 

customField3

Custom value up to 50 characters.

 

customField4

Custom value up to 50 characters.

 

customField5

Custom value up to 50 characters.

 

customField6

Custom value up to 50 characters.

 

customField7

Custom value up to 50 characters.

 

taxCounty

Tax county name if the state the order is going to charges tax at the county level.

 

affiliateId

The affiliate ID to associate the order with.

 

gift

True/False if the order is a gift (defaults to false)

 

giftEmail

Email to send the gift receipt to.

 

leastCostRoute

Either this needs to be True or the name of a shipping method must be specified in *order.shippingMethod*

Maybe

leastCostRouteShippingMethods[]

Array of shipping methods to restrict the least cost routing calculation to.

 

coupons[]

Coupons to apply to the order.

 

items[]

Items they ordered

Y

OrderItem

Field

Description

Required

itemId

Item ID of the item

Y

quantity

Quantity to purchase

Y

arbitraryUnitCost

Specific price for the item.

 

autoOrderSchedule

Auto order schedule if the item is a customer selectable auto order.

 

upsell

Flag indicating the item was an upsell (default to false)

 

autoOrderLastRebillDateThe last time the order was rebilled.  This will determine when the next shipment occurs.  This is used for importing historical auto orders from another system. 

options[]

Options associated with the item

Y - if the item has options

OrderItemOption

Field

Description

Required

name

Name of the option

Y

value

Value of the option

Y

ImportResult

Field

Description

Required

successful

True/false flag indicating the success of the import

Y

errors[]

Array of one or more errors if the import failed

 

orderId

UltraCart order ID if the import was successful

 

CancelResult

Field

Description

Required

successful

True/false flag indicating the success of the cancellation

Y

errors[]

Array of one or more errors preventing the cancellation attempt

 

Retries

If you API call fails, you should code your system to gracefully retry in the future. Give yourself time to review the failure in your logs before hitting the order repeatedly against the system.