API Docs

Rest Po Line

Overview

PO line can be a purchase for physical or electronic material.
PO lines are linked to a PO, which is sent to the vendor.
The POST PO line action is mainly used for creating a PO line in Alma, for an order that was purchased at a vendor system. See details here.
The following fields are required by the POST action: owner, type and title. If they were not supplied - 400 HTTP error will be returned.
There are other fields which are required for the PO line to be processed in Alma: vendor, vendor account, price and fund.
If any of these fields is missing, the PO Line will be created in Alma, but will be in the "In Review" list.
Note that PO line processing in Alma is asynchronous. This means that the response for POST action might not include status and alerts.
The GET action can be used afterwards to review the PO line situation.

Data Dictionary

Click here to download rest_po_line.xsd

po_line

Description: PO line Object.

FieldTypeDescription
numberstringThe PO line number. Output parameter.
Should be used in subsequent queries regarding the PO line.
statusstring with attr. The PO Line Status. Output parameter.
Possible codes are listed in 'POLineStatus' code table.

The valid values for this parameter are controlled by the code-table: POLineStatus. These are the currently defined values for your institution:
CodeDescription
ownerstring with attr. The organization unit that is responsible of the PO line.
Mandatory in POST.
See Get libraries API.
typestring with attr. The code of the PO line type. Mandatory in POST.
Possible codes are listed in 'PurchaseType' code table.

The valid values for this parameter are controlled by the code-table: PurchaseType. These are the currently defined values for your institution:
CodeDescription
vendorstring with attr. The vendors code. Mandatory for processing the PO line.
If not supplied, the PO line will be created as "In Review". In the PUT action, a vendor can be changed only before the PO line was attached to a PO (i.e. statuses: "In Review", "Deferred", "Packaging").
vendor_accountstringThe vendor account code. Mandatory for processing the PO line. If not supplied, the PO line will be created as "In Review".
In the PUT action, a vendor account can be changed only before the PO line was attached to a PO (i.e. statuses: "In Review", "Deferred", "Packaging").
reclaim_intervalstring
The number of days to wait before sending a 2nd, 3rd, 4th etc claim letter to the vendor.
Optional. By default, this field will be populated based on the definitions on the vendor account.
expected_receipt_intervalstring
Added to the current date. Default is from vendor account.
claiming_intervalstring
Added to the expected receipt date. Default is from vendor account.
expected_activation_intervalstring
Added to the current date. Default is from vendor account.
subscription_intervalstring
Added to the expected activation date. Default is from vendor account.
expected_activation_datedateAdded to expected activation date. Default is from vendor account.
e_activation_due_intervalstringAdded to expected activation date. Default is from customer parameter.
acquisition_methodstring with attr. The code of the PO line acquisition method.
Possible codes are listed in 'AcquisitionMethod' code table.
Default value is: VENDOR_SYSTEM. In the PUT action, the acq method can be changed only before the PO line was attached to a PO (i.e. statuses: "In Review", "Deferred", "Packaging").

The valid values for this parameter are controlled by the code-table: AcquisitionMethod. These are the currently defined values for your institution:
CodeDescription
no_chargeboolean
Indication if the order is free of charge. Optional.
Default is False. Relevant only for acquisition methods: Approval Plan,
Purchase, Purchase at Vendor System.
rushbooleanIs it rush PO line. Optional.
Default is False.
cancellation_restrictionboolean Indication whether the cancellation restriction note should display a warning upon the cancellation of a PO line.
Optional. Default is False.
cancellation_restriction_notestringA warning to be displayed when canceling a PO line. Optional.
priceamountThe list price - i.e. price for a single copy of the item, before discount.
See here for more details about pricing.
Mandatory for processing the PO line. If not supplied, the PO line will be created as "In Review".
discountstringDiscount (in percentage).
In the POST action, the default for this field is the discount defined on the vendor account.
Overriding vendor account's discount with discount 0 is currently not supported.
Not supported with PUT action.
vendor_reference_numberstringThe number given by the vendor to the PO line.
Optional. If exists, it can be used for identifying the PO line.
vendor_reference_number_typestring with attr. The types of vendor reference number.
Possible codes are listed in 'VendorReferenceNumberType' code table.

The valid values for this parameter are controlled by the code-table: VendorReferenceNumberType. These are the currently defined values for your institution:
CodeDescription
source_typestring with attr. The source in which the PO line was initially created.
Possible codes are listed in 'AcqItemSourceType' code table.
Note that the POST action will always populate this with "API" value.

