Screen: ShopSite > Merchandising > Order API

Order API Specification

Note:
Windows programmers should be aware of the Special considerations for Windows Servers.

Interface

From the point of view of the CGI, it's running like any other CGI called with the POST method. It's input is an '&' delimited series of name value pairs (name=value) and the whole thing is URL-encoded.

The CGI should find the pairs, determine the name and value for each, and decode the name and value. The CGI can then do whatever CGIs do. Anything written to standard output will go to the server, etc.

The input is currently in five parts.

Input to thankyou.cgi

The first set of input values contains the original input to thankyou.cgi:
prevlocation The location (and QUERY method string) where the order entered the shopping cart system of CGIs.
sbid Shopping basket id. A unique identifier for the shopping cart making the CGI calls.
storeid The unique identifier of the store. This value is also contained in the store’s store.auth file.
snoreid An encrypted value for the store ID. (Yes, that’s "snoreid" and not "storeid.") Note: This parameter may not be available when the order is placed through a 'hosted' payment gateway such as PayPal Payments Standard, Authorize.Net SIM, etc.
rnd1 A random number used for security
rnd2 A random number used for security
tax Indicates if tax was calculated for the purchase.
Submit this Order.x The horizontal cursor location when the Submit button was clicked.
Submit this Order.y The vertical cursor location when the Submit button was clicked.
pay1 The encrypted Payment 1 field. This is the credit card number for credit card payments.
cvv2 The encrypted CVV2 value.

The next set of items are those entered by the customer in the shopping cart and shipping forms.
Name
ShipName
paytype Number code for the payment type used. The number codes correlate to the following payment types:
  1. 0 - Visa
  2. 1 - MasterCard
  3. 2 - Discover
  4. 3 - American Express
  5. 4 - Purchase Order
  6. 5 - Cash On Delivery
  7. 6 - Check
  8. 7 - PayPal (standard)
  9. 8 - Generic Payment Option 1
  10. 9 - Generic Payment Option 2
  11. 10 - Diner's Club
  12. 11 - Fire Pay
  13. 12 - eCheck
  14. 13 - WorldPay
  15. 14 - PayPal Express
  16. 15 - Google Checkout (No longer valid)
  17. 16 - NetBanx
  18. 17 - Solo
  19. 18 - Switch
  20. 19 - Delta
  21. 20 - Visa Electron/UK
  22. 21 - JCB
  23. 22 - Maestro
  24. 23 - Authorize.net SIM
  25. 24 - Amazon Payments
  26. 25 - PayPal Advanced
  27. 26 - xDSpot
  28. 27 - PayPal Link
  29. 28 - eWay
  30. 29 - UnionPay
  31. 99 - No payment required
Comments The text supplied by the customer in the Comments box.
Title
First
Middle
Last
Suffix
Company
Email
Address
Address2
City
State
Zip
Country
Phone

Shipping information.
ShipTitle
ShipFirst
ShipMiddle
ShipLast
ShipSuffix
ShipCompany
ShipAddress
ShipAddress2
ShipCity
ShipState
ShipZip
ShipCountry
ShipPhone

The next few items reflect the payment method.
pay1
pay2
pay3
pay4
pay4_1
pay4_2		 These differ according to the PayType. For most credit cards:
pay1 is the card number
pay2 is the name on card
pay3 is the company name on the card
pay4 is replaced by pay4_1 containing the expiration month and pay4_2 containing the expiration year.

For PayType C.O.D. all of these will be '--'.
cvv2 the card CVV2 number
fieldnn The values for any custom checkout fields filled in by the customer. "nn" will be the field number, such as field02.
input_image_number The security image number the customer was required to input.
F- Values

The next block of name value pairs come from an internal thankyou.cgi table. All are prefaced by 'F-'.

Items from the Checkout form:
F-Name
F-Company
F-Email
F-Address
F-Address2
F-City
F-State
F-Zip
F-Country
F-Phone

