Shipping API Specs
From CommerceV3 Docs
CV3 Documentation Resources
COMMERCEV3 SHIPPING API DOCUMENTATION
Copyright 2009 Color Maria, Inc.
1. TABLE OF CONTENTS
1. Table of Contents 2. Introduction 3. Specifications I. Capabilities II. Query To the Service III. Response From the Service 4. Example
2. INTRODUCTION
If your store requires shipping options that are not already built-in to our software, you can use the Shipping API in conjunction with third-party software to make adjustments to shipping on each order. To do so, answer "Yes" to the question "Would you like to use your own Shipping web service?" on the Shipping Options page and type the URL to your web service in the box.
3. SPECIFICATIONS
3.I CAPABILITIES
The shipping API allows you to make adjustments to the shipping method used for each ship-to and to the order's total shipping charge. Note that this feature is developmental and that more features can be added by request.
3.II QUERY TO THE SERVICE
When calculating the order's totals, CommerceV3 will make a query to your web service (HTTP GET or POST depending on admin services) with the following keys and values:
'askus': comma-delimited list (CDL) of all SKUs in order 'aprices': CDL of per-each prices 'aqtys': CDL of quantities 'aweights': CDL of shipping weights 'sgrps': CDL of number of SKUs per ship-to 'szips': CDL of ship-to zip codes 'sstates': CDL of ship-to states 'scountries': CDL of ship-to countries 'smeths': CDL of ship-to shipping methods 'sprices': CDL of ship-to shipping prices
Additional fields available for POST requests only:
'aphysical': CDL of 'y' for physical, 'n' for gift card 'astockstatus': CDL of stock statuses 'abackordered_date': CDL of backordered dates 'tpercentofforder': Number that represents the percent discount of an order 'tflatamountofforder': Number that represents a flat amount taken off the order 'tpercentoffshipping': Number that represents the percent discount for shipping 'tpromo_code': The promo code used on an order 'tprice_category': The name of the active price category for an order 'tprice_cat_id': The price category id for the order 'acust_1': a semicolon-delimited list of the 1st 25 characters of custom field 1 'acust_2': a semicolon-delimited list of the 1st 25 characters of custom field 2 'acust_3': a semicolon-delimited list of the 1st 25 characters of custom field 3 'acust_4': a semicolon-delimited list of the 1st 25 characters of custom field 4 'acust_5': a semicolon-delimited list of the 1st 25 characters of custom field 5 'acust_6': a semicolon-delimited list of the 1st 25 characters of custom field 6 'acust_7': a semicolon-delimited list of the 1st 25 characters of custom field 7 'acust_8': a semicolon-delimited list of the 1st 25 characters of custom field 8 'acust_9': a semicolon-delimited list of the 1st 25 characters of custom field 9 'acust_10': a semicolon-delimited list of the 1st 25 characters of custom field 10 'acust_11': a semicolon-delimited list of the 1st 25 characters of custom field 11 'acust_12': a semicolon-delimited list of the 1st 25 characters of custom field 12
In addition, all custom form field names and values in the checkout process will be included, sans prefix ('cust_') and suffix ('_db?'), if applicable.
The values of all 'a*' keys are linked. Likewise, values of all 's*' keys are linked. For this reason, it is advised not to name any custom form fields starting with 'a' or 's'. Most of the above is self-explanatory.
However, the link between 's*' and 'a*' keys requires some explanation.
Take, for example, this portion of a possible query to the webservice:
...&askus=1ABC,2CDE,1ABC,A3CE,QWE3&aqtys=1,2,1,3,1&sgrps=2,3&...
The sku '1ABC' appears twice in the 'askus' CDL. That is because each of the first and second ship-tos are receiving 1 of the '1ABC' product. As defined by the 'sgrps' CDL, the first ship-to is receiving the first two SKUs paired with the first two quantities, respectively. The second ship-to is receiving the next three SKUs paired with the next three quantities, respectively.
3.III RESPONSE FROM THE SERVICE
The response from your web service is a newline-delimited list of <key>=<value> pairs. The following keys are currently supported:
'smeths': CDL of ship-to shipping methods. Null values are ignored (i.e., 'smeths=,,DEFAULT,,' would change only the third ship-to's shipping method to 'DEFAULT' and leave the others unchanged). 'smsg': HTML message to be posted at top of 'checkout_display' (if using extended checkout) and 'checkout_confirmation' views. 'tadd': additional value to be applied to total shipping amount. Can be negative.
Note that all of the above are optional. These values, if specified, merely adjust the shipping methods and rates calculated by the CommerceV3 shipping options.
Color Maria maintains a sample web service written in PHP, including a modest suite of functions to speed up the process of developing your own web service. The source code will be made available upon request.
4. EXAMPLE
