API Overview

The KSS API provides programmatic access to product catalog, inventory, customer, invoice, and pricing data. All requests are made over HTTPS and return JSON responses.

OpenAPI JSON specification

Import an OpenAPI specification into Postman

There are two environments, each backed by its own isolated database and requiring a separate API key.

Production
api.kssdata.com
Live data. Use production API keys only. Data is updated continuously
Test
api.test.kssdata.com
Safe for development and integration testing. Data is updated every Sunday morning
⚠
API keys are environment-scoped. A production key will be rejected by the test environment and vice versa. Never use production keys in development or CI pipelines.

All endpoints are versioned under /api/v1. A full request to the products endpoint looks like:

https 
GET https://api.kssdata.com/api/{{version}}/products?States=CA&Statuses=1
x-api-key: your-api-key

Authentication

Every request must include your API key in the x-api-key request header. Requests without a valid key return 401 Unauthorized.

http header 
x-api-key: your-api-key

Each key belongs to a KSS Live user. A key is accepted only while the key is active, it was issued for this environment, and its user is active. What the key can do is covered under Authorization.

Authorization

What an API key can access is determined by the permissions of its user's KSS Live role, the same as in KSS Live. Changes to the user's role or account access apply to the key automatically; no new key is needed.

Permissions

Endpoints that need a permission are marked with a Requires badge. Some endpoints also need a permission for specific actions or filters, noted in the endpoint description. When the key's user lacks a required permission, the API returns 403 Forbidden and names the missing permission in RequiredPermission.

Permission Allows
CanViewInventory
Read inventory and batch inventory.
CanViewPurchaseOrders
Read purchase orders, purchase transactions and vendors.
CanApplyPayments
Request payment applications, and include inactive suppliers when listing payment types.
CanEditOrderTerms
Read supplier credit terms and change the credit terms on an order.
CanViewInactiveSuppliers
Include inactive suppliers when listing suppliers.
CanViewInactiveCustomers
Filter customers by account statuses other than Active.
CanEditUsers
Include inactive users when listing users.
Data Access

A user may be restricted to specific customers or specific suppliers. A restricted key only sees data for those customers or suppliers, and every key only sees data in its user's states. Requests outside that access are filtered out of the results or return 403 without a permission name.

i
Check your key's access. GET /api/v1/me returns the key's role, its full list of permissions and restrictions, and the customers, suppliers and states it can access.

Idempotency

For POST and PATCH requests, you may send an Idempotency-Key request header to make retries safe after a timeout or lost response.

Use a unique key for each logical operation, such as a UUID generated by your client. If the same API key sends the same idempotency key with the same method, path, query, and body, the API returns the original response instead of running the operation again.

Do not reuse a key for a different operation. Reusing a key with a different request returns 409 IDEMPOTENCY_KEY_REUSED. A retry while the original request is still processing returns 409 IDEMPOTENCY_KEY_IN_PROGRESS. If the original request never finished, an exact retry is processed again once 30 minutes have passed since it started.

Keys and their stored responses are kept for at least 7 days after first use. After that, a request with the same key is processed as a new request.

request headers 
POST /api/{{version}}/purchases
x-api-key: your-api-key
Idempotency-Key: 9f30f7f5-7e08-4f6a-a60c-8f7d11e9c702
↻
Exact retries replay the stored response. Replayed responses include Idempotency-Replayed: true. Keep your own idempotency keys long enough to cover your retry window.

Rate Limiting

Rate limits are enforced per API key. Each key has a configurable maximum requests per hour. When the limit is reached, the API returns 429 Too Many Requests.

Every response reports your current standing so you can pace requests before you are throttled:

RateLimit-Limit
The maximum number of requests allowed in the current window.
RateLimit-Remaining
Requests you have left before hitting the limit. 0 means the next request may be rejected.
RateLimit-Reset
Seconds until your remaining count recovers.
Retry-After
On a 429 only: seconds to wait before retrying.

When you receive a 429, wait the number of seconds given in Retry-After before sending another request rather than retrying immediately.

If you are building a sync process that requires high request volume, contact KSS to discuss your needs.

response headers 
RateLimit-Limit: 1000
RateLimit-Remaining: 847
RateLimit-Reset: 2934
↻
Use pagination and filtering. Fetching only the data you need — by state, supplier, or customer — is the most effective way to reduce request volume.

Pagination

All list endpoints support pagination via Page and PageSize query parameters. The default page size is 50. The maximum page size is 500.

Paginated responses wrap results in a Data array alongside Page and PageSize fields. A HasNextPage boolean indicates whether more results exist beyond the current page.

example request 
GET /api/{{version}}/products?States=CA&Page=2&PageSize=100
json 
{
  "Data": [ ... ],
  "Page": 2,
  "PageSize": 100,
  "HasNextPage": true
}

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with an Error field describing the issue.

400 Bad Request
Missing or invalid parameter.
401 Unauthorized
Missing or invalid API key, or the key's user is inactive.
403 Forbidden
Your key's user lacks the required permission, or the resource is outside their data access.
404 Not Found
The endpoint does not exist.
429 Too Many Requests
Rate limit exceeded.
500 Server Error
Unexpected server error. Contact KSS support.
error response 
{
  "Error": "InvoiceIDs parameter is required"
}

A 403 caused by a missing permission names that permission:

403 response 
{
  "Error": "Not authorized",
  "RequiredPermission": "CanViewInventory"
}

Response Headers

Alongside the rate limit headers, every response includes the following.

Request tracing

Each response carries an X-Request-Id header uniquely identifying that request. Include this value when contacting KSS support so we can locate the exact request in our logs.

If you send your own X-Request-Id on a request, we echo it back unchanged (when it is a short alphanumeric token), letting you correlate a request across your systems and ours.

Conditional requests

Responses include an ETag validator. To avoid re-downloading data that has not changed, send the ETag from a previous response back on your next request using the If-None-Match header. If the data is unchanged, the API returns 304 Not Modified with an empty body; otherwise it returns the full response with a new ETag.

Responses are marked private and must not be shared between different API keys in a downstream cache.

conditional request 
GET /api/{{version}}/products?States=CA
x-api-key: your-api-key
If-None-Match: W/"a1b2c3d4e5f6..."

Endpoints

Allocations
GET
/allocations
Paginated

Returns product allocations filtered by customer, supplier, and state.

Callout:
A single Allocation ID can effect multiple customers. The Unique key is [Allocation, ProductID, CustomerID]
Parameters
Name Type Required Description
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "AllocationID": 85001,
      "ProductID": 30001,
      "CustomerID": 10001,
      "Units": 24,
      "AllocationTypeID": 0,
      "StartDate": "2025-01-01",
      "EndDate": "2025-03-31",
      "TimeUpdated": "2025-01-15T10:00:00.000Z"
    },
    {
      "AllocationID": 85002,
      "ProductID": 30002,
      "CustomerID": 10001,
      "Units": 48,
      "AllocationTypeID": 0,
      "StartDate": "2025-01-01",
      "EndDate": "2025-03-31",
      "TimeUpdated": "2025-01-15T10:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
AR Aging
GET
/arAging
Paginated

Returns accounts receivable aging records broken out by AR account and supplier.

Callout:
AR Aging is recalculated once per day at the end of the day
Parameters
Name Type Required Description
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "ARAccountID": 81001,
      "SupplierID": 20002,
      "OpenCredit": "-31.050000",
      "CurrentDue": "0.000000",
      "Due_1_30": "34635.280000",
      "Due_31_60": "0.000000",
      "Due_61_90": "0.000000",
      "Due_91": "0.000000",
      "CloseDate": "2026-01-25T07:00:00.000Z",
      "TotalBalanceOutstanding": "34635.280000",
      "CurrentInvoices": [],
      "Invoices_1_30": [
        {
          "InvoiceID": 60003,
          "InvoiceNum": "X-00001",
          "OpenBalance": "11545.090000"
        },
        {
          "InvoiceID": 60004,
          "InvoiceNum": "X-00002",
          "OpenBalance": "11545.090000"
        },
        {
          "InvoiceID": 60005,
          "InvoiceNum": "X-00003",
          "OpenBalance": "11545.100000"
        }
      ],
      "Invoices_31_60": [],
      "Invoices_61_90": [],
      "Invoices_91": [],
      "TimeUpdated": "2024-09-23T19:05:39.984Z",
      "CreditInvoices": []
    }
  ],
  "Page": 1,
  "PageSize": 50
}
Pricing
GET
/customerPricing
Paginated

Returns per-customer product pricing including any applicable promotions and discounts for a given effective date.

Parameters
Name Type Required Description
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
EffectiveDate
query
 date optional
