Write fractional inventory

Adjust or replace Measura inventory using ordinary measured values such as 2.75 kg or 14.5 m.

Available operations

Measura coordinates Shopify integer inventory with its fractional inventory data. Submit the exact measured value and a compatible unit; do not calculate the Shopify and fractional portions yourself.

Operation	Endpoint	Use case
Adjust current inventory	`POST /api/v1/inventory/adjustments`	Sales, returns, receiving stock, and inventory corrections.
Set final inventory	`PUT /api/v1/inventory/levels`	ERP, warehouse, and scheduled inventory synchronization.

Shared requirements

A Measura public API key and an idempotency key are required.
Each request operates on one Shopify location.
Each request accepts up to 100 unique variants.
Location and variant IDs must be Shopify legacy numeric IDs, not GraphQL GIDs.
Measurement units must be compatible with each variant's configured measurement type.

Authentication and idempotency

Send a public API key as a bearer token. Keys have the form apik_<keyId>_<secret> and can be generated from the Measura Public API settings page.

Authorization: Bearer apik_example_secret
Content-Type: application/json
Idempotency-Key: warehouse-receipt-PO-1048

Generate a new Idempotency-Key for every logical inventory operation. Reuse that key when retrying the same operation so a network retry cannot apply the write twice.

Keys may contain up to 255 characters.
Keys are scoped to the authenticated shop and retained for 24 hours.
During that period, never reuse a key with a different endpoint, location, variant, quantity, or unit.

Safe retries:

When a completed request is repeated with the same key and identical body, Measura returns the saved response with the Idempotency-Replayed: true response header.

POST /api/v1/inventory/adjustments

Headers:
  Authorization: Bearer <api-key>
  Content-Type: application/json
  Idempotency-Key: <unique-operation-key>

Request body

{
  "locationId": "123456",
  "adjustments": [
    {
      "variantId": "111",
      "delta": {
        "value": 5.75,
        "unit": "kg"
      }
    },
    {
      "variantId": "222",
      "delta": {
        "value": -1.5,
        "unit": "m"
      }
    }
  ]
}

Note

Use an adjustment when the supplied value is a change from current inventory. A positive delta adds inventory; a negative delta removes it. This example adds 5.75 kg to variant 111 and removes 1.5 m from variant 222.

cURL example

curl --request POST "https://sell-by-weight-app.atomicpos.com/api/v1/inventory/adjustments" \
  --header "Authorization: Bearer apik_example_secret" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: warehouse-receipt-PO-1048" \
  --data '{
    "locationId": "123456",
    "adjustments": [
      {
        "variantId": "111",
        "delta": { "value": 5.75, "unit": "kg" }
      }
    ]
  }'

PUT /api/v1/inventory/levels

Headers:
  Authorization: Bearer <api-key>
  Content-Type: application/json
  Idempotency-Key: <unique-operation-key>

Request body

{
  "locationId": "123456",
  "levels": [
    {
      "variantId": "111",
      "quantity": {
        "value": 18.75,
        "unit": "kg"
      }
    },
    {
      "variantId": "222",
      "quantity": {
        "value": 0,
        "unit": "m"
      }
    }
  ]
}

Note

Use an absolute level when the supplied value is the final inventory that should remain. This example sets variant 111 to exactly 18.75 kg and variant 222 to zero. Absolute levels cannot be negative.

cURL example

curl --request PUT "https://sell-by-weight-app.atomicpos.com/api/v1/inventory/levels" \
  --header "Authorization: Bearer apik_example_secret" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: erp-stock-snapshot-2026-08-13T18:00:00Z" \
  --data '{
    "locationId": "123456",
    "levels": [
      {
        "variantId": "111",
        "quantity": { "value": 18.75, "unit": "kg" }
      }
    ]
  }'

Request fields

Field	Type	Description
`locationId`	string	Required. Shopify legacy numeric location ID.
`adjustments`	array	Required for an adjustment request. One to 100 unique variant adjustments.
`adjustments[].variantId`	string	Required. Shopify legacy numeric product variant ID.
`adjustments[].delta.value`	number	Required. Finite positive, negative, or zero change; numeric strings are not accepted.
`adjustments[].delta.unit`	string	Required. A measurement unit compatible with the variant configuration.
`levels`	array	Required for an absolute-level request. One to 100 unique variant levels.
`levels[].variantId`	string	Required. Shopify legacy numeric product variant ID.
`levels[].quantity.value`	number	Required. Finite value greater than or equal to zero; numeric strings are not accepted.
`levels[].quantity.unit`	string	Required. A measurement unit compatible with the variant configuration.

Duplicate variants:

Variant IDs must be unique within a request. Measura rejects duplicate variants instead of processing them in request order.

Successful response

Measura returns the previous and resulting measured inventory in each variant's configured inventory unit. The returned unit can differ from the submitted unit when Measura performs a compatible conversion.

{
  "success": true,
  "data": {
    "operation": "adjustment",
    "locationId": "123456",
    "results": [
      {
        "variantId": "111",
        "status": "updated",
        "previousQuantity": {
          "value": 12.5,
          "unit": "kg"
        },
        "quantity": {
          "value": 18.25,
          "unit": "kg"
        }
      }
    ]
  },
  "error": null,
  "requestId": "4a402347-312f-4628-8c88-b24ee4ec3d86"
}

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`data.operation`	string	The inventory operation that was performed.
`data.locationId`	string	The Shopify legacy numeric location ID.
`data.results`	array	The result for every submitted variant.
`data.results[].variantId`	string	The Shopify legacy numeric variant ID.
`data.results[].status`	string	The outcome for the variant, such as updated.
`data.results[].previousQuantity`	object	Measured inventory before the write, in the configured inventory unit.
`data.results[].quantity`	object	Measured inventory after the write, in the configured inventory unit.
`error`	null	Null for a successful request.
`requestId`	string	Request identifier to include when contacting support.

For the standard error envelope and status codes, see Error codes.