Troubleshooting

A sale was made but no document appeared. Check the Documents tile's subtitle and Queue & errors. If the sale is queued, wait or press Process all. If it says the store is not configured, finish its setup in Settings › Stores and Settings › SAGE items. If you are not live yet, sales are ignored by design. Queue & errors shows only this till's store: a sale made at another store shows on that store's tills and on Documents in the admin. A sale at a location marked Does not sell on the POS is skipped silently: zrsPOS does not invoice it and it appears in no queue.

The receipt did not print. Open the Documents tile → Printer. If it says "to configure", pick this till's printer. For pull printers, the printer's page in the app shows the last contact time; no contact means the printer lost power or network. For direct printers, use Print test and check the router rule.

The print app says "No connection to zrsPOS". The tablet has no internet, or the printer was deleted in the admin (the app then says it was revoked). Check Wi-Fi first; the app retries by itself. See The print app.

Printing stops when the tablet's screen goes off. Open zrsPOS Print and press Allow running in the background (battery), then allow it. Android otherwise stops the app.

The Epson printer has no Server Direct Print option. Check for an Epson firmware update for that model. Otherwise connect the printer by USB to the tablet and use the print app, or switch the printer to Direct. See Printing & delivery.

"Store not configured" on a sale. The store's série, document types, warehouse or final-consumer PartyID are missing. Open the store in Settings › Stores and complete them; it turns to Working once they are right.

The wrong document type was used for a return. Each store's Documents & SAGE codes page (Settings › Stores) lets you choose NC or NRE, as its Returns document. Change it; future returns use the new choice.

An order was edited after invoicing. zrsPOS raises an alert on Documents and on the order. Correct in SAGE (credit note and new invoice as your accountant advises), then press I handled it in SAGE on the alert.

The NIF was rejected. Portuguese NIFs are checked for a valid checksum. For foreign tax numbers, switch on Foreign tax number on the NIF tile.

SAGE is unreachable. Documents queue and retry automatically. Test the connection in Settings › SAGE connection; check the address there is right and that the SAGE API service is running.

When SAGE refuses a sale

A sale that SAGE refused shows on the Documents page under Needs you, with its cause and Details for support — the exact document we sent and SAGE's answer. The causes zrsPOS recognises, and what to do:

"The série has not been communicated to the AT for this document". SAGE refuses a certified document in a série the AT does not know for that document type — typically a new credit-note série used for the first time. In SAGE, communicate the série to the AT for that document type, then press Try again on the sale in Documents. Meanwhile, the store's Returns série (Settings › Stores, Documents & SAGE codes) can go back to Same as sales: the sales série is already communicated.

Full guide: /manual/en/problems/series_not_communicated

"As zonas do tipo Intracomunitário… estão reservadas para séries configuradas para IVA Comércio Eletrónico" (intra-community zones are reserved for e-commerce séries). In SAGE the customer is filed under an EU online-sales zone (OSS, for example "ESP NAO SUJEITO") or an intra-community zone — typically a foreign customer who first bought from the online shop. A sale at the till is taxed in Portugal, so zrsPOS issues store documents in the store's own VAT zone, whatever zone the customer has. If you still see this, check that the store's VAT zone (on its page in Settings › Stores) is the domestic one (for example "Nacional"), then press Try again.

Full guide: /manual/en/problems/zone_not_domestic

"O código do imposto 'NS' utilizado no documento não é válido" (tax code not valid) — on a Tax Free sale. The VAT-exempt group chosen in the Tax Free codes (Tax Free → exemption group) resolves, inside your SAGE company, to a tax code and exemption reason that SAGE will not accept on a certified document. The group's name can look right ("Isento Taxfree") while the rule behind it is not. Open the group in SAGE (Tabelas → Impostos → Grupos de IVA) and check which line of the tax table it uses: the combination proven to work on tax-free invoices is code NS with exemption reason M05 (Isento Artigo 14.º do CIVA). If your company only has ISE / M05, use that. After the change, zrsPOS retries the sale by itself within minutes; you can also press Try these … sales again. The deposit item (caução) uses its own group — check it points at the same rule.

Full guide: /manual/en/problems/tax_code_invalid

"O cliente tem o crédito cancelado" (customer credit cancelled). SAGE refuses every document for a customer whose credit limit type is "cancelled" — a default some SAGE versions apply to customers created from outside. Open the customer in SAGE and set a credit limit by value. The sale retries by itself.

Full guide: /manual/en/problems/credit_cancelled

"The document type does not exist in SAGE". The document type set for the store (FS, FR or credit note) does not exist or is not valid in SAGE, and SAGE refused the document — it was not created. Fix the store's document types in Settings › Stores and press Try again: the retry uses the corrected type.

