Shipping API Specification

The CGI for the Custom Shipping Add-On is called with the POST method. Its input is an '&' delimited series of name-value pairs (name=value) and the whole thing is URL-encoded.

The CGI application returns information to ShopSite by simply writing its data to standard out.

ShopSite Input to Shipping Program

ShopSite sends information to the shipping program is in the form of '&' delimited name-value pairs (see the example).

The following characters are used to indicate value types in these fields:

a - character

n - digit

b - character or digit

f - floating point

Services Information

Some features, such as Free Shipping Coupons require a list of methods before a customer ZIP code is provided. This field is passed to request such a list:

api_services_only=yes

Request the API to return a list of all services.

Order Values

These fields contain information that applies to the entire order, including store information and customer information.

locale=aa-AA

The merchant locale, such as en-US or en-CA.

storeid=aaaaa…

A character string indicating the store’s ID.

cust_zip=bbbbb…

The zip/postal code as entered by the customer.

cust_country=aa

The customer’s country as entered by the customer.

merch_zip=bbbbb…

The Zip/postal code that the merchant is shipping from, as configured in ShopSite.

merch_country=aa

The country that the merchant is shipping from, as configured in ShopSite.

parm1=bbbb…
parm2=bbbb…
parm3=bbbb…
parm4=bbbb…
parm5=bbbb…
parm6=bbbb…
parm7=bbbb…
parm8=bbbb…

Additional Parameters that the merchant may have entered when configuring the Custom Shipping Add-On.

item_total=nnnn

The total number of line items in the order. Each line item in the order increases this value by 1, regardless of how many units are ordered in a given line.

currency_code=AAA

Three-character currency code indicating the store’s primary currency, such as USD or GBP.

weight_unit=AAA

An indicator of the unit of weight used in the store, either LBS or KGS.

Line Item Values

These fields will be repeated for each line item in the order. X is the line item number, from 1 to the item_total.

pXname=bbbbb…

The product name.

pXsku=bbbbb…

The product SKU.

pXorigsku=bbbbb…

The product's original SKU. When using Advanced Options for Ordering Options, the product SKU can change based on what the customer selects. This field gives merchants the original, unmodified SKU of the product.

pXoption_total=nn

Number of Ordering Option menus for this product. 0 if this product has no Ordering Options.

pXoptionN=bbbbb…

The value of the selected Ordering Options for this product. This field is repeated for each menus choice, where N is the option number from 1 to pXoption_total. This field is not present if pXoption_total is 0.

pXuprice=ffff.ff

Per unit price of this product. If the product is on sale, this price is the sale price.

pXprice=ffff.ff

Total price of all products on this line. If the product is on sale, this price reflects the sale price, but does not include any coupons or discounts.

pXship=A

Set to N if no shipping charge for this product, Y if shipping charges apply.

pXquantity=nnnnn

The number of units ordered for this product.

pXweight=fffff

The shipping weight of one product.

pXdimension=nnxnnxnn

The shipping box dimensions of one product in the form LxWxH.

pXtype=A

The Product Type of this product, either T for tangible products or D for digital download products.

pXapi_fieldF=bbbbb…

Information from up to 25 extra Product Fields may be included, depending on the Extra Product Field settings and the Shipping Add on configuration.

pXcustomer_text=bbbb…

Contents of the Customer Text field. This will often be special instructions or words for a card.

Shipping Program Data Returned to ShopSite

The shipping program should simply write its output to standard out. The data is made of name-value pairs, URL-encoded, with each pair separated by a newline (line feed) character (See the example).

Order Values

These fields contain information that applies to the entire order.

status=aaaa

A four-character string indicating the status of the request, either pass, warn, or fail.

error=bbbbb…

A text string containing an error message to be displayed to the customer. If status=fail then this field will exist and describe the problem and no other fields will be expected. This message will be displayed to the customer at the top of the shopping cart screen, and the shipping total field will be displayed as ----- (See the example).

If status=warn then this message will be displayed but processing of return data will continue as with status=pass.

option_count=nn

Total number of shipping options

Option Values

These fields must be repeated for each shipping option. X is the shipping option number, 1 to option_count.