The following "Ship" fields are only present if the order includes a separate shipping address.
F-ShipName
F-ShipCompany
F-ShipAddress
F-ShipAddress2
F-ShipCity
F-ShipState
F-ShipZip
F-ShipCountry
F-ShipPhone

The PayType values again:
F-paytype see paytype values above.
F-pay1
F-pay2
F-pay3
F-pay4 credit card expiration date in the form mm/yyyy.

Miscellaneous information:
F-ShipOn "checked" if the shipping address and billing address were entered separately. If this field is empty, the customer selected to use the same address for billing and shipping.
F-OrderInst The text of any customer-supplied ordering instructions.
F-Comments The text of any customer-supplied comments.
F-ProductTotal The total price of all products in the order, before any discounts, surcharges, tax, and shipping.
F-TaxTotal The total amount of tax for the order.
F-ShippingTotal The total shipping charge for the order.
F-GrandTotal The amount charged to the customer for the order, including all products, surcharges, discounts, tax, and shipping.
F-OrderInfo This field is only included if realtime credit card processing was used to pay for the order. It contains the response from the payment gateway.
F-Shipping The name of the shipping method selected by the customer.
F-cvv2 The CVV2 number from the credit card.
F-EmailList Set to on if the customer checked the e-mail box, or no if the box was not checked.
F-IP_Addr The IP address from which the customer placed the order.
F-Total_Weight The total shipping weight for the order.
F-Custom Fields The names and values of any custom fields, separated by a pipe symbol ( | ).
F-Title
F-First
F-Middle
F-Last
F-Suffix
F-ShipFirst
F-ShipLast
F-tax_percent Tax percentage for zip-code based tax calculation.
F-tax_string Zip code location name for zip-code based tax calculation
F-doba_shipping Shipping rate for Doba products
F-doba_order_info Doba product ID and merchant cost.
O- Values (Order Information)

The next block of name value pairs come from the record for this order in the orders database. Each name is prefixed by 'O-' and the name is the field name in the data base.
O-Date Date of the order
O-OrderNum Order number

Items from the various forms:
O-Name
O-Company
O-Email
O-Address
O-Address2
O-City
O-State
O-Zip
O-Country
O-Phone

Items for the shipping information. If the shipping information is the same as the billing information, these fields will have no value.
O-ShipName
O-ShipCompany
O-ShipAddress
O-ShipAddress2
O-ShipCity
O-ShipState
O-ShipZip
O-ShipCountry
O-ShipPhone

PayType values:
O-paytype
O-PayType		 see paytype values above
O-pay1
O-pay2
O-pay3
O-pay4

More form values:
O-ShipOn
O-OrderInst
O-Comments
O-ProductTotal
O-TaxTotal
O-ShippingTotal
O-GrandTotal

Last, some items not on the form.
O-NumItems Number of items in this order
O-OrderData Some miscellaneous binary coded data. Usually a couple of random bytes (BSDI, Linux) or nothing (Solaris).
O-Viewed Whether the order has been viewed from ShopSite by the merchant. 'n' or 'y'.
O-Shipping The shipping method selected by the customer.
O-Discount The amount of any discount applied to the order.
O-Surcharge The text of the surcharge selection chosen by the customer, including the method for modifying the price.
O-RefName Associate name, if the customer arrived at the store via an associate referral
O-AllTotals A text line containing various totals in the order, separated by a pipe ( | ) character.
O-Coupons
O-OrderInfo
O-cvv2
O-EmailList
O-IP/Hostname The IP address and hostname of the customer placing the order.
O-TotalWeight The total weight of all products in the order.
O-CustomFields
O-Title
O-First
O-Middle
O-Last
O-Suffix
O-ShipTitle
O-ShipFirst
O-ShipMiddle
O-ShipLast
O-ShipSuffix
O-TaxRate
O-TaxName
O-GiftCertificate If a gift certificate is redeemed, the certificate number, the remaining balance, and the used balance of the certificate.
O-ShopSiteTransactionID
O-Time
O-DobaShipping
O-DobaOrderInfo
B Values (Basket information)

