OverDrive Developers

Checkouts API

The Checkouts API is your path to borrowing, returning, and checking the status of titles. To use the checkouts endpoint, be sure to send the proper access token for your patron in the "Authorization" header. To get a patron's OAuth access token, you must first authenticate the user using patron authentication.

Note: The examples below show our production API URL. If you're using our integration environment, use https://integration-patron.api.overdrive.com. For more information on the integration environment, please see Getting Started.

Using the Checkouts API

Using POST, GET, and DELETE requests, you can use the Checkouts API to do the following:

Available endpoint actions

  • GET patron checkouts: This request returns a current list of the user's borrowed titles or finds a specific title they've borrowed.
  • Check out (borrow) a title: POST to this endpoint to borrow a title on the user's behalf.
  • Fulfill a checked out title (GET): This request redirects the user to an interface where they can choose a format and open a borrowed title.
  • Return a title: This DELETE request allows you to return a title on behalf of a user.

GET a list of a patron's checkouts

Below is the example GET request sent to the /v1/patrons/me/checkouts endpoint.

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com

The response includes a list of titles that the authenticated user currently has checked out from their library.

200 OK
Pragma: no-cache
X-Frame-Options: DENY
Content-Length: 1959
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Fri, 13 Aug 2021 14:41:26 GMT
Expires: -1

{
    "totalItems": 2,
    "totalCheckouts": 2,
    "checkouts": [
        {
            "reserveId": "2EEC1B6A-9C0A-4FFF-BAAB-60B3B1019E6A",
            "crossRefId": 19532,
            "expires": "2021-08-27T14:41:20Z",
            "isFormatLockedIn": false,
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/2EEC1B6A-9C0A-4FFF-BAAB-60B3B1019E6A",
                    "type": "application/vnd.overdrive.circulation.api+json"
                },
                "metadata": {
                    "href": "https://api.overdrive.com/v1/collections/v1P2BvyQAAAImAAA1U/products/2EEC1B6A-9C0A-4FFF-BAAB-60B3B1019E6A/metadata",
                    "type": "application/vnd.overdrive.api+json"
                },
                "downloadRedirect": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/2EEC1B6A-9C0A-4FFF-BAAB-60B3B1019E6A/formats/downloadRedirect",
                    "type": "application/vnd.overdrive.circulation.api+json"
                }
            },
            "actions": {
                "earlyReturn": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/2EEC1B6A-9C0A-4FFF-BAAB-60B3B1019E6A",
                    "method": "delete"
                }
            },
            "checkoutDate": "2021-08-13T14:41:20Z"
        },
        {
            "reserveId": "E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1",
            "crossRefId": 230,
            "expires": "2021-08-24T18:43:57Z",
            "isFormatLockedIn": false,
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1",
                    "type": "application/vnd.overdrive.circulation.api+json"
                },
                "metadata": {
                    "href": "https://api.overdrive.com/v1/collections/v1P2BvyQAAAImAAA1U/products/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1/metadata",
                    "type": "application/vnd.overdrive.api+json"
                },
                "downloadRedirect": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1/formats/downloadRedirect",
                    "type": "application/vnd.overdrive.circulation.api+json"
                }
            },
            "actions": {
                "earlyReturn": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1",
                    "method": "delete"
                }
            },
            "checkoutDate": "2021-08-10T18:43:57Z"
        }
    ],
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts",
            "type": "application/vnd.overdrive.circulation.api+json"
        }
    }
}

Use the hypermedia links in the checkouts response to make calls to other APIs for more information on a given title (like Metadata). You can also return a book on a user's behalf (via the earlyReturn action).

To get information about a specific checkout, you can include the reserveId or crossRefId on the checkouts endpoint GET request.

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1 HTTP/1.1
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host:patron.api.overdrive.com

200 OK
Pragma: no-cache
X-Frame-Options: DENY
Content-Length: 901
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Tue, 10 Aug 2021 18:44:07 GMT
Expires: -1

{
    "reserveId": "E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1",
    "crossRefId": 230,
    "expires": "2021-08-24T18:43:57Z",
    "isFormatLockedIn": false,
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1",
            "type": "application/vnd.overdrive.circulation.api+json"
        },
        "metadata": {
            "href": "https://api.overdrive.com/v1/collections/v1P2BvyQAAAImAAA1U/products/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1/metadata",
            "type": "application/vnd.overdrive.api+json"
        },
        "downloadRedirect": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1/formats/downloadRedirect",
            "type": "application/vnd.overdrive.circulation.api+json"
        }
    },
    "actions": {
        "earlyReturn": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1",
            "method": "delete"
        }
    },
    "checkoutDate": "2021-08-10T18:43:57Z"
}

