Checkout & Checkin

View as Markdown The page’s .md file llms.txt All pages, for AI tools Open in ChatGPT Ask questions about the page Open in Claude Ask questions about the page

Lending an item to a patron and taking it back again. A checkout may complete straight away, or first need the patron to accept something such as a lending fee. Both endpoints also accept transactions carried out while the vendor was offline.

2 operations

POST /checkin/{itemId}

Check in an item

Bearer token Checkin

Check in an item.

A vendor must find circulation.checkin.isEnabled set to true in GET /configuration before using this endpoint, and circulation.checkin.offline.isAllowed set to true before sending checkin.offline.

This endpoint always answers 200 when the request was understood. Whether the item was checked in is said by status in the response body, never by the HTTP status code:

completed the item was checked in, and checkin holds the result.
failed the item was not checked in, and reason says why.

An unknown itemId is a failed checkin with the reason item_not_found. It is not a 404. 404 is not used by this endpoint, so a vendor only needs one code path for a refused checkin.

On a completed checkin, permanentLocation says where the item belongs, needsStaff says whether a person has to look at it, and sortingCode carries the provider's own bin value where it has one. That is what a sorter needs to route it.

message.text is shown to the patron, so send ui_language to say which language it should be written in.

A checkin can be sent again safely. If the item is not on loan, the provider answers failed with the reason item_not_on_loan, and a vendor that is retrying may treat that as done, since the item is back either way. This is how a vendor recovers when a response is lost, and how an offline queue can be replayed more than once.

Example request

cURL

curl -X POST "$PLAS_BASE_URL/checkin/03011042557129?version=0.6.7" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $PLAS_TOKEN" \
  -d '{
  "checkin": {
    "location": {
      "branchId": "nordby-main",
      "sections": [
        {
          "id": "nordby-main-children",
          "name": "Children’s department",
          "type": "department"
        }
      ]
    },
    "offline": false,
    "returnDateTime": "2025-03-14T10:24:00+01:00"
  }
}'

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/checkin/03011042557129?version=0.6.7`, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.PLAS_TOKEN}`,
  },
  body: JSON.stringify({
    "checkin": {
      "location": {
        "branchId": "nordby-main",
        "sections": [
          {
            "id": "nordby-main-children",
            "name": "Children’s department",
            "type": "department"
          }
        ]
      },
      "offline": false,
      "returnDateTime": "2025-03-14T10:24:00+01:00"
    }
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.post(
    f"{os.environ['PLAS_BASE_URL']}/checkin/03011042557129",
    params={
        "version": "0.6.7",
    },
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['PLAS_TOKEN']}",
    },
    json={
        "checkin": {
            "location": {
                "branchId": "nordby-main",
                "sections": [
                    {
                        "id": "nordby-main-children",
                        "name": "Children’s department",
                        "type": "department",
                    },
                ],
            },
            "offline": False,
            "returnDateTime": "2025-03-14T10:24:00+01:00",
        },
    },
)
data = response.json()

The host and token are environment variables: PLAS_BASE_URL the provider’s base URL · PLAS_TOKEN an access token.

Parameters

itemIdrequired: path · string
The item identifier of the item to check in.
Example: 03011042557129

Shared across operations: ui_language, version. See the shared contract on the version page.

Request body

application/json · required · CheckinRequestBody

checkinobjectrequired
Show 3 fieldsHide 3 fields
- locationCheckOutOrInLocationWithoutNamesrequired
  Show 2 fieldsHide 2 fields
  - branchIdstringrequired
    The branch ID where the checkout or checkin was made.
  - sectionsarray of LocationSectionElementWithIdNameAndType
    This is specifying the location more precisely.
    See LocationSectionElementWithIdNameAndType in the schema index
- offlineboolean
  Set this to true when the checkin was already carried out while the vendor was offline, e.g. a self service machine in offline mode. Leave it out for a normal checkin. This only works when circulation.checkin.offline.isAllowed is true.
  The item is already back, so the provider registers the checkin rather than ruling on it. Only item_not_found and item_not_on_loan can still fail.
  If the field is missing, the default value is false.
- returnDateTimestring (date-time)required
  This is the return date and time the patron made the checkin.

Responses

200 It is important to check the returned status field, to distinguish between a completed checkin and a failure. CheckinResponseBody

Generated from the schema

Example

