Purchase API - Available endpoints
Available Endpoints
Base URL: purchase.api.abebooks.com/v1, Version: 1
Schemes: https
Summary
| Path | Operation |
| /orders | GET |
| POST | |
| /orders/{orderId} | GET |
Paths
Description
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.
| Name | Description | Data type |
| dateStart | Returns orders created after the given datetime. Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58Z". Max range between dateStart and dateEnd is 90 days, this will default to 90 days before dateEnd, or 90 days before the current time if dateEnd is not provided. | string |
| dateEnd | Returns orders created before the given datetime. Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58Z". Max range between dateStart and dateEnd is 90 days, this will default to 90 days after dateStart. | string |
| itemUpdateDateStart | Returns orders containing items that have been updated after the given datetime. Only items matching the provided search criteria will be returned in the response. Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58Z" | string |
| itemUpdateDateEnd | Returns orders containing items that have been updated before the given datetime. Only items matching the provided search criteria will be returned in the response. Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58Z" | string |
| vendorId | Returns orders fulfilled by the vendorId provided | string |
| referenceId | Returns orders with the referenceId provided | string |
| orderId | Returns orders for the AbeBooks orderIds provided. Multiple values can be supplied by repeating the url parameter. For example, "orderId=1234&orderId=5678" | string[] |
| orderItemId | Returns orders containing the items with the AbeBooks orderItemIds provided. Only items matching the provided search criteria will be returned in the response. Multiple values can be supplied by repeating the url parameter. For example, "orderItemId=1234&orderItemId=5678" | string[] |
| sortOrder | Specifies the sort order. All responses are sorted by createDate. Default value is ascending. | string , x ∈ { ascending , descending } |
| limit | Specifies the number of orders to be returned at a time. Default value is 20 and the maximum allowed is 100. | integer |
| next | Used to obtain the next page of data matching the given search criteria. Value is returned as part of the OrderSearchResponse and can be used in a subsequent request | integer |
Header Parameters
| Abe-RequestId | A unique ID generated by the user. This is used to handle duplicates and report errors. It is highly recommended to use GUIDs for this field. | string | Required |
| Abe-Access-Key | Your Purchase API access key retrieved from the Manage API Keys page. | string | Required |
| Abe-Date | The date the request is sent. Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58.260Z" | string | Required |
| Abe-Signature | See the authentication section for details on producing the request signature. | string |
Responses
200 OK
OrderResponse
4xx Error
There was some error with the request
ErrorRequest
| Header | Description | Data type |
| Abe-Status | The response status of the request. To see full list of possible response codes, see the appendix. If the request failed, there may be multiple error statuses. | string[] |
Schema definitions
Properties
shipAddr: Address
billAddr: Address
ccToken: string
The token for the credit card to use, acquired from the API Payment Methods page.
listings: object[]
RequestedListing
shippingMode: string , x ∈ { S , P }
This flag indicates whether to use Standard or Priority shipping.
domain: string , x ∈ { abebooks.com , abebooks.co.uk , abebooks.de , abebooks.fr , abebooks.it , iberlibro.com , zvab.com }
The domain is used to determine which currency is used for the transaction. (See Domain to Currency mapping.)
totalMaxPrice: number
Optional. This value is used to ensure that the order total (all items, shipping, and tax) is not higher than expected. Setting a totalMaxPrice will ensure that the order will not be purchased if the combined cost of the order exceeds the value listed here. The currency used is based on the domain. (See Domain to Currency mapping.)
dryrun: boolean
If true, the the details of the request are verified and the response is returned containing the expected status of the order to be placed. Note that all order IDs will be 0 because no order was actually created.
referenceId: string
Optional. You may use this field to add a custom ID that can be used to lookup your order. Restricted to alphanumeric characters, hyphen (-), and underscore (_).
shipAddr: Address
billAddr: Address
ccToken: string
The token for the credit card to use, acquired from the API Payment Methods page.
listings: object[]
RequestedListing
shippingMode: string , x ∈ { S , P }
This flag indicates whether to use Standard or Priority shipping.
domain: string , x ∈ { abebooks.com , abebooks.co.uk , abebooks.de , abebooks.fr , abebooks.it , iberlibro.com , zvab.com }
The domain is used to determine which currency is used for the transaction. (See Domain to Currency mapping.)
totalMaxPrice: number
Optional. This value is used to ensure that the order total (all items, shipping, and tax) is not higher than expected. Setting a totalMaxPrice will ensure that the order will not be purchased if the combined cost of the order exceeds the value listed here. The currency used is based on the domain. (See Domain to Currency mapping.)
dryrun: boolean
If true, the the details of the request are verified and the response is returned containing the expected status of the order to be placed. Note that all order IDs will be 0 because no order was actually created.
referenceId: string
Optional. You may use this field to add a custom ID that can be used to lookup your order. Restricted to alphanumeric characters, hyphen (-), and underscore (_).
OrderRequest: object
Example
{
"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
}RequestedListing: object
listingId: integer
The listing identifier. Also referred to as "BookID" in Search Web Services.
quantity: integer
maxPrice: number
Optional. This value is used to ensure that the price is not higher than expected. In very rare cases, after the price is queried, a seller could update the price of their listing, resulting in a listing being purchased at a higher price than expected. Setting a maxPrice will ensure that the listing will not be purchased if its the combined cost of the item and first item shipping exceeds the value listed here. The currency used is based on the domain. (See Domain to Currency mapping.)
listingId: integer
The listing identifier. Also referred to as "BookID" in Search Web Services.
quantity: integer
maxPrice: number
Optional. This value is used to ensure that the price is not higher than expected. In very rare cases, after the price is queried, a seller could update the price of their listing, resulting in a listing being purchased at a higher price than expected. Setting a maxPrice will ensure that the listing will not be purchased if its the combined cost of the item and first item shipping exceeds the value listed here. The currency used is based on the domain. (See Domain to Currency mapping.)
Address: object
name: string
address1: string
address2: string
Optional
city: string
provstate: string
Optional. The two or three digit ISO_3166-2 code for the destination province or state.
country: string
The ISO-3 code for the destination country.
zipcode: string
phone: string
name: string
address1: string
address2: string
Optional
city: string
provstate: string
Optional. The two or three digit ISO_3166-2 code for the destination province or state.
country: string
The ISO-3 code for the destination country.
zipcode: string
phone: string
OrderResponse: object
Example
{
"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"
}Properties
orderId: integer
This is the ID used to query for order status. Will be 0 for dryrun requests.
createDate: string
The datetime that the order was created. Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58Z"
currency: string
All values will be displayed in this currency, corresponds to the domain passed based on Domain to Currency mapping.
listings: object[]
ITEMS
ListingSummary
dryrun: boolean
tax: number
This is the tax amount for the entire order. Optionally returned when the value is non-null.
taxModel: string
Describes the type of tax that applies to the order. Optionally returned when the value is non-null.
referenceId: string
The referenceId passed with the original order.
orderId: integer
This is the ID used to query for order status. Will be 0 for dryrun requests.
createDate: string
The datetime that the order was created. Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58Z"
currency: string
All values will be displayed in this currency, corresponds to the domain passed based on Domain to Currency mapping.
listings: object[]
ITEMS
ListingSummary
dryrun: boolean
tax: number
This is the tax amount for the entire order. Optionally returned when the value is non-null.
taxModel: string
Describes the type of tax that applies to the order. Optionally returned when the value is non-null.
referenceId: string
The referenceId passed with the original order.
OrderItemSummary: object
Properties
cost: number
shipcost: number
Shipping costs are divided between the total number of items in an order.
status: integer
See Order Status Descriptions.
itemUpdateDate: string
The datetime that the item was updated. Field is not returned on order creation (refer to createDate). Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58Z"
orderItemId: integer
Properties
cost: number
shipcost: number
Shipping costs are divided between the total number of items in an order.
status: integer
See Order Status Descriptions.
itemUpdateDate: string
The datetime that the item was updated. Field is not returned on order creation (refer to createDate). Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58Z"
orderItemId: integer
ListingSummary: object
Properties
listingId: integer
title: string
isbn: string
quantity: integer
vendorId: integer
shippingCompany: string
Optionally returned when value is non-null.
shippingTrackingId: string
Optionally returned when value is non-null.
minShippingDays: integer
maxShippingDays: integer
orderItems: object[]
ITEMS
OrderItemSummary
Properties
listingId: integer
title: string
isbn: string
quantity: integer
vendorId: integer
shippingCompany: string
Optionally returned when value is non-null.
shippingTrackingId: string
Optionally returned when value is non-null.
minShippingDays: integer
maxShippingDays: integer
orderItems: object[]
ITEMS
OrderItemSummary
OrderSearchResponse: object
Example
{
"metadata": {
"next": 87324198,
"orderResponseSize": 3
},
"orders": [
"..."
]
}Properties
orders: object[]
ITEMS
OrderResponse
metadata: object
PROPERTIES
orderResponseSize: integer
The number of orders returned in the response.
next: string
Indicates that more orders are available matching the given search criteria. To be used in the "next" field of a subsequent API call with the same search criteria. If absent, indicates that all matching orders have been returned.
ErrorResponse: object
Example
{
"messages": [
"Sample message",
"Invalid listingId passed"
],
"requestId": "62FBB727-DB8E-4D56-93F9-17227967206C"
}Properties
requestID: string
messages: string[]
ITEMS
string