The valid values for this parameter are controlled by the code-table: AcqItemSourceType. These are the currently defined values for your institution:
CodeDescription
po_numberstringThe PO number that this PO Line is packed into.
Optional.
If supplied in the POST action, and exists in Alma - then the newly created PO line will be linked to this PO.
If not, the PO line will be linked to a PO when it will be packaged, according to the system's policy.
In the PUT action, the po_number can be changed only before the PO line was attached to a PO (i.e. statuses: "In Review", "Deferred", "Packaging").
invoice_referencestringInvoice reference number, if exists. Optional.
In the PUT action, the invoice can be changed only before the PO line was attached to a PO (i.e. statuses: "In Review", "Deferred", "Packaging").
resource_metadataresource_metadataMetadata related information.
If a matching bibliographic record is found - the PO line will be related to it. If not - a new bibliographic record will be created.
See here for more details regarding the matching process.
fund_distributionsfund_distributionsThe Fund Distributions list.
One fund is mandatory for processing the PO line. If not supplied, the PO line will be created as "In Review".
See Get funds API.
reporting_codestringThe related Reporting Code. Optional.
Possible codes are listed in 'HFundsTransactionItem.reportingCode' code table.
secondary_reporting_codestringSecondary reporting code. Optional.
Possible values are listed in 'SecondReportingCode' code table.

The valid values for this parameter are controlled by the code-table: SecondReportingCode. These are the currently defined values for your institution:
CodeDescription
tertiary_reporting_codestringTertiary reporting code. Optional.
Possible values are listed in 'ThirdReportingCode' code table.

The valid values for this parameter are controlled by the code-table: ThirdReportingCode. These are the currently defined values for your institution:
CodeDescription
vendor_notestringThe vendor's note. Optional.
receiving_notestringThe related receiving note. Optional.
alertsalertsList of Alerts that blocked the processing of the PO line. Output parameter.
notesnotesList of the PO line related notes. Optional.
In the PUT action the incoming list will replace the existing list. If the incoming list is empty, the existing list will be deleted.
locationslocationsInformation about the locations in which the ordered items will be stored.
Relevant only for Physical.
See Get locations API.
interested_usersinterested_usersList of users to be annotated.
With PUT if not sent will preserve the existing users.
licensestring with attr. The license code. Relevant for electronic orders only, and is not supported for PUT.
List of possible licenses can be retrieved using the GET licenses API
access_modelstringRelevant when PO Line type is Electronic
and the Access Model is defined in the "New Order API" Integration Profile.
It will be appended as a public note in the created electronic resource.
urlstringURL for E-book item.
base_statusbase_status
access_providerstringService Provider for E-book item.
Relevant only for Electronic.
In the PUT action, the access_provider can be changed only before the PO line was attached to a PO (i.e. statuses: "In Review", "Deferred", "Packaging").
manual_renewalbooleanIndication if the renewal is done manually. Optional. Default is True.
Relevant only for continuous and standing orders PO lines.
renewal_cyclestring with attr. The renewal cycle.
Relevant only if "manual renewal" is false.
codes are listed in 'Renewal Cycle' code table.

The valid values for this parameter are controlled by the code-table: RenewalCycle. These are the currently defined values for your institution:
CodeDescription
subscription_from_datedateThe date that the subscription for the PO line began. Optional.
Relevant only for continuous and standing orders PO lines.
subscription_to_datedateThe the last day of the subscription for the PO line. Optional.
Relevant only for continuous and standing orders PO lines.
renewal_datedateThe the date of renewal.
Relevant and mandatory only for continuous and standing orders PO lines.
If not supplied, the PO line will be created as "In Review".
renewal_periodintThe number of days before the renewal date to be reminded. Optional. Default is 0.
Relevant only for continuous and standing orders PO lines.
renewal_notestringThe note regarding renewal at vendor system. Optional. Max length is 4000
material_typestring with attr. Material type of the item.
Possible codes are listed in the "PhysicalMaterialType" code table for Physical,
and in the "electronicMaterialType" code table for Electronic.
created_datedateThe creation date of the PO line.
status_datedateThe date in which the PO line status was last updated.
expected_receipt_datedate
The date in which the po line is expected to be received at the library.
If not specify, Alma will calculate estimation when the request will be sent to the vendor.

 

fund_distributions

Description: The Fund Distributions list. One fund is mandatory for processing the PO line.
If not supplied, the PO line will be created as "In Review".
In the PUT action the incoming list will replace the existing list. If the incoming list is empty, the existing list will be deleted.
See Get funds API.

FieldTypeDescription
fund_distributionfund_distributionSpecific Fund Distributions.

 

fund_distribution

Description: Specific Fund Distributions.

FieldTypeDescription
fund_codestring with attr. The fund code.
amountamountThe amount which is to be paid by the fund.
See here for more details about funding calculation.

 

resource_metadata

Description: Metadata related information.
If a matching bibliographic record is found - the PO line will be related to it. If not - a new bibliographic record will be created.
See here for more details regarding the matching process.

