NakPOS Documentation

Overview

Base URL

All API requests should be made to:

https://pos.itglonline.com/api/v1

Authentication

Use Laravel Sanctum Bearer tokens. Include in all requests:

Authorization: Bearer {token}

Content Type

All requests and responses use JSON format:

Content-Type: application/json
Accept: application/json

Rate Limiting

Default limits per endpoint type:

Standard: 60/min
POS lookups: 120/min
Bulk operations: 10/min

Response Format

All API responses follow a consistent structure:

Success Response 
{
    "success": true,
    "data": { "...response data..." },
    "meta": { "...pagination info (if applicable)..." }
}
Error Response 
{
    "success": false,
    "message": "Error description",
    "errors": { "...validation errors (if applicable)..." }
}

Authentication

Authentication basics for API consumers.

POST /auth/login User Login
5/minute

Authenticate a user and receive an access token for API requests.

Request Parameters
Parameter Type Description
email *required string User email address
password *required string User password
device_name string Device identifier (default: "Mobile POS")
store_id integer Store to login to
two_factor_code string 2FA code if enabled
Example Request
JSON 
{
    "email": "cashier@store.com",
    "password": "secret123",
    "device_name": "iPhone 15 Pro",
    "store_id": 1
}
Example Response
JSON 
{
    "success": true,
    "data": {
        "token": "1|abc123xyz...",
        "user": {
            "id": 1,
            "name": "John Doe",
            "email": "cashier@store.com",
            "role": {
                "id": 2,
                "name": "Cashier",
                "slug": "cashier"
            },
            "store_id": 1,
            "store_name": "Main Store",
            "is_super_admin": false,
            "has_two_factor": false
        },
        "permissions": [
            "pos.access",
            "sales.view",
            "customers.view"
        ],
        "store_id": 1
    }
}
GET /auth/me Get Current User
Auth

Retrieve the authenticated user profile, permissions, and discount limits.

Example Response
JSON 
{
    "success": true,
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "cashier@store.com",
        "role": {
            "id": 2,
            "name": "Cashier"
        },
        "store_id": 1,
        "permissions": [
            "pos.access",
            "sales.view"
        ],
        "discount_limits": {
            "max_discount_percent": 15,
            "max_discount_amount": 500
        }
    }
}

Integrations & Webhooks

Public integration consumer endpoints and outbound webhook signature contract. Webhook headers: X-NakPOS-Event, X-NakPOS-Timestamp, X-NakPOS-Signature, X-NakPOS-Delivery-Id. Signature: HMAC SHA-256 over "timestamp.raw_body".

GET /integration/sales Integration Sales Feed
Auth

Read-only sales export feed for API application users. Requires auth:sanctum + api.application + permission:sales.view + token ability integration:read. Alias path: /integrations/sales.

Request Parameters
Parameter Type Description
from date Start date (YYYY-MM-DD)
to date End date (YYYY-MM-DD)
date_from date Alias of from
date_to date Alias of to
status string Sale status
store_id integer Filter by store
warehouse_id integer Filter by warehouse
q string Search receipt/barcode/reference
per_page integer Items per page (default: 50, max: 200)
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 123,
            "receipt_number": "RCP-20260212-0001",
            "store": {
                "id": 1,
                "name": "Main Store"
            },
            "warehouse": {
                "id": 2,
                "name": "Main Sales Floor"
            },
            "status": "completed",
            "total_amount": 1074.99,
            "created_at": "2026-02-12T10: 30: 00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 10,
        "per_page": 50,
        "total": 500
    }
}
GET /integration/sales/{sale} Integration Sale Details
Auth

Get one sale with full store/warehouse context for downstream ingestion. Requires auth:sanctum + api.application + permission:sales.view + token ability integration:read. Alias path: /integrations/sales/{sale}.