Information for each of the products and coupons in the order from the basket db. Each name starts with 'B' and a two or more digit preface, which differs for each product/coupon. The products and coupons are numbered starting with '01'. So, for the first product (item) in the basket, the prefix will be 'B01-'.

The names and functions can be best understood by looking in the back office in the Products -> Add Product form.
Bnn-Download Key The download key for downloadable products. This field will not appear if Bnn-Product Type is not "Download"
Bnn-Name
Bnn-Price The price of the product. This value will be negative for coupons that have been applied, and 0 for coupons that were not applied.
Bnn-Quantity
Bnn-Sub-total
Bnn-Finite Options Customer-selected ordering options
Bnn-Freeform Options Text entered into the ordering options text box.
Bnn-OrigDB The database that the product information came from.
Bnn-OrigRNum The product record number in the database.
Bnn-ship1
Bnn-ship2
Bnn-ship3
Bnn-Options Box?
Bnn-Option Text
Bnn-Option Finite Text
Bnn-Taxable
Bnn-SKU
Bnn-Base Price
Bnn-ship4
Bnn-ship5
Bnn-ship6
Bnn-ship7
Bnn-ship8
Bnn-ship9
Bnn-ship10
Bnn-SuperNum The item number of the parent product if the product ordered is a subproduct (AKA Cross-Sell).
Bnn-Page Ordered From The URL of the page from which the product was ordered.
Bnn-recid
Bnn-NoShipping
Bnn-Product Type Tangible, Download, or coupon
Bnn-Product Type Data The file name of a digital download product.
Bnn-record_number
Bnn-rec_type Set to cpn for coupons
Bnn-coupon_ret_val 0 if the coupon was not applied; all other values indicate the coupon was applied. 1 indicates a normal coupon, 2 indicates a one-time coupon, 8 indicates a free-shipping coupon, 9 indicates a one-time free shipping coupon.
Bnn-Dimension The dimensions of the shipping box for this product, in the form LxWxH.
Bnn-Weight The shipping weight of the product.
Bnn-Handling_Charge The product-specific handling charge for this product.
Bnn-QBImport The QuickBooks account and sales categories for this product, which are only used when exporting order information in QuickBooks format.
Bnn-Field1
through
Bnn-Field25		 Information from extra Product Fields may be included, depending on the Extra Product Field settings.
Bnn-Quantity Pricing If Quantity Pricing is enabled for this product, this value contains all of the information from the Quantity Pricing table. The important values, such as price, quantity, and sub-total, can be found in other fields.
Bnn-OnSaleFlag checked if the product was on sale.
Bnn-ActualBasePrice The base product price (not the sale price)
Bnn-RewardIDQuantity The ID number of the reward group the product earns reward credit for.
Bnn-RewardIDReward The ID number of the reward group the product is a reward for.
Bnn-RewardStatus The product reward status. 1 indicates the product is eligible for a reward, Free indicates the product is a reward item.
Bnn-FedExPackageType The package type used for FedEx shipping calculations.
Bnn-Customer Text Header The customer Text Entry header text.
Bnn-Customer Text Rows The height setting of the customer text entry box.
Bnn-Customer Text Columns The width setting of the customer text entry box.
Bnn-Minimum Quantity The minimum order quantity for this product.
Bnn-Graphic The name of the Product Graphic.
Bnn-PQP Group The Product Quantity Pricing group to which the product belongs.
Bnn-USPSPackageType The Package Type used for USPS shipping calculations.
Bnn-UUID Unique product ID number.
Bnn-VAT The VAT category assigned to this product.
Bnn-DobaItemID The Doba ID for this product.
Bnn-TaxCode The Tax Code assigned to this product. This field is only used by AvaTax or a custom tax API. If a Tax Code is used, a Tax Rate will not be used, and vice versa.
Bnn-TaxRate The Tax Rate (or percentage) assigned to this product. This field is only applicable when using the ZIP Code to determine tax, a value added tax, or a shopper selected tax. If a Tax Rate is used, a Tax Code will not be used, and vice versa.
Bnn-SubscriptionProduct checked if this product is a subscription product.
Bnn-SubPaymentIntervalUnit weekly, monthly, yearly, quarterly, twice-yearly
Bnn-SubRegularPaymentAmount The amount that will be billed each payment interval.
Bnn-SubEndingPeriod The number of payment intervals to bill before stopping billing.
Bnn-SubBillOn For monthly payment intervals, this is the date on which the customer's account will be billed.
Bnn-SubTrialCheckBox checked if a trial subscription is offered.
Bnn-SubTrialPaymentAmount This is the amount that is charged each payment interval for a trial subscription.
Bnn-SubTrialPeriods This is the number of payment intervals that the trial subscription will last.
Bnn-SubOneTimeCheckBox checked if there is a one time fee associated with the trial subscription.
Bnn-SubOneTimePaymentAmount This is the one time fee amount.
S- Values (Store Settings)

