Endpoints

XML Requests

Nine types of requests can be sent to the Order Update server:

getOrder
getAllNewOrders
update
updateShipping
searchOrders
getReturn
searchReturns
initiateReturn
updateReturn

Common Request Elements

All order update requests follow XML standards and should include the standard XML header:

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.0">
  <action name="getOrder">
    <username>jsinclair</username>
    <password>123abc</password>
  </action>
</orderUpdateRequest>

orderUpdateRequest Tag — This tag encompasses the entire order update request version. The current available versions are 1.0, 1.1, 1.2 and 1.3.

action Tag — This tag tells the Order Update server which action to take and which user should execute the action. The parameter "name" may have the value of "getAllNewOrders", "getOrder", "update", "updateShipping" or "searchOrders", indicating which action to take. The value of the elements "username" and "password" must represent a valid AbeBooks.com bookseller, and this bookseller must be the owner of the purchase order being processed by the action.

getAllNewOrders Request

This request returns all new orders that are available for processing (all ABEPOs that are in the status "seller notified").

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.1">
  <action name="getAllNewOrders">
    <username>jsinclair</username>
    <password>123abc</password>
  </action>
</orderUpdateRequest>

All orders returned by the getAllNewOrdersRequest may be processed by the update request. The output is limited to 500 orders. Repeated calls to this request will return the same orders until the individual orders are processed, or change status for some other reason, such as buyer cancellation.

To receive more than 500 orders, use the <offset> and <limit> parameters, incrementing the offset to 500 on each subsequent call. Keep using it until you receive less than 500 orders, at which point you would have completed all the pending orders.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.1">
  <action name="getAllNewOrders">
    <username>jsinclair</username>
    <password>123abc</password>
  </action>
  <limit>500</limit>
  <offset>0</offset>
</orderUpdateRequest>

searchOrders Request

This action is used to search for purchase orders based on a set of parameters. Each of the parameters is optional. A request with no parameters uses the default for all parameters, results are always sorted by creation date in descending order (newest first). All parameters are grouped inside an orderSearch tag. The response has the same format as the getAllNewOrders response.

Parameter	Required	Description
createdAfter	No	Return orders created on or after this date in ISO 8601 format. Cannot be used with `updatedAfter` or `updatedBefore`. Defaults to 10 years ago, which is also the earliest date that can be searched.
createdBefore	No	Return orders created on or before this date in ISO 8601 format. Cannot be used with `updatedAfter` or `updatedBefore`. Must be after `createdAfter`. Defaults to the current time.
updatedAfter	No	Return orders whose status was last updated on or after this date in ISO 8601 format. Cannot be used with `createdAfter` or `createdBefore`. Defaults to 10 years ago, which is also the earliest date that can be searched.
updatedBefore	No	Return orders whose status was last updated on or before this date in ISO 8601 format. Cannot be used with `createdAfter` or `createdBefore`. Must be after `updatedAfter`. Defaults to the current time.
status	No	The status of the orders to return. Valid values are `CANCELLED`, `EXPIRED`, `ORDERED`, `PROCESSED` and `REJECTED`. Defaults to all statuses.
limit	No	The maximum results to return in the search. The default is 10. Valid values are from 0 to 100. A value greater than 100 is treated as 100.
offset	No	Use with the limit to page through results if the number of results available exceeds the limit. Defaults to 0.

All date parameters must include a timezone offset (for example 2025-04-30T00:00:00-07:00) or be in UTC (for example 2023-10-19T19:07:50Z). Dates are converted to the America/Vancouver timezone for processing. Orders older than 10 years from the current date cannot be searched.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.3">
  <action name="searchOrders">
    <username>jsinclair</username>
    <password>abc123</password>
  </action>
  <orderSearch>
    <createdAfter>2025-04-30T00:00:00-07:00</createdAfter>
    <createdBefore>2025-05-01T00:00:00-07:00</createdBefore>
    <status>PROCESSED</status>
    <limit>100</limit>
    <offset>0</offset>
  </orderSearch>
