Purchase API - Available endpoints



Available Endpoints

Base URL: purchase.api.abebooks.com/v1, Version: 1

Schemes: https

Summary

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

NameDescriptionData type
dateStartReturns 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
dateEndReturns 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
itemUpdateDateStartReturns 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
itemUpdateDateEndReturns 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
vendorIdReturns orders fulfilled by the vendorId providedstring
referenceIdReturns orders with the referenceId providedstring
orderIdReturns orders for the AbeBooks orderIds provided. Multiple values can be supplied by repeating the url parameter. For example, "orderId=1234&orderId=5678"string[]
orderItemIdReturns 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[]
sortOrderSpecifies the sort order. All responses are sorted by createDate. Default value is ascending.string , x ∈ { ascending , descending }
limitSpecifies the number of orders to be returned at a time. Default value is 20 and the maximum allowed is 100.integer
nextUsed 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 requestinteger

Header Parameters

Abe-RequestIdA 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.stringRequired
Abe-Access-KeyYour Purchase API access key retrieved from the Manage API Keys page.stringRequired
Abe-DateThe date the request is sent. Formatted in UTC according to the ISO 8601 datetime standard. For example, "2017-06-26T19:54:58.260Z"stringRequired
Abe-SignatureSee 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

HeaderDescriptionData type
Abe-StatusThe 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 (_).

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

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

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.
OrderItemSummary: object

Properties

cost: number

shipcost: number

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

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