03API reference

Version 1.0.0Made from openapi.yaml

Inventory

Keep the store's hand-managed stock in step with an inventory system, by your own external_id. FastBound items are read only (FastBound stays the record for guns). A change shows on the store after the next rebuild, normally within minutes.

GET/inventory/itemsList stock items GET/inventory/items/{external_id}One stock item PUT/inventory/items/{external_id}Create or update a hand-managed item PATCH/inventory/items/{external_id}Change a hand-managed item DELETE/inventory/items/{external_id}Remove a hand-managed item POST/inventory/items/{external_id}/zeroSet the quantity to zero POST/inventory/batchChange many items at once

List stock items

GET/inventory/items

Scoped private key (rm_prv_), from a server

inventory:read

Hand-managed items and FastBound items, oldest change first, with cursor paging. A FastBound item has writable: false and only the last four of its serial; cost is never shown. Needs the inventory:read permission.

Parameters

Name	In	Type	Description
`source`	query	`"manual" \| "fastbound"`
`product_key`	query	`string`
`external_id`	query	`string`
`hidden`	query	`"true" \| "false"`
`updated_since`	query	`string`	ISO 8601 date or time. Lists what changed at or after it, oldest change first.
`limit`	query	`integer`	Default 50. 1 to 100.
`cursor`	query	`string`	The `next_cursor` of the previous page. Opaque; do not build or change one. A cursor belongs to the request that produced it; with other parameters it is `bad_cursor`. Up to 2048 characters.

Responses

200A page.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object[]`
data[].`id`required	`string`	Rollmark's id for the item.
data[].`external_id`	`string \| null`	Your id for a hand-managed item. Null for a FastBound item.
data[].`source`required	`"manual" \| "fastbound"`
data[].`writable`required	`boolean`	True for a hand-managed item; false for a FastBound item
data[].`product_key`	`string \| null`	The catalog product a hand-managed item adds stock to.
data[].`title`	`string \| null`
data[].`manufacturer`	`string`
data[].`model`	`string`
data[].`upc`	`string \| null`
data[].`mpn`	`string \| null`
data[].`category`	`string \| null`
data[].`firearm`	`boolean`
data[].`quantity`required	`integer`	At least 0.
data[].`price`	`number \| null`	Your selling price in dollars.
data[].`condition`	`string \| null`
data[].`location`	`string \| null`
data[].`note`	`string \| null`
data[].`hidden`required	`boolean`	Hidden from the store (`store_hidden`): the item counts for nothing there, but stays in your inventory.
data[].`serial_last4`	`string \| null`	Only on a FastBound item. The last four characters of its serial number; never more.
data[].`updated_at`required	`string (date-time)`
`next_cursor`required	`string \| null`

Errors400401403429503in the error envelope.

Example

Shell
curl "https://app.getrollmark.com/api/v1/inventory/items" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

One stock item

GET/inventory/items/{external_id}

Scoped private key (rm_prv_), from a server

inventory:read

A hand-managed item by your own id. Any item, FastBound ones too, can also be read by its Rollmark id. Needs the inventory:read permission.

Parameters

Name	In	Type	Description
`external_id`required	path	`string`	Your own id for the item (1 to 100 characters), URL-encoded. 1 to 100 characters.

Responses

200The item.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`	Rollmark's id for the item.
data.`external_id`	`string \| null`	Your id for a hand-managed item. Null for a FastBound item.
data.`source`required	`"manual" \| "fastbound"`
data.`writable`required	`boolean`	True for a hand-managed item; false for a FastBound item
data.`product_key`	`string \| null`	The catalog product a hand-managed item adds stock to.
data.`title`	`string \| null`
data.`manufacturer`	`string`
data.`model`	`string`
data.`upc`	`string \| null`
data.`mpn`	`string \| null`
data.`category`	`string \| null`
data.`firearm`	`boolean`
data.`quantity`required	`integer`	At least 0.
data.`price`	`number \| null`	Your selling price in dollars.
data.`condition`	`string \| null`
data.`location`	`string \| null`
data.`note`	`string \| null`
data.`hidden`required	`boolean`	Hidden from the store (`store_hidden`): the item counts for nothing there, but stays in your inventory.
data.`serial_last4`	`string \| null`	Only on a FastBound item. The last four characters of its serial number; never more.
data.`updated_at`required	`string (date-time)`

Errors401403404429503in the error envelope.

Example

Shell
curl "https://app.getrollmark.com/api/v1/inventory/items/<external_id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Create or update a hand-managed item

PUT/inventory/items/{external_id}

Scoped private key (rm_prv_), from a server

inventory:write

Creates the item if your external_id is new (201, a quantity is required), or changes the fields you send (200; what you leave out stays). Checked like the Add item form. The same external_id is always the same item, so a repeat is safe. A FastBound item is 409 fastbound_managed; a field named cost is 400. The store shows the change after the next rebuild, which this call queues. Needs the inventory:write permission.

Parameters

