Mashgin Graph API

Mashgin Graph API is a RESTful JSON API that accesses basic data from the Mashgin data warehouse. JSON is returned by all API responses, including errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

Authentication

Example request:

curl https://graph.mashgin.com/v1/locations \
    -u {API_KEY}:

Replace {API_KEY} with your API key.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

API Usage

Requests are currently rate limited to 5 per second to minimize traffic spikes.

Errors

Graph API uses traditional HTTP response codes to indicate success or failure of an API request. the following error codes:

Error Code	Meaning
200 - Result Not Found	The request was successful, but no data was found matching your search query.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Authentication Error	Invalid or missing API key.
402 - Request Failed	The parameters were valid but the request failed.
403 - No Permission	You don't have permission to access the data.
404 - Not Found	The requested resource doesn't exist.
422 - Validation	One of the parameters sent is invalid.
429 - Too Many Requests	Too many requests hit the API too quickly.
500 - Internal Server Error	We had a problem with our server. Try again later or contact support.
503 - Timeout	Response has timed out (more than 30 seconds). This is likely very temporary and should be able to be retried. If it persists, please contact support with your full request.
513 - Response Too Large	The response size is over 5MB in size. Narrow your filters or contact Mashgin for more information.

Changelog

The changelog is a list of important updates in the API. This includes major features, capabilities, or backwards-incompatible changes. Minor updates and forwards-compatible changes will not appear in this list.

Release date	Changes
2024-07-29	Refunded transactions now show which items were refunded with count: -1.
2024-01-11	DEPRECATE UNUSED ENDPOINTS: Update POS ID; Transactions all-by-day.
2023-12-18	Refunded transactions can now be partial (less than original total). Transaction response remains the same, excepy tender.payment_status will be "refunded_partial".
2023-08-14	Added group field to location object to view groups a location is assoicated with.
2023-06-09	Added /v2/pricebook endpoint for syncing menu.
2023-04-07	Added fees_total field to transaction object.
2023-02-28	Added tips_total field to transaction object.
2023-02-01	All customer and report endpoints have been deprecated in preparation for the transaction to Mashgin's new Data API.
2022-12-16	(1) In transactions calls, total_count no longer displays the total non-paginated count. This drastically speeds up the request time. has_more field should reflect whether there are more pages to fetch. (2) Location transactions endpoint is now non-paginated, and accepts start/end dates only in format YYYY-MM-DD. Any ISO format will be converted. (3) DEPRECATED: Mashgin no longer tracks customers, so customer_id will return cust_0.
2021-10-14	Added query flag to All Transactions to allow conversion to local timezones.
2021-09-23	Added fields to transaction tenders (offline) and transaction items (taxes). Added field to discounts (ref).
2021-08-31	"All customers" endpoint now paginated by default, with a default limit of 2000 and date range of 7 days. Location customers endpoint temporarily disabled.
2021-08-27	Item endpoints are now paginated by default, with a default limit of 2000 items. Item object keys taxable, no_discount, side_ids, group, and item_type will all be deprecated in upcoming updates. As of this change they will return 0 or [] values.
2021-08-19	Transaction endpoints now return item pos_id and tags by default.
2021-08-04	Major transaction endpoint feature release. All transaction endpoints can now be paginated by using the paginate=true query parameter. In addition to total_count, all list responses will now return has_more and page to assist with proper pagination.
2021-03-15	Transaction location endpoint fetches transaction by payment time by default to match other reporting endpoints.

Use with Command Line

Example cURL Commands

Download a list of all locations:

curl https://graph.mashgin.com/v1/locations \
  -u "<api_key>": \
  -H "Accept: text/csv" > locations.csv

Download CSV of first 1000 transactions for all locations.

curl -G "https://graph.mashgin.com/v1/transactions" \
  -u "<api_key>": \
  -d "start=2023-08-21T00:00:00.000" \
  -d "end=2023-08-21T23:59:59.000" \
  -d "page=0" \
  -H "Accept: text/csv"  > transactions.csv

Download CSV of first 1000 item purchases for all locations.

curl -G "https://graph.mashgin.com/v1/transactions" \
  -u "<api_key>": \
  -d "start=2023-08-21T00:00:00.000" \
  -d "end=2023-08-21T23:59:59.000" \
  -d "items_only=true" \
  -d "page=0" \
  -H "Accept: text/csv" > transaction_items.csv

On MacOS

1. Open the Terminal app.
2. Type in cd ~/Downloads, then press Enter.
3. Copy any of the examples on the right and paste it into the Terminal prompt, making sure to replace <api_key> with your API token. Read the documentation for each endpoint about how to change the filters.
4. Press enter.
5. The result should be a CSV file in your Downloads folder.

Locations

Location object

Example Response

{
  "id": "loc_ac85m",
  "object": "location",
  "numeric_id": 134,
  "site_id": "010101010101",
  "name": "Bluth's Original Frozen Banana Stand",
  "active": 1,
  "kiosk_count": 1,
  "address": {
    "street": "1234 Newport Blvd.",
    "city": "Newport Beach",
    "state": "CA",
    "zip": "93402"
  },
  "timezone": "America/Los_Angeles",
  "week_end": "Wednesday",
  "type": "production",
  "credentials": {
    "freedompay": {...},
    "cbord": {...}
  },
  "operations": {
    "meals": [
      { "id": 1, "name": "Breakfast", "start": "06:00", "end": "10:30" },
      { "id": 2, "name": "Lunch", "start": "10:30", "end": "15:30" }
    ],
    "operation_hours": {
      "start": "00:00",
      "end:": "24:00",
      "weekends": true
    }
  },
  "groups": [{
    "id": 456,
    "type": "group",
    "name": "California Locations"
  }]
}

