Loyverse

BUSINESS · COMMERCE & FINANCE

Items, inventory, receipts, and customers across that merchant’s stores.

Connecting Loyverse in practice

Loyverse’s quota is 300 requests per 300 seconds per account, an average of one a second with no documented burst, and an OAuth access token lives only 43,200 seconds so a long-running agent refreshes twice a day. The simpler alternative carries a warning in Loyverse’s own words: "Be aware that personal access token gives unlimited access to the targeted account."

Scopes that draw scrutiny

RECEIPTS_WRITE Creates receipts, so an agent holding it can write sales into the merchant’s books rather than just read them.
INVENTORY_WRITE Edits inventory levels, which moves real stock figures the shop floor depends on.
EMPLOYEES_READ Reads employee information — staff personal data, separate from the merchant record, and the one most likely to raise a question in review.
POS_DEVICES_WRITE Updates POS device information, so it reaches the till configuration and not only the data it produces.
Personal access token The non-OAuth route, taken from the back office. Loyverse documents it as unlimited access to the account, so it cannot express read-only.

Rate limits

"The current limit is 300 requests per 300 sec per account", plus additional resource-based rate limits.
Over the limit returns HTTP 429 with error 429 RATE_LIMITED.
List endpoints: `limit` defaults to 50 and maxes at 250.

Worth knowing

