How do I create a pre-fill URL?

How do I create a pre-fill URL?

SUMMARY

eSellerate publishers whose Web Stores use standard layouts or custom layouts can use the prefill method to add multiple SKUs to the customer's shopping cart with a single click, prefill custom data or customer information, and more.  There are two ways to prefill a Web Store:  using a custom URL and using an HTML form POST.  This article provides information on how to create a custom pre-fill URL.

Note:  For a self-explanatory example of how to create a HTML pre-fill form rather than using a URL, please see zip Web Store Prefill Example.

Note:  For information on prefilling the shopping cart in your Embedded Web Store within your application, please consult the eSellerate SDK Reference - specifically, the sections on eWeb_NewPrefillData, eWeb_AddPrefillData and eWeb_PurchaseEx.

MORE INFORMATION

The key to creating pre-fill URLs is to know the correct name format of each of the variables you want to pre-fill.  But before you can learn to use the variables, it is important to understand the basic portion of a pre-fill URL.  The following is an example of the core of most pre-fill URLs, with a fictitious sample value included for the Web Store ID:

https://secure.esellerate.net/secure/prefill.aspx?s=STR1234567890

The first part of the URL, up to the ?, is the same for any pre-fill URL.  This posts data to eSellerate's secure pre-fill server at secure.esellerate.net/secure/prefill.aspx.  The data to be posted to your Web Store follows in the form of query parameters appended to the URL.

The remainder of this article talks about the various arguments that are added to that core of a pre-fill URL to control what will be in the shopping cart.  The article is divided into the following sections:

1) IDENTIFYING THE WEB STORE ESELLER
2) PASSING THE PREVIEW CERTIFICATE TO TRIGGER A PREVIEW MODE ORDER
3) THE "CMD" COMMAND
4) PASSING THE VARIABLES THAT WILL FILL THE CART
5) PASSING A COUPON ID
6) PREVALIDATING THE COUPON
7) CONTROLLING THE WEB STORE PAGE ON WHICH CUSTOMERS WILL LAND
8) THE LAYOUT TEST CERTIFICATE
9) PREFILLING CUSTOM DATA
10) OTHER VALUES YOU CAN PREFILL
11) CONCLUSION


IDENTIFYING THE WEB STORE ESELLER

In the example URL above, the ?s=STR1234567890 tells eSellerate's pre-fill server which Web Store eSeller to send the data to; this is a fictional example but your actual eSellerRefNum can be found on the list of eSellers in your account using the eSellers link under SKU Management.

PASSING THE PREVIEW CERTIFICATE TO TRIGGER A PREVIEW MODE ORDER

We could add &pc=aBcDeFGh7 following the eSeller ID, as a fictional example of the Web Store's preview certificate value.  When a Web Store's preview certificate value is passed (whether via a pre-fill URL or a regular "Buy" URL), it tells the Web Store to handle the order in preview mode.  No credit card will be charged, so it is critical that your live pre-fill URL must not include the preview certificate--it gives away your product for free, and it is intended only to allow you to test your Web Store, links, etc.

The actual preview certificate value for your Web Store is found on the Web Store eSeller Summary screen--just click eSellers, click the link for your Web Store, and then notice the Preview URL shown in the Web Store Links section.  The preview certificate is shown at the end of the Preview URL, complete with "&pc=".

Note that you can click Regenerate to create a new preview certificate for your Web Store.  If you do this, any previously existing preview URL will result in only live orders instead.  This is because the preview certificate being passed as part of your "Buy" or pre-fill URL must match the actual, current preview certificate for the Web Store--otherwise, the non-matching preview certificate is simply ignored and a live order will be processed instead.  The example above would look like this for a live URL (i.e., without the preview certificate):

https://secure.esellerate.net/secure/prefill.aspx?s=STR1234567890&cmd=BUY
 

THE "CMD" COMMAND

&cmd=BUY tells the Web Store what action to take (the "cmd" means "command").  "Buy" is by far the most commonly used command.  There are a couple of other possible values, but for this purpose we will use "&cmd=BUY".


PASSING THE VARIABLES THAT WILL FILL THE CART

After &cmd=BUY, we start telling the secure pre-fill server what data/values are going to be passed to the Web Store.  There are a great many variables of different kinds that you could pass here, ranging from SKU ID to the quantity of each SKU being prefilled, to customer billing address info, etc.  However, for the purpose of this article we will tell the secure server which SKUs will be pre-filled.  If we do not specify the quantity for any given SKU, it will default to 1.  For this example, we will also let the customer enter her own name and e-mail address, etc.

To tell the server which SKUs are going to be prefilled, you need to pass their SKU IDs using "_cartitemX.skurefnum=<skuID>", where "X" represents an index number that indicates WHICH item in the sequence of SKUs you are identifying (the first item is 0, the second is 1, the third is 2, and so on). <skuID> is used here as a reference to the SKU's actual ID (e.g., SKU01234567890).

You can find the SKU ID on the list of SKUs by clicking SKUs from the main page of your Sales Manager.  Or, find your desired SKU by searching on the SKU name after clicking that link - you might find it easier to copy and paste the SKU ID from the SKU's Basic tab.

To add three SKUs to the URL, we would add something like this:

&_cartitem0.skurefnum=SKU012345678901&_cartitem1.skurefnum=SKU10987654321&_cartitem2.skurefnum=SKU246810121416

Notice that each variable you pass is separated by an ampersand (&).  That does not apply only to SKU ID variables, either.  The very first variable we passed was the eSeller ID, using a ?, but all variable following the ? (e.g., "cmd=", "pc=", etc.) begins with & instead.


PASSING THE COUPON ID

