1. Audits
  2. Create & Update Audit

Audits

Create & Update Audit

Create Audit

POST
`/v1/audits`

The only property required to create an audit is location_id. When the audit is created, the system will inspect the inventory levels at that location and automatically generate one audit_task per item/layout combination that has a non-zero quantity. You can narrow the scope of the audit by supplying item_ids and/or layout_ids.
location_id string (required) The ID of the location at which the audit will be performed.
item_ids string[]
A list of item IDs to scope the audit to. If omitted, all items with non-zero quantity at the location are included.
layout_ids string[]
A list of layout IDs to scope the audit to. If omitted, all layouts at the location with non-zero quantity are included.
number string
A human-readable identifier for the audit. Must be unique within the location for the organization. If omitted, the system will generate one in the form AUD-<n>.
priority string
The priority of the audit. Can be low, medium, or high. Defaults to medium.
assignee string
The ID of a contact to assign as the auditor.
complete_at integer
Time in epoch seconds by which the audit should be completed. If this date passes before the audit is approved, the audit will be marked as overdue.
update_inventory boolean
If true, inventory levels will be reconciled with counted_qty when the audit is approved. If false, the audit is recorded but does not modify inventory. Defaults to true.
metadata object
Additional metadata to associate with the audit.
js 
        const data = {
  location_id: "loc_8axWLqDo9kprqgNmFpCqxo",
  layout_ids: ["lay_vgM65sMYtakxwfXkTCC8FB"],
  item_ids: ["item_5TngYZKdRFTSkcVCvNa885"],
  priority: "high",
  complete_at: 1739898954,
};

const res = await fetch(`https://api.packagex.io/v1/audits`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

const audit = res.data; //Refer to the audit model

The system will generate one audit_task per eligible item/layout combination at the location. If no items are eligible for counting at the location (e.g., all levels are at 0 quantity), the request will fail with a 400 error. Audits are also capped at 100 tasks per audit; if more tasks would be generated, the request will fail and you should narrow the scope using item_ids and/or layout_ids.

If you supply a number that already exists for the location in your organization, the request will fail.


Update Audit

POST
`/v1/audits/:audit_id`

Audits are updated through the same endpoint used to submit task counts, transition status, and add review feedback.
status string
The new status of the audit. Can be created, processing, in_review, recount, approved, or canceled.
priority string
The priority of the audit. Can be low, medium, or high.
assignee string
The ID of the contact responsible for performing the audit. Pass null to unassign.
complete_at integer
Time in epoch seconds by which the audit should be completed.
feedback string
Free-form feedback or notes about the audit, typically added during review.
update_inventory boolean
If true, inventory levels will be reconciled with counted_qty when the audit is approved. If false, the audit will not modify inventory levels.
metadata object
Additional metadata to associate with the audit. Pass null on a key to remove it.
tasks array
An array of audit task updates. See Updating Audit Tasks below.

Updating Audit Tasks

To submit counts and reason codes for the tasks in an audit, supply a tasks array. Each entry in the array must include the id of an existing audit task. The item_id and layout_id for a task cannot be changed once created.

Task Field
id string (required) The ID of the audit task being updated.
counted_qty integer | integer[] The quantity counted for this task. Pass an integer to set the count directly, or an array containing a single integer to increment the existing count by that value.
reason_code_id string The ID of the reason code explaining the discrepancy. Required when transitioning the audit to in_review if the discrepancy exceeds the organization's audit approval threshold.
metadata object Additional metadata to associate with the task. Pass null on a key to remove it.
js 
        const data = {
  status: "in_review",
  feedback: "Counted all bins on Aisle A.",
  tasks: [
    {
      id: "audit_task_HoNwbmYWy7zfeBs6BzABnp",
      counted_qty: 24,
    },
    {
      id: "audit_task_4AzbnQ8jXk96P7CkAcKxAh",
      counted_qty: 9,
      reason_code_id: "rsnc_aBcDeFgHiJkLmNoPqRsT",
    },
  ],
};

const res = await fetch(`https://api.packagex.io/v1/audits/audit_1tH2ofoBcDbPnyZCYmrSX3`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

const audit = res.data;

To increment the existing counted quantity rather than overwriting it, pass counted_qty as a single-element array:

js 
        const data = {
  tasks: [
    {
      id: "audit_task_HoNwbmYWy7zfeBs6BzABnp",
      counted_qty: [5], // adds 5 to the existing counted_qty
    },
  ],
};

Status Transitions

When you submit task counts and move the audit to in_review, the system locks in total_qty for each task and validates that any tasks whose discrepancy exceeds the organization's audit approval threshold have a reason_code_id. If all in-review tasks fall within the threshold, the audit is automatically transitioned from in_review to approved.

When the audit is approved with update_inventory set to true, the system applies the difference between counted_qty and total_qty to the corresponding inventory level's available_qty, and stamps last_audited_at on the impacted items, layouts, and location. If applying a discrepancy would cause available_qty to drop below 0, the request will fail.

Previous <- Events
Next Retrieve Audit ->