03API reference

Version 1.0.0Made from openapi.yaml

Distributor orders

Read your orders to distributors and make DRAFTS from order lines. Sending, readying, confirming, cancelling and receiving a distributor order are not in the API; staff do them in Rollmark.

GET/distributor-ordersList distributor orders POST/distributor-orders/draftsMake drafts from order lines GET/distributor-orders/{id}One distributor order DELETE/distributor-orders/{id}Delete a draft POST/distributor-orders/{id}/linesAdd an order line to a draft DELETE/distributor-orders/{id}/lines/{line_no}Remove a line from a draft

List distributor orders

GET/distributor-orders

Scoped private key (rm_prv_), from a server

distributor_orders:read

The store's orders to distributors, oldest change first. Unit costs and quoted totals only for a key that also has catalog:cost:read. Needs the distributor_orders:read permission.

Parameters

Name	In	Type	Description
`status`	query	`"draft" \| "ready" \| "sent" \| "confirmed" \| "partially_shipped" \| "shipped" \| "received" \| "cancelled" \| "failed"`
`distributor`	query	`string`
`order_id`	query	`string`	Only POs that serve this order.
`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, X-RateLimit-Remaining

Field	Type	Description
`data`required	`object[]`
data[].`id`required	`string`
data[].`po_number`required	`string`
data[].`distributor`required	`string`	The distributor id (`RSR`, `Lipseys`, `Davidsons`, `SportsSouth`, `Zanders`).
data[].`status`required	`"draft" \| "ready" \| "sent" \| "confirmed" \| "partially_shipped" \| "shipped" \| "received" \| "cancelled" \| "failed"`
data[].`method`required	`"api" \| "manual"`	How staff will place it.
data[].`ship_to`required	`"shop" \| "customer_ffl" \| "customer_address"`
data[].`purpose`	`"stock" \| "customer"`
data[].`distributor_order_no`	`string \| null`	The distributor's own order or confirmation number
data[].`tracking`	`string \| null`
data[].`client_order_ids`	`string[]`
data[].`send_groups`	`object[]`	One entry per customer when a direct-ship PO was sent as several distributor orders.
data[].send_groups[].`order_id`	`string`
data[].send_groups[].`sent_po`	`string`
data[].send_groups[].`status`	`string`
data[].send_groups[].`distributor_order_no`	`string \| null`
data[].`lines`required	`object[]`
data[].lines[].`line_no`required	`integer`
data[].lines[].`sku`required	`string`
data[].lines[].`title`required	`string`
data[].lines[].`quantity`required	`integer`
data[].lines[].`shipped_quantity`	`integer`
data[].lines[].`received_quantity`	`integer`
data[].lines[].`order_id`	`string \| null`
data[].lines[].`order_line_no`	`integer \| null`
data[].lines[].`unit_cost_cents`	`integer \| null`	Only for a key with `catalog:cost:read`.
data[].`quoted`	`object`	Only for a key with `catalog:cost:read`.
data[].quoted.`subtotal_cents`	`integer \| null`
data[].quoted.`shipping_cents`	`integer \| null`
data[].quoted.`tax_cents`	`integer \| null`
data[].quoted.`total_cents`	`integer \| null`
data[].`created_at`	`string (date-time) \| null`
data[].`ready_at`	`string (date-time) \| null`
data[].`sent_at`	`string (date-time) \| null`
data[].`confirmed_at`	`string (date-time) \| null`
data[].`shipped_at`	`string (date-time) \| null`
data[].`received_at`	`string (date-time) \| null`
data[].`cancelled_at`	`string (date-time) \| null`
data[].`cancel_reason`	`string \| null`
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/distributor-orders" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Make drafts from order lines

POST/distributor-orders/drafts

Scoped private key (rm_prv_), from a server

distributor_orders:write

{ lines: [{ order_id, line_no, quantity?, offer_id?, ship_to? }] }, up to 100. Rollmark plans what is not given (the quantity still to order, the best offer, where it is delivered under the store's drop-ship settings) and makes one draft per distributor and place. Lines that cannot be planned come back in skipped. Nothing is sent: a draft costs nothing and staff review and send it in Rollmark. 201 when a draft was made, else 200. Needs the distributor_orders:write permission.

Parameters

Name	In	Type	Description
`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
`lines`required	`object[]`	1 to 100 items.
lines[].`order_id`required	`string`
lines[].`line_no`required	`integer`
lines[].`quantity`	`integer`	At least 1.
lines[].`offer_id`	`string`
lines[].`ship_to`	`"shop" \| "customer_ffl" \| "customer_address"`

