Checkout

Start Checkout Process

POST /rpc/.../circulation/checkout

This method allows the caller to check out an item to a patron.

Request Information

Parameters
Name Type Required Description
checkoutData DtoCheckOutData Yes Define this parameter in the request body.
DtoCheckOutData
Property Type Nullable Description
CircTranType Int No Required. Sets the type of checkout and applies specific rules.
  • CircTranType.CHKOUT_NORM (6)
  • CircTranType.CHKOUTNORM_DIFFPAT (7)
  • CircTranType.CHKOUT_OFFL (16)
  • CircTranType.CHKOUTOFFL_DIFFPAT (18)
  • CircTranType.CHKOUT_EXPRESS (34)
  • CircTranType.CHKOUT_EXPRESS_DIFFPAT (35)
  • CircTranType.CHKOUT_OUTREACH (36)
  • CircTranType.CHKOUT_BBM (37)
PatronBarcode String No Barcode of patron.
ItemBarcode String No Barcode of item.
LoginBranchID Int Organization ID where the checkout is occurring. Used for SA settings and to record statistical data.
UserID Int No Required. Staff user ID processing the checkout. Used for SA settings and to record statistical data.
WorkstationID Int No Required. Workstation where the checkout is occurring. Used for SA settings and to record statistical data.
OfflineCheckoutDate DateTime Yes Provide a date if this is an offline checkout.
SpecialLoan Boolean No If set to true. Use provided special loan settings.
SpecialLoanUnits Int No Required if SpecialLoan is set to true.
SpecialLoanUnitsNum Int No Required if SpecialLoan is set to true.
SpecialLoanDueDate DateTime Yes Used when SpecialLoan is set to true.
BBMBulkCheckout Boolean No Only set to true if processing a 'Borrower by mail' checkout.
ProcedureStep Int No Set the checkout state machine to the last procedure step.
Answer Int No Value when responding to a prompt.
EphemeralItemCount Int No Only used when replying to an ephemeral item procedural prompt.
Request body
application/json, text/json 
{
  "CircTranType": 6,
  "PatronBarcode": "21756003332022",
  "ItemBarcode": "0004300060946",
  "LoginBranchID": 3,
  "UserID": 923,
  "WorkstationID": 470,
  "OfflineCheckoutDate": null,
  "SpecialLoan": false,
  "SpecialLoanUnits": 0,
  "SpecialLoanUnitsNum": 0,
  "SpecialLoanDueDate": null,
  "BBMBulkCheckout": false,
  "ProcedureStep": 1,
  "Answer": 0,
  "EphemeralItemCount": 0
}

Response Information

Example
application/json, text/json 
{
    "HeldItemBlock":false,
    "FirstLevelFineBlock":true,
    "UnreadMessageBlock":false,
    "SecondLevelFineBlock":true,
    "OverdueItemBlock":true,
    "LibraryAssignedBlock":false,
    "FreeTextBlock":false,
    "CollectionAgencyBlock":false,
    "ClaimLimitBlock":false,
    "BlockingNoteBlock":false,
    "PatronSystemBlock":true,
    "CheckedOut_EphemeralItem":false,
    "CheckedOut_ItemID":0,
    “CheckedOut_ItemTitle”:”The secret of Shadow ranch”,
    "CheckedOut_AssignedBranchID":0,
    "CheckedOut_AssignedBranchName":null,
    "CheckedOut_MaterialTypeID":0,
    "CheckedOut_MaterialTypeDescription":null,
    "CheckedOut_DueDate":null,
    "PatronBlocks":[
    {
        "PatronID":299377,
        "PatronFullName":"Franklin, Jeffrey D",
        "BlockType":3,
        "BlockID":103,
        "BlockDescription":"Total overdue items: 1"
    },
    {
        "PatronID":299377,
        "PatronFullName":"Franklin, Jeffrey D",
        "BlockType":3,
        "BlockID":109,
        "BlockDescription":"Patron has accrued fees. Amount due: $8.60"
    }
    ],
    "LinkedPatronBlocks":[
    {
        "PatronID":189171,
        "PatronFullName":"Franklin, Alaina C",
        "BlockType":3,
        "BlockID":109,
        "BlockDescription":"Patron owes money and has accrued fees. Amount due: $90.40"
    },
    {
        "PatronID":189171,
        "PatronFullName":"Franklin, Alaina C",
        "BlockType":3,
        "BlockID":110,
        "BlockDescription":"Patron has exceeded maximum fees and accrued fees permitted. 
        Amount due: $90.40"
    },
    {
        "PatronID":189171,
        "PatronFullName":"Franklin, Alaina C",
        "BlockType":1,
        "BlockID":44861,
        "BlockDescription":"patron 1000601062713 to collection agency 12/31/2007 cph_kr"
    },
    {
        "PatronID":189171,
        "PatronFullName":"Franklin, Alaina C",
        "BlockType":2,"BlockID":3,"BlockDescription":"Registration Has Expired"
    }
    ],
    "ItemBlocks":[
        "sample string 1",
        "sample string 2",
        "sample string 3"
    ],
    "PAPIProcedure":0,
    "PAPIProcedureStep":2,
    "PAPIAction":2,
    "PAPIActionProcedure":0,
    "PAPIPromptType":4,
    "PAPIStopType":0,
    "PAPIReturnCode":-6101,
    "Success":false,
    "Message":"Patron is blocked.  Do you want to continue with this operation?"
}

