--- sourceDocument: Yokohama API Reference sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference Release : - yokohama ft:locale : - en-US ft:publication_title : - Yokohama API Reference ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # AP Invoice API # AP Invoice API {#ariaid-title1} * Release version: Yokohama * * Updated January 30, 2025 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 33 minutes to read Allows external systems, such as those used by vendors, to securely submit invoices directly into an accounts payable system in a structured and automated manner. This API requires the Accounts Payable Invoice Processing (com.sn_ap_apm) store application, which is provided within the `sn_spend_intg` namespace. For information, see [Accounts Payable Invoice Processing](https://www.servicenow.com/docs/access?context=acc-pay-invoice-processing&version=yokohama&pubname=yokohama-source-to-pay-operations&ft:locale=en-US). Refer to [AP Invoice API Developer Guide](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-dev-guide "This developer guide describes how to define custom invoice fields that aren’t provided by default with the AP Invoice API for Accounts Payable Invoice Processing. Instructions are also provided for setting authentication when using cXML as the payload.") for help with the following tasks: * Define a custom field for invoices, invoice lines, and invoice tax lines. * Map the custom field between source and target tables. * Map the custom field to a payload entry in a specific format, such as JSON, cXML, or XML. * Setting credentials for authentication when using cXML as the payload. {#ap-invoice-api__ul_nns_lmr_tdc} Note: The maximum default payload size is 100 records. This value is configurable in the sn_spend_intg.ap.invoice.create.api.record_limit system property. ## AP Invoice -- POST sn_spend_intg/ap_invoice/cxml {#ariaid-title2} Processes an automated invoice in commerce XML (cXML) format. Use the Invoice integration field mappings \[sn_spend_intg_invoice_intg_field_mapping\] table to determine how the fields are mapped to cXML tags. For additional cXML resources, refer to the cXML Reference Guide at [https://xml.cxml.org](https://xml.cxml.org/current/cXMLReferenceGuide.pdf). Credentials for this API are included in the payload. You can set up credentials in the Source system credential \[sn_spend_intg_source_system_credential\] table. For instructions, see [Setting credentials for authentication in the cXML payload](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-setCxmlCreds "The sn_spend_intg/ap_invoice/cxml endpoint is authenticated in the payload using credentials stored in the Source System Credential [sn_spend_intg_source_system_credential] table."). You can define custom invoice fields for the request body. Use the following flow to add custom fields, map them to target tables, and format them for availability in the payload: 1. [Add custom fields for invoice import](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-addColToTable "Use the following procedure to add custom fields for invoices, invoice lines, and invoice tax lines to be used with the AP Invoice API.") 2. [Map custom fields between source and target tables](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-mapFieldsTransform "Use the following procedure to map custom fields between source and target tables for the AP Invoice API.") 3. [Map custom fields to a payload source format](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-mapFieldsTSrcFormat "Use the following procedure to map custom fields to a payload entry in JSON, cXML, or XML for the AP Invoice API.") {#ap_invoice-POST-cxml__ul_kcx_5fx_sdc} ### URL format Versioned URL: /api/sn_spend_intg/v1/ap_invoice/cxml Default URL: /api/sn_spend_intg/ap_invoice/cxml ### Supported request parameters {#ap_invoice-POST-cxml__entry__2}{#ap_invoice-POST-cxml__version-not_optional-RESTAPI} | Name | Description | |-|-| | api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String | [Table 1. Path parameters] {#ap_invoice-POST-cxml__entry__6} | Name | Description | |-|-| | None | | [Table 2. Query parameters] {#ap_invoice-POST-cxml__entry__10} | Path | Description | |-|-| | /cXML/Header/From /Credential\[@domain='VendorID'\]/Identity | Identifier for the reseller or supplier that the customer can place orders with. Target field: u_supplier Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest /InvoiceDetailRequestHeader\[@invoiceDate\] | Date on which the customer was invoiced. Target field: u_invoice_date Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Format: YYYY-MM-DD | | /cXML/Request/InvoiceDetailRequest /InvoiceDetailRequestHeader\[@invoiceID\] | Invoice number generated from a third-party application. Target field: u_external_invoice_number Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest /InvoiceDetailRequestHeader\[@invoiceOrigin\] | External source system from where the invoice is received. For example, supplier. Target field: u_inbound_source Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest /InvoiceDetailRequestHeader/InvoicePartner /Contact\[@role='billTo'\]/PostalAddress/City | The city to which the invoice is sent. Target field: u_bill_to_city Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest /InvoiceDetailRequestHeader/InvoicePartner /Contact\[@role='billTo'\]/PostalAddress/Country | The country to which the invoice is sent in ISO 3166 format. For example, `US`. Target field: u_bill_to_country Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest /InvoiceDetailRequestHeader/InvoicePartner /Contact\[@role='billTo'\]/PostalAddress/State | The state or province to which the invoice is sent. Target field: u_bill_to_state_or_province Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest /InvoiceDetailRequestHeader/InvoicePartner /Contact\[@role='billTo'\]/PostalAddress/Street | The street address to which the invoice is sent. Target field: u_bill_to_street Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest /InvoiceDetailRequestHeader/InvoicePartner /Contact\[@role='billTo'\]/PostalAddress/PostalCode | The zip or postal code to which the invoice is sent. Target field: u_bill_to_zip_or_postal_code | | Contact\[@role="remitTo"\]/PostalAddress /Street | The street address to which the payment is made. Target field: u_remit_address | | Contact\[@role="remitTo"\]/PostalAddress /City | The city to which the payment is made. Target field: u_remit_to_city | | Contact\[@role="remitTo"\]/PostalAddress /State | The state or province to which the payment is made. Target field: u_remit_to_state_or_province | | Contact\[@role="remitTo"\]/PostalAddress /PostalCode | The zip or postal code to which the payment is made. Target field: u_remit_to_zip_or_postal_code | | Contact\[@role="remitTo"\]/PostalAddress /Country | The country to which the payment is made in ISO 3166 format. For example, `US`. Target field: u_remit_to_country | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader /InvoiceDetailShipping/Contact\[@role="shipFrom"\]/PostalAddress /Street | Street from which the items on the purchase order are shipped. Target field: u_ship_from_street Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader /InvoiceDetailShipping/Contact\[@role="shipFrom"\]/PostalAddress /City | City from which the items on the purchase order are shipped. Target field: u_ship_from_city Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader /InvoiceDetailShipping/Contact\[@role="shipFrom"\]/PostalAddress /State | State from which the items on the purchase order are shipped. Target field: u_ship_from_state_or_province Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader /InvoiceDetailShipping/Contact\[@role="shipFrom"\]/PostalAddress /PostalCode | Zip code from which the items on the purchase order are shipped. Target field: u_ship_from_zip_or_postal_code Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader /InvoiceDetailShipping/Contact\[@role="shipFrom"\]/PostalAddress /Country | Country from which the items on the purchase order are shipped. Target field: u_ship_from_country Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader /InvoicePartner/Contact\[@role="billTo"\] \[@addressID\] | Name of the legal entity of the supplier. Located in the Legal Entity \[sn_fin_legal_entity\] table. Target field: u_legal_entity Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | Contact\[@role="shipTo"\]/Name | Name of the contact to which the items on the purchase order should be shipped. Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | Contact\[@role="shipTo"\]/PostalAddress /Street | Street to which the items on the purchase order are shipped. Target field: u_ship_to_street Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | Contact\[@role="shipTo"\]/PostalAddress /City | City to which the items on the purchase order are shipped. Target field: u_ship_to_city Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | Contact\[@role="shipTo"\]/PostalAddress /State | State or province to which the items on the purchase order are shipped. Target field: u_ship_to_state_or_province | | Contact\[@role="shipTo"\]/PostalAddress /PostalCode | Zip code to which the items on the purchase order are shipped. Target field: u_ship_to_zip_or_postal_code Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | Contact\[@role="shipTo"\]/PostalAddress /Country | Country to which the items on the purchase order are shipped. Target field: u_ship_from_country Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest /InvoiceDetailRequestHeader/PaymentTerm | The agreed upon time and conditions under which a payment to a supplier is made. For example, `Net 30`. Target field: u_payment_terms Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem\[@description\]/ | Description of the invoice line. Target field: u_line_description | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem\[@quantity\]/ | Quantity of goods or services that a customer is being invoiced for. Target field: u_line_quantity | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/Distribution/Accounting /AccountingSegment\[1\]/Name | Account number of the cost center for which the invoice is generated. Listed in the Cost Center \[cmn_cost_center\] table. Target field: u_cost_center | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/Distribution/Accounting /AccountingSegment\[2\]/Name | Account number of the general ledger (GL) used to generate the invoice. Target field: u_gl_account See also: * [ERP source](https://www.servicenow.com/docs/access?context=erp-source&version=yokohama&pubname=yokohama-source-to-pay-operations&ft:locale=en-US) * [Ledger account](https://www.servicenow.com/docs/access?context=ledger-account&version=yokohama&pubname=yokohama-source-to-pay-operations&ft:locale=en-US) {#ap_invoice-POST-cxml__ul_u23_b3r_cdc} | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/SubtotalAmount/Money | Total amount of money to be paid to the supplier excluding tax and shipping charges. Target field: u_subtotal Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/NetAmount/Money | Total cost, excluding taxes and shipping, that a customer is being invoiced for a given purchase order line. Target field: u_line_amount_invoiced Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailOrderInfo/OrderReference | Purchase order number that is provided by the customer for this order. Listed in the Purchase Order \[sn_shop_purchase_order\] table. Target field: u_purchase_order Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/UnitPrice/UnitOfMeasure | Base unit of measure (UOM) used to count the item in the invoice. Target field: u_uom Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/UnitPrice/Money | Unit price of the line item in the invoice. Target field: u_line_unit_price Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/UnitPrice/Money\[@currency\] | Currency for the line item. For example, `USD`. Target field: u_currency Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem /InvoiceDetailItemReference\[@lineNumber\] | Purchase order line ID for the referenced supplier. Listed in the Purchase Order Line \[sn_shop_purchase_order_line\] table. Target field: u_purchase_order_line Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/InvoiceDetailItemReference /ItemID/SupplierPartID | Part number that is generated by a supplier for this invoice line. Target field: u_supplier_part_number Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/InvoiceDetailItemReference /Description | Description of the purchase order line for the invoice. Target field: u_po_line_description Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/Tax/Money | Total amount of taxes that are billed for the purchase. Target field: u_tax_amount Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder /InvoiceDetailItem/Tax/Description | Unique tax code generated from the ERP source. Target field: u_tax_code Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /cXML/Request/InvoiceDetailRequest/ InvoiceDetailSummary /SubtotalAmount/Money | Total amount of money to be paid to the supplier excluding tax and shipping charges. Target field: u_subtotal Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary /Tax/Money | Total amount of taxes that are billed for the purchase. Target field: u_tax_amount Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary /Tax/TaxDetail\[@category\] | Type of tax applicable on the invoice. Listed in the Tax Type \[sn_fin_tax_type\] table. Target field: u_tax_type Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary /Tax/TaxDetail\[@percentageRate\] | The tax rate charged by the supplier. Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] Target field: u_supplier_tax_rate Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary /SpecialHandlingAmount/Money | Other additional charges associated with the invoice. This is an editable field. Target field: u_other_charges Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary /ShippingAmount/Money | Total shipping cost for the entire purchase. Target field: u_shipping_amount Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary /GrossAmount/Money | Required. Currency for subtotal, tax, and shipping. The subtotal, tax, and shipping should be in the same currency. Target field: u_currency Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary /InvoiceDetailDiscount/Money | Discounts that are applied toward the invoice. Target field: u_discounts Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary /NetAmount/Money | Total amount of money to be paid to the supplier including tax and shipping charges. Target field: u_amount_invoiced Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | [Table 3. Request body elements (cXML)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#ap_invoice-POST-cxml__entry__114} | Header | Description | |-|-| | Content-Type | Data format of the request body. Only supports application/xml. | | Source-System | Specifies the source system from which the request is coming from. Available systems are listed in the Source systems credentials \[sn_spend_intg_source_system_credential\] table. This setting helps to determine if the request provided follows the structure in the Invoice integration field mapping \[sn_spend_intg_invoice_intg_field_mapping\] table. This setting is also used to fetch credentials from the Source system credentials \[sn_spend_intg_source_system_credential\] table. | [Table 4. Request headers] {#ap_invoice-POST-cxml__entry__120} | Header | Description | |-|-| | None | | [Table 5. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#ap_invoice-POST-cxml__table_wqv_qxk_ddc__entry__2}{#ap_invoice-POST-cxml__entry-400-status-code} | Status code | Description | |-|-| | 202 | Request Accepted. The request is successful and invoice processing is in progress. | | 400 | Bad Request. A bad request type or malformed request was detected. | | 429 | Too Many Requests. The request rate has exceeded the maximum of 10 requests per hour. | [Table 6. Status codes] {#ap_invoice-POST-cxml__table_wqv_qxk_ddc} ### Response body parameters {#ap_invoice-POST-cxml__entry__132} | Name | Description | |-|-| | batch_id | Unique identifier for the batch request. This ID can be used to track the status of the request. This record is stored in the Invoice integration log \[sn_spend_intg_invoice_integration_log\] table. Data type: String | | error | Contains error message and details when the request fails. { "detail": String, "message": String } Data type: Object | | error.detail | Additional details about the request error. Possible results: * Failed API level ACL Validation - User does not have read/write access to the resource. * Rate limit of 13 requests per hour for AP Invoice exceeded -- The number of records in the batch is more than the batch size set. * Required to provide Auth information - Either the password is wrong or user name is wrong. {#ap_invoice-POST-cxml__ul_ukg_sht_c2c} Data type: String | | error.message | Error message containing the reason the request failed Possible errors: * Invalid payload - Invalid content type. * Invalid payload - Error: Invalid payload structure. * Invalid payload - Error: Payload exceeds allowed invoices limit in a batch. The number of records in the batch is more than the batch size set. The maximum default payload size is 100 records. This value is configurable in the sn_spend_intg.ap.invoice.create.api.record_limit system property. * Invalid payload - Error: Empty invoices. No data to process. The number of records in the batch is zero. * Rate limit of 500 requests per hour for APO Invoice Ingestion exceeded. * User Not Authenticated. Either the password is wrong or user name is wrong. * Failed API level ACL Validation - User does not have read/write access to the resource. {#ap_invoice-POST-cxml__ul_knb_fhr_2dc} Data type: String | | message | Success message, for example, Your request has been successfully received and is being processed. You can view the status of the request in the Invoice integration log \[sn_spend_intg_invoice_integration_log\] table. Data type: String | | status | Indicates the result of the request. Possible values: * Success * Fail {#ap_invoice-POST-cxml__ul_zfp_shr_2dc} Data type: String | [ ] ### cURL request {#ap_invoice-POST-cxml__example_mnp_3dm_ddc} The following example shows how to process an invoice provided as a request in cXML format. curl -X POST https://instance.servicenow.com/api/sn_spend_intg/v1/ap_invoice/cxml \ -H "Source-System: Ariba" \ -H "Content-Type: application/json" \ -d '{ "content": "------=_Part_1367_1859161670.1709186492411\r\nContent-Type: text/xml; charset=UTF-8\r\n Content-ID: 1709186492411.10815535@produs-c4-an-s2-z3-1.us2.gcpint.ariba.com\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n 186492411.10815535@produs-c4-an-s2-z3-1.us2.gcpint.ariba.com.110\r\n \r\n \r\n 1709186492403.306612238@produs-c4-an-s2-z3-1.us2.gcpint.ariba.com.108 \r\n \r\n \r\n \r\n\r\n------=_Part_1367_1859161670.1709186492411 \r\nContent-Type: text/xml; charset=UTF-8\r\nContent-ID: 1709186492403.306612238@produs-c4-an-s2-z3-1.us2.gcpint.ariba.com.108 \r\n\r\n \r\n \r\n
\r\n \r\n \r\n AN01532216648-T\r\n \r\n \r\n 3245545\r\n \r\n \r\n 0000099123\r\n \r\n \r\n \r\n \r\n AN01404744424-T\r\n \r\n \r\n ERP1\r\n \r\n \r\n CIG\r\n \r\n \r\n \r\n \r\n AN01000000001\r\n Ariba@123\r\n \r\n Supplier\r\n \r\n
\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n Oil and Natural Gas Corporation Limited\r\n \r\n Xyz street\r\n USA\r\n NY\r\n 10001\r\n United States\r\n \r\n \r\n \r\n \r\n \r\n Bristlecone Inc\r\n \r\n 10 Boulvard-10\r\n San Jose\r\n CA\r\n 94077\r\n \r\n \r\n \r\n \r\n 1\r\n 7687687799\r\n \r\n \r\n \r\n \r\n 1\r\n 768-FAX-NUMBER\r\n \r\n \r\n \r\n \r\n \r\n \r\n Oil and Natural Gas Corporation Limited\r\n \r\n 123 , street no 5\r\n Dallas\r\n AL\r\n 36615\r\n United States\r\n \r\n \r\n \r\n \r\n \r\n Oil and Natural Gas Corporation Limited\r\n \r\n Deendayal Urja Bhawan\r\n New Delhi\r\n Maharashtra\r\n 110070\r\n India\r\n \r\n \r\n \r\n Buyer Plant Bristlecone\r\n \r\n 18 Hanoi Road\r\n San Jose\r\n CA\r\n 77077\r\n \r\n \r\n test@test.com\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n EA\r\n \r\n 50\r\n \r\n \r\n 1250.00\r\n \r\n \r\n \r\n \r\n \r\n\r\n------=_Part_1367_1859161670.1709186492411--" }' The following result shows that the request is successful and the invoice data is processing. You can view the status of the request in the Invoice integration log \[sn_spend_intg_invoice_integration_log\] table. Use the batch ID listed in the Batch ID column to find the invoice. { "batchId": "APIINV1729711710733280", "status": "Success", "message": "Your request has been successfully received and is being processed." } ## AP Invoice -- POST sn_spend_intg/ap_invoice/json {#ariaid-title3} Processes an automated invoice in JSON format. Role required: sn_spend_intg.procurement_integrator Use the Invoice integration field mappings \[sn_spend_intg_invoice_intg_field_mapping\] table to determine how the fields are mapped to JSON properties. You can define custom invoice fields for the request body. Use the following flow to add custom fields, map them to target tables, and format them for availability in the payload: 1. [Add custom fields for invoice import](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-addColToTable "Use the following procedure to add custom fields for invoices, invoice lines, and invoice tax lines to be used with the AP Invoice API.") 2. [Map custom fields between source and target tables](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-mapFieldsTransform "Use the following procedure to map custom fields between source and target tables for the AP Invoice API.") 3. [Map custom fields to a payload source format](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-mapFieldsTSrcFormat "Use the following procedure to map custom fields to a payload entry in JSON, cXML, or XML for the AP Invoice API.") {#ap_invoice-POST-json__ul_kcx_5fx_sdc} ### URL format Versioned URL: /api/sn_spend_intg/v1/ap_invoice/json Default URL: /api/sn_spend_intg/ap_invoice/json ### Supported request parameters {#ap_invoice-POST-json__entry__2}{#ap_invoice-POST-json__version-not_optional-RESTAPI} | Name | Description | |-|-| | api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String | [Table 7. Path parameters] {#ap_invoice-POST-json__entry__6} | Name | Description | |-|-| | None | | [Table 8. Query parameters] {#ap_invoice-POST-json__entry__10} | Name | Description | |-|-| | invoices | List containing each invoice to be processed. Data type: Object of nested invoice objects. "invoices": { { "amount_invoiced": "String", "bill_to_city": "String", "bill_to_country": "String", "bill_to_state_or_province": "String", "bill_to_street": "String", "bill_to_zip_or_postal_code": "String", "business_owner": "String", "currency": "String", "discounts": "String", "erp_number": "String", "external_invoice_number": "String", "invoice_date": "String", "invoice_line_count": "String", "invoice_lines": [Array], "invoice_type": "String", "legal_entity": "String", "original_invoice": "String", "other_charges": "String", "payment_terms": "String", "purchase_order": "String", "remit_address": "String", "remit_to_city": "String", "remit_to_country": "String", "remit_to_state_or_province": "String", "remit_to_zip_or_postal_code": "String", "ship_from_city": "String", "ship_from_country": "String", "ship_from_state_or_province": "String", "ship_from_street": "String", "ship_from_zip_or_postal_code": "String", "ship_to_city": "String", "ship_to_country": "String", "ship_to_state_or_province": "String", "ship_to_street": "String", "ship_to_zip_or_postal_code": "String", "shipping_amount": "String", "subtotal": "String", "supplier": "String", "supplier_invoice_number": "String", "supplier_tax_id": "String" } } | | invoices.amount_invoiced | Total amount of money to be paid to the supplier including tax and shipping charges. Target field: u_amount_invoiced Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | bill_to_city | The city to which the invoice is sent. Target field: u_bill_to_city Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | bill_to_country | The country to which the invoice is sent in ISO 3166 format. For example, `US`. Target field: u_bill_to_country Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | bill_to_state_or_province | The state or province to which the invoice is sent. Target field: u_bill_to_state_or_province Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | bill_to_street | The street address to which the invoice is sent. Target field: u_bill_to_street Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | bill_to_zip_or_postal_code | The zip or postal code to which the invoice is sent. Target field: u_bill_to_zip_or_postal_code | | invoices.business_owner | Name of the owner who owns the application from the business side. Target field: u_business_owner Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | invoices.currency | Required. Currency for subtotal, tax, and shipping. The subtotal, tax, and shipping should be in the same currency. Target field: u_currency Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | invoices.discounts | Discounts that are applied toward the invoice. Target field: u_discounts Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.erp_number | Unique number generated within the ERP (Enterprise Resource Planning) system for the purchase order. For information, see [Purchase order integration](https://www.servicenow.com/docs/access?context=purchase-order-integration-2&version=yokohama&pubname=yokohama-source-to-pay-operations&ft:locale=en-US). Target field: u_erp_number Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | invoices. external_invoice_number | Required. Invoice number generated from a third-party application. Target field: u_external_invoice_number Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | invoices.invoice_date | Required. Date on which the customer was invoiced. Target field: u_invoice_date Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 Format: YYYY-MM-DD | | invoices.invoice_line_count | Number of lines in the invoice. Target field: u_invoice_line_count Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | invoices.invoice_lines | List of objects that define the lines that are being invoiced for purchases within this order. Invoice lines are staged in the Invoice line import inbound \[sn_spend_intg_imp_invoice_line\] table. Data type: Array "invoice_lines": [ { "cost_center": "String", "currency": "String", "external_invoice_number": "String", "gl_account": "String", "line_amount_invoiced": "String", "line_description": "String", "line_quantity": "String", "line_unit_price": "String", "po_line_description": "String", "purchase_order_line": "String", "ship_to_city": "String", "ship_to_country": "String", "ship_to_state_or_province": "String", "ship_to_street": "String", "ship_to_zip_or_postal_code": "String", "subtotal": "String", "supplier_part_number": "String", "tax_code": "String", "tax_details": [Array], "uom": "String" } ] | | invoices.invoice_lines. cost_center | Account number of the cost center for which the invoice is generated. Listed in the Cost Center \[cmn_cost_center\] table. Target field: u_cost_center Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 40 | | invoices.invoice_lines. currency | Currency for the line item. For example, `USD`. Target field: u_currency Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 40 | | invoices.invoice_lines. external_invoice_number | Required. Invoice number generated from a third-party application. Target field: u_external_invoice_number Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | invoices.invoice_lines. gl_account | Account number of the general ledger (GL) used to generate the invoice. Target field: u_gl_account Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 40 See also: * [ERP source](https://www.servicenow.com/docs/access?context=erp-source&version=yokohama&pubname=yokohama-source-to-pay-operations&ft:locale=en-US) * [Ledger account](https://www.servicenow.com/docs/access?context=ledger-account&version=yokohama&pubname=yokohama-source-to-pay-operations&ft:locale=en-US) {#ap_invoice-POST-json__ul_u23_b3r_cdc} | | invoices.invoice_lines. line_amount_invoiced | Required. Total cost, excluding taxes and shipping, that a customer is being invoiced for a given purchase order line. Target field: u_line_amount_invoiced Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 40 | | invoices.invoice_lines. line_description | Required. Description of the invoice line. Target field: u_line_description Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 40 | | invoices.invoice_lines. line_quantity | Required. Quantity of goods or services that a customer is being invoiced for. Target field: u_line_quantity Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 40 | | invoices.invoice_lines. line_unit_price | Unit price of the line item in the invoice. Target field: u_line_unit_price Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 40 | | invoices.invoice_lines. po_line_description | Description of the purchase order line for the invoice. Target field: u_po_line_description Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 100 | | invoices.invoice_lines. purchase_order_line | Required. Purchase order line ID for the referenced supplier. Listed in the Purchase Order Line \[sn_shop_purchase_order_line\] table. Target field: u_purchase_order_line Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 40 | | invoices.invoice_lines. ship_to_city | City to which the items on the purchase order are shipped. Target field: u_ship_to_city Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 100 | | invoices.invoice_lines. ship_to_country | Country to which the items on the purchase order are shipped. Target field: u_ship_to_country Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 100 | | invoices.invoice_lines. ship_to_state_or_province | State or province to which the items on the purchase order are shipped. Target field: u_ship_to_state_or_province Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 100 | | invoices.invoice_lines. ship_to_street | Street to which the items on the purchase order are shipped. Target field: u_ship_to_street Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 100 | | invoices.invoice_lines. ship_to_zip_or_postal_code | Zip code to which the items on the purchase order are shipped. Target field: u_ship_to_zip_or_postal_code Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] Data type: String Maximum length: 100 | | invoices.invoice_lines. subtotal | Required. Total amount of money to be paid to the supplier excluding tax and shipping charges. Target field: u_subtotal Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.invoice_lines. supplier_part_number | Required. Part number that is generated by a supplier for this invoice line. Target field: u_supplier_part_number Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.invoice_lines. tax_code | Unique tax code generated from the ERP source. Target field: u_tax_code Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.invoice_lines. tax_details | List of tax lines for purchases associated with the invoice line. Data type: Array of Objects "tax_details": [ { "tax_amount": "String", "tax_rate": "String", "tax_type": "String" } ] | | invoices.invoice_lines. tax_details.tax_amount | Required. Total amount of taxes that are billed for the purchase. Target field: u_tax_amount Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] Data type: String Maximum length: 40 | | invoices.invoice_lines. tax_details.tax_rate | The tax rate charged by the supplier. Target field: u_supplier_tax_rate Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] Data type: String Maximum length: 100 | | invoices.invoice_lines. tax_details.tax_type | Type of tax applicable on the invoice. Listed in the Tax Type \[sn_fin_tax_type\] table. Target field: u_tax_type Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] Data type: String Maximum length: 100 | | invoices.invoice_lines.uom | Base unit of measure (UOM) used to count the item in the invoice. Target field: u_uom Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.invoice_type | Type of invoice for processing. Target field: u_invoice_type Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.legal_entity | Name of the legal entity of the supplier. Located in the Legal Entity \[sn_fin_legal_entity\] table. Target field: u_legal_entity Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.original_invoice | Unique invoice number created by the supplier. Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Target field: u_original_invoice Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.other_charges | Other additional charges associated with the invoice. This is an editable field. Target field: u_other_charges Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.payment_terms | The agreed upon time and conditions under which a payment to a supplier is made. For example, `Net 30`. Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.purchase_order | Required. Purchase order number that is provided by the customer for this order. Listed in the Purchase Order \[sn_shop_purchase_order\] table. Target field: u_purchase_order Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | invoices.remit_address | Required. The street address to which the payment is made. Target field: u_remit_address Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.remit_to_city | Required. The city to which the payment is made. Target field: u_remit_to_city Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.remit_to_country | Required. The country to which the payment is made in ISO 3166 format. For example, `US`. Target field: u_remit_to_country Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices. remit_to_state_or_province | Required. The state or province to which the payment is made. Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices. remit_to_zip_or_postal_code | Required. The zip or postal code to which the payment is made. Target field: u_remit_to_state_or_province Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.ship_from_city | City from which the items on the purchase order are shipped. Target field: u_ship_from_city Data type: String Maximum length: 100 | | invoices.ship_from_country | Country from which the items on the purchase order are shipped. Target field: u_ship_from_country Data type: String Maximum length: 100 | | invoices. ship_from_state_or_province | State from which the items on the purchase order are shipped. Target field: u_ship_from_state_or_province Data type: String Maximum length: 100 | | invoices.ship_from_street | Street from which the items on the purchase order are shipped. Target field: u_ship_from_street Data type: String Maximum length: 100 | | invoices. ship_from_zip_or_postal_code | Zip code from which the items on the purchase order are shipped. Target field: u_ship_from_zip_or_postal_code Data type: String Maximum length: 100 | | invoices.ship_to_city | City to which the items on the purchase order are shipped. Target field: u_ship_to_city Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.ship_to_country | Country to which the items on the purchase order are shipped. Target field: u_ship_to_country Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices. ship_to_state_or_province | State to which the items on the purchase order are shipped. Target field: u_ship_to_state_or_province Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.ship_to_street | Street to which the items on the purchase order are shipped. Target field: u_ship_to_street Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices. ship_to_zip_or_postal_code | Zip code to which the items on the purchase order are shipped. Target field: u_ship_to_zip_or_postal_code Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.shipping_amount | Required. Total shipping cost for the entire purchase. Target field: u_shipping_amount Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | invoices.subtotal | Required. Total amount of money to be paid to the supplier excluding tax and shipping charges. Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 40 | | invoices.supplier | Required. Identifier for the reseller or supplier that the customer can place orders with. Target field: u_supplier Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices. supplier_invoice_number | Required. Identification number that is generated by a supplier for this invoice. Target field: u_supplier_invoice_number Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.supplier_tax_id | Tax identifier that is associated with the third party reseller. This is an editable field. Target field: u_supplier_tax_id Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Data type: String Maximum length: 100 | | invoices.target_erp | ERP record in which the invoice is posted. Located in the ERP Source \[sn_fin_erp_source\] table. See [ERP source](https://www.servicenow.com/docs/access?context=erp-source&version=yokohama&pubname=yokohama-source-to-pay-operations&ft:locale=en-US). Data type: String | [Table 9. Request body parameters] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#ap_invoice-POST-json__entry__142} | Header | Description | |-|-| | Content-Type | Data format of the request body. Only supports application/json. | | Source-System | Specifies the source system from which the request is coming from. This setting helps to determine if the request provided follows the structure in the Invoice integration field mapping \[sn_spend_intg_invoice_intg_field_mapping\] table. | [Table 10. Request headers] {#ap_invoice-POST-json__entry__148} | Header | Description | |-|-| | None | | [Table 11. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#ap_invoice-POST-json__table_wqv_qxk_ddc__entry__2}{#ap_invoice-POST-json__entry-400-status-code} | Status code | Description | |-|-| | 202 | Request Accepted. The request is successful and invoice processing is in progress. | | 400 | Bad Request. A bad request type or malformed request was detected. | | 429 | Too Many Requests. The request rate has exceeded the maximum of 10 requests per hour. | [Table 12. Status codes] {#ap_invoice-POST-json__table_wqv_qxk_ddc} ### Response body parameters {#ap_invoice-POST-json__section_hg4_h1l_ddc} {#ap_invoice-POST-json__table_ig4_h1l_ddc__entry__2} | Name | Description | |-|-| | batch_id | Unique identifier for the batch request. This ID can be used to track the status of the request. This record is stored in the Invoice integration log \[sn_spend_intg_invoice_integration_log\] table. Data type: String | | error | Contains error message and details when the request fails. { "detail": String, "message": String } Data type: Object | | error.detail | Additional details about the request error. Possible results: * Failed API level ACL Validation - User does not have read/write access to the resource. * Rate limit of 13 requests per hour for AP Invoice exceeded -- The number of records in the batch is more than the batch size set. * Required to provide Auth information - Either the password is wrong or user name is wrong. {#ap_invoice-POST-json__ul_ukg_sht_c2c} Data type: String | | error.message | Error message containing the reason the request failed Possible errors: * Invalid payload - Invalid content type. * Invalid payload - Error: Invalid payload structure. * Invalid payload - Error: Payload exceeds allowed invoices limit in a batch. The number of records in the batch is more than the batch size set. The maximum default payload size is 100 records. This value is configurable in the sn_spend_intg.ap.invoice.create.api.record_limit system property. * Invalid payload - Error: Empty invoices. No data to process. The number of records in the batch is zero. * Rate limit of 500 requests per hour for APO Invoice Ingestion exceeded. * User Not Authenticated. Either the password is wrong or user name is wrong. * Failed API level ACL Validation - User does not have read/write access to the resource. {#ap_invoice-POST-json__ul_knb_fhr_2dc} Data type: String | | message | Success message, for example, Your request has been successfully received and is being processed. You can view the status of the request in the Invoice integration log \[sn_spend_intg_invoice_integration_log\] table. Data type: String | | status | Indicates the result of the request. Possible values: * Success * Fail {#ap_invoice-POST-json__ul_zfp_shr_2dc} Data type: String | [ ] {#ap_invoice-POST-json__table_ig4_h1l_ddc} ### cURL request The following example shows how to process an invoice provided as a request in JSON format. curl "https://instance.servicenow.com/api/sn_spend_intg/v1/ap_invoice/json" \ --request \ POST \ --header \ "Source-System: Coupa" \ --header \ "Content-Type: application/json" \ --user 'username' \ :'password' \ --data \ '{ "invoices": [ { "invoice_type": "non_po_invoice", "supplier_invoice_number": "SPOTLIGHT98", "external_invoice_number": "SPOTLIGHT98", "erp_number": "RTest12345", "purchase_order": "R0030R16537", "business_owner": "paula.smith@example.com", "supplier": "3245545", "original_invoice": "SIN188191", "invoice_date": "2023-08-15", "payment_terms": "Net 30", "legal_entity": "1000", "subtotal": "100.00", "shipping_amount": "50.00", "other_charges": "20.00", "discounts": "100.00", "amount_invoiced": "150.00", "currency": "USD", "invoice_line_count": "2", "ship_to_city": "", "ship_to_country": "USA", "ship_to_state_or_province": "NY", "ship_to_street": "123 Main St", "ship_to_zip_or_postal_code": "10001", "ship_from_city": "Los Angeles", "ship_from_country": "USA", "ship_from_state_or_province": "CA", "ship_from_street": "456 Oak Ave", "ship_from_zip_or_postal_code": "90001", "remit_address": "789 Elm St, Suite 200", "remit_to_city": "Chicago", "remit_to_country": "USA", "remit_to_state_or_province": "IL", "remit_to_zip_or_postal_code": "60601", "bill_to_city": "San Diego", "bill_to_country": "USA", "bill_to_state_or_province": "CA", "bill_to_street": "4810 Eastgate Mall", "bill_to_zip_or_postal_code": "92121", "supplier_tax_id": "123456789", "tax_details": [ { "tax_type": "Central Goods and Services Tax", "tax_amount": "25", "tax_rate": "" }, { "tax_type": "Sales tax", "tax_amount": "10", "tax_rate": "10" }, { "tax_type": "IGST", "tax_amount": "", "tax_rate": "15" }, { "tax_type": "State Goods and Service Tax", "tax_amount": "20", "tax_rate": "10" } ], "invoice_lines": [ { "external_invoice_number": "SPOTLIGHT98", "line_description": "Laptop", "line_quantity": "5", "line_unit_price": "20.00", "subtotal": "100.00", "line_amount_invoiced": "100.00", "purchase_order_line": "232432", "po_line_description": "Mac laptop", "currency": "USD", "cost_center": "41605600", "gl_account": "141101", "tax_code": "A0 - Sales tax, standard rate", "ship_to_city": "New York", "ship_to_country": "USA", "ship_to_state_or_province": "NY", "ship_to_street": "123 Main St", "ship_to_zip_or_postal_code": "10001", "supplier_part_number": "SPN-001", "uom": "Hours", "tax_details": [ { "tax_type": "Central Goods and Services Tax", "tax_amount": "25", "tax_rate": "" }, { "tax_type": "Sales tax", "tax_amount": "", "tax_rate": "10" } ] }, { "external_invoice_number": "SPOTLIGHT98", "line_description": "Charger", "line_quantity": "5", "line_unit_price": "40.00", "subtotal": "200.00", "line_amount_invoiced": "200.00", "purchase_order_line": "232432", "po_line_description": "Mac laptop", "currency": "USD", "cost_center": "41605600", "gl_account": "141101", "tax_code": "A0 - Sales tax, standard rate", "ship_to_city": "New York", "ship_to_country": "USA", "ship_to_state_or_province": "NY", "ship_to_street": "123 Main St", "ship_to_zip_or_postal_code": "10001", "supplier_part_number": "SPN-001", "uom": "Hours", "tax_details": [ { "tax_type": "Central Goods and Services Tax", "tax_amount": "25", "tax_rate": "" }, { "tax_type": "Sales tax", "tax_amount": "", "tax_rate": "10" } ] } ] } ], "target_erp": "" }' The following result shows that the request is successful and the invoice data is processing. You can view the status of the request in the Invoice integration log \[sn_spend_intg_invoice_integration_log\] table. Use the batch ID listed in the Batch ID column to find the invoice. { "batchId": "APIINV1729711710733280", "status": "Success", "message": "Your request has been successfully received and is being processed." } ## AP Invoice -- POST sn_spend_intg/ap_invoice/xml {#ariaid-title4} Processes an automated invoice in XML format. Use the Invoice integration field mappings \[sn_spend_intg_invoice_intg_field_mapping\] table to determine how the fields are mapped to XML tags. You can define custom invoice fields for the request body. Use the following flow to add custom fields, map them to target tables, and format them for availability in the payload: 1. [Add custom fields for invoice import](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-addColToTable "Use the following procedure to add custom fields for invoices, invoice lines, and invoice tax lines to be used with the AP Invoice API.") 2. [Map custom fields between source and target tables](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-mapFieldsTransform "Use the following procedure to map custom fields between source and target tables for the AP Invoice API.") 3. [Map custom fields to a payload source format](https://www.servicenow.com/docs/FuR_wJZltOuvY~Hn63H68Q#apInvoice-mapFieldsTSrcFormat "Use the following procedure to map custom fields to a payload entry in JSON, cXML, or XML for the AP Invoice API.") {#ap_invoice-POST-xml__ul_kcx_5fx_sdc} ### URL format Versioned URL: /api/sn_spend_intg/v1/ap_invoice/xml Default URL: /api/sn_spend_intg/ap_invoice/xml ### Supported request parameters {#ap_invoice-POST-xml__entry__2}{#ap_invoice-POST-xml__version-not_optional-RESTAPI} | Name | Description | |-|-| | api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String | [Table 13. Path parameters] {#ap_invoice-POST-xml__entry__6} | Name | Description | |-|-| | None | | [Table 14. Query parameters] {#ap_invoice-POST-xml__entry__10} | Path | Description | |-|-| | /Invoice/AmountInvoiced | Total amount of money to be paid to the supplier including tax and shipping charges. Target field: u_amount_invoiced Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | Invoice/BillToCity | The city to which the invoice is sent. Target field: u_bill_to_city Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/BillToCountry | The country to which the invoice is sent in ISO 3166 format. For example, `US`. Target field: u_bill_to_country Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/BillToStateOrProvince | The state or province to which the invoice is sent. Target field: u_bill_to_state_or_province Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/BillToStreet | The street address to which the invoice is sent. Target field: u_bill_to_street Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/BillToZipOrPostalCode | The zip or postal code to which the invoice is sent. Target field: u_bill_to_zip_or_postal_code | | /Invoice/Currency | Required. Currency for subtotal, tax, and shipping. The subtotal, tax, and shipping should be in the same currency. Target field: u_currency Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/DateFormat | Sets the invoice date format from the default YYYY-MM-DD to another supported date format. The date value is set in the InvoiceDate element. Supported date formats: * DD MMM YYYY * DD MMM, YY * DD MMM, YYYY * DD MMMM YYYY * DD MMMM, YY * DD MMMM, YYYY * DD-MM-YY * DD-MM-YYYY * DD-MMM-YY * DD-MMM-YYYY * DD.MM.YY * DD.MM.YYYY * DD/MM/YY * DD/MM/YYYY * dd/mmm/yyyy * MM-DD-YY * MM-DD-YYYY * MM.DD.YY * MM.DD.YYYY * MM/DD/YY * MM/DD/YYYY * MMM DD YYYY * MMM DD, YY * MMM DD, YYYY * MMMM DD YYYY * MMMM DD, YY * MMMM DD, YYYY * YY-MM-DD * YY.MM.DD * YY/MM/DD * YYYY-MM-DD (default) * YYYY.MM.DD * YYYY/MM/DD {#ap_invoice-POST-xml__ul_d12_xkt_c2c} Note: The MMM format entry represents a month in its first three letters, for example, Aug. The MMMM format entry represents the full month name, for example, August. Target field: u_date_format Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Default format: YYYY-MM-DD | | /Invoice/Discounts | Discounts that are applied toward the invoice. Target field: u_discounts Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/ExternalInvoiceNumber | Invoice number generated from a third-party application. Target field: u_external_invoice_number Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/InvoiceDate | Date on which the customer was invoiced. Use the DateFormat element to add the date in a supported non-default format. Target field: u_invoice_date Related table: Invoice Import \[sn_spend_intg_imp_invoice\] Default format: YYYY-MM-DD | | /Invoice/LegalEntity | Name of the legal entity of the supplier. Located in the Legal Entity \[sn_fin_legal_entity\] table. Target field: u_legal_entity Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/OtherCharges | Other additional charges associated with the invoice. This is an editable field. Target field: u_other_charges Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/PaymentTerms | The agreed upon time and conditions under which a payment to a supplier is made. For example, `Net 30`. Target field: u_payment_terms Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/RemitAddress | The street address to which the payment is made. Target field: u_remit_address | | Invoice/RemitToCity | The city to which the payment is made. Target field: u_remit_to_city | | /Invoice/RemitToCountry | The country to which the payment is made in ISO 3166 format. For example, `US`. Target field: u_remit_to_country | | /Invoice/RemitToStateOrProvince | The state or province to which the payment is made. Target field: u_remit_to_state_or_province | | /Invoice/RemitToZipOrPostalCode | The zip or postal code to which the payment is made. Target field: u_remit_to_zip_or_postal_code | | /Invoice/ShipFromCity | City from which the items on the purchase order are shipped. Target field: u_ship_from_city Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/ShipFromCountry | Country from which the items on the purchase order are shipped. Target field: u_ship_from_country Related table: Invoice Line \[sn_spend_intg_imp_invoice\] | | /Invoice/ShipFromStateOrProvince | State from which the items on the purchase order are shipped. Target field: u_ship_from_state_or_province Related table: Invoice Line \[sn_spend_intg_imp_invoice\] | | /Invoice/ShipFromStreet | Street from which the items on the purchase order are shipped. Target field: u_ship_from_street Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/ShipFromZipOrPostalCode | Zip code from which the items on the purchase order are shipped. Target field: u_ship_from_zip_or_postal_code Related table: Invoice Line \[sn_spend_intg_imp_invoice\] | | /Invoice/ShippingAmount | Total shipping cost for the entire purchase. Target field: u_shipping_amount Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/Subtotal | Total amount of money to be paid to the supplier excluding tax and shipping charges. Target field: u_subtotal Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /Invoice/Supplier | Identifier for the reseller or supplier that the customer can place orders with. Target field: u_supplier Related table: Invoice Import \[sn_spend_intg_imp_invoice\] | | /InvoiceLine/CostCenter | Account number of the cost center for which the invoice is generated. Listed in the Cost Center \[cmn_cost_center\] table. Target field: u_cost_center | | /InvoiceLine/Currency | Currency for the line item. For example, `USD`. Target field: u_currency Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/GLAccount | Account number of the general ledger (GL) used to generate the invoice. Target field: u_gl_account See also: * [ERP source](https://www.servicenow.com/docs/access?context=erp-source&version=yokohama&pubname=yokohama-source-to-pay-operations&ft:locale=en-US) * [Ledger account](https://www.servicenow.com/docs/access?context=ledger-account&version=yokohama&pubname=yokohama-source-to-pay-operations&ft:locale=en-US) {#ap_invoice-POST-xml__ul_u23_b3r_cdc} | | /InvoiceLine/LineAmountInvoiced | Total cost, excluding taxes and shipping, that a customer is being invoiced for a given purchase order line. Target field: u_line_amount_invoiced Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/LineDescription | Description of the invoice line. Target field: u_line_description | | /InvoiceLine/LineQuantity | Quantity of goods or services that a customer is being invoiced for. Target field: u_line_quantity | | /InvoiceLine/LineUnitPrice | Unit price of the line item in the invoice. Target field: u_line_unit_price Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/POLineDescription | Description of the purchase order line for the invoice. Target field: u_po_line_description Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/PurchaseOrderLine | Purchase order number that is provided by the customer for this order. Listed in the Purchase Order \[sn_shop_purchase_order\] table. Target field: u_purchase_order Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/ShipToCity | City to which the items on the purchase order are shipped. Target field: u_ship_to_city Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/ShipToCountry | Country to which the items on the purchase order are shipped. Target field: u_ship_to_country Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/ShipToStateOrProvince | State or province to which the items on the purchase order are shipped. Target field: u_ship_to_state_or_province | | /InvoiceLine/ShipToStreet | Street to which the items on the purchase order are shipped. Target field: u_ship_to_street Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/ShipToZipOrPostalCode | Zip code to which the items on the purchase order are shipped. Target field: u_ship_to_zip_or_postal_code Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/Subtotal | Total amount of money to be paid to the supplier excluding tax and shipping charges. Target field: u_subtotal Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/SupplierPartNumber | Part number that is generated by a supplier for this invoice line. Target field: u_supplier_part_number Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/TaxCode | Unique tax code generated from the ERP source. Target field: u_tax_code Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /InvoiceLine/UOM | Base unit of measure (UOM) used to count the item in the invoice. Target field: u_uom Related table: Invoice Line Import \[sn_spend_intg_imp_invoice_line\] | | /TaxDetail/TaxType | Type of tax applicable on the invoice. Listed in the Tax Type \[sn_fin_tax_type\] table. Target field: u_tax_type Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] | | /TaxDetail/TaxRate | The tax rate charged by the supplier. Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] Target field: u_supplier_tax_rate Related table: Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\] | [Table 15. Request body elements (XML)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#ap_invoice-POST-xml__entry__106} | Header | Description | |-|-| | Content-Type | Data format of the request body. Only supports application/xml. | | Source-System | Specifies the source system from which the request is coming from. Available systems are listed in the Source systems credentials \[sn_spend_intg_source_system_credential\] table. This setting helps to determine if the request provided follows the structure in the Invoice integration field mapping \[sn_spend_intg_invoice_intg_field_mapping\] table. This setting is also used to fetch credentials from the Source system credentials \[sn_spend_intg_source_system_credential\] table. | [Table 16. Request headers] {#ap_invoice-POST-xml__entry__112} | Header | Description | |-|-| | None | | [Table 17. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#ap_invoice-POST-xml__table_wqv_qxk_ddc__entry__2}{#ap_invoice-POST-xml__entry-400-status-code} | Status code | Description | |-|-| | 202 | Request Accepted. The request is successful and invoice processing is in progress. | | 400 | Bad Request. A bad request type or malformed request was detected. | | 429 | Too Many Requests. The request rate has exceeded the maximum of 10 requests per hour. | [Table 18. Status codes] {#ap_invoice-POST-xml__table_wqv_qxk_ddc} ### Response body parameters {#ap_invoice-POST-xml__entry__124} | Name | Description | |-|-| | batch_id | Unique identifier for the batch request. This ID can be used to track the status of the request. This record is stored in the Invoice integration log \[sn_spend_intg_invoice_integration_log\] table. Data type: String | | error | Contains error message and details when the request fails. { "detail": String, "message": String } Data type: Object | | error.detail | Additional details about the request error. Possible results: * Failed API level ACL Validation - User does not have read/write access to the resource. * Rate limit of 13 requests per hour for AP Invoice exceeded -- The number of records in the batch is more than the batch size set. * Required to provide Auth information - Either the password is wrong or user name is wrong. {#ap_invoice-POST-xml__ul_ukg_sht_c2c} Data type: String | | error.message | Error message containing the reason the request failed Possible errors: * Invalid payload - Invalid content type. * Invalid payload - Error: Invalid payload structure. * Invalid payload - Error: Payload exceeds allowed invoices limit in a batch. The number of records in the batch is more than the batch size set. The maximum default payload size is 100 records. This value is configurable in the sn_spend_intg.ap.invoice.create.api.record_limit system property. * Invalid payload - Error: Empty invoices. No data to process. The number of records in the batch is zero. * Rate limit of 500 requests per hour for APO Invoice Ingestion exceeded. * User Not Authenticated. Either the password is wrong or user name is wrong. * Failed API level ACL Validation - User does not have read/write access to the resource. {#ap_invoice-POST-xml__ul_knb_fhr_2dc} Data type: String | | message | Success message, for example, Your request has been successfully received and is being processed. You can view the status of the request in the Invoice integration log \[sn_spend_intg_invoice_integration_log\] table. Data type: String | | status | Indicates the result of the request. Possible values: * Success * Fail {#ap_invoice-POST-xml__ul_zfp_shr_2dc} Data type: String | [ ] ### cURL request {#ap_invoice-POST-xml__example_mnp_3dm_ddc} The following example shows how to process an invoice provided as a request in XML format. curl -X POST https://instance.servicenow.com/api/sn_spend_intg/v1/ap_invoice/xml \ -H "Source-System: Ariba" \ -H "Content-Type: application/json" \ -d ' invoice S-432432425 EXT-INV-003 3245545 0004511198 Paula Smith 2023-09-02 Net 60 23985.00 750.00 27073.54 USD 2 Los Angeles USA CA 456 Oak Ave 90001 Addison USA TX 15725 Dallas P 55555 47 W 11th St New York USA NY 99999 4810 Eastgate Mall San Diego USA CA 92121 7894328742 CGST 15 SGST 100 EXT-INV-002 NowX Laptop 15 1500.00 22500.00 24693.75 USD Individual Unit WHTTax 2193.75 9.75 EXT-INV-002 NowX Charger PO-6789-001 15 99.00 1485.00 1629.79 USD Individual Unit GSTTax 144.79 9.75 CGST 1000 12 invoice S-432432426 EXT-INV-006 3245545 0004511198 Paula Smith 2023-09-02 Net 60 23985.00 750.00 27073.54 USD 2 Los Angeles USA CA 456 Oak Ave 90001 Addison USA TX 15725 Dallas P 55555 47 W 11th St New York USA NY 99999 4810 Eastgate Mall San Diego USA CA 92121 7894328742 VATTax 2338.54 EXT-INV-002 NowX Laptop 15 1500.00 22500.00 24693.75 USD Individual Unit EXT-INV-002 NowX Charger PO-6789-001 15 99.00 1485.00 1629.79 USD Individual Unit ERP1 ' The following result shows that the request is successful and the invoice data is processing. You can view the status of the request in the Invoice integration log \[sn_spend_intg_invoice_integration_log\] table. Use the batch ID listed in the Batch ID column to find the invoice. { "batchId": "APIINV1736249646168148", "status": "Success", "message": "Your request has been successfully received and is being processed." }