Create or Update an Invoice

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;
If PO based value: PO_POLICY_TWO_WAY_MATCH OR PO_POLICY_THREE_WAY_MATCH

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.
Example: 2019-07-21T17:32:28Z

Yes

invoice_type

String

The invoice type.
Values may be:
INVOICE, CREDIT_NOTE, DEBIT_NOTE, PROFORMA, TAX_ONLY

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.
Example:USD

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.
Example: Format: OFFICE, REMIT_TO, or SUPPLIER_SITE.

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.
Example: USA

No

email

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.
Example:Format: OFFICE, REMIT_TO, or SUPPLIER_SITE.

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.
Example: USA

No

email

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.
Example: Format: OFFICE, REMIT_TO, or SUPPLIER_SITE.

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

email

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.
Example: Format: OFFICE, REMIT_TO, or SUPPLIER_SITE.

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.
Example: USA

No

email

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.
Example: OFFICE, REMIT_TO, or SUPPLIER_SITE.

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.
Example: San Francisco.

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.
Example: USS.

No

email

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
Example: 101.2111.34456.6001.401.01all

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.
Example: USD

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.
Example: USD

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.
Example: USD

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.
Example: each, pallet, package, etc.

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.
Valid values “0” or “1”

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

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.