ISO 8601 date string to evaluate promotion validity against. Defaults to the current date.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "ProductID": 30001,
      "CustomerID": 10001,
      "FullPrice": "18.00",
      "UnitPrice": "15.50",
      "Discount": "2.50",
      "PromotionID": 83001,
      "StartDate": "2025-01-01",
      "EndDate": "2025-03-31",
      "TimeUpdated": "2025-01-10T08:00:00.000Z"
    },
    {
      "ProductID": 30002,
      "CustomerID": 10001,
      "FullPrice": "18.00",
      "UnitPrice": "18.00",
      "Discount": "0.00",
      "PromotionID": null,
      "StartDate": null,
      "EndDate": null,
      "TimeUpdated": "2025-01-10T08:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
Customers
GET
/customers
Paginated

Returns a list of customers filtered by state, customer ID, and account status.

Callout:
OnHold is a warning only. It does not prevent an order from being placed for the customer, but KSS may decline to deliver the order at its discretion.
Parameters
Name Type Required Description
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
AccountStatuses
query
 string optional
Comma-separated list of account statuses to filter by. Defaults to Active. Only keys with the CanViewInactiveCustomers permission may request other statuses; for other keys the value is ignored and only Active customers are returned.
ARAccountIDs
query
 string optional
Comma-separated list of AR account IDs to filter by. Returns the customers billed to those AR accounts.
OnHold
query
 string optional
Filter by on hold status. Pass "true" to return only customers on hold, "false" to exclude them. When omitted, on hold status is not filtered. On hold is a warning only: it does not prevent an order from being placed, but KSS may decline to deliver the order at its discretion.
true true false false
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "CustomerID": 10001,
      "CustomerName": "Kettles Secret Stash",
      "CustomerNameAlt": "Kettles",
      "ChainName": "Kettles Chain",
      "LicenseNum": "C10-0000001-LIC",
      "Address": "123 Main St, Los Angeles, CA 90001",
      "LocationID": 40002,
      "State": "CA",
      "DeliveryDays": "1",
      "AccountStatus": "Active",
      "DeliveryDates": [
        "2026-01-05",
        "2026-01-12",
        "2026-01-19",
        "2026-01-26"
      ],
      "DeliveryMinimum": 500,
      "OnHold": false,
      "DefaultCreditTermID": 5,
      "CollectionAgentFullName": "Alex Rivera",
      "CollectionAgentEmail": "alex.rivera@example.com",
      "ARAccountID": 81002,
      "ARAccountName": "Kettles Secret Stash",
      "TimeUpdated": "2025-01-15T10:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/customers/creditTerms
Paginated

Returns the credit terms negotiated between each customer and supplier pair.

Callout:
Keys restricted to specific customers only see rows for those customers. Keys restricted to specific suppliers only see rows for those suppliers.
Parameters
Name Type Required Description
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "CustomerID": 10001,
      "SupplierID": 20001,
      "TermID": 80001,
      "Term": "Net 30",
      "TimeUpdated": "2025-01-15T10:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/customers/{customerID}

Returns a single customer by ID.

Callout:
OnHold is a warning only. It does not prevent an order from being placed for the customer, but KSS may decline to deliver the order at its discretion.
Parameters
Name Type Required Description
customerID
path
 number required
The ID of the customer to retrieve.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
404
The requested resource was not found.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "CustomerID": 10001,
      "CustomerName": "Kettles Secret Stash",
      "CustomerNameAlt": "Kettles",
      "ChainName": "Kettles Chain",
      "LicenseNum": "C10-0000001-LIC",
      "Address": "123 Main St, Los Angeles, CA 90001",
      "LocationID": 40002,
      "State": "CA",
      "DeliveryDays": "1",
      "AccountStatus": "Active",
      "DeliveryDates": [
        "2026-01-05",
        "2026-01-12",
        "2026-01-19",
        "2026-01-26"
      ],
      "DeliveryMinimum": 500,
      "OnHold": false,
      "DefaultCreditTermID": 5,
      "CollectionAgentFullName": "Alex Rivera",
      "CollectionAgentEmail": "alex.rivera@example.com",
      "ARAccountID": 81002,
      "ARAccountName": "Kettles Secret Stash",
      "TimeUpdated": "2025-01-15T10:00:00.000Z"
    }
  ]
}
GET
/deliveryDays
Paginated

Returns delivery day schedules for active customers.

Callout:
'DeliveryDays' is the day of the week the customer is delivered on. 1 = Monday, 7 = Sunday
Parameters
Name Type Required Description
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "CustomerID": 10001,
      "DeliveryDays": "3",
      "DeliveryDates": [
        "2026-02-04",
        "2026-02-11",
        "2026-02-18",
        "2026-02-25"
      ]
    }
  ],
  "Page": 1,
  "PageSize": 50
}
Inventory
GET
/inventory
Requires CanViewInventory Paginated

Returns warehouse inventory records filtered by supplier, product, location, and state. AvailableUnits = OnFloorInventory - PreSales - Allocations

Callout:
Use Inventory + Received for the full total of what is in the warehouse. The NotAuthorized field signifies that all of this product is reserved for specific accounts. Refer to the Allocations endpoint for details
Parameters
Name Type Required Description
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
ProductIDs
query
 string optional
Comma-separated list of product IDs to filter by.
LocationIDs
query
 string optional
