/checkin/{itemId} Check in an item
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:
completedthe item was checked in, andcheckinholds the result.failedthe item was not checked in, andreasonsays 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.
Eksempel på kald
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()PLAS_BASE_URL providerens adresse · PLAS_TOKEN et access token.
Parametre
- itemIdpåkrævet
- path · stringEksempel: 03011042557129
The item identifier of the item to check in.
Request body
application/json · påkrævet · CheckinRequestBody - checkinobjectpåkrævet
Vis 3 felterSkjul 3 felter
Vis 2 felterSkjul 2 felter
- branchIdstringpåkrævet
The branch ID where the checkout or checkin was made.
This is specifying the location more precisely.
- 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.isAllowedis true.The item is already back, so the provider registers the checkin rather than ruling on it. Only
item_not_foundanditem_not_on_loancan still fail.If the field is missing, the default value is false.
- returnDateTimestring (date-time)påkrævet
This is the return date and time the patron made the checkin.
Svar
200 It is important to check the returned status field, to distinguish between a completed checkin and a failure. CheckinResponseBody
Eksempel
{
"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"
}
}Skema
Vælges af feltet status
Variant: completed
- messageCheckOutOrInMessage
Vis 2 felterSkjul 2 felter
- 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.
- requestIdstringpåkrævet
This is a unique identifier for the checkin request. This will change for each request.
It is meant for correlating logs. - statusstringpåkrævet
This tells that the checkin went well and was completed.
Én af: completed
Vis 12 felterSkjul 12 felter
- 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.
- dueDatestring (date)
This is the due date of the checkin item, meaning the date where item should (at the latest) be returned.
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.- itemIdstringpåkrævet
This is the item ID of the checked in item.
- loanIdstringpåkrævet
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.
- publicationIdstringpåkrævet
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.
- 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)påkrævet
This is the registered time and date of the checkin.
Variant: failed
- messageCheckOutOrInMessage
Vis 2 felterSkjul 2 felter
- 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.
- requestIdstringpåkrævet
This is a unique identifier for the checkin request. This will change for each request.
It is meant for correlating logs. - statusstringpåkrævet
This tells that the checkin failed, and the item was not checked in.
Én af: failed
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
unknownand showmessageto the patron.Én af: item_not_found · item_not_on_loan · item_belongs_to_other_library · unknown
Vis 2 varianterSkjul 2 varianter
Variant: CheckinFailureReasonEnum
Variant: CheckinFailureReasonLiteral
400 The list of errors. Errors
Fælles svar, defineret én gang for hele API’et. Se den fælles kontrakt på versionssiden.
Eksempel
{
"errors": [
{
"code": 200103,
"info": "200103: invalid/unsupported query parameter value"
}
]
}Skema
The first error should always be the most relevant.
Vis 2 felterSkjul 2 felter
- codeintegerpåkrævet
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
Én af: 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
- infostringpåkrævet
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.
Fælles svar, defineret én gang for hele API’et. Se den fælles kontrakt på versionssiden.
Intet indhold i svaret.
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.
Fælles svar, defineret én gang for hele API’et. Se den fælles kontrakt på versionssiden.
- Headers
- Retry-After integer
Seconds to wait before sending the request again.
Intet indhold i svaret.