</orderUpdateRequest>

To page through results, increment the offset by the limit on each subsequent call. Keep going until you receive fewer orders than the limit, at which point you have retrieved all matching orders.

The searchOrders action works with any request version. The shipping speed and last status update date fields (see the Response Element Reference) are only returned when the request uses version 1.3 or later.

getOrder Request

If you specify an order number with this request, the order details can be retrieved. This request will return processed and unprocessed purchase orders. Retrieval is limited to purchase orders on which you are the seller.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.1">
  <action name="getOrder">
    <username>jsinclair</username>
    <password>123abc</password>
  </action>
  <purchaseOrder id="1234"/>
</orderUpdateRequest>

update and updateShipping Request

The update request is used to change the status of the purchase order and each of the books in the purchase order. Marking a book as "shipped" results in a credit card transaction on the buyer's card. An update request can take one of two forms: A single status that is applied to all items in the order, or a status for individual items. Each item in the order must be set to one of the valid statuses. Failure to update the status of all items in an order will result in the update request failing. Note that the update request only processes one order at a time.

Example with status applied to all items:

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.1">
  <action name="update">
    <username>jsinclair</username>
    <password>123abc</password>
  </action>
  <purchaseOrder id="3425234">
    <shipping>
      <company>FEDEX</company>
      <trackingCode>12343456231341234</trackingCode>
    </shipping>
    <status>shipped</status>
  </purchaseOrder>
</orderUpdateRequest>

Example with status applied to individual items:

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.1">
  <action name="update">
    <username>jsinclair</username>
    <password>abc123</password>
  </action>
  <purchaseOrder id="3425234">
    <purchaseOrderItemList>
      <purchaseOrderItem id="1212">
        <status>shipped</status>
      </purchaseOrderItem>
      <purchaseOrderItem id="1213">
        <status>rejected</status>
      </purchaseOrderItem>
    </purchaseOrderItemList>
  </purchaseOrder>
</orderUpdateRequest>

If you do not have the shipping information at the time the order status is updated, you can use the orderUpdateRequest with the updateShipping action at a later time. This request is useful for minimizing returns made for "item did not arrive" as well as reducing the number of customer service contacts. Please note that the shipping company field is limited to 25 characters, and the tracking number is limited to 200.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.1">
  <action name="updateShipping">
    <username>jsinclair</username>
    <password>abc123</password>
  </action>
  <purchaseOrder id="xxxxxxx">
    <shipping>
      <company>FEDEX</company>
      <trackingCode>12343456231341234</trackingCode>
    </shipping>
  </purchaseOrder>
</orderUpdateRequest>

Request Element Reference

purchaseOrder Tag — Identifies the order to update. The ID is the AbeBooks.com purchase order ID, or ABEPOID. The user specified in the action tag must own the purchase order for this request to be successful.

shipping Tag (optional) — Can be used to inform the buyer of the shipping company used and the tracking number.

status Tag (applied to all items) — This status tag applies to all items in the order. If it is present, all item specific statuses are ignored.

Status	Definition
Shipped	Bookseller will ship the item
Rejected	Bookseller rejected the item
PreviouslySold	Bookseller already sold the item
CreditCardDeclined	The buyer's credit card was declined
availabilityConfirmed	Seller Direct order accepted

purchaseOrderItemList Tag — Contains the list of items in the order.

purchaseOrderItem Tag — Identifies the item within the order to alter. The ID must be set to the AbeBooks purchase order item ID or ABEPOITEMID. For an order update request to be accepted, all items within the order must be included.

status Tag (applied to individual items):

Status	Definition
Shipped	Seller will ship the item
Rejected	Seller rejected the item
PreviouslySold	Seller already sold the item
availabilityConfirmed	Seller Direct order accepted

getReturn Request

This action is used to retrieve a single return using the return ID.

searchReturns Request