{
  "message": {
    "text": "This item is reserved by another patron. Please return it to the counter.",
    "type": "reservation-waiting"
  },
  "requestId": "5b1f6c2e-9a7d-4e3b-8f21-6c0d9e4a7b13",
  "status": "completed",
  "checkin": {
    "acquiredFrom": {
      "type": "local_circulation"
    },
    "dueDate": "2025-04-11",
    "fees": [
      {
        "amount": 15000,
        "createdTime": "2025-03-14T10:24:00+01:00",
        "currency": "NOK",
        "dueDate": "2025-04-11",
        "id": "94549",
        "items": [
          {
            "acquiredFrom": {
              "type": "local_circulation"
            },
            "itemId": "03011042557129",
            "publicationMetadata": {
              "additionalIdentifiers": [
                {
                  "digits": "10",
                  "type": "isbn",
                  "value": "9788203363344"
                }
              ],
              "binding": {
                "type": "literal",
                "value": "Hardback"
              },
              "contributors": [
                {
                  "agent": {
                    "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
                    "fullName": "Sigrid Undset",
                    "id": "agent-4102",
                    "images": [
                      {
                        "height": 1200,
                        "mime": "png",
                        "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                        "width": 800,
                        "type": "agent"
                      }
                    ],
                    "active": {
                      "type": "literal",
                      "value": "1882-1949"
                    },
                    "birthDate": {
                      "type": "literal",
                      "value": "1920"
                    },
                    "deathDate": {
                      "type": "literal",
                      "value": "1920"
                    },
                    "externals": {
                      "identifiers": [
                        {
                          "type": "norwegianAuthorityFile",
                          "value": "4102"
                        }
                      ]
                    },
                    "givenName": "Kari",
                    "surname": "Nordmann",
                    "type": "person"
                  },
                  "roles": [
                    {
                      "roleCode": "aut",
                      "type": "marcRelator"
                    }
                  ]
                }
              ],
              "creators": [
                {
                  "agent": {
                    "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
                    "fullName": "Sigrid Undset",
                    "id": "agent-4102",
                    "images": [
                      {
                        "height": 1200,
                        "mime": "png",
                        "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                        "width": 800,
                        "type": "agent"
                      }
                    ],
                    "active": {
                      "type": "literal",
                      "value": "1882-1949"
                    },
                    "birthDate": {
                      "type": "literal",
                      "value": "1920"
                    },
                    "deathDate": {
                      "type": "literal",
                      "value": "1920"
                    },
                    "externals": {
                      "identifiers": [
                        {
                          "type": "norwegianAuthorityFile",
                          "value": "4102"
                        }
                      ]
                    },
                    "givenName": "Kari",
                    "surname": "Nordmann",
                    "type": "person"
                  },
                  "roles": [
                    {
                      "roleCode": "aut",
                      "type": "marcRelator"
                    }
                  ]
                }
              ],
              "edition": {
                "type": "literal",
                "value": "2nd edition"
              },
              "extent": [
                {
                  "type": "literal",
                  "value": "312 pages"
                }
              ],
              "identifier": "310552",
              "images": [
                {
                  "height": 1200,
                  "mime": "png",
                  "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                  "width": 800,
                  "type": "frontCover"
                }
              ],
              "language": [
                {
                  "code": "SplxlOBeZQQYbYS6WxSbIA",
                  "name": "Kari Nordmann"
                }
              ],
              "mediaTypes": [
                {
                  "code": "book",
                  "name": "Kari Nordmann"
                }
              ],
              "publicationDate": {
                "type": "literal",
                "value": "1920"
              },
              "publishers": [
                {
                  "places": [
                    {
                      "place": "Oslo"
                    }
                  ],
                  "publisher": {
                    "id": "94549",
                    "name": "Kari Nordmann"
                  }
                }
              ],
              "titles": [
                {
                  "language": {
                    "code": "SplxlOBeZQQYbYS6WxSbIA",
                    "name": "Kari Nordmann"
                  },
                  "main": "Kristin Lavransdatter",
                  "part": {
                    "name": "Kari Nordmann",
                    "number": "1"
                  },
                  "remainder": "The Wreath",
                  "type": "preferred"
                }
              ],
              "works": [
                {
                  "identifier": "882107",
                  "relation": "contains"
                }
              ]
            }
          }
        ],
        "payableState": "payable",
        "remainingAmount": 1,
        "type": "fee"
      }
    ],
    "itemId": "03011042557129",
    "loanId": "58210447",
    "needsStaff": false,
    "patronId": "40218873",
    "permanentLocation": {
      "branchId": "nordby-main",
      "sections": [
        {
          "id": "nordby-main-children",
          "name": "Children’s department",
          "type": "department"
        }
      ]
    },
    "publicationId": "310552",
    "publicationMetadata": {
      "additionalIdentifiers": [
        {
          "digits": "10",
          "type": "isbn",
          "value": "9788203363344"
        }
      ],
      "binding": {
        "type": "literal",
        "value": "Hardback"
      },
      "contributors": [
        {
          "agent": {
            "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
            "fullName": "Sigrid Undset",
            "id": "agent-4102",
            "images": [
              {
                "height": 1200,
                "mime": "png",
                "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                "width": 800,
                "type": "agent"
              }
            ],
            "active": {
              "type": "literal",
              "value": "1882-1949"
            },
            "birthDate": {
              "type": "literal",
              "value": "1920"
            },
            "deathDate": {
              "type": "literal",
              "value": "1920"
            },
            "externals": {
              "identifiers": [
                {
                  "type": "norwegianAuthorityFile",
                  "value": "4102"
                }
              ]
            },
            "givenName": "Kari",
            "surname": "Nordmann",
            "type": "person"
          },
          "roles": [
            {
              "roleCode": "aut",
              "type": "marcRelator"
            }
          ]
        }
      ],
      "creators": [
        {
          "agent": {
            "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
            "fullName": "Sigrid Undset",
            "id": "agent-4102",
            "images": [
              {
                "height": 1200,
                "mime": "png",
                "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                "width": 800,
                "type": "agent"
              }
            ],
            "active": {
              "type": "literal",
              "value": "1882-1949"
            },
            "birthDate": {
              "type": "literal",
              "value": "1920"
            },
            "deathDate": {
              "type": "literal",
              "value": "1920"
            },
            "externals": {
              "identifiers": [
                {
                  "type": "norwegianAuthorityFile",
                  "value": "4102"
                }
              ]
            },
            "givenName": "Kari",
            "surname": "Nordmann",
            "type": "person"
          },
          "roles": [
            {
              "roleCode": "aut",
              "type": "marcRelator"
            }
          ]
        }
      ],
      "edition": {
        "type": "literal",
        "value": "2nd edition"
      },
      "extent": [
        {
          "type": "literal",
          "value": "312 pages"
        }
      ],
      "identifier": "310552",
      "images": [
        {
          "height": 1200,
          "mime": "png",
          "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
          "width": 800,
          "type": "frontCover"
        }
      ],
      "language": [
        {
          "code": "SplxlOBeZQQYbYS6WxSbIA",
          "name": "Kari Nordmann"
        }
      ],
      "mediaTypes": [
        {
          "code": "book",
          "name": "Kari Nordmann"
        }
      ],
      "publicationDate": {
        "type": "literal",
        "value": "1920"
      },
      "publishers": [
        {
          "places": [
            {
              "place": "Oslo"
            }
          ],
          "publisher": {
            "id": "94549",
            "name": "Kari Nordmann"
          }
        }
      ],
      "titles": [
        {
          "language": {
            "code": "SplxlOBeZQQYbYS6WxSbIA",
            "name": "Kari Nordmann"
          },
          "main": "Kristin Lavransdatter",
          "part": {
            "name": "Kari Nordmann",
            "number": "1"
          },
          "remainder": "The Wreath",
          "type": "preferred"
        }
      ],
      "works": [
        {
          "identifier": "882107",
          "relation": "contains"
        }
      ]
    },
    "sortingCode": "A3",
    "transactionDateTime": "2025-03-14T10:24:00+01:00"
  }
}

