Endpoints

Path	Operation
/orders	GET
/orders	POST
/orders/{orderId}	GET

Required Headers

All requests require the following headers:

Header	Type	Required	Description
Abe-RequestId	string	Yes	A unique ID generated by the user. Used to handle duplicates and report errors. It is highly recommended to use GUIDs.
Abe-Access-Key	string	Yes	Your Purchase API access key retrieved from the Manage API Keys page.
Abe-Date	string	Yes	The date the request is sent. Formatted in UTC according to ISO 8601, e.g., "2017-06-26T19:54:58.260Z"
Abe-Signature	string	Yes	See the authentication section for details on producing the request signature.

GET /orders

Search your order history by given search criteria. One or more of the following query parameters can be provided to filter results.

Note: if searching by item-specific criteria, only order items matching the given search criteria will be included in the response.

Query Parameters

Name	Type	Description
dateStart	string	Returns orders created after the given datetime. Formatted in UTC per ISO 8601, e.g., "2017-06-26T19:54:58Z". Max range between dateStart and dateEnd is 90 days. Defaults to 90 days before dateEnd, or 90 days before the current time if dateEnd is not provided.
dateEnd	string	Returns orders created before the given datetime. Formatted in UTC per ISO 8601. Max range is 90 days. Defaults to 90 days after dateStart.
itemUpdateDateStart	string	Returns orders containing items updated after the given datetime. Only matching items will be returned in the response.
itemUpdateDateEnd	string	Returns orders containing items updated before the given datetime. Only matching items will be returned in the response.
vendorId	string	Returns orders fulfilled by the vendorId provided.
referenceId	string	Returns orders with the referenceId provided.
orderId	string[]	Returns orders for the AbeBooks orderIds provided. Multiple values can be supplied by repeating the parameter, e.g., "orderId=1234&orderId=5678".
orderItemId	string[]	Returns orders containing items with the AbeBooks orderItemIds provided. Only matching items will be returned. Multiple values via repeated parameter.
sortOrder	string	Specifies the sort order. All responses are sorted by createDate. Values: `ascending` (default), `descending`.
limit	integer	Number of orders to return at a time. Default is 20, maximum is 100.
next	integer	Used to obtain the next page of data. Value is returned as part of the OrderSearchResponse.

Response

200 OK — Returns an OrderSearchResponse.

4xx Error — Returns an ErrorResponse. The Abe-Status response header contains one or more status codes (see errors).

POST /orders

Place a new order.

Request Body — OrderRequest

{
  "billAddr": {
    "address1": "6666 Road Rd",
    "address2": null,
    "city": "Los Angeles",
    "country": "USA",
    "name": "Smith Smitherson",
    "phone": "(800) 555-4242",
    "provstate": "CA",
    "zipcode": "12345"
  },
  "ccToken": "A13705A2-D1EA-4220-8C28-6CFAKETOKEN",
  "domain": "abebooks.com",
  "dryrun": false,
  "listings": [
    {
      "listingId": 1009999999,
      "maxPrice": 45.11,
      "quantity": 2
    }
  ],
  "referenceId": "5D8CF1E1-EB94-40D2-934D-718058F18D4C",
  "shipAddr": {
    "address1": "5555 Street St",
    "address2": null,
    "city": "Victoria",
    "country": "Canada",
    "name": "Joe McJoeburt",
    "phone": "(888) 555-1234",
    "provstate": "BC",
    "zipcode": "V8V8V8"
  },
  "shippingMode": "S",
  "totalMaxPrice": 99.25
}

OrderRequest Fields

Field	Type	Required	Description
shipAddr	Address	Yes	Shipping address.
billAddr	Address	Yes	Billing address.
ccToken	string	Yes	The token for the credit card to use, acquired from the API Payment Methods page.
listings	RequestedListing[]	Yes	One or more listings to order.
shippingMode	string	Yes	`S` (Standard) or `P` (Priority).
domain	string	Yes	Determines which currency is used for the transaction. Values: `abebooks.com`, `abebooks.co.uk`, `abebooks.de`, `abebooks.fr`, `abebooks.it`, `iberlibro.com`, `zvab.com`. See Domain/Currency Mapping.
totalMaxPrice	number	No	If set, the order will not be purchased if the combined cost (items + shipping + tax) exceeds this value. Currency is based on the domain.
dryrun	boolean	No	If true, the request is verified and the response shows the expected status without creating an order. All order IDs will be 0.
referenceId	string	No	A custom ID that can be used to look up your order. Restricted to alphanumeric characters, hyphen (-), and underscore (_).

