Skip to main content
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"
    }
  }
}
'
{
  "attempt_result": "success",
  "attempt_number": 1
}

​
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

FieldRequiredDescription
product_idYesID of the product being counted
physical_countYesQuantity actually counted in the location
batchNoBatch identifier when the account uses batch tracking
sell_by_dateNoSell-by date when the account uses sell-by tracking
best_before_dateNoBest-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

​
id
integer
required

The unique identifier of the stock check

Body

application/json
​
data
object
required

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)