Schema

CheckinResponseBody

Selected by the field status

Variant: completed

CheckinCompleted

messageCheckOutOrInMessage
Show 2 fieldsHide 2 fields
- textstring
  Message to the patron.
- typestring
  This can be used instead of the text field to identify the message type.
  This can be used by a vendor to handle the message or control the content of the message.
  PLAS defines no values for this field, they are agreed between a provider and the vendors integrating with it. A vendor that does not recognise a value should fall back to text.
requestIdstringrequired
This is a unique identifier for the checkin request. This will change for each request.
It is meant for correlating logs.
statusstringrequired
This tells that the checkin went well and was completed.
One of: completed
checkinCheckinFieldrequired
Show 12 fieldsHide 12 fields
- acquiredFromPatronLoanAcquiredFrom
  This tells from where (the material for) this loan was acquired.
  If this field are missing, the default value local_circulation should be assumed.
  - local_circulation: Meaning that this loan was acquired from the customers own inventory.
  - interlibrary_loan: Meaning that this loan was acquired as a interlibrary loan.
  - unknown: Meaning that this information is unknown.
  See PatronLoanAcquiredFrom in the schema index
- dueDatestring (date)
  This is the due date of the checkin item, meaning the date where item should (at the latest) be returned.
- feesarray of PatronFee
  The fees the library registered on the patron as part of this checkin, e.g. an overdue fine created because the item came back after dueDate. Send an empty array when the checkin created no fee. Leave the field out only when the provider cannot tell whether a fee was created, e.g. when fines are calculated later by a separate process.
  See PatronFee in the schema index
- itemIdstringrequired
  This is the item ID of the checked in item.
- loanIdstringrequired
  This is the loan ID.
- needsStaffboolean
  True when a person has to look at this item, e.g. it is damaged, or it is not the item the provider expected.
  Do not set it for a reservation or for an item that belongs to another branch. Those are about where the item goes, not about something being wrong with it.
  If the field is missing, the default is false.
- patronIdstring
  The patron who had the item on loan. Leave the field out when the provider does not disclose it, or when the loan was not to a patron, e.g. an interlibrary loan.
- permanentLocationCheckinPermanentLocation
  The location where the item is normally kept. A sorter uses it to route the item after a checkin: an item whose permanent location is another branch goes to that branch.
  See CheckinPermanentLocation in the schema index
- publicationIdstringrequired
  This is the publication ID of the checkin item. A vendor needs it to show or print a title.
- publicationMetadataPublicationFallback
  This metadata is only intended as fallback data, for when the provider is not able to serve the metadata through the GET /publication endpoint.
  This can for some provider be the case when working with e.g. interlibrary loans.
  See PublicationFallback in the schema index
- sortingCodestring
  This is the sorting code, and can be used to sort checked in items, on e.g. a self service machine by reserved and not-reserved items.
  PLAS defines no values for this field, they are agreed between a provider and the vendors integrating with it. It is for providers whose sorters already run on a code of their own.
  A provider that also serves SIP2 can put the same value here that it puts in sort bin (CL). It is the same idea: a bin value that the library, the provider and the sorter supplier agree on between them.
- transactionDateTimestring (date-time)required
  This is the registered time and date of the checkin.

Variant: failed

CheckinFailed

messageCheckOutOrInMessage
Show 2 fieldsHide 2 fields
- textstring
  Message to the patron.
- typestring
  This can be used instead of the text field to identify the message type.
  This can be used by a vendor to handle the message or control the content of the message.
  PLAS defines no values for this field, they are agreed between a provider and the vendors integrating with it. A vendor that does not recognise a value should fall back to text.