Comma-separated list of location IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Field Definitions
Field Description
Inventory
Verified received purchases minus verified sales. This can be negative if received purchases are not yet verified. Purchases and Sales are verified at the end of the day.
Loaded
Total inventory that has been loaded onto trucks for delivery.
Picked
Total inventory that has been picked, but not yet Loaded.
Delivered
Total inventory that has been delivered, but is still on Load Sheets in the Loaded Status.
Unsellable
Total inventory in the warehouse that is not flagged as sellable.
OnFloorInventory
Total sellable inventory in the warehouse. Inventory + Received - (Loaded + Picked + Pending Sales + Delivered + Unsellable).
PreSales
Total inventory that is on an invoice for delivery and not yet picked or loaded.
PendingSales
Inventory that has been delivered but not yet verified
Allocated
Inventory that has been specifically "set aside" using allocations, and is therefore not universally available.
AvailableUnits
Total inventory available for any retailer to buy: OnFloorInventory - (Pre-Sales + Allocated).
Received
Total inventory that has been received and not yet put in on floor or unsellable. This value is not included in the Inventory field.
NotAuthorized
If true this product is not generally available. Only specifically authorized accounts can purchase this product.
PurchaseTransID
The Purchase Transaction ID of the current FIFO layer that is being sold. The inventory values can be the sum of multiple purchase transactions. Not just the one that is being sold.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "LocationID": 40001,
      "ProductID": 30006,
      "OnFloorInventory": "1239.00",
      "PreSales": "110.00",
      "Allocated": "0.00",
      "NotAuthorized": false,
      "AvailableUnits": 1129,
      "PurchaseTransID": 71002,
      "DOI": "5.60",
      "AvgDailySales90d": "201.49",
      "Inventory": "1239.00",
      "Received": "1500.00",
      "Loaded": "0.00",
      "Picked": "0.00",
      "Delivered": "261.00",
      "Unsellable": "0.00",
      "TimeUpdated": "2026-02-24T17:06:10.610Z"
    },
    {
      "LocationID": 40001,
      "ProductID": 30007,
      "OnFloorInventory": "1939.00",
      "PreSales": "180.00",
      "Allocated": "0.00",
      "NotAuthorized": false,
      "AvailableUnits": 1759,
      "PurchaseTransID": 71003,
      "DOI": "3.77",
      "AvgDailySales90d": "466.83",
      "Inventory": "1939.00",
      "Received": "2100.00",
      "Loaded": "0.00",
      "Picked": "0.00",
      "Delivered": "161.00",
      "Unsellable": "0.00",
      "TimeUpdated": "2026-02-24T17:06:10.610Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/inventory/batches
Requires CanViewInventory Paginated

Returns warehouse inventory broken out by batch, including batch codes, potency, and compliance dates. Filtered by supplier, product, location, state, and batch code.

Parameters
Name Type Required Description
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
ProductIDs
query
 string optional
Comma-separated list of product IDs to filter by.
LocationIDs
query
 string optional
Comma-separated list of location IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
BatchCodes
query
 string optional
Comma-separated list of batch codes to filter by. Matches exactly.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "LocationID": 40001,
      "ProductID": 30006,
      "SupplierID": 20001,
      "State": "CA",
      "InventoryUnits": 1239,
      "PurchaseTransID": 71002,
      "ExpirationDate": "2026-12-31",
      "COAURL": "https://cdn.example.com/ExampleBrand/COA/example-coa-1.pdf",
      "BatchCode": "EXAMPLE-240115-A",
      "Vintage": null,
      "UID": "1A4060300012345000000001",
      "Laboratory": "SC Labs",
      "BestByDate": "2026-11-30",
      "HarvestDate": null,
      "ManufactureDate": "2024-01-15",
      "PackDate": "2024-01-16",
      "COAExpirationDate": "2026-01-15",
      "PotencyType": "PerServing",
      "THCPotency": "5.00",
      "CBDPotency": "0.00",
      "TotalCannabinoids": "5.00",
      "LabelTHCPotency": "5.00",
      "LabelCBDPotency": "0.00",
      "LabelTotalCannabinoids": "5.00",
      "TimeCreated": "2024-01-16T08:00:00.000Z",
      "TimeUpdated": "2026-02-24T17:06:10.610Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/availableInventory
Paginated

Returns a simplified view of orderable warehouse inventory, filtered by customer, supplier, product, location, and state. Instead of exact unit counts, each product reports whether it is in stock and which stock level bucket it falls into, measured in cases. Retailers only see inventory at the warehouse locations that serve their accounts.

Callout:
Stock levels exclude units already sold or reserved for specific accounts. Products reserved entirely for specific accounts are still listed; refer to the Allocations endpoint for details.
Parameters
Name Type Required Description
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
ProductIDs
query
 string optional
Comma-separated list of product IDs to filter by.
LocationIDs
query
 string optional
Comma-separated list of location IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Field Definitions
Field Description
InStock
True when enough stock is available to place the smallest allowed order: one full case for products sold by the case only, otherwise the product's minimum order quantity (at least 1 unit).
InventoryBucket
The available stock level. One of "50+ Cases", "< 50 Cases", "< 25 Cases", "< 10 Cases", "< 5 Cases", "< 1 Case", or "Out of Stock".
TimeUpdated
When this inventory record was last refreshed.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "LocationID": 40001,
      "ProductID": 30006,
      "InStock": true,
      "InventoryBucket": "50+ Cases",
      "TimeUpdated": "2026-02-24T17:06:10.610Z"
    },
    {
      "LocationID": 40001,
      "ProductID": 30007,
      "InStock": false,
      "InventoryBucket": "Out of Stock",
      "TimeUpdated": "2026-02-24T17:06:10.610Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/retailerInventory
Paginated

Returns retailer-level inventory records filtered by customer, supplier, product, and state.

Parameters
Name Type Required Description
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
ProductIDs
query
 string optional
Comma-separated list of product IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "ID": 95001,
      "ProductID": 30001,
      "CustomerID": 10001,
      "LastInventoryDate": "2025-05-20T06:00:00.000Z",
      "Inventory": "20.00",
      "DailySales": "0.03",
      "TimeUpdated": "2025-06-02T21:31:05.941Z"
    },
    {
      "ID": 95002,
      "ProductID": 30002,
      "CustomerID": 10001,
      "LastInventoryDate": "1999-12-31T07:00:00.000Z",
      "Inventory": "0.00",
      "DailySales": "0.03",
      "TimeUpdated": "2025-06-17T15:46:14.397Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
Invoices
GET
/invoices
Paginated

Returns invoices filtered by customer, status, date range, and state. RevisionStatus is Submitted, Importing, or Accepted while a requested update is being applied to the invoice, and null otherwise. When it is set, the invoice values returned here may not reflect the update yet; poll again later. RevisionUpdatedAt is when the update was last changed.

Callout:
Defaults to returning only New (1) status invoices if the 'Statuses' parameter is not included
Parameters
Name Type Required Description
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
InvoiceIDs
query
 string optional
Comma-separated list of invoice IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Statuses
query
 string optional
Comma-separated list of invoice status IDs. Defaults to New (1).
StartDate
query
 date optional
ISO 8601 date string. Returns invoices on or after this date.
EndDate
query
 date optional
ISO 8601 date string. Returns invoices on or before this date.
UpdatedSince
query
 date-time optional
ISO 8601 date-time with a timezone offset, such as 2026-11-01T00:00:00Z. Returns invoices whose InvoiceLastUpdated is at or after this time; combines with the other filters. Pass back the latest InvoiceLastUpdated you received to poll for changes. URL-encode a + offset as %2B. Values without an offset return 400.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Field Definitions
Field Description
Status
Numeric invoice status: 1 New, 2 Locked for Routing, 3 Loaded, 4 Returned, 5 Balanced, 7 Verified. Filter on it with Statuses.
RevisionStatus
Progress of an update being applied to the invoice: Submitted (the update has been submitted and is queued), Importing (the update is being processed), Accepted (the update has been accepted and is waiting to sync to the invoice). Null when no update is in progress.
MetrcTransferManifestID
The Metrc transfer manifest number for the shipment that delivers this invoice. When the invoice has been re-manifested, the most recent manifest is returned. Null until a manifest is created.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "InvoiceID": 60001,
      "CustomerID": 10001,
      "CustomerName": "Acme Beverages",
      "InvoiceNum": "INV-2025-0001",
      "OpenDebit": "0.320000",
      "OpenCredit": "0.000000",
      "PONum": null,
      "PODate": null,
      "TermID": 80001,
      "PDFURL": "https://example.com/api?APIKeyID=94001",
      "Memo": "This is a memo",
      "Date": "2026-02-10T07:00:00.000Z",
      "DueDate": "2026-03-11T06:00:00.000Z",
      "Status": 1,
      "InvoiceTotal": "1536.000000",
      "SubmittedByUserID": 93001,
      "SubmittedByUserName": "John Doe",
      "SubmittedByUserEmail": "john.doe@example.com",
      "BuiltByUserID": 93001,
      "BuiltByUserName": "Jane Smith",
      "BuiltByUserEmail": "jane.smith@example.com",
      "InvoiceTimeCreated": "2026-01-27T13:40:00.000Z",
      "InvoiceLastUpdated": "2026-01-27T13:40:00.000Z",
      "ARNote": null,
      "MetrcTransferManifestID": "0011730640",
      "TotalNumUnits": "72",
      "TotalCases": "6.00",
      "TotalFullPrice": "1680.000000",
      "TotalExtPrice": "1536.000000",
      "TotalDiscount": "144.000000",
      "OpenBalance": "1536.000000",
      "RevisionStatus": null,
      "RevisionUpdatedAt": null
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/invoices/{invoiceID}

Returns a single invoice by ID. RevisionStatus is Submitted, Importing, or Accepted while a requested update is being applied to the invoice, and null otherwise. When it is set, the invoice values returned here may not reflect the update yet; poll again later. RevisionUpdatedAt is when the update was last changed.

Parameters
Name Type Required Description
invoiceID
path
 number required
The ID of the invoice to retrieve.
Field Definitions
Field Description
Status
Numeric invoice status: 1 New, 2 Locked for Routing, 3 Loaded, 4 Returned, 5 Balanced, 7 Verified.
RevisionStatus
Progress of an update being applied to the invoice: Submitted (the update has been submitted and is queued), Importing (the update is being processed), Accepted (the update has been accepted and is waiting to sync to the invoice). Null when no update is in progress.
MetrcTransferManifestID
The Metrc transfer manifest number for the shipment that delivers this invoice. When the invoice has been re-manifested, the most recent manifest is returned. Null until a manifest is created.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
404
The requested resource was not found.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "InvoiceID": 60001,
      "CustomerID": 10001,
      "CustomerName": "Acme Beverages",
      "InvoiceNum": "INV-2025-0001",
      "OpenDebit": "0.320000",
      "OpenCredit": "0.000000",
      "PONum": null,
      "PODate": null,
      "TermID": 80001,
      "PDFURL": "https://example.com/api?APIKeyID=94001",
      "Memo": "This is a memo",
      "Date": "2026-02-10T07:00:00.000Z",
      "DueDate": "2026-03-11T06:00:00.000Z",
      "Status": 1,
      "InvoiceTotal": "1536.000000",
      "SubmittedByUserID": 93001,
      "SubmittedByUserName": "John Doe",
      "SubmittedByUserEmail": "john.doe@example.com",
      "BuiltByUserID": 93001,
      "BuiltByUserName": "Jane Smith",
      "BuiltByUserEmail": "jane.smith@example.com",
      "InvoiceTimeCreated": "2026-01-27T13:40:00.000Z",
      "InvoiceLastUpdated": "2026-01-27T13:40:00.000Z",
      "MetrcTransferManifestID": "0011730640",
      "TotalNumUnits": "72",
      "TotalCases": "6.00",
      "TotalFullPrice": "1680.000000",
      "TotalExtPrice": "1536.000000",
      "TotalDiscount": "144.000000",
      "OpenBalance": "1536.000000",
      "RevisionStatus": null,
      "RevisionUpdatedAt": null
    }
  ]
}
GET
/invoiceTransactions
Paginated