Attribute	Type	Description
id	string	Unique identifier for the object.
object	string	The object's type (location).
numeric_id	number	Numeric identifier for the location.
site_id	string	The client site ID of the location if it exists.
name	string	The name of the location.
active	boolean	Whether the location is currently operational.
kiosk_count	integer	The number of Mashgin kiosks at the location.
address	object	Location address if it exists, with street, city, state, zip, country, geo.
timezone	string	The tz timezone of the location.
week_end	string	Day of the week the reporting period ends.
type	string	Type of the location. Possible values are production, development, demo.
credentials	object	Payment credentials for the location. Values will depend on the payment types being used at the location.
operations	object	Operation times, including day parts.
operations.meals	collection	Collection of day parts, each with id, name, start time in HH:mm format, end time.
operations.operation_hours	object	Operation hours of the kiosks, with start time in HH:mm format, end time, and weekends boolean.
groups	collection	Collection of group objects, each with: id (number), type = "group", name (string).

List all locations

Example Request

curl https://graph.mashgin.com/v1/locations \
    -u {API_KEY}:

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "loc_jG2kD",
      "object": "location",
      "name": "Jack Rabbit Slims",
      "active": 1,
      "kiosk_count": 1,
      "credentials": {...}
    },
    ...
  ]
}

Returns a list of all your locations with abbreviated data.

HTTP Request

GET /v1/locations

Get a location

Example Request

curl https://graph.mashgin.com/v1/locations/{ID} \
    -u {API_KEY}:

Example Response

{
  "id": "loc_ay495m",
  "object": "location",
  "numeric_id": 876,
  "site_id": "010101010101",
  "name": "Pizza Planet",
  "active": 1,
  "kiosk_count": 1,
  "address": {...},
  "timezone": "America/Los_Angeles",
  "week_end": "Wednesday",
  "type": "production",
  "credentials": {...},
  "operations": {...},
  "groups": [...]
}

Returns all details of an individual location.

HTTP Request

GET /v1/locations/{ID}

URL Parameters

Parameter	Description
ID	The ID of the location to be retrieved.

Transactions

Transaction object

Example Transaction Object

{
  "id": "tx_7KDSCWCQQX",
  "object": "transaction",
  "start": "2018-09-19T03:50:06.000Z",
  "status": "complete",
  "sub_total": 3.19,
  "discount_total": 0.50,
  "fees_total": 0,
  "tips_total": 0,
  "tax": 0.2,
  "total": 3.39,
  "location_id": "loc_ay495m",
  "kiosk_id": "ksk_he532",
  "site_id": "123456",
  "time_total": 33.99,
  "upload_time": "2018-09-19T03:50:06.000Z",
  "meal": 0,
  "tenders": [
    {
      "payment_time": "2018-09-19T03:51:06.000Z",
      "payment_number": 1,
      "payment_type": "freedompay",
      "payment_method": "credit_card",
      "payment_amount": 3.39,
      "payment_status": "approved",
      "tender_type_id": "tdt_5",
      "tender_type": "air-mc",
      "card_type": "mc",
      "card_name": "Mobile Pay 5624",
      "card_number": "567212*1234",
      "auth_code": "11223344",
      "request_id": "DFWERTGFEFGDGHRTREYUE",
      "offline": false
    }
  ],
  "items": [
    {
      "item_id": "itm_gwU78",
      "numeric_id": 4,
      "pos_id": "A-12345",
      "name": "Bai Coconut 18oz",
      "count": 1,
      "weight": null,
      "options": [{
        "item_id": "itm_75bn8",
        "name": "Bottle Deposit",
        "pos_id": "534452D",
        "price": 0.05
      }],
      "discounts": [{
        "id": "disc_42",
        "name": "Employee Discount",
        "amount": 0.50
      }],
      "fees":[{
        "id": 83,
        "ref": "59",
        "name": "Sf Litter Fee Nt",
        "type": "flat",
        "value": 0.75,
        "amount": 0.75
      }],
      "item_price": 3.49,
      "total_price": 2.99,
      "tax": 0.43,
      "taxes": [{
        "id": 2311,
        "ref": "A1243",
        "name": "Sales Tax",
        "amount": 0.43,
        "rate": 0.08
      }],
      "after_tax_price": 3.42,
      "rebate_total": 0.51,
      "reco_method": "visual",
      "tags": ["beverage"]
    }
  ]
}

Example Refund Object

A refunded transaction will have identical data to the original transaction object (including id), except with a status of "refunded", additional negative payment_amount tender(s), and item count of -1 for any refunded items.

{
  "id": "tx_7KDSCWCQQX",
  "object": "transaction",
  "start": "2023-09-19T03:50:06.000Z",
  "status": "refunded",
  "sub_total": 3.19,
  "discount_total": 0.50,
  "fees_total": 0,
  "tips_total": 0,
  "tax": 0.2,
  "total": 3.39,
  "location_id": "loc_ay495m",
  "kiosk_id": "ksk_he532",
  "site_id": "123456",
  "time_total": 33.99,
  "upload_time": "2023-09-20T03:51:06.000Z",
  "meal": 0,
  "tenders": [
    {
      "payment_number": 1,
      "payment_time": "2023-09-19T03:51:06.000Z",
      "payment_type": "freedompay",
      "payment_method": "credit_card",
      "payment_amount": 3.39,
      "payment_status": "approved",
      "tender_type_id": "tdt_5",
      "tender_type": "air-mc",
      "card_type": "mc",
      "card_name": "Mobile Pay 5624",
      "card_number": "567212*1234",
      "auth_code": "11223344",
      "request_id": "DFWERTGFEFGDGHRTREYUE",
      "offline": false
    }, {
      
      "payment_number": 2,
      "payment_time": "2023-09-20T03:51:06.000Z",
      "payment_type": "freedompay",
      "payment_method": "credit_card",
      "payment_amount": -3.39,
      "payment_status": "refunded", // or "refunded_partial" if amount is less than transaction total
      "tender_type_id": "tdt_5",
      "tender_type": "air-mc"
    }
  ],
  "items": [
    {
      "count": -1,
      ...
    }
  ]
}