The next block of pairs represents the settings file for the store. All names are prefaced by 'S-'. Many of these may be seen in the Hosting Service screen.
S-storeid The unique identifier of the store. This value is also contained in the store’s store.auth file.
S-datadir Data directory
S-bo_dir URL of ShopSite CGIs
S-smtp_host The name of the host that ShopSite uses for SMTP services.
S-keep_sb_days The number of days that ShopSite keeps shopping carts.
S-sb_secure_url Secure URL of shopping cart CGIs
S-sb_prompt_orderinst Prompt for ordering instructions
S-bo_use_security Use Security in ShopSite?
S-from_addr "From" address in e-mail receipts
S-bo_reg_url URL of ShopSite CGIs
S-mystore The storefront URL that the merchant sees by clicking the My Store button.
S-customcgi Location of custom CGI
S-separator The separator character used in large currency amounts.
S-decimal The decimal separator used in currency for this locale.
S-bo_secure_url The secure URL of back office CGI programs.
S-delim_infield
S-image_url The URL where standard ShopSite images are stored.
S-image_dir The pathname where standard ShopSite images are stored.
S-smartbuild (ignore)
S-image_url_secure The secure URL where standard ShopSite images are stored.
S-inventory_tracking Inventory tracking status
S-indexbuild (ignore)
S-MerchantLocale Full description of the merchant locale, as defined in the localeinfo.dat file.
S-sb_use_security Use security in shopping cart?
S-AdvancedUser (ignore)
S-sb_dir Shopping cart (basket) directory
S-pagesbuild (ignore)
S-altcurrency The alternate currency used in the store.
S-ccprocessor Credit card processor type
S-sb_prompt_comments Prompt for comments?
S-sb_reg_url URL of shopping cart CGIs
S-outputurl URL of store
S-delim_betfield (ignore)
S-sitemapbuild Whether or not to build a sitemap.
S-currencyratio primary/seconday currency conversion rate.
S-outputdir Output directory
S-BuyerLocale Full description of the merchant locale, as defined in the localeinfo.dat file.
S-currency The currency defined for the store, in the format of the currency.dat file.
S-sendmail_loc Location of sendmail executable.
PayType see paytype values above
orderapi1
orderapi2
orderapi3
orderapi4		 The values that the merchant entered into the Additional Parameter fields on the Order API screen.
CCemail The e-mail addresses and names entered by the merchant in the Order Notifications CC: field on the Hosting Services screen.
cgi The file name of the currently running CGI program.
number_cgis The total number of CGI programs that are to be run by the Order AIP interface.
current_cgi The number of the current CGI program out of the total number to run.
ShopSite Help and Resource Center
Last updated: March 01, 2010
Give Feedback

ShopSite Shopping Cart Software