Legacy Single Item API

Overview

To view/generate your Order API token in Fillz:

  1. Go to Account -> API/FTP
  2. Click Generate New Legacy API Token 
  3. Copy the token (the token will only be shown once)

Use the POST HTTP method to send XML to the following URL:

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. )

Throttling

Calls are limited to 15 calls/second, 240 calls/minute, and 5400 calls/hour.

Security

TLS v1.2 is highly recommended, however, v1.0 and v1.1 are permitted.

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></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.

ToCountry will be blank for US orders, but will contain a value for any other Country.

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> <!-- tracking number -->
   <Service>USPS</Service> <!-- USPS/FEDEX/UPS/DHL/DHLGM -->
  </Package>
</SetOrderStatus>
  • You need to include at least one “package attribute”, such as , 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 the marketplace 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).

Modifying Orders in Bulk

Up to 10 orders can be moved to a new status and have their postage set with one API call in Fillz:

<SetBatchOrderStatus>
  <AuthUser>username</AuthUser>
  <AuthToken>token</AuthToken>
  <SetOrderStatus id="1234" status="shipped">
    <Package>
      <FinalPostage>3.99</FinalPostage>
      <TransactionDateTime>2016-07-21 05:16:24</TransactionDateTime>
      <PostmarkDate>2016-07-22</PostmarkDate>
      <Status>Success</Status>
      <TransactionID>ABC-123</TransactionID>
      <PIC>4321-8765-81576</PIC> <!-- tracking number -->
      <Service>USPS</Service> <!-- USPS/FEDEX/UPS/DHL/DHLGM -->
    </Package>
  </SetOrderStatus>
  <SetOrderStatus id="1235" status="work1">
    <Package>
      <FinalPostage>2.99</FinalPostage>
      <TransactionDateTime>2016-07-21 05:17:31</TransactionDateTime>
      <PostmarkDate>2016-07-22</PostmarkDate>
      <Status>Success</Status>
      <TransactionID>DEF-456</TransactionID>
      <PIC>9876-5432-21875</PIC> <!-- tracking number -->
      <Service>UPS</Service> <!-- USPS/FEDEX/UPS/DHL/DHLGM -->
    </Package>
  </SetOrderStatus>
</SetBatchOrderStatus>

The syntax is similar to SetOrderStatus and contains the same restrictions, namely:

  • You need to include at least one "package attribute", but you do not need to include them all
  • You have the following options for changing order status: "packed" (aka in Process), "shipped, "cancelled", "deferred", and any work folders you have configured, such as "work1"
  • 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 the marketplace 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).

There are a few small differences from the single SetOrderStatus to note:

  • AuthUser and AuthToken are set under SetBatchOrderStatus, not each individual SetOrderStatus, so that they are only sent once
  • The response will contain a "Message" line for each order in the batch, and will appear in the same order they appear in the request
  • A single failure will result in a 500 code being returned, though other orders could have still been processed successfully

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 field are positive and negative numbers. Examples: 1, -1, 2, -2

Accessing API from your code

Using PHP to access API

Have more questions? Submit a request