Materials

Create a new Material

Changed on

OAuth Scope

This endpoint requires the following OAuth scope manage_inventory.

Record UUID

UUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the x-record-uuid response header.

post/material.json

Request

  • Base URL
    https://api.servicem8.com/api_1.0
  • URL
    https://api.servicem8.com/api_1.0/material.json
  • Auth
    • API key in header X-Api-Key
    • or OAuth 2
      Authorization code: https://api.servicem8.com/oauth/authorize
      Token URL: https://api.servicem8.com/oauth/access_token scopes: manage_inventory

Request body

namestring required

Name of the material, product or labour rate. The maximum length varies based on accounting package integration 30-100 characters for standard mode, up to 2000 characters for description billing mode. Required field that identifies the material in inventory lists, job forms, and invoices.

item_numberstring

Unique identifier code for the material. max length. Must be unique within an account.

pricestring

The selling price of the material. May include or exclude tax based on the price_includes_taxes field. Used as the default price when adding this material to jobs and generating invoices.

coststring

The purchase cost of the material. May include or exclude tax depending on the price_includes_taxes setting. Used for profit calculations and reporting. This field may be hidden from users without appropriate permissions.

quantity_in_stocknumber

The current inventory quantity of this material available in stock. Stored as a numeric value with decimal support. Updated automatically when materials are used in jobs or when inventory is manually adjusted. Only tracked if item_is_inventoried is enabled.

price_includes_taxes0 | 1

Boolean flag indicating whether the price and cost values include tax (1/true) or exclude tax (0/false). Controls tax calculations when determining final pricing. New materials inherit this setting from the account's default tax display preference.. Valid values are [0,1]

barcodestring

The barcode identifier for the material. Can store UPC, EAN, or other barcode formats. Used for inventory scanning and quick material lookup in the mobile app.

item_is_inventoried0 | 1

Boolean flag indicating whether inventory tracking is enabled for this material (1/true) or disabled (0/false). When enabled, the quantity_in_stock is tracked and updated automatically when the material is used in jobs. Only physical products typically have this enabled.. Valid values are [0,1]

uuidstring uuid

Unique identifier for this record

item_descriptionstring
use_description_for_invoicingstring
tax_rate_uuidstring uuid

Example request

{
  "uuid": "123e4567-0719-4932-bd73-23f945fd0dab",
  "tax_rate_uuid": "123e4567-ca58-48a3-9a03-23f945b3507b"
}

Response

Success

errorCodenumber
messagestring

Example response

{
  "message": "OK"
}

Changes

  • 638a8df09bf4Revision changes
    • warning

      removed the request property

  • ca9b053c4373Revision changes
    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status