Copy page

API Documentation

The Decimal API provides programmatic access to manage orders, products, invoices, customers, and sale records in your point-of-sale system. This RESTful API uses JSON for all requests and responses.

Base URL

Code
https://api.poswithlogic.dev

Authentication

All API requests require authentication using an API key in the request header:

Code
x-api-key: YOUR_API_KEY

Important: You can only access orders created with your API key, invoices generated from those orders, and customers associated with those orders. Products are globally accessible. Sale records (GET /salerecords) are limited to items on this key's permission list (GET /permissionlist). A key whose permission list is empty gets 403.

Example Request:

Code
curl -X GET https://api.poswithlogic.dev/products \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Permission Scopes

API access is controlled by permission scopes assigned to your API key. Each scope determines which endpoints and operations you can access.

Key Points:

• Requests without required scopes return 403 Forbidden
• Only store owners can modify API key permission scopes
• View and manage permissions in the API Keys section

Tip: If you receive 403 errors with valid authentication, verify your API key has the required scope for that endpoint.

Endpoint Scope Reference

The following table shows which scope is required for each API endpoint:

Additional Scopes

The following scopes are for actions not tied to specific API endpoints:

API Key Bundles

When creating an API key, you can choose a predefined bundle or configure custom scopes:

Customer PIN

A few endpoints touch customer money or payment instruments directly and require a second factor on top of your API key: the customer's PIN. This is a short numeric code (max 8 digits) that the customer has configured on their POS account. Your API key authenticates your application; the PIN authenticates the customer behind the request.

Send the PIN in the X-Customer-Pin request header:

Code
x-api-key: YOUR_API_KEY
X-Customer-Pin: 1234

When is the PIN required?

Endpoint	PIN Requirement
GET /customers/id/{id}/balance	Always
GET /customers/phonenumber/{phoneNumber}/balance	Always
POST /customers/id/{customerId}/charges	Always
POST /orders	Conditional — required when payment.method is OnAccount or when paying with a stored credit card (cardId). Not required for ad-hoc cash, food stamp, or temp-card payments.

Requests missing or failing the PIN check return 401 Unauthorized with an RFC 7807 problem detail.

Content Type

All requests and responses use application/json:

• Include Content-Type: application/json header in POST/PUT requests
• All responses return JSON format

Rate Limiting

The API implements rate limiting to ensure service stability. Exceeding the current limit returns a 429 Too Many Requests response.

Response Headers

When a request is throttled, the response includes a Retry-After header telling you how long to wait before retrying:

Header	Example	Description
Retry-After	Retry-After: 60	Number of seconds to wait before sending another request.

Example 429 Response:

Code
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/problem+json

{
  "type": "https://httpproblems.com/http-status/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You have exceeded the rate limit.",
  "instance": "/products"
}

Handling 429 Responses

Follow these steps when you receive a 429:

1. Read the Retry-After header to determine how many seconds to wait. It is returned in delay-seconds format (a whole number of seconds).
2. Pause before retrying. Wait at least the number of seconds indicated by Retry-After before sending the request again.
3. Use exponential backoff with jitter for repeated failures, so retries don't all fire at the same moment.
4. Avoid tight retry loops. Blindly retrying without honoring Retry-After will keep you throttled and may extend the block.

Example (JavaScript):

Code
async function requestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    // Honor Retry-After (in seconds); fall back to exponential backoff.
    const retryAfter = response.headers.get('Retry-After');
    const waitSeconds = retryAfter ? Number(retryAfter) : 2 ** attempt;
    const jitter = Math.random() * 0.5;

    await new Promise((resolve) => setTimeout(resolve, (waitSeconds + jitter) * 1000));
  }

  throw new Error('Rate limit retries exhausted');
}

Pagination

List endpoints (GET /products, GET /customers, GET /permissionlist, GET /salerecords) use cursor-based pagination.

• The total count is only on the first request (no cursor)
• GET /salerecords never includes total
• Use the cursor from the response to fetch the next page — do not invent or edit it
• Cursors expire after 1 minute — process pages promptly
• You must include all original query parameters (e.g., take, lastMod) alongside the cursor
• Stop when hasMore is false, or when no cursor is returned

Error Handling

The API uses standard HTTP status codes:

• 200 OK - Request succeeded
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Missing or invalid API key
• 403 Forbidden - Valid API key but insufficient permissions
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Error responses follow the RFC 7807 Problem Details format:

