Introducing Inventory Import and Export XML Using Inventory Export Guide To Manage Your Inventory Data Version 1.0 ADD TO CART XML API GUIDE 5/28/13 PAGE 1
Copyright 2013 Shopatron, Inc. Using Inventory Export Guide, Version 1.0 This document contains proprietary and confidential information of Shopatron, Inc., and is protected by Federal copyright law. The contents of this document may not be disclosed to third parties, translated, copied, or duplicated in any form, in whole or in part, (or by any means, electronic, mechanical, photocopying, or otherwise) without the express written permission of Shopatron, Inc. The information contained in this document is subject to change without notice. Neither Shopatron, Inc., its affiliates, nor their directors, officers, employees, or agents, are responsible for punitive or multiple damages or lost profits or other special, direct, indirect, incidental, or consequential damages, including any damages resulting from loss of business arising out of or resulting from the use of this material, or for technical or editorial omissions or errors made in it. Aspects of the Shopatron network are patented, patent-pending, or patent-applied for. Shopatron North America Shopatron, Inc. P.O. Box 5351 San Luis Obispo, CA, 93403 Shopatron Europe Shopatron UK, Ltd. Newport House 19-21 Newport Street Old Town, Swindon SN1 3DX
Contents Introducing Inventory Import and Export... 4 Using Inventory Export... 4 Getting Started... 4 Setup requirements... 4 Scheduling Imports and Exports... 5 Inventory Export files... 5 Aggregate Export files... 5 File names for aggregate Exports... 5 Data elements: aggregate Exports... 5 Location Export files... 6 File names for location Exports... 6 Data elements: location Exports... 6 Example Requests... 8 Example 1: Aggregate Export schema... 8 Example 2: Location Export schema... 9 Example 3: Sample location Export file... 12 Example 4: Sample aggregate Export file... 13
Introducing Inventory Import and Export Introducing Inventory Import and Export Shopatron's Inventory Import and Export processes allow our clients to manage inventory data throughout multiple fulfillment locations. The Inventory Import process imports a fulfillment location's real-time inventory data into Shopatron for processing. The Inventory Export process exports the inventory data that is stored in Shopatron and transmits it to the client's front-end website when needed. With Inventory Import, fulfillment locations provide their real-time inventory data to the Shopatron system. The inventory data helps us to accurately assign orders to these locations and to set product availabilities. Some clients also use the imported inventory data to assign orders to their fulfillment locations. The inventory data is provided to those clients through the Inventory Export process. This document describes how to use the Inventory Export process to receive stock information from Shopatron. To learn how you can provide your real-time stock level information to Shopatron, see the separate document, Using Inventory Import Guide. Using Inventory Export Two types of exports are available: Aggregate Exports and Location Exports. An Aggregate Export provides total stock information for items across all fulfillment locations included in the export. Location Exports provide item stock and location information, sorted by fulfillment location. Shopatron staff will help you determine the types of export you need to receive and when you need to receive them. Getting Started NOTE: If you want to start using Shopatron to manage your inventory data, please call your Shopatron Account Manager. Setup requirements To get started, you will need an SFTP (Secure FTP) site where we can pick up and drop off inventory files. We will also ask you to provide a username, password, remote path, and remote path archive for the file transmission location. USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 4
Inventory Export files Scheduling Imports and Exports Your inventory imports and exports will occur on a regular, set schedule. Shopatron staff will work with you to determine the optimum frequency and times that you should perform each type of import and export. Inventory Export files Inventory data is provided as XML files, compressed into Zip format. We also provide a Trigger or Control file with the data. The Trigger file is written to the SFTP after transmission of the Inventory Export file is completed. Trigger files are empty files and have an extension of.done. Aggregate Export files Aggregate Export files provide total stock information for items across multiple fulfillment locations. File names for aggregate Exports Files are named as follows: Where: mfg_id_agg_yymmddhhmmss - for XML files File name extension is.xml for XML files;.zip for zip files;.done for Trigger files. mfg_id is your Shopatron-assigned manufacturer ID (for example, 3456) YYMMDD is the date as year-month-day that the file is created (for example, 130301 for March 1, 2013) _AGG_ designates that this is an Aggregate file, and is entered literally hhmmss is the time as hour-minute-second that the file is created in Pacific Standard Military Time (for example, 225912 for 10:59:12 p.m. PT) Data elements: aggregate Exports http://api.shopatron.com/xsd/inventoryaggregateexport.xsd Element Required Data Type (Length) Occurs Description Item Yes Number of items in inventory (1 to 50) A container that includes information for one item in inventory. PartNumber Optional String (50) 0 or 1/item The merchant-assigned Part Number for the product. UPC Optional String (50) 0 or 1/item The UPC of the product. USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 5
Inventory Export files Element Required Data Type (Length) Occurs Description SKU Optional String (50) 0 or 1/item The SKU for the product. QuantityOnHand Yes Integer 1/item The number of this item in inventory. QuantityAvailable Yes Integer 1/item The number of this item that are available to sell; in other words, the QuantityOnHand minus the quantity already allocated minus the safety stock level. Location Export files Location Exports provide item stock and location information, by fulfillment location. File names for location Exports Files are named as follows: Where: mfg_id_loc_yymmddhhmmss.xml - for XML files mfg_id_loc_yymmddhhmmss.zip - for zip files mfg_id is your Shopatron-assigned manufacturer ID (for example, 3456) YYMMDD is the date as year-month-day that the file is created (for example, 130301 for March 1, 2013) _LOC_ designates that this is a location file, and is entered literally hhmmss is the time as hour-minute-second that the file is created in Pacific Standard Military Time (for example, 225912 for 10:59:12 p.m. PT. Data elements: location Exports http://api.shopatron.com/xsd/inventoryexport.xsd Element Required Date Type (Length) Occurs Description Location Yes Struct Number of locations in inventory file A container that includes all the information for this location. LocationName Yes String (50) 1/location The name of this location. LocationActive Yes Int 1/location Indicates whether this location is active (1) or not active (0). USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 6
Inventory Export files Element Required Date Type (Length) Occurs Description STHEnabled Optional Int 1/location Indicates whether this store fulfills Standard (ship to home) orders; 0 (no) or 1 (yes). If not specified, default of 1 (yes) is used. STSEnabled Optional Int 1/location Indicates whether this store fulfills Ship to Store orders; 0 (no) or 1 (yes). If not specified, default of 0 (no) is used. ISPUEnabled Optional Int 1/location Indicates whether this store fulfills In- Store Pickup Local Search First orders; 0 (no) or 1 (yes). If not specified, default of 0 (no) is used. IncludeIn AggregateFeed Optional Int 1/location Indicates whether this location information is included in the aggregate inventory export file; 0 (no) or 1 (yes). If not specified, default of 1 (yes) is used. Item Yes Number of items in inventory file (1 to 50) A container that includes information for one item in inventory. PartNumber Optional String (50) 0 or 1/item The merchant-assigned Part Number for the product. UPC Optional String (50) 0 or 1/item The UPC of the product. SKU Optional String (50) 0 or 1/item The SKU for the product. QuantityOnHand Yes Int 1/item The number of this item in inventory. QuantityAvailable Yes Int 1/item The number of this item that are available to sell; in other words, the QuantityOnHand minus the quantity already allocated minus the safety stock level. SafetyStock Optional Int 0 or 1/Item Quantity you want to keep in stock to ensure your stock isn't completely depleted. Both Safety Stock and Floor are optional; most people prefer Safety Stock to Floor. USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 7
Example Requests Element Required Date Type (Length) Occurs Description Floor Optional Int 0 or 1/Item Absolute minimum number that should be in stock at any time. Both Safety Stock and Floor are optional; most people prefer Safety Stock to Floor. LTD Optional Int 0 or 1/Item Custom field used for store prioritization. Shopatron will advise you on the type of data to enter in this field, if you need to use it. Example Requests Example 1: Aggregate Export schema This example has only required elements and shows a single order with one item. Example 1: Aggregate Export schema <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/xmlschema" attributeformdefault="unqualified" elementformdefault="qualified"> <xs:element name="schema"> <xs:element name="element"> <xs:extension base="xs:string"> <xs:attribute type="xs:string" name="name" /> <xs:attribute type="xs:string" name="type" /> <xs:element name="complextype" maxoccurs="unbounded" minoccurs="0"> <xs:element name="sequence"> <xs:element name="element" maxoccurs="unbounded" minoccurs="0"> <xs:extension base="xs:string"> <xs:attribute type="xs:string" name="name" use="optional" /> <xs:attribute type="xs:byte" name="minoccurs" use="optional" /> <xs:attribute type="xs:string" USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 8
Example Requests Example 1: Aggregate Export schema name="maxoccurs" use="optional" /> <xs:attribute type="xs:string" name="type" use="optional" /> <xs:attribute type="xs:string" name="nillable" use="optional" /> <xs:attribute type="xs:string" name="name" use="optional" /> <xs:element name="simpletype"> <xs:element name="restriction"> <xs:element name="maxlength"> <xs:extension base="xs:string"> <xs:attribute type="xs:byte" name="value" /> <xs:attribute type="xs:string" name="base" /> <xs:attribute type="xs:string" name="name" /> <xs:attribute type="xs:anyuri" name="targetnamespace" /> <xs:attribute type="xs:string" name="elementformdefault" /> </xs:schema> Example 2: Location Export schema Example 2: Location Export schema <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/xmlschema" attributeformdefault="unqualified" elementformdefault="qualified"> <xs:element name="schema"> USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 9
Example Requests Example 2: Location Export schema <xs:element name="element"> <xs:extension base="xs:string"> <xs:attribute type="xs:string" name="name" /> <xs:attribute type="xs:string" name="type" /> <xs:element name="complextype" maxoccurs="unbounded" minoccurs="0"> <xs:element name="sequence"> <xs:element name="element" maxoccurs="unbounded" minoccurs="0"> <xs:complextype mixed="true"> <xs:element name="annotation" minoccurs="0"> <xs:element name="documentation"> <xs:extension base="xs:string"> <xs:attribute ref="xml:lang" /> <xs:element name="simpletype" minoccurs="0"> <xs:element name="restriction"> <xs:element name="mininclusive"> <xs:extension base="xs:string"> <xs:attribute type="xs:byte" name="value" /> USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 10
Example Requests Example 2: Location Export schema <xs:attribute type="xs:string" name="base" /> <xs:attribute type="xs:string" name="name" use="optional" /> <xs:attribute type="xs:byte" name="minoccurs" use="optional" /> <xs:attribute type="xs:string" name="maxoccurs" use="optional" /> <xs:attribute type="xs:string" name="type" use="optional" /> <xs:attribute type="xs:string" name="nillable" use="optional" /> <xs:attribute type="xs:string" name="default" use="optional" /> <xs:attribute type="xs:string" name="name" use="optional" /> <xs:element name="simpletype" maxoccurs="unbounded" minoccurs="0"> <xs:element name="restriction"> <xs:element name="maxlength" minoccurs="0"> <xs:extension base="xs:string"> <xs:attribute type="xs:byte" name="value" /> <xs:element name="mininclusive" minoccurs="0"> <xs:extension base="xs:string"> <xs:attribute type="xs:byte" name="value" /> <xs:attribute type="xs:string" name="base" use="optional" /> USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 11
Example Requests Example 2: Location Export schema <xs:attribute type="xs:string" name="name" use="optional" /> <xs:attribute type="xs:anyuri" name="targetnamespace" /> <xs:attribute type="xs:string" name="elementformdefault" /> </xs:schema> Example 3: Sample location Export file Example 3: Sample location Export file <?xml version="1.0" encoding="utf-8"?> <InventoryExport> <Location> <LocationName>0001</LocationName> <LocationActive>true</LocationActive> <STHEnabled>true</STHEnabled> <ISPUEnabled>true</ISPUEnabled> <STSEnabled>true</STSEnabled> <IncludeInAggregateFeed>true</IncludeInAggregateFeed> <Item> <PartNumber>883360541099</PartNumber> <SKU>883360541099</SKU> <QuantityAvailable>94</QuantityAvailable> <QuantityOnHand>94</QuantityOnHand> <SafetyStock>0</SafetyStock> <Floor>0</Floor> <LTD>0</LTD> </Item> <Item> <PartNumber>883360541075</PartNumber> <SKU>883360541075</SKU> <QuantityAvailable>73</QuantityAvailable> <QuantityOnHand>73</QuantityOnHand> <SafetyStock>0</SafetyStock> <Floor>0</Floor> <LTD>0</LTD> </Item> </Location> <Location> <LocationName>0002</LocationName> <LocationActive>true</LocationActive> <STHEnabled>true</STHEnabled> <ISPUEnabled>true</ISPUEnabled> <STSEnabled>true</STSEnabled> <IncludeInAggregateFeed>true</IncludeInAggregateFeed> <Item> <PartNumber>883360541099</PartNumber> <SKU>883360541099</SKU> <QuantityAvailable>10</QuantityAvailable> <QuantityOnHand>10</QuantityOnHand> USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 12
Example Requests Example 3: Sample location Export file <SafetyStock>0</SafetyStock> <Floor>0</Floor> <LTD>0</LTD> </Item> <Item> <PartNumber>883360541075</PartNumber> <SKU>883360541075</SKU> <QuantityAvailable>22</QuantityAvailable> <QuantityOnHand>22</QuantityOnHand> <SafetyStock>0</SafetyStock> <Floor>0</Floor> <LTD>0</LTD> </Item> </Location> </InventoryExport> Example 4: Sample aggregate Export file Example 4: Sample aggregate Export file <?xml version="1.0" encoding="utf-8"?> <InventoryAggregateExport> <Item> <PartNumber>883360541099</PartNumber> <UPC /> <SKU>883360541099</SKU> <QuantityOnHand>100</QuantityOnHand> <QuantityAvailable>80</QuantityAvailable> </Item> <Item> <PartNumber>883360541075</PartNumber> <UPC /> <SKU>883360541075</SKU> <QuantityOnHand>77</QuantityOnHand> <QuantityAvailable>65</QuantityAvailable> </Item> </InventoryAggregateExport> USING INVENTORY EXPORT GUIDE, VERSION 1.0 5/28/13 PAGE 13