To create a new invoice or update an existing one in the AppZen System, it returns the AppZen generated uuid - the unique identifier, for this invoice. This invoice will be processed further by AppZen for extraction and validation.
If there already exists an invoice, with the given invoice_id body parameter, then the existing invoice will be updated. The status in the response shows as UPDATED. For a newly created invoice, the status shows asCREATED.
Request URI
POST https://api.appzen.com/dictionary-data-services/
invoice
Header Parameters
Name |
Type |
Description |
Required |
x-api-key | String | The x-api-key provided to authorize the request. | Yes |
customer-id | String | The Customer ID provided to authorize the request. | Yes |
customer-key | String | The Customer Key provided to authorize the request. | Yes |
historical |
Boolean |
Flag to indicate whether the invoice is historical or not |
Yes |
Body Parameters
Name |
Type |
Description |
Required |
total_amount |
Number |
The total amount on the invoice. |
Yes |
amount |
Number |
The total amount for the invoice line – is calculated as Quantity multiplied by Unit Price. |
Yes |
currency |
String |
The currency of the total amount. Example: USD. |
Yes |
invoice_id |
String |
The unique invoice id in your System. |
Yes |
invoice_status |
String |
Status of invoice in your System such as POSTED, PARKED, APPROVED, PAID, etc. |
No |
entity_id |
String |
The organization id reference from your System. |
Yes |
entity_name |
String |
The organization/company name. |
No |
purchase_order_number |
String |
The Purchase Order number for the invoice. |
No |
po_policy |
NA |
The root element to hold information of PO Backed/Non PO backed invoice. |
No |
po_backed |
Boolean |
This shows if the invoice is generated based on PO. |
No |
po_match_type |
String |
If non PO value is : PO_NONE_MATCH_TYPE; |
No |
site_id |
String |
The site id in the address. |
No |
invoice_number |
String |
The invoice number in your System. |
Yes |
invoice_date |
String |
The date on which an invoice for a good is issued. |
Yes |
invoice_type |
String |
The invoice type. |
No |
original_invoice_id |
String |
This should be populated for the Credit memo transaction. It is the unique ID of the invoice on which the credit memo is created. |
No |
original_invoice_date |
String |
This should be populated for the Credit memo transaction. It is the invoice date of invoice on which the credit memo was created. |
No |
payment_term_id |
String |
Payment term id your System. |
No |
remit_to_bank_info |
NA |
The root element that holds the payment settlement bank information. |
No |
bank_acct_last4 |
String |
The last 4 digit of the account number to which payment should be made. |
No |
routing_number_last4 |
String |
The unique number assigned to each bank. |
No |
bank_account_name |
String |
The name assigned to that bank account. |
No |
bank_account_type |
String |
The type of bank account. |
No |
requestor |
String |
The Name or Id of the person who is generating this invoice. |
No |
documents |
NA |
The root element which holds information about the documents |
No |
uuid |
String |
The single or list of uuids which you will get by calling generate-upload-url. |
No |
shipping_handling_amount |
NA |
The root element which holds information about the amount charged for the labor, storage, and delivery costs incurred to complete customer orders. |
No |
amount |
Number |
The amount charged for the labor, storage, and delivery costs incurred to complete customer orders. |
No |
currency |
String |
The currency in which amount is charged for the labor, storage, and delivery costs incurred to complete customer orders. |
No |
submission_date |
String |
The submission date of the Invoice. |
No |
submitter |
String |
The name of the person who submitted the invoice. |
No |
supplier_name |
String |
The name of the supplier. |
No |
supplier_number |
String |
The unique number assigned to the supplier. |
No |
supplier_id |
String |
The unique external number assigned to the supplier in your system. |
Yes |
tax_amount |
NA |
The root element which holds information about the tax amount. |
No |
amount |
Number |
The sum of tax for each line in the invoice. |
No |
currency |
String |
The currency of the tax amount. Example: USD |
No |
vat_amount |
Number |
The root element which holds information about the VAT amount |
No |
amount |
Number |
The total VAT applicable for a line. |
No |
currency |
String |
The currency of the VAT amount. |
No |
vat_breakdown |
Number |
The break down of VAT amount for the Invoice. | No |
code |
String |
Tax code. Example: GST |
No |
rate |
Number
|
Tax rate in percentage. minimum:0 exclusiveMinimum: True |
No |
vat_amount |
NA |
Root element to hold VAT information. | No |
amount |
Number Default:0 |
VAT amount for the Invoice | No |
currency |
String |
Currency of the VAT amount on the Invoice | No |
vat_registration_numbers |
String |
Vat registration numbers. |
No |
total_amount_excluding_vat |
Number |
Total amount excluding vat. |
No |
amount |
Number Default:0 |
The amount. |
No |
currency |
String |
The currency. |
No |
supplier_address |
NA |
The root element which holds information about the supplier address |
|
address_type |
String |
The type of address. |
No |
address |
NA |
This is the root field to contain info about an address. |
No |
address_line1 |
String |
The address line 1 of the supplier. |
Yes |
address_line2 |
String |
The address line 2 of the supplier. |
No |
address_line3 |
String |
The address line 3 of the supplier. |
No |
area_code |
String |
The area code of the area mentioned in address of supplier. |
No |
city |
String |
The city of the supplier. |
No |
company |
String |
The name of the company of the supplier. |
No |
contact |
String |
The name of the contact person. |
No |
country |
String |
The country of the supplier. Ex: US |
Yes |
country_iso3 |
String |
The Country code of supplier in iso3 format. |
No |
|
String |
The email id of the supplier. |
No |
phone |
String |
The contact number of the supplier. |
No |
province |
String |
The province of the supplier. |
No |
state |
String |
The state of the supplier. |
No |
zip |
String |
The zip code of the supplier. |
Yes |
billing_address |
NA |
The root element which holds information about the billing address. |
No |
address_type |
String |
The type of address. |
No |
address |
NA |
This is the root field to contain information about an address |
No |
address_line1 |
String |
Billing dept address line 1 for company represented in OrgName. |
Yes |
address_line2 |
String |
Billing dept address line 2 for company represented in OrgName |
No |
address_line3 |
String |
Billing dept address line 3 for company represented in OrgName. |
No |
area_code |
String |
The area code of the area mentioned in the address of the supplier. |
No |
city |
String |
Billing dept bill to City for company represented in OrgName. |
No |
company |
String |
The name of the company. |
No |
contact |
String |
The name of the contact person in the billing company. |
No |
country |
String |
Billing dept bill to Country for company represented in OrgName. |
Yes |
country_iso3 |
String |
Billing dept bill to Country for company represented in OrgName. the name of the country should be in iso3 format. |
No |
|
String |
The email id of the contact person. |
No |
phone |
String |
The contact number of the contact person. |
No |
province |
String |
Billing dept bill to Province for company represented in OrgName. |
No |
state |
String |
Billing dept bill to State for company represented in OrgName. |
No |
zip |
String |
Billing dept bill to Zip for company represented in OrgName. |
Yes |
shipping_address |
NA |
This is the root field to contain information about shipping address. |
No |
address_type |
String |
The type of address. |
No |
address |
NA |
This is the root field to contain information about an address. |
No |
address_line1 |
String |
The physical address line 1 where shipments are sent. |
Yes |
address_line2 |
String |
The physical address line 2 where shipments are sent. |
No |
address_line3 |
String |
The physical address line 3 where shipments are sent. |
No |
area_code |
String |
The area code of the area mentioned in address where shipments are sent. |
No |
city |
String |
The city where shipments are sent. |
No |
company |
String |
The name of the company where shipments are sent. |
No |
contact |
String |
The name of the contact person in the company where shipments are sent. |
No |
country |
String |
The country where shipments are sent. |
Yes |
country_iso3 |
String |
The name of the country where shipments are sent in iso3 format. Example: USA |
No |
|
String |
The email id of the contact person in the company where shipments are sent. |
No |
phone |
String |
The phone number of the contact person in the company where shipments are sent. |
No |
province |
String |
The province where shipments are sent. |
No |
state |
String |
The state where shipments are sent. |
No |
zip |
String |
The zip code where shipments are sent. |
Yes |
remit_to_address |
NA |
This is the root field to contain information about address where payment is to be received |
No |
address_type |
String |
The type of address. |
No |
address |
NA |
This is the root field to contain information about an address |
No |
address_line1 |
String |
The physical address line 1 where payment is to be received. |
Yes |
address_line2 |
String |
The physical address line 2 where payment is to be received. |
No |
address_line3 |
String |
The physical address line 3 where payment is to be received. |
No |
area_code |
String |
The area code of the area mentioned in address where payment is to be received. |
No |
city |
String |
The city where payment is to be received. |
No |
company |
String |
The name of the company where payment is to be received. |
No |
contact |
String |
The name of the contact person in the company where payment is to be received. |
No |
country |
String |
The country where payment is to be received. |
Yes |
country_iso3 |
String |
The name of the country where payment is to be received in iso3 format. |
No |
|
String |
The email id of the contact person in the company where payment is to be received. |
No |
phone |
String |
The phone number of the contact person in the company where payment is to be received. |
No |
province |
String |
The province where payment is to be received. |
No |
state |
String |
The state where payment is to be received. |
No |
zip |
String |
The zip code where payment is to be received. |
Yes |
other_addresses |
NA |
This is the root field to contain information about any extra address |
No |
address_type |
String |
The type of address. |
No |
address |
NA |
This is the root field to contain information about an address. |
No |
address_line1 |
String |
Line 1 of the address. |
Yes |
address_line2 |
String |
Line 2 of the address. |
No |
address_line3 |
String |
Line 3 of the address. |
No |
area_code |
String |
The area code of the area in address. |
No |
city |
String |
City in the address. |
No |
company |
String |
Name of the Company. |
No |
contact |
String |
Name of the contact person. |
No |
country |
String |
Country name in the address . For Example: US |
Yes |
country_iso3 |
String |
Country name in the address in iso3 format. |
No |
|
String |
Email Id of the contact person. |
No |
phone |
String |
Phone number of the contact person. |
No |
province |
String |
The name of the Province if it exists in the address. |
No |
state |
String |
The name of the state if it exists in the address. |
No |
zip |
String |
The Zip code of the address. |
Yes |
site_id |
String |
The site ID in the address. |
No |
site_name |
String |
The site name in the address. |
No |
custom_json |
NA |
For storing any additional information. |
No |
key1 |
Values sent under Custom JSON. |
No | |
gl_code |
All Accounting segments of the GL distribution |
No | |
segments |
The list of segments. |
No | |
segments |
NA |
The root element which holds information about the Invoice account segments |
No |
code |
String |
The code value of segment. |
Yes |
name |
String |
The name of the segment. |
Yes |
segment_type |
String |
The type of segment. |
Yes |
appzen_segment_type |
String |
Value represents how appzen understands the customer segment type. OTHER_SEGMENT should be used to map any customer segment type that does not have correspondence with one of the named appzen segment types (e.g. ACCOUNT_SEGMENT, DEPARTMENT_SEGMENT etc). Multiple OTHER_SEGMENT mappings may be specified, if needed. |
Yes |
segment_name_id |
String |
The unique id of a segment. |
Yes |
invoice_description |
String |
The description of the invoice. |
No |
payment_date |
String |
The root element which holds information about the invoice lines. |
No |
invoice_lines |
Number |
The line number of the line in invoice |
Yes |
line_number |
Number |
The sequence of line numbers. |
Yes |
line_description |
String |
The description of the item. |
Yes |
quantity |
Number |
The quantity of goods and services provided by the supplier on the line. |
Yes |
unit_price |
String |
The root element which holds information about the unit price in invoice lines. |
Yes |
amount |
Number |
The price you charge per unit of goods or services. |
Yes |
currency |
String |
The currency of the unit amount. |
Yes |
total_amount |
NA |
The root element which hold information about the total amount in the invoice lines |
Yes |
amount |
Number |
The total amount of the invoice in transactional currency. |
Yes |
currency |
String |
The transactional currency of the invoice amount. |
Yes |
tax_amount |
The root element which holds information about the tax amount. |
No | |
amount |
Number |
The sum of tax for each line in the invoice. |
Yes |
currency |
String |
The currency of the tax amount. |
Yes |
purchase_order_number |
String |
The purchase order number of the invoice. |
No |
purchase_order_line_number |
String |
The line number of the purchase order number of the invoice |
No |
po_match_type |
String |
The match type of invoice like PO_NONE_MATCH_TYPE, PO_POLICY_TWO_WAY_MATCH, PO_POLICY_THREE_WAY_MATCH |
No |
line_item_code |
String |
The unique item id from your System |
No |
unit_of_measure |
String |
The unit of measure for the line item. |
No |
model_number |
String |
Model number of the item in invoice |
No |
currency |
String |
The currency of the amount in invoice. |
No |
gl_code |
String |
The code value of segment. |
No |
segments |
The list of segments. |
No | |
segments |
The root element which holds information about the Invoice account segments. |
No | |
code |
String |
The code value of segment. |
Yes |
name |
String |
The name of the segment |
Yes |
segment_type |
String |
The type of segment. |
Yes |
appzen_segment_type |
String |
Value represents how appzen understands the customer segment type. OTHER_SEGMENT should be used to map any customer segment type that does not have correspondence with one of the named appzen segment types (e.g. ACCOUNT_SEGMENT, DEPARTMENT_SEGMENT etc). Multiple OTHER_SEGMENT mappings may be specified, if needed. |
Yes |
segment_name_id |
String |
The unique ID of a segment in your System. |
Yes |
custom_json |
NA |
For storing any custom values needed by your system. |
No |
options |
NA |
The root element which holds information about the Invoice lines |
No |
strict_invoice_number |
String |
Whether invoice_number can be used for looking up invoice. |
No |
Sample Request
curl --location 'https://api.enft.dev.appzen.com/dictionary-data-services/invoice' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: <>' \
--header 'historical: false' \
--header 'customer-id: 100094' \
--header 'customer-key: <>' \
--data '{
"total_amount": {
"amount": 200.00,
"currency": "USD"
},
"accounting_date_override": "2023-12-01T12:00:00Z",
"payment_type_override": "CASH",
"tax_applicability_id" : "2A3B",
"default_tax_option" : "Calculate",
"purchase_order_number": "749429",
"payment_due_date": "2021-02-01T00:00:00Z",
"invoice_id": "794441",
"invoice_status": "Fully Paid",
"invoice_type": "",
"invoice_date": "2021-01-01T00:00:00Z",
"invoice_description": "A0041111",
"entity_id": "422626",
"supplier_name": "Supplier 546189",
"entity_name": "422626 BU",
"documents": [
{
"uuid": "3d328247-62d3-4fc1-b7cf-5d750ceb0ab6"
}
],
"invoice_number": "794441",
"payment_term_id": "414683",
"supplier_id": "546189",
"site_id": "0000",
"shipping_address": {
"address_line1": "TEST COMPANY",
"address_line2": "ATTN: ACCOUNTS PAYABLE",
"address_line3": "PO BOX 123",
"city": "SAN FRANCISCO",
"state": "CA",
"zip": "94016",
"country": "US"
},
"billing_address": {
"address_line1": "TEST CUSTOMER",
"address_line2": "ATTN: ACCOUNTS PAYABLE",
"address_line3": "PO BOX 123",
"city": "SAN FRANCISCO",
"state": "CA",
"zip": "94016",
"country": "US"
},
"invoice_lines": [
{
"line_number": 1,
"tax_applicability_id" : "2A3BAtLine",
"line_description": "DESCRIPTION1",
"quantity": 1,
"unit_price": {
"amount": 200.00,
"currency": "USD"
},
"total_amount": {
"amount": 200.00,
"currency": "USD"
},
"line_vat_amount": {
"amount": 13.08,
"currency": "JPY"
},
"line_allocations": [
{
"external_allocation_id": "",
"amount": 25,
"tax": 2,
"percentage": 35,
"gl_code": "330011.957406.258090"
}
],
"line_vat_breakdown": [
{
"vat_amount": {
"amount": 3.08,
"currency": "JPY"
},
"rate": "10a",
"code": "HST"
}
],
"purchase_order_number": "749429",
"unit_of_measure": "Each",
"gl_code": "330011.957406.258090"
}
]
}'
Sample Response
Success
{
"uuid": "5fc03087-d265-11e7-b8c6-83e29cd24f4c",
"status": "UPDATED"
}
Failure
The request failed as the resource is not found.
{
"timestamp": "2019-01-17T16:12:45.977+0000",
"status": 404,
"error": "Not Found",
"message": "Error code : 17e3338d - The resource you specified cannot be not found"
}
Response Code
Response Code | Description |
200 | The request is successful. |
201 |
The request is successful. |
400 |
The request failed due to a malformed request syntax. Check the requested URL, including the parameters. |
401 |
The request failed due to an authorization issue. For example, the Customer Key could be missing or invalid. |
403 |
The request failed due to a permission issue. The x-api key may not have permission to perform the request. |
404 |
The request failed as the resource is not found. Check the requested URL. |
500 |
The request failed due to an AppZen server issue. |
See Also
Comments
Article is closed for comments.