FillZAPI

Overview

To view/generate your API token:

 Login to your FillZ account and click on "Settings". Under the "Change password" section, click "FTP or API token".

Use the POST HTTP method to send XML to the following URL (substitute w1 with the server number the account is on):

https://w1.fillz.com/exec/api1

General return:

<Result>
 <Code>200</Code>
 <Message>Success</Message>
</Result>

or:

<Result>
 <Code>500</Code>
 <Message>Internal error</Message>
</Result>

(codes starting with 2 are success and starting with 5 are failures. )

Getting orders

Getting an order list

This XML call is used by the postage software to get all orders of a certain status:

<GetOrders status="new">
  <AuthUser>username</AuthUser>
  <AuthToken>token</AuthToken>
</GetOrders>

Valid status values are "new", "packed", "shipped", "unconfirm", "deferred", "cancelled" and the user-defined folders "work1" through "work20".

result is a list of order IDs:

<Orders>
  <Order id="1234"/>
  <Order id="1235"/>
</Orders>

Getting a specific order

<GetOrder id="1234">
  <AuthUser>username</AuthUser>
  <AuthToken>token</AuthToken>
</GetOrder>

result is

<Order id="1234">
   <Status>new</Status>
   <ShipMethod>Standard</ShipMethod>
   <Marketplace name="Amazon" id="4567"/>
   <ToName>John Doe</ToName>
   <ToAddress1>100 Main St </ToAddress1>
   <ToAddress2>Suite 120 </ToAddress2>
   <ToCity>San Jose </ToCity>
   <ToState>CA </ToState>
   <ToPostalCode>94001</ToPostalCode>
   <ToCountry>USA</ToCountry>
   <ToEmail>jdoe@gmail.com</ToEmail>
   <ToPhone></ToPhone>
   <Date>2006-04-06 13:27:39</Date>
   <CreateDate>2006-04-06 14:58:53</CreateDate>
   <LastModified>0000-00-00 00:00:00</LastModified>
   <PaymentReceiveDate></PaymentReceiveDate> 
   <Value>12.34</Value>
   <Currency>USD</Currency>
   <ShippingTotal>0</ShippingTotal>
</Order>

Status is "new", "packed", "shipped" or "cancelled".

ShipMethod will most commonly contain Standard, Expedited, NextDay and SecondDay. However, additional options are possible depending on the marketplace that processed the order. In addition, the value of this field can be edited in the FillZ UI. Users of the Order API must be prepared to deal with unexpected values in this field.

Getting more details about an order

Adding the "detail" parameter with a value of 1, provides addition information about the items within an order.

<GetOrder id="36578494" detail="1">
  <AuthUser>username</AuthUser>
  <AuthToken>token</AuthToken>
</GetOrder>

Will return:

<Order id="36578494">
    <Status>new</Status>
    <ShipMethod>Standard International</ShipMethod>
    <Marketplace id="M00001" name="Store"/>
    <ToName>Jane Doe</ToName>
    <ToAddress1>100 Main St</ToAddress1>
    <ToAddress2>Apt 123</ToAddress2>
    <ToCity>San Francisco</ToCity>
    <ToState>CA</ToState>
    <ToPostalCode>94105</ToPostalCode>
    <ToCountry></ToCountry>
    <ToEmail>info@fillz.com</ToEmail>
    <ToPhone>555-555-1212</ToPhone>
    <Date>2006-04-06 13:27:39</Date>
    <CreateDate>2006-04-06 14:58:53</CreateDate>
    <LastModified>0000-00-00 00:00:00</LastModified>
    <PaymentReceiveDate></PaymentReceiveDate> 
    <Value>16.67</Value>
    <Currency>USD</Currency>
    <ShippingTotal>4.50</ShippingTotal> 
    <BuyerNote>This is a note made by the buyer</BuyerNote>
    <SellerNote>This is a note made by the seller</SellerNote>
    <Items>
        <Item>
            <SKU>X001</SKU>
            <Author>Ray Kurzweil</Author>
            <Title>The Singularity Is Near: When Humans Transcend Biology</Title>
            <Media>Hardcover</Media>
            <ProductId>0670033847</ProductId>
            <Location>[-]</Location>
            <Quantity>1</Quantity>
            <Condition>1</Condition>
            <Price>6.78</Price>
            <Shipping>2.00</Shipping>
            <Note>This is a note about the book</Note>
        </Item>
        <Item>
            <SKU>X002</SKU>
            <Author>Henry Beard; Roy McKie</Author>
            <Title>Sailing - A Sailor's Dictionary - A Dictionary for Landlubbers, Old Salts, & Armchair Drifters</Title>
            <Media>Paperback</Media>
            <ProductId>0894801449</ProductId>
            <Location>[xyz1]</Location>
            <Quantity>1</Quantity>
            <Condition>1</Condition>
            <Price>9.89</Price>
            <Shipping>2.50</Shipping>
            <Note>This is a note about the book</Note>
        </Item>
    </Items>