sXoption=aaaaa…

The name of the shipping option, such as "Second Day Air."

sXprice=fffffff

The price of this shipping option.

ShopSite Input to Shipping Program ShopSite sends information to the shipping program is in the form of '&' delimited name-value pairs (see the example). The following characters are used to indicate value types in these fields: a - character n - digit b - character or digit f - floating point
Services Information Some features, such as Free Shipping Coupons require a list of methods before a customer ZIP code is provided. This field is passed to request such a list:
api_services_only=yes	Request the API to return a list of all services.
Order Values These fields contain information that applies to the entire order, including store information and customer information.
locale=aa-AA	The merchant locale, such as en-US or en-CA.
storeid=aaaaa…	A character string indicating the store’s ID.
cust_zip=bbbbb…	The zip/postal code as entered by the customer.
cust_country=aa	The customer’s country as entered by the customer.
merch_zip=bbbbb…	The Zip/postal code that the merchant is shipping from, as configured in ShopSite.
merch_country=aa	The country that the merchant is shipping from, as configured in ShopSite.
parm1=bbbb… parm2=bbbb… parm3=bbbb… parm4=bbbb… parm5=bbbb… parm6=bbbb… parm7=bbbb… parm8=bbbb…	Additional Parameters that the merchant may have entered when configuring the Custom Shipping Add-On.
item_total=nnnn	The total number of line items in the order. Each line item in the order increases this value by 1, regardless of how many units are ordered in a given line.
currency_code=AAA	Three-character currency code indicating the store’s primary currency, such as USD or GBP.
weight_unit=AAA	An indicator of the unit of weight used in the store, either LBS or KGS.
Line Item Values These fields will be repeated for each line item in the order. X is the line item number, from 1 to the item_total.
pXname=bbbbb…	The product name.
pXsku=bbbbb…	The product SKU.
pXorigsku=bbbbb…	The product's original SKU. When using Advanced Options for Ordering Options, the product SKU can change based on what the customer selects. This field gives merchants the original, unmodified SKU of the product.
pXoption_total=nn	Number of Ordering Option menus for this product. 0 if this product has no Ordering Options.
pXoptionN=bbbbb…	The value of the selected Ordering Options for this product. This field is repeated for each menus choice, where N is the option number from 1 to pXoption_total. This field is not present if pXoption_total is 0.
pXuprice=ffff.ff	Per unit price of this product. If the product is on sale, this price is the sale price.
pXprice=ffff.ff	Total price of all products on this line. If the product is on sale, this price reflects the sale price, but does not include any coupons or discounts.
pXship=A	Set to N if no shipping charge for this product, Y if shipping charges apply.
pXquantity=nnnnn	The number of units ordered for this product.
pXweight=fffff	The shipping weight of one product.
pXdimension=nnxnnxnn	The shipping box dimensions of one product in the form LxWxH.
pXtype=A	The Product Type of this product, either T for tangible products or D for digital download products.
pXapi_fieldF=bbbbb…	Information from up to 25 extra Product Fields may be included, depending on the Extra Product Field settings and the Shipping Add on configuration.
pXcustomer_text=bbbb…	Contents of the Customer Text field. This will often be special instructions or words for a card.
Shipping Program Data Returned to ShopSite The shipping program should simply write its output to standard out. The data is made of name-value pairs, URL-encoded, with each pair separated by a newline (line feed) character (See the example). Order Values These fields contain information that applies to the entire order.
status=aaaa	A four-character string indicating the status of the request, either pass, warn, or fail.
error=bbbbb…	A text string containing an error message to be displayed to the customer. If status=fail then this field will exist and describe the problem and no other fields will be expected. This message will be displayed to the customer at the top of the shopping cart screen, and the shipping total field will be displayed as ----- (See the example). If status=warn then this message will be displayed but processing of return data will continue as with status=pass.
option_count=nn	Total number of shipping options
Option Values These fields must be repeated for each shipping option. X is the shipping option number, 1 to option_count.
sXoption=aaaaa…	The name of the shipping option, such as "Second Day Air."
sXprice=fffffff	The price of this shipping option.