Returns line item transactions for the specified invoices. InvoiceIDs is required. Reason and ReasonID identify the adjustment reason recorded against a line item, and are null on lines with no reason. RevisionStatus is set on every line of an invoice with an update in progress (Submitted, Importing, or Accepted) and null otherwise. When it is set, the lines returned here reflect the invoice before the update and may change once it is applied.

Parameters
Name Type Required Description
InvoiceIDs
query
 string required
Comma-separated list of invoice IDs to fetch transactions for. Returns 400 if not provided.
Statuses
query
 string optional
Comma-separated list of invoice status IDs. If provided and does not include Verified (7), verified invoices are excluded from results.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Field Definitions
Field Description
RevisionStatus
Progress of an update being applied to the line's invoice: Submitted (the update has been submitted and is queued), Importing (the update is being processed), Accepted (the update has been accepted and is waiting to sync to the invoice). Null when no update is in progress.
PromotionOverridden
True when the line item's price was manually overridden from its default price.
PurchaseTransID
The purchase transaction ID used to fill the line item. Null when the line item has not been filled from a purchase yet.
MetrcPackageID
The Metrc package tag for the inventory this line shipped from. Null when not recorded.
MetrcItemName
The item name registered for this product in Metrc. Null when no Metrc mapping exists.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "InvoiceTransID": 61001,
      "InvoiceID": 60001,
      "CustomerID": 10001,
      "ProductID": 30004,
      "ProductName": "Example Bites Milk Chocolate Blueberries",
      "Cases": "1.00",
      "NumUnits": 20,
      "Ordered": 20,
      "BackOrder": 0,
      "FullPrice": "11.000000",
      "Discount": "2.250000",
      "UnitPrice": "8.750000",
      "ExtPrice": "175.000000",
      "TimeUpdated": "2024-09-23T19:05:39.984Z",
      "SupplierID": 20001,
      "PromotionID": 83002,
      "ReasonID": null,
      "Reason": null,
      "PromotionOverridden": true,
      "PurchaseTransID": 71001,
      "MetrcPackageID": "1A4060300003B01000012345",
      "BatchCode": "BATCH-2025-01",
      "COA_URL": "https://cdn.example.com/coa/batch-2025-001.pdf",
      "MetrcItemName": "Example Bites Milk Chocolate Blueberries 20pk",
      "RevisionStatus": null,
      "RevisionUpdatedAt": null
    },
    {
      "InvoiceTransID": 61002,
      "InvoiceID": 60001,
      "ProductID": 30005,
      "ProductName": "Example Gummies Wild Cherry",
      "Cases": "1.00",
      "NumUnits": 20,
      "Ordered": 20,
      "BackOrder": 0,
      "FullPrice": "11.000000",
      "Discount": "0.000000",
      "UnitPrice": "11.000000",
      "ExtPrice": "220.000000",
      "TimeUpdated": "2024-09-23T19:05:39.984Z",
      "SupplierID": 20001,
      "PromotionID": null,
      "ReasonID": 4,
      "Reason": "Damaged",
      "PromotionOverridden": false,
      "PurchaseTransID": 71002,
      "MetrcPackageID": null,
      "BatchCode": "BATCH-2025-002",
      "COA_URL": null,
      "MetrcItemName": null,
      "RevisionStatus": null,
      "RevisionUpdatedAt": null
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/invoiceTransactions/{invoiceID}
Paginated

Returns line item transactions for a single invoice by ID. Reason and ReasonID identify the adjustment reason recorded against a line item, and are null on lines with no reason. RevisionStatus is set on every line of an invoice with an update in progress (Submitted, Importing, or Accepted) and null otherwise. When it is set, the lines returned here reflect the invoice before the update and may change once it is applied.

Parameters
Name Type Required Description
invoiceID
path
 number required
The ID of the invoice to fetch transactions for.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Field Definitions
Field Description
RevisionStatus
Progress of an update being applied to the line's invoice: Submitted (the update has been submitted and is queued), Importing (the update is being processed), Accepted (the update has been accepted and is waiting to sync to the invoice). Null when no update is in progress.
PromotionOverridden
True when the line item's price was manually overridden from its default price.
PurchaseTransID
The purchase transaction ID used to fill the line item. Null when the line item has not been filled from a purchase yet.
MetrcPackageID
The Metrc package tag for the inventory this line shipped from. Null when not recorded.
MetrcItemName
The item name registered for this product in Metrc. Null when no Metrc mapping exists.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
404
The requested resource was not found.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "InvoiceTransID": 61001,
      "InvoiceID": 60001,
      "CustomerID": 10001,
      "ProductID": 30004,
      "ProductName": "Example Bites Milk Chocolate Blueberries",
      "Cases": "1.00",
      "NumUnits": 20,
      "Ordered": 20,
      "BackOrder": 0,
      "FullPrice": "11.000000",
      "Discount": "2.250000",
      "UnitPrice": "8.750000",
      "ExtPrice": "175.000000",
      "TimeUpdated": "2024-09-23T19:05:39.984Z",
      "SupplierID": 20001,
      "PromotionID": 83002,
      "ReasonID": null,
      "Reason": null,
      "PromotionOverridden": true,
      "PurchaseTransID": 71001,
      "MetrcPackageID": "1A4060300003B01000012345",
      "BatchCode": "BATCH-2025-01",
      "COA_URL": "https://cdn.example.com/coa/batch-2025-001.pdf",
      "MetrcItemName": "Example Bites Milk Chocolate Blueberries 20pk",
      "RevisionStatus": null,
      "RevisionUpdatedAt": null
    },
    {
      "InvoiceTransID": 61002,
      "InvoiceID": 60001,
      "ProductID": 30005,
      "ProductName": "Example Gummies Wild Cherry",
      "Cases": "1.00",
      "NumUnits": 20,
      "Ordered": 20,
      "BackOrder": 0,
      "FullPrice": "11.000000",
      "Discount": "0.000000",
      "UnitPrice": "11.000000",
      "ExtPrice": "220.000000",
      "TimeUpdated": "2024-09-23T19:05:39.984Z",
      "SupplierID": 20001,
      "PromotionID": null,
      "ReasonID": 4,
      "Reason": "Damaged",
      "PromotionOverridden": false,
      "PurchaseTransID": 71002,
      "MetrcPackageID": null,
      "BatchCode": "BATCH-2025-002",
      "COA_URL": null,
      "MetrcItemName": null,
      "RevisionStatus": null,
      "RevisionUpdatedAt": null
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/invoices/creditTerms
Paginated

Returns the catalog of credit terms (Net 30, Net 60, etc.) used on invoices.

Parameters
Name Type Required Description
TermIDs
query
 string optional
Comma-separated list of term IDs to filter by.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "TermID": 80001,
      "Term": "Net 30",
      "DaysOfCredit": 30,
      "AccountOnHold": false,
      "TimeUpdated": "2025-01-01T00:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/invoiceCOAs
Paginated

Returns certificate of analysis records for the specified invoices. InvoiceIDs is required.

Parameters
Name Type Required Description
InvoiceIDs
query
 string required
Comma-separated list of invoice IDs to fetch COAs for. Returns 400 if not provided.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "InvoiceID": 60001,
      "ProductID": 30001,
      "InvoiceTransID": 61001,
      "BatchCode": "BATCH-2025-001",
      "COA_URL": "https://cdn.example.com/coa/batch-2025-001.pdf",
      "TimeUpdated": "2025-01-10T14:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/invoiceCOAs/{invoiceID}
Paginated

Returns certificate of analysis records for a single invoice by ID.

Parameters
Name Type Required Description
invoiceID
path
 number required
The ID of the invoice to fetch COAs for.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
404
The requested resource was not found.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "InvoiceID": 60001,
      "ProductID": 30001,
      "InvoiceTransID": 61001,
      "BatchCode": "BATCH-2025-001",
      "COA_URL": "https://cdn.example.com/coa/batch-2025-001.pdf",
      "TimeUpdated": "2025-01-10T14:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
Locations
GET
/locations
Paginated

Returns warehouse and distribution locations filtered by state and location ID.

Parameters
Name Type Required Description
LocationIDs
query
 string optional
Comma-separated list of location IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "LocationID": 40001,
      "Location": "Alameda",
      "DBA": "Example Sales & Service",
      "Address": "100 Example Loop Rd",
      "Address2": null,
      "Address3": "N/A",
      "City": "Alameda",
      "State": "CA",
      "PostalCode": "94502",
      "TimeUpdated": "2024-09-23T19:05:39.984Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/locations/{locationID}

Returns a single location by ID.

Parameters
Name Type Required Description
locationID
path
 number required
The ID of the location to retrieve.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
404
The requested resource was not found.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "LocationID": 40001,
      "Location": "Alameda",
      "DBA": "Example Sales & Service",
      "Address": "100 Example Loop Rd",
      "Address2": null,
      "Address3": "N/A",
      "City": "Alameda",
      "State": "CA",
      "PostalCode": "94502",
      "TimeUpdated": "2024-09-23T19:05:39.984Z"
    }
  ]
}
API Key
GET
/me