Attribute	Type	Description
id	string	Unique identifier for the object.
object	string	The object's type (transaction).
start	timestamp	Start time of the transaction (ISO String).
status	string	Current status of the transaction. Possible values: complete, refunded.
sub_total	number	Pre-tax sub-total.
discount_total	number	Total amount of discounts.
fees_total	number	Total amount of fees.
tips_total	number	Total amount of tips.
tax	number	Tax amount.
total	number	Total amount customer was charged.
location_id	string	ID of the transaction's location.
kiosk_id	string	ID of the kiosk the transaction occured on. "mobile" if transaction went through on mobile app.
site_id	string	Customer-provided ID of the transaction's source location or profit center.
time_total	number	Total transaction time in seconds (sum of 4 other times).
upload_time	timestamp	The time the transaction was uploaded to Mashgin cloud servers.
meal	number	ID of the day part for the transaction. 0 is default (all day).
tenders	collection	List of transaction tenders.
tenders.payment_time	string	Time of payment (ISO String).
tenders.payment_type	string	Processor of payment. Possible values: freedompay, cbord, braintree, stadis, ...
tenders.payment_method	string	Method of payment. Possible values: credit_card, chase, stored_value, loyalty.
tenders.payment_amount	number	Amount tendered. Refunds will be negative.
tenders.payment_status	string	Status of payment. Possible values: approved, rejected, refunded, refunded_partial, reversed.
tenders.tender_type_id	string	Tender object ID (see Tender Types endpoint). If tender doesn't match existing type, type will be null.
tenders.tender_type	string	Type of tender (see Tender Types endpoint). If tender doesn't match existing type, type will be "unknown".
tenders.card_type	string	Type of card used. Possible values: visa, mc, amex, discover, other.
tenders.card_name	string	Name on the card if available.
tenders.card_number	string	Masked card number (or full card ID if stored value)
tenders.auth_code	string	Auth code of payment if it exists.
tenders.request_id	string	Request ID from the payment provider.
tenders.offline	boolean	Whether the payment occured offline or not.
items	collection	List of items in transaction (See Item object), plus the following fields:
items.count	number	Count will always be 1 in a completed transaction. In refunded transactions, and refunded item will have count of -1.
items.discounts	collection	List of discounts applied to the item. Includes fields id, name and amount.
items.fees	collection	List of fees applied to the item. Includes fields id, ref, name, type, value and amount.
items.item_price	number	Original unit price of item. If priced by weight, this is the price per pound.
items.total_price	number	Total price of the item at time of sale, including all options and discounts.
items.discount_total	number	Total discounts applied to item.
items.fees_total	number	Total fees applied to item.
items.tax	number	Total tax applied to item.
items.taxes	collection	List of individual taxes applied to the item. Includes fields name {string}, id {number}, ref {string}, amount {number}, and rate {number}.
items.after_tax_price	number	After tax price of item.
items.rebate_total	number	Tax rebate of the item.
items.price_by_weight	boolean	Whether the item is priced by weight.
items.reco_method	string	The method that the item was recognized.

All transactions

Example Request

Display a JSON of transactions:

# First page:
curl -G "https://graph.mashgin.com/v1/transactions" \
  -u "<api_key>": \
  -d "start=2023-08-21T00:00:00.000" \
  -d "end=2023-08-21T23:59:59.000" \
  -d "page=0"

import requests

def get_transactions(page=0):
    url = "https://graph.mashgin.com/v1/transactions"
    token = "{API_KEY}"
    querystring = {
        "start": "2023-04-11T00:00:00",
        "end": "2023-04-11T23:59:59.999",
        "page": page,
        "limit": 1000
    }

    response = requests.get(
        url,
        auth=(token, ''),
        params=querystring
    ).json()

    transactions = response.get('data')

    if response.get('has_more'):
        transactions.extend(get_transactions(page + 1))
    
    return transactions

get_transactions()

Download a CSV of item purchases:

# First page:
curl -G "https://graph.mashgin.com/v1/transactions" \
  -u "<api_key>": \
  -d "start=2023-08-21T00:00:00.000" \
  -d "end=2023-08-21T23:59:59.000" \
  -d "items_only=true" \
  -d "page=0" \
  -H "Accept: text/csv" > transaction_items.csv

import requests

def get_transactions(page=0, first_page=True):
    url = "https://graph.mashgin.com/v1/transactions"
    token = "{API_KEY}"
    querystring = {
        "start": "2023-04-11T00:00:00",
        "end": "2023-04-11T23:59:59.999",
        "page": page,
        "limit": 1000
    }
    headers = {
        "Accept": "text/csv"
    }

    response = requests.get(
        url,
        auth=(token, ''),
        params=querystring,
        headers=headers
    )

    if response.status_code == 200:
        with open('transactions.csv', 'a') as f:
            # If it's the first page, write everything including headers
            if first_page:
                f.write(response.text)
            else:
                # If it's not the first page, skip the header line
                f.write('\n'.join(response.text.split('\n')[1:]))

    if response.json().get('has_more'):
        get_transactions(page + 1, first_page=False)

get_transactions()

Example Response

{
  "object": "list",
  "has_more": true,
  "page": 0,
  "data": [
    {
      "id": "tx_W6BIN6S22P",
      "object": "transaction",
      "start": "2018-12-05T14:00:56.000Z",
      "status": "complete",
      "sub_total": 4.99,
      "discount_total": 0,
      "tips_total": 0,
      "fees_total": 0,
      "tax": 0.41,
      "total": 5.4,
      "location_id": "loc_MyhfA",
      "kiosk_id": "ksk_E346j",
      "customer_id": "cust_g127B",
      "site_id": "12345678",
      "time_total": 33.99,
      "meal": 0,
      "tenders": [
        {
          "payment_number": 1,
          "payment_time": "2018-12-05T14:02:25.000Z",
          "payment_type": "freedompay",
          "payment_method": "credit_card",
          "payment_amount": 5.4,
          "payment_status": "approved",
          "tender_type_id": "tdt_5",
          "tender_type": "air-visa",
          "card_type": "visa",
          "card_name": "MICHAEL BLUTH",
          "auth_code": "11223344",
          "request_id": "DFWERTGFEFGDGHRTREYUE",
          "offline": false
        }
      ],
      "items": [
        {
          "item_id": "itm_vWSkW6",
          "numeric_id": "987654",
          "pos_id": "B-8899",
          "name": "Frozen Bananas",
          "count": 1,
          "weight": null,
          "options": [],
          "discounts": [],
          "item_price": 4.99,
          "reco_method": "visual",
          "item_price": 4.99,
          "total_price": 4.99,
          "tax": 0.41,
          "taxes": [...],
          "after_tax_price": 5.4,
          "price_by_weight": false,
          "reco_method": "visual"
        }
      ]
    },
    ...
  ]
}

