Skip to content

Set SKU-specific inventory batch settings

Request

Creates or updates SKU-specific inventory batch settings.

For merchants enrolled in expiry handling, a write that sets action_weeks_before_expiry or expiry_follow_up_action to a new value also turns batch tracking on for the SKU, since expiry handling only applies to a batch-tracked SKU. Clearing a value, re-sending one the settings already hold, and writing neither field all leave batch tracking as it is, whether the settings are being created or edited. When the merchant does not have batch tracking, a write that would turn it on is rejected with 422 and nothing is saved.

Security
BearerAuth
Path
sku_idinteger, (int64)required

SKU ID

Bodyapplication/json
batch_prioritystring
Enum:"first_expired_first_out""first_produced_first_out"
b2c_shelf_life_in_weeksinteger or null
b2b_shelf_life_in_weeksinteger or null
ito_shelf_life_in_weeksinteger or null
kit_shelf_life_in_weeksinteger or null
action_weeks_before_expiryinteger or null, >= 0

Weeks before expiry at which the batch is taken out of circulation. Null clears the value.

expiry_follow_up_actionstring or null

What happens to a batch once it has expired. null makes this SKU inherit the merchant default's action; the resolved value is on the SKU's effective_inventory_batch_settings. Omit it to keep the stored value.

Enum:"block_only""block_and_dispose""block_and_sendback"null
curl -i -X PUT \
  'https://developers.hive.app/_mock/merchant-api-v2/mapi_v2_oas31/skus/{sku_id}/inventory_batch_settings' \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "batch_priority": "first_expired_first_out",
    "b2c_shelf_life_in_weeks": 0,
    "b2b_shelf_life_in_weeks": 0,
    "ito_shelf_life_in_weeks": 0,
    "kit_shelf_life_in_weeks": 0,
    "action_weeks_before_expiry": 0,
    "expiry_follow_up_action": "block_only"
  }'

Responses

SKU-specific inventory batch settings

Bodyapplication/json
idinteger, (int64)required

Unique identifier

batch_prioritystringrequired

Priority strategy for batch selection

Enum:"first_expired_first_out""first_produced_first_out"
b2c_shelf_life_in_weeksinteger or nullrequired

Minimum remaining shelf life in weeks for B2C orders

b2b_shelf_life_in_weeksinteger or nullrequired

Minimum remaining shelf life in weeks for B2B orders

ito_shelf_life_in_weeksinteger or nullrequired

Minimum remaining shelf life in weeks for inventory transfer orders

kit_shelf_life_in_weeksinteger or nullrequired

Minimum remaining shelf life in weeks for kitting

is_merchant_defaultbooleanrequired

Whether this is the merchant's default settings (true) or SKU-specific (false)

sku_idinteger or null, (int64)required

SKU ID if this is a SKU-specific setting, null for merchant default

action_weeks_before_expiryinteger or null, >= 0required

How many weeks before a batch's expiry date its stock is taken out of circulation, as stored on this settings record. Hive resolves the window it actually applies one field at a time: the SKU's own value, else the merchant default's value, else Hive's own default. So a null here means only that this record sets no value — on a SKU-specific record (is_merchant_default: false) the merchant default may still supply one, and only on the merchant default record does null mean Hive's own default applies. Always null until the batch expiry handling feature is rolled out to the account.

expiry_follow_up_actionstring or nullrequired

What happens to a batch once it has expired: block it only, dispose of it, or send it back to the merchant. The value as stored on this settings record, not resolved through the merchant default. On a SKU-specific record (is_merchant_default: false) null means the SKU inherits the merchant default's action; the merchant default record always carries one. Also null until the batch expiry handling feature is rolled out to the account.

Enum:"block_only""block_and_dispose""block_and_sendback"null
Response
{
  "id": 0,
  "batch_priority": "first_expired_first_out",
  "b2c_shelf_life_in_weeks": 0,
  "b2b_shelf_life_in_weeks": 0,
  "ito_shelf_life_in_weeks": 0,
  "kit_shelf_life_in_weeks": 0,
  "is_merchant_default": true,
  "sku_id": 0,
  "action_weeks_before_expiry": 0,
  "expiry_follow_up_action": "block_only"
}