Looking for clarification on the following material endpoint fields:
name
item_description
use_description_for_invoicing
The name is generally self explanatory, as it is the field which is seen in for the material detail and seeds new jobmaterial.name fields.
However how is item_description used? There is also an assumed boolean flag field of use_description_for_invoicing, which exists but does not seem to be modifiable via API calls. Are these fields used? If so, in what way? The assumption would be that the item_description is a made available to the line item upon invoice document generation and also assumed if use_description_for_invoicing is set to 1. Please clarify.
Short answer: name is the documented line-item text to rely on for invoice/quote output via the Job Materials API, while item_description and use_description_for_invoicing are exposed in the Material API schema without further documented behaviour or valid-value notes.
Material.name is documented as a required field that identifies the material in inventory lists, job forms and invoices. The Material API schema also includes item_description and use_description_for_invoicing, but the public spec only defines those entries as string fields.
When a material is added to a job, the Job Material schema documents material_uuid as the link back to the catalogue material, and jobMaterial.name as the field displayed on invoices, typically coming from the associated material object but customisable per job.
The public Job Material API docs don’t document Material.item_description being copied into a Job Material field or being used automatically at invoice document generation.
Quote/invoice templates can include jobMaterial.description, but invoices and quotes are generated from templates, and whether materials/services are itemised depends on the template being used.
So if your integration needs reliable line-item text on generated invoices/quotes, use jobmaterial.name or a template field that matches the job material data your integration is populating.
For the use_description_for_invoicing write behaviour specifically, the public docs list the field in create/update schemas but don’t currently clarify its behaviour, so we’ll treat that as a documentation gap rather than guessing.
We’ll raise this with the team so the developer docs can be clarified.