Returns a list of every transaction and refund in all locations in specified period. All times queried and returned are in UTC unless otherwise specified.

By default, transaction query is based on upload time rather than actual start time. This should allow the results to match with other aggregated reporting functions in Mashgin Cloud.

A refunded transaction will appear twice: once for the original transaction, and again when the refund takes place. Transaction id will be the same in both objects. (See this example above of a refund object.) Example if fetching 1 day at a time: If a transaction and its refund occur in the same day, there will be 2 objects with the same id in the results. If the refund occurs the following day, the original transaction will be in day 1, and the refund in day 2.

HTTP Request

GET /v1/transactions

Query Parameters

Parameter	Default	Description
start	today	Start time in UTC to get transactions. Accepts UTC ISO String.
end	today	End time in UTC to get transactions. Accepts UTC ISO String. Time range limited to 1 day.
page	0	The page number to return (indexed to 0);
limit	500	Limit of transactions to return, between 1 and 1000.
local_time	false	Converts start and tenders.payment_time to local timezone and includes timezone {string} field in transaction objects.
decoded_ids	false	Includes decoded versions of location ID, kiosk ID and transaction ID.
items_only	false	Returns a flattened list of transaction items including all transaction fields but no tenders.

List Response Format

Attribute	Type	Description
object	string	"list"
has_more	boolean	Whether there are more pages or not when paginated.
page	number	Current page number (indexed to 0).
data	collection	List of transactions.

Location transactions

Example Request

curl 'https://graph.mashgin.com/v1/locations/{ID}/transactions?start=2023-09-18' \
    -u {API_KEY}:

import requests

def get_transactions(location, page=0):
    url = f"https://graph.mashgin.com/v1/locations/{location}/transactions"
    token = "{API_KEY}"
    querystring = {
        "start": "2023-04-11",
        "end": "2023-04-11",
        "page": page,
        "limit": 1000
    }

    response = requests.get(
        url,
        auth=(token, ''),
        params=querystring
    ).json()

    transactions = response.get('data')

    if response.get('has_more'):
        transactions.extend(get_transactions(location, page + 1))
    
    return transactions

transactions = get_transactions('loc_12345')

Example Response

{
  "object": "list",
  "has_more": false,
  "page": 0,
  "data": [
    {
      "id": "tx_434CE5SX2L5",
      "object": "transaction",
      "start": "2018-09-19T03:59:51.000Z",
      ...
    },
    ...
  ]
}

Returns a list of all completed and refunded transactions for a location and specified period.

All transaction times (including query parameters) are adjusted automatically for local timezone. By default, transaction query is based on upload time rather than actual start time. This should allow the results to match with other aggregated reporting functions in Mashgin Cloud.

A refunded transaction will appear twice: once for the original transaction, and again when the refund takes place. Transaction id will be the same in both objects. (See this example above of a refund object.) Example if fetching 1 day at a time: If a transaction and its refund occur in the same day, there will be 2 objects with the same id in the results. If the refund occurs the following day, the original transaction will be in day 1, and the refund in day 2.

HTTP Request

GET /v1/locations/{ID}/transactions

URL Parameters

Parameter	Description
ID	The ID of the location or the site ID to fetch transactions.

Query Parameters

Parameter	Default	Description
start	today	Start time to get transactions. Accepts "YYYY-MM-DD" which uses start-of-day 00:00 in local timezone (this will match Mashgin's reporting summaries).
end	today	End time to get transactions. Accepts "YYYY-MM-DD" which uses end-of-day 24:00 in local timezone (this will match Mashgin's reporting summaries). Time range limited to 7 days.

List Response Format

Attribute	Type	Description
object	string	"list"
has_more	boolean	Whether there are more pages or not when paginated.
page	number	Current page number (indexed to 0).
data	collection	List of transactions.

Get a transaction

Example Request

curl https://graph.mashgin.com/v1/transactions/{ID} \
    -u {API_KEY}:

import requests

response = requests.get(
  f'https://graph.mashgin.com/v1/transactions/{id}',
  auth=('{API_KEY}', '')
).json()

transaction = response.get('data')

Example Response

{
  "id": "tx_WJPCEJ16PDJ",
  "object": "transaction",
  "start": "2018-09-20T02:50:50.000Z",
  "status": "complete",
  "sub_total": 4.99,
  "discount_total": 0,
  "tips_total": 0,
  "fees_total": 0,
  "tax": 0.41,
  "total": 5.4,
  "location_id": "loc_MyhfA",
  "kiosk_id": "ksk_E346j",
  "customer_id": "cust_g127B",
  "site_id": "12345678",
  "time_total": 33.99,
  "meal": 0,
  "tenders": [
    {
      "payment_number": 1,
      "payment_type": "freedompay",
      "payment_method": "credit_card",
      "payment_amount": 1.71,
      "payment_status": "approved",
      "card_type": "visa",
      "card_name": "MICHAEL BLUTH",
      "auth_code": "11223344",
      "request_id": "DFWERTGFEFGDGHRTREYUE",
      "offline": false
    }
  ],
  "items": [
    {
      "item_id": "itm_vWSkW6",
      "numeric_id": "987654",
      "pos_id": "B-8899",
      "name": "Frozen Banana",
      "count": 1,
      "weight": null,
      "options": [],
      "discounts": [],
      "reco_method": "visual",
      "item_price": 4.99,
      "total_price": 4.99,
      "tax": 0.41,
      "taxes": [...],
      "after_tax_price": 5.4,
      "price_by_weight": false,
      "reco_method": "visual"
    }
  ]
}

Returns all details of an individual transaction, including tenders used and items purchased.

HTTP Request

GET /v1/transactions/{ID}

URL Parameters

Parameter	Description
ID	The ID of the transaction to be retrieved.

Items

Item object

Example Response

{
  "id": "itm_g6jA11",
  "object": "item",
  "numeric_id": 4,
  "location_id": "loc_jG2kD",
  "global_id": "gi_Ge6t50",
  "name": "Cheeseburger Special",
  "price": 4.99,
  "weight": null,
  "sku": ["123456789098"],
  "pos_id": "CS-12456",
  "price_by_weight": 0,
  "meal": null,
  "active": 1,
  "options": [
    {
      "item_id": "itm_c78A11",
        "name": "Add Bacon",
        "price": 0.49,
        "type": "multi",
        "group": 1
    }
  ],
  "labels": [
      {
      "type": "identifier",
      "pattern": "F1"
    }, {
      "type": "qr",
      "pattern": "001234567"
    }
  ],
  "container_ids": [],
  "tags": []
}

Attribute	Type	Description
id	string	Unique identifier for the object.
object	string	The object's type (item).
numeric_id	number	Numeric identifier for the item in the specific location.
location_id	string	ID of the location the item is in.
global_id	string	Optional Global ID the local item matches to.
name	string	The name of the item.
price	number	Price of the item.
weight	number	Weight of the item if applicable.
sku	string[]	Array of SKU/UPC values associated with item.
pos_id	string	Optional ID that associates the item with an item on the local point of sale or client database.
price_by_weight	boolean	Whether the item is priced based on weight (pounds). If it is, price will be per pound.
meal	string	Meal the item is specific to, if any. Possible values: null, "breakfast", "lunch", "dinner".
active	boolean	Whether the item is currently in use.
options	collection	Options available for the item. item_id = ID of option item. name = Name of option. price = Price of the option. type = multi or single select. group = Which group to show options in.
labels	collection	Labels that identify that item, if any. type: upc UPC barcode qr QR code identifier Mashgin DotCode modifier Mashgin DotCode subset Mashgin DotCode. pattern: Label pattern to match.
container_ids	string[]	List of container item IDs the item goes in.
tags	string[]	List of tag names associated with the item. (Ex. "category-beverage")

List all items

Example Request

curl https://graph.mashgin.com/v1/locations/{ID}/items \
    -u {API_KEY}:

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "itm_atyU11",
      "object": "item",
      "numeric_id": 6,
      "location_id": "loc_jG2kD",
      "global_id": "gi_k7gj",
      "name": "Milkshake",
      "display_name": null,
      "price": 3.99,
      "weight": null,
      "sku": null,
      "pos_id": null,
      "price_by_weight": 0,
      "meal": "lunch",
      "active": 1
    },
    ...
  ]
}