This action is used to search for returns based on a set of parameters. Each of the parameters is optional, and a request with no parameters will search for the most recent returns. Returns in the response are always ordered by most recent initiated date first. All parameters are grouped inside a returnSearch tag.

Parameter	Required	Description
purchaseOrderItem id	No	The identifier for a single purchase order item.
returnStatus	No	The current status of a return. The allowed statuses are defined in the Return Statuses appendix.
dateStart	No	The date to start looking for returns in ISO 8601 format. If only start date is provided then returns from the date start to current time will be searched for.
dateEnd	No	The date to stop looking for returns in ISO 8601 format. If only end date is provided, then all returns up until the end date will be searched for.
limit	No	The maximum results to return in the search. The default for the limit is 500. Valid values are from 0 to 500.
offset	No	Use with the limit to page through results if the number of results available exceeds the limit.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.1">
  <action name="searchReturns">
    <username>jsinclair</username>
    <password>abc123</password>
  </action>
  <returnSearch>
    <purchaseOrderItem id="629929538"/>
    <returnStatus>I</returnStatus>
    <dateStart>2023-09-13T20:00:00+02:00</dateStart>
    <dateEnd>2023-09-13T21:00:00+02:00</dateEnd>
    <limit>100</limit>
    <offset>0</offset>
  </returnSearch>
</orderUpdateRequest>

initiateReturn Request

This action allows the creation of a return for a given item. All parameters are grouped inside a returnInitiation tag.

Parameter	Required	Description
purchaseOrderItem id	Yes	The identifier for a single purchase order item.
returnReason	Yes	The reason for the return. Valid return reasons can be found in the Return Reasons appendix.
processImmediately	No	A true or false value that determines if the return should be processed immediately or opened but not processed. This parameter is invalid for return reasons 01 and 07 along with any return on an order that had a seller direct payment method because those returns will always be processed immediately. Defaults to true if not specified.
includeReturnShipping	No	A true or false value that determines if the buyer should be refunded for return shipping. This parameter is only valid for return reason 05. Any request that has this parameter but does not have return reason 05 will fail.
comments	No	A text field to attach comments to a return. These comments are visible to buyers.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateRequest version="1.1">
  <action name="initiateReturn">
    <username>jsinclair</username>
    <password>abc123</password>
  </action>
  <returnInitiation>
    <purchaseOrderItem id="629929538"/>
    <returnReason>05</returnReason>
    <includeReturnShipping>true</includeReturnShipping>
    <processImmediately>false</processImmediately>
    <comments>seller return comments</comments>
  </returnInitiation>
</orderUpdateRequest>

updateReturn Request

This action allows the status of a return that is "In progress" to be changed. All parameters are grouped inside a returnUpdate tag. There are rules around what updates are allowed on returns — see the Rules for Updating Returns appendix.

XML Responses

Purchase Order Response (getOrder/update)

The requests "getOrder" and "update" return a single purchase order. In the case of an "update" request, the statuses of each item in the order will be updated and the order totals re-calculated.

