This guide documents the public API endpoints used to synchronize products and inventory, manage customers and rewards, retrieve event and news content, access orders, and work with vendor drop-ship data. Each section includes the request method, URL, authentication requirements, supported fields, and practical examples suitable for partner integrations.
API Overview
All examples use the placeholder domain below. Replace YOUR_URL with the hostname provided for your RunFree site or integration environment.
Authentication
Unless otherwise noted, API requests must include a Bearer Token. The token identifies and authorizes the integration for the appropriate site.
Authorization: Bearer YOUR_API_TOKEN |
For requests that send JSON, also include:
Content-Type: application/json |
Common Responses
403 Not Authorized: The Bearer Token is missing or not valid for the site.
500 Server error: The request could not be completed because of an internal or database error.
Some lookup endpoints return an empty JSON object when a matching record is not found.
Products & Inventory
Update Product Inventory
Updates the current inventory quantity for a product at a store. Products can be identified by UPC, product ID, SKU, or a combination of SKU and variation fields such as size and width.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
quantity | JSON body | Yes | Current quantity to store for the matching inventory record. |
store | JSON body | Recommended | Store code or store identifier for the inventory location. |
upc | JSON body | Conditional | UPC used to identify the product or variation. |
productId | JSON body | Conditional | Internal product ID. |
sku | JSON body | Conditional | Product SKU. |
size | JSON body | No | Variation size, useful when SKU is shared by multiple variations. |
width | JSON body | No | Variation width. |
posId | JSON body | No | External/POS integration identifier. |
Example Request Body
{ |
Example Response
{ |
Notes
At least one useful product identifier must be supplied so the backend can locate the correct inventory record.
The API sets the inventory total to the quantity provided; it does not add the quantity to the existing amount.
SKU, size, and width can be used together when a UPC is unavailable.
Error Handling
If quantity is omitted, the API returns: {"error":"Missing required field: quantity"}.
Import or Update a Product
Imports product and inventory data. This endpoint is useful for creating or updating catalog items from an external POS, ERP, vendor feed, or product database.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
Sku | JSON body | Conditional | Product SKU. |
Upc | JSON body | Conditional | Product UPC. |
Name | JSON body | No | Product name. |
Description | JSON body | No | Product description. |
Price | JSON body | No | Selling price; dollar signs are accepted. |
Msrp | JSON body | No | MSRP; dollar signs are accepted. |
Size | JSON body | No | Product variation size; limited to 50 characters. |
Width | JSON body | No | Product variation width; limited to 50 characters. |
Store | JSON body | No | Store code; limited to 50 characters. |
Image1, Image2, Image3, ... | JSON body | No | Image fields. Values may be an existing /assets/... path or a remote HTTP/HTTPS URL. |
Example Request Body
{ |
Notes
Properties beginning with Image are treated as product images by the API.
Remote image URLs are downloaded into the product asset library during import.
Most non-description string fields are limited to 100 characters by the import handler.
Get Product by Product ID
Returns a product and its associated inventory records using the internal product ID.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Internal product ID. |
Example Response
{ |
Notes
The API formats price and MSRP with two decimal places.
Site-specific internal fields are removed from the public response.
Get Product by UPC
Returns a product and its inventory using a UPC value.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
upc | URL path | Yes | UPC to locate. |
Example Response
{ |
Get Product by SKU
Returns a product and its inventory using the product SKU.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
sku | URL path | Yes | SKU to locate. |
Example Response
{ |
Vendor / Drop-Ship
Update Drop-Ship Product
Creates or updates a vendor drop-ship product and its inventory. This endpoint uses the integration token to determine which vendor/brand is authorized to submit the product.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
sku | JSON body | Yes | Vendor SKU. |
name | JSON body | No | Product name. |
color | JSON body | No | Color. |
description | JSON body | No | Description. |
price | JSON body | No | Vendor cost. |
gender | JSON body | No | Gender/category value. |
size | JSON body | No | Variation size. |
width | JSON body | No | Variation width. |
upc | JSON body | No | UPC. |
qty | JSON body | No | Available quantity. |
image1 through image6 | JSON body | No | Remote image URLs. Up to six image fields are explicitly supported by this endpoint. |
Example Request Body
{ |
Example Response
{ |
Notes
This endpoint explicitly supports image1 through image6.
Images are downloaded and saved locally when they do not already exist.
Get Drop-Ship Product by SKU
Returns vendor drop-ship product information, image URLs, and inventory for the specified SKU.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
sku | URL path | Yes | Vendor SKU. |
Example Response
{ |
Error Handling
Invalid vendor token returns {"error":"Invalid Token"}.
Unknown SKU returns {"error":"Product Not Found"}.
Customers
List Customers
Returns a paginated list of customers for the authenticated site. Results can be filtered by customer name or email and sorted using supported fields.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
page | Query string | No | Page number. Defaults to 1. |
total | Query string | No | Rows per page. Maximum 100. |
sort | Query string | No | Sort field. Defaults to customerId. |
sortType | Query string | No | ASC or DESC. Defaults to DESC. |
filter | Query string | No | Searches first name, last name, and email address. |
Example Request URL
Example Response
{ |
Get Customer
Returns a single customer, including related orders and event check-ins.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Customer ID. |
onlineOnly | Query string | No | Set to true or 1 to only include orders where isInStore=0. |
Example Request URL
Example Response
{ |
Notes
· Orders include decorated items and shipment information.
Update Customer Details
Creates or updates API customer details using the customer email address as the primary supplied identity field.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
emailAddress | JSON body | Yes | Customer email address. |
externalId | JSON body | No | External/POS customer identifier. |
firstName | JSON body | No | First name. |
lastName | JSON body | No | Last name. |
phone | JSON body | No | Phone number. |
password | JSON body | No | Customer password. The server stores an MD5 hash of this value. |
birthDate | JSON body | No | Birth date value. |
Example Request Body
{ |
Get Customer Devices
Returns devices registered to a customer, such as devices used by applications or push-notification integrations.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Customer ID. |
Example Response
{ |
Customer Rewards
Get Customer Rewards
Returns rewards activity for a customer. An optional sinceDate can be used to request only newer reward records.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Customer ID. |
sinceDate | Query string | No | Only return reward data from this date forward when the date is valid. |
Example Request URL
Add Reward Adjustment
Adds a manual reward-point adjustment for a customer.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Customer ID. |
points | JSON body | Yes | Number of points in the adjustment. |
info | JSON body | Yes | Description or reason for the adjustment. |
Example Request Body
{ |
Delete Reward Adjustment
Deletes a specific reward adjustment belonging to a customer.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Customer ID. |
rewardId | URL path | Yes | Reward record ID to delete. |
Example Response
{ |
Events
List Events
Returns a paginated list of events, including location data and attendee counts.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
page | Query string | No | Page number. Defaults to 1. |
total | Query string | No | Rows per page. Maximum 100. |
sort | Query string | No | Sort field. Defaults to dateOccurs. |
sortType | Query string | No | ASC or DESC. Defaults to DESC. |
status | Query string | No | Use future for upcoming events or past for historical events. |
sinceDate | Query string | No | Only include events occurring on or after this date. |
Example Request URL
Example Response
{ |
Get Event
Returns a single event with its address/location data and attendee count.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Event ID. |
Example Response
{ |
Get Event Attendees
Returns customers checked into an event, ordered by check-in date descending.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Event ID. |
page | Query string | No | Page number. |
total | Query string | No | Rows per page. Maximum 100. |
Example Request URL
Example Response
{ |
Check In Customer to Event
Checks a customer into an event.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Event ID. |
customerId | JSON body | Yes | Customer ID to check in. |
Example Request Body
{ |
Example Response
{ |
Error Handling
· If customerId is missing, the API returns HTTP 400 with {"error":"customerId is required"}.
News
List News
Returns active, non-expired news posts for the authenticated site.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
page | Query string | No | Page number. Defaults to 1. |
total | Query string | No | Rows per page. Maximum 100. |
sort | Query string | No | Sort field. Defaults to datePosted. |
sortType | Query string | No | ASC or DESC. Defaults to DESC. |
sinceDate | Query string | No | Only include posts published on or after this date. |
Example Request URL
Example Response
{ |
Get News Post by ID
Returns a single news post by ID.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | News post ID. |
Create or Update News Post
Creates or updates a news post through the API.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
newsId | JSON body | Conditional | News ID when updating an existing record. |
title | JSON body | No | Post title. |
contents | JSON body | No | Post body/HTML content. |
datePosted | JSON body | No | If supplied, must use MM/DD/YYYY hh:mm A format. |
expires | JSON body | No | Optional expiration date that must be parseable as a JavaScript Date. |
seoTitle | JSON body | No | SEO title. |
seoDescription | JSON body | No | SEO description. |
suppressPush | JSON body | No | true to suppress push notification behavior. |
Example Request Body
{ |
Error Handling
· Invalid datePosted returns {"errors":["DatePosted"]}.
· Invalid expires returns {"errors":["Expires"]}.
Upload News Image
Uploads an image for use with a news post. This request must use multipart/form-data rather than JSON.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
file | multipart/form-data | Yes | Image file. The multipart field name must be file. |
Example Response
{ |
Notes
· Do not manually set a JSON Content-Type for this request. Let your HTTP client generate the multipart boundary.
Error Handling
· If no file is sent, the API returns HTTP 400 with {"error":"No Files Sent"}.
Collections
Get Collections
Returns active, non-deleted collections for the authenticated site, ordered alphabetically by title.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Example Response
{ |
Orders
Get Order Detail
Returns detailed order information through the Orders.Detail handler.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Order ID. |
Notes
· The route is part of the public API, but the Orders.Detail handler implementation was not included in the supplied API handler file. Exact response fields should be documented from the Orders module before publishing a strict response schema.
Get API Order / Status
Returns a complete API order representation, including decorated order data, shipments, and line items.
Authentication
Include your API Bearer Token in the request headers:
Authorization: Bearer YOUR_API_TOKEN |
Request Fields and Parameters
Field | Location | Required | Description |
id | URL path | Yes | Positive integer order ID. |
Example Response
{ |
Error Handling
· Invalid or non-positive order IDs return HTTP 400 with {"error":"Invalid order id"}.
· Unknown order IDs return HTTP 404 with {"error":"Order Not Found"}.
Integration Best Practices
Store the Bearer Token securely and never expose it in browser-side JavaScript or public repositories.
· Use HTTPS for every API request.
· Treat inventory quantities as absolute stock totals unless your integration contract explicitly says otherwise.
· Use UPC when available for variation-level inventory. When UPC is not available, use SKU together with size and width where needed to identify a specific variation.
· Keep page sizes at 100 records or fewer for customers, events, and news.
· For remote product images, use stable publicly reachable HTTPS URLs so the server can download them successfully.
· Log both HTTP status codes and JSON response bodies in your integration so authentication, validation, and server failures can be distinguished quickly.
Endpoint Summary
Method | Endpoint | Purpose |
POST | /api/vendor | Update drop-ship product |
GET | /api/vendor/{sku} | Get drop-ship product |
GET | /api/customers | List customers |
GET | /api/customer/{id} | Get customer |
GET | /api/customer/{id}/rewards | Get customer rewards |
POST | /api/customer/{id}/reward | Add reward adjustment |
DELETE | /api/customer/{id}/reward/{rewardId} | Delete reward adjustment |
POST | /api/customer/details | Update customer details |
GET | /api/customer/{id}/devices | Get customer devices |
GET | /api/events | List events |
GET | /api/event/{id} | Get event |
GET | /api/event/{id}/attendees | Get event attendees |
POST | /api/event/{id}/checkin | Check in customer |
GET | /api/news | List news |
GET | /api/news/{id} | Get news by ID |
PUT | /api/news | Create/update news |
POST | /api/news/image | Upload news image |
GET | /api/collections | Get collections |
GET | /api/order/{id} | Get order detail |
GET | /api/order/{id}/status | Get API order/status |
POST | /api/product/inventory | Update inventory |
POST | /api/product/import | Import/update product |
GET | /api/product/{id} | Get product by ID |
GET | /api/product/upc/{upc} | Get product by UPC |
GET | /api/product/sku/{sku} | Get product by SKU |