Full guide: /manual/en/problems/document_type_invalid

"Série não existe / não válida" (series does not exist). The série configured for the store does not exist in SAGE for this document type, or is closed. Check the store's série (Settings › Stores) against SAGE's Séries table.

Full guide: /manual/en/problems/series_exhausted

"Artigo não existe" (item does not exist). One of the item codes in Settings › SAGE items (shipping, generic refund) or in the Tax Free codes (deposit) is not in SAGE. The page that holds it names the missing one and offers to create it.

Full guide: /manual/en/problems/item_not_found

"Timed out" — SAGE did not answer in time. SAGE can be slow. The document may have been issued anyway: a retry looks for it before issuing another, so there is no duplicate risk. If it keeps happening, the SAGE server or its network is overloaded.

Full guide: /manual/en/problems/timeout

"Unreachable" — zrsPOS cannot reach SAGE. The SmartAPI service is stopped, or the address or port in Settings › SAGE connection is no longer correct (a router change, a new public IP). Test the connection there.

Full guide: /manual/en/problems/unreachable

"Preview" — a return of an online order, credit note built but not sent. Online returns is in preview mode: zrsPOS found the online invoice in SAGE and built the credit note, but did not send it. Open "Details for support" and check the source invoice (OriginatingON), the lines, the currency and the rate. When the result is right across several returns, switch the mode to Automatic and press Try again on each pending job — only then is it issued.

Full guide: /manual/en/problems/online_preview