Checking out a title (POST)

You can borrow a title on a patron's behalf by sending a POST request to the checkouts endpoint. This request must include the title's reserveId or crossRefId in the request body (as a name and value pair).

Here's an example POST:

POST https://patron.api.overdrive.com/v1/patrons/me/checkouts HTTP/1.1
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Content-Type: application/json; charset=utf-8
Host: patron.api.overdrive.com
Content-Length: 138
Expect: 100-continue

{
    "fields": [
        {
            "name": "id",
            "value": "E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1"
        }
    ]
}

A successful response looks like this:

201 Created
Pragma: no-cache
X-Frame-Options: DENY
Content-Length: 881
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Tue, 10 Aug 2021 18:43:57 GMT
Expires: -1
Location: https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1

{
    "reserveId": "E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1",
    "crossRefId": 230,
    "expires": "2021-08-24T18:43:57Z",
    "isFormatLockedIn": false,
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1",
            "type": "application/vnd.overdrive.circulation.api+json"
        },
        "metadata": {
            "href": "https://api.overdrive.com/v1/collections/v1P2BvyQAAAImAAA1U/products/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1/metadata",
            "type": "application/vnd.overdrive.api+json"
        },
        "downloadRedirect": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1/formats/downloadRedirect",
            "type": "application/vnd.overdrive.circulation.api+json"
        }
    },
    "actions": {
        "earlyReturn": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/E96BA937-CB3E-4B8F-B2E7-51A8B43C10D1",
            "method": "delete"
        }
    },
    "checkoutDate": "2021-08-10T18:43:57Z"
}

Fulfilling a checked out title (GET)

The downloadRedirect link (available in the GET and POST checkout responses) points to the OverDrive fulfillment interface, where your user can select a format for the title, open it, and download any required software.

Note: When designing buttons/links in your user interface for the downloadRedirect link, we recommend using more neutral language like "Get book" (instead of "Download"), since the user needs to select an option in the fulfillment interface before download.

Here's an example GET request for the downloadRedirect endpoint:

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/229991A9-E9E0-42D3-A106-2F016941CD69/formats/downloadredirect HTTP/1.1
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com

A successful request will return a "302 Redirect" response:

302 Redirect
Cache-Control: no-cache
Pragma: no-cache
Location: https://{site}.overdrive.com/fulfillment/229991A9-E9E0-42D3-A106-2F016941CD69?code=2fb88da1ab0a872c0d5affb7afc09bb1b34b6d932cd5a067e443d7a36380ed96&client={client}
X-Frame-Options: DENY
Date: Wed, 04 Aug 2021 12:50:24 GMT
Expires: -1
Content-Length: 0

The fulfillment interface's UI is provided by OverDrive, but you can choose how it's displayed: as a new browser window, as a new tab, or in an iframe.

If using an iframe:

  • Make sure scrolling is enabled, so all content and options appear.
  • Note that users may be prompted to refresh the page if something goes wrong.

Format options and software requirements vary by title, by type of content (ebooks, audiobooks, etc.), and by type of library (public, school, law, etc.).

Returning a title (DELETE)

Titles are automatically returned once their lending period expires, but you can return a book on a user's behalf before then by making a DELETE request to the checkouts endpoint.

Here's a sample DELETE request to return a title:

DELETE https://patron.api.overdrive.com/v1/patrons/me/checkouts/08F7D7E6-423F-45A6-9A1E-5AE9122C82E7
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com

The response will show a "204 NoContent" message when the return has been completed successfully.

204 NoContent
Pragma: no-cache
X-Frame-Options: deny
Cache-Control: no-cache
Date: Tue, 24 Sep 2013 00:52:17 GMT
Expires: -1

Note that if a user has selected the ebook-kindle format for a title and wants to return it early, they must go through Amazon. You'll get a 400 BadRequest error if a Kindle Book is returned via the checkouts endpoint.

400 BadRequest
Date: Tue, 12 Nov 2024 20:13:36 GMT
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 177
Content-Type: application/json; charset=utf-8

{
    "errorCode": "CannotEarlyReturnWhenFulfilledOnKindle",
    "message": "This loan was sent to Kindle so it must be returned via Amazon.",
    "token": "a3df449f-3cec-41b0-9d8c-a24f0491bbd1"
}

Copyright © 2014 OverDrive, Inc. All rights reserved.