Uploading Invoices via Smart Upload Manager

Data Sets for Invoicing

Smart Upload Manager has four data sets related to managing invoices in Kantata OX:

• Invoices
• Invoice Additional Items
• Invoices Fixed Fee Items
• Invoice Payments

Invoices Data Set

The Invoices data set is responsible for setting the invoice header fields, like Purchase Order and Invoice Message. Billable time entries, expenses, and billing milestones can also be added to invoices with this data set. If you do not provide an invoice number, the system will auto-number the invoice based on the last invoice number used. If an invoice date is not provided, invoices created will default to today’s date.

Details on all supported fields in the Invoices data set can be found in the links below:

• Invoices Data Set Template
• Invoices Data Set Reference

Invoice Additional Items Data Set

The Invoice Additional Items data set is where additional items can be added to invoices. This is a dependent data set and must be on the same blueprint as an Invoices data set. An external_invoice_id must be on each line in this data set to properly associate the additional item with the core invoice from the Invoices data set. Additional items must have a value in the amount field, this number can be positive or negative and will increase or decrease the total invoice amount accordingly.

Details on all supported fields in the Invoice Additional Items data set can be found in the links below:

• Invoice Additional Item Data Set Template
• Invoice Additional Item Data Set Reference

Invoice Fixed Fee Items Data Set

The Invoice Fixed Fee Items data set allows fixed fee items to be added to invoices. Similar to the Invoice Additional Items data set, this data set is a dependent data set and must also be on the same blueprint as an Invoices data set. An external_invoice_id must be on each line in this data set to properly associate the fixed fee item with the core invoice from the Invoices data set. Each line must reference a task by setting either the story_id or external_story_id field. The task must be fixed fee and billable in order to be added to the invoice, and the fixed fee amount must be positive.

Details on all supported fields in the Invoice Fixed Fee Items data set can be found in the links below:

• Invoice Fixed Fee Item Data Set Template
• Invoice Fixed Fee Item Data Set Reference

Invoice Payments Data Set

Invoices can be marked as paid via the Invoice Payments data set. Invoice Payments are not a dependent data set and do not have to be on a blueprint with a related Invoices data set. The workspace_id field is required for all lines when uploading a payment. If a payment does not have an invoice_id, then the amount_in_cents field is required. This will create a stand-alone invoice to the specified project, and this invoice cannot be updated or associated with any invoice after it's created. If an invoice_id is provided, any value in amount_in_cents will be ignored and the full amount of the specified invoice will be paid.

Details on all supported fields in the Invoice Payments data set can be found in the links below:

• Invoice Payments Data Set Template
• Invoice Payments Data Set Reference

Creating Invoices in SUM

Creating an invoice uses the Invoices data set as a base, with the dependent data sets Invoice Additional Items and Invoice Fixed Fee as related and supplemental data sets. You cannot create an invoice using only the Invoice Additional Items or Invoice Fixed Fee Items data sets alone. The invoice created cannot have a negative total amount. The Invoices data set requires only one CSV row per invoice; the dependent data sets may have multiple CSV rows associated with the same invoice.

Creating the Invoice Header

The Invoice header contains the fields in the OX UI screenshot below. Only the payment_schedule field is required when creating invoices via SUM. Acceptable values for payment_schedule are 0, 15, 30, and 60.

Populate the desired invoice header fields for each row of the CSV file. Each of the above fields can be set only once per invoice.

Adding Time Entries, Expenses, and Billing Milestones to Invoices

Time entries, expenses, and billing milestones are contained within the Invoices data set. They are added by populating the time_entry_ids, expense_ids, and billing_milestone_ids fields. These fields support an array of IDs. The array must be comma-separated and contained within square brackets. An example array is shown below.

Example Array of Time Entry, Expense, or Billing Milestone IDs:
[2434476,9345783,8756345,7346522,5259380]

If the time entries, expenses, or billing milestones to be invoiced were uploaded via the Smart Upload Manager, they can be added to an invoice via the external_time_entry_ids, external_expense_ids, and external_billing_milestone_ids fields. If the items to be invoiced do not have SUM external references, you will have to supply the system IDs. The IDs of time entries, expenses, and billing milestones—either system or external—cannot be combined into the same field.

Supplied time entries or expenses must be billable and not already on any other invoice. If they are tracked to a task, that task must be set as Time & Materials. Fixed Fee tasks do not allow time or expenses tracked to them to be invoiced. If your company has time approvals or expense approvals enabled, then the time and/or expenses must be approved before they can be invoiced.

Adding Additional Items and Fixed Fee Items to Invoices

Invoices with Fixed Fee Items or Additional Items must have those items added via their respective dependent data sets. Each row of the data set must reference an invoice in the parent Invoices data set by setting the external_invoice_id field.

Fixed Fee Items must reference a valid task on the same project that the invoice is being created for. A valid task is unarchived and has a Fixed Fee task billing mode. Time & Materials type tasks cannot be invoiced as a Fixed Fee Item.

Multiple Additional Items and Fixed Fee Items can be added per invoice in their respective dependent data sets. Each line must contain the parent invoice’s external_invoice_id that was set on the parent Invoices data set. The amount value does not need to match the total budget of the fixed fee task, and can even exceed the associated task’s budget. This amount value is in whole units (e.g. dollars). See example below:

The Invoice Fixed Fee Items data set above will link three fixed fee items (one per row) to two different invoices. The first two lines will add fixed fee items to the invoice with the external ID of invoice_1, and the third line will add one fixed fee item to the invoice with the external ID of invoice_2. You can see that all three rows are related to different tasks as determined by the values in the external_story_id column. Note that the workspace_id column and the story_id are intentionally left blank in favor of the Smart Reference Keys references set in the last two columns.

Updating Invoices in SUM

To update an invoice in SUM, you must supply either the external_invoice_id or the id of the desired invoice(s) on the Invoices data set’s CSV. You can then populate the desired columns and fields for the updates you would like to make to the existing invoices.

If you would like to add or update fixed fee items or additional items to already created invoices, this must be done through Kantata OX.

Creating Invoice Payments in SUM

SUM allows the bulk creation of payment objects. These objects can be associated to an invoice or only associated to a project. Payment amount values are in subunits—or cents—and are a different magnitude from the amount field in the Fixed Fee Items and Additional Items data sets. Ex: 45075 = $450.75.

Creating a Payment to a Invoice

In SUM, create a blueprint with the Invoice Payment data set. This data set is not dependent and doesn't require an Invoices data set to be on the same blueprint. Input the invoice_id or the external_invoice_id of the invoice you’d like to pay. Input the workspace_id or external_workspace_id to indicate the project. This project ID must match the project the invoice was created for.

Creating a Payment to a Project

Create a blueprint with the Invoice Payment data set. The Invoice Payment data set is not a dependent data set and does not require an Invoices data set to be on the same blueprint. Input the amount_in_cents for the desired payment amount. Set the workspace_id or external_workspace_id to indicate which project this payment will be created for. Make sure to leave the invoice_id and external_invoice_id fields blank, as adding one will overwrite any amount given and apply the payment to an invoice instead of the project.