Nexternal Customer Integration Documentation

CUSTOMER INTEGRATION

Customer Integration is used to pass customer information (name, physical address, e-mail address, etc.) from an independent source directly into the customer database used in the Online Store and Order Management System. Popular uses include:

A specialty foods merchant creates a form whereby new visitors can sign up to be added to that merchant's mailing list. Visitors who complete the form are added to the customer database (thereby being available to the Order Management System's Mail Wizard) and are rewarded with a $10.00 off coupon redeemable in the Online Store.

A winery creates a Wine Club signup form, allowing visitors to join the club for a monthly fee. Those who complete the form are added to the customer database with a Customer Type of "Wine Club", entitling them to preferential pricing and allocations.

A special interest club creates a "members-only" section of its web site requiring a login. Visitors who successfully log in are permitted to visit the members-only BtoB Store without an additional login.

METHODOLOGY

Customer Integration is achieved via an HTTP POST (the Request POST) from the client's web site to the default page of the client's Online Store via the secure https protocol. The exact URL depends on which Online Store (BtoC or BtoB) is targeted.

BtoC Store: https://www.nexternal.com/AccountName/default.aspx
BtoB Store: https://www.nexternal.com/busAccountName/default.aspx

Note: Nexternal strongly recommends that you use the secure (https) protocol as shown above. If you are using a Secure Domain Alias (Settings/Site Options in the Order Management System), Nexternal recommends using the Domain Alias in your URLs, i.e. https://DomainAlias/default.aspx (BtoC) and https://DomainAlias/bus/default.aspx (BtoB).

Customer Integration may be used to identify existing customers, to create new customers, or both. If integration is used to identify existing customers, one or more "Match" fields (starting with Match1) are required. These "Match" fields are then used to identify the customer, while any other fields specified are used to update the customer's information. If new customers are being created, all fields listed as Required for New Customers are required. If the integration fields provided are not sufficient to uniquely determine the existing customer, or to create a new customer, then the integration fails. (Any error in the data provided likewise causes the integration to fail.)

MODES

Customer Integration may be operated in any of seven possible modes:

Reply-Only: Following the Request POST, an HTTP POST (the Reply POST) is sent back to a URL specified in the Request POST (the ReplyURL). The Reply POST contains the all of the data included in the Request POST, as well as the status of the integration attempt and reason for failure, if applicable. The ReplyURL must be a file that can accept an HTTP POST, and thus may not be a .htm (or .html) file. In this mode, it is inconsequential whether the Request POST is directed to the BtoC Store or the BtoB Store. Reply-Only is appropriate if you wish to keep the customer on your site regardless of the success or failure of the integration, and have the ability to read in the values of the Reply POST and take corresponding action.

Redirect-Only: Similar to the Reply-Only mode, the customer is redirected to a URL specified in the Request POST (the ReplyURL). In this mode, no data is sent to the ReplyURL, and thus a .htm (or .html) file is permitted. It is inconsequential whether the Request POST is directed to the BtoC Store or the BtoB Store. Redirect-Only is appropriate if you wish to keep the customer on your site regardless of the success or failure of the integration, but lack the ability to read in the values of the Reply POST and take corresponding action.

Proceed-Only: This is the default mode. Following the Request POST, the customer proceeds to the Online Store (either BtoC or BtoB, as appropriate). If the integration attempt is successful, the customer enters the store already logged in and never sees the store's login screen. If the integration attempt is unsuccessful, the customer must log in as usual. There is never a Reply POST in this mode. Proceed-Only is appropriate if you wish to send the customer into the Online Store regardless of the success or failure of the integration.

Display-Only: Following a successful integration attempt (via the Request POST), the word "Success" is displayed on screen. Following an unsuccessful integration attempt, the Failure Reason is displayed on screen. Display-Only is appropriate for debugging purposes when developing your integration, if you lack the ability to read in the values of the Reply POST used in the Reply-Failure mode.