Code
{
  "type": "https://example.com/errors/invalid-parameters",
  "title": "Invalid Request Parameters",
  "status": 400,
  "detail": "The request contains invalid or missing parameters.",
  "instance": "/api/v1/users/123"
}

---

Understanding Orders vs Invoices

The Decimal system follows a structured workflow from order creation to completed transaction.

Order Lifecycle

1. Order Creation

Create an order via POST /orders to capture the customer's purchase intent:

• Represents items the customer wants to purchase
• Records quantities and prices
• Exists in a pre-checkout state
• No payment has been processed

2. Order Fulfillment

The order moves through fulfillment:

• Staff prepares the items for the customer
• Order is readied for checkout
• Remains in "order" status until payment

3. Checkout & Invoice Generation

At checkout, the order converts to an invoice:

• Invoice represents the completed transaction
• Payment processing is initiated
• Order transitions to paid/unpaid status based on payment result

Payment Webhook Requirement

The payment webhook is essential for automated payment processing and invoice completion.

Successful Payment Flow

1. Your webhook endpoint receives the payment request
2. You process the payment and respond with "accepted" status
3. Invoice is marked as paid
4. Order is released for fulfillment

Failure Scenarios

The invoice remains unpaid and requires manual processing if:

• No paymentEndpoint provided in order creation
• Webhook times out (>30 seconds)
• Webhook returns an error or non-200 status

Best Practice: Always include a paymentEndpoint in order requests to enable automated payment processing.

---

Endpoints

Orders

Note: You can only access orders created with your API key.

Create Order

Endpoint: POST /orders

Headers:

Header	Type	Required	Description
X-Customer-Pin	string (≤8)	Conditional	Customer PIN, required when paying OnAccount or with a stored card

Request Body:

See the Order schema in the Data Models section.

OrderMethod Values:

• Pickup
• Delivery

Response:

A successful order creation returns:

• Status Code: 201 Created
• Location Header: Contains the URL to retrieve the created order (e.g., /orders/id/15007763)

Example Response Headers:

Code
HTTP/1.1 201 Created
Location: /orders/id/15007763

Payment Processing Webhooks

Overview

Provide a payment webhook endpoint in your order creation request to receive payment processing notifications. Without a webhook, orders remain unpaid and require manual payment processing.

Webhook Configuration

Include the paymentEndpoint object in your order creation request:

Code
{
  "customer": { ... },
  "items": [ ... ],
  "paymentEndpoint": {
    "url": "https://your-domain.com/webhooks/payment",
    "headers": {
      "Authorization": "Bearer your-webhook-token"
    }
  }
}

Webhook Request

When checkout occurs, we send a POST request to your endpoint:

Endpoint: Your specified paymentEndpoint.url

Payment Method Values:

• CreditCard
• FoodStamps

Request Body:

Code
{
  "orderNumber": "15007763",
  "invoiceNumber": "990000000000",
  "externalOrderId": "ext-order-123",
  "totalAmountDue": 75.00,
  "charges": [
    {
      "paymentMethod": "CreditCard",
      "eligibleChargeAmount": 75.00
    },
    {
      "paymentMethod": "FoodStamps",
      "eligibleChargeAmount": 25.00
    }
  ]
}

Webhook Response

Your endpoint must respond with a 200 status code and the following structure:

Code
{
  "status": "accepted",
  "errorCode": null,
  "errorDescription": null,
  "errorShortDescription": null,
  "authorizationNumber": "10458088728",
  "orderNumber": "15007763",
  "invoiceNumber": "990000000000",
  "externalOrderId": "ext-order-123",
  "chargedDate": "2025-10-28T15:34:22.9324473+00:00",
  "payments": [
    {
      "paymentMethod": "CreditCard",
      "chargeAmount": 50.00,
      "paymentNumber": 1512,
      "reference": "10458088728",
      "errorDescription": null
    },
    {
      "paymentMethod": "FoodStamps",
      "chargeAmount": 25.00,
      "paymentNumber": 56585121,
      "reference": "1045808834",
      "errorDescription": null
    }
  ]
}

Status Values:

• accepted - Payment processed successfully
• rejected - Payment declined or failed

Failure Handling

• Webhook timeout: 30 seconds
• If webhook fails or times out, invoice remains unpaid and requires manual processing

Get Order by ID

Endpoint: GET /orders/id/{id}

Path Parameters:

Parameter	Type	Description
id	string	Internal order identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/orders/id/15007763 \
  -H "x-api-key: YOUR_API_KEY"

Get Order by External ID

