API Docs

Rest Invoice

Overview


An invoice is received from a vendor which provided material to the institution.
After an invoice is created, it is processed and checked. If there are data issues or alerts, it is sent to manual review.
Note that invoice 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 invoice's situation.
PUT action is not allowed for invoice in the following stauses: In Approval (code: InApproval), Ready to be Paid (code: Waiting to be Sent).
when the invoice is in the following statuses: Waiting for Payment (code: Ready to be Paid), Closed (code: CLOSED), only the following fields can be updated:
report_tax, explicit_ratios, notes, payment_status, voucher_number, voucher_date, voucher_amount, voucher_currency.

Data Dictionary

Click here to download rest_invoice.xsd

invoice

Description: Invoice Object.

FieldTypeDescription
idstring
Unique identifier of the invoice. Output parameter.
Should be used in subsequent queries regarding the invoice.
numberstringThe invoice number as received from the vendor. Mandatory.
invoice_datedateThe invoice date. Mandatory.
invoice_due_datedateThe invoice due date.
vendorstring with attr. The code of the vendor to whom the invoice is to be issued. Mandatory.
vendor_accountstringThe vendor account for this invoice.
total_amountdecimalThe total invoice amount. Mandatory.
currencystring with attr. The invoice currency.
Possible values are listed in 'Currency_CT' code table.
Default is the institution's currency.

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
total_invoice_lines_amountdecimalThe total price of existing invoice lines. Output parameter.
vendor_contact_personcontact_personThe contact person at the vendor dealing with this invoice. Output parameter.
payment_methodstring with attr. Payment method for the invoice.
Possible values are listed in 'PaymentMethod' code table.
Default is 'Accounting Department'.

The valid values for this parameter are controlled by the code-table: PaymentMethod. These are the currently defined values for your institution:
CodeDescription
reference_numberstringA reference number for the invoice, to enable grouping of invoices for reporting.
creation_formstring with attr. The source in which the invoice was initially created. Output parameter.
Possible codes are listed in 'InvoiceCreationForm' code table.

The valid values for this parameter are controlled by the code-table: InvoiceCreationForm. These are the currently defined values for your institution:
CodeDescription
ownerstring with attr.
The invoice owner.
This can be the institution code or a library code.
Default is the institution.
This field cannot be updated.

The valid values for this parameter are the library codes. These are the currently defined values for your institution:
CodeDescription
invoice_statusstring with attr. The invoice status. Output parameter.
Possible codes are: ACTIVE, CLOSED.
invoice_workflow_statusstring with attr. The invoice status in workflow. Output parameter.
Possible codes are listed in 'InvoiceStatus' code table.

The valid values for this parameter are controlled by the code-table: InvoiceStatus. These are the currently defined values for your institution:
CodeDescription
invoice_approval_statusstring with attr. The invoice approval status. Output parameter.
Possible codes are listed in 'InvoiceApprovalStatus' code table.

The valid values for this parameter are controlled by the code-table: InvoiceApprovalStatus. These are the currently defined values for your institution:
CodeDescription
approved_bystringThe primary key of the operator which made the approval. Output parameter.
approval_datedateThe date of the approval. Output parameter
additional_chargesadditional_chargesAdditional charges that are included in the invoice.
invoice_vatinvoice_vatVAT charge that is included in the invoice.
explicit_ratiosexplicit_ratios
List of exchange rates between the invoice currency and foreign currencies.
Relevant only if the institution has ledgers in more than one currency.
In the PUT action the incoming list will replace the existing list. If the incoming list is empty, the existing list will be deleted.
This field is relevant in POST /almaws/v1/acq/invoices/invoice ID?op=paid.
paymentpaymentPayment information.
alertsalertsList of Alerts that blocked the processing of the
invoice. Output parameter.
notesnotesList of the invoice 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.
This field can be included in POST /almaws/v1/acq/invoices/invoice ID?op=paid.
number_of_linesint with attr.
A count of the number of lines.
Output parameter.
invoice_linesinvoice_linesList of invoice lines. Output parameter.
When view=brief, invoice_lines will not be returned.
number_of_attachmentsint with attr. Number of attachments. Output parameter.

 

invoice_vat

Description: VAT charge that is included in the invoice.