Returns the role, permissions, restrictions, and scope of the API key making the request, plus its current rate-limit status. The key's access comes from the role and assignments of the user it belongs to, so changes to that user apply within a few minutes. The request itself counts toward the limit, and the response is never cached. Useful for checking what a key can do, and which suppliers, customers, and states it can act for, before debugging a 403; a 403 caused by a missing permission names that permission in RequiredPermission.

Field Definitions
Field Description
APIKeyID
The numeric identifier of the API key making the request.
Type
The name of the role the key's user holds. Null when the user has no active role, in which case the key has no permissions and is fully restricted.
Environment
The environment the key is issued for: Production, Test, or Development.
UserID
The numeric identifier of the user the key belongs to.
SupplierIDs
The suppliers the key can act for. Null means the key is not restricted to particular suppliers.
CustomerIDs
The customers the key can act for. Null means the key is not restricted to particular customers.
States
The states the key can access.
Permissions
The permissions the key's role grants. Endpoints that need a permission the key lacks return 403 with that permission in RequiredPermission.
Restrictions
How the key's access is narrowed. IsCustomerRestricted and IsSupplierRestricted mean the key only sees the customers or suppliers listed in CustomerIDs and SupplierIDs; IsCreditProductRestricted limits which credit products it can use.
RateLimit
The key's request allowance over a rolling 60-minute window. Null when rate-limit status is not available for the request.
RateLimit.Limit
The maximum number of requests the key may make in a rolling 60-minute window.
RateLimit.Remaining
The number of requests left in the current window, after counting this request.
RateLimit.ResetSeconds
The number of seconds until the oldest request counted in the window ages out and frees up an allowance.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": {
    "APIKeyID": 94001,
    "Type": "Supplier",
    "Environment": "Production",
    "UserID": 10042,
    "SupplierIDs": [
      20001,
      20002
    ],
    "CustomerIDs": null,
    "States": [
      "CA",
      "NJ"
    ],
    "Permissions": [
      "CanEditUsers",
      "CanSubmitPurchaseOrders",
      "CanViewInventory",
      "CanViewPurchaseOrders"
    ],
    "Restrictions": [
      "IsSupplierRestricted"
    ],
    "RateLimit": {
      "Limit": 1000,
      "Remaining": 962,
      "ResetSeconds": 2718
    }
  }
}
Promotions
GET
/menuPromotions
Paginated

Returns menu promotions filtered by supplier, state, and active date range.

Parameters
Name Type Required Description
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
StartDate
query
 date optional
ISO 8601 date string. Returns promotions whose end date is on or after this value.
EndDate
query
 date optional
ISO 8601 date string. Returns promotions whose start date is on or before this value.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "MenuPromotionID": 84001,
      "SupplierID": 20003,
      "SupplierName": "Example Supplier",
      "State": "CA",
      "Description": "Featured products for spring menus.",
      "StartDate": "2025-03-01",
      "EndDate": "2025-05-31",
      "TimeUpdated": "2025-02-15T10:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/promotionsProducts
Paginated

Returns promotion records with their associated products filtered by supplier and state.

Parameters
Name Type Required Description
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "PromotionID": 83001,
      "PromotionTypeID": 4,
      "States": [
        "CA"
      ],
      "PromotionName": "Spring Chocolate Deal",
      "ProductOverrideType": "none",
      "UnitPrice": 15.5,
      "StartDate": "2025-01-01",
      "EndDate": "2025-03-31",
      "AllProducts": false,
      "ProductIDs": [
        30001,
        30002,
        30003
      ],
      "TimeUpdated": "2024-12-20T10:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
Products
GET
/productCategories
Paginated

Returns all product categories ordered by sequence.

