Loyverse

Loyverse

This connector uses the Loyverse API v1.0 (https://api.loyverse.com/v1.0), the back office API of the Loyverse point of sale. It reads sales and refund receipts, shifts, the item catalog with variants, categories, modifiers, discounts and taxes, stock levels per store, customers with loyalty points, employees, stores, POS devices, payment types and suppliers, and it can create and update catalog records, customers and stock and record receipts.

Setup (2 minutes)

1. Sign in to the Loyverse Back Office as the owner and open Settings, Access tokens (https://r.loyverse.com/dashboard/#/integrations/tokens). Access tokens are part of the Integrations add-on on some plans.
2. Click Add access token, give it a name, optionally an expiry date, and save. Copy the token.
3. Paste it into LOYVERSE_ACCESS_TOKEN. It is sent as Authorization: Bearer <token> and has full access to the account, so keep it private.
4. Run loyverse_get_merchant to check it.

Workflow

• Account and stores: loyverse_get_merchant (currency and decimals), loyverse_list_stores, loyverse_get_store, loyverse_list_pos_devices.
• Sales: loyverse_list_receipts by store and date range (created_at_min/created_at_max), loyverse_get_receipt by receipt number. loyverse_create_receipt records a sale made elsewhere. Shifts and cash: loyverse_list_shifts, loyverse_get_shift. Payment types: loyverse_list_payment_types, loyverse_get_payment_type.
• Refunds: loyverse_refund_receipt creates a refund receipt for chosen lines of a sale.
• Catalog: loyverse_list_items, loyverse_get_item, loyverse_save_item, loyverse_delete_item; variants (SKU, barcode, price per store) with loyverse_list_variants (search by sku), loyverse_get_variant, loyverse_save_variant; loyverse_list_categories, loyverse_get_category, loyverse_save_category; loyverse_list_modifiers; loyverse_list_discounts, loyverse_get_discount, loyverse_save_discount; loyverse_list_taxes, loyverse_get_tax, loyverse_save_tax; loyverse_list_suppliers.
• Stock: loyverse_list_inventory gives in_stock per variant and store; loyverse_set_inventory sets new levels.
• Customers and staff: loyverse_list_customers (search by email), loyverse_get_customer, loyverse_save_customer, loyverse_delete_customer; loyverse_list_employees, loyverse_get_employee.
• Webhooks: loyverse_list_webhooks, loyverse_create_webhook (one event per webhook).

Switched off at install: loyverse_refund_receipt, loyverse_delete_item and loyverse_delete_customer; they cannot be undone, so an admin switches them on when the team needs them.

Before writing: the save tools create a record without id and update it with id, and an update replaces the record, so read it first and send every field you want to keep. loyverse_set_inventory takes the new absolute quantity in stock_after, not a difference. A receipt created through the API reduces stock and counts in reports; confirm lines and payments with the user.

Reading the answers: ids are UUIDs, receipts are addressed by receipt_number (e.g. 1-1001). Money is a decimal number in the account currency (see loyverse_get_merchant). Receipts have receipt_type SALE or REFUND; refunds carry positive amounts, so subtract them when you add up sales, and cancelled_at marks cancelled receipts. All times are UTC (ISO 8601); convert to the store's time zone before you group by day. Records deleted in the Back Office are hidden unless show_deleted is true.

Paging: list tools (all but stores, POS devices, payment types, discounts and taxes, which return everything at once) return limit records (50 by default, 250 at most) and a cursor while more exist; pass it as cursor until it is missing.

Limits and errors: 300 requests per 300 seconds per account (429 RATE_LIMITED above). Errors come as errors: [{code, details, field}]: 401 UNAUTHORIZED a wrong or expired token, 402 PAYMENT_REQUIRED a lapsed subscription or a missing add-on, 403 FORBIDDEN, 404 NOT_FOUND a wrong id, 400 INVALID_VALUE or MISSING_REQUIRED_PARAMETER with the field named.