1 Channel Partner API - Spreadsheet Import

Channel Partner API - Spreadsheet Import

The spreadsheet import interface for the generic channel partner is intended to allow importing of complete orders from a spreadsheet. There are two methods of processing the spreadsheet:

Uploading it through the web interface, or
FTPing the file to UltraCart's Virtual FTP server

Irregardless of which way you send the file to UltraCart, the format of the file is the same. In this tutorial we will cover building the file first and then uploading it.

Configuring the Custom Channel Partner

The first thing that needs to happen before you can import orders is to configure the custom channel partner. Channel partners are how UltraCart keeps track of orders that originate from a source other than the UltraCart checkout process. To configure your channel partner go to:

Main Menu → Configuration →Custom Channel Partners

At the 1st screen click the new button.

There are four text fields and two check boxes to be completed. Also, two check boxes are to be considerd.

API Credentials

The following are brief descriptions of the fields.

Field	Description	Required
Code	A 1-10 character code identifying the channel partner. We recommend using the initials of the partner as this will be visible when viewing orders within UltraCart	Y
Name	The descriptive name of the channel partner.	Y
API/FTP Password	Create a strong password. This will be the same password used for the API (SOAP or HTTP) as well as the FTP interface.	Y
Email FTP File Processing Reports To	The email address to send processing reports. You can specify multiple emails separated by a comma.	Y

Building the Spreadsheet

UltraCart will support three different formats for the spreadsheet:

.csv (comma separated values) - Download Channel Partner Template CSV
.xls (Microsoft Excel 1997-2002 format)
.xlsx (Microsoft Excel 2007+ format) Download Channel Partner Template (xlsx)

The first row of the spreadsheet must contain headers. The headers need to come from the table below.

Acceptable values for boolean parameters:

true: true, TRUE, yes, YES, on, ON, y, Y, 1
false false, FALSE, no, NO, off, OFF, n, N, 0

Header Name	Format	Description	Required
order.channelPartnerOrderId	String	A unique order ID from the external system.	Y
order.paymentMethod	String	The method of payment. Credit Card or Purchase Order	Y
order.noRealtimePaymentProcessing	Boolean	Leaves the order in Accounts Receivable instead of processing the card in real-time.
order.skipPaymentProcessing	Boolean	Skip over the payment processing and move the order on to shipping.
order.considerRecurring	Boolean	If set to true, then we will pass the recurring flag to the gateways that support it (Authorize.Net and PayPal Web Payments Pro)
order.autoApprovePurchaseOrder	Boolean	Automatically approve the purchase order.
order.storeIfPaymentDeclines	Boolean	Store the order in Accounts Receivable if the credit card declines	Recommend - Y
order.treatWarningsAsErrors	Boolean	Treat warnings (like the pre-oder warning) as errors that prevent the order from importing	Defaults to Y
order.storeCompleted	Boolean	Store the order in the completed orders stage of the system. This is used for importing historical orders from other carts.
order.creditCardAuthorizationReferenceNumber	String	If you authorized the order outside of UltraCart, this is the transaction identifier that UltraCart will use to capture the order.
order.creditCardAuthorizationAmount	Number	If you authorized the order outside of UltraCart, this is the amount of the authorization.
order.creditCardAuthorizationDts	Timestamp	If you authorized the order outside of UltraCart, this is the timestamp of the authorization. Required format: MM/DD/YYYY HH:MM:SS Example 07/01/2014 14:23:32 Required format: MM/DD/YYYY HH:MM:SS Example: 07/01/2014 14:23:32
order.creditCardType	String	Visa, MasterCard, AMEX, or Discover	Y - CC Orders
order.creditCardNumber	String	15 or 16 digit credit card number (spaces or dashes OK)	Y - CC Orders
order.creditCardToken	String	Token of the credit card (Stripe.com or other tokenizing gateway supported by UltraCart).
order.creditCardExpirationMonth	Number	Month 1 through 12 (January = 1, December = 12)	Y - CC Orders
order.creditCardExpirationYear	Number	Four Digit Year	Y - CC Orders
order.creditCardExpirationMonthYear	String	The format MM/YY or MM/YYYY
order.creditCardVerificationNumber	Number
order.rotatingTransactionGatewayCode	String	The rotating transaction gateway code to use for this order.
order.purchaseOrderNumber	String	The purchase order number.	Y- Purchase Order
order.billToFirstName	String		Y
order.billToLastName	String		Y
order.billToTitle	String
order.billToCompany	String
order.billToAddress1	String		Y
order.billToAddress2	String
order.billToCity	String		Y
order.billToState	String		Y
order.billToPostalCode	String		Y
order.billToCountry	String	Use the full spelling that UltraCart uses or provide the ISO-3166 two letter country code.	Y
order.billToDayPhone	String
order.billToEveningPhone	String
order.email	String
order.ccEmail	String
order.associatedWithCustomerProfileIfPresent	String	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.
order.shipToFirstName	String		Y - physical goods
order.shipToLastName	String		Y - physical goods
order.shipToTitle	String
order.shipToCompany	String
order.shipToAddress1	String		Y - physical goods
order.shipToAddress2	String
order.shipToCity	String		Y - physical goods
order.shipToState	String		Y - physical goods
order.shipToPostalCode	String		Y - physical goods
order.shipToCountry	String	Use the full spelling that UltraCart uses or provide the ISO-3166 two letter country code.	Y - physical goods
order.shipToPhone	String		Y - physical goods
order.shipToEveningPhone	String
order.shippingMethod	String	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
order.arbitraryTax	Number	The tax charged by the external system
order.arbitraryTaxableSubtotal	Number	The taxable subtotal the tax was based upon by the external system
order.arbitraryTaxRate	Number	The tax rate used by the external system
order.arbitraryShippingHandlingTotal	Number	The shipping/handling cost charged by the external system
order.taxExempt	Boolean
order.giftMessage	String
order.deliveryDate	Date	If specified, use the format MM/DD/YYYY
order.shipOnDate	Date
order.ipAddress	String	The IP address of the remote customer (pass 127.0.0.1) if not available	Y
order.shipToResidential	Boolean	Will default to a business if not specified	Recommended
order.mailingListOptIn	Boolean	Will default to opted out if not specified	Recommended
order.specialInstructions