Acquisitions¶

Reached as client.acq. Covers Alma's /acq/po-lines endpoints: retrieving and updating a purchase order line, receiving an item against one, and cancelling it.

AlmaClientAcqNS ¶

AlmaClientAcqNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for acquisitions functionality.

Available as client.acq. Every method here returns a Box by default; pass model= a Pydantic model class to get a validated instance of that model instead. See Responses for the details.

get_po_line `async` Alma: Get PO-Line ¶

get_po_line(
    po_line_id: str, *, model: type[_ModelT]
) -> _ModelT

get_po_line(
    po_line_id: str, *, model: None = ...
) -> RESP_TYPE

Retrieve a single purchase order line.

Parameters:

Name	Type	Description	Default
`po_line_id`	`str`	The PO line identifier, e.g. `POL-12345`.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The PO line record.

Raises:

Type	Description
`APIClientError`	If the PO line does not exist or is not accessible.

Examples:

pol = await client.acq.get_po_line("POL-12345")
print(pol.number, pol.status.desc)

update_po_line `async` Alma: Update PO-Line ¶

update_po_line(
    po_line_id: str,
    updated_po_line: Body,
    *,
    update_inventory: bool = ...,
    redistribute_funds: bool = ...,
    model: type[_ModelT],
) -> _ModelT

update_po_line(
    po_line_id: str,
    updated_po_line: Body,
    *,
    update_inventory: bool = ...,
    redistribute_funds: bool = ...,
    model: None = ...,
) -> RESP_TYPE

Update a purchase order line.

Alma replaces the whole PO line with the body supplied, so updated_po_line should normally be a record fetched with get_po_line and then modified, not a partial object.

Parameters:

Name	Type	Description	Default
`po_line_id`	`str`	The PO line identifier, e.g. `POL-12345`.	required
`updated_po_line`	`Body`	The full, modified PO line record. Accepts a mapping or any object implementing `dump`/`model_dump`, so a Pydantic model can be passed directly.	required
`update_inventory`	`bool`	Whether Alma should propagate the change to the associated inventory (items and holdings).	`False`
`redistribute_funds`	`bool`	Whether Alma should redistribute encumbrances across the fund distribution when the price or funds change.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated PO line record as returned by Alma.

Raises:

Type	Description
`POUpdateFailedError`	If Alma rejected the update (Alma code `401876`).
`APIClientError`	If the PO line does not exist or the body is invalid.

Examples:

pol = await client.acq.get_po_line("POL-12345")
pol.vendor_note = "Chase before end of quarter"
updated = await client.acq.update_po_line("POL-12345", pol)

receive_existing_item `async` Alma: Receive an Existing Item ¶

receive_existing_item(
    po_line_id: str,
    item_pid: str,
    *,
    receive_date: date | None = ...,
    department: str | None = ...,
    department_library: str | None = ...,
    updated_item: Body | None = ...,
    model: type[_ModelT],
) -> _ModelT

receive_existing_item(
    po_line_id: str,
    item_pid: str,
    *,
    receive_date: date | None = ...,
    department: str | None = ...,
    department_library: str | None = ...,
    updated_item: Body | None = ...,
    model: None = ...,
) -> RESP_TYPE

Receive an item that already exists against a purchase order line.

This is the op=receive operation on a PO line item – it marks physical material as arrived. The item must already exist in Alma; this method does not create one.

Parameters:

Name	Type	Description	Default
`po_line_id`	`str`	The PO line identifier, e.g. `POL-12345`.	required
`item_pid`	`str`	The process ID of the item being received.	required
`receive_date`	`date \| None`	Date of receipt. Defaults to Alma's own default (now) when omitted. Serialised as `YYYY-MM-DDZ`.	`None`
`department`	`str \| None`	Code of the receiving department.	`None`
`department_library`	`str \| None`	Code of the library owning the receiving department.	`None`
`updated_item`	`Body \| None`	Optional item record to apply as part of receiving, for example to set a barcode or enumeration at the same time. An empty body is sent when omitted.	`None`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The received item record.

Raises:

Type	Description
`APIClientError`	If the PO line or item does not exist, or the department codes are not valid for this institution.

Examples:

from datetime import date

item = await client.acq.receive_existing_item(
    "POL-12345",
    "23456789000000541",
    receive_date=date(2026, 7, 29),
    department="ACQ_DEPT",
    department_library="MAIN",
)

cancel_po_line `async` Alma: Cancel PO-Line ¶

cancel_po_line(
    po_line_id: str,
    reason_code: str,
    *,
    comment: str | None = None,
    inform_vendor: bool = False,
    override: bool = False,
    bib_handling: Literal[
        "retain", "delete", "suppress"
    ] = "retain",
) -> None

Cancel a purchase order line.

Parameters:

Name	Type	Description	Default
`po_line_id`	`str`	The PO line identifier, e.g. `POL-12345`.	required
`reason_code`	`str`	Cancellation reason. Must be a code from the `POLineCancellationReasons` code table – fetch the valid values with `client.config.code_tables.get_code_table()`.	required
`comment`	`str \| None`	Free-text note recorded against the cancellation.	`None`
`inform_vendor`	`bool`	Whether Alma should notify the vendor.	`False`
`override`	`bool`	Whether to override Alma's cancellation warnings, for example when the line has already been partly received.	`False`
`bib_handling`	`Literal['retain', 'delete', 'suppress']`	What to do with the associated bibliographic record – `"retain"` leaves it, `"delete"` removes it, `"suppress"` hides it from discovery.	`'retain'`

Returns:

Type	Description
`None`	`None`. Alma returns an empty body for a successful cancellation.

Raises:

Type	Description
`APIClientError`	If the PO line does not exist, the reason code is not valid, or Alma refuses the cancellation and `override` is False.

Examples:

await client.acq.cancel_po_line(
    "POL-12345",
    "LIBRARY_CANCELLED",
    comment="Duplicate order",
    inform_vendor=True,
)

Acquisitions¶

AlmaClientAcqNS ¶

get_po_line async Alma: Get PO-Line ¶

update_po_line async Alma: Update PO-Line ¶

receive_existing_item async Alma: Receive an Existing Item ¶

cancel_po_line async Alma: Cancel PO-Line ¶

get_po_line `async` Alma: Get PO-Line ¶

update_po_line `async` Alma: Update PO-Line ¶

receive_existing_item `async` Alma: Receive an Existing Item ¶

cancel_po_line `async` Alma: Cancel PO-Line ¶