requestIdstringrequired
This is a unique identifier for the checkin request. This will change for each request.
It is meant for correlating logs.
statusstringrequired
This tells that the checkin failed, and the item was not checked in.
One of: failed
reasonCheckinFailureReasonrequired
Why the item was not checked in.
This is an open enum, so values other than the known ones are allowed. A vendor that does not know a value should treat it as unknown and show message to the patron.
One of: item_not_found · item_not_on_loan · item_belongs_to_other_library · unknown
Show 2 variantsHide 2 variants
Variant: CheckinFailureReasonEnum
CheckinFailureReasonEnum
Variant: CheckinFailureReasonLiteral
CheckinFailureReasonLiteral

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
The first error should always be the most relevant.
Show 2 fieldsHide 2 fields
- codeintegerrequired
  A number representing the type of error.
  List of error codes:
  - \<error code\>: \<error description\>
  - 500: System error
  - 600: Unsupported Open Library API version
  - 10001: Endpoint disabled
  - 71001: Consent has not been given for 'loan history'
  - 100001: Wrong patron identifier, password or pin code
  - 100011: New password or pin code rejected, because it does not meet the provider's requirements
  - 100013: The provider does not let the patron change the given credential
  - 100023: Patron ID not found
  - 100101: Patron could not be deleted, because the patron has something unresolved issue with the library (this could be anything from a loan to a fee, and so on ...)
  - 100211: maxNumberOfEmailAddresses exceeded
  - 100215: maxNumberOfPhoneNumbers exceeded
  - 100221: Pickup location cannot contain sections
  - 100411: Updating patron consent failed
  - 100611: Updating patron notification settings failed
  - 101001: Reservation ID not found
  - 101047: Branch ID cannot be used as pick up branch
  - 101053: Section ID cannot be used as pick up branch
  - 102001: Loan ID not found
  - 102301: Loan not renewable, because it is an interlibrary loan
  - 102311: Loan not renewable, because it is reserved
  - 110001: Branch ID not found
  - 200001: Publication ID not found
  - 200077: ui language not supported
  - 200101: missing required query parameter
  - 200103: invalid/unsupported query parameter value
  - 300001: Initialize payment should not be used
  - 300005: Initialize payment should be used
  - 300009: Payment method not supported
  - 300013: Payment method does not support partial payment
  - 300301: Finalized payment can not de changed
  - 300311: FinalizePaymentRequest.fees contains fees with the same ID
  - 310001: Loan history ID not found
  - 310011: Loan history ID already exists
  - 330001: List ID not found
  - 330011: List ID already exists
  - 330101: List item ID not found
  - 330111: List item ID already exists
  One of: 500 · 600 · 10001 · 71001 · 100001 · 100011 · 100013 · 100023 · 100101 · 100211 · 100215 · 100221 · 100411 · 100611 · 101001 · 101047 · 101053 · 102001 · 102301 · 102311 · 110001 · 200001 · 200077 · 200101 · 200103 · 300001 · 300005 · 300009 · 300013 · 300301 · 300311 · 310001 · 310011 · 330001 · 330011 · 330101 · 330111
- infostringrequired
  Starts with the text matching the error code field (defined above), and a describing text could be added.

401 Bearer token invalid, missing, or expired.

Shared response, defined once for the whole API. See the shared contract on the version page.

No response body.

429 Too many requests. The provider is rate limiting and did not carry out the request.

The response should have a Retry-After header saying how many seconds to wait. Show the patron "try again later", not an error about what they sent.

Shared response, defined once for the whole API. See the shared contract on the version page.

Headers: Retry-After integer
Seconds to wait before sending the request again.

No response body.

POST /checkout/{itemId}

Check out an item

Bearer token Checkout

Check out an item to a patron.

A vendor must find circulation.checkout.isEnabled set to true in GET /configuration before using this endpoint, and circulation.checkout.offline.isAllowed set to true before sending checkout.offline.

This endpoint always answers 200 when the request was understood. Whether the item was checked out is said by status in the response body, never by the HTTP status code:

completed the item was checked out, and checkout holds the resulting loan.
needs_acknowledgement the item was not checked out. The patron must accept what acknowledgement describes, and the same checkout must then be sent again carrying acknowledgement.code.
failed the item was not checked out, and reason says why.

An unknown itemId or an unknown patronId is a failed checkout with the reason item_not_found or patron_not_found. It is not a 404. 404 is not used by this endpoint, so a vendor only needs one code path for a refused checkout.

A patron sent as an identifier rather than a patronId is different: everything that goes wrong while identifying them is patron_authentication_failed, in the same time and with the same rate limiting whether the identifier is real or not, so that nobody can use this endpoint to find out which card numbers belong to real patrons.

checkout.patron identifies the patron either by patronId from a successful authentication, or by the same identifier and optional password that POST /patron/authentication and POST /patron/authentication/no-password take. A vendor replaying an offline checkout has to use the second form: a patron ID is only obtained by authenticating against the provider, which is what it could not do while it was offline.

message.text and the message entries in acknowledgement.conditions are shown to the patron, so send ui_language to say which language they should be written in.