Parameters
Name Type Required Description
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "ProductCategoryID": 86001,
      "CategoryName": "Chocolate",
      "Sequence": 1,
      "TimeUpdated": "2025-01-01T00:00:00.000Z"
    },
    {
      "ProductCategoryID": 86002,
      "CategoryName": "Gummies",
      "Sequence": 2,
      "TimeUpdated": "2025-01-01T00:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/products
Paginated

Returns products filtered by supplier, state, product ID, and status.

Parameters
Name Type Required Description
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
ProductIDs
query
 string optional
Comma-separated list of product IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Statuses
query
 string optional
Comma-separated list of product status IDs. Defaults to Active (1). Ignored when ProductIDs is provided.
SupplierProductNumbers
query
 string optional
Comma-separated list of supplier product numbers to filter by. Matches exactly.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Field Definitions
Field Description
SellByCaseOnly
true when this product is sold only in full cases: each order line must be a whole multiple of WholesaleUnitsPerCase units. Order requests that break this are rejected with NOT_CASE_MULTIPLE, or adjusted to a full-case quantity when lenient handling is requested. Does not apply to lines priced as samples through a promotion. Null means there is no case-only rule.
MinOrderUnits
The minimum number of units an order line for this product must contain. 1 or null means there is no minimum. Order requests below it are rejected with BELOW_MIN_ORDER, or raised to the minimum when lenient handling is requested. Does not apply to lines priced as samples through a promotion. A product can have both a case-only rule and a minimum.
MetrcItemName
The item name registered for this product in Metrc. Null when no Metrc mapping exists.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "ProductID": 30001,
      "Supplier": "Example Supplier",
      "SupplierID": 20001,
      "ProductName": "Bar Dark Chocolate",
      "BrandFamily": "Example Bars",
      "ProductTypeName": "Edible - Chocolate",
      "UnitNetWeight": "50g",
      "WholesaleUnitsPerCase": 20,
      "SellByCaseOnly": false,
      "MinOrderUnits": 5,
      "Description": "Our classic Dark Chocolate bar is uniquely complex with flavors of black coffee and dark cherry. Using a 57% sustainably sourced dark chocolate infused with pure, clean cold water hash, this bar is sure to delight any true chocolate lover.Example Brand chocolates are crafted from sustainably sourced, premium cacao infused with pure, hand-crafted cold water hash. Since 2010, Example Brand's mission has been to change how the world views and uses cannabis. By applying art and science to ensure a delicious, consistent experience every time, we continue to deliver on that mission today.",
      "Ingredients": "Semisweet Chocolate (Unsweetened Chocolate, Sugar, Cocoa Butter, Sunflower Lecithin, Vanilla), Cannabis Extract.",
      "ThumbnailImageURL": "https://cdn.example.com/ExampleBrand/S3Images/example-thumbnail-1.png",
      "FullSizeImageURL": "https://cdn.example.com/ExampleBrand/S3Images/example-fullsize-1.png",
      "Potency": "100mg THC",
      "PotencyTHC": null,
      "Blend": "Hybrid",
      "KSSMenuCategory": "Edibles/Ingestibles",
      "KSSLiveCategoryID": 1,
      "StatusID": 1,
      "TimeUpdated": "2026-02-12T19:51:57.510Z",
      "State": "CA",
      "IsSample": false,
      "ProductGroupID": 3,
      "BrandStyle": "Example Bar",
      "PackageID": 97001,
      "PackageName": "20 Example Bar",
      "ProductTypeID": 96001,
      "StrainName": null,
      "StrainID": null,
      "Flavor": "dark",
      "BrandID": 98001,
      "BrandName": "Example Bars Base",
      "SupplierProductNumber": "EXAMPLE-BAR-DARK-50",
      "MetrcItemName": "Example Bar Dark Chocolate 100mg"
    },
    {
      "ProductID": 30002,
      "Supplier": "Example Supplier",
      "SupplierID": 20001,
      "ProductName": "Bar Milk Chocolate",
      "BrandFamily": "Example Bars",
      "ProductTypeName": "Edible - Chocolate",
      "UnitNetWeight": "50g",
      "WholesaleUnitsPerCase": 20,
      "SellByCaseOnly": true,
      "MinOrderUnits": 1,
      "Description": "Meticulously crafted from the purest ingredients, Example Brand's classic milk chocolate bar has hints of brown butter and a silky, creamy finish. Like all Example Brand chocolates, this bar is crafted from sustainably sourced, premium cacao infused with handmade, cold water cannabis hash. Ideal for those with a love for chocolate and a refined palate.Example Brand chocolates are crafted from sustainably sourced, premium cacao infused with pure, hand-crafted cold water hash. Since 2010, Example Brand's mission has been to change how the world views and uses cannabis. By applying art and science to ensure a delicious, consistent experience every time, we continue to deliver on that mission today.",
      "Ingredients": "Milk Chocolate (Sugar, Cocoa Butter, Milk, Unsweetened Chocolate, Sunflower Lecithin, Vanilla), Cannabis Extract.",
      "ThumbnailImageURL": "https://cdn.example.com/ExampleBrand/S3Images/example-thumbnail-2.png",
      "FullSizeImageURL": "https://cdn.example.com/ExampleBrand/S3Images/example-fullsize-2.png",
      "Potency": "100mg THC",
      "PotencyTHC": null,
      "Blend": "Hybrid",
      "KSSMenuCategory": "Edibles/Ingestibles",
      "KSSLiveCategoryID": 1,
      "StatusID": 1,
      "TimeUpdated": "2026-02-12T19:51:57.510Z",
      "State": "CA",
      "IsSample": false,
      "ProductGroupID": 3,
      "BrandStyle": "Example Bar",
      "PackageID": 97001,
      "PackageName": "20 Example Bar",
      "ProductTypeID": 96001,
      "StrainName": null,
      "StrainID": null,
      "Flavor": "milk",
      "BrandID": 98001,
      "BrandName": "Example Bars Base",
      "SupplierProductNumber": "EXAMPLE-BAR-MILK-50",
      "MetrcItemName": null
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/products/{productID}

Returns a single product by ID.

Parameters
Name Type Required Description
productID
path
 number required
The ID of the product to retrieve.
Field Definitions
Field Description
SellByCaseOnly
true when this product is sold only in full cases: each order line must be a whole multiple of WholesaleUnitsPerCase units. Order requests that break this are rejected with NOT_CASE_MULTIPLE, or adjusted to a full-case quantity when lenient handling is requested. Does not apply to lines priced as samples through a promotion. Null means there is no case-only rule.
MinOrderUnits
The minimum number of units an order line for this product must contain. 1 or null means there is no minimum. Order requests below it are rejected with BELOW_MIN_ORDER, or raised to the minimum when lenient handling is requested. Does not apply to lines priced as samples through a promotion. A product can have both a case-only rule and a minimum.
MetrcItemName
The item name registered for this product in Metrc. Null when no Metrc mapping exists.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
404
The requested resource was not found.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "ProductID": 30001,
      "Supplier": "Example Supplier",
      "SupplierID": 20001,
      "ProductName": "Bar Dark Chocolate",
      "BrandFamily": "Example Bars",
      "ProductTypeName": "Edible - Chocolate",
      "UnitNetWeight": "50g",
      "WholesaleUnitsPerCase": 20,
      "SellByCaseOnly": false,
      "MinOrderUnits": 5,
      "Description": "Our classic Dark Chocolate bar is uniquely complex with flavors of black coffee and dark cherry. Using a 57% sustainably sourced dark chocolate infused with pure, clean cold water hash, this bar is sure to delight any true chocolate lover.Example Brand chocolates are crafted from sustainably sourced, premium cacao infused with pure, hand-crafted cold water hash. Since 2010, Example Brand's mission has been to change how the world views and uses cannabis. By applying art and science to ensure a delicious, consistent experience every time, we continue to deliver on that mission today.",
      "Ingredients": "Semisweet Chocolate (Unsweetened Chocolate, Sugar, Cocoa Butter, Sunflower Lecithin, Vanilla), Cannabis Extract.",
      "ThumbnailImageURL": "https://cdn.example.com/ExampleBrand/S3Images/example-thumbnail-1.png",
      "FullSizeImageURL": "https://cdn.example.com/ExampleBrand/S3Images/example-fullsize-1.png",
      "Potency": "100mg THC",
      "PotencyTHC": null,
      "Blend": "Hybrid",
      "KSSMenuCategory": "Edibles/Ingestibles",
      "KSSLiveCategoryID": 1,
      "StatusID": 1,
      "TimeUpdated": "2026-02-12T19:51:57.510Z",
      "State": "CA",
      "IsSample": false,
      "ProductGroupID": 3,
      "BrandStyle": "Example Bar",
      "PackageID": 97001,
      "PackageName": "20 Example Bar",
      "ProductTypeID": 96001,
      "StrainName": null,
      "StrainID": null,
      "Flavor": "dark",
      "BrandID": 98001,
      "BrandName": "Example Bars Base",
      "SupplierProductNumber": "EXAMPLE-BAR-DARK-50",
      "MetrcItemName": "Example Bar Dark Chocolate 100mg"
    }
  ]
}
States
GET
/states
Paginated

Returns the active states available to your API key.

Parameters
Name Type Required Description
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "StateAbbreviation": "CA",
      "StateName": "California",
      "OrderCutOffTime": "2:30 PM",
      "TimeZone": "America/Los_Angeles",
      "OrderCutOffDaysInAdvance": "1",
      "TimeUpdated": "2025-12-30T18:28:17.710Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
Suppliers
GET
/suppliers
Paginated

Returns suppliers filtered by state, supplier ID, and status.

Parameters
Name Type Required Description
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Active
query
 boolean[] optional
True or False flag for supplier status. Defaults to Active = true. Keys with the CanViewInactiveSuppliers permission may pass Active=false (or true,false) to include inactive suppliers; for other keys the value is ignored.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "SupplierID": 20003,
      "Supplier": "Example Supplier",
      "State": "CA",
      "Active": true,
      "Description": "Premium cannabis edibles and infused products.",
      "BrandAssetsURL": "https://cdn.example.com/example-brand/brand-assets.zip",
      "SupplierWebsiteURL": "https://www.example.com",
      "TimeUpdated": "2025-01-01T00:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/suppliers/creditTerms
Requires CanEditOrderTerms Paginated

Returns the credit terms offered by each supplier.

Callout:
Requires the CanEditOrderTerms permission; keys without it receive a 403 naming the missing permission. Keys restricted to specific suppliers only see rows for those suppliers.
Parameters
Name Type Required Description
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "SupplierID": 20001,
      "TermID": 80001,
      "Term": "Net 30",
      "TimeUpdated": "2025-01-15T10:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/suppliers/{supplierID}

Returns a single supplier by ID.

Parameters
Name Type Required Description
supplierID
path
 number required
The ID of the supplier to retrieve.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
404
The requested resource was not found.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "SupplierID": 20003,
      "Supplier": "Example Supplier",
      "State": "CA",
      "Active": true,
      "Description": "Premium cannabis edibles and infused products.",
      "BrandAssetsURL": "https://cdn.example.com/example-brand/brand-assets.zip",
      "SupplierWebsiteURL": "https://www.example.com",
      "TimeUpdated": "2025-01-01T00:00:00.000Z"
    }
  ]
}
Users
GET
/users
Paginated

Returns users filtered by state, role, customer ID, and supplier ID. Keys restricted to specific suppliers return Supplier users for those suppliers plus Customer users. Keys restricted to specific customers only return Customer users for those customers.

Parameters
Name Type Required Description
UserIDs
query
 string optional
Comma-separated list of user IDs to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
Roles
query
 string optional
Comma-separated list of roles to filter by.
States
query
 string optional
Comma-separated list of state abbreviations to filter by. Example: "CA,NJ".
Active
query
 boolean[] optional
True or False flag for user status. Defaults to Active = true. Keys with the CanEditUsers permission may pass Active=false (or true,false) to include inactive users; for other keys the value is ignored.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "UserID": 90002,
      "SiteUserID": 91001,
      "UserActive": true,
      "KSSLiveAccess": true,
      "Email": "buyer@example.com",
      "States": [
        "CA"
      ],
      "Role": "Customer",
      "CustomerIDs": [
        10001
      ],
      "SupplierIDs": null,
      "LocationIDs": [
        40002
      ],
      "PowerUser": false,
      "JobTitle": null,
      "Department": null,
      "FullName": "Jane Buyer"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/users/{userID}

Returns a single user by ID.

Parameters
Name Type Required Description
userID
path
 number required
The ID of the user to retrieve.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
404
The requested resource was not found.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "UserID": 90002,
      "SiteUserID": 91001,
      "UserActive": true,
      "KSSLiveAccess": true,
      "Email": "buyer@example.com",
      "States": [
        "CA"
      ],
      "Role": "Customer",
      "CustomerIDs": [
        10001
      ],
      "SupplierIDs": null,
      "LocationIDs": [
        40002
      ],
      "PowerUser": false,
      "JobTitle": null,
      "Department": null,
      "FullName": "Jane Buyer"
    }
  ]
}
Payments
GET
/payments/types
Paginated