OAuth access tokens come back with expires_in 43200, so refresh handling is mandatory rather than an optimisation.
Cursor pagination returns 400 INVALID_CURSOR on a stale or malformed cursor, so a resumed job cannot assume yesterday’s cursor still works.
Scope names are uppercase and space-separated in the authorize URL (ITEMS_READ RECEIPTS_WRITE) but lowercase in the OpenID discovery document’s scopes_supported, so a copy-paste between the two produces an invalid request.
The version is in the base URL (https://api.loyverse.com/v1.0) and the published reference is a single OpenAPI YAML rendered through Redoc, so the endpoint list is not crawlable without fetching the spec.

Checked against Loyverse API reference (2026-09-29)

Acts as the person, not as itself

Each user connects their own account. Every call carries both identities — the agent and the person it is acting for — so the agent can never reach past what that individual can already do.

Credentials never touch the agent

Tokens live in the vault and attach server-side at call time. The agent holds a session, not a secret, and revoking access does not mean rotating a key.

Every call on the record

Who asked, which agent acted, which action ran, and the verdict that let it through — one audit trail across every integration, not one per vendor.

What an agent can do

Each action is granted on its own. An agent allowed to read is not thereby allowed to write, and the scope beside each row is what the acting user must have connected for it to run at all.

loyverse_delete_categories_by_category_idWRITE

Delete Category via DELETE /categories/{category_id}

ITEMS_WRITE

loyverse_delete_customers_by_customer_idWRITE

Delete Customer via DELETE /customers/{customer_id}

CUSTOMERS_WRITE

loyverse_delete_discounts_by_discount_idWRITE

Delete Discount via DELETE /discounts/{discount_id}

ITEMS_WRITE

loyverse_delete_items_by_item_idWRITE

Delete Item via DELETE /items/{item_id}

ITEMS_WRITE

loyverse_delete_items_by_item_id_imageWRITE

Delete a single image via DELETE /items/{item_id}/image

ITEMS_WRITE

loyverse_delete_modifiers_by_modifier_idWRITE

Delete Modifier via DELETE /modifiers/{modifier_id}

ITEMS_WRITE

loyverse_delete_pos_devices_by_pos_device_idWRITE

Delete POS Device via DELETE /pos_devices/{pos_device_id}

POS_DEVICES_WRITE

loyverse_delete_suppliers_by_supplier_idWRITE

Delete Supplier via DELETE /suppliers/{supplier_id}

SUPPLIERS_WRITE

loyverse_delete_taxes_by_tax_idWRITE

Delete Tax via DELETE /taxes/{tax_id}

TAXES_WRITE

loyverse_delete_variants_by_variant_idWRITE

Delete Item Variant via DELETE /variants/{variant_id}

ITEMS_WRITE

loyverse_delete_webhooks_by_webhook_idWRITE

Delete Webhook via DELETE /webhooks/{webhook_id}

no provider scope

loyverse_get_categoriesREAD

The list of categories is sorted by created_at property in descending order. The most recent categories appear first via GET /categories

ITEMS_READ

loyverse_get_categories_by_category_idREAD

Get a single category via GET /categories/{category_id}

ITEMS_READ

loyverse_get_customersREAD

The list of customers is sorted by created_at property in descending order. The most recent customers appear first via GET /customers

CUSTOMERS_READ

loyverse_get_customers_by_customer_idREAD

Get a single customer via GET /customers/{customer_id}

CUSTOMERS_READ

loyverse_get_discountsREAD

The list of discounts is sorted by created_at property in descending order. The most recent discounts appear first via GET /discounts

ITEMS_READ

loyverse_get_discounts_by_discount_idREAD

Get a single discount via GET /discounts/{discount_id}

ITEMS_READ

loyverse_get_employeesREAD

The list of employees is sorted by created_at property in descending order. The most recent employees appear first via GET /employees

EMPLOYEES_READ

loyverse_get_employees_by_employee_idREAD

Get a single employee via GET /employees/{employee_id}

EMPLOYEES_READ

loyverse_get_inventoryREAD

Inventory levels for item variants via GET /inventory

INVENTORY_READ

loyverse_get_itemsREAD

The list of items is sorted by created_at property in descending order. The most recent items appear first via GET /items

ITEMS_READ

loyverse_get_items_by_item_idREAD

Get a single item via GET /items/{item_id}

ITEMS_READ

loyverse_get_merchantREAD

Get merchant information via GET /merchant/

MERCHANT_READ

loyverse_get_modifiersREAD

The list of modifiers is sorted by created_at property in descending order. The most recent modifiers appear first via GET /modifiers

ITEMS_READ

loyverse_get_modifiers_by_modifier_idREAD

Get a single modifier via GET /modifiers/{modifier_id}

ITEMS_READ

loyverse_get_payment_typesREAD

The list of payment types is sorted by created_at property in descending order. The most recent payment types appear first via GET /payment_types

PAYMENT_TYPES_READ

loyverse_get_payment_types_by_payment_type_idREAD

Get a single payment type via GET /payment_types/{payment_type_id}

PAYMENT_TYPES_READ

loyverse_get_pos_devicesREAD

The list of pos devices is sorted by created_at property in descending order. The most recent pos devices appear first via GET /pos_devices

POS_DEVICES_READ

loyverse_get_pos_devices_by_pos_device_idREAD

Get a single pos device via GET /pos_devices/{pos_device_id}

POS_DEVICES_READ

loyverse_get_receiptsREAD

The list of receipts is sorted by created_at property in descending order. The most recent receipts appear first via GET /receipts

RECEIPTS_READ

loyverse_get_receipts_by_receipt_numberREAD

Get a single receipt via GET /receipts/{receipt_number}

RECEIPTS_READ

loyverse_get_shiftsREAD

The list of shifts is sorted by created_at property in descending order. The most recent shifts appear first via GET /shifts

SHIFTS_READ

loyverse_get_shifts_by_shift_idREAD

Get a single shift via GET /shifts/{shift_id}

SHIFTS_READ

loyverse_get_storesREAD

The list of stores is sorted by created_at property in descending order. The most recent stores appear first via GET /stores

STORES_READ

loyverse_get_stores_by_store_idREAD

Get a single store via GET /stores/{store_id}

STORES_READ

loyverse_get_suppliersREAD

The list of suppliers is sorted by created_at property in descending order. The most recent suppliers appear first via GET /suppliers/

SUPPLIERS_READ

loyverse_get_suppliers_by_supplier_idREAD

Get a single supplier via GET /suppliers/{supplier_id}

SUPPLIERS_READ

loyverse_get_taxesREAD

The list of taxes is sorted by created_at property in descending order. The most recent taxes appear first via GET /taxes

TAXES_READ

loyverse_get_taxes_by_tax_idREAD

Get a single tax via GET /taxes/{tax_id}

TAXES_READ

loyverse_get_variantsREAD

The list of variants is sorted by created_at property in descending order. The most recent variants appear first via GET /variants

ITEMS_READ

loyverse_get_variants_by_variant_idREAD

Get a single item variant via GET /variants/{variant_id}

ITEMS_READ

loyverse_get_webhooksREAD

This endpoint will only return webhooks created by the application which is making the request. via GET /webhooks/

no provider scope

loyverse_get_webhooks_by_webhook_idREAD

Get a single webhook via GET /webhooks/{webhook_id}

no provider scope

loyverse_post_categoriesWRITE

Create or update a single category via POST /categories

ITEMS_WRITE

loyverse_post_customersWRITE

Create or update a single customer via POST /customers

CUSTOMERS_WRITE

loyverse_post_discountsWRITE

Create or update a single discount via POST /discounts

ITEMS_WRITE

loyverse_post_inventoryWRITE

Batch update inventory levels for item variants via POST /inventory

INVENTORY_WRITE

loyverse_post_itemsWRITE

Create or update a single item via POST /items

ITEMS_WRITE

loyverse_post_modifiersWRITE

Create or update a single modifier via POST /modifiers

ITEMS_WRITE

loyverse_post_pos_devicesWRITE

Create or update a single pos device via POST /pos_devices

POS_DEVICES_WRITE

loyverse_post_receiptsWRITE

Create a sales receipt via POST /receipts

RECEIPTS_WRITE

loyverse_post_receipts_by_receipt_number_refundWRITE

When using the refund API you should take into account these notes: * At the moment refund API allows creating a refund only for sales receipts which are paid by a single payment. For any attempt to make a refund for a sales receipt that has more than one payment Loyverse API will respond with an error. * Refund API doesn't support a refund of receipts paid by integrated payments using Loyverse POS app (e.g. iZettle, Sumup, etc.). For this purpose please use Loyverse POS app. * If a refund is created successfully, it will cause a restock of items specified in a refund receipt. via POST /receipts/{receipt_number}/refund

RECEIPTS_WRITE

loyverse_post_suppliersWRITE

Create or update a single supplier via POST /suppliers/

SUPPLIERS_WRITE

loyverse_post_taxesWRITE

Create or update a single tax via POST /taxes

TAXES_WRITE

loyverse_post_variantsWRITE

Create or update a single variant via POST /variants

ITEMS_WRITE

loyverse_post_webhooksWRITE

Create or update a single webhook via POST /webhooks/