Endpoint: GET /orders/external/{externalOrderId}

Path Parameters:

Parameter	Type	Description
externalOrderId	string	External order identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/orders/external/ext-order-123 \
  -H "x-api-key: YOUR_API_KEY"

---

Products

Get Products

Retrieve a paginated list of products with optional filtering. Results are sorted by product ID (ascending).

Endpoint: GET /products

Query Parameters:

Parameter	Type	Default	Description
take	integer	20	Records to return (max 100)
cursor	string	-	Cursor for pagination (returned from previous request)
lastMod	datetime	-	Filter by products updated since this date (ISO 8601)
lastSold	datetime	-	Filter by products sold since this date (ISO 8601)
includeInactive	boolean	false	Include inactive products in results

Example:

Code
curl -X GET "https://api.poswithlogic.dev/products?take=100&lastMod=2024-01-01T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"

Incremental Sync Pattern:

1. Store the lastMod timestamp from your previous sync
2. Use lastMod in subsequent requests to retrieve only modified products
3. Paginate through results using the cursor returned in the response
4. Include all original parameters (take, lastMod, etc.) with each cursor request
5. Continue until no cursor is returned

Example Workflow:

Code
# Initial sync — response includes total count
curl -X GET "https://api.poswithlogic.dev/products?take=100" \
  -H "x-api-key: YOUR_API_KEY"

# Store the latest lastMod timestamp (e.g., 2024-12-26T10:30:00Z)

# Subsequent sync — only modified products
curl -X GET "https://api.poswithlogic.dev/products?take=100&lastMod=2024-12-26T10:30:00Z" \
  -H "x-api-key: YOUR_API_KEY"

# Paginate — include all original params alongside cursor
curl -X GET "https://api.poswithlogic.dev/products?take=100&lastMod=2024-12-26T10:30:00Z&cursor=CURSOR_FROM_RESPONSE" \
  -H "x-api-key: YOUR_API_KEY"

Get Product by ID

Endpoint: GET /products/id/{id}

Path Parameters:

Parameter	Type	Description
id	string	Numeric product identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/products/id/12345 \
  -H "x-api-key: YOUR_API_KEY"

Get Product by Code

Endpoint: GET /products/code/{code}

Path Parameters:

Parameter	Type	Description
code	string	Product SKU or item code

Example:

Code
curl -X GET https://api.poswithlogic.dev/products/code/PROD001 \
  -H "x-api-key: YOUR_API_KEY"

Understanding Product Pricing

The priceQty Field

The priceQty field is a divisor that determines the actual unit price:

Code
Unit Price = price ÷ priceQty

Example:

• price: 10.00
• priceQty: 2
• Unit Price: $5.00

Common Use Cases:

• Bulk pricing: "2 for $10" promotions
• Fractional pricing: Items sold by weight or volume
• Multi-pack items: Cases or bundles sold as individual units

---

Invoices

Note: You can only access invoices generated from orders created with your API key.

Create Invoice

Endpoint: POST /invoices

Create a new invoice directly. You must provide either a customerId (existing customer) or a customer object (to create a new customer).

Request Body:

Field	Type	Required	Description
externalInvoiceId	string	Yes	External invoice identifier (max 20 chars)
invoiceDate	datetime	Yes	Date the invoice was created (ISO 8601)
orderMethod	string	Yes	Pickup or Delivery
taxAmount	number	Yes	Total tax amount
items	array	Yes	Invoice line items (see below)
customerId	string	Conditional	Existing customer ID (provide this OR customer)
customer	object	Conditional	New customer details (provide this OR customerId)
payments	array	No	Payments applied to this invoice
taxableAmount	number	No	Total taxable amount before tax
memo	string	No	Memo for the invoice

Invoice Line Item Fields:

Field	Type	Required	Description
productId	string	Conditional	Product ID (provide this OR productCode)
productCode	string	Conditional	Product code/SKU (provide this OR productId)
quantity	number	Yes	Quantity of the product
unitPrice	number	Yes	Unit price of the product
subtotal	number	Yes	Subtotal before tax/discounts
isTaxable	boolean	Yes	Whether the item is taxable
discountAmount	number	Yes	Discount amount applied

Payment Fields:

Field	Type	Required	Description
paymentMethod	string	Yes	APICreditCard or APIFoodStamp
amount	number	Yes	Payment amount
referenceNo	string	Yes	Reference number (max 15 chars)
dateTime	datetime	Yes	Payment date/time (ISO 8601)
maskedCreditCardNumber	string	No	Masked card number
cardholderName	string	No	Cardholder name
authorizationCode	string	No	Bank authorization code

