Skip to main content
POST
/
v1
/
inventory
/
hold-reasons
Create user-defined hold reason
curl --request POST \
  --url https://{base_url_domain}/api/global/v1/inventory/hold-reasons \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "qc_followup",
  "label": "QC Follow-up",
  "parent": {
    "type": "HoldReason",
    "id": 3
  },
  "display_group": "Hold",
  "allow_relocation": null,
  "merchants": [
    {
      "type": "Merchant",
      "id": 4
    }
  ],
  "is_active": true,
  "sort_order": 0
}
'
{
  "resource": {
    "type": "HoldReason",
    "code": "damaged",
    "label": "Damaged",
    "sort_order": 30,
    "is_active": true,
    "is_system": true,
    "id": 12,
    "parent_code": "damaged",
    "allow_relocation": false,
    "children": "<array>",
    "parent": {
      "type": "HoldReason",
      "id": 3
    },
    "merchants": [
      {
        "type": "Merchant",
        "id": 4
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Generate a JWT access token through a Custom Global Integration and provide it with each request in the Authorization header prefixed with "Bearer" and then a single space.

Query Parameters

​
fields
enum<string>[]

Specify additional fields of the HoldReason object to be included in the response.

Available options:
basic,
all,
code,
label,
parent_code,
allow_relocation,
sort_order,
is_active,
is_system,
children,
parent,
merchants
​
fields:parent
enum<string>[]

Specify additional fields of the parent HoldReason object to be included in the response. See the selecting fields page for more information. Specify additional fields of the HoldReason object to be included in the response.

Available options:
basic,
all,
code,
label,
parent_code,
allow_relocation,
sort_order,
is_active,
is_system,
children,
parent,
merchants

Body

application/json
​
code
string
required

Stable identifier. Must match ^[a-z0-9_]+$, ≤ 64 characters, unique.

Example:

"qc_followup"

​
label
string
required

Human-readable label, ≤ 255 characters.

Example:

"QC Follow-up"

​
parent
HoldReasonRef · object
required

Reference to the top-level system reason that owns this child.

​
display_group
string | null

Display group name, ≤ 25 characters. Defaults to "Hold" via model.

Example:

"Hold"

​
allow_relocation
boolean | null

Whether inventory under this hold may be relocated. null = inherit from parent.

Example:

null

​
merchants
MerchantRef · object[] | null

Merchant scope restrictions. Empty array or omit for unrestricted.

​
is_active
boolean

Whether this reason is active. Defaults to true.

Example:

true

​
sort_order
integer

Display order within siblings. Defaults to 0.

Example:

0

Response

Hold reason created.

​
resource
HoldReason · object

An inventory hold reason. System (parent) reasons are seeded and immutable; user-defined child reasons can be added under any system parent and inherit allow_relocation semantics. Schema enforces a single nesting level: parent reasons MAY include a children array; child reasons do NOT carry a children key.