Returns a list of all items in a location with header data.

HTTP Request

GET /v1/locations/{ID}/items

URL Parameters

Parameter	Description
ID	The ID of the location to retrieve the items from.

Query Parameters

Parameter	Default	Description
page	0	The page number to return (indexed to 0);
limit	2000	Limit of items to return, between 1 and 5000.

List Response Format

Attribute	Type	Description
object	string	"list"
total_count	number	Count of all items for the location.
has_more	boolean	Whether there are more pages.
page	number	Current page number (indexed to 0).
data	collection	List of items.

Get an item

Example Request

curl https://graph.mashgin.com/v1/items/{ID} \
    -u {API_KEY}:

Example Response

{
  "id": "itm_5hGK1",
  "object": "item",
  "numeric_id": 8,
  "location_id": "loc_jG2kD",
  "global_id": null,
  "name": "Sweet Potato Fries Boat",
  "display_name": "Sweet Potato Fries",
  "price": 2.99,
  "weight": null,
  "sku": null,
  "pos_id": "",
  "price_by_weight": 0,
  "meal": null,
  "active": 1,
  "options": [],
  "labels": [],
  "container_ids": [],
  "tags": []
}

Returns all details of an individual item.

HTTP Request

GET /v1/items/{ID}

URL Parameters

Parameter	Description
ID	The ID of the item to be retrieved.

Pricebook

Pricebook object

Sample Mashgin Pricebook Object

{
  "site_id": "MO123456",
  "taxes": [
    {
      "name": "CA Sales Tax",
      "details": {
        "rates": { "ALL": 0.0825 },
        "skip_tags": ["tax-free-item"],
      }
    },
    {
      "name": "Special Tax",
      "details": {
        "rates": { "ALL": 0.02 },
        "apply_to_tags": ["tax-1"]
      }
    }
  ],
  "items": [
    {
      "name": "Coca-Cola 20oz",
      "pos_id": "012345678900-0",
      "price": 2.99,
      "sku": "012345678900",
      "active": 1,
      "tags": ["beverage", "category-01456", "tax-1"]
    }
  ],
  "discounts": [
    {
      "name": "$6.99 Pizza Combo",
      "discount_type": "combo",
      "details": {
        "items": [
          ["012345678900-0", "012345678900-0"],
          ["012345678900-0", "012345678900-0"]
        ],
        "total_amount": 6.99
      },
      "ref": "GHRD345DG9500S"
    },
    {
      "name": "New Years BOGO Ice Cream",
      "discount_type": "single",
      "details": {
        "items": ["ice-cream", "ice-cream"],
        "rules": [{"percent_off": 0}, {"percent_off": 100}],
        "start_datetime": "2023-01-01 00:00:00",
        "end_datetime": "2023-01-02 00:00:00"
      },
      "ref": "GHR981239555S"
    },
    {
      "name": "Happy Hour 10% off",
      "discount_type": "global",
      "details": {
        "percent_off": 10,
        "times_of_day": "14:00-15:00,17:30-18:00",
        "skip_tags": ["alcohol"]
      },
      "ref": "GHR981239555S"
    }
  ],
  "fees": [
    {
      "name": "CRV Fee",
      "ref": "fee1234455",
      "details": {
        "type": "flat",
        "value": 0.05,
        "items": ["crv-fee"]
      }
    }
  ]
}

Pricebook object