Example:

Code
curl -X POST https://api.poswithlogic.dev/invoices \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalInvoiceId": "INV-2026-001",
    "customerId": "12345",
    "invoiceDate": "2026-02-27T12:00:00Z",
    "orderMethod": "Pickup",
    "taxAmount": 5.25,
    "items": [
      {
        "productCode": "PROD001",
        "quantity": 2,
        "unitPrice": 15.00,
        "subtotal": 30.00,
        "isTaxable": true,
        "discountAmount": 0.00
      }
    ],
    "payments": [
      {
        "paymentMethod": "APICreditCard",
        "amount": 35.25,
        "referenceNo": "REF123456",
        "dateTime": "2026-02-27T12:05:00Z"
      }
    ]
  }'

Response:

• Status Code: 201 Created
• 400 - Invalid request parameters or product not found
• 404 - Customer not found
• 409 - Invoice with this external ID already exists

---

Get Invoice by ID

Endpoint: GET /invoices/id/{id}

Path Parameters:

Parameter	Type	Description
id	string	Invoice identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/invoices/id/990000000000 \
  -H "x-api-key: YOUR_API_KEY"

Get Invoice by Order ID

Endpoint: GET /invoices/order/{orderId}

Path Parameters:

Parameter	Type	Description
orderId	string	Order identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/invoices/order/15007763 \
  -H "x-api-key: YOUR_API_KEY"

Get Invoice by External Invoice ID

Endpoint: GET /invoices/externalinvoiceid/{externalInvoiceId}

Path Parameters:

Parameter	Type	Description
externalInvoiceId	string	External invoice identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/invoices/externalinvoiceid/INV-2026-001 \
  -H "x-api-key: YOUR_API_KEY"

Get Invoice by External Order ID

Endpoint: GET /invoices/externalorderid/{externalOrderId}

Path Parameters:

Parameter	Type	Description
externalOrderId	string	External order identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/invoices/externalorderid/ext-order-123 \
  -H "x-api-key: YOUR_API_KEY"

---

Customers

Note: With the customer:get:own scope, you can only access customers associated with orders created by your API key.

To access all customers in the account, use the customer:get:all scope. ⚠️ This is a sensitive scope — only request it if your application genuinely needs access to all customer data, and ensure you handle personal information responsibly.

Get All Customers

Retrieve a paginated list of all customers with optional filtering by last modified date.

Endpoint: GET /customers

Query Parameters:

Parameter	Type	Default	Description
take	integer	20	Records to return (max 100)
cursor	string	-	Cursor for pagination (returned from previous request)
lastMod	datetime	-	Filter by last modified date (ISO 8601)

Example:

Code
curl -X GET "https://api.poswithlogic.dev/customers?take=100" \
  -H "x-api-key: YOUR_API_KEY"

Get Customer by ID

Endpoint: GET /customers/id/{id}

Path Parameters:

Parameter	Type	Description
id	string	Customer identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/customers/id/12345 \
  -H "x-api-key: YOUR_API_KEY"

Get Customer by Phone Number

Endpoint: GET /customers/phonenumber/{phoneNumber}

Path Parameters:

Parameter	Type	Description
phoneNumber	string	Customer phone number (10 digits)

Example:

Code
curl -X GET https://api.poswithlogic.dev/customers/phonenumber/5551234567 \
  -H "x-api-key: YOUR_API_KEY"

Get Customer ID by Phone Number

Endpoint: GET /customers/phonenumber/{phoneNumber}/id

Path Parameters:

Parameter	Type	Description
phoneNumber	string	Customer phone number (10 digits)

Example:

Code
curl -X GET https://api.poswithlogic.dev/customers/phonenumber/5551234567/id \
  -H "x-api-key: YOUR_API_KEY"

---

Customer Credit Cards

Note: Card endpoints never return full card numbers — only masked values, expiration, and issuer.

Get All Cards for a Customer

Retrieve all credit cards on file for a customer.

Endpoint: GET /customers/id/{customerId}/cards

Path Parameters:

Parameter	Type	Description
customerId	string	Customer identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/customers/id/12345/cards \
  -H "x-api-key: YOUR_API_KEY"

Response:

Code
[
  {
    "id": "CC001",
    "masked": "************1234",
    "exp": "0627",
    "name": "John Doe",
    "zipCode": "10001",
    "issuer": "Visa"
  }
]