Responses

200Nothing was made (every line was skipped).

Field	Type	Description
`data`required	`object[]`
data[].`id`required	`string`
data[].`po_number`required	`string`
data[].`distributor`required	`string`	The distributor id (`RSR`, `Lipseys`, `Davidsons`, `SportsSouth`, `Zanders`).
data[].`status`required	`"draft" \| "ready" \| "sent" \| "confirmed" \| "partially_shipped" \| "shipped" \| "received" \| "cancelled" \| "failed"`
data[].`method`required	`"api" \| "manual"`	How staff will place it.
data[].`ship_to`required	`"shop" \| "customer_ffl" \| "customer_address"`
data[].`purpose`	`"stock" \| "customer"`
data[].`distributor_order_no`	`string \| null`	The distributor's own order or confirmation number
data[].`tracking`	`string \| null`
data[].`client_order_ids`	`string[]`
data[].`send_groups`	`object[]`	One entry per customer when a direct-ship PO was sent as several distributor orders.
data[].send_groups[].`order_id`	`string`
data[].send_groups[].`sent_po`	`string`
data[].send_groups[].`status`	`string`
data[].send_groups[].`distributor_order_no`	`string \| null`
data[].`lines`required	`object[]`
data[].lines[].`line_no`required	`integer`
data[].lines[].`sku`required	`string`
data[].lines[].`title`required	`string`
data[].lines[].`quantity`required	`integer`
data[].lines[].`shipped_quantity`	`integer`
data[].lines[].`received_quantity`	`integer`
data[].lines[].`order_id`	`string \| null`
data[].lines[].`order_line_no`	`integer \| null`
data[].lines[].`unit_cost_cents`	`integer \| null`	Only for a key with `catalog:cost:read`.
data[].`quoted`	`object`	Only for a key with `catalog:cost:read`.
data[].quoted.`subtotal_cents`	`integer \| null`
data[].quoted.`shipping_cents`	`integer \| null`
data[].quoted.`tax_cents`	`integer \| null`
data[].quoted.`total_cents`	`integer \| null`
data[].`created_at`	`string (date-time) \| null`
data[].`ready_at`	`string (date-time) \| null`
data[].`sent_at`	`string (date-time) \| null`
data[].`confirmed_at`	`string (date-time) \| null`
data[].`shipped_at`	`string (date-time) \| null`
data[].`received_at`	`string (date-time) \| null`
data[].`cancelled_at`	`string (date-time) \| null`
data[].`cancel_reason`	`string \| null`
data[].`updated_at`required	`string (date-time)`
`skipped`required	`object[]`	Lines that could not be planned, with why. The rest were made.
skipped[].`order_id`required	`string`
skipped[].`line_no`required	`integer`
skipped[].`reason`required	`"not_found" \| "order_not_live" \| "covered" \| "bad_offer" \| "no_offer" \| "ship_to_not_allowed" \| "quantity"`
skipped[].`message`required	`string`

201Drafts were made.

Errors400401403429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/distributor-orders/drafts" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lines":[{"order_id":"…","line_no":1}]}'

One distributor order

GET/distributor-orders/{id}

Scoped private key (rm_prv_), from a server

distributor_orders:read

Status, lines, the distributor's own order number, tracking and what has shipped and been received. Needs the distributor_orders:read permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200The order.