A checkout can be sent again safely. If the item is already on loan to this patron, the provider answers completed with that loan instead of lending it a second time. This check comes before the acknowledgement code is looked at, so it also covers a lost answer to the acknowledging request. It is how a vendor recovers when a response is lost, and how an offline queue can be replayed more than once.

Example request

cURL

curl -X POST "$PLAS_BASE_URL/checkout/03011042557129?version=0.6.7" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $PLAS_TOKEN" \
  -d '{
  "acknowledgement": {
    "code": "SplxlOBeZQQYbYS6WxSbIA"
  },
  "checkout": {
    "location": {
      "branchId": "nordby-main",
      "sections": [
        {
          "id": "nordby-main-children",
          "name": "Children’s department",
          "type": "department"
        }
      ]
    },
    "offline": {
      "dueDate": "2025-04-11"
    },
    "patron": {
      "identifiedBy": "patron_id",
      "patronId": "40218873"
    },
    "transactionDateTime": "2025-03-14T10:24:00+01:00"
  }
}'

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/checkout/03011042557129?version=0.6.7`, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.PLAS_TOKEN}`,
  },
  body: JSON.stringify({
    "acknowledgement": {
      "code": "SplxlOBeZQQYbYS6WxSbIA"
    },
    "checkout": {
      "location": {
        "branchId": "nordby-main",
        "sections": [
          {
            "id": "nordby-main-children",
            "name": "Children’s department",
            "type": "department"
          }
        ]
      },
      "offline": {
        "dueDate": "2025-04-11"
      },
      "patron": {
        "identifiedBy": "patron_id",
        "patronId": "40218873"
      },
      "transactionDateTime": "2025-03-14T10:24:00+01:00"
    }
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.post(
    f"{os.environ['PLAS_BASE_URL']}/checkout/03011042557129",
    params={
        "version": "0.6.7",
    },
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['PLAS_TOKEN']}",
    },
    json={
        "acknowledgement": {
            "code": "SplxlOBeZQQYbYS6WxSbIA",
        },
        "checkout": {
            "location": {
                "branchId": "nordby-main",
                "sections": [
                    {
                        "id": "nordby-main-children",
                        "name": "Children’s department",
                        "type": "department",
                    },
                ],
            },
            "offline": {
                "dueDate": "2025-04-11",
            },
            "patron": {
                "identifiedBy": "patron_id",
                "patronId": "40218873",
            },
            "transactionDateTime": "2025-03-14T10:24:00+01:00",
        },
    },
)
data = response.json()

The host and token are environment variables: PLAS_BASE_URL the provider’s base URL · PLAS_TOKEN an access token.

Parameters

itemIdrequired: path · string
The item identifier of the item to check out.
Example: 03011042557129

Shared across operations: ui_language, version. See the shared contract on the version page.

Request body

application/json · required · CheckoutRequestBody

acknowledgementobject
This is used to acknowledge the checkout, see CheckoutNeedsAcknowledgement.
Send checkout exactly as it was in the request that returned the code, transactionDateTime included. The code belongs to that exact checkout. If anything in checkout is different, the provider answers failed with the reason acknowledgement_rejected.
Show 1 fieldHide 1 field
- codestringrequired
  This should be the acknowledgement code from the needs_acknowledgement response.
checkoutobjectrequired
Show 4 fieldsHide 4 fields
- locationCheckOutOrInLocationWithoutNamesrequired
  Show 2 fieldsHide 2 fields
  - branchIdstringrequired
    The branch ID where the checkout or checkin was made.
  - sectionsarray of LocationSectionElementWithIdNameAndType
    This is specifying the location more precisely.
    See LocationSectionElementWithIdNameAndType in the schema index
- offlineobject
  Set this when the checkout was already carried out while the vendor was offline, e.g. a self service machine in offline mode. Leave it out for a normal checkout. This only works when circulation.checkout.offline.isAllowed is true.
  The item has already left the building, so the provider registers the checkout rather than ruling on it. Only an identity that cannot be resolved can still fail, meaning item_not_found, patron_not_found or patron_authentication_failed.
  A vendor that was offline has no patron ID, so identify the patron by identifier, see CheckoutPatron.
  Show 1 fieldHide 1 field
  - dueDatestring (date)required
    This is the due date the patron was given at checkout.
- patronCheckoutPatronrequired
  Who the checkout is for, told by identifiedBy. Either the patron ID from a successful authentication, or the same identification that is sent to POST /patron/authentication and POST /patron/authentication/no-password.
  The second form exists because an offline checkout cannot use the first.
  When the patron is identified by identifier, the provider applies the same rules as the authentication endpoints, as configured in patron.login from the GET /configuration endpoint.
  Show 2 variantsHide 2 variants
  Selected by the field identifiedBy
  Variant: patron_id
  CheckoutPatronById
  See CheckoutPatronById in the schema index
  Variant: identifier
  CheckoutPatronByIdentifier
  See CheckoutPatronByIdentifier in the schema index
- transactionDateTimestring (date-time)required
  This is the date and time the patron made the checkout, meaning the moment they acted at the machine, not the moment the request was sent. The two are not always close: an offline checkout replayed hours later still carries the moment the patron stood there.
  A checkout sent again to acknowledge it keeps the value from the first request. The patron acted once, and the provider records its own time separately in CheckoutField.transactionDateTime.

Responses

200 It is important to check the returned status field, to distinguish between a completed checkout, one waiting to be acknowledged, and a failure. CheckoutResponseBody

