VendSoft API (2.0.0)

Download OpenAPI specification:

Introduction

Rate limits

Each authenticated API key is limited to 5,000 total requests per hour. Mutating requests are additionally limited to 1,500 per hour and 10,000 per day. A request over any limit returns HTTP 429 with a Retry-After value of 60 seconds.

Product

Operations about products.

Get list of products

Returns a list of products

Authorizations:
api_keybasic_auth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new product

Operation description Markdown.

Authorizations:
api_keybasic_auth
Request Body schema: application/json
required

requestBody description

productCode
string non-empty

Product SKU (should be unique)

productName
string non-empty

Product name

productType
string non-empty

Product type (category)

barcode
string

Barcode

unitsPerCase
integer

Number of items in a case / box

lastCost
number <double>

Last cost

averageCost
number <double>

Average cost

Responses

Request samples

Content type
application/json
{
  • "productCode": "COKE01",
  • "productName": "Coca Cola Can",
  • "productType": "Cold Drinks",
  • "barcode": "5449000000996",
  • "unitsPerCase": 24,
  • "lastCost": 0.1,
  • "averageCost": 0.1
}

Response samples

Content type
application/json
{
  • "productCode": "COKE01",
  • "productName": "Coca Cola Can",
  • "productType": "Cold Drinks",
  • "barcode": "5449000000996",
  • "unitsPerCase": 24,
  • "lastCost": 0.1,
  • "averageCost": 0.1
}

Update product

This can only be done by the logged in user.

Authorizations:
api_keybasic_auth
path Parameters
productCode
required
string

The code of the product that needs to be updated

Request Body schema: application/json
required

Updated product object

productCode
string non-empty

Product SKU (should be unique)

productName
string non-empty

Product name

productType
string non-empty

Product type (category)

barcode
string

Barcode

unitsPerCase
integer

Number of items in a case / box

lastCost
number <double>

Last cost

averageCost
number <double>

Average cost

Responses

Request samples

Content type
application/json
{
  • "productCode": "COKE01",
  • "productName": "Coca Cola Can",
  • "productType": "Cold Drinks",
  • "barcode": "5449000000996",
  • "unitsPerCase": 24,
  • "lastCost": 0.1,
  • "averageCost": 0.1
}

Response samples

Content type
application/json
{
  • "productCode": "COKE01",
  • "productName": "Coca Cola Can",
  • "productType": "Cold Drinks",
  • "barcode": "5449000000996",
  • "unitsPerCase": 24,
  • "lastCost": 0.1,
  • "averageCost": 0.1
}

Machine

Operations about machines.

Get list of machines

Returns a list of machines

Authorizations:
api_keybasic_auth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new machine

Operation description Markdown.

Authorizations:
api_keybasic_auth
Request Body schema: application/json
required

requestBody description

machineCode
string non-empty

Machine code (should be unique)

machineName
string non-empty

Machine name

machineType
string non-empty
Enum: "Soda" "Snack" "Coffee" "Soda/Snack" "Snack/Coffee"

Machine type

machineModel
string

Machine model

locationName
string

Location name

Responses

Request samples

Content type
application/json
{
  • "machineCode": "CD001",
  • "machineName": "Soda machine first floor",
  • "machineType": "Soda",
  • "machineModel": "Dixie Narco",
  • "locationName": "string"
}

Response samples

Content type
application/json
{
  • "machineCode": "CD001",
  • "machineName": "Soda machine first floor",
  • "machineType": "Soda",
  • "machineModel": "Dixie Narco",
  • "locationName": "string"
}

Update machine

This can only be done by the logged in user.

Authorizations:
api_keybasic_auth
Request Body schema: application/json
required

Updated machine object

machineCode
string non-empty

Machine code (should be unique)

machineName
string non-empty

Machine name

machineType
string non-empty
Enum: "Soda" "Snack" "Coffee" "Soda/Snack" "Snack/Coffee"

Machine type

machineModel
string

Machine model

locationName
string

Location name

Responses

Request samples

Content type
application/json
{
  • "machineCode": "CD001",
  • "machineName": "Soda machine first floor",
  • "machineType": "Soda",
  • "machineModel": "Dixie Narco",
  • "locationName": "string"
}

Response samples

Content type
application/json
{
  • "machineCode": "CD001",
  • "machineName": "Soda machine first floor",
  • "machineType": "Soda",
  • "machineModel": "Dixie Narco",
  • "locationName": "string"
}

Get telemetry sales

Get sales transactions from telemetry data for a specific machine.

Authorizations:
api_keybasic_auth
path Parameters
machineCode
required
string

The code of the machine

query Parameters
fromDate
string^\d{14}$
Example: fromDate=20250610000000

Start date in format yyyyMMddHHmmss

toDate
string^\d{14}$
Example: toDate=20250610235959

End date in format yyyyMMddHHmmss

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Planogram

Operations about machine planograms.

Get planogram

This can only be done by the logged in user.

Authorizations:
api_keybasic_auth
path Parameters
machineCode
required
string

The code of the machine

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update planogram

This can only be done by the logged in user.

Authorizations:
api_keybasic_auth
path Parameters
machineCode
required
string

The code of the machine that needs to be updated

Request Body schema: application/json
required

Updated machine object

Array
column
string non-empty

The item selection (should be unique)

columnType
string
Enum: "soda" "drink" "ingredient"

