Tech Blog

Alma – ERP invoices integration using APIs

The Alma acquisitions process includes ordering and receiving materials from vendors, which involves the handling of both orders and invoices by vendors.

Invoices are handled outside of the library’s scope, usually by the institution’s Enterprise Resource Planning (ERP) system. Invoices must therefore be exported from Alma to the institution’s financial system. Institutions that want to receive confirmation about the invoice status in the Enterprise Resource Planning (ERP) system, can import the invoices from the ERP back into Alma.

Traditionally, the export and import of invoices was done using FTP servers. See Alma – Finance integration. The December 2018 Alma release includes several new APIs for utilizing invoices integration using APIs.

The purpose of this blog is to describe in details the required steps for implementing end-to-end invoices integration with finance system using APIs.

1. Retrieve invoices for ERP handling – status code is “waiting to be sent”:
GET /almaws/v1/acq/invoices?invoice_workflow_status=Waiting to be Sent&view=brief

The response will include a list of invoices that should be handled by the ERP.

2. ERP starts working on the invoice, so marks it as in ERP:
POST /almaws/v1/acq/invoices/<invoice id>?op=mark_in_erp

Payload should be an empty invoice object:


Note that the status of the invoice is updated according to the institution’s workflow (handle_invoice_payment parameter): If a confirmation should be returned from ERP, the status will be updated to “Waiting for Payment”. Else, the invoice will be closed. This logic is the same as in the “Invoice export” job.

3. For institutions that work with confirmation from ERP, ERP should update the invoice as “paid” or as “rejected“:
POST /almaws/v1/acq/invoices/{invoice id}?op=paid/rejected

If the invoice is rejected, a note must be specified in the payload including the reject reason:

         <content>Rejected becuase no confirmation from manager</content>


If the invoice is paid, payment information can be specified in the payload, as well as explicit ratio if it was used by the ERP:

   <voucher_currency desc="US Dollar">USD</voucher_currency>
   <voucher_number>Release review</voucher_number>


7 Replies to “Alma – ERP invoices integration using APIs”

  1. if I’m using the JSON api how do I handle the payload. I tested it a few ways in postman but the only way to make a request seems to be with a XML payload. This is an issue if the library is generated with openapi as you sometimes have to pick a path, xml or json, and changing headers/content for one request is difficult. I would prefer not to have to write XML

    1. Hi David. You can use JSON to make the POST request. You just need to send an empty JSON object as the body.

      See this curl request as an example:

      curl "{{ID}}?op=mark_in_erp" \
      -X POST \
      -d "{}" \
      -H "Authorization: apikey {{APIKEY}}" \
      -H "Accept: application/json" \
      -H "Content-type: application/json"

  2. Hi Tamar,

    what about the corresponding po line? After the op=paid on the invoice, the po-line is still open. What is the best way to close the po line as well if it is fully paid?

  3. Hi Eike,
    Thanks for the comment.
    You are correct that the PO line should close once the invoice is paid (if it is a one time PO line).
    This is something we’ll work on to correct. You can open a case if you want to be notified when it’s fixed.


Leave a Reply