Name	In	Type	Description
`external_id`required	path	`string`	Your own id for the item (1 to 100 characters), URL-encoded. 1 to 100 characters.
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Request body

Field	Type	Description
`link_to`	`string`	A catalog product key the item adds stock to. Give this, or `title` and `category` for a product of its own. Cannot change after the item is made.
`title`	`string`	Up to 160 characters.
`manufacturer`	`string`	Up to 80 characters.
`model`	`string`	Up to 80 characters.
`upc`	`string \| null`	A valid UPC/EAN (the check digit is verified).
`mpn`	`string`	Up to 60 characters.
`category`	`"handguns" \| "rifles" \| "shotguns" \| "nfa" \| "ammunition" \| "magazines" \| "optics" \| "parts" \| "gear" \| "reloading"`
`quantity`	`integer`	0 to 9999.
`quantity_delta`	`integer`	PATCH only. Adds (or, negative, takes) this many; the quantity never goes below 0. Applied in the database, so two writers do not lose an update. Not with `quantity`.
`price`	`number \| null`	Dollars; null clears it. At least 0.
`condition`	`string`	Up to 40 characters.
`location`	`string`	Up to 60 characters.
`note`	`string`	Up to 300 characters.
`hidden`	`boolean`	Hide the item from the store

Responses

200Changed, or nothing to change.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`	Rollmark's id for the item.
data.`external_id`	`string \| null`	Your id for a hand-managed item. Null for a FastBound item.
data.`source`required	`"manual" \| "fastbound"`
data.`writable`required	`boolean`	True for a hand-managed item; false for a FastBound item
data.`product_key`	`string \| null`	The catalog product a hand-managed item adds stock to.
data.`title`	`string \| null`
data.`manufacturer`	`string`
data.`model`	`string`
data.`upc`	`string \| null`
data.`mpn`	`string \| null`
data.`category`	`string \| null`
data.`firearm`	`boolean`
data.`quantity`required	`integer`	At least 0.
data.`price`	`number \| null`	Your selling price in dollars.
data.`condition`	`string \| null`
data.`location`	`string \| null`
data.`note`	`string \| null`
data.`hidden`required	`boolean`	Hidden from the store (`store_hidden`): the item counts for nothing there, but stays in your inventory.
data.`serial_last4`	`string \| null`	Only on a FastBound item. The last four characters of its serial number; never more.
data.`updated_at`required	`string (date-time)`
`change`required	`"created" \| "updated" \| "unchanged"`
`effective`required	`"after_rebuild"`	The store shows the change after the next rebuild.

201Created.

Errors400401403409429503in the error envelope.

Example

Shell
curl -X PUT "https://app.getrollmark.com/api/v1/inventory/items/<external_id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Change a hand-managed item

PATCH/inventory/items/{external_id}

Scoped private key (rm_prv_), from a server

inventory:write

Changes an item that exists (404 otherwise; use PUT to create). Send quantity to set it or quantity_delta to add or take; price; hidden to hide the item from the store or show it again. Needs the inventory:write permission.

Parameters

Name	In	Type	Description
`external_id`required	path	`string`	Your own id for the item (1 to 100 characters), URL-encoded. 1 to 100 characters.
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Request body

Field	Type	Description
`link_to`	`string`	A catalog product key the item adds stock to. Give this, or `title` and `category` for a product of its own. Cannot change after the item is made.
`title`	`string`	Up to 160 characters.
`manufacturer`	`string`	Up to 80 characters.
`model`	`string`	Up to 80 characters.
`upc`	`string \| null`	A valid UPC/EAN (the check digit is verified).
`mpn`	`string`	Up to 60 characters.
`category`	`"handguns" \| "rifles" \| "shotguns" \| "nfa" \| "ammunition" \| "magazines" \| "optics" \| "parts" \| "gear" \| "reloading"`
`quantity`	`integer`	0 to 9999.
`quantity_delta`	`integer`	PATCH only. Adds (or, negative, takes) this many; the quantity never goes below 0. Applied in the database, so two writers do not lose an update. Not with `quantity`.
`price`	`number \| null`	Dollars; null clears it. At least 0.
`condition`	`string`	Up to 40 characters.
`location`	`string`	Up to 60 characters.
`note`	`string`	Up to 300 characters.
`hidden`	`boolean`	Hide the item from the store

Responses

200Changed, or nothing to change.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`	Rollmark's id for the item.
data.`external_id`	`string \| null`	Your id for a hand-managed item. Null for a FastBound item.
data.`source`required	`"manual" \| "fastbound"`
data.`writable`required	`boolean`	True for a hand-managed item; false for a FastBound item
data.`product_key`	`string \| null`	The catalog product a hand-managed item adds stock to.
data.`title`	`string \| null`
data.`manufacturer`	`string`
data.`model`	`string`
data.`upc`	`string \| null`
data.`mpn`	`string \| null`
data.`category`	`string \| null`
data.`firearm`	`boolean`
data.`quantity`required	`integer`	At least 0.
data.`price`	`number \| null`	Your selling price in dollars.
data.`condition`	`string \| null`
data.`location`	`string \| null`
data.`note`	`string \| null`
data.`hidden`required	`boolean`	Hidden from the store (`store_hidden`): the item counts for nothing there, but stays in your inventory.
data.`serial_last4`	`string \| null`	Only on a FastBound item. The last four characters of its serial number; never more.
data.`updated_at`required	`string (date-time)`
`change`required	`"created" \| "updated" \| "unchanged"`
`effective`required	`"after_rebuild"`	The store shows the change after the next rebuild.