Note: there are two places that a "status" tag appears — one relating to the purchaseOrder, which encompasses the order as a whole, and one relating to each purchaseOrderItem in the order, which indicates the status of individual items. It is possible for some items in an order to be in "Buyer Cancelled" status while others are "Shipped". In this case, it's important that only the "shipped" items are physically shipped to the buyer, as no payment is collected for cancelled items. For partially cancelled orders, the purchaseOrder status will appear as "Processed", so it's important to examine the status of each individual purchaseOrderItem.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateResponse version="1.1">
  <purchaseOrder id="1121066">
    <buyer id="877723">
      <email>blah@somewhere.com</email>
      <mailingAddress>
        <city>Vancouver</city>
        <code>V8T 1Z1</code>
        <country>Canada</country>
        <name>John Doe</name>
        <phone>604-123-1234</phone>
        <region></region>
        <street>123 John Avenue</street>
        <street2></street2>
      </mailingAddress>
    </buyer>
    <domain id="1">
      <name>abebooks.com</name>
    </domain>
    <indirectTaxList>
      <indirectTax>
        <taxCollectionModel>EU VAT for Ecommerce</taxCollectionModel>
        <AbeBooksRegistrationNumber>IM1234567</AbeBooksRegistrationNumber>
        <taxMessage>dummy message</taxMessage>
      </indirectTax>
    </indirectTaxList>
    <orderDate>
      <date><day>2</day><month>8</month><year>2002</year></date>
      <time><hour>1</hour><minute>13</minute><second>38</second></time>
    </orderDate>
    <orderTotals>
      <gst currency="USD">0.0</gst>
      <handling currency="USD">0.0</handling>
      <shipping currency="USD">8.5</shipping>
      <subtotal currency="USD">25.0</subtotal>
      <tax currency="USD">0.0</tax>
      <total currency="USD">33.5</total>
    </orderTotals>
    <purchaseMethod>CC</purchaseMethod>
    <purchaseOrderItemList>
      <purchaseOrderItem id="2077519">
        <book id="63511185">
          <author>Irving, Washington</author>
          <description>Robert A. Reynolds 8vo, 357p Klikitat Edition.</description>
          <price currency="USD">25.0</price>
          <title>Adventures of Captain Bonneville</title>
          <vendorKey>000073</vendorKey>
          <weightValue>1.00</weightValue>
          <weightUnit>GRAMS</weightUnit>
        </book>
        <orderDate>
          <date><day>2</day><month>8</month><year>2002</year></date>
          <time><hour>1</hour><minute>13</minute><second>38</second></time>
        </orderDate>
        <purchaseOrder id="1121066"/>
        <sellerTotal currency="USD">0.0</sellerTotal>
        <status code="05">Ordered</status>
      </purchaseOrderItem>
    </purchaseOrderItemList>
    <reseller id="15">
      <name>abebooks</name>
    </reseller>
    <seller id="6158"/>
    <shipmentManifest>
      http://www.abebooks.com/servlet/ShipmentManifest?abepoid=1121066
    </shipmentManifest>
    <shipping>
      <extraItemShippingCost currency="USD">0.0</extraItemShippingCost>
      <firstItemShippingCost currency="USD">0.0</firstItemShippingCost>
      <maxDeliveryDays>42</maxDeliveryDays>
      <minDeliveryDays>28</minDeliveryDays>
      <company>FEDEX</company>
      <trackingCode>12343456231341234</trackingCode>
    </shipping>
    <specialInstructions>Deliver express</specialInstructions>
    <status code="05">Ordered</status>
  </purchaseOrder>
</orderUpdateResponse>

When a request uses version 1.3 or later, the purchase order response includes two additional fields: a speed element within the shipping tag, and a lastStatusUpdateDate tag on the order. These fields are returned by getOrder, getAllNewOrders, update, updateShipping and searchOrders.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateResponse version="1.3">
  <purchaseOrder id="1121066">
    ...
    <lastStatusUpdateDate>
      <date><day>3</day><month>8</month><year>2002</year></date>
      <time><hour>14</hour><minute>22</minute><second>5</second></time>
    </lastStatusUpdateDate>
    ...
    <shipping>
      <extraItemShippingCost currency="USD">0.0</extraItemShippingCost>
      <firstItemShippingCost currency="USD">0.0</firstItemShippingCost>
      <maxDeliveryDays>42</maxDeliveryDays>
      <minDeliveryDays>28</minDeliveryDays>
      <company>FEDEX</company>
      <trackingCode>12343456231341234</trackingCode>
      <speed>PRIORITY</speed>
    </shipping>
    ...
  </purchaseOrder>
</orderUpdateResponse>

Response Element Reference

purchaseOrder Tag — Encompasses the entire order and indicates the AbeBooks.com ABEPOID.