Generated from the schema

Example

{
  "message": {
    "text": "This item is reserved by another patron. Please return it to the counter.",
    "type": "reservation-waiting"
  },
  "requestId": "5b1f6c2e-9a7d-4e3b-8f21-6c0d9e4a7b13",
  "status": "completed",
  "checkout": {
    "acquiredFrom": {
      "type": "local_circulation"
    },
    "dueDate": "2025-04-11",
    "fees": [
      {
        "amount": 15000,
        "createdTime": "2025-03-14T10:24:00+01:00",
        "currency": "NOK",
        "dueDate": "2025-04-11",
        "id": "94549",
        "items": [
          {
            "acquiredFrom": {
              "type": "local_circulation"
            },
            "itemId": "03011042557129",
            "publicationMetadata": {
              "additionalIdentifiers": [
                {
                  "digits": "10",
                  "type": "isbn",
                  "value": "9788203363344"
                }
              ],
              "binding": {
                "type": "literal",
                "value": "Hardback"
              },
              "contributors": [
                {
                  "agent": {
                    "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
                    "fullName": "Sigrid Undset",
                    "id": "agent-4102",
                    "images": [
                      {
                        "height": 1200,
                        "mime": "png",
                        "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                        "width": 800,
                        "type": "agent"
                      }
                    ],
                    "active": {
                      "type": "literal",
                      "value": "1882-1949"
                    },
                    "birthDate": {
                      "type": "literal",
                      "value": "1920"
                    },
                    "deathDate": {
                      "type": "literal",
                      "value": "1920"
                    },
                    "externals": {
                      "identifiers": [
                        {
                          "type": "norwegianAuthorityFile",
                          "value": "4102"
                        }
                      ]
                    },
                    "givenName": "Kari",
                    "surname": "Nordmann",
                    "type": "person"
                  },
                  "roles": [
                    {
                      "roleCode": "aut",
                      "type": "marcRelator"
                    }
                  ]
                }
              ],
              "creators": [
                {
                  "agent": {
                    "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
                    "fullName": "Sigrid Undset",
                    "id": "agent-4102",
                    "images": [
                      {
                        "height": 1200,
                        "mime": "png",
                        "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                        "width": 800,
                        "type": "agent"
                      }
                    ],
                    "active": {
                      "type": "literal",
                      "value": "1882-1949"
                    },
                    "birthDate": {
                      "type": "literal",
                      "value": "1920"
                    },
                    "deathDate": {
                      "type": "literal",
                      "value": "1920"
                    },
                    "externals": {
                      "identifiers": [
                        {
                          "type": "norwegianAuthorityFile",
                          "value": "4102"
                        }
                      ]
                    },
                    "givenName": "Kari",
                    "surname": "Nordmann",
                    "type": "person"
                  },
                  "roles": [
                    {
                      "roleCode": "aut",
                      "type": "marcRelator"
                    }
                  ]
                }
              ],
              "edition": {
                "type": "literal",
                "value": "2nd edition"
              },
              "extent": [
                {
                  "type": "literal",
                  "value": "312 pages"
                }
              ],
              "identifier": "310552",
              "images": [
                {
                  "height": 1200,
                  "mime": "png",
                  "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                  "width": 800,
                  "type": "frontCover"
                }
              ],
              "language": [
                {
                  "code": "SplxlOBeZQQYbYS6WxSbIA",
                  "name": "Kari Nordmann"
                }
              ],
              "mediaTypes": [
                {
                  "code": "book",
                  "name": "Kari Nordmann"
                }
              ],
              "publicationDate": {
                "type": "literal",
                "value": "1920"
              },
              "publishers": [
                {
                  "places": [
                    {
                      "place": "Oslo"
                    }
                  ],
                  "publisher": {
                    "id": "94549",
                    "name": "Kari Nordmann"
                  }
                }
              ],
              "titles": [
                {
                  "language": {
                    "code": "SplxlOBeZQQYbYS6WxSbIA",
                    "name": "Kari Nordmann"
                  },
                  "main": "Kristin Lavransdatter",
                  "part": {
                    "name": "Kari Nordmann",
                    "number": "1"
                  },
                  "remainder": "The Wreath",
                  "type": "preferred"
                }
              ],
              "works": [
                {
                  "identifier": "882107",
                  "relation": "contains"
                }
              ]
            }
          }
        ],
        "payableState": "payable",
        "remainingAmount": 1,
        "type": "fee"
      }
    ],
    "itemId": "03011042557129",
    "loanId": "58210447",
    "patronId": "40218873",
    "publicationId": "310552",
    "publicationMetadata": {
      "additionalIdentifiers": [
        {
          "digits": "10",
          "type": "isbn",
          "value": "9788203363344"
        }
      ],
      "binding": {
        "type": "literal",
        "value": "Hardback"
      },
      "contributors": [
        {
          "agent": {
            "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
            "fullName": "Sigrid Undset",
            "id": "agent-4102",
            "images": [
              {
                "height": 1200,
                "mime": "png",
                "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                "width": 800,
                "type": "agent"
              }
            ],
            "active": {
              "type": "literal",
              "value": "1882-1949"
            },
            "birthDate": {
              "type": "literal",
              "value": "1920"
            },
            "deathDate": {
              "type": "literal",
              "value": "1920"
            },
            "externals": {
              "identifiers": [
                {
                  "type": "norwegianAuthorityFile",
                  "value": "4102"
                }
              ]
            },
            "givenName": "Kari",
            "surname": "Nordmann",
            "type": "person"
          },
          "roles": [
            {
              "roleCode": "aut",
              "type": "marcRelator"
            }
          ]
        }
      ],
      "creators": [
        {
          "agent": {
            "description": "Norwegian novelist, awarded the Nobel Prize in Literature in 1928.",
            "fullName": "Sigrid Undset",
            "id": "agent-4102",
            "images": [
              {
                "height": 1200,
                "mime": "png",
                "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
                "width": 800,
                "type": "agent"
              }
            ],
            "active": {
              "type": "literal",
              "value": "1882-1949"
            },
            "birthDate": {
              "type": "literal",
              "value": "1920"
            },
            "deathDate": {
              "type": "literal",
              "value": "1920"
            },
            "externals": {
              "identifiers": [
                {
                  "type": "norwegianAuthorityFile",
                  "value": "4102"
                }
              ]
            },
            "givenName": "Kari",
            "surname": "Nordmann",
            "type": "person"
          },
          "roles": [
            {
              "roleCode": "aut",
              "type": "marcRelator"
            }
          ]
        }
      ],
      "edition": {
        "type": "literal",
        "value": "2nd edition"
      },
      "extent": [
        {
          "type": "literal",
          "value": "312 pages"
        }
      ],
      "identifier": "310552",
      "images": [
        {
          "height": 1200,
          "mime": "png",
          "url": "https://images.nordby.bibliotek.example/covers/310552.jpg",
          "width": 800,
          "type": "frontCover"
        }
      ],
      "language": [
        {
          "code": "SplxlOBeZQQYbYS6WxSbIA",
          "name": "Kari Nordmann"
        }
      ],
      "mediaTypes": [
        {
          "code": "book",
          "name": "Kari Nordmann"
        }
      ],
      "publicationDate": {
        "type": "literal",
        "value": "1920"
      },
      "publishers": [
        {
          "places": [
            {
              "place": "Oslo"
            }
          ],
          "publisher": {
            "id": "94549",
            "name": "Kari Nordmann"
          }
        }
      ],
      "titles": [
        {
          "language": {
            "code": "SplxlOBeZQQYbYS6WxSbIA",
            "name": "Kari Nordmann"
          },
          "main": "Kristin Lavransdatter",
          "part": {
            "name": "Kari Nordmann",
            "number": "1"
          },
          "remainder": "The Wreath",
          "type": "preferred"
        }
      ],
      "works": [
        {
          "identifier": "882107",
          "relation": "contains"
        }
      ]
    },
    "renewed": false,
    "transactionDateTime": "2025-03-14T10:24:00+01:00"
  }
}