"No invoice in the online séries carries this order" — an online order returned in store. zrsPOS searches the séries named in Online returns for an invoice (FR/FT) whose reference contains the order number (#1234). It found none: the online série is missing from the list, the order was invoiced without a reference (about 5% of orders), or it has not been invoiced yet (only an NE). Find the invoice in SAGE by reference and issue the credit note by hand; fix the séries list if that was the cause.

Full guide: /manual/en/problems/online_no_match

"More than one invoice carries this order" — zrsPOS does not guess. Two or more invoices in the online séries carry the same order number in their reference (an order invoiced in two shipments, say). zrsPOS never picks one by itself. Issue the credit note by hand in SAGE against the invoice that billed the returned item.

Full guide: /manual/en/problems/online_ambiguous

"Different currency" — the online invoice is in another currency. The online invoice was issued in the currency the customer paid in (Shopify Markets: USD, GBP…) and the return did not carry prices in that currency, or it is a value-only refund. A credit note must be in the original invoice's currency and at its rate. Issue it by hand in SAGE, copying the invoice's currency and exchange rate.

Full guide: /manual/en/problems/online_currency

"Could not read the order from Shopify". To match the return to the online invoice zrsPOS needs the order number, which it reads from Shopify. That failed for lack of access (the app's token expired) or because the order does not exist. Open zrsPOS in the Shopify admin once — that renews access — and press Try again.

Full guide: /manual/en/problems/online_lookup

"Online payment method has no SAGE payment method". An online order was refunded through a payment method (PayPal or an online card, for example) that is not mapped to any SAGE payment method. For online orders zrsPOS never uses the default SAGE payment method, which is usually cash: a refund to a card must not show up as cash leaving the till. On Settings › Payments, map that payment method to a SAGE payment method that is not cash. The credit note issues on the next retry.

Full guide: /manual/en/problems/online_tender

"Payment method has no SAGE payment method". The sale or refund was paid by a Shopify payment method (MB Way, for example) that is not mapped to a SAGE payment method, and the shop has no default SAGE payment method. zrsPOS never lets SAGE choose, because SAGE would book everything as cash. On Payments, map the method or choose the default SAGE payment method. The document issues on the next retry. Once a default is chosen, an unmapped method uses it and an alert asks you to map it.

Full guide: /manual/en/problems/tender_unmapped

"The online invoice was already credited". The online order's invoice already has credit notes in SAGE, issued by the online shop or by hand, and this return would exceed what was invoiced. zrsPOS does not credit twice. Check with the online team what was already refunded. If this credit note is still due, issue it by hand in SAGE.

Full guide: /manual/en/problems/online_already_credited

"The item is not on the online invoice". The return is of an item the order's online invoice does not bill — for example a pre-order that stayed on the order (NE) only and was never invoiced. There is nothing invoiced to credit. If the item was never invoiced, archive this. If it was invoiced on another document, issue the credit note by hand against that document.

Full guide: /manual/en/problems/online_item_not_invoiced

"Not known whether the return was made in a store". zrsPOS only credits online orders returned at a store's POS — never those managed online, in the Shopify admin or the online store. This time Shopify did not say which app made the return. If it was made at the POS, press Try again. If it was managed online, archive this.

Full guide: /manual/en/problems/online_origin_unknown

"Location not set up". The sale or return happened at a Shopify location that has no series, document types and warehouse in zrsPOS yet. Set that store up in Settings › Stores. The document issues on the next retry.

Full guide: /manual/en/problems/store_unconfigured

"Custom sale with no item for its VAT rate". A POS custom sale (a line with no product) is invoiced on the SAGE item you chose for its VAT rate in Settings › SAGE items, Custom sales, with the cashier's text as its description. This sale's VAT rate has no item yet. Set it and press Try again.

Full guide: /manual/en/problems/custom_sale_item

"Items with no match in SAGE". An item in the sale does not exist in SAGE. Usually it is a product whose barcode is not in SAGE (zrsPOS matches by barcode only, never by SKU). Put the SAGE item's barcode on the Shopify variant, or create the item in SAGE with that barcode, or sell catalogue products, and press Try again.

Full guide: /manual/en/problems/unmapped_items

"The generic refund item is missing". A refund with no items uses the generic refund item. A shipping refund uses the shipping refund item, else the shipping item, else the generic refund item: at least one must be set in Settings › SAGE items. Then press Try again.

Full guide: /manual/en/problems/refund_item_missing

"No original document". The refund was made at a zrsPOS till, but zrsPOS issued no document for that order: a sale from before go-live, or invoiced elsewhere. It shows once and is never retried. Issue the credit note by hand in SAGE, against the original invoice, then press I issued it by hand in SAGE. Refunds of such orders made outside zrsPOS stores (the warehouse, the online shop) are skipped and never shown.

Full guide: /manual/en/problems/no_original_document

"Waiting for the sale's invoice". The return arrived before the sale's invoice was issued (SAGE was slow or down, and the sale is still being retried). Nothing to do: the credit note issues by itself as soon as the invoice does. Do not issue it by hand.

Full guide: /manual/en/problems/awaiting_original

"The exchange waits for the return's credit note". An exchange made at the till issues two documents: the credit note for the item returned and the invoice for the new one. The invoice waits for the credit note, which was not issued yet: Shopify sends the refund a few minutes after the exchange, or SAGE was slow and the credit note is being retried. Nothing to do: the invoice issues by itself as soon as the credit note does. Do not issue it by hand. If the exchange was not made at a till (it was handled in the Shopify admin, where the online shop invoices it), press Archive order #….

Full guide: /manual/en/problems/awaiting_return_credit

"Could not read the exchange". To invoice the new item of an exchange, zrsPOS reads the return from Shopify. That read failed (Shopify did not answer, or zrsPOS had no access at that moment). The job is kept and tried again by itself; nothing is lost. If it persists, open the app once in the Shopify admin to renew its access, then press Try again.

Full guide: /manual/en/problems/exchange_lookup

"Could not read the original invoice in SAGE". To issue the credit note to the same customer and by the same payment method as the sale, zrsPOS reads the original invoice in SAGE. SAGE did not answer (or did not find it), and zrsPOS does not issue the credit note on a guess — to "Consumidor Final", with the default SAGE payment method. It retries by itself within minutes. If it persists, check in SAGE that the original invoice exists.

Full guide: /manual/en/problems/original_unreadable

"The issuer NIF is missing". zrsPOS reads the company name and NIF from SAGE and stores them when the connection is tested (Settings › SAGE connection). If SAGE does not answer and nothing is stored, zrsPOS neither prints nor sends the document — a fiscal document without the company NIF is not valid. The receipt waits and is tried again by itself for a few minutes. Test the connection there and reprint from the POS.

Full guide: /manual/en/problems/issuer_nif_missing

"Store credit has no SAGE payment method". The sale was paid, fully or partly, with store credit, and the shop records that credit as a voucher in SAGE. For that, store credit (shopify_store_credit) must be mapped on Settings › Payments to the SAGE voucher payment method (for example "N.Cred-Reembolso"). zrsPOS does not guess: that method's number differs from one company to the next. Map it and press Try again.

Full guide: /manual/en/problems/store_credit_tender

"The store-credit voucher is for another credit note". A sale was paid with store credit at a store whose own credit-note série issues another type of credit note than the SAGE voucher pays (for example the voucher pays "NRE" and the store issues "NC"). The sale still issues, but SAGE picks the voucher by the type of the document redeemed. Give that store its own voucher on Payments → Store credit.

Full guide: /manual/en/problems/voucher_wrong_doc

"Would credit the invoice past its total". zrsPOS credit notes already credit this invoice (for example the exchange it came from), and this return would credit it again. It happens when an exchange's replacement invoice was never issued and was archived. Check the order, issue the right correction by hand in SAGE and press Archive order #….

Full guide: /manual/en/problems/already_credited

"Value-only refund of a Tax Free sale". A refund with no items on a Tax Free sale: zrsPOS cannot tell which part belongs to the exempt goods and which to the deposit (caução). Issue the credit note by hand in SAGE, void or correct the Tax Free form, and press I issued it by hand in SAGE.

Full guide: /manual/en/problems/taxfree_value_refund

"The money refunded is not the value of the returned goods". Extra money was refunded on top of the items, or the refund was lowered in Shopify outside a return (from the order, not through Return), so what went back to the customer differs from the value of the returned goods. A refund made through a return (an exchange, or a return whose refund was lowered) is not checked here. zrsPOS does not issue the credit note: it would credit, and book as paid out, the goods' value instead of what was refunded. Check the order, issue the right credit note by hand in SAGE and press I issued it by hand in SAGE. Try again does not change the outcome while the refund stays as it is.

Full guide: /manual/en/problems/refund_discrepancy

"Refund with no items and no money completed". Shopify reported a refund that names no items and had no completed money when it arrived — usually a card or PayPal refund still pending at that moment. Shopify does not report again once it completes, so zrsPOS issues nothing. If money did go back to the customer, issue the credit note by hand in SAGE against the document named in the message, then press I issued it by hand in SAGE; if nothing was refunded, just archive it. Try again does not change the outcome. (The same refund on an order zrsPOS never invoiced — an online order refunded from the Shopify admin — is not ours and is skipped without showing here.)

Full guide: /manual/en/problems/nothing_to_credit

"The SAGE codes for Tax Free are missing". The sale, or its return, is Tax Free and one of the SAGE codes for Tax Free is missing (the deposit item, the exempt group, or the VAT rate of the store’s zone). Set it and press Try again.

Full guide: /manual/en/problems/taxfree_unconfigured

"The store’s VAT zone is not known yet". The sale, or its return, is Tax Free, zrsPOS has not read the store’s Shopify address yet, and the Tax Free rates differ by zone. Open the admin (it reads the addresses) and press Try again; zrsPOS also retries by itself.

Full guide: /manual/en/problems/taxfree_zone_unknown

"Tax Free sale with shipping". A Tax Free sale cannot include shipping: services are not eligible. Charge shipping in a separate sale. This one must be issued by hand, or rung up again without shipping.

Full guide: /manual/en/problems/taxfree_shipping

"The shipping item is missing". The sale charges shipping and the shipping item is not set in Settings › SAGE items. Set it and press Try again.

Full guide: /manual/en/problems/shipping_item_missing

"Not paid". The order was not paid yet when it arrived. The document issues once the payment completes. If the sale was cancelled, press Archive order #….

Full guide: /manual/en/problems/not_paid

"The order has no items". For example a gift card only, or a voided sale. There is no document to issue; press Archive order #….

Full guide: /manual/en/problems/no_line_items

"SAGE lookup failed". SAGE did not answer a lookup zrsPOS needs before issuing (the online invoice, or the credit notes already issued). It retries by itself. If it persists, SAGE is slow or down.

Full guide: /manual/en/problems/sage_lookup_failed

"Stale — reaped". The server restarted mid-issuance. The retry first looks in SAGE for a document that may already have been issued, so there is no duplicate. It retries by itself.

Full guide: /manual/en/problems/stale_reaped

"Automatic retries have ended". zrsPOS tries to issue a failed sale twice, right after the sale, and then stops trying by itself (and tells you by e-mail and on the POS, with the cause): fix the cause shown and press "Retry" in Documents (or on the POS). Do not issue the document by hand in SAGE — it would be duplicated once you pressed "Retry".

Full guide: /manual/en/problems/retry_ended

"The payments do not add up to the total". The sale's payments do not add up to the document total, and zrsPOS will not issue an inconsistent document. It happens with unusual split payments. Contact support (support@zrspos.com) with the order number.

Full guide: /manual/en/problems/tender_mismatch

"Could not confirm whether the document already exists". SAGE may have issued the document on an earlier attempt without answering in time. This time zrsPOS could not confirm it, and it does not resend blind, to avoid a duplicate. It retries by itself within minutes. If it persists, SAGE is slow or down.

Full guide: /manual/en/problems/ghost_lookup

An error with no likely cause. SAGE returned a message zrsPOS does not recognise yet. Open Details for support, copy the request and the response, and send them to support@zrspos.com. Once the cause is fixed, press Try again.

Full guide: /manual/en/problems/unknown