FieldTypeDescription
report_taxbooleanIndication whether governmental vendor can be configured to receive use tax (VAT) on this invoice.
Default is false.
vat_per_invoice_linebooleanIndication whether the invoice vat is in invoice line level. Default is false.
vat_codestring with attr. VAT code to assign to the invoice.
If supplied, percentage and vat_amount will be defined accordingly.
Possible values are according to the VATCodes_MT mapping table.
percentagedecimalVAT Percentage of the invoice total amount.
In POST and PUT actions, percentage or vat_amount should be supplied, but not both.
If vat_code is defined, percentage and vat_amount should be left empty in these actions.
vat_amountdecimalAmount of VAT to be paid on the invoice.
In POST and PUT actions, percentage or vat_amount should be supplied, but not both. If vat_code is defined, percentage and vat_amount should be left empty in these actions.
typestring with attr. Inclusive: the invoice total amount includes VAT.
Exclusive: VAT is added above the invoice total amount.
Line Exclusive: the invoice's total amount includes VAT, but the VAT amount is calculated outside of the invoice lines' total value and is not factored into the individual invoice lines.
Possible codes are listed in 'InvoiceStatus' code table. Default is 'Inclusive'.

The valid values for this parameter are controlled by the code-table: VATType. These are the currently defined values for your institution:
CodeDescription
expended_from_fundbooleanIndication whether the VAT amount is expended from the invoice line's fund.
If set to false, the VAT amount is expended from a separate fund (adjustment invoice line). Default is true.
vendor_taxstringTextual note that indicates that the invoice is in a foreign currency and the VAT is charged in the local currency.

 

additional_charges

Description: Additional charges that are included in the invoice.

FieldTypeDescription
use_pro_ratabooleanIndication whether additional charges should be prorate over all invoice lines.
Default is according to invoice_use_pro_rata parameter setup.
shipmentdecimalThe amount of shipment charge.
overheaddecimalThe amount of overhead charge.
insurancedecimalThe amount of insurance charge.
discountdecimalThe amount of discount charge.

 

payment

Description: Payment information.

FieldTypeDescription
prepaidbooleanIndication if the invoice is already paid.
True is valid only when the payment method is not Accounting department, and the invoice is not an internal copy.
Optional. Default is False.
internal_copybooleanIndication if the invoice is to be loaded into Alma for documentation or tracking purposes.
Such invoice is not sent to the ERP and is not prepaid. Optional. Default is False.
export_to_erpbooleanIndication if the invoice should be sent to the (ERP) for notification purposes.
Internal copy invoices cannot be sent to ERP. Optional. Default is False.
payment_statusstring with attr. the payment status.
Possible codes are listed in 'PaymentStatus' code table. Default is 'Not Paid'.

The valid values for this parameter are controlled by the code-table: PaymentStatus. These are the currently defined values for your institution:
CodeDescription
voucher_datedateThe date of the payment. Default is current date.
This field is relevant in POST /almaws/v1/acq/invoices/invoice ID?op=paid.
voucher_numberstringAn external reference number from the ERP system, used to indicate that the invoice was paid.
If there is no integration with an external system, you can enter an invoice or check number in this field.
This field is relevant in POST /almaws/v1/acq/invoices/invoice ID?op=paid.
voucher_amountstringThe final amount that was paid (after exchange rates and so forth are taken into account).
This field is relevant in POST /almaws/v1/acq/invoices/invoice ID?op=paid.
voucher_currencystring with attr. The voucher currency.
Possible values are listed in 'Currency_CT' code table.
This field is relevant in POST /almaws/v1/acq/invoices/invoice ID?op=paid.

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

 

explicit_ratios

Description: List of exchange rates between the invoice currency and foreign currencies.
Relevant only if the institution has ledgers in more than one currency.
In the PUT action the incoming list will replace the existing list. If the incoming list is empty, the existing list will be deleted.
This field is relevant in POST /almaws/v1/acq/invoices/invoice ID?op=paid.

FieldTypeDescription
explicit_ratioexplicit_ratioExchange rate between the invoice currency and foreign currency.
Relevant only if the institution has ledgers in more than one currency.
This field is relevant in POST /almaws/v1/acq/invoices/invoice ID?op=paid.

 

explicit_ratio

Description: Exchange rate between the invoice currency and foreign currency.
Relevant only if the institution has ledgers in more than one currency.

FieldTypeDescription
foreign_currencystring with attr. The foreign currency.
Possible values are listed in 'Currency_CT' code table.
This field is relevant in POST /almaws/v1/acq/invoices/invoice ID?op=paid.

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
ratedecimalRate for forgein currency exchange.
This field is relevant in POST /almaws/v1/acq/invoices/invoice ID?op=paid.

 

alerts

Description: List of Alerts that blocked the processing of the invoice. 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_InvoiceAssertions_by_CT_AssertionCodes. These are the currently defined values for your institution:
CodeDescription

 

contact_person

Description: The contact person at the vendor dealing with this invoice. Output parameter.

FieldTypeDescription
first_namestringThe contact person's first name. Output parameter.
last_namestringThe contact person's last name. Output parameter.

 

Samples

XML
JSON
__