Schema

CheckoutResponseBody

Selected by the field status

Variant: completed

CheckoutCompleted

messageCheckOutOrInMessage
Show 2 fieldsHide 2 fields
- textstring
  Message to the patron.
- typestring
  This can be used instead of the text field to identify the message type.
  This can be used by a vendor to handle the message or control the content of the message.
  PLAS defines no values for this field, they are agreed between a provider and the vendors integrating with it. A vendor that does not recognise a value should fall back to text.
requestIdstringrequired
This is a unique identifier for the checkout request. This will change for each request.
It is meant for correlating logs.
statusstringrequired
This tells that the checkout went well and was completed.
One of: completed
checkoutCheckoutFieldrequired
Show 10 fieldsHide 10 fields
- acquiredFromPatronLoanAcquiredFrom
  This tells from where (the material for) this loan was acquired.
  If this field are missing, the default value local_circulation should be assumed.
  - local_circulation: Meaning that this loan was acquired from the customers own inventory.
  - interlibrary_loan: Meaning that this loan was acquired as a interlibrary loan.
  - unknown: Meaning that this information is unknown.
  See PatronLoanAcquiredFrom in the schema index
- dueDatestring (date)required
  This is the due date of the checked out item.
- feesarray of PatronFee
  The fees the library registered on the patron as part of this checkout, e.g. a lending fee the patron accepted through acknowledgement. Send an empty array when the checkout created no fee. Leave the field out only when the provider cannot tell whether a fee was created.
  See PatronFee in the schema index
- itemIdstringrequired
  This is the item ID of the checkout item.
- loanIdstringrequired
  This is the loan ID.
- patronIdstringrequired
  This is the patron ID of the patron that made the checkout.
- publicationIdstringrequired
  This is the publication ID of the checkout item. A vendor needs it to show or print a title.
- publicationMetadataPublicationFallback
  This metadata is only intended as fallback data, for when the provider is not able to serve the metadata through the GET /publication endpoint.
  This can for some provider be the case when working with e.g. interlibrary loans.
  See PublicationFallback in the schema index
- renewedboolean
  True when the patron already had this item on loan, so this checkout extended the existing loan instead of creating a new one.
  If the field is missing, this information is unknown.
- transactionDateTimestring (date-time)required
  This is the registered time and date of the checkout.

Variant: needs_acknowledgement

CheckoutNeedsAcknowledgement

messageCheckOutOrInMessage
Show 2 fieldsHide 2 fields
- textstring
  Message to the patron.