Processing the Results

API Procedural calls act like a “conversation”. You initiate the conversation by calling the method with a ProcedureStep value of 1 (Start).

Example:
"ProcedureStep": 1

The checkout procedure will process the DtoCheckOutData that was posted to it. It will reply to your checkout request with a DtoCheckOutResult that contains a set of PAPI Values:

Example:
"PAPIProcedure":0,
"PAPIProcedureStep":2,
"PAPIAction":2,
"PAPIActionProcedure":0,
"PAPIPromptType":4,
"PAPIStopType":0,
"PAPIReturnCode":-6101,
"Success":false,
"Message":"Patron is blocked. Do you want to continue with this operation?"

You should always check the PAPIReturnCode. 0 or greater represents a successful call. The procedure completed. A return code of < 0, means the call did not complete or more processing is required. In this case, a -6101 was returned. This tells us the checkout patron was blocked. You may also look at the PAPIProcedureStep that was returned. It is set to 2, which signifies the process stopped on “CheckPatronBlocks”.

Next, look at the PAPIAction value. Given the value 2 (Prompt), it is telling the caller that they need to display a prompt. The Message property contains the prompt text. The PAPIPromptType value is 4, which indicates a Yes/No prompt.

The caller should display a prompt that displays the message and provide “Yes” and “No” options. Because this is a patron block return code, additional information is returned that should be displayed. The PatronBlocks and LinkedPatronBlocks arrays contain additional blocking information. In the native staff client, the following dialog displays:

The caller replies to this checkout response by calling checkout again, but this time the procedure step will be set to 2. The current step is returned in the DtoCheckOutResult:

Example:
"PAPIProcedureStep":2

The answer is set to 1 (yes) or 0 (no).

Example:
        {
          "CircTranType": 6,
          "PatronBarcode": "21756003332022",
          "ItemBarcode": "0004300060946",
          "LoginBranchID": 3,
          "UserID": 923,
          "WorkstationID": 470,
          "OfflineCheckoutDate": null,
          "SpecialLoan": false,
          "SpecialLoanUnits": 0,
          "SpecialLoanUnitsNum": 0,
          "SpecialLoanDueDate": null,
          "BBMBulkCheckout": false,
          "ProcedureStep": 1,
          "Answer": 0,
          "EphemeralItemCount": 0
        }

Continue this process until the conversation is complete. Please note that by not replying, you are simply choosing to discontinue with the checkout operation. It is a best practice to follow-through the process until the conversation is complete.

Reference for Polaris API Procedure values:

public enum PAPIProcedureStatus
{
	Error = -1,
	Exit = 0,
	Continue = 1
}

public enum PAPIProcedure
{
	None = 0,
	CheckIn = 1,
	CheckOut = 2,
	CreateOTFItem = 3,
	PatronRegistration = 4,
	PlaceHoldRequest = 5,
	RenewItemCheckout = 6
}

public enum PAPIProcedureStep
{
	None = 0,
	Start = 1,
	CheckPatronBlocks = 2,
	GetEphemeralItemCount = 3,
	CheckAssignedBranch = 4,
	PlaceItemInTransit = 5,
	PermitOvernightLoan = 6,
	NonCirculatingItemBlock = 7,
	RestrictedPatronCodeBlock = 8,
	CheckItemBlocks = 9,
	CheckOutItemInTransit = 10,
	FloatingCheckIn = 11,
	PlaceInTransit = 12,
	OutToDifferentPatron = 13,
	ResolveLostBilledItem = 14
}

public enum PAPIAction
{
	None = 0,
	Stop = 1,
	Prompt = 2,
	Procedure = 3
}

public enum PAPIStopType
{
	None = 0,
	Exit = 1,
	Error = 2
}

public enum PAPIPromptType
{
	None = 0,
	Warning = 1,
	Continue = 2,
	Count = 3,
	YesNo = 4,
	YesNoCancel = 5,
	Acknowledge = 6,
	ResolveLostBilledItem = 7
}

public enum PAPIPromptResult
{
	None = -1,
	No = 0,
	Yes = 1,
	OK = 2,
	Cancel = 3,
	Abort = 4,
	Retry = 5,
	Ignore = 6
}

HTTP Response Codes

Code Description
200 OK. Success