Get Card by ID

Retrieve a specific credit card by its ID.

Endpoint: GET /customers/id/{customerId}/cards/{cardId}

Path Parameters:

Parameter	Type	Description
customerId	string	Customer identifier
cardId	string	Card identifier

Example:

Code
curl -X GET https://api.poswithlogic.dev/customers/id/12345/cards/CC001 \
  -H "x-api-key: YOUR_API_KEY"

Save a Credit Card

Save a credit card to a customer's account. The card is tokenized via the payment gateway — full card numbers are never stored.

Endpoint: POST /customers/id/{customerId}/cards

Path Parameters:

Parameter	Type	Description
customerId	string	Customer identifier

Request Body:

Field	Type	Required	Description
cardNumber	string	Yes	Full card number (13-19 digits). Tokenized — never stored raw
expMonth	integer	Yes	Expiration month (1-12)
expYear	integer	Yes	Expiration year (2-digit, e.g. 26 for 2026)
cvv	string	Yes	Card verification value (CVV/CVC)
name	string	Yes	Cardholder name (max 25 chars)
zip	string	No	Billing zip code (max 5 chars)
houseNumber	string	No	Billing house number for AVS verification (max 5 chars)

Example:

Code
curl -X POST https://api.poswithlogic.dev/customers/id/12345/cards \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "4111111111111111",
    "expMonth": 6,
    "expYear": 27,
    "cvv": "123",
    "name": "John Doe",
    "zip": "10001"
  }'

Response:

• Status Code: 201 Created
• 400 - Invalid request or gateway rejected the card
• 404 - Customer not found

---

Customer Balance

Get Balance by Customer ID

Endpoint: GET /customers/id/{id}/balance

Path Parameters:

Parameter	Type	Description
id	string	Customer identifier

Headers:

Header	Type	Required	Description
X-Customer-Pin	string (≤8)	Yes	Customer PIN for second-factor verification

Example:

Code
curl -X GET https://api.poswithlogic.dev/customers/id/12345/balance \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Customer-Pin: 1234"

Response:

Code
{
  "id": "12345",
  "balance": 25.50
}

Note: A positive balance means the customer owes money. A negative balance means the store owes the customer.

Get Balance by Phone Number

Endpoint: GET /customers/phonenumber/{phoneNumber}/balance

Path Parameters:

Parameter	Type	Description
phoneNumber	string	Customer phone number (10 digits)

Headers:

Header	Type	Required	Description
X-Customer-Pin	string (≤8)	Yes	Customer PIN for second-factor verification

Example:

Code
curl -X GET https://api.poswithlogic.dev/customers/phonenumber/5551234567/balance \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Customer-Pin: 1234"

---

Customer Charges

Charge a Customer's Credit Card

Charge a stored or temporary credit card. The amount must be greater than zero — refunds are not supported via this endpoint.

Endpoint: POST /customers/id/{customerId}/charges

Path Parameters:

Parameter	Type	Description
customerId	string	Customer identifier

Headers:

Header	Type	Required	Description
X-Customer-Pin	string (≤8)	Yes	Customer PIN for second-factor verification

Request Body:

Field	Type	Required	Description
externalId	string	Yes	Client-provided unique ID for idempotency (max 20 chars)
amount	number	Yes	Amount to charge (0.01 - 99999.99)
cardId	string	Conditional	Stored card ID. Mutually exclusive with card
card	object	Conditional	Temporary card details (same fields as Save Card request). Mutually exclusive with cardId

Example (charge by stored card ID):

Code
curl -X POST https://api.poswithlogic.dev/customers/id/12345/charges \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "CHG-2026-001",
    "amount": 35.25,
    "cardId": "CC001"
  }'

Response:

Code
{
  "amountCharged": 35.25,
  "authCode": "A12345",
  "referenceNo": "REF789",
  "maskedCardNumber": "************1234",
  "newBalance": 0.00
}

Status Codes:

• 200 - Charge approved
• 400 - Invalid request, card declined, or charge failed
• 404 - Customer or card not found
• 409 - A record with this externalId already exists (idempotency protection)

---

Sale Records

Sale history is read one item at a time — there is no endpoint that returns the whole store's sales.

Access is granted by the store owner, not by the key itself. Creating an API key grants nothing here, and neither the e-commerce nor the shelf-tag bundle includes it. The owner opens Permission list in the dashboard, which attaches the salerecord:get:all permission to the key, then checks the items this key may look up and saves. Checkbox changes take effect only on save; until then, both routes below return 403.

