> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Update Inventory Settings

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/settings/inventory
Content-Type: application/json

Update inventory settings

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/settings/inventory/update-settings-inventory

## Authentication

- `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Information & Settings | modify | `store_v2_information` | | Information & Settings | read-only | `store_v2_information_read_only` | NOTE: Analytics endpoints require the Content (`store_v2_content` and `store_v2_content_read_only`) OAuth scope. ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

## Request

### Path parameters

- `store_hash` (string, required) — Permanent ID of the BigCommerce store.

### Query parameters

- `channel_id` (integer, optional) — Channel ID to use for channel-specific settings. If omitted, you will interact with the global settings only.

### Headers

- `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

### Body (application/json)

This endpoint expects an InventorySettings.

- `product_out_of_stock_behavior` (enum, optional) — Describes storefront behavior when product is out of stock.
  - Allowed values: `do_nothing`, `hide_product`, `hide_product_and_accessible`, `hide_product_and_redirect`
- `option_out_of_stock_behavior` (enum, optional) — Describes storefront behavior when variant is out of stock.
  - Allowed values: `do_nothing`, `hide_option`, `label_option`
- `update_stock_behavior` (enum, optional) — Describes when stock levels are updated. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/developer/docs/integrations/webhooks/event-reference#products), [SKU](/developer/docs/integrations/webhooks/event-reference#skus), and [inventory](/developer/docs/integrations/webhooks/event-reference/inventory-and-location-events#inventory) webhooks.
  - Allowed values: `order_placed`, `order_completed_or_shipped`
- `edit_order_stock_adjustment` (boolean, optional) — Describes whether stock levels automatically adjust when you edit an order. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/developer/docs/integrations/webhooks/event-reference#products), [SKU](/developer/docs/integrations/webhooks/event-reference#skus), and [inventory](/developer/docs/integrations/webhooks/event-reference/inventory-and-location-events#inventory) webhooks.
- `refund_order_stock_adjustment` (boolean, optional) — Describes whether stock levels automatically adjust when you refund or cancel an order. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/developer/docs/integrations/webhooks/event-reference#products), [SKU](/developer/docs/integrations/webhooks/event-reference#skus), and [inventory](/developer/docs/integrations/webhooks/event-reference/inventory-and-location-events#inventory) webhooks.
- `stock_level_display` (enum, optional) — Describes whether a storefront displays stock levels.
  - Allowed values: `dont_show`, `show`, `show_when_low`
