Record a stock check count attempt

curl --request POST \
  --url https://clarus-api.com/api/stock_checks/{id}/record_attempt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Clarus-Subdomain: <api-key>' \
  --data '
{
  "data": {
    "attributes": {
      "product_id": 42,
      "physical_count": 5,
      "batch": "BATCH_A",
      "sell_by_date": "2026-06-01",
      "best_before_date": "2026-12-01"
    }
  }
}
'

import requests

url = "https://clarus-api.com/api/stock_checks/{id}/record_attempt"

payload = { "data": { "attributes": {
            "product_id": 42,
            "physical_count": 5,
            "batch": "BATCH_A",
            "sell_by_date": "2026-06-01",
            "best_before_date": "2026-12-01"
        } } }
headers = {
    "Authorization": "Bearer <token>",
    "X-Clarus-Subdomain": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Clarus-Subdomain': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      attributes: {
        product_id: 42,
        physical_count: 5,
        batch: 'BATCH_A',
        sell_by_date: '2026-06-01',
        best_before_date: '2026-12-01'
      }
    }
  })
};

fetch('https://clarus-api.com/api/stock_checks/{id}/record_attempt', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "attempt_result": "success",
  "attempt_number": 1
}

{
  "error": "<string>"
}

{
  "errors": [
    {
      "code": 123,
      "symbol": "<string>",
      "details": "<string>",
      "source": "<string>",
      "context": {}
    }
  ]
}

{
  "errors": [
    {
      "code": 123,
      "symbol": "<string>",
      "details": "<string>",
      "source": "<string>",
      "context": {}
    }
  ]
}

POST

api

stock_checks

{id}

record_attempt

Record a stock check count attempt

curl --request POST \
  --url https://clarus-api.com/api/stock_checks/{id}/record_attempt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Clarus-Subdomain: <api-key>' \
  --data '
{
  "data": {
    "attributes": {
      "product_id": 42,
      "physical_count": 5,
      "batch": "BATCH_A",
      "sell_by_date": "2026-06-01",
      "best_before_date": "2026-12-01"
    }
  }
}
'

import requests

url = "https://clarus-api.com/api/stock_checks/{id}/record_attempt"

payload = { "data": { "attributes": {
            "product_id": 42,
            "physical_count": 5,
            "batch": "BATCH_A",
            "sell_by_date": "2026-06-01",
            "best_before_date": "2026-12-01"
        } } }
headers = {
    "Authorization": "Bearer <token>",
    "X-Clarus-Subdomain": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Clarus-Subdomain': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      attributes: {
        product_id: 42,
        physical_count: 5,
        batch: 'BATCH_A',
        sell_by_date: '2026-06-01',
        best_before_date: '2026-12-01'
      }
    }
  })
};

fetch('https://clarus-api.com/api/stock_checks/{id}/record_attempt', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "attempt_result": "success",
  "attempt_number": 1
}

{
  "error": "<string>"
}

{
  "errors": [
    {
      "code": 123,
      "symbol": "<string>",
      "details": "<string>",
      "source": "<string>",
      "context": {}
    }
  ]
}

{
  "errors": [
    {
      "code": 123,
      "symbol": "<string>",
      "details": "<string>",
      "source": "<string>",
      "context": {}
    }
  ]
}

Request Structure

{
  "data": {
    "attributes": {
      "product_id": 42,
      "physical_count": 5.0,
      "batch": "BATCH_A",
      "sell_by_date": "2026-06-01",
      "best_before_date": "2026-12-01"
    }
  }
}

Key Fields

Field	Required	Description
`product_id`	Yes	ID of the product being counted
`physical_count`	Yes	Quantity actually counted in the location
`batch`	No	Batch identifier when the account uses batch tracking
`sell_by_date`	No	Sell-by date when the account uses sell-by tracking
`best_before_date`	No	Best-before date when the account uses best-before tracking

Behavior

The product, batch and date fields together identify a stock group within the stock check. Repeat counts for the same group accumulate as numbered attempts.
The attempt is success when physical_count matches the system count for that group, otherwise failure.
A third attempt for the same group is rejected with 422; failed groups must be resolved via POST /api/stock_checks/resolve.
The stock check and its associated task must still be active. Completed, cancelled or non-pending checks return 422.

Authorizations

Authorization

string

header

required

OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token.

X-Clarus-Subdomain

string

header

required

The subdomain/tenant name identifying which tenant's data to access. Required for all API requests.

Path Parameters

integer

required

The unique identifier of the stock check

Body

application/json

data

object

required

Show child attributes

Response

Attempt recorded

attempt_result

enum<string>

Whether the physical count matched the system count for the matched stock group

Available options:

success,

failure

attempt_number

integer

Which attempt this is for the matched stock group (1 or 2)

⌘I

​Request Structure

​Key Fields

​Behavior

Authorizations

Path Parameters

Body

Response

Request Structure

Key Fields

Behavior