Docs
/
FFL Monkey

docs.fflmonkey.com/data-feed/inventory/adjust. For the whole Data Feed API as one document, use Print or save as PDF at the foot of the docs menu.

Docs / Data Feed / In-house inventory

For Data Feed stores
Endpoint · Move stock up or down

POST/items/{upc}/adjust

Move a row's stock by an amount, for systems that know what happened ("sold one") rather than what is on the shelf.

Needs In-house inventory: Read and writeBase URL https://backend.fflmonkey.com/api/v1/inventoryCounts 1 toward 120 a minute

Fields

Needs write access. The row must already exist.

FieldTypeRule
deltarequiredintegerA whole number from -100,000 to 100,000, not 0.
reasonoptionalstring or nullUp to 255 characters, kept with the adjustment.
Idempotency-KeyheaderstringOptional but strongly recommended. 1 to 255 printable characters, unique per adjustment. See Idempotency.
  • Stock never goes below 0. A delta that would take it lower stops at 0, and the response says so with clamped and applied_delta.
  • On a row priced 0.00, an adjustment that would leave stock above 0 is refused with 422 on price: set a price with PUT or PATCH first. An adjustment that takes its stock to 0 is allowed.

The adjustment in the response

The answer is the row as it now is, in data, and the adjustment beside it, in adjustment: {"data": {…}, "adjustment": {…}}.

FieldMeaning
deltaWhat you asked for.
applied_deltaWhat changed. Differs from delta only when the stock stopped at 0.
previous_stockStock before.
stockStock after.
clampedtrue when the stock stopped at 0.
reasonYour reason, or null.
idempotency_keyYour key, or null.
created_atWhen it happened.

Returns

  • 200Applied, or replayed (header Idempotent-Replayed: true).
  • 404item_not_found: the row must exist first.
  • 409idempotency_key_reused: the key was used for a different adjustment.
  • 422A field broke a rule, or the row is priced 0.00.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included and 429 rate_limited.

Idempotency

PUT, PATCH and batch set absolute values, so sending one twice is harmless. An adjustment is different: if a "sold one" request times out and your system sends it again, a second -1 would take away a unit you still have.

So send an Idempotency-Key header with every adjustment: a value unique to that one event and the same on every retry of it, such as your POS sale id plus the line number. Up to 255 printable characters.

  • Same key, same UPC, same delta: nothing changes. You get the original result back, with the header Idempotent-Replayed: true. data shows the row as it is now.
  • Same key, different UPC or delta: 409 idempotency_key_reused, and nothing changes.
  • A request that failed (for example 404 because the row did not exist yet) does not use up its key. Retry it with the same key once the cause is fixed.

Keys are per store, and are remembered for as long as the adjustment log is kept.

Example

FFL Monkey Data Feed API, version 1. Questions: Support in your FFL Monkey account, or [email protected].