FieldTypeDescription
mms_idstring with attr. The mms_id. Cannot be updated by the PUT action.
If supplied in the POST action, match will be done based on it.
titlestringThe title.
Mandatory in the POST action if mms_id was not supplied.
authorstringAuthor - taken from inventory field 250 $b.
issnstringissn
isbnstringisbn
publisherstringThe Publisher of the item.
publication_placestringThe publication place of the item.
publication_yearstringThe publication year of the item.
vendor_title_numberstringThe value given by the vendor to the title.
title_idstringRelevant only for electronic orders from OASIS for portfolios
which are part of "Ebook Central Perpetual and DDA Titles" collection.
This field will be used in order to find and activate the relevant portfolio from the CZ.
system_control_numberssystem_control_numbersList of system control numbers, corresponding to the MARC 035 field.

 

system_control_numbers

Description:

FieldTypeDescription
system_control_numberstringSystem control number.

 

locations

Description: Information about the locations in which the ordered items will be stored.
Relevant only for physical.
See Get locations API.

FieldTypeDescription
locationlocationSpecific location Distributions.

 

location

Description: Specific location Distributions.

FieldTypeDescription
quantityintThe quantity per location.
librarystring with attr. The library which the location belongs to.

The valid values for this parameter are the library codes. These are the currently defined values for your institution:
CodeDescription
shelving_locationstringThe location.
holdingsholdingsRelevant holding records. Output parameter.
copiescopiesCopies of item in a specific location.

 

copies

Description: Copies of item in a specific location.

FieldTypeDescription
copycopySpecific copy of item in a specific location.

 

copy

Description: Specific copy of item in a specific location.

FieldTypeDescription
pidstringThe item's pid. Output parameter.
holding_idstringThe item's related holding record id. Output parameter.
barcodestringThe item's barcode.
item_policystring with attr. The related item policy.
Possible codes are listed in 'ItemPolicy' code table.

The valid values for this parameter are controlled by the code-table: ItemPolicy. These are the currently defined values for your institution:
CodeDescription
receive_datedateThe date in which the item has arrived to the library.
If supplied in POST action the item will be created as received.
expected_arrival_datedateThe date in which the item is expected to arrive at the library. Note that this field is deprecated in the POST action: the expected_receipt_date on the po line level should be supplied.
enumeration_astringenumeration A
enumeration_bstringenumeration B
enumeration_cstringenumeration C
chronology_istringchronology I
chronology_jstringchronology J
chronology_kstringchronology K
descriptionstringThis item's description.
storage_location_idstringThe ID number of the location where the item is stored.
is_temp_locationbooleanIf this location is the item's temporary location.
permanent_librarystring with attr. Permanent library.
Relevant only if is_temp_location is True.
permanent_shelving_locationstringPermanent shelving location.
Relevant only if is_temp_location is True.

 

amount

Description:

FieldTypeDescription
sumstringThe sum.
currencystring with attr. The currency.
Possible values are listed in 'Currency_CT' code table.

The valid values for this parameter are controlled by the code-table: MT_CurrencySubset_by_CT_Currency_CT. These are the currently defined values for your institution:
CodeDescription

 

interested_users

Description: List of users to be annotated.
With PUT if not sent will preserve the existing users.

FieldTypeDescription
interested_userinterested_userSpecific user to be annotated.

 

interested_user

Description: Specific user to be annotated.

FieldTypeDescription
primary_idstringUser's primary identifier.
notify_receiving_activationboolean
When true, Alma sends an email to the user when the item arrives at the library's receiving department.
Optional. Default is False.
hold_itemboolean
When true, Alma creates a hold request on the item for the user.
Optional. Relevant only for physical items. Default is False.
notify_renewalboolean
When true, Alma sends a notification letter to the user when the order is sent to manual renewal.
Optional. Relevant only for continuous orders. Default is False.
notify_cancelboolean
When true, Alma sends a notification letter to the user when the order is canceled.
Optional. Default is False.
first_namestringUser's first name. Output parameter.
last_namestringUser's last name. Output parameter.
emailstringUser's email address. Output parameter.

 

alerts

Description: List of Alerts that blocked the processing of the PO line. Output parameter.

FieldTypeDescription
alertstring with attr. Specific alert.
Possible codes are listed in 'AssertionCodes' code table.

The valid values for this parameter are controlled by the code-table: MT_POLineAssertions_by_CT_AssertionCodes. These are the currently defined values for your institution:
CodeDescription

 

notes

Description: List of the PO line related notes.
In the PUT action the incoming list will replace the existing list. If the incoming list is empty, the existing list will be deleted.

FieldTypeDescription
notenoteSpecific PO line related note.

 

note

Description: Specific PO line related note.

FieldTypeDescription
note_textstringThe note's text.
creation_datedate
The creation date of the note. Default is the current date.
created_bystringThe creator of the note.

 

holdings

Description: Relevant holding records. Output parameter.

FieldTypeDescription
holdingholdingSpecific holding record.

 

holding

Description: Specific holding record.

FieldTypeDescription
idstringThe holding record's id. Output parameter.

 

Samples

XML
JSON
__