Field	Required	Type	Description
site_id	Yes	String	Your unique identifier for the location. This must match the site ID that Mashgin has on record for the location.
taxes	No	Tax[]	Collection of tax objects (tax rules). If not present, taxes will not be updated. If present, all taxes will be updated to match those in the array.
items	No	Item[]	Collection of item objects. If not present, items will not be updated. If present, all items will be updated to match those in the array. Depending on the client or location settings, items not present will either be deactivated or deleted.
discounts	No	Discount[]	Collection of discount objects (promotions). If not present, discounts will not be updated. If present, all discounts will be updated to match those in the array.
fees	No	Fee[]	Collection of fee objects. If not present, fees will not be updated. If present, all fees will be updated to match those in the array.

Item object

Field	Required	Type	Description
name	Yes	String	The item name that will be display to the customer.
pos_id	Yes	String	Your unique item identifier.
price	Yes	Float	Price of the item.
sku	No	String, String[]	The barcode identifier, UPC or SKU. Accepts a single string or an array of strings.
sku_type	No	String	One of: "UPC-A", "UPC-E", "EAN-13", "EAN-8", or "EAN-CUSTOM" for any other type.
active	No	Boolean	Whether the item is active or not. Defaults to true (active).
tags	No	String[]	List of item tags. Tags can be used for anything from applying discounts/taxes/fees to tracking for reporting purposes. If tags field is not present, existing tags will not be updated; otherwise if present, all tags will be updated to match those in the array.

Tax object

Field	Required	Type	Description
name	Yes	String	Tax name that will be displayed to customers (must be unique)
details	Yes	Object	Tax details object.
details.rates	Yes	Object	Ex: {"ALL":0.095}
details.rates.ALL	Yes	Float	Tax rate to apply, in decimals. A rate of 8.25% would be 0.0825.
details.apply_to_tags	No	String[]	List of item tags the tax should apply to. If not present, tax will be applied to all items in cart that don’t have one of the skip_tags.
details.skip_tags	No	String[]	List of item tags that the tax should not apply to. If not present, tax will be applied to all items matching apply_to_tags or entire cart if this is not present.
ref	Yes	String	Client tax reference or ID. Any unique string you can use to refer back to.

Discount object

Field	Required	Type	Description
name	Yes	String	Discount name that will be displayed to customers.
discount_type	Yes	String	Type of discount. One of: "global": Applies to all items in the cart. "single": Adjusts price of a single item without regard to other items in the cart. "combo": Adjusts prices of a group of items.
ref	Yes	String	Client discount reference or ID. Any unique string you can use to refer back to.
details	Yes	Object	Discount details object. Required to have only one of either amount_off, percent_off, total_amount, rules.
details.items	If type in [single, combo]	String[], String[][]	Required for type of single or combo. Single: Items should be an array of POS ID or tag strings the discount should apply to. Ex: [”1234”, “side-dish”] Combo: Items should be an array of arrays of POS ID or tag strings. Each array represents 1 item in the combo. So a 3-item combo could be: [[”001”], [”002”, “002B”], [”drink”]]
details.amount_off	No	Float	Apply fixed amount off subtotal. A value of “2” would subtract $2.00 from the total. Number can be negative to add amount as well.
details.percent_off	No	Float	Apply percentage off subtotal. Amount is “per cent” and will be divided by 100 before multiplying. A value of “10” on a $5.00 subtotal will add a discount of $0.50.
details.total_amount	No	Float	Adjust the subtotal to the provided value. A value of “8.5” on a $10.00 subtotal would add a discount of $1.50.
details.rules	No	Object[]	Adjust the subtotal for each combo group by amount_off, percent_off, or total_amount. Ex: For a Buy-One-Get-One item combo of [[”drink”],[”drink”]], the rules could be [{"percent_off":0}, {"percent_off":100}] or [{"amount_off":0}, {"total_amount":0}]; either would mark one of the drinks as $0.
details.start_datetime	No	String	When the discount should start applying. If not present, discount will go into effect immediately after sync. Format should be "YYYY-MM-DD HH:mm:ss".
details.end_datetime	No	String	When the discount should end. If not present, discount will be applied until it is removed or deactivated. Format should be "YYYY-MM-DD HH:mm:ss".
details.times_of_day	No	String	Provide a comma-separated list of daily time ranges in the format HH:mm. The discount will only apply in these windows. Times use local timezone. Ex: “08:00-09:30,13:30-15:00” would apply the discount from 8-9:30am and 1:30-3:00pm.
details.skip_tags	No	String[]	For global discount types. An array of item tags where the discount should not be applied. Ex: [”alcohol”] will not apply the discount to any item with that tag.
details.regexp	No	String	A value or regular expression that triggers the discount when scanned on the kiosk via barcode, QR, or otherwise. This can be any length, and will be read as a RegExp string meaning any special characters need to be backslashed. Ex: with a value of "0001\d\d\d" a barcode scan of 0001845 would trigger the discount.
details.rebate_amount	No	Float	Adds a taxable rebate amount to the discount. These are manufacturer discounts that are taxable. The rebate amount is the amount that is taxed — so a discount that has amount_off: 2 and rebate_amount: 1.5 will add a $2 discount but only $1.50 of that will be the taxable rebate. Similarly, if these discounts are already included in the item price, then the amount_off can be set to zero, and the rebate_amount can be positive.

Fee object

Field	Required	Type	Description
name	Yes	String	Fee name that will be displayed to customers.
details	Yes	Object	Fee details object.
details.type	Yes	String	Type of fee. One of: "flat": Flat amount. "percent": Percent of item subtotal.
details.value	Yes	Float	Amount of fee to apply as a flat rate or percentage. Ex. for flat: “0.05” adds a fee of $0.05. For percent, “1.5” adds a fee of 1.5%.
details.items	Yes	String[]	List of item POS IDs or tags for the fee to apply to.
ref	Yes	String	Client fee reference or ID. Any unique string you can use to refer back to.

Import Pricebook

Example Request

curl https://graph.mashgin.com/v2/pricebook \
    -u {API_KEY}: \
    -X POST \
    --data '{
  "site_id": "123456",
  "items": ...
}'

import requests

url = "https://graph.mashgin.com/v2/pricebook"
token = "{API_KEY}"
pricebook = {
  "site_id": "S4698210134",
  "items": [
    {
      "name": "Chicken Sandwich",
      "pos_id": "0013545212111",
      "price": 7.99,
      "sku": "0013545212111"
    }
  ]
}