Example Response
JSON 
{
    "success": true,
    "data": {
        "id": 123,
        "receipt_number": "RCP-20260212-0001",
        "store": {
            "id": 1,
            "name": "Main Store"
        },
        "warehouse": {
            "id": 2,
            "name": "Main Sales Floor"
        },
        "items": [
            "...line items..."
        ],
        "payments": [
            "...payment lines..."
        ],
        "status": "completed"
    }
}
GET /integration/reports/overview Integration Report: Overview
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.view. Alias path: /integrations/reports/overview.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/sales Integration Report: Sales
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/sales.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/discounts Integration Report: Discounts
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/discounts.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/returns Integration Report: Returns
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/returns.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/closeout Integration Report: Closeout
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/closeout.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/profit Integration Report: Profit
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.profit. Alias path: /integrations/reports/profit.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/products Integration Report: Products
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.inventory. Alias path: /integrations/reports/products.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/products/abc Integration Report: Product ABC
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.inventory. Alias path: /integrations/reports/products/abc.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/customers Integration Report: Customers
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.customers. Alias path: /integrations/reports/customers.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/payments Integration Report: Payments
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.payments. Alias path: /integrations/reports/payments.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/stores Integration Report: Stores
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.stores. Alias path: /integrations/reports/stores.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/tax Integration Report: Tax
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.tax. Alias path: /integrations/reports/tax.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/invoices Integration Report: Invoices
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/invoices.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/invoices/aging Integration Report: Invoice Aging
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/invoices/aging.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/invoices/dso Integration Report: Invoice DSO
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/invoices/dso.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/invoices/credit-notes Integration Report: Invoice Credit Notes
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/invoices/credit-notes.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/invoices/funnel Integration Report: Invoice Funnel
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/invoices/funnel.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/revenue Integration Report: Revenue
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/revenue.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/heatmap Integration Report: Heatmap
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/heatmap.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/voids Integration Report: Voids
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/voids.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/return-rate Integration Report: Return Rate
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/return-rate.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/price-source Integration Report: Price Source
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.inventory. Alias path: /integrations/reports/price-source.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/cashier Integration Report: Cashier
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/cashier.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/cashier/{cashier} Integration Report: Cashier Detail
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:reports.sales. Alias path: /integrations/reports/cashier/{cashier}.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/inventory/overview Integration Inventory Report: Overview
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:inventory.reports. Alias path: /integrations/reports/inventory/overview.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/inventory/stock Integration Inventory Report: Stock
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:inventory.reports. Alias path: /integrations/reports/inventory/stock.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/inventory/movement Integration Inventory Report: Movement
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:inventory.reports. Alias path: /integrations/reports/inventory/movement.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/inventory/valuation Integration Inventory Report: Valuation
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:inventory.reports. Alias path: /integrations/reports/inventory/valuation.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/inventory/replenishment Integration Inventory Report: Replenishment
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:inventory.reports. Alias path: /integrations/reports/inventory/replenishment.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/inventory/turns Integration Inventory Report: Turns
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:inventory.reports. Alias path: /integrations/reports/inventory/turns.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/inventory/dead-stock Integration Inventory Report: Dead Stock
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:inventory.reports. Alias path: /integrations/reports/inventory/dead-stock.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/reports/inventory/damage-spoilage Integration Inventory Report: Damage & Spoilage
Auth

JSON report payload for application-user integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:inventory.reports. Alias path: /integrations/reports/inventory/damage-spoilage.

Request Parameters
Parameter Type Description
date_from date Start date (report convention)
date_to date End date (report convention)
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
Example Response
JSON 
{
    "success": true,
    "data": {
        "summary": [
            "...aggregates..."
        ],
        "rows": [
            "...report rows..."
        ],
        "charts": [
            "...optional chart payloads..."
        ]
    },
    "meta": {
        "filters": {
            "date_from": "2026-02-01",
            "date_to": "2026-02-29"
        },
        "generated_at": "2026-03-03T10: 00: 00Z"
    }
}
GET /integration/data/sales Integration Data: Sales
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:sales.view. Alias path: /integrations/data/sales.

Request Parameters
Parameter Type Description
from date Start date
to date End date
date_from date Alias of from
date_to date Alias of to
store_id integer Filter by store
warehouse_id integer Filter by warehouse
q string Search receipt/barcode/reference
per_page integer Items per page (default: 50)
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 1,
            "...row_fields...": "..."
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 50,
        "total": 1
    }
}
GET /integration/data/sales/{sale} Integration Data: Sale Detail
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:sales.view. Alias path: /integrations/data/sales/{sale}.