buyer Tag — Lists the buyer specifics including name and address. The ID listed is the AbeBooks.com ClientID for this buyer.

domain Tag — Shows the originating domain for the order.

Domain Id	Domain Name
1	abebooks.com
46	abebooks.co.uk
47	abebooks.de
48	abebooks.fr
51	abebooks.it
52	iberlibro.com
53	zvab.com

orderDate Tag — Lists the date the order was placed.

lastStatusUpdateDate Tag (v1.3+) — The date and time the order's status was last updated, using the same date/time structure as orderDate.

orderTotals Tag — Lists the order totals displayed to the buyer in the bookseller's currency.

Tag	Definition
subtotal	The total of all items unprocessed or shipped
tax	The total tax on the order
gst	The total GST on the order
shipping	Total shipping on the order
handling	Total handling on the order
total	The total of all items, taxes, and shipping

purchaseMethod Tag — Displays the purchase method in use for the purchase order.

Purchase Method	Definition
CC	AbeBooks.com processed credit card
SD	Seller Direct
UNK	Unknown (Please contact inventory@abebooks.com if you receive this code.)

Seller Direct purchase method types (available for orderUpdateRequest v1.1+):

Check
PayPal
Direct Debit (Personally Authorized Payment)
Bank/Wire Transfer
Cash on Delivery (COD)
Money Order
Bank Draft
Invoice
Cash

purchaseOrderItem Tag — Contains the item specific information. The ID specifies the purchase order item ID, or ABEPOITEMID.