response = requests.post(
  url,
  auth=(token, ''),
  data=pricebook
).json()

summary = response.get('data')

Example Response

{
  "object": "summary",
  "data": {
    "preview": false,
    "items": {
      "inserts": 14,
      "updates": 162,
      "deletes": 0
    },
    "discounts": {
      "inserts": 0,
      "updates": 4,
      "deletes": 0
    },
    "fees": {
      "inserts": 0,
      "updates": 0,
      "deletes": 0
    },
    "taxes": {
      "inserts": 0,
      "updates": 0,
      "deletes": 0
    }
  }
}

Example Validation Errors

{
  "code": 422,
  "error": {
    "message": "Pricebook validation errors",
    "type": "validation",
    "errors": [
      {
        "code": "missing_field",
        "description": "`pos_id` is required for item object (name = RC Cola)"
      },
      {
        "code": "wrong_type",
        "description": "`price` in item object must be of type Float (pos_id = 12345, name = RC Cola)"
      }
    ]
  }
}

Allows you to update the full menu for a location, including: items, discounts, taxes, fees.

Accepts a Mashgin Pricebook Object as JSON data.

HTTP Request

POST /v2/pricebook

JSON Data Parameters

A full Mashgin Pricebook Object must be passed as JSON data.

Query Parameters

Parameter	Default	Description
preview_only	false	Set to "true" to preview all changes.

Sync with Client API

Example Request

curl https://graph.mashgin.com/v2/locations/loc_1234/sync \
    -u {API_KEY}:

Initiates a location sync with your Mashgin client integration. This is only relevant if Mashgin has a custom API integration with your locations.

HTTP Request

GET /v2/locations/{ID}/sync

URL Parameters

Parameter	Description
ID	The ID or client site_id of the location to be synced.

Response

Responses will differ for each client integration. In general, assume that any non-error response was successful.

Menu

Menu object

Example Object

{
  "object": "menu",
  "location_id": "loc_ac85m",
  "name": "Bluth's Original Frozen Banana Stand",
  "timezone": "America/Los_Angeles",
  "image": {
    "url_small": "https://order.mashgin.com/mash.api-images/sample_small.jpg",
    "url": "https://order.mashgin.com/mash.api-images/sample.jpg"
  },
  "stations": [
    {
      "object": "station",
      "id": 373,
      "name": "Main Menu",
      "description": "",
      "image": {
        "url_small": null,
        "url": null
      },
      "categories": [{
        "object": "category",
        "id": 381,
        "name": "Frozen Treats",
        "description": "",
        "image": {
          "url_small": null,
          "url": null
        }
      },  ...],
      "items": [{
        "object": "item",
        "id": "itm_Nensa0WB",
        "numeric_id": 148675,
        "pos_id": "20300009",
        "category_ids": [381],
        "name": "Strawberry Banana",
        "description": "",
        "price": 1.86,
        "meal": 0,
        "no_notes": false,
        "tags": ["frozen"],
        "option_groups": [{
          "name": "Choose your toppings",
          "options": [{
            "object": "option",
            "id": "itm_j9EsmnBn",
            "pos_id": "11274485",
            "name": "Whipped Cream",
            "price": 0.25,
            "type": "single",
            "default": false,
            "max_count": 0
          }, ...]
        }, ...]
      }, ...]
    }
  ]
}

Attribute	Type	Description
object	string	The object's type (menu).
location_id	string	ID of the location the item is in.
name	string	The name of the location.
timezone	string	The tz timezone of the location.
image	object	Contains url and url_small strings of image URLs. Both URL fields will be null if no image exists.
stations	collection	List of stations.

Station object

Attribute	Type	Description
object	string	The object's type (station).
id	string	ID of the station.
name	string	The name of the station.
description	string	The description of the station.
image	object	Contains url and url_small strings of image URLs. Both URL fields will be null if no image exists.
categories	collection	List of categories.
items	collection	List of items.

Category object

Attribute	Type	Description
object	string	The object's type (category).
id	string	ID of the category.
name	string	The name of the category.
description	string	The description of the category.
image	object	Contains url and url_small strings of image URLs. Both URL fields will be null if no image exists.

Item object

Attribute	Type	Description
object	string	The object's type (item).
id	string	ID of the category.
numeric_id	number	Numeric identifier for the item in the specific location.
pos_id	string	Optional ID that associates the item with an item on the local point of sale or client database.
category_ids	number[]	List of category IDs the item belongs to.
name	string	The name of the item.
description	string	The description of the item.
price	number	Price of the item.
meal	number	ID of the meal the item belongs to. 0 if all meals.
no_notes	boolean	Whether the item allows custom notes.
tags	string[]	List of tag names associated with the item.
option_groups	collection	List of option groups for the item.
option_groups.name	string	Name/instructions for the option group.
option_groups.options	collection	Options in the group.

Option object

Attribute	Type	Description
object	string	The object's type (option).
id	string	ID of the option item.
pos_id	string	Optional local ID for item.
name	string	Name of the option.
price	number	Price of the option.
type	string	Type of option: "single" = Select only one. "multi" = Select multiple. "N_free" = Select multiple with N options free.
default	boolean	Whether the option is selected by default.
max_count	number	The maximum amount of the option that can be added. If 0, multiple options can't be selected.

Get menu

Example Request

curl https://graph.mashgin.com/v1/locations/{ID}/menu \
    -u {API_KEY}:

Example Response

