---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# AP Invoice API Developer Guide

# AP Invoice API Developer Guide {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read

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.
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://servicenow-prod.fluidtopics.net/kOrnvusY542Hw557CTMCYA#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://servicenow-prod.fluidtopics.net/kOrnvusY542Hw557CTMCYA#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://servicenow-prod.fluidtopics.net/kOrnvusY542Hw557CTMCYA#apInvoice-mapFieldsTSrcFormat "Use the following procedure to map custom fields to a payload entry in JSON or cXML for the AP Invoice API.")
{#apInvoice-dev-guide__ul_kcx_5fx_sdc}

Define credentials for cXML payloads in the Source system credential \[sn_spend_intg_source_system_credential\] table. For instructions, see [Setting credentials for authentication in the cXML payload](https://servicenow-prod.fluidtopics.net/kOrnvusY542Hw557CTMCYA#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.").  
See also:

* [Accounts Payable Invoice Processing](https://www.servicenow.com/docs/access?context=acc-pay-invoice-processing&version=xanadu&pubname=xanadu-source-to-pay-operations&ft:locale=en-US)
* [AP Invoice API](https://servicenow-prod.fluidtopics.net/gSxgxL_yyLKEicj2BnMBVg#ap-invoice-api "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.")
{#apInvoice-dev-guide__ul_vlt_xxw_sdc}

## Add custom fields for invoice import {#ariaid-title2}

Use the following procedure to add custom fields for invoices, invoice lines, and invoice tax lines to be used with the AP Invoice API.

### Before you begin

* Role required: admin
* Application scope: [Source-to-Pay integration framework](https://www.servicenow.com/docs/access?context=sap-integration-overview-2&version=xanadu&pubname=xanadu-source-to-pay-operations&ft:locale=en-US)
{#apInvoice-addColToTable__ul_d2n_2k5_pdc}

### Procedure

1. Navigate to AllSystem DefinitionTables.
2. Select one of the following invoice import tables:  
   * Invoice Import \[sn_spend_intg_imp_invoice\]
   * Invoice Line Import \[sn_spend_intg_imp_invoice_line\]
   * Invoice Tax Line Import \[sn_spend_intg_imp_invoice_tax_line\]
   {#apInvoice-addColToTable__ul_trr_2bg_tdc}
3. On the Table Columns tab, select New.
4. Select a type associated with the field value (for example, <kbd class="ph userinput">Integer</kbd>) from the Type menu.  
   Note:  
   For a list of valid types, see [Field types](https://www.servicenow.com/docs/access?context=r_FieldTypes&version=xanadu&pubname=xanadu-platform-administration&ft:locale=en-US).
5. Enter a meaningful name in the Column label field.  
   Text including the label is automatically populated in the Column name field.
6. Select Save or Submit.
7. Add a column of the same name and type to the Invoice \[sn_shop_invoice\] table.  
   Note:  
   For more information on columns and fields, see [Field administration](https://www.servicenow.com/docs/access?context=c_IntroductionToFields&version=xanadu&pubname=xanadu-platform-administration&ft:locale=en-US).
8. [Map the fields between the source and target tables](https://servicenow-prod.fluidtopics.net/kOrnvusY542Hw557CTMCYA#apInvoice-mapFieldsTransform "Use the following procedure to map custom fields between source and target tables for the AP Invoice API.").
{#apInvoice-addColToTable__steps_uxf_c4g_ndc}

## Map custom fields between source and target tables {#ariaid-title3}

Use the following procedure to map custom fields between source and target tables for the AP Invoice API.

### Before you begin

* Role required: admin
* Application scope: [Source-to-Pay integration framework](https://www.servicenow.com/docs/access?context=sap-integration-overview-2&version=xanadu&pubname=xanadu-source-to-pay-operations&ft:locale=en-US)
{#apInvoice-mapFieldsTransform__ul_d2n_2k5_pdc}

Create table columns for mapping the new field from the source table to the target table. Use the steps in [Add custom fields for invoice import](https://servicenow-prod.fluidtopics.net/kOrnvusY542Hw557CTMCYA#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.").

### Procedure

1. Navigate to AllSystem Import SetsTransform Maps.
2. Open the Invoice Import table transform map.
3. Click New on the Field Maps tab.
4. Select the name of the custom field from the Source field menu.
5. Select the name of the custom field from the Target field menu.
6. Select Save or Submit.
7. [Map custom fields to a payload source format](https://servicenow-prod.fluidtopics.net/kOrnvusY542Hw557CTMCYA#apInvoice-mapFieldsTSrcFormat "Use the following procedure to map custom fields to a payload entry in JSON or cXML for the AP Invoice API.").
{#apInvoice-mapFieldsTransform__steps_uxf_c4g_ndc}

## Map custom fields to a payload source format {#ariaid-title4}

Use the following procedure to map custom fields to a payload entry in JSON or cXML for the AP Invoice API.

### Before you begin

* Role required: admin
* Application scope: [Source-to-Pay integration framework](https://www.servicenow.com/docs/access?context=sap-integration-overview-2&version=xanadu&pubname=xanadu-source-to-pay-operations&ft:locale=en-US)
* [Add custom fields for invoice import](https://servicenow-prod.fluidtopics.net/kOrnvusY542Hw557CTMCYA#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.")
* [Map custom fields between source and target tables](https://servicenow-prod.fluidtopics.net/kOrnvusY542Hw557CTMCYA#apInvoice-mapFieldsTransform "Use the following procedure to map custom fields between source and target tables for the AP Invoice API.")
{#apInvoice-mapFieldsTSrcFormat__ul_d2n_2k5_pdc}

### Procedure

1. Navigate to AllProcurement IntegrationsSuppliersInvoice Integration Field Mappings.
2. Select New.
3. Add the name of the source system to the Source system field.  
   * If this field mapping applies to all source systems, enter <kbd class="ph userinput">Default</kbd>.
   * If the mapping is specific to a particular source system, this value must match the value of the Source-System header parameter received in the API.  
     Note:  
     All remaining field mappings must be configured specifically for this source system.
   {#apInvoice-mapFieldsTSrcFormat__ul_ih3_rl2_tdc}
4. Select the format of the source system for which the mapping is being created from the Source format choice list (cXML or JSON).
5. Provide a name (JSON property) or path (cXML attribute or element) for the payload entry in the Source field field.  
   You can view the Invoice integration field mapping \[sn_spend_intg_invoice_intg_field_mapping\] table for examples of cXML path settings.
6. Add the name of an attribute if the field is to be defined as an element attribute for cXML payloads, otherwise leave the field empty.
7. Select the name of the target table containing your custom field from the Related table list.
8. Select the name of the custom field from the Target field list.
9. Select Save or Submit.  
   The mapped field is added to the Invoice integration field mapping \[sn_spend_intg_invoice_intg_field_mapping\] table.
{#apInvoice-mapFieldsTSrcFormat__steps_uxf_c4g_ndc}

## Setting credentials for authentication in the cXML payload {#ariaid-title5}

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.

### Before you begin

Role required: admin

Identify the payload source system listed in the Invoice integration field mappings \[sn_spend_intg_invoice_intg_field_mapping\] table.

See also [AP Invoice -- POST sn_spend_intg/ap_invoice/cxml](https://servicenow-prod.fluidtopics.net/gSxgxL_yyLKEicj2BnMBVg#ap_invoice-POST-cxml "Processes an automated invoice in commerce XML (cXML) format.").

### Procedure

1. Navigate to AllProcurement IntegrationsSource System Credentials.
2. Select New.
3. Add the name of the source system listed in the Invoice integration field mappings \[sn_spend_intg_invoice_intg_field_mapping\] table in the Source System field.  
   The source system name must match the Source-System header parameter.
4. Add the user name to be fetched in the User name field.  
   Use this value in the /cXML/Header/To/Credential \[@domain='NetworkID'\]/Identity element.
5. Add a strong combination of letters, numbers, and special characters to the Password field.  
   Use this value in the /cXML/Header/Sender/Credential \[@domain='NetworkID'\]/SharedSecret element.
6. Select Submit.
{#apInvoice-setCxmlCreds__steps_uxf_c4g_ndc}

*[\>]: and then