Returns the list of payment types. Optionally filter by PaymentTypeIDs or SupplierIDs.

Callout:
Each payment type is returned once per supplier in its product groups. Results default to active suppliers only; keys with the CanApplyPayments permission may include inactive suppliers with the Active filter. Keys restricted to specific suppliers only see rows for those suppliers, plus the shared generic payment type (PaymentTypeID = -1).
Parameters
Name Type Required Description
PaymentTypeIDs
query
 string optional
Comma-separated list of payment type IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
Active
query
 boolean[] optional
True or False flag for supplier status. Defaults to Active only; keys with the CanApplyPayments permission may override.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "PaymentTypeID": 82401,
      "Name": "ACH",
      "SupplierID": null,
      "TimeCreated": "2025-01-01T00:00:00.000Z",
      "TimeUpdated": "2025-01-01T00:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/payments
Paginated

Returns payments for an AR account, including payment type and available balance. AvailableBalance is the payment's remaining credit after confirmed applications and pending requests, and is never negative. A reversed payment can appear with a negative Amount and an AvailableBalance of 0. CustomerID and CustomerName identify the customer the payment was received from, and are null when that customer is not available.

Callout:
Keys restricted to specific customers only see payments for those customers' AR accounts. Keys restricted to specific suppliers only see payments belonging to those suppliers.
Parameters
Name Type Required Description
ARAccountIDs
query
 string optional
Comma-separated list of AR account IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
PaymentTypeIDs
query
 string optional
Comma-separated list of payment type IDs to filter by.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "PaymentID": 82001,
      "PaymentInvoiceID": 82201,
      "PaymentInvoiceNum": "INV-PAY-0001",
      "ARAccountID": 81002,
      "PaymentTypeID": 82401,
      "PaymentTypeName": "ACH",
      "Amount": "5000.000000",
      "SupplierID": null,
      "LoadSheetStatusID": 7,
      "PostDate": "2025-03-01T00:00:00.000Z",
      "TimeCreated": "2025-03-01T08:00:00.000Z",
      "TimeUpdated": "2025-03-01T08:00:00.000Z",
      "ARNote": null,
      "Memo": "Check #12345",
      "CustomerID": 10001,
      "CustomerName": "Kettles Secret Stash",
      "AvailableBalance": "3500.000000"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/payments/openInvoices
Paginated

Returns invoices with a non-zero open balance. Used to identify invoices eligible for payment allocation.

Callout:
Keys restricted to specific customers only see invoices for those customers' AR accounts. Keys restricted to specific suppliers only see invoices that contain those suppliers' products; InvoiceTotal and OpenBalance reflect only the portion of the invoice attributable to the supplier, and OpenDebit / OpenCredit are not returned. For all other keys InvoiceTotal and OpenBalance reflect the entire invoice.
Parameters
Name Type Required Description
ARAccountIDs
query
 string optional
Comma-separated list of AR account IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "InvoiceID": 60002,
      "InvoiceNum": "INV-2025-0042",
      "CustomerID": 10001,
      "CustomerName": "Kettles Secret Stash",
      "ARAccountID": 81002,
      "InvoiceTotal": "1200.00",
      "OpenDebit": "1200.00",
      "OpenCredit": "0.00",
      "OpenBalance": "1200.00",
      "CreditTermID": 5,
      "TermID": 5,
      "DueDate": "2025-04-01T00:00:00.000Z",
      "Date": "2025-03-01T00:00:00.000Z",
      "PONum": "PO-2025-001"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
GET
/payments/applications
Paginated

Returns payment allocations and allocation requests, each with its current Status (Pending, Exported, Confirmed, or Rejected). Includes both API-initiated requests and allocations applied outside the API. CustomerID and CustomerName identify the customer on the target invoice, and are null when that invoice is not available.

Callout:
Keys restricted to specific customers only see allocations for those customers' AR accounts. Keys restricted to specific suppliers only see allocations whose payment belongs to one of those suppliers. RequestID is null for allocations applied outside the API; PaymentApplicationID and TimeApplied are populated once a request has been confirmed.
Parameters
Name Type Required Description
ARAccountIDs
query
 string optional
Comma-separated list of AR account IDs to filter by.
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
PaymentInvoiceNums
query
 string optional
Comma-separated list of payment invoice numbers to filter by.
TargetInvoiceNums
query
 string optional
Comma-separated list of target invoice numbers to filter by.
Statuses
query
 string optional
Comma-separated list of statuses to filter by.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "PaymentApplicationID": 82101,
      "RequestID": 82301,
      "PaymentInvoiceNum": "INV-PAY-0001",
      "TargetInvoiceNum": "INV-2025-0042",
      "ARAccountID": 81002,
      "Amount": "1200.00",
      "Status": "Confirmed",
      "RequestedByUserID": 90002,
      "AppliedBy": "jsmith",
      "TimeRequested": "2025-03-08T09:00:00.000Z",
      "TimeExported": "2025-03-08T09:05:00.000Z",
      "TimeApplied": "2025-03-10T14:00:00.000Z",
      "TimeUpdated": "2025-03-10T14:00:00.000Z",
      "CustomerID": 10001,
      "CustomerName": "Kettles Secret Stash"
    },
    {
      "PaymentApplicationID": null,
      "RequestID": 82302,
      "PaymentInvoiceNum": "INV-PAY-0002",
      "TargetInvoiceNum": "INV-2025-0099",
      "ARAccountID": 81002,
      "Amount": "500.00",
      "Status": "Pending",
      "RequestedByUserID": 90002,
      "AppliedBy": null,
      "TimeRequested": "2025-03-19T10:00:00.000Z",
      "TimeExported": null,
      "TimeApplied": null,
      "TimeUpdated": "2025-03-19T10:00:00.000Z",
      "CustomerID": 10002,
      "CustomerName": "Kettles Downtown"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
POST
/payments/applications
Requires CanApplyPayments

Creates a payment allocation request. Validates the payment has sufficient available balance and the target invoice belongs to the same AR account. The request is queued as Pending and processed in the background; follow its Status (Pending, Exported, Confirmed, or Rejected) for the outcome.

Callout:
Requires the CanApplyPayments permission; keys without it receive a 403 naming the missing permission. Keys restricted to specific customers may only request allocations against those customers' AR accounts (403 otherwise). Keys restricted to specific suppliers may only allocate payments belonging to those suppliers (404 otherwise).
Parameters
Name Type Required Description
Idempotency-Key
header
 string optional
Optional for POST and PATCH requests. Send a unique key for each logical mutation so an exact retry can replay the original response instead of running the operation again. Keys are kept for at least 7 days after first use; after that, a request with the same key is processed as new. If a request never finished, an exact retry with its key is processed again after 30 minutes instead of returning 409 IDEMPOTENCY_KEY_IN_PROGRESS.
PaymentInvoiceNum
query
 string required
The invoice number of the payment to allocate from.
TargetInvoiceNum
query
 string required
The invoice number to allocate the payment toward.
ARAccountID
query
 number required
The AR account ID both invoices belong to.
Amount
query
 number required
The dollar amount to allocate. Must be positive and not exceed the available balance.
PaymentDate
query
 date optional
The date to record the allocation against, as YYYY-MM-DD. Defaults to the next business day for the target invoice's customer. Returns 400 when the value is not a valid date, or when it is omitted and no upcoming business day is available.
Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
409
The request conflicts with the current state of the resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": {
    "RequestID": 82302,
    "PaymentInvoiceNum": "INV-PAY-0001",
    "TargetInvoiceNum": "INV-2025-0042",
    "ARAccountID": 81002,
    "Amount": "500.00",
    "Status": "Pending",
    "RequestedByUserID": 90002,
    "PaymentDate": "2025-03-20",
    "TimeRequested": "2025-03-19T10:00:00.000Z",
    "TimeExported": null,
    "TimeConfirmed": null,
    "MatchedPaymentApplicationID": null,
    "TimeUpdated": "2025-03-19T10:00:00.000Z"
  }
}
Vendors
GET
/vendors
Requires CanViewPurchaseOrders Paginated

Returns the vendors a supplier ships from for each warehouse location, including address, lead time, and DOI targets.

Callout:
Requires the CanViewPurchaseOrders permission; keys without it receive a 403 naming the missing permission. Keys restricted to specific suppliers only see vendors for those suppliers. Inactive vendors are hidden unless requested via Active=false.
Parameters
Name Type Required Description
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
LocationIDs
query
 string optional
