InvoiceModel

An Invoice represents a bill sent from one company to another. The creator of the invoice is identified by the CompanyId field, and the recipient of the invoice is identified by the CustomerId field. Most invoices are uniquely identified both by a Sage Network ID number and a customer ERP “key” that was generated by the system that originated the invoice. Invoices have a total amount and a due date, and when some payments have been made on the Invoice the TotalAmount and the OutstandingBalanceAmount may be different.

Methods

The following API methods use this data model.

• Retrieve Invoice
• Update Invoice
• Create Invoices
• Query Invoices

  Read-Only Fields

  These fields are assigned by the API server and cannot be changed.

  groupKey

uuid, read-only

The GroupKey uniquely identifies a single Sage Network account. All records for this account will share the same GroupKey value. GroupKey values cannot be changed once created.

For more information, see Accounts and GroupKeys.

invoiceId

uuid, read-only

The unique ID of this record, automatically assigned by Sage Network when this record is added to the Sage Network.

For the ID of this record in its originating financial system, see ErpKey.

created

date-time, read-only

The date on which this invoice record was created.

createdUserId

uuid, read-only

The ID number of the user who created this invoice.

modified

date-time, read-only

The date on which this invoice record was last modified.

modifiedUserId

uuid, read-only

The ID number of the user who most recently modified this invoice.

appEnrollmentId

uuid, nullable, read-only

The AppEnrollmentId of the application that imported this record. For accounts with more than one financial system connected, this field identifies the originating financial system that produced this record. This value is null if this record was not loaded from an external ERP or financial system.

erpWriteStatus

ErpWriteStatuses, read-only

Possible statuses for a record that supports ERP write.

erpWriteStatusName

string, nullable, read-only

The name of the ErpWriteStatus for this Invoice

sourceModifiedDate

date-time, nullable, read-only

The date on which this record was last modified in source ERP.

company

CompanyModel, nullable, read-only

The Company associated to this invoice. To retrieve this item, specify Company in the “Include” parameter for your query.

customer

CompanyModel, nullable, read-only

The Customer associated to the invoice customer To retrieve this item, specify Customer in the “Include” parameter for your query.

customerPrimaryContact

ContactModel, nullable, read-only

The Contact associated to the invoice customer To retrieve this item, specify Customer in the “Include” parameter for your query.

creditMemos

CreditMemoInvoiceModel[], nullable, read-only

The credit memos associated to this invoice. To retrieve this item, specify CreditMemos in the “Include” parameter for your query.

Required Fields

companyId

uuid

The ID number of the company that created this invoice.

customerId

uuid

The ID number of the counterparty for the invoice, for example, a customer or vendor.

totalAmount

double

The total value of this invoice, inclusive of all taxes and line items in it’s tendered currency.

salesTaxAmount

double

The total sales (or transactional) tax calculated for this invoice in it’s tendered currency.

discountAmount

double

The total discounts given by the seller to the buyer on this invoice in it’s tendered currency.

outstandingBalanceAmount

double

The remaining balance value of this invoice in it’s tendered currency.

isVoided

boolean

Is the invoice voided?

inDispute

boolean

Is the invoice in dispute?

excludeFromAging

boolean

Should the invoice be excluded from aging calculations?

currencyRate

double

The Currency Rate used to get from the account’s base currency to the invoice amount.

baseCurrencyTotalAmount

double

The total value of this invoice, inclusive of all taxes and line items in the group’s base currency.

baseCurrencySalesTaxAmount

double

The total sales (or transactional) tax calculated for this invoice in the group’s base currency.

baseCurrencyDiscountAmount

double

The total discounts given by the seller to the buyer on this invoice in the group’s base currency.

baseCurrencyOutstandingBalanceAmount

double

The remaining balance value of this invoice in the group’s base currency.

Optional Fields

erpKey

string, nullable, max 100 characters

The unique ID of this record as it was known in its originating financial system.

If this company record was imported from a financial system, it will have the value ErpKey set to the original primary key number of the record as it was known in the originating financial system. If this record was not imported, this value will be null.

For more information, see Identity Columns.

purchaseOrderCode

string, nullable, max 100 characters

The “Purchase Order Code” is a code that is sometimes used by companies to refer to the original PO that was sent that caused this invoice to be written. If a customer sends a purchase order to a vendor, the vendor can then create an invoice and refer back to the originating purchase order using this field.

referenceCode