Example Response
JSON 
{
    "success": true,
    "data": {
        "id": 1,
        "...detail_fields...": "..."
    }
}
GET /integration/data/items Integration Data: Items
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:items.view. Alias path: /integrations/data/items.

Request Parameters
Parameter Type Description
q string Search name/SKU/barcode
is_active boolean Filter active/inactive
per_page integer Items per page (default: 50)
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 1,
            "...row_fields...": "..."
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 50,
        "total": 1
    }
}
GET /integration/data/customers Integration Data: Customers
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:customers.view. Alias path: /integrations/data/customers.

Request Parameters
Parameter Type Description
q string Customer search
exclude_walk_in boolean Default true
per_page integer Items per page (default: 50)
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 1,
            "...row_fields...": "..."
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 50,
        "total": 1
    }
}
GET /integration/data/customers/{customer} Integration Data: Customer Detail
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:customers.view. Alias path: /integrations/data/customers/{customer}.

Example Response
JSON 
{
    "success": true,
    "data": {
        "id": 1,
        "...detail_fields...": "..."
    }
}
GET /integration/data/invoices Integration Data: Invoices
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:invoices.view. Alias path: /integrations/data/invoices.

Request Parameters
Parameter Type Description
date_from date Start date
date_to date End date
store_id integer Store filter
warehouse_id integer Warehouse filter
status string Invoice status
q string Search invoice/notes
per_page integer Items per page (default: 50)
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 1,
            "...row_fields...": "..."
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 50,
        "total": 1
    }
}
GET /integration/data/invoices/{invoice} Integration Data: Invoice Detail
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:invoices.view. Alias path: /integrations/data/invoices/{invoice}.

Example Response
JSON 
{
    "success": true,
    "data": {
        "id": 1,
        "...detail_fields...": "..."
    }
}
GET /integration/data/returns Integration Data: Returns
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:returns.view. Alias path: /integrations/data/returns.

Request Parameters
Parameter Type Description
date_from date Start date
date_to date End date
store_id integer Store filter
warehouse_id integer Warehouse filter
status string Return status
per_page integer Items per page (default: 50)
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 1,
            "...row_fields...": "..."
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 50,
        "total": 1
    }
}
GET /integration/data/returns/{saleReturn} Integration Data: Return Detail
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:returns.view. Alias path: /integrations/data/returns/{saleReturn}.

Example Response
JSON 
{
    "success": true,
    "data": {
        "id": 1,
        "...detail_fields...": "..."
    }
}
GET /integration/data/stores Integration Data: Stores
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:stores.view. Alias path: /integrations/data/stores.

Request Parameters
Parameter Type Description
with_warehouses boolean Include active warehouses
per_page integer Items per page (default: 50)
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 1,
            "...row_fields...": "..."
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 50,
        "total": 1
    }
}
GET /integration/data/stores/{store} Integration Data: Store Detail
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:stores.view. Alias path: /integrations/data/stores/{store}.

Example Response
JSON 
{
    "success": true,
    "data": {
        "id": 1,
        "...detail_fields...": "..."
    }
}
GET /integration/data/warehouses Integration Data: Warehouses
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:warehouses.view. Alias path: /integrations/data/warehouses.

Request Parameters
Parameter Type Description
store_id integer Filter by store
standalone_only boolean Only standalone warehouses
per_page integer Items per page (default: 50)
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 1,
            "...row_fields...": "..."
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 50,
        "total": 1
    }
}
GET /integration/data/warehouses/{warehouse} Integration Data: Warehouse Detail
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:warehouses.view. Alias path: /integrations/data/warehouses/{warehouse}.

Example Response
JSON 
{
    "success": true,
    "data": {
        "id": 1,
        "...detail_fields...": "..."
    }
}
GET /integration/data/inventory Integration Data: Inventory Snapshot
Auth

JSON core data endpoint for integrations. Requires auth:sanctum + api.application + token ability integration:read + permission:inventory.view. Alias path: /integrations/data/inventory.

Request Parameters
Parameter Type Description
store_id integer Filter by store
warehouse_id integer Filter by warehouse
item_id integer Filter by item
stock_status string out | low | in_stock
per_page integer Items per page (default: 50)
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 1,
            "...row_fields...": "..."
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 50,
        "total": 1
    }
}