Comma-separated list of location IDs to filter by.
VendorIDs
query
 string optional
Comma-separated list of vendor IDs to filter by.
Active
query
 boolean[] optional
True or False flag for vendor status. Defaults to Active = true. Pass Active=false (or true,false) to include inactive vendors.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "SupplierID": 20001,
      "LocationID": 40002,
      "VendorID": 50002,
      "VendorName": "Acme Distributing",
      "VendorLicenseNumber": "C11-0000042-LIC",
      "VendorAddress": "500 Industrial Way",
      "VendorAddress2": null,
      "VendorCity": "Oakland",
      "VendorState": "CA",
      "VendorPostalCode": "94607",
      "LeadTimeDays": 5,
      "TargetDOI": 14,
      "MaxDOI": 30,
      "PickupDates": [
        "Mon",
        "Wed",
        "Fri"
      ],
      "RequirePOBatchCodes": false,
      "Active": true,
      "TimeUpdated": "2025-01-15T10:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50
}
Purchases
GET

Returns processed purchase orders filtered by purchase ID, vendor, location, status, and date range. Not accessible to Customer API keys.

Parameters
Name Type Required Description
PurchaseIDs
query
 string optional
Comma-separated list of numeric purchase IDs to filter by.
VendorIDs
query
 string optional
Comma-separated list of vendor IDs to filter by.
LocationIDs
query
 string optional
Comma-separated list of location IDs to filter by.
Statuses
query
 string optional
Comma-separated list of posted purchase statuses to filter by.
StartDate
query
 date optional
ISO 8601 date string. Returns purchases with a PostDate on or after this date.
EndDate
query
 date optional
ISO 8601 date string. Returns purchases with a PostDate on or before this date.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "PurchaseID": 70001,
      "ReceiveDate": "2026-06-02T06:00:00.000Z",
      "ShipmentNum": "Example PO 70001",
      "ShipmentID": 72001,
      "ToLocationID": 40001,
      "ToLocationName": "Alameda",
      "VendorName": "EXAMPLE DISTRIBUTORS LLC (Example Location)",
      "VendorID": 50001,
      "PostDate": "2026-06-02T06:00:00.000Z",
      "Status": "Verified",
      "PONum": "Example PO 70001",
      "Freight": "0.00",
      "Tax": "0.00",
      "OtherCost": "0.00",
      "Total": "35726.38",
      "TotalCases": "184.00",
      "PublicPDFLink": null,
      "PurchasePDFURLAPIKeyID": 94001,
      "Memo": null,
      "LastEditTime": null,
      "LastCalcTime": "2026-06-04T10:20:14.000Z",
      "TimeUpdated": "2026-08-21T18:06:57.930Z",
      "InvoiceDate": "2026-06-01T06:00:00.000Z",
      "DueDate": "2026-08-30T06:00:00.000Z",
      "Terms": "Driver Accounts",
      "TermID": 80002,
      "TimeCreated": "2026-06-15T22:09:09.921Z",
      "ReceivingNum": null
    }
  ],
  "Page": 1,
  "PageSize": 50,
  "HasNextPage": false
}
GET
/purchases/{purchaseID}
Requires CanViewPurchaseOrders Paginated v2 available

Returns processed purchase orders matching a numeric purchase ID. The response uses the same paginated array envelope as GET /purchases. Not accessible to Customer API keys.

Parameters
Name Type Required Description
purchaseID
path
 number required
Numeric purchase ID.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
404
The requested resource was not found.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "PurchaseID": 70001,
      "ReceiveDate": "2026-06-02T06:00:00.000Z",
      "ShipmentNum": "Example PO 70001",
      "ShipmentID": 72001,
      "ToLocationID": 40001,
      "ToLocationName": "Alameda",
      "VendorName": "EXAMPLE DISTRIBUTORS LLC (Example Location)",
      "VendorID": 50001,
      "PostDate": "2026-06-02T06:00:00.000Z",
      "Status": "Verified",
      "PONum": "Example PO 70001",
      "Freight": "0.00",
      "Tax": "0.00",
      "OtherCost": "0.00",
      "Total": "35726.38",
      "TotalCases": "184.00",
      "PublicPDFLink": null,
      "PurchasePDFURLAPIKeyID": 94001,
      "Memo": null,
      "LastEditTime": null,
      "LastCalcTime": "2026-06-04T10:20:14.000Z",
      "TimeUpdated": "2026-08-21T18:06:57.930Z",
      "InvoiceDate": "2026-06-01T06:00:00.000Z",
      "DueDate": "2026-08-30T06:00:00.000Z",
      "Terms": "Driver Accounts",
      "TermID": 80002,
      "TimeCreated": "2026-06-15T22:09:09.921Z",
      "ReceivingNum": null
    }
  ],
  "Page": 1,
  "PageSize": 50,
  "HasNextPage": false
}
Purchase Transactions
GET
/purchaseTrans
Requires CanViewPurchaseOrders Paginated v2 available

Returns purchase order line items for one or more purchases. PurchaseIDs is required. Not accessible to Customer API keys.

Parameters
Name Type Required Description
PurchaseIDs
query
 string required
Comma-separated list of purchase IDs to retrieve line items for.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "PurchaseTransID": 71001,
      "PurchaseID": 70002,
      "ProductID": 30006,
      "Ordered": "10",
      "NumUnits": "120",
      "FOB": "12.50",
      "DepositCost": "0.00",
      "ExtPrice": "1500.00",
      "ExpirationDate": "2026-01-01T00:00:00.000Z",
      "CodeDate": "2025-01-15T00:00:00.000Z",
      "BatchCode": "BCH-001",
      "LaidInCost": "13.00",
      "PalletTag": null,
      "Cases": "10",
      "Weight": "120.00",
      "TimeUpdated": "2025-03-02T10:00:00.000Z"
    }
  ],
  "Page": 1,
  "PageSize": 50,
  "HasNextPage": false
}
Sales Reps
GET
/salesReps
Paginated

Returns sales reps grouped by user, including both Territory Managers and Supplier Reps. Each result includes the rep's name, email, type, the product groups they cover, and arrays of associated customers and suppliers. Type is derived from ProductGroup: 'Supplier' indicates a Supplier Rep; any other value (e.g. a product-line group such as 'Cookies' or 'Tinctures') indicates a Territory Manager. Only returns active users, active customers, and active suppliers. Supplier API keys see reps scoped to their authorized suppliers. Customer API keys only see reps assigned to their own customers.

Parameters
Name Type Required Description
SupplierIDs
query
 string optional
Comma-separated list of supplier IDs to filter by.
CustomerIDs
query
 string optional
Comma-separated list of customer IDs to filter by.
ProductGroups
query
 string optional
Comma-separated list of product group names to filter by. Use 'Supplier' to limit results to Supplier Reps, or product-line names (e.g. 'Cookies') to limit to Territory Managers covering those groups.
Page
query
 number optional
Page number to retrieve. Defaults to 1.
PageSize
query
 number optional
Number of rows to return per page. Defaults to 50; maximum is 500.

Supports Page and PageSize query parameters. Default page size: 50. Maximum page size: 500 — larger values are reduced to 500.

Responses
Status Description
200
OK
400
The request is missing required input or contains invalid input.
401
The request is missing a valid API key.
403
The API key is not authorized to access this resource.
429
Rate limit exceeded.
500
Unexpected server error.
Example Response
json 
{
  "Data": [
    {
      "UserID": 90001,
      "Name": "Jane Smith",
      "Email": "jane.smith@example.com",
      "Type": "Territory Manager",
      "ProductGroups": [
        "Cookies",
        "Tinctures"
      ],
      "Suppliers": [
        {
          "SupplierID": 20004,
          "Supplier": "Example Confections"
        }
      ],
      "Customers": [
        {
          "CustomerID": 10002,
          "CustomerName": "Acme Dispensary"
        },
        {
          "CustomerID": 10003,
          "CustomerName": "Example Leaf Co"
        }
      ]
    },
    {
      "UserID": 90002,
      "Name": "Bob Jones",
      "Email": "bob.jones@supplier.com",
      "Type": "Supplier Rep",
      "ProductGroups": [
        "Supplier"
      ],
      "Suppliers": [
        {
          "SupplierID": 20004,
          "Supplier": "Example Confections"
        },
        {
          "SupplierID": 20005,
          "Supplier": "Example Brand 2"
        }
      ],
      "Customers": [
        {
          "CustomerID": 10002,
          "CustomerName": "Acme Dispensary"
        }
      ]
    }
  ],
  "Page": 1,
  "PageSize": 50
}