Inventory Adjustment Reasons

Applies to: Inventory API

Learn how to categorize inventory adjustments with standard and custom adjustment reasons and filter inventory change history by reason.

Adjustment reasons let applications record why an inventory quantity changed, using the same set of reasons that sellers see in the Square Dashboard and Square Point of Sale. Every InventoryAdjustment can carry a reason_id that identifies a standard reason provided by Square (such as DAMAGED or RECEIVED) or a custom reason defined by the seller (such as "Donated to charity").

With adjustment reasons, your application can:

• Write adjustments with a reason, so they're categorized consistently with first-party Square products.
• Manage the seller's custom adjustment reasons (create, update, delete, and restore).
• Filter the inventory change history by one or more reasons.

A reason is identified by an InventoryAdjustmentReasonId object rather than a single ID string, in order to support predefined reason codes alongside the seller's custom reasons:

• Standard and system-generated reasons are identified by type alone - for example, { "type": "DAMAGED" }.
• Custom reasons use type CUSTOM plus the seller-specific custom_reason_id - for example, { "type": "CUSTOM", "custom_reason_id": "R5BX3PDCZ6EXAMPLE" }.

The full InventoryAdjustmentReason resource adds a name (custom reasons only), a direction (INCREASE or DECREASE), timestamps, and an is_deleted flag.

Standard reasons are predefined by Square, available to every seller, and can be written on adjustments by your application. Each standard reason implies a direction:

Some reasons are only ever attached to adjustments generated by Square products and cannot be written by your application: SALE, RECOUNT, TRANSFER, IN_TRANSIT, and CANCELED_SALE. You might encounter them when reading the change history. By default, they're omitted from ListInventoryAdjustmentReasons results; pass include_system_codes=true to include them.

Sellers (and your application, on their behalf) can define custom reasons with a name of up to 50 characters and a direction. Deleting a custom reason is a soft delete: historical adjustments keep referencing it, deleted reasons can still be retrieved by ID, and a deleted reason can be brought back with RestoreInventoryAdjustmentReason.