- `default_out_of_stock_message` (string, optional) — Out of stock message displayed to shoppers.
- `hide_in_product_filtering` (boolean, optional) — Describes whether an option is hidden in product filtering. Applies when `option_out_of_stock_behavior` is set to `label_option`.
- `show_pre_order_stock_levels` (boolean, optional, default: false) — Describes whether pre-order stock levels are shown.
- `show_out_of_stock_message` (boolean, optional, default: false) — Describes whether out-of-stock messages are shown on product listing pages.
- `show_quantity_on_backorder` (boolean, optional, default: false) — Shows the quantity of an item that will be backordered, on the product detail page and in cart line items. Backorder display settings are omitted from the response entirely when the store's backorder feature is not enabled. See [Backorders](/developer/docs/admin/catalog-and-inventory/backorders).
- `show_quantity_on_hand` (boolean, optional, default: false) — Shows the quantity of an item that is ready to ship, in cart line items.
- `show_backorder_message` (boolean, optional, default: false) — Shows the per-variant backorder message on the product detail page, cart, and product cards.
- `show_backorder_availability_prompt` (boolean, optional, default: false) — Shows the availability prompt next to the stock level on the product detail page.
- `backorder_availability_prompt` (string, optional, default: More available for backorder) — Text of the availability prompt shown on the product detail page. Only shown when `show_backorder_availability_prompt` is `true`.
- `show_default_shipping_expectation_prompt` (boolean, optional, default: false) — Shows the shipping expectation message in cart totals when any item in the cart is backordered.
- `default_shipping_expectation_prompt` (string, optional, default: We ship available items right away, and backordered items as soon as they're in stock) — Text of the shipping expectation message shown in cart totals. Only shown when `show_default_shipping_expectation_prompt` is `true`.

## Response

### 200

OK, null indicates that a particular field has not been overridden on a channel level when channel level settings are requested

- `data` (InventorySettings, optional)
- `meta` (MetaOpen, optional) — Response metadata.

## Types

### InventorySettings

- `product_out_of_stock_behavior` (enum, optional) — Describes storefront behavior when product is out of stock.
  - Allowed values: `do_nothing`, `hide_product`, `hide_product_and_accessible`, `hide_product_and_redirect`
- `option_out_of_stock_behavior` (enum, optional) — Describes storefront behavior when variant is out of stock.
  - Allowed values: `do_nothing`, `hide_option`, `label_option`
- `update_stock_behavior` (enum, optional) — Describes when stock levels are updated. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/developer/docs/integrations/webhooks/event-reference#products), [SKU](/developer/docs/integrations/webhooks/event-reference#skus), and [inventory](/developer/docs/integrations/webhooks/event-reference/inventory-and-location-events#inventory) webhooks.
  - Allowed values: `order_placed`, `order_completed_or_shipped`
- `edit_order_stock_adjustment` (boolean, optional) — Describes whether stock levels automatically adjust when you edit an order. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/developer/docs/integrations/webhooks/event-reference#products), [SKU](/developer/docs/integrations/webhooks/event-reference#skus), and [inventory](/developer/docs/integrations/webhooks/event-reference/inventory-and-location-events#inventory) webhooks.
- `refund_order_stock_adjustment` (boolean, optional) — Describes whether stock levels automatically adjust when you refund or cancel an order. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/developer/docs/integrations/webhooks/event-reference#products), [SKU](/developer/docs/integrations/webhooks/event-reference#skus), and [inventory](/developer/docs/integrations/webhooks/event-reference/inventory-and-location-events#inventory) webhooks.
- `stock_level_display` (enum, optional) — Describes whether a storefront displays stock levels.
  - Allowed values: `dont_show`, `show`, `show_when_low`
- `default_out_of_stock_message` (string, optional) — Out of stock message displayed to shoppers.
- `hide_in_product_filtering` (boolean, optional) — Describes whether an option is hidden in product filtering. Applies when `option_out_of_stock_behavior` is set to `label_option`.
- `show_pre_order_stock_levels` (boolean, optional, default: false) — Describes whether pre-order stock levels are shown.
- `show_out_of_stock_message` (boolean, optional, default: false) — Describes whether out-of-stock messages are shown on product listing pages.
- `show_quantity_on_backorder` (boolean, optional, default: false) — Shows the quantity of an item that will be backordered, on the product detail page and in cart line items. Backorder display settings are omitted from the response entirely when the store's backorder feature is not enabled. See [Backorders](/developer/docs/admin/catalog-and-inventory/backorders).
- `show_quantity_on_hand` (boolean, optional, default: false) — Shows the quantity of an item that is ready to ship, in cart line items.
- `show_backorder_message` (boolean, optional, default: false) — Shows the per-variant backorder message on the product detail page, cart, and product cards.
- `show_backorder_availability_prompt` (boolean, optional, default: false) — Shows the availability prompt next to the stock level on the product detail page.
- `backorder_availability_prompt` (string, optional, default: More available for backorder) — Text of the availability prompt shown on the product detail page. Only shown when `show_backorder_availability_prompt` is `true`.
- `show_default_shipping_expectation_prompt` (boolean, optional, default: false) — Shows the shipping expectation message in cart totals when any item in the cart is backordered.
- `default_shipping_expectation_prompt` (string, optional, default: We ship available items right away, and backordered items as soon as they're in stock) — Text of the shipping expectation message shown in cart totals. Only shown when `show_default_shipping_expectation_prompt` is `true`.

### MetaOpen

Response metadata.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "data": {
    "product_out_of_stock_behavior": "do_nothing",
    "option_out_of_stock_behavior": "do_nothing",
    "update_stock_behavior": "order_placed",
    "edit_order_stock_adjustment": true,
    "refund_order_stock_adjustment": true,
    "stock_level_display": "dont_show",
    "default_out_of_stock_message": "Currently out of stock",
    "hide_in_product_filtering": true,
    "show_pre_order_stock_levels": true,
    "show_out_of_stock_message": true,
    "show_quantity_on_backorder": false,
    "show_quantity_on_hand": false,
    "show_backorder_message": false,
    "show_backorder_availability_prompt": false,
    "backorder_availability_prompt": "More available for backorder",
    "show_default_shipping_expectation_prompt": false,
    "default_shipping_expectation_prompt": "We ship available items right away, and backordered items as soon as they're in stock"
  },
  "meta": {}
}
```

**SDK Code**

```python
import requests

url = "https://api.bigcommerce.com/stores/store_hash/v3/settings/inventory"

payload = {}
headers = {
    "Accept": "application/json",
    "X-Auth-Token": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.bigcommerce.com/stores/store_hash/v3/settings/inventory';
const options = {
  method: 'PUT',
  headers: {
    Accept: 'application/json',
    'X-Auth-Token': '<apiKey>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bigcommerce.com/stores/store_hash/v3/settings/inventory"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("X-Auth-Token", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.bigcommerce.com/stores/store_hash/v3/settings/inventory")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = 'application/json'
request["X-Auth-Token"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.bigcommerce.com/stores/store_hash/v3/settings/inventory")
  .header("Accept", "application/json")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.bigcommerce.com/stores/store_hash/v3/settings/inventory', [
  'body' => '{}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/settings/inventory");
var request = new RestRequest(Method.PUT);
request.AddHeader("Accept", "application/json");
request.AddHeader("X-Auth-Token", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "application/json",
  "X-Auth-Token": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/settings/inventory")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```