Yasuaki Posted July 7 Posted July 7 Last updated: July 6, 2026 · Covers Loyverse API v1.0 · Base URL: https://api.loyverse.com/v1.0/ The most common Loyverse API pitfalls are scope-and-limit surprises. The Loyverse API is read-mostly: you can read almost every point-of-sale object but create only a limited set. Receipts older than 31 days can return 402 unless Unlimited Sales History is enabled, a receipt created with POST can hold only one payment type, you cannot create open orders or tickets for the kitchen display, item updates use POST (not PUT), and a 403 is often a request problem rather than a bad token. This guide explains each of these, with the exact endpoints and status codes, so you can find the answer without opening a support ticket. Why does my Loyverse API token return 401 or “access token is not valid”? The Loyverse API returns 401 Unauthorized (apps often show this as “access token is not valid”) when the token was regenerated or deleted, the Authorization header is malformed, or the wrong value was pasted. Deleting or regenerating a token in the Back Office suspends the old value immediately, so any integration still using it breaks until updated — a recurring cause of sudden 401s. Check, in order: the header is exactly Authorization: Bearer <token> with one space after Bearer and no quotation marks; no leading/trailing whitespace or newline was copied with the token; the token still exists under Settings → Access Tokens; and you are calling https://api.loyverse.com/v1.0/. If you rotate a token, update every integration in the same change window. Why can’t I read receipts older than 31 days from the Loyverse API? By default the Loyverse API returns sales data only from the last 31 days. The Loyverse Help Center states that access to sales data is limited to the last 31 days unless you start a trial of, or subscribe to, the Unlimited Sales History add-on. When an integration requests receipts older than that window without the add-on, the request returns 402 PAYMENT_REQUIRED rather than an empty list. This is the most common “I created a token but cannot pull my data” case, and the cause is the account plan, not the code. To read older receipts, enable Unlimited Sales History in Settings → Billing & Subscriptions (a 14-day free trial is available). Confirm you are inside the allowed window with date filters: GET https://api.loyverse.com/v1.0/receipts?created_at_min=2026-06-06T00:00:00.000Z&limit=250 Authorization: Bearer YOUR_ACCESS_TOKEN A 402 here is a subscription signal, not a bug — check the date range and whether the add-on is active before debugging the request. Can I create sales, receipts, and orders through the Loyverse API? Partly. You can create a completed sales receipt with a POST to /v1.0/receipts, but a receipt created this way can carry only one payment type. The API reference states there is a restriction that “only one payment can be applied to receipt when using POST request,” — so split-tender (multiple payment methods on one receipt) cannot be created through the Loyverse API. You also cannot post a receipt with a GET request; creation is POST only. Separately, you cannot create open orders or open tickets through the Loyverse API. Creating orders via the API so they appear on the Loyverse Kitchen Display System (KDS) is not possible. If your app takes online or in-app orders, the API will not route them to the POS or KDS as live tickets. Plan for this early: design each API-created receipt around a single payment type, and do not build a workflow that depends on pushing open tickets into the POS. How do I create or update items, and why do I get 405 Method Not Allowed? Use POST, not PUT, and post to the collection, not to an item URL. The /v1.0/items endpoint supports GET and POST only. To create an item you POST to /v1.0/items; to update one you POST to the same /v1.0/items with the item’s id in the request body. Sending PUT /v1.0/items, or POST to /v1.0/items/{id}, returns 405 Method Not Allowed. This trips up developers whose HTTP client or framework defaults to PUT for updates. POST https://api.loyverse.com/v1.0/items Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "id": "EXISTING_ITEM_ID", "item_name": "Latte" } // include id to update; omit id to create One more item-creation caution: you cannot set an item’s initial stock in the same call that creates the item. Create the item first, then set stock levels through the inventory endpoint as a separate step. How does pagination work in the Loyverse API, and why did I only get 50 records? The Loyverse API uses cursor-based pagination, and the default page size is small. The default limit is 50 objects and the maximum is 250. List responses include a cursor; to get the next page you pass that value back as the cursor query parameter. If you read only the first response you silently receive at most 50 (or 250) rows and assume the rest are missing. GET /v1.0/receipts?limit=250 -> read receipts, capture "cursor" GET /v1.0/receipts?cursor=<cursor_from_previous_response> -> repeat until no cursor is returned Keep the same filters across the whole cursor sequence — let the cursor drive paging. What are the Loyverse API rate limits? The Loyverse API is rate limited and returns 429 Too Many Requests when you exceed it. The limit is 300 requests per 300 seconds; when you hit a limit, back off and retry with increasing delays rather than looping immediately. Reduce request volume by paginating with limit=250, requesting only the date ranges you need with created_at_min/created_at_max, and caching reference data (categories, items, payment types) instead of refetching it on every run. How do webhooks work, and what breaks webhook verification? There are three ways to create webhooks in Loyverse. From https://r.loyverse.com/dashboard/#/webhooks From /webhook endpoint using an access token. From /webhook endpoint using OAuth 2.0. Only webhooks created by the third method include X-Loyverse-Signature in the header. We use the SHA-1 HMAC algorithm with hex encoding as the hash function. How do I get the sold items (line items) for each receipt? There is no separate “line items” or “invoice details” endpoint in the Loyverse API — the items sold are embedded inside each receipt object as its line_items field. To get every item sold in a period, request the receipts for that period and read line_items from each receipt in the response. GET https://api.loyverse.com/v1.0/receipts?created_at_min=2026-06-01T00:00:00.000Z&created_at_max=2026-07-01T00:00:00.000Z&limit=250 Authorization: Bearer YOUR_ACCESS_TOKEN Each receipt in the response carries its own line_items (the items sold on that receipt), alongside totals, taxes, payment, and customer references. Use created_at_min/created_at_max to bound the period, and follow the cursor to page through all receipts. If you need per-item sales analysis, flatten line_items across receipts on your side — the Loyverse API does not offer a pre-aggregated “sales by item” endpoint. What is a Variant ID in the Loyverse API? A Variant ID (variant_id) is the internal identifier — a UUID — of one specific variant of an item. In Loyverse API structure, every item has at least one variant, even if an item doesn’t have variant in the Back office. You will not find the ID by browsing the Back Office item card — read it from the API. Get variant_id values from the items endpoints: each item returned by GET /v1.0/items includes its variants, and each variant carries its variant_id. This matters because two core operations key on the variant, not the item: inventory levels are tracked per variant per store, and receipt line_items reference the variant that was sold. If your integration maps products by item ID alone, it cannot address stock or reconcile sale lines for items. How do I increase or decrease stock through the Loyverse API? Update stock with a POST to /v1.0/inventory (batch update of inventory levels), and note the most important detail: stock_after is the new absolute stock level, not the amount to add or remove. To reduce stock by 3 from a level of 13, you send stock_after: 10 — not -3. Sending a delta silently sets the stock to that delta value, which is the classic way integrations corrupt their stock counts. POST https://api.loyverse.com/v1.0/inventory Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "inventory_levels": [ { "variant_id": "YOUR_VARIANT_ID", "store_id": "YOUR_STORE_ID", "stock_after": 10 } ] } Because stock_after is absolute, a decrease is always read-then-write: fetch the current level from GET /v1.0/inventory for that variant_id and store_id, compute the new level, and post it. This applies equally when calling the Loyverse API from no-code tools such as Make, Zapier, or n8n — add an HTTP module, perform the read step first, and be aware that between your read and your write a sale at the POS can change the level (re-read or reconcile periodically if exact counts matter). Also remember the item-creation order of operations: you cannot set initial stock in the call that creates an item — create the item first, then set its level through /v1.0/inventory. Can I connect a payment provider through the Loyverse API? The Loyverse API does not connect payment providers to the POS checkout. The API does not add it to the sale screen. What the API does allow is building your own integration around the sale: you can record a completed sale by posting a receipt (with a single payment type), and you can read receipts, items, customers, and inventory to sync with an external system. Plan the boundary accordingly: taking the payment happens in your own app or the provider’s system; the Loyverse API’s role is recording the resulting sale and keeping catalog, stock, and customer data in sync. Can I read Time Clock (timecard) data through the Loyverse API? Time Clock data — employee clock-in and clock-out records — is not currently exposed through the Loyverse API. The Employees resource covers employee profiles, but there is no endpoint for retrieving timecards, so payroll or attendance integrations cannot pull working hours automatically today. Which resources does the Loyverse API expose? The Loyverse API (v1.0) exposes the core point-of-sale objects as REST resources. Reads are broad; writes are limited (see the sections above). Confirm exact fields and any new resources against the API reference, since the list evolves. You want to… Resource(s) Note Read or sync the catalog Items, Variants, Categories, Modifiers, Discounts Update objects via POST (id in body); no PUT Read sales / bills Receipts POST creates a receipt with one payment type Read or adjust stock Inventory Set stock separately after creating an item Sync customers / loyalty Customers — Map structure and staff Stores, Employees, Payment Types, Merchant React to changes Webhooks Quick reference: where the data actually lives You are looking for… It lives in… Key detail Items sold per sale (“invoice lines”) line_items inside each receipt No separate line-items endpoint; filter receipts by created_at One specific receipt GET /v1.0/receipts/{receipt_number} Use the receipt_number value exactly. Stock levels GET/POST /v1.0/inventory Per variant_id per store_id; stock_after is absolute Variant identifiers Variants inside GET /v1.0/items Every item has ≥1 variant Employee timecards Not in the API Back Office reports only; employee profiles are available, hours are not Frequently asked questions Can I create a sale or receipt through the Loyverse API? Yes, with a POST to /v1.0/receipts, but the receipt can have only one payment type — split payments cannot be created via the API. Can I push orders to the POS or Kitchen Display via the API? No. Creating open orders or tickets via the API to appear on the KDS is not possible at this time. Why do I get 405 when updating an item? Because /v1.0/items accepts only GET and POST. Update an item by POST-ing to /v1.0/items with its id in the body; do not use PUT or post to /v1.0/items/{id}. Why can I only read the last 31 days of receipts? By default the API limits sales data to the last 31 days. Reading older receipts requires the Unlimited Sales History add-on (14-day trial available); without it, older requests return 402. Why did a list request return only 50 records? The default page size is 50. Set limit up to 250 and follow the cursor in each response to page through the full result set. Is there a line-items or invoice-details endpoint in the Loyverse API? No. The items sold are nested inside each receipt as line_items. Request receipts for your date range and read line_items from each receipt object. How do I get all items sold in a specific period? Call GET /v1.0/receipts with created_at_min and created_at_max, follow the cursor through all pages, and flatten the line_items of each receipt on your side. What is variant_id and where do I find it? The UUID of one specific variant of an item, assigned by the system. Read it from the variants inside GET /v1.0/items; inventory and sale lines are keyed on it. How do I add or subtract stock via the API? You don’t add or subtract — you set. POST /v1.0/inventory with stock_after as the new absolute level. Read the current level first, compute, then write. Can the API add a new payment provider to the POS? No. The API records completed sales (one payment type per API-created receipt) and syncs data; charging on the POS with a new provider cannot be done by an API call. Can I pull employee working hours via the API? Not currently. Timecard data is available in Back Office reports but has no API endpoint; employee profiles are available via the Employees resource. 1
.cropped.png.a7e4ae4c5301e57c9ef939a22b67918e.png){kind=logo}
.thumb.JPG.90b7660bad4461922fa90bc2b4d98910.JPG)
Recommended Posts