The type of the column

productCode
string non-empty

Product SKU (should be unique)

productName
string non-empty

Product name

productType
string non-empty

Product type (category)

vendPrice
number <double>

Vend price

maxCapacity
integer

Capacity of the column

lastCount
integer

The last fill level (for soda columns)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 400,
  • "detail": "string",
  • "instance": "string"
}

Refill

Operations about refilling machines.

Refill machine

This can only be done by the logged in user. A planogram write after a refill is not needed. Do not use lastCount on the planogram endpoint to correct counts between refills, because it does not move the refill time.

Authorizations:
api_keybasic_auth
path Parameters
machineCode
required
string

The code of the machine that needs to be updated

Request Body schema: application/json
required

Refill object

refillTime
string

Refill instant. Values without an offset, using either a space or T between the date and time, are interpreted as UTC. An explicit Z or numeric offset in +HH:mm or -HH:mm format is honored; compact offsets such as -0800 are not accepted. Fractional seconds are accepted and truncated to whole seconds. For example, 2026-11-06 00:17:04 and 2026-11-05T16:17:04-08:00 represent the same instant. A retry with the same refillTime, machine and driver replaces the existing visit. Missing or invalid values return HTTP 400 with "Invalid refillTime". An instant more than 10 minutes in the future returns HTTP 400 with "refillTime is in the future".

driverEmail
string

The email of the driver. If no active driver in this account matches the supplied email or username, a driver is created. Creation returns HTTP 400 if either identifier is already in use by another account.

driverUsername
string

The username of the driver. Driver lookup and creation follow the same rules as driverEmail.

cashCollected
boolean

A flag showing whether the cash has been collected during the visit

cashCollectedAmount
number <double>

The cash collected from the machine

Array of objects (RefillColumn)

Counts for the selections the driver counted. A selection left out keeps VendSoft's computed count (last count minus sales).

Responses

Request samples

Content type
application/json
{
  • "refillTime": "2026-11-06 00:17:04",
  • "driverEmail": "string",
  • "driverUsername": "string",
  • "cashCollected": true,
  • "cashCollectedAmount": 0.1,
  • "columns": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 400,
  • "detail": "string",
  • "instance": "string"
}

Location

Operations about locations.

Get list of locations

Returns a list of locations

Authorizations:
api_keybasic_auth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Purchase

Operations about purchases.

Create a new purchase

Operation description Markdown.

Authorizations:
api_keybasic_auth
Request Body schema: application/json
required

requestBody description

purchaseDate
string <date> non-empty

Date of the purchase

supplierName
string non-empty

Name of the supplier

invoiceNumber
string non-empty

Invoice number

shippingCost
number <double>

Shipping Cost

salesTax
number <double>

Sales Tax

Array of objects (PurchaseLineItem)

Purchase line items

Responses

Request samples

Content type
application/json
{
  • "purchaseDate": "2023-07-12",
  • "supplierName": "string",
  • "invoiceNumber": "string",
  • "shippingCost": 0.1,
  • "salesTax": 0.1,
  • "lineItems": [
    ]
}

Response samples

Content type
application/json
{
  • "purchaseDate": "2023-07-12",
  • "supplierName": "string",
  • "invoiceNumber": "string",
  • "shippingCost": 0.1,
  • "salesTax": 0.1,
  • "lineItems": [
    ]
}

Trip

Operations about trips.

Create a new trip

Creates a trip in Created status for an existing driver and a list of machines.

At least one of driverEmail or driverUsername must be provided, and the driver must already exist for the authenticated customer.

Authorizations:
api_keybasic_auth
Request Body schema: application/json
required

Create trip request

Any of
delivery_date
required
string non-empty

Preferred delivery date field. The API also accepts deliveryDate. Supported formats are yyyy-MM-dd, yyyy-MM-dd HH:mm:ss, yyyy-MM-dd'T'HH:mm:ss, and yyyy-MM-dd'T'HH:mm:ssZ.

driverEmail
required
string <email>

Email of an existing driver for this customer.

driverUsername
string

Username of an existing driver for this customer.

description
string

Optional trip description.

machineCodes
required
Array of strings non-empty

Preferred machine code array field. The API also accepts machine_codes.

Responses

Request samples

Content type
application/json
{
  • "delivery_date": "2026-04-06",
  • "driverEmail": "driver@example.com",
  • "description": "Tuesday downtown route",
  • "machineCodes": [
    ]
}

Response samples

Content type
application/json
{
  • "tripNumber": 12345
}

Ticket

Create a new ticket

Operation description Markdown.

Authorizations:
api_keybasic_auth
Request Body schema: application/json
required

requestBody description

machineCode
string non-empty

Machine Code

problemType
string non-empty

Problem Type

description
string

Description

clientEmail
string

Client Email

clientPhone
string

Client Phone

Responses

Request samples

Content type
application/json
{
  • "machineCode": "CD001",
  • "problemType": "Refund/Machine Broken/Restock Required/Product Request/Other",
  • "description": "string",
  • "clientEmail": "string",
  • "clientPhone": "string"
}

Response samples

Content type
application/json
{
  • "machineCode": "CD001",
  • "problemType": "Refund/Machine Broken/Restock Required/Product Request/Other",
  • "description": "string",
  • "clientEmail": "string",
  • "clientPhone": "string"
}