book Tag — Contains the book information in the order including author, description, title, ISBN, bookseller book price (in the seller's currency) and bookseller's BookID.

taxCollectionModel Tag (v1.1+) — Displays the tax collection model for which AbeBooks is responsible.

abeBooksRegistrationNumber Tag (v1.1+) — Displays AbeBooks' tax registration number.

taxMessage Tag (v1.1+) — Shows tax related information, if applicable.

weightValue Tag (v1.2+) — Shows the weight of a given item.

weightUnit Tag (v1.2+) — Shows the weight unit of a given item. Possible values: "GRAMS", "KILOGRAMS", "OUNCES", "POUNDS".

sellerTotal Tag — Contains the seller total in the bookseller's currency for this item. This value is zero on seller direct orders.

status Tag (item) — The status of the item, distinct from the status of the purchaseOrder.

Status	Definition
Buyer Cancelled	The buyer cancelled the item
Cancelled	The bookseller cancelled the item
Expired	The item expired because it was not processed in a timely manner
Ordered	The item is ready for processing
Previously Sold	The item was already sold by the seller
Rejected	The item was rejected by the credit card processor used by AbeBooks
Shipped	The item was shipped by the bookseller
Availability confirmed	The Seller Direct order has been processed by the seller

seller Tag — Lists the seller's AbeBooks client ID and currency.

shipmentManifest Tag — Shows the AbeBooks.com shipment manifest URL, present once the purchase order is in a processed status.

shipping Tag — The extraItemShippingCost and firstItemShippingCost fields will return 0.0 if users change rate types or use multiple templates. The total shipping cost will continue to be in the orderTotals section.

speed Tag (v1.3+) — The shipping speed for the order. Possible values: "PRIORITY", "STANDARD". May be empty if no shipping speed is set.

specialInstructions Tag — Contains the buyer's special instructions to the bookseller, if any.

status Tag (order) — Shows the status of the entire order. This is distinct from the status of the individual purchaseOrderItems and should not be relied upon to determine the status of individual items.

Status	Definition
Ordered	The order is ready for processing
Processed	The order has been processed by the bookseller
Expired	The order expired because it was not processed in a timely manner
Cancelled	The bookseller cancelled the order
Rejected	The item was rejected by the credit card processor used by AbeBooks

Purchase Order List Response (getAllNewOrders/searchOrders)

The "getAllNewOrders" request returns a list of all orders ready for processing by the bookseller. An order will not be returned by this request after it has been processed or has expired. The "searchOrders" request returns a list in the same format, containing the orders that match the search parameters.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateResponse version="1.1">
  <purchaseOrderList>
    <purchaseOrder id="1121066">
      ...
    </purchaseOrder>
    <purchaseOrder id="1121076">
      ...
    </purchaseOrder>
  </purchaseOrderList>
</orderUpdateResponse>

Empty response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateResponse version="1.1">
  <purchaseOrderList/>
</orderUpdateResponse>

Single Return Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateResponse version="1.2">
  <return id="629929538">
    <buyerCurrency>GBP</buyerCurrency>
    <buyerEmail>abcdeg@gmail.com</buyerEmail>
    <buyerRefundAmount>48.53</buyerRefundAmount>
    <buyerRefundDate>
      <date><day>9</day><month>11</month><year>2024</year></date>
      <time><hour>8</hour><minute>52</minute><second>13</second></time>
    </buyerRefundDate>
    <comments>Pages were ripped</comments>
    <initiatedDate>
      <date><day>9</day><month>11</month><year>2024</year></date>
      <time><hour>8</hour><minute>30</minute><second>13</second></time>
    </initiatedDate>
    <purchaseOrderItem id="11111111">
      <book id="1234567">
        <author/>
        <description/>
        <isbn/>
        <price>50.0</price>
        <title>Book Title</title>
        <vendorKey>ABE-1000000</vendorKey>
      </book>
      <orderDate>
        <date><day>9</day><month>11</month><year>2024</year></date>
        <time><hour>8</hour><minute>30</minute><second>13</second></time>
      </orderDate>
      <purchaseOrder id="2222222"/>
      <sellerTotal>58.5</sellerTotal>
      <status code="24">Returned/Refunded</status>
    </purchaseOrderItem>
    <returnReason code="04">Item was damaged</returnReason>
    <returnStatus code="L">Buyer refunded</returnStatus>
    <sellerBilledDate>
      <date><day>9</day><month>11</month><year>2023</year></date>
      <time><hour>10</hour><minute>55</minute><second>11</second></time>
    </sellerBilledDate>
    <shipper>MyShipper</shipper>
    <shipperTrackingCode>123456789</shipperTrackingCode>
    <returnlessRefundRule id="RR-00001"/>
  </return>
</orderUpdateResponse>

Return Response Element Reference

return id — The unique identifier for a return. Each return id is associated with a single purchaseOrderItem.
buyerCurrency — The currency the buyer was refunded in.
buyerEmail — The buyer's email.
buyerRefundAmount — The amount refunded to the buyer in buyer currency.
buyerRefundDate — The date the buyer was refunded. Can be empty if the return is still "In progress".
comments — Comments from the initiator of the return, can be from either the buyer or seller.
initiatedDate — The date the return was initiated.
purchaseOrderItem — The detail of the item being refunded. A purchaseOrderItem may appear for more than one return if a return has been cancelled and a new return is created.
returnReason — The reason why the return was made, includes both the reason code and text description.
returnStatus — The current status of the return, includes both the status code and text description.
sellerBilledDate — The date the refund charge was billed to the seller. Can be empty if the return is still "In progress".
shipper — The return shipper name provided by the buyer. Can be empty.
shipperTrackingCode — The return shipper tracking code provided by the buyer. Can be empty.
returnlessRefundRule id (v1.2+) — The Returnless Refund Rule ID of the rule that matched on this return, indicating that the buyer was told not to ship the book back and would be processed automatically. If blank, the return has gone through the regular returns process.

List of Returns Response

Used in the searchReturns response. Multiple returns inside a returnList tag, each with the same format as the single return response.

<?xml version="1.0" encoding="ISO-8859-1"?>
<orderUpdateResponse version="1.1">
  <returnList>
    <return id="1121066">
      ...
    </return>
    <return id="1121076">
      ...
    </return>
  </returnList>
</orderUpdateResponse>