Reply-Failure: Following a successful integration attempt (via the Request POST), the customer proceeds to the Online Store as in the Proceed-Only mode, and no Reply POST is sent. Following an unsuccessful integration attempt, a Reply POST is sent as in the Reply-Only mode. Reply-Failure is appropriate if you wish to send the customer into the Online Store only if the integration is successful, and have the ability to read in the values of the Reply POST and take corresponding action for an unsuccessful integration. Reply-Failure is also useful for debugging purposes when developing your integration.

Redirect-Failure: Following a successful integration attempt (via the Request POST), the customer proceeds to the Online Store as in the Proceed-Only mode. Following an unsuccessful integration attempt, the customer is redirected to the ReplyURL as in the Redirect-Only mode. Redirect-Failure is appropriate if you wish to send the customer into the Online Store only if the integration is successful, but lack the ability to read in the values of the Reply POST and take corresponding action for an unsuccessful integration.

Display-Failure: Following a successful integration attempt (via the Request POST), the customer proceeds to the Online Store as in the Proceed-Only mode. Following an unsuccessful integration attempt, the Failure Reason is displayed on screen as in the Display-Only mode. Display-Failure is appropriate for debugging purposes when developing your integration, if you lack the ability to read in the values of the Reply POST used in the Reply-Failure mode. Using Display-Failure in a live integration is not recommended.

Note: If the customer lands on a page within the Online Store following an integration attempt, the body tag of that page includes the css class nextIntegrationSuccess or nextIntegrationFailure, as appropriate.

REQUEST POST FIELDS

Customer Fields

Field Name Description Notes Data Type (Max Length) Required for New Customers

LAST_NAME Customer's Last Name Text (50) Yes

FIRST_NAME Customer's First Name Text (30) Yes

EMAIL Customer's E-Mail Address Text (50) Yes

ADDRESS_LABEL Customer's Contact Address Label Text (25) No

COMPANY_NAME Customer's Company Name Text (100) Conditional¹

ADDRESS1 Customer's Street Address, Line 1 Text (100) Yes

ADDRESS2 Customer's Street Address, Line 2 Text (100) No

CITY Customer's City Text (50) Yes