Reporting

Build read-only reports from integration sales feeds. Use created_at consistently for time windows, group with store/warehouse objects, and handle nullable warehouse values.

GET /integration/sales Daily Summary Pull (By Status)
Auth

Pull daily sales for status-based reporting. Alias path: /integrations/sales. Use this for daily totals and status rollups.

Request Parameters
Parameter Type Description
from date Start date (YYYY-MM-DD)
to date End date (YYYY-MM-DD)
status string Sale status filter for report slices
store_id integer Optional store filter
warehouse_id integer Optional warehouse filter
q string Free-text search on receipt/barcode/reference
per_page integer Items per page (default: 50, max: 200)
Example Request
JSON 
{
    "from": "2026-02-11",
    "to": "2026-02-11",
    "status": "completed",
    "per_page": 200
}
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 901,
            "receipt_number": "RCP-20260211-0001",
            "status": "completed",
            "store": {
                "id": 1,
                "name": "Main Store"
            },
            "warehouse": {
                "id": 2,
                "name": "Sales Floor"
            },
            "total_amount": 245,
            "created_at": "2026-02-11T09: 15: 00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 3,
        "per_page": 200,
        "total": 467
    }
}
GET /integration/sales Store Rollup Pull
Auth

Filter by store_id and aggregate totals externally for store-level performance reporting.

Request Parameters
Parameter Type Description
store_id *required integer Store ID for rollup
from date Start date
to date End date
per_page integer Items per page for batching
Example Request
JSON 
{
    "store_id": 1,
    "from": "2026-02-01",
    "to": "2026-02-12",
    "per_page": 100
}
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 950,
            "receipt_number": "RCP-20260212-0212",
            "store": {
                "id": 1,
                "name": "Main Store"
            },
            "warehouse": {
                "id": 2,
                "name": "Sales Floor"
            },
            "status": "completed",
            "total_amount": 1080,
            "created_at": "2026-02-12T17: 40: 00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 6,
        "per_page": 100,
        "total": 581
    }
}
GET /integration/sales Warehouse Rollup Pull
Auth

Filter by warehouse_id for warehouse-level reporting. Warehouses can be null on some sales, so account for uncategorized rows.

Request Parameters
Parameter Type Description
warehouse_id *required integer Warehouse ID for grouping
from date Start date
to date End date
status string Optional status filter
per_page integer Items per page for batching
Example Request
JSON 
{
    "warehouse_id": 2,
    "from": "2026-02-01",
    "to": "2026-02-12",
    "status": "completed"
}
Example Response
JSON 
{
    "success": true,
    "data": [
        {
            "id": 997,
            "receipt_number": "RCP-20260212-0301",
            "store": {
                "id": 1,
                "name": "Main Store"
            },
            "warehouse": {
                "id": 2,
                "name": "Sales Floor"
            },
            "status": "completed",
            "total_amount": 320.5,
            "created_at": "2026-02-12T19: 02: 00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 2,
        "per_page": 50,
        "total": 95
    }
}
GET /integration/sales/{sale} Incremental Sync Drilldown
Auth

Use sale detail lookups to reconcile line items/payments for records flagged during incremental reporting syncs.

Example Response
JSON 
{
    "success": true,
    "data": {
        "id": 997,
        "receipt_number": "RCP-20260212-0301",
        "store": {
            "id": 1,
            "name": "Main Store"
        },
        "warehouse": {
            "id": 2,
            "name": "Sales Floor"
        },
        "status": "completed",
        "items": [
            "...line items..."
        ],
        "payments": [
            "...payment lines..."
        ],
        "created_at": "2026-02-12T19: 02: 00Z"
    }
}

Error Handling

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:

Status Meaning Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request data or checkout validation error
401 Unauthorized Missing or invalid authentication token
403 Forbidden User lacks permission for this action
404 Not Found Resource not found
409 Conflict Conflict (e.g., duplicate session)
422 Unprocessable Entity Validation errors in request data
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error

Validation Error Response

When validation fails (422), the response includes field-specific errors:

422 Validation Error 
{
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
        "email": ["The email field is required."],
        "password": ["The password must be at least 8 characters."]
    }
}