- typestring
  This can be used instead of the text field to identify the message type.
  This can be used by a vendor to handle the message or control the content of the message.
  PLAS defines no values for this field, they are agreed between a provider and the vendors integrating with it. A vendor that does not recognise a value should fall back to text.
requestIdstringrequired
This is a unique identifier for the checkout request. This will change for each request.
It is meant for correlating logs.
statusstringrequired
This tells that the checkout needs to be acknowledged to be completed.
One of: needs_acknowledgement
acknowledgementCheckoutAcknowledgementrequired
Show 3 fieldsHide 3 fields
- codestringrequired
  This code must be included in the checkout request in order for the checkout to be completed.
- conditionsarray of one of CheckoutAcknowledgementTypeFee | CheckoutAcknowledgementTypePreviouslyCheckedOut | CheckoutAcknowledgementTypeMessagerequiredmin items 1
  Everything the patron must accept, in one list. A vendor must show all of it to the patron, and then send the checkout again with the single code that covers the whole list.
  A provider that needs the patron to accept something PLAS does not model puts it here as a message entry.
- expiresAtstring (date-time)required
  When the code stops being valid.

Variant: failed

CheckoutFailed

messageCheckOutOrInMessage
Show 2 fieldsHide 2 fields
- textstring
  Message to the patron.
- typestring
  This can be used instead of the text field to identify the message type.
  This can be used by a vendor to handle the message or control the content of the message.
  PLAS defines no values for this field, they are agreed between a provider and the vendors integrating with it. A vendor that does not recognise a value should fall back to text.
requestIdstringrequired
This is a unique identifier for the checkout request. This will change for each request.
It is meant for correlating logs.
statusstringrequired
This tells that the checkout failed, and the item was not checked out.
One of: failed
reasonCheckoutFailureReasonrequired
Why the item was not checked out.
This is an open enum, so values other than the known ones are allowed. A vendor that does not know a value should treat it as unknown and show message to the patron.
One of: item_not_found · item_not_lendable · item_on_loan · item_reserved_for_other_patron · item_belongs_to_other_branch · patron_not_found · patron_authentication_failed · patron_blocked · patron_owes_fees · patron_loan_limit_reached · patron_expired · acknowledgement_rejected · unknown
Show 2 variantsHide 2 variants
Variant: CheckoutFailureReasonEnum
CheckoutFailureReasonEnum
Variant: CheckoutFailureReasonLiteral
CheckoutFailureReasonLiteral

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
The first error should always be the most relevant.
Show 2 fieldsHide 2 fields
- codeintegerrequired
  A number representing the type of error.
  List of error codes:
  - \<error code\>: \<error description\>
  - 500: System error
  - 600: Unsupported Open Library API version
  - 10001: Endpoint disabled
  - 71001: Consent has not been given for 'loan history'
  - 100001: Wrong patron identifier, password or pin code
  - 100011: New password or pin code rejected, because it does not meet the provider's requirements
  - 100013: The provider does not let the patron change the given credential
  - 100023: Patron ID not found
  - 100101: Patron could not be deleted, because the patron has something unresolved issue with the library (this could be anything from a loan to a fee, and so on ...)
  - 100211: maxNumberOfEmailAddresses exceeded
  - 100215: maxNumberOfPhoneNumbers exceeded
  - 100221: Pickup location cannot contain sections
  - 100411: Updating patron consent failed
  - 100611: Updating patron notification settings failed
  - 101001: Reservation ID not found
  - 101047: Branch ID cannot be used as pick up branch
  - 101053: Section ID cannot be used as pick up branch
  - 102001: Loan ID not found
  - 102301: Loan not renewable, because it is an interlibrary loan
  - 102311: Loan not renewable, because it is reserved
  - 110001: Branch ID not found
  - 200001: Publication ID not found
  - 200077: ui language not supported
  - 200101: missing required query parameter
  - 200103: invalid/unsupported query parameter value
  - 300001: Initialize payment should not be used
  - 300005: Initialize payment should be used
  - 300009: Payment method not supported
  - 300013: Payment method does not support partial payment
  - 300301: Finalized payment can not de changed
  - 300311: FinalizePaymentRequest.fees contains fees with the same ID
  - 310001: Loan history ID not found
  - 310011: Loan history ID already exists
  - 330001: List ID not found
  - 330011: List ID already exists
  - 330101: List item ID not found
  - 330111: List item ID already exists
  One of: 500 · 600 · 10001 · 71001 · 100001 · 100011 · 100013 · 100023 · 100101 · 100211 · 100215 · 100221 · 100411 · 100611 · 101001 · 101047 · 101053 · 102001 · 102301 · 102311 · 110001 · 200001 · 200077 · 200101 · 200103 · 300001 · 300005 · 300009 · 300013 · 300301 · 300311 · 310001 · 310011 · 330001 · 330011 · 330101 · 330111
- infostringrequired
  Starts with the text matching the error code field (defined above), and a describing text could be added.

401 Bearer token invalid, missing, or expired.

Shared response, defined once for the whole API. See the shared contract on the version page.

No response body.

429 Too many requests. The provider is rate limiting and did not carry out the request.

The response should have a Retry-After header saying how many seconds to wait. Show the patron "try again later", not an error about what they sent.

Shared response, defined once for the whole API. See the shared contract on the version page.

Headers: Retry-After integer
Seconds to wait before sending the request again.

No response body.