Headers: X-Request-Id, X-RateLimit-Remaining

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`po_number`required	`string`
data.`distributor`required	`string`	The distributor id (`RSR`, `Lipseys`, `Davidsons`, `SportsSouth`, `Zanders`).
data.`status`required	`"draft" \| "ready" \| "sent" \| "confirmed" \| "partially_shipped" \| "shipped" \| "received" \| "cancelled" \| "failed"`
data.`method`required	`"api" \| "manual"`	How staff will place it.
data.`ship_to`required	`"shop" \| "customer_ffl" \| "customer_address"`
data.`purpose`	`"stock" \| "customer"`
data.`distributor_order_no`	`string \| null`	The distributor's own order or confirmation number
data.`tracking`	`string \| null`
data.`client_order_ids`	`string[]`
data.`send_groups`	`object[]`	One entry per customer when a direct-ship PO was sent as several distributor orders.
data.send_groups[].`order_id`	`string`
data.send_groups[].`sent_po`	`string`
data.send_groups[].`status`	`string`
data.send_groups[].`distributor_order_no`	`string \| null`
data.`lines`required	`object[]`
data.lines[].`line_no`required	`integer`
data.lines[].`sku`required	`string`
data.lines[].`title`required	`string`
data.lines[].`quantity`required	`integer`
data.lines[].`shipped_quantity`	`integer`
data.lines[].`received_quantity`	`integer`
data.lines[].`order_id`	`string \| null`
data.lines[].`order_line_no`	`integer \| null`
data.lines[].`unit_cost_cents`	`integer \| null`	Only for a key with `catalog:cost:read`.
data.`quoted`	`object`	Only for a key with `catalog:cost:read`.
data.quoted.`subtotal_cents`	`integer \| null`
data.quoted.`shipping_cents`	`integer \| null`
data.quoted.`tax_cents`	`integer \| null`
data.quoted.`total_cents`	`integer \| null`
data.`created_at`	`string (date-time) \| null`
data.`ready_at`	`string (date-time) \| null`
data.`sent_at`	`string (date-time) \| null`
data.`confirmed_at`	`string (date-time) \| null`
data.`shipped_at`	`string (date-time) \| null`
data.`received_at`	`string (date-time) \| null`
data.`cancelled_at`	`string (date-time) \| null`
data.`cancel_reason`	`string \| null`
data.`updated_at`required	`string (date-time)`

Errors401403404429503in the error envelope.

Example

Shell
curl "https://app.getrollmark.com/api/v1/distributor-orders/<id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Delete a draft

DELETE/distributor-orders/{id}

Scoped private key (rm_prv_), from a server

distributor_orders:write

A draft that was never marked ready. Anything else is 409 not_a_draft. Needs the distributor_orders:write permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`
`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

200Deleted.

Headers: X-Request-Id, X-RateLimit-Remaining

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

Errors401403404409429503in the error envelope.

Example

Shell
curl -X DELETE "https://app.getrollmark.com/api/v1/distributor-orders/<id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Add an order line to a draft

POST/distributor-orders/{id}/lines

Scoped private key (rm_prv_), from a server

distributor_orders:write