{
  "object": "menu",
  "location_id": "loc_ac85m",
  "name": "Bluth's Original Frozen Banana Stand",
  "timezone": "America/Los_Angeles",
  "image": {
    "url_small": "https://order.mashgin.com/mash.api-images/sample_small.jpg",
    "url": "https://order.mashgin.com/mash.api-images/sample.jpg"
  },
  "stations": [
    {
      "object": "station",
      "id": 373,
      "name": "Main Menu",
      "description": "",
      "image": {
        "url_small": null,
        "url": null
      },
      "categories": [{
        "object": "category",
        "id": 381,
        "name": "Frozen Treats",
        "description": "",
        "image": {
          "url_small": null,
          "url": null
        }
      }],
      "items": [{
        "object": "item",
        "id": "itm_Nensa0WB",
        "numeric_id": 148675,
        "pos_id": "20300009",
        "category_ids": [381],
        "name": "Strawberry Banana",
        "description": "",
        "price": 1.86,
        "meal": 0,
        "no_notes": false,
        "tags": ["frozen"],
        "option_groups": [{
          "name": "Choose your toppings",
          "options": [{
            "object": "option",
            "id": "itm_j9EsmnBn",
            "pos_id": "11274485",
            "name": "Whipped Cream",
            "price": 0.25,
            "type": "single",
            "default": false,
            "max_count": 0
          }]
        }]
      }]
    }
  ]
}

Returns a the menu object for a location.

HTTP Request

GET /v1/locations/{ID}/menu

URL Parameters

Parameter	Description
ID	The ID of the location to retrieve the items from.

Discounts

Discount object

Example Response

{
  "id": "disc_42",
  "object": "discount",
  "location_id": "loc_1bpuY",
  "discount_type": "combo",
  "name": "Sandwich Combo",
  "ref": null,
  "details": {
    "total_amount": 2,
    "items": [[...], [...]]
  }
}

Attribute	Type	Description
id	string	Unique identifier for the object.
object	string	The object's type (discount).
location_id	string	ID of the discount's location.
discount_type	string	Type of the discount: either combo for an item combo, or global_percentage for a transaction-wide percentage discount.
name	string	Name of the discount to be displayed to customer.
ref	string	Client reference string if it exists.
details	object	Details of the discount according to the discount type.

All discounts

Example Request

curl 'https://graph.mashgin.com/v1/discounts' \
    -u {API_KEY}:

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "disc_42",
      "object": "discount",
      "location_id": "loc_1bpuY",
      "discount_type": "combo",
      "name": "Sandwich Combo",
      "ref": "556DFGDFFR75",
      "details": {
        "total_amount": 2,
        "items": [[...], [...]]
      }
    },
    ...
  ]
}

Returns a list of all discounts for your group.

HTTP Request

GET /v1/discounts

Location discounts

Example Request

curl 'https://graph.mashgin.com/v1/locations/{ID}/discounts' \
    -u {API_KEY}:

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "disc_42",
      "object": "discount",
      "location_id": "loc_1bpuY",
      "discount_type": "combo",
      "name": "Sandwich Combo",
      "ref": "556DFGDFFR75",
      "details": {
        "total_amount": 2,
        "items": [[...], [...]]
      }
    },
    ...
  ]
}

Returns a list of all discounts at the location.

HTTP Request

GET /v1/locations/{ID}/discounts

URL Parameters

Parameter	Description
ID	The ID of the location to fetch discounts.

Get a discount

Example Request

curl https://graph.mashgin.com/v1/discounts/{ID} \
    -u {API_KEY}:

Example Response

{
  "id": "disc_42",
  "object": "discount",
  "location_id": "loc_aGBqk",
  "discount_type": "global_percentage",
  "name": "Employee discount",
  "ref": "556DFGDFFR75",
  "details": {
    "percent_off": 25,
    "regexp": ".*"
  }
}

Returns an individual discount.

HTTP Request

GET /v1/discounts/{ID}

URL Parameters

Parameter	Description
ID	The ID of the discount to be retrieved.

Kiosks

Kiosk object

Example Response

{
  "id": "ksk_lr78k",
  "object": "kiosk",
  "type": "kiosk",
  "name": "Jack Rabbit Slims #1",
  "numeric_id": 15,
  "location_id": "loc_jG2kD",
  "location_name": "Jack Rabbit Slims"
}

Attribute	Type	Description
id	string	Unique identifier for the object.
object	string	The object's type (kiosk).
type	string	The type of kiosk: kiosk: Place and pay kiosk. wave: Pass-through wave kiosk. order: Custom order station.
name	string	The name of the kiosk.
numeric_id	number	Numeric identifier for the kiosk.
location_id	string	ID of the location the kiosk is in.
location_name	string	The name of the location the kiosk is in.

List all kiosks

Example Request

curl https://graph.mashgin.com/v1/kiosks \
    -u {API_KEY}:

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "ksk_39o6z",
      "object": "kiosk",
      "type": "order",
      "name": "Frozen Banana Order Station",
      "location_id": "loc_ac85m",
      "location_name": "Bluth's Original Frozen Banana Stand"
    },
    ...
  ]
}

Returns a list of all kiosks.

HTTP Request

GET /v1/kiosks

List kiosks in location

Example Request

curl https://graph.mashgin.com/v1/locations/{ID}/kiosks \
    -u {API_KEY}:

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "ksk_lr78k",
      "object": "kiosk",
      "type": "kiosk",
      "name": "Jack Rabbit Slims #1",
      "location_id": "loc_jG2kD",
      "location_name": "Jack Rabbit Slims"
    },
    ...
  ]
}

Returns a list of all kiosks in a location.

HTTP Request

GET /v1/locations/{ID}/kiosks

URL Parameters

Parameter	Description
ID	The ID of the location to retrieve the items from.

Tender Types

Tender type object

{
  "id": "tdt_18",
  "object": "tender_type",
  "type": "card_amex",
  "service": "freedompay",
  "method": "credit_card",
  "card_type": "amex"
}

Attribute	Type	Description
id	string	Unique identifier for the object.
object	string	The object's type (tender_type).
type	string	Slug of the tender type (can be shared among multiple tender types)
service	string	Payment service or processor
method	string	Method of payment
card_type	string	Type of credit card (or "other")

All tender types

Example Request

curl 'https://graph.mashgin.com/v1/tenderTypes' \
    -u {API_KEY}:

Example Response

{
  "object": "list",
  "total_count": 35,
  "data": [
    {
      "id": "tdt_1",
      "object": "tender_type",
      "type": "card_amex",
      "service": "braintree",
      "method": "credit_card",
      "card_type": "amex"
    },
    ...
  ]
}

Returns a list of all tender types.

HTTP Request

GET /v1/tenderTypes