string, nullable, max 100 characters

An additional reference code that is sometimes used to identify this invoice. The meaning of this field is specific to the ERP or accounting system used by the user.

salespersonCode

string, nullable, max 50 characters

A code identifying the salesperson responsible for writing this quote, invoice, or order.

salespersonName

string, nullable, max 50 characters

A name identifying the salesperson responsible for writing this quote, invoice, or order.

invoiceTypeCode

string, nullable, max 50 characters

A code identifying the type of this invoice.

Recognized Invoice types are:

• AR Invoice - Represents an invoice sent by Company to the Customer
• AP Invoice - Represents an invoice sent by Vendor to the Company
• AR Credit Memo - Represents a credit memo generated by Company given to Customer
• AP Credit Memo - Represents a credit memo generated by Vendor given to Company

invoiceStatusCode

string, nullable, max 50 characters

A code identifying the status of this invoice.

Recognized Invoice status codes are:

• Open - Represents an invoice that is considered open and needs more work to complete
• Closed - Represents an invoice that is considered closed and resolved

termsCode

string, nullable, max 50 characters

A code identifying the terms given to the purchaser. This field is imported directly from the originating financial system and does not follow a specified format.

specialTerms

string, nullable, max 200 characters

If the customer negotiated any special terms different from the standard terms above, describe them here.

currencyCode

string, nullable, max 3 characters

The three-character ISO 4217 currency code used for this invoice.

invoiceDate

date, nullable

The reporting date for this invoice.

discountDate

date, nullable

The date when discounts were adjusted for this invoice.

postedDate

date, nullable

The date when this invoice posted to the company’s general ledger.

invoiceClosedDate

date, nullable

The date when the invoice was closed and finalized after completion of all payments and delivery of all products and services.

paymentDueDate

date, nullable

The date when the remaining outstanding balance is due.

importedDate

date-time, nullable

The date and time when this record was imported from the user’s ERP or accounting system.

primaryOriginAddressId

uuid, nullable

The ID number of the invoice’s origination address

primaryBillToAddressId

uuid, nullable

The ID number of the invoice’s bill-to address

primaryShipToAddressId

uuid, nullable

The ID number of the invoice’s ship-to address

preferredDeliveryMethod

string, nullable

Indicates the preferred delivery method for this invoice. Examples include Print, Email, Fax

addresses

InvoiceAddressModel[], nullable

All addresses connected to this invoice. To retrieve this collection, specify Addresses in the “Include” parameter for your query.

lines

InvoiceLineModel[], nullable

All lines attached to this invoice. To retrieve this collection, specify Lines in the “Include” parameter for your query.

Included Collections

These fields are available when using Retrieve or Query API calls if you specify the associated Include parameter.

payments

InvoicePaymentDetailModel[], nullable, read-only

All payments attached to this invoice, the amount of the payment applied to this Invoice, and the date the Payment was applied. To retrieve this collection, specify Payments in the “Include” parameter for your query.

notes

NoteModel[], nullable, read-only

A collection of notes linked to this record. To retrieve this collection, specify Notes in the include parameter when retrieving data.

To create a note, use the Create Note endpoint with the TableKey to Invoice and the ObjectKey set to the InvoiceId for this record. For more information on extensibility, see linking extensible metadata to objects.

attachments

AttachmentModel[], nullable, read-only

A collection of attachments linked to this record. To retrieve this collection, specify Attachments in the include parameter when retrieving data.

To create an attachment, use the Upload Attachment endpoint with the TableKey to Invoice and the ObjectKey set to the InvoiceId for this record. For more information on extensibility, see linking extensible metadata to objects.

customFieldValues

CustomFieldValueModel[], nullable, read-only

A collection of custom fields linked to this record. To retrieve this collection, specify CustomFieldValues in the include parameter when retrieving data.

To create a custom field, use the Create Custom Field endpoint with the TableKey to Invoice and the ObjectKey set to the InvoiceId for this record. For more information on extensibility, see linking extensible metadata to objects.

customFieldDefinitions

CustomFieldDefinitionModel[], nullable, read-only

A collection of custom fields linked to this record. To retrieve this collection, specify CustomFieldDefinitions in the include parameter when retrieving data.

To create a custom field, use the Create Custom Field endpoint with the TableKey to Invoice and the ObjectKey set to the InvoiceId for this record. For more information on extensibility, see linking extensible metadata to objects.