{ order_id, order_line_no, quantity?, offer_id? }. Only a draft; any other status is 409 not_a_draft. The offer defaults to the best one from the draft's distributor. Needs the distributor_orders:write permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`
`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
`order_id`required	`string`
`order_line_no`required	`integer`
`quantity`	`integer`	At least 1.
`offer_id`	`string`

Responses

201The draft.

Headers: X-Request-Id, X-RateLimit-Remaining

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`po_number`required	`string`
data.`distributor`required	`string`	The distributor id (`RSR`, `Lipseys`, `Davidsons`, `SportsSouth`, `Zanders`).
data.`status`required	`"draft" \| "ready" \| "sent" \| "confirmed" \| "partially_shipped" \| "shipped" \| "received" \| "cancelled" \| "failed"`
data.`method`required	`"api" \| "manual"`	How staff will place it.
data.`ship_to`required	`"shop" \| "customer_ffl" \| "customer_address"`
data.`purpose`	`"stock" \| "customer"`
data.`distributor_order_no`	`string \| null`	The distributor's own order or confirmation number
data.`tracking`	`string \| null`
data.`client_order_ids`	`string[]`
data.`send_groups`	`object[]`	One entry per customer when a direct-ship PO was sent as several distributor orders.
data.send_groups[].`order_id`	`string`
data.send_groups[].`sent_po`	`string`
data.send_groups[].`status`	`string`
data.send_groups[].`distributor_order_no`	`string \| null`
data.`lines`required	`object[]`
data.lines[].`line_no`required	`integer`
data.lines[].`sku`required	`string`
data.lines[].`title`required	`string`
data.lines[].`quantity`required	`integer`
data.lines[].`shipped_quantity`	`integer`
data.lines[].`received_quantity`	`integer`
data.lines[].`order_id`	`string \| null`
data.lines[].`order_line_no`	`integer \| null`
data.lines[].`unit_cost_cents`	`integer \| null`	Only for a key with `catalog:cost:read`.
data.`quoted`	`object`	Only for a key with `catalog:cost:read`.
data.quoted.`subtotal_cents`	`integer \| null`
data.quoted.`shipping_cents`	`integer \| null`
data.quoted.`tax_cents`	`integer \| null`
data.quoted.`total_cents`	`integer \| null`
data.`created_at`	`string (date-time) \| null`
data.`ready_at`	`string (date-time) \| null`
data.`sent_at`	`string (date-time) \| null`
data.`confirmed_at`	`string (date-time) \| null`
data.`shipped_at`	`string (date-time) \| null`
data.`received_at`	`string (date-time) \| null`
data.`cancelled_at`	`string (date-time) \| null`
data.`cancel_reason`	`string \| null`
data.`updated_at`required	`string (date-time)`

Errors400401403404409429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/distributor-orders/<id>/lines" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"…","order_line_no":1}'

Remove a line from a draft

DELETE/distributor-orders/{id}/lines/{line_no}

Scoped private key (rm_prv_), from a server

distributor_orders:write

Only a draft. Needs the distributor_orders:write permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`
`line_no`required	path	`integer`	At least 1.
`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

200The draft.

Headers: X-Request-Id, X-RateLimit-Remaining

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`po_number`required	`string`
data.`distributor`required	`string`	The distributor id (`RSR`, `Lipseys`, `Davidsons`, `SportsSouth`, `Zanders`).
data.`status`required	`"draft" \| "ready" \| "sent" \| "confirmed" \| "partially_shipped" \| "shipped" \| "received" \| "cancelled" \| "failed"`
data.`method`required	`"api" \| "manual"`	How staff will place it.
data.`ship_to`required	`"shop" \| "customer_ffl" \| "customer_address"`
data.`purpose`	`"stock" \| "customer"`
data.`distributor_order_no`	`string \| null`	The distributor's own order or confirmation number
data.`tracking`	`string \| null`
data.`client_order_ids`	`string[]`
data.`send_groups`	`object[]`	One entry per customer when a direct-ship PO was sent as several distributor orders.
data.send_groups[].`order_id`	`string`
data.send_groups[].`sent_po`	`string`
data.send_groups[].`status`	`string`
data.send_groups[].`distributor_order_no`	`string \| null`
data.`lines`required	`object[]`
data.lines[].`line_no`required	`integer`
data.lines[].`sku`required	`string`
data.lines[].`title`required	`string`
data.lines[].`quantity`required	`integer`
data.lines[].`shipped_quantity`	`integer`
data.lines[].`received_quantity`	`integer`
data.lines[].`order_id`	`string \| null`
data.lines[].`order_line_no`	`integer \| null`
data.lines[].`unit_cost_cents`	`integer \| null`	Only for a key with `catalog:cost:read`.
data.`quoted`	`object`	Only for a key with `catalog:cost:read`.
data.quoted.`subtotal_cents`	`integer \| null`
data.quoted.`shipping_cents`	`integer \| null`
data.quoted.`tax_cents`	`integer \| null`
data.quoted.`total_cents`	`integer \| null`
data.`created_at`	`string (date-time) \| null`
data.`ready_at`	`string (date-time) \| null`
data.`sent_at`	`string (date-time) \| null`
data.`confirmed_at`	`string (date-time) \| null`
data.`shipped_at`	`string (date-time) \| null`
data.`received_at`	`string (date-time) \| null`
data.`cancelled_at`	`string (date-time) \| null`
data.`cancel_reason`	`string \| null`
data.`updated_at`required	`string (date-time)`

Errors401403404409429503in the error envelope.

Example

Shell
curl -X DELETE "https://app.getrollmark.com/api/v1/distributor-orders/<id>/lines/<line_no>" \
  -H "Authorization: Bearer $ROLLMARK_KEY"