Store orders

When an order is placed or paid, send it with POST /store_orders: the merchant (mer_…) and the order as the platform holds it (lines, taxes, shipping, fees, coupons, payment gateway, buyer). Tallio maps a paid order to a receipt or an invoice and issues it through the merchant’s connection in the key’s mode; a test key without a test connection issues through Tallio’s sandbox. An unpaid order is kept and skipped as order_not_paid: retry it once it is paid.

• One store order per order. Tallio keeps one per merchant, mode, platform and order id. Sending an order it already holds answers that store order with 200 and maps nothing again, so a resend after a lost answer is safe. Use an idempotency key per order too.
• Tallio maps, never the store. Taxes, rounding, payment methods and the buyer are read from the order with the merchant’s store settings. An order Tallio cannot map exactly is skipped with a reason, never issued on a guess.
• Read it back. GET /store_orders/{id} returns the status, the reason and its document, with the number and, in Greece, the MARK once issued. GET /store_orders lists the store orders of the key’s mode, newest first.

• pending: received, not yet mapped, or waiting to be sent.
• skipped: it maps to no document; reason says why.
• sent: its document was created and is on its way to the provider.
• issued: the document was issued.
• failed: the document was rejected, failed or cancelled, or Tallio could not create it; reason says why.

Every skipped or failed store order carries a machine reason and a detail sentence for the merchant (the table below). warnings lists what is worth knowing about an issued document: a rounding cent, a free line left out, the store’s default payment method used.

A skipped or failed store order that waits for the merchant has action_needed: true, and GET /store_orders?status=action_needed lists them, with the orders whose refund waits. Skips that need nothing (a test order, nothing to invoice, a French sale to report) stay off the list.

• Retry. When retryable is true, the cause was outside the order (no provider connected, a payment method to choose, the plan’s limit) and is now fixed: POST /store_orders/{id}/retry with the order as the platform holds it now. A failed document is sent again as it was. A retry never makes a second document.
• Mark handled. When the merchant issued the document by hand, POST /store_orders/{id}/mark_handled takes the order off the list; its reason stays. Send the reason the merchant saw: if it changed since, the answer is 409 invalid_state, so a newer outcome is never hidden unread.

Send each refund with POST /store_orders/{id}/refunds. Tallio credits exactly what was refunded with a credit note linked to the order’s document: the whole sale, its lines, or an amount on a single-rate sale. A refund sent before the order’s document is issued waits for it. A refund Tallio cannot match is skipped with a reason and waits for the merchant, who issues the credit by hand and marks it handled with POST /store_orders/{id}/refunds/{refundId}/mark_handled. The order’s refunds lists them, each with its credit note.

A buyer who wants an invoice gives their VAT number (in France, their SIREN, SIRET or VAT number) and company name. Captured at checkout, they travel in the order’s invoice_request. Asked for after checkout, on the order-received page or in the buyer’s account, they are saved with PUT /store_orders/{id}/invoice_request. The order can be named as platform:external_id before the store sent it, and then reads the request when it arrives. Once the order’s document is made, a request changes nothing (409 already_issued): the merchant reissues the document instead (the correct call below).

Before a Greek invoice is issued, Tallio looks the buyer’s number up in the VAT registry. A number that is not registered skips the order as buyer_vat_not_registered. When the registered name differs from the order’s, or the registry withholds it, or the store’s settings ask to confirm every invoice, the order waits as invoice_awaiting_confirmation:

• POST /store_orders/{id}/invoice_review returns the buyer as the invoice names them beside the registry’s answer. It changes nothing; show both to the merchant.
• When registry.confirmable is true, POST /store_orders/{id}/confirm_invoice with the order as it is now and registry_hash issues the invoice with the registered name and address. If the registry changed in between, the order waits again for a new review.

When the merchant edits an issued order, or the buyer’s details change, POST /store_orders/{id}/correct replaces the document with one mapped from the order as it is now. In Greece the original is cancelled in myDATA, or credited in full where it cannot be cancelled; in France it is credited in full and a new invoice is issued. POST /store_orders/{id}/cancel cancels a Greek document for a sale that did not happen; a French invoice is never cancelled, only corrected. The store order’s correctable and cancellable say what Tallio allows now; offer only those actions.

Tallio’s Shopify app and WooCommerce plugin call this action Reissue: the document is not edited, a new one with its own number is issued dated today, and the old one stays on record, cancelled or credited. Name it that way to merchants and ask them to change the order in the shop first.

French invoices and credit notes of store orders are numbered by Tallio, one unbroken series for invoices and one for credit notes, per mode and year, from the prefixes in the merchant’s store settings (PATCH /merchants/{id}/store_settings). A number given to a record that ends with no document is kept as a gap and listed in voided_numbers, so the series can be explained.

Tallio sends store_order.updated when a store order’s status, reason, handled mark, document or refunds change. Connecting a store creates its webhook endpoints, one per key, scoped to its merchant. Treat the event as a hint: check its signature, then read the store order back. A store whose host blocks inbound requests lists its recent store orders on a timer instead.

A store team issues live without a card on the Free plan, up to 50 documents a month, or on a paid store plan chosen by an owner in the dashboard. GET /store_usage returns the plan, the live documents counted this period and the cap, so the store can warn the merchant from 80% of it. Past the cap Tallio still issues 10% more; at that limit new orders are skipped as plan_cap_reached, which the merchant retries once the plan changes or the next period starts. Credit notes, corrections and test-mode documents are never counted.

When a buyer asks to be erased, POST /erasures with store_orders (their ord_… ids) removes the buyer’s personal data Tallio holds about each order: in its documents, its refunds’ credit notes and corrections, the buyer’s invoice request and the requests logged about it. The provider stays the archive of the issued documents.