eLink retailmax.elink.customers

Input Arguments

Arg#	Name	Type	Description
3		's'	Required. Constant 'retailmax.elink.customers'
8		'E'	Maximum rows to return. Customer databases in Point of Sale can easily contain millions of customer records. You should set this to the maximum number you are able to process in one call. If you do not provide a value for this, the system will apply a reasonable default value.
9		's'	Predicates to select data to return.
7		's'	Specify list of fields to return. Any current list is cleared before adding these fields
10		's'	Specify list of fields to return. These fields adjust any current list
18		's'	Specify list of fields to ideally return. These fields adjust any current list. This optional list of fields informs the server that you would like to receive this information, but would prefer the server not delay in order to fetch it. This frees the server to omit these fields if not currently available. The server will begin to calculate this information for future requests, a form of cache loading.

Advanced Predicate Notes

Using the predicate &9=f500,0,123 instructs the server to search for "123" in a wider range of fields in one go. Typcially this is fields like name, companyname, email etc

The predicate &9=f503,0,XX applies a number of special case searchs.

• &9=f503,0,a7 Returns records that have an email address and that email address is considered technically invalid.
• &9=f503,0,a8 Returns records that have an email address and that email address is considered technically correct. You might apply this predicate if you are selecting customer records for an email campagin.
• &9=f503,0,a6 Returns records that have an email address that is duplicated on 2 or more different customer records.

Output Fields

Arg#	Name	Description
f100	Cid	Internal customer id#.
f101	Name	The customers full name. This field is typically used on reports. If left blank the system will populate it based on other fields
f1130	LifetimeSpend	Total raw revenue received from this customer over their lifetime. This field must be specifically requested as it can impose significant processing requirements. The figure includes all revenue without prejudice, so can overstate the customer value if they purchase items such as gift cards, prepay cards or make account payments. See the examples below for how this might be used.

Notes

Examples - Simple Call

Request minimal details about customer #12345, with XML response

/gnap/M/buck?3=retailmax.elink.customers&9=f100,=,12345

<DATS>
    <Cid>12345</Cid>
    <Name>John Doe</Name>
</DATS>

Request minimal details about customer #12345, with JSON response

/gnap/J/buck?3=retailmax.elink.customers&9=f100,=,12345

{ "RootType":"ARAY",
    "DATS":[ 
        {"Cid":12345, "Name":"John Doe" }
    }
}

Request minimal details about customers with name containing 'doe', reply in JSON response

/gnap/J/buck?3=retailmax.elink.customers&9=f101,like.ignorecase,doe

{ "RootType":"ARAY",
    "DATS":[ 
        {"Cid":12345, "Name":"John Doe" },
        {"Cid":89431, "Name":"Sarah DOE" },
        {"Cid":89555, "Name":"Ximena doe" }
    }
}

Request lifetime spend about customers with name containing 'doe', reply in JSON response. Adding &10=1103 to the request url forces the POS to calculate and respond with the information.

/gnap/J/buck?3=retailmax.elink.customers&10=1103&9=f101,like.ignorecase,doe

{ "RootType":"ARAY",
    "DATS":[ 
        {"Cid":12345, "Name":"John Doe", "LifetimeSpend":583.60 },
        {"Cid":89431, "Name":"Sarah DOE", "LifetimeSpend":77.90 },
        {"Cid":89555, "Name":"Ximena doe", "LifetimeSpend":0 }
    }
}

As calculating lifetime spend might involve noticeable delay, if you are requesting it for display in places where it isn't absolutely critical, such as while searching for customers from a list, you can request the field using the format "&18=1103" rather than "&10=1103". This instructs the POS to provide the information if available, but not to stall this request in order to fetch it. The POS will start a background task to calculate it, so the identical future request may return this information.

/gnap/J/buck?3=retailmax.elink.customers&18=1103&9=f101,like.ignorecase,doe

{ "RootType":"ARAY",
    "DATS":[ 
        {"Cid":12345, "Name":"John Doe", "LifetimeSpend":583.60 },
        {"Cid":89431, "Name":"Sarah DOE" },             // Field missing indicates not yet available, still being calculated
        {"Cid":89431, "Name":"Sarah DOE", "LifetimeSpend":0 }
    }
}

Request using wildcard searching, search for all records with "cat" present

/gnap/J/buck?3=retailmax.elink.customers&9=f500,0,cat

{ "RootType":"ARAY",
    "DATS":[ 
        {"Cid":12345, "Name":"John Doe", "Email":"johndoe@acat.example.com" },
        {"Cid":11782, "Name":"Catherine" }
    }
}