</Order>

Getting complete details about an order

Adding the "detail" parameter with a value of 2, provides all the information from level 1, in addition to Cost, OrderItemId and Source details for each item, and the PaymentMethod for the order.

The level of detail you choose to request depends only on the amount of information you want to process.

<GetOrder id="36578494" detail="2">
  <AuthUser>username</AuthUser>
  <AuthToken>token</AuthToken>
</GetOrder>

Will return:

<Order id="36578494">
    <Status>new</Status>
    <ShipMethod>Standard International</ShipMethod>
    <Marketplace id="M00001" name="Store"/>
    <ToName>Jane Doe</ToName>
    <ToAddress1>100 Main St</ToAddress1>
    <ToAddress2>Apt 123</ToAddress2>
    <ToCity>San Francisco</ToCity>
    <ToState>CA</ToState>
    <ToPostalCode>94105</ToPostalCode>
    <ToCountry></ToCountry>
    <ToEmail>info@fillz.com</ToEmail>
    <ToPhone>555-555-1212</ToPhone>
    <Date>2006-04-06 13:27:39</Date>
    <CreateDate>2006-04-06 14:58:53</CreateDate>
    <LastModified>0000-00-00 00:00:00</LastModified>
    <PaymentReceiveDate></PaymentReceiveDate> 
    <Value>16.67</Value>
    <Currency>USD</Currency>
    <ShippingTotal>4.50</ShippingTotal> 
    <BuyerNote>This is a note made by the buyer</BuyerNote>
    <SellerNote>This is a note made by the seller</SellerNote>
    <Items>
        <Item>
            <SKU>X001</SKU>
            <Author>Ray Kurzweil</Author>
            <Title>The Singularity Is Near: When Humans Transcend Biology</Title>
            <Media>Hardcover</Media>
            <ProductId>0670033847</ProductId>
            <Location>[-]</Location>
            <Quantity>1</Quantity>
            <Condition>1</Condition>
            <Price>6.78</Price>
            <Shipping>2.00</Shipping>
            <Note>This is a note about the book</Note>
            <Cost>0.00</Cost>
            <OrderItemId>2147483645</OrderItemId>
            <Source>data from the source field of your listing</Source>
        </Item>
        <Item>
            <SKU>X002</SKU>
            <Author>Henry Beard; Roy McKie</Author>
            <Title>Sailing - A Sailor's Dictionary - A Dictionary for Landlubbers, Old Salts, & Armchair Drifters</Title>
            <Media>Paperback</Media>
            <ProductId>0894801449</ProductId>
            <Location>[xyz1]</Location>
            <Quantity>1</Quantity>
            <Condition>1</Condition>
            <Price>9.89</Price>
            <Shipping>2.50</Shipping>
            <Note>This is a note about the book</Note>
            <Cost>0.00</Cost>
            <OrderItemId>2147483317</OrderItemId>
            <Source>data from the source field of your listing</Source>
        </Item>
    </Items>
    <PaymentMethod>Prepaid</PaymentMethod>
</Order>

Modifying Orders

To set the postage result of an order, and move it to a new status in FillZ:

<SetOrderStatus id="1234" status="shipped">
  <AuthUser>username</AuthUser>
  <AuthToken>token</AuthToken>
  <Package>
   <FinalPostage>1.23</FinalPostage>
   <TransactionDateTime>2006-01-01 04:04:04</TransactionDateTime>
   <PostmarkDate>2006-01-02</PostmarkDate>
   <Status>Success</Status>
   <TransactionID>abc123456</TransactionID>
   <PIC>1234-5678-92839</PIC> <!-- this is the tracking code -->
   <Service>USPS</Service> <!-- USPS/FEDEX/UPS/DHL/DHLGM -->
  </Package>
</SetOrderStatus>

• You need to include at least one "package attribute", such as <Status>, but you do not need to include all of them.
• You have the following options for changing the order status: "packed" (aka In Process), "shipped", "cancelled", "deferred"
• If you have configured work folders, you can change the order status to these as well. For example: "work1", "work2"

• If an order cannot be confirmed it will be moved to a status called "unconfirm" in the FillZ account. Should you see this, you should take a look at the order on Amazon to see if there are any problems. These orders won't show a "success" message when you change their status to packed/shipped (depending on your FillZ settings).

Adding/Subtracting Quantity for Inventory

To add or subtract from the total quantity in FillZ for an item:

<EditItem sku="sku">
  <AuthUser>username</AuthUser>
  <AuthToken>token</AuthToken>
  <QuantityChange>quantity_delta</QuantityChange>
</EditItem> 

Valid values for the <QuantityChange> field are positive and negative numbers. Examples: 1, -1, 2, -2