Skip to main content
The Sales API provides endpoints for processing sales transactions, retrieving sales history, and accessing analytics and reporting data.

​
Get sales

Retrieve completed sales transactions. 
GET /api/sales

​
Query parameters

​
days
integer
Filter sales from the last N days

​
Response

Returns an array of sale objects with employee and item details.
​
id
integer
Unique sale identifier
​
transactionId
string
Unique transaction ID (format: TXN-YYYYMMDD-XXXXXXXX)
​
employeeId
integer
ID of employee who processed the sale
​
saleDate
string
ISO 8601 timestamp of sale
​
subtotal
decimal
Subtotal before tax and discounts
​
taxRate
decimal
Tax rate percentage applied
​
taxAmount
decimal
Tax amount calculated
​
discountAmount
decimal
Discount amount applied
​
discountReason
string
Reason for discount
​
total
decimal
Total amount after tax and discounts
​
amountPaid
decimal
Amount paid by customer
​
change
decimal
Change given to customer
​
paymentMethod
string
Payment method (Cash, Card, etc.)
​
status
string
Sale status (Completed, Voided, Refunded)
​
saleItems
array
Array of items in the sale

​
Example request

curl -X GET "https://api.example.com/api/sales?days=7" \
  -H "Content-Type: application/json"

​
Get sale by ID

Retrieve details of a specific sale. 
GET /api/sales/{id}

​
Path parameters

​
id
integer
required
Sale ID

​
Create sale

Process a new sales transaction. 
POST /api/sales

​
Request body

​
employeeId
integer
required
ID of employee processing the sale
​
subtotal
decimal
required
Subtotal amount
​
taxRate
decimal
required
Tax rate percentage
​
taxAmount
decimal
required
Tax amount
​
discountAmount
decimal
default:"0"
Discount amount
​
discountReason
string
Reason for discount
​
total
decimal
required
Total amount
​
amountPaid
decimal
required
Amount paid by customer
​
change
decimal
required
Change to give customer
​
paymentMethod
string
default:"Cash"
Payment method
​
notes
string
Additional notes
​
items
array
required
Array of sale items

​
Sale item structure

​
productId
integer
required
Product ID
​
quantity
integer
required
Quantity sold
​
unitPrice
decimal
required
Price per unit
​
lineTotal
decimal
required
Total for this line item

​
Example request

curl -X POST "https://api.example.com/api/sales" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": 2,
    "subtotal": 49.98,
    "taxRate": 10,
    "taxAmount": 5.00,
    "discountAmount": 0,
    "total": 54.98,
    "amountPaid": 60.00,
    "change": 5.02,
    "paymentMethod": "Cash",
    "items": [
      {
        "productId": 5,
        "quantity": 2,
        "unitPrice": 24.99,
        "lineTotal": 49.98
      }
    ]
  }'

​
Validation

  • Employee must exist
  • Products must exist and have sufficient stock
  • Stock is automatically reduced when sale is created

​
Response

Returns the complete sale object with generated transaction ID.

​
Today’s sales summary

Get a summary of all sales for the current day. 
GET /api/sales/today

​
Response

​
date
string
Date of the summary
​
totalSales
integer
Number of sales transactions
​
totalRevenue
decimal
Total revenue
​
totalTax
decimal
Total tax collected
​
totalDiscounts
decimal
Total discounts given
​
sales
array
Array of today’s sales

​
Example request

curl -X GET "https://api.example.com/api/sales/today" \
  -H "Content-Type: application/json"

​
This week’s summary

Get sales summary for the current week. 
GET /api/sales/this-week

​
Response

Returns aggregated sales data for the week (Monday through today).

​
This month’s summary

Get sales summary for the current month. 
GET /api/sales/this-month

​
Response

Returns aggregated sales data for the current calendar month.

​
Top products

Get the best-selling products for a time period. 
GET /api/sales/top-products

​
Query parameters

​
days
integer
default:"7"
Number of days to analyze

​
Response

​
productName
string
Product name
​
totalQuantitySold
integer
Total units sold
​
totalRevenue
decimal
Total revenue generated
​
transactionCount
integer
Number of transactions

​
Example request

curl -X GET "https://api.example.com/api/sales/top-products?days=30" \
  -H "Content-Type: application/json"

​
Payment breakdown

Get breakdown of sales by payment method. 
GET /api/sales/payment-breakdown

​
Query parameters

​
period
string
default:"today"
Time period: today, week, or month

​
Response

​
period
string
Period label
​
paymentMethods
array
Array of payment method summaries

​
Example request

curl -X GET "https://api.example.com/api/sales/payment-breakdown?period=week" \
  -H "Content-Type: application/json"

​
Tax summary

Get tax collection summary for reporting. 
GET /api/sales/tax-summary

​
Query parameters

​
period
string
default:"month"
Time period: week, month, or year

​
Response

​
period
string
Period label
​
totalSales
integer
Number of sales
​
totalRevenue
decimal
Total revenue
​
totalTaxCollected
decimal
Total tax collected
​
averageTaxRate
decimal
Average tax rate applied

​
Employee performance

Get sales performance by employee. 
GET /api/sales/employee-performance

​
Query parameters

​
period
string
default:"month"
Time period: today, week, or month

​
Response

​
employeeName
string
Employee name
​
totalSales
integer
Number of sales processed
​
totalRevenue
decimal
Total revenue generated
​
averageTransactionValue
decimal
Average sale amount

​
Example request

curl -X GET "https://api.example.com/api/sales/employee-performance?period=month" \
  -H "Content-Type: application/json"

Build docs developers (and LLMs) love

Get started for freeTalk to us