STATE Customer's State/Province
Use recognized 2 letter state/province abbreviations (refer to http://www.nexternal.com/documentation/statescountries.htm for a complete list), or leave blank (if State/Province does not apply)
Integrity must be maintined between STATE and COUNTRY
Text (2) Conditional²

POSTAL_CODE Customer's Postal (Zip) Code Text (20) Yes

COUNTRY Customer's Country
Use recognized 2 letter country codes (refer to http://www.nexternal.com/documentation/statescountries.htm for a complete list)
Integrity must be maintained between STATE and COUNTRY
May not be a country denied access to the Online Store (Settings/Anti-Fraud and Security in the Order Management System)
Text (2) Yes

ADDRESS_TYPE Contact Address Type
Use 1 for Business and 0 for Residential
Defaults to 0 (Residential) for new customers (if not specified)
Boolean No

PHONE_NUM Customer's Phone Number Subject to a minimum number of digits if the Minimum Phone Digits feature is in use (Settings/Site Options in the Order Management System) Text (30) Yes

PHONE_EXT Customer's Phone Extension Text (30) No

PRIMARY_SHIP Primary Ship To Address
Use 1 for Yes and 0 for No
Defaults to 0 (No) for new customers (if not specified)
Boolean No

PRIMARY_BILL Primary Bill To Address
Use 1 for Yes and 0 for No
Defaults to 0 (No) for new customers (if not specified)
Boolean No

DISCOUNT Customer Discount
Express as a decimal number between 0 and 1
Defaults to 0 for new customers (if not specified)
Must be blank if the Allow Customer Discount option (Customers/Integration in the OMS) is off
Float No

ACTIVE Active Status
Use 1 for Yes and 0 for No
Defaults to 1 (Yes) for new customers (if not specified)
Must be blank if the Allow Active option (Customers/Integration in the OMS) is off
Boolean No

MAILING_LIST Mailing List Status
Use 1 for Yes and 0 for No
Defaults to 1 (Yes) for new customers (if not specified)
Boolean No

CUST_TYPE Customer Type
Must be a recognized Customer Type (Customers/Types in the OMS)
Defaults to the Default Type for new customers (if not specified)
Must be blank if the Allow Customer Type option (Customers/Integration in the OMS) is off
Text (20) No

PASSWORD Customer's Password Text (50) Conditional³

PASSWORD_REMINDER Customer's Password Reminder (Hint) Text (100) No

CUSTOM_FIELD1 Custom Field #1 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD2 Custom Field #2 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD3 Custom Field #3 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD4 Custom Field #4 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD5 Custom Field #5 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD6 Custom Field #6 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD7 Custom Field #7 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD8 Custom Field #8 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD9 Custom Field #9 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD10 Custom Field #10 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD11 Custom Field #11 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD12 Custom Field #12 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD13 Custom Field #13 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD14 Custom Field #14 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD15 Custom Field #15 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD16 Custom Field #16 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD17 Custom Field #17 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD18 Custom Field #18 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD19 Custom Field #19 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOM_FIELD20 Custom Field #20 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional⁴

CUSTOMER_NO Customer Number May be used for matching purposes only (will be ignored otherwise) Integer No

¹May be required, optional, or not in use, as set at Customers/Types in the Order Management System
²Required if COUNTRY has associated STATE values -- otherwise must be left blank; please refer to http://www.nexternal.com/documentation/statescountries.htm
³Required if the Require Password option is on (Customers/Password Preferences in the Order Management System); you may enable password auto-generation for Customer Integration at Customers/Password Preferences
⁴Required if that Custom Field is required (Customers/Custom Fields in the Order Management System)

Administrative Fields

Field Name Description Notes

Matchn nth field to be used for customer matching
n must be an integer starting with 1
Value must be the name of a Customer Field
If any Match field is included and the Require Password for Matching option (Customers/Integration in the OMS) is on, PASSWORD must be included as a match field

Mode Integration Mode
Allowed values are Reply-Only, Redirect-Only, Proceed-Only, Reply-Failure, Redirect-Failure, and Display-Failure
Defaults to Proceed-Only if not specified

ReplyURL URL to which the Reply POST is directed for Reply-Only and Reply-Failure modes; or to which the customer is redirected for Redirect-Only and Redirect-Failure modes
Must be a full URL beginning with http:// or https:// (preferred)
Required for Reply-Only, Redirect-Only, Reply-Failure, and Redirect-Failure modes; not relevant for Proceed-Only and Display-Failure modes

Example:

<form name="Customer" method="post" action="https://www.nexternal.com/fairway/default.aspx">
<input type="hidden" name="LAST_NAME" value="Woods">
<input type="hidden" name="FIRST_NAME" value="Tiger">
<input type="hidden" name="EMAIL" value="demo@demo.com">
<input type="hidden" name="ADDRESS_LABEL" value="Home">
<input type="hidden" name="ADDRESS1" value="956 18th St.">
<input type="hidden" name="CITY" value="La Jolla">
<input type="hidden" name="STATE" value="CA">
<input type="hidden" name="POSTAL_CODE" value="92037">
<input type="hidden" name="COUNTRY" value="US">
<input type="hidden" name="ADDRESS_TYPE" value="0">
<input type="hidden" name="PHONE_NUM" value="760-730-9015">
<input type="hidden" name="PHONE_EXT" value="882">
<input type="hidden" name="PRIMARY_SHIP" value="0">
<input type="hidden" name="PRIMARY_BILL" value="0">
<input type="hidden" name="PASSWORD" value="demo">
<input type="hidden" name="MAILING_LIST" value="1">
<input type="hidden" name="Match1" value="EMAIL">
<input type="hidden" name="Match2" value="PASSWORD">
<input type="hidden" name="Mode" value="Proceed-Only">
<input type="submit" value="Shop Online">
</form>

Warning Field names are case sensitive.

REPLY POST FIELDS (Reply-Only and Reply-Failure modes only)

Field Name Description Notes

(Same as Request POST) (Same as Request POST) Every field included in the Request POST is also included in the Reply POST, even if that field is not needed for Customer Integration

Status Integration Status Value is either Success or Failure

Action Action Taken
Successful Integration: Value is either Create (if a new customer was created) or Update (if a new customer was updated)
Failed Integration: Value is blank

FailureReason Reason for Failed Integration
Successful Integration: Value is blank
Failed Integration: Value is a textual description of the first error found

Field Name	Description	Notes	Data Type (Max Length)	Required for New Customers
LAST_NAME	Customer's Last Name		Text (50)	Yes
FIRST_NAME	Customer's First Name		Text (30)	Yes
EMAIL	Customer's E-Mail Address		Text (50)	Yes
ADDRESS_LABEL	Customer's Contact Address Label		Text (25)	No
COMPANY_NAME	Customer's Company Name		Text (100)	Conditional¹
ADDRESS1	Customer's Street Address, Line 1		Text (100)	Yes
ADDRESS2	Customer's Street Address, Line 2		Text (100)	No
CITY	Customer's City		Text (50)	Yes
STATE	Customer's State/Province	Use recognized 2 letter state/province abbreviations (refer to http://www.nexternal.com/documentation/statescountries.htm for a complete list), or leave blank (if State/Province does not apply) Integrity must be maintined between STATE and COUNTRY	Text (2)	Conditional²
POSTAL_CODE	Customer's Postal (Zip) Code		Text (20)	Yes
COUNTRY	Customer's Country	Use recognized 2 letter country codes (refer to http://www.nexternal.com/documentation/statescountries.htm for a complete list) Integrity must be maintained between STATE and COUNTRY May not be a country denied access to the Online Store (Settings/Anti-Fraud and Security in the Order Management System)	Text (2)	Yes
ADDRESS_TYPE	Contact Address Type	Use 1 for Business and 0 for Residential Defaults to 0 (Residential) for new customers (if not specified)	Boolean	No
PHONE_NUM	Customer's Phone Number	Subject to a minimum number of digits if the Minimum Phone Digits feature is in use (Settings/Site Options in the Order Management System)	Text (30)	Yes
PHONE_EXT	Customer's Phone Extension		Text (30)	No
PRIMARY_SHIP	Primary Ship To Address	Use 1 for Yes and 0 for No Defaults to 0 (No) for new customers (if not specified)	Boolean	No
PRIMARY_BILL	Primary Bill To Address	Use 1 for Yes and 0 for No Defaults to 0 (No) for new customers (if not specified)	Boolean	No
DISCOUNT	Customer Discount	Express as a decimal number between 0 and 1 Defaults to 0 for new customers (if not specified) Must be blank if the Allow Customer Discount option (Customers/Integration in the OMS) is off	Float	No
ACTIVE	Active Status	Use 1 for Yes and 0 for No Defaults to 1 (Yes) for new customers (if not specified) Must be blank if the Allow Active option (Customers/Integration in the OMS) is off	Boolean	No
MAILING_LIST	Mailing List Status	Use 1 for Yes and 0 for No Defaults to 1 (Yes) for new customers (if not specified)	Boolean	No
CUST_TYPE	Customer Type	Must be a recognized Customer Type (Customers/Types in the OMS) Defaults to the Default Type for new customers (if not specified) Must be blank if the Allow Customer Type option (Customers/Integration in the OMS) is off	Text (20)	No
PASSWORD	Customer's Password		Text (50)	Conditional³
PASSWORD_REMINDER	Customer's Password Reminder (Hint)		Text (100)	No
CUSTOM_FIELD1	Custom Field #1	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD2	Custom Field #2	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD3	Custom Field #3	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD4	Custom Field #4	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD5	Custom Field #5	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD6	Custom Field #6	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD7	Custom Field #7	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD8	Custom Field #8	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD9	Custom Field #9	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD10	Custom Field #10	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD11	Custom Field #11	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD12	Custom Field #12	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD13	Custom Field #13	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD14	Custom Field #14	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD15	Custom Field #15	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD16	Custom Field #16	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD17	Custom Field #17	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD18	Custom Field #18	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD19	Custom Field #19	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOM_FIELD20	Custom Field #20	For type Yes/No, use 1 for Yes and 0 for No	Conditional (50)	Conditional⁴
CUSTOMER_NO	Customer Number	May be used for matching purposes only (will be ignored otherwise)	Integer	No