With access saved, reading history takes two calls:

You want	Call
Which products may I query?	GET /permissionlist
History for one of those products	GET /salerecords

Code
GET /permissionlist?take=50
        ↓
  pick an itemCode from the results
        ↓
GET /salerecords?itemCode=…&startDate=2026-08-01&endDate=2026-08-31&take=50
        ↓
  while hasMore, repeat with cursor (same itemCode and dates)

Every response sets x-meter-unit-cost to the number of rows it returns in results.

Permission list

Endpoint: GET /permissionlist

The items this API key may query. size and unit carry the same meaning as in GET /products.

Query Parameters:

Parameter	Type	Required	Description
take	integer	No	Page size, 1–100. Default 20.
cursor	string	No	Opaque. Omit on the first page. Pass the previous page's cursor unchanged after that.

Example response:

Code
{
  "results": [
    {
      "itemCode": "012345678905",
      "description": "Apple Cider 12 oz",
      "brand": "Carbolicious",
      "size": 12,
      "unit": "oz"
    }
  ],
  "hasMore": true,
  "cursor": "…",
  "total": 128
}

Field	Meaning
itemCode	Pass this as itemCode on sale records (primary UPC / SKU).
description	Item description.
brand	Brand.
size	Numeric size. Omitted when the catalog size is zero.
unit	Unit of measure for size.
total	Match count. First page only (no cursor on the request).
hasMore	Another page exists.
cursor	Token for the next page. Ignore it unless hasMore is true.

Example:

Code
curl "https://api.poswithlogic.dev/permissionlist?take=50" \
  -H "x-api-key: YOUR_API_KEY"

Errors:

Status	When
403	This key's permission list is empty.
400	take out of range, or cursor is not a token from this API.

Sale records

Endpoint: GET /salerecords

Invoice lines for a single itemCode. Money fields are per unit (line amount ÷ quantity), rounded to 2 decimals; a line with quantity 0 reports 0 for all of them. This response carries no total — keep paging while hasMore is true. Each returned row costs 0.1 credits, so a full page of 20 lines costs 2 credits.

Query Parameters:

Parameter	Type	Required	Description
itemCode	string	Yes	From the permission list, or an alias of that item.
startDate	date	Yes	Inclusive start (YYYY-MM-DD). Not in the future.
endDate	date	Yes	Inclusive end. On or after startDate; at most 31 days; not in the future.
take	integer	No	Page size, 1–100. Default 20.
cursor	string	No	Opaque. Reuse with the same itemCode, startDate, and endDate.

Example response:

Code
{
  "results": [
    {
      "invoiceNumber": "10432",
      "date": "2026-08-01",
      "quantity": 2,
      "unitPrice": 3.49,
      "itemDiscount": 0.10,
      "allocatedSaleDiscount": 0.05
    }
  ],
  "hasMore": true,
  "cursor": "…"
}

Field	Meaning
invoiceNumber	Invoice that contains the line.
date	Line date.
quantity	Units sold on this line.
unitPrice	Price per unit (line amount ÷ quantity).
itemDiscount	Per-unit markdown on this line. Not a ticket total.
allocatedSaleDiscount	This line's share of the sale-level discount, per unit. Not the whole ticket, and not a second line markdown.

Example:

Code
curl "https://api.poswithlogic.dev/permissionlist?take=50" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://api.poswithlogic.dev/salerecords?itemCode=012345678905&startDate=2026-08-01&endDate=2026-08-31&take=50" \
  -H "x-api-key: YOUR_API_KEY"

Errors:

Status	When
400	Missing/invalid dates, itemCode empty or too long, take out of range, or cursor does not match this item and date range.
403	This key's permission list is empty, or this itemCode is not on it.
404	Unknown itemCode.

---

Best Practices

1. Pagination - Use take and cursor parameters for large datasets
2. Rate Limiting - Honor the Retry-After header and implement exponential backoff for 429 errors (see Rate Limiting)
3. Webhooks - Respond within 30 seconds to avoid timeouts
4. Incremental Sync - Use lastMod parameter to efficiently sync product updates
5. Payment Processing - Include paymentEndpoint to enable automated payment handling
6. Error Handling - Check HTTP status codes and handle errors appropriately
7. Sale records - Page GET /permissionlist for a granted itemCode, then GET /salerecords for that code over a window of at most 31 days (see Sale Records)

---

Support

For API support or questions, contact your Decimal representative.