If you want to pre-fill a coupon ID, that variable is called _shopper.CouponName=.  Remember to begin with & when you are starting the new variable, e.g., &_shopper.CouponName=CPN0123456789).  The coupon ID itself is found by looking at your list of coupons in Sales Manager, or looking at a specific coupon's details.  To view the list (and optionally drill into a coupon's details), click Coupons under the Advanced Sales Options section of your main Sales Manager page.


PREVALIDATING THE COUPON

When you pass a coupon ID, you may not want the customer to have to click Enter next to the Coupon field if it can be avoided - and with a pre-fill URL, it can be done.  You can pass &_eSellerate.Options=PREVALIDATECOUPON so that the coupon ID will already be posted (and its discount applied) before the Web Store page ever renders.  We recommend putting the prevalidate option after the coupon ID in your prefill URL.


CONTROLLING THE WEB STORE PAGE ON WHICH CUSTOMERS WILL LAND

A very popular feature of pre-fill URLs is the ability to control what page the customer lands on when clicking your link.  For example, if you prefill one or more SKUs, you may want the customer to land directly on your cart page.  In that case, you can use the &page= parameter.  This lets you specify the name of the HTML file that contains your cart page (you can find the file name on the Settings tab of your custom layout).  We recommend that you put the page name variable at the END of your pre-fill URL.  For example, if your cart page is named "MultiCart.htm", you would add the following to the end of the pre-fill URL:

&page=MultiCart.htm


THE LAYOUT TEST CERTIFICATE

Another parameter that should never be included in your finished/live URLs is the custom layout's test certificate.  In order to view a MODIFIED custom layout that hasn't even been published yet--in other words, to essentially duplicate the way the Test Layout button works--you would need to tell your Web Store to use the most recently-modified layout files (even if they have not been published).  This can be accomplished by adding your layout's test certificate using the following format:

&tc=LTC01234567-ABCD

The "tc" means "test certificate", and that test certificate value is found on the bottom of the Settings tab in your custom layout:  e.g., LTC01234567-ABCD.  But again, this should NOT be included in your live pre-fill URLs, because of course you want customers to see only the Web Store's PUBLISHED layout.  If you were to pass the test certificate variable, the orange and black "UNPUBLISHED LAYOUT" banner would appear at the bottom of the screen on your live orders.

NOTE:  Your Web Store must currently have a custom layout assigned in order for the tc= parameter to work.  The assigned layout does not have to be the same custom layout that you're testing; any custom layout currently assigned to the Web Store will meet this requirement and the layout test certificate will tell the store which custom layout to use.  However, if your Web Store uses one of the 12 standard layouts or an older legacy layout, then the tc= parameter will be ignored.


PREFILLING CUSTOM DATA

Another very popular function of prefilling the shopping cart is the ability to prefill custom data values, which will be stored as part of the order record for your internal reporting purposes. There are twenty custom data fields available that can hold any type of data you may need to track, and you can prefill them without requiring the customer to enter anything.

In fact, unless you intentionally add the custom data fields to your custom layout, customers will not see the values displayed in the Web Store page contents.

The custom data fields are named and numbered using a zero-based index, from _custom.data0 through _custom.data19.  To prefil a custom data value, then, you would append the following to your URL.  In this example, the value being passed to the custom data field is the word "TEST":

&_custom.data0=TEST

It is very important that you select one or more of the custom data variables and always use it (or them) for the same purpose(s) every time - you do not want to mix two different types of sets of data in the same data field, or else your reporting may be adversely affected.

Please note that custom data values are not reported in most sales reports.  They are accessible specifically via the following methods only.  Also note that custom data fields 10 through 19 are only available via the final two options in this list:

  • The Daily Summary File export (via the Sales Reports link in Sales Manager)
  • The Daily Summary File e-mail message (which can be configured via the Account Information page in Sales Manager)
  • The Order Detail screen (via the Orders link in Sales Manager; drill into an order and click the + next to Custom Data)
  • XML Order Notice posting (which can be configured via the Account Information page in Sales Manager)
  • The Order Lookup Web Service

Publishers who rely on order event notification by e-mail should especially note that custom data values are not included in any order notification e-mail messages.


OTHER VALUES YOU CAN PREFILL

For a complete list of prefillable values, please visit the following URL and then click the Can Prefill column heading when the page has loaded.  All of the variables with a checkmark in that column can be prefilled using a pre-fill URL or form.


https://publishers.esellerate.net/SalesMgr/CustomLayouts/Variables.aspx?Embedded=0&SortExpression=CAN_PREFILL.


CONCLUSION

Now that we have broken down each part of a typical pre-fill URL, let's look at the total URL one more time.  With a little more exposure, you will be able to look at the URL and understand the meaning and purpose of each part of it.  Once you have that understanding, you can make your own pre-fill URLs by mixing and matching whatever variables you want.  (Please note:  For display purposes, line breaks are artificially added to the URL in this article.)

https://secure.esellerate.net/secure/prefill.aspx?s=STR1234567890&pc=aBcDeFgH7&cmd=BUY
&_cartitem0.skurefnum=SKU012345678901&_cartitem1.skurefnum=SKU10987654321&_cartitem2.skurefnum=SKU2468101214
&_shopper.CouponName=CPN0123456789&Options=PREVALIDATECOUPON&tc=LTC123456789-ABCD&page=MultiCart.htm

Rating:Rating of 3.5 Stars13 Votes
Was this answer helpful?YesNo
Topic Information
  • Topic #: 5570-373
  • Date Created: 03/27/2009
  • Last Modified Since: 08/22/2011
  • Viewed: 7962
Welcome Guest
Help Desk and Customer Support Software by Parature