RequestedListing Fields

Field	Type	Required	Description
listingId	integer	Yes	The listing identifier. Also referred to as "BookID" in Search Web Services.
quantity	integer	Yes	Number of copies to order.
maxPrice	number	No	If set, the listing will not be purchased if the combined cost of the item and first item shipping exceeds this value. Currency is based on the domain.

Address Fields

Field	Type	Required	Description
name	string	Yes	Recipient name.
address1	string	Yes	Street address line 1.
address2	string	No	Street address line 2.
city	string	Yes	City.
provstate	string	No	The two or three digit ISO 3166-2 code for the destination province or state.
country	string	Yes	The ISO-3 code for the destination country.
zipcode	string	Yes	Postal/zip code.
phone	string	Yes	Phone number.

Response

200 OK — Returns an OrderResponse.

4xx Error — Returns an ErrorResponse.

GET /orders/{orderId}

Retrieve a specific order by its AbeBooks order ID.

Response

200 OK — Returns an OrderResponse.

4xx Error — Returns an ErrorResponse.

Schema Definitions

OrderResponse

{
  "createDate": "2018-01-15T10:22:00Z",
  "currency": "USD",
  "dryrun": false,
  "listings": [
    {
      "isbn": "1111111111111",
      "listingId": 12345,
      "maxShippingDays": 7,
      "minShippingDays": 5,
      "orderItems": [
        {
          "cost": 44.22,
          "itemUpdateDate": "2018-01-15T17:55:12Z",
          "orderItemId": 454567,
          "shipcost": 1.5,
          "status": 1
        },
        {
          "cost": 44.22,
          "itemUpdateDate": "2018-01-15T17:55:25Z",
          "orderItemId": 454568,
          "shipcost": 0.33,
          "status": 1
        }
      ],
      "quantity": 2,
      "shippingCompany": "USPS",
      "shippingTrackingId": "37dae8b2-0554-11e8-ba89-0ed5f89f718b",
      "title": "A Nice Book",
      "vendorId": 55555
    }
  ],
  "orderId": 1234567,
  "referenceId": "5D8CF1E1-EB94-40D2-934D-718058F18D4C",
  "tax": 8.84,
  "taxModel": "US Marketplace Facilitator"
}

Field	Type	Description
orderId	integer	The order ID used to query for status. Will be 0 for dryrun requests.
createDate	string	Datetime the order was created, in UTC ISO 8601 format.
currency	string	All values will be displayed in this currency, corresponds to the domain passed.
listings	ListingSummary[]	The listings in the order.
dryrun	boolean	Whether this was a dry run.
tax	number	Tax amount for the entire order. Optionally returned when non-null.
taxModel	string	Type of tax that applies to the order. Optionally returned when non-null.
referenceId	string	The referenceId passed with the original order.

ListingSummary

Field	Type	Description
listingId	integer	The listing identifier.
title	string	Book title.
isbn	string	ISBN.
quantity	integer	Quantity ordered.
vendorId	integer	Seller ID.
shippingCompany	string	Optionally returned when non-null.
shippingTrackingId	string	Optionally returned when non-null.
minShippingDays	integer	Minimum estimated shipping days.
maxShippingDays	integer	Maximum estimated shipping days.
orderItems	OrderItemSummary[]	Individual item details.

OrderItemSummary

Field	Type	Description
cost	number	Item cost.
shipcost	number	Shipping cost. Divided between the total number of items in an order.
status	integer	Order status code. See Order Status Descriptions.
itemUpdateDate	string	Datetime the item was last updated. Not returned on order creation (refer to createDate). UTC ISO 8601 format.
orderItemId	integer	AbeBooks order item ID.

OrderSearchResponse

{
  "metadata": {
    "next": 87324198,
    "orderResponseSize": 3
  },
  "orders": ["..."]
}

Field	Type	Description
orders	OrderResponse[]	List of orders matching the search criteria.
metadata.orderResponseSize	integer	Number of orders returned in the response.
metadata.next	integer	Indicates more orders are available. Use in the "next" parameter of a subsequent call with the same search criteria. Absent when all matching orders have been returned.

ErrorResponse

{
  "messages": [
    "Sample message",
    "Invalid listingId passed"
  ],
  "requestId": "62FBB727-DB8E-4D56-93F9-17227967206C"
}

Field	Type	Description
requestId	string	The request ID echoed back.
messages	string[]	One or more error messages.