Errors400401403404409429503in the error envelope.

Example

Shell
curl -X PATCH "https://app.getrollmark.com/api/v1/inventory/items/<external_id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Remove a hand-managed item

DELETE/inventory/items/{external_id}

Scoped private key (rm_prv_), from a server

inventory:write

Takes the item out of the inventory (the same as Remove on the screen). To keep the item and show none on hand, use /zero; to keep it off the store, set hidden. Needs the inventory:write permission.

Parameters

Name	In	Type	Description
`external_id`required	path	`string`	Your own id for the item (1 to 100 characters), URL-encoded. 1 to 100 characters.
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Responses

200Removed.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`external_id`required	`string`
data.`deleted`required	`true`

Errors400401403404409429503in the error envelope.

Example

Shell
curl -X DELETE "https://app.getrollmark.com/api/v1/inventory/items/<external_id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Set the quantity to zero

POST/inventory/items/{external_id}/zero

Scoped private key (rm_prv_), from a server

inventory:write

The item stays (and so does your external_id); the store shows none on hand. Needs the inventory:write permission.

Parameters

Name	In	Type	Description
`external_id`required	path	`string`	Your own id for the item (1 to 100 characters), URL-encoded. 1 to 100 characters.
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Responses

200Set, or already zero.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`	Rollmark's id for the item.
data.`external_id`	`string \| null`	Your id for a hand-managed item. Null for a FastBound item.
data.`source`required	`"manual" \| "fastbound"`
data.`writable`required	`boolean`	True for a hand-managed item; false for a FastBound item
data.`product_key`	`string \| null`	The catalog product a hand-managed item adds stock to.
data.`title`	`string \| null`
data.`manufacturer`	`string`
data.`model`	`string`
data.`upc`	`string \| null`
data.`mpn`	`string \| null`
data.`category`	`string \| null`
data.`firearm`	`boolean`
data.`quantity`required	`integer`	At least 0.
data.`price`	`number \| null`	Your selling price in dollars.
data.`condition`	`string \| null`
data.`location`	`string \| null`
data.`note`	`string \| null`
data.`hidden`required	`boolean`	Hidden from the store (`store_hidden`): the item counts for nothing there, but stays in your inventory.
data.`serial_last4`	`string \| null`	Only on a FastBound item. The last four characters of its serial number; never more.
data.`updated_at`required	`string (date-time)`
`change`required	`"created" \| "updated" \| "unchanged"`
`effective`required	`"after_rebuild"`	The store shows the change after the next rebuild.

Errors401403404409429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/inventory/items/<external_id>/zero" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Change many items at once

POST/inventory/batch

Scoped private key (rm_prv_), from a server

inventory:write

Idempotency-Key required

Up to 500 operations (upsert, patch, zero, delete), each with its external_id and the fields of the single call. Each is applied on its own, so one bad item does not lose the rest: the answer is 200 with a result per item and the counts, and an item's failure is in its result. One rebuild is queued for the whole request. The body is at most 1 MB and an Idempotency-Key is required, so a request that timed out can be sent again. A batch is limited to 60 a minute. Needs the inventory:write permission.

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`	Required on this call, because it counts toward billing. See the other calls for how the key works. 1 to 255 characters.

Request body

Field	Type	Description
`items`required	`object[]`	1 to 500 items.
items[].`external_id`required	`string`
items[].`op`	`"upsert" \| "patch" \| "zero" \| "delete"`	Default "upsert".

Responses

200Applied item by item.

Headers: X-Request-Id

Field	Type	Description
`results`required	`object[]`
results[].`external_id`required	`string \| null`
results[].`status`required	`"created" \| "updated" \| "unchanged" \| "deleted" \| "error"`
results[].`error`	`object`
results[].error.`code`required	`string`
results[].error.`message`required	`string`
results[].error.`fields`	`object[]`
results[].error.fields[].`field`	`string`
results[].error.fields[].`message`	`string`
`summary`required	`object`
summary.`total`required	`integer`
summary.`created`required	`integer`
summary.`updated`required	`integer`
summary.`unchanged`required	`integer`
summary.`deleted`required	`integer`
summary.`error`required	`integer`
`effective`required	`"after_rebuild"`

Errors400401403413429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/inventory/batch" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Idempotency-Key: <one id per action>" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"external_id":"…"}]}'