Events
Post business events. SYNC turns each into a balanced journal entry.
GET /eventsList eventsGET /events/{event_id}Get an eventPOST /events/{event_id}/bounceMark a payment as bouncedPOST /events/{event_id}/repostRe-post an event held for reviewPOST /events/repostRe-post events held for reviewPOST /events/salesPost a salePOST /events/refundsPost a refundPOST /events/daily-closesPost a daily closePOST /events/payoutsPost a processor payoutPOST /events/invoicesPost an invoicePOST /events/credit-notesPost a credit notePOST /events/credit-applicationsApply a customer's credit to invoicesPOST /events/credit-refundsPay a customer's credit outPOST /events/payments-receivedPost a customer paymentPOST /events/payment-refundsPost a refund of money receivedPOST /events/billsPost a vendor billPOST /events/bill-paymentsPost a bill paymentPOST /events/payroll-runsPost a payroll runPOST /events/inventory-movementsPost inventory movements
List events
GET /events
Sends Vortex-Entity.
Lists events posted to the entity, newest first. Requires events:read.
Parameters
| Name | In | Type | About |
|---|---|---|---|
limit | query | integer | |
starting_after | query | string | |
type | query | EventType | |
status | query | EventStatus | |
connection_id | query | string | |
external_id | query | string |
Answers
Get an event
GET /events/{event_id}
Sends Vortex-Entity.
Parameters
| Name | In | Type | About |
|---|---|---|---|
event_id required | path | string |
Answers
Mark a payment as bounced
POST /events/{event_id}/bounce
Sends Vortex-Entity and Idempotency-Key.
Takes back a posted customer or bill payment on the given date and reopens what it paid. Unlike reversing its entry, this works when the payment is already matched to a bank line, because the deposit did happen; the new entry matches the returned item on a later statement. Only whoever recorded the payment can do this. Requires events:write and journal:write.
Parameters
| Name | In | Type | About |
|---|---|---|---|
event_id required | path | string |
Body
| Field | Type | About |
|---|---|---|
date required | string (date) | |
reason required | string | Up to 500 characters. |
Answers
- 201 JournalEntry. The entry that took the payment back.
- 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
- 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
Re-post an event held for review
POST /events/{event_id}/repost
Sends Vortex-Entity and Idempotency-Key.
Runs a needs_review event's stored payload through the posting rules again, usually after its missing mapping has been set. It posts one balanced entry, with the same documents, inventory, refund tracking and webhooks as a first post, or stays in needs_review with an updated review_reason and errors, and nothing else changes. That includes checks a first post would reject outright, such as totals that don't add up or a closed period. Inventory is costed at the current average cost, or from the layers on hand under FIFO, not the cost on the event's date. Any other status answers 409 event_not_in_review, so an event can't post twice. Platforms can re-post only what their own connection sent; the entity's own keys can re-post any of its events. Requires events:write.
Parameters
| Name | In | Type | About |
|---|---|---|---|
event_id required | path | string |
Answers
Re-post events held for review
POST /events/repost
Sends Vortex-Entity and Idempotency-Key.
Re-posts needs_review events, oldest occurred_on first, with the same rules as re-posting one. Each event posts or stays in review on its own. Events that stay in review still come first on the next call, so continue with starting_after set to the last event returned. Platforms reach only what their own connection sent. Requires events:write.
Body
| Field | Type | About |
|---|---|---|
event_ids | list of string | Only these events. Those not in |
type | EventType | |
starting_after | string | |
limit | integer | Default: 100. |
Answers
Post a sale
POST /events/sales
Sends Vortex-Entity and Idempotency-Key.
A completed sale (ticket, order or receipt). Requires events:write.
Body
Answers
Post a refund
POST /events/refunds
Sends Vortex-Entity and Idempotency-Key.
A full or partial refund of an earlier sale, named by original_external_id. The sale must exist, come from the same connection and be posted (422 unknown_sale).
Omit lines to refund the whole sale, including its order discount, shipping and customer fees; taxes and tips default to the sale's. A partial refund reverses only what it lists. Tenders must equal the refund total (422 totals_mismatch).
Across all refunds of a sale, a line (matched by item_sku, else description) can't take back more quantity than was sold, nothing can be refunded that wasn't on the sale, and the money can't exceed the sale's tenders (422 over_refund). With restock, inventory lines go back at the cost the sale took out. Requires events:write.
Body
Answers
Post a daily close
POST /events/daily-closes
Sends Vortex-Entity and Idempotency-Key.
A day's sales summary for a location or register, for platforms that post totals instead of each sale. Do not post both a daily close and the individual sales for the same day and location; SYNC rejects the overlap with 409 overlapping_sales. Requires events:write.
Body
Answers
Post a processor payout
POST /events/payouts
Sends Vortex-Entity and Idempotency-Key.
A deposit from a card processor or marketplace, with its fees and adjustments. SYNC clears the matching sales from card clearing and records the fees. Requires events:write.
Body
Answers
Post an invoice
POST /events/invoices
Sends Vortex-Entity and Idempotency-Key.
An invoice issued to a customer, or a void of one.
A line whose item_sku is an inventory item must carry a positive quantity (422 quantity_required). It takes that stock out at average cost and posts cost of goods sold, as a sale does. Lines for other or unknown items move no stock. On a line with no category or account_id, the item's income account applies.
A void reverses the entry and puts the goods back at the cost they left at. Invoices with payments can't be voided (422 invoice_has_payments). Requires events:write.
Body
Answers
Post a credit note
POST /events/credit-notes
Sends Vortex-Entity and Idempotency-Key.
Money taken off what a customer owes, for a return, a price adjustment or a mistake, or a void of one. Its lines, tax and shipping are taken back from income, sales tax and shipping income on its own date, not the invoice's, so the sales tax return and economic nexus count it in the period it was given. applied_to settles the customer's open invoices now (422 overpayment past what one has open); the rest is kept as the customer's credit, to apply later with POST /events/credit-applications or pay out with POST /events/credit-refunds.
A line for an inventory item comes back into stock when restock is true (the default) and it carries a positive quantity (422 quantity_required): at what the invoice named in invoice_number took out (422 over_refund past what it sold, less earlier credits), or at the item's average cost without one. Set restock to false for goods not coming back.
A void reverses the credit note, everything applied from it and any stock it brought back: the invoices it settled are owed again. A credit note with any part paid out can't be voided (422 credit_paid_out). An invoice a credit settled part of can't be voided while the credit stands (422 invoice_has_payments). Requires events:write.
Body
Answers
Apply a customer's credit to invoices
POST /events/credit-applications
Sends Vortex-Entity and Idempotency-Key.
Part of a credit note's remaining credit applied to the same customer's open invoices (422 credit_exceeded past what's left). Requires events:write.
Body
Answers
Pay a customer's credit out
POST /events/credit-refunds
Sends Vortex-Entity and Idempotency-Key.
Part of a credit note's remaining credit paid out to the customer, from the account named in paid_from_account_id or the default for the method (card and ACH from the processor's clearing account, cash from undeposited funds, the rest from the operating bank account). 422 credit_exceeded past what's left. Requires events:write.
Body
Answers
Post a customer payment
POST /events/payments-received
Sends Vortex-Entity and Idempotency-Key.
Money received against one or more invoices. Requires events:write.
Body
Answers
Post a refund of money received
POST /events/payment-refunds
Sends Vortex-Entity and Idempotency-Key.
Money given back from a sale or customer payment this connection sent, by amount: for example a refund of an invoice payment, or a partial refund of a sale. It comes out of the account the original's money went into (card clearing for the processor, undeposited funds, or the payment's deposit_account_id). customer_fee, the part that gives back a fee the customer paid on top, comes off customer_fee_income. For a customer payment the rest gives back its unapplied credit first (customer_credits), then reopens the invoices it paid, in the order of applied_to (accounts_receivable, and the invoice's open balance goes back up). For a sale the rest is booked to sales_returns, and sales tax is not changed. To take back a sale's lines and restock items, use /events/refunds instead.
original_external_id must be a posted sale or payment from the same connection (422 unknown_payment). A sale paid more than one way can't be refunded this way (422 split_tenders). Refunds can't add up to more than was received, counting a sale's line refunds, nor give back more customer fee than was paid, nor more of a customer payment than it applied and left as credit (422 over_refund). An invoice voided since can't be reopened (422 invoice_void).
A platform that reconnects to the same business for the same external_tenant_id carries on where its earlier connection left off: what it sent before is still found by its external_id and invoice number. Requires events:write.
Body
Answers
Post a vendor bill
POST /events/bills
Sends Vortex-Entity and Idempotency-Key.
A bill received from a vendor, or a void of one.
Lines go to the account named by account_id, else to their category's mapping (an unmapped category holds the event in needs_review), else to the expense_default role. A line whose item_sku is an inventory item, with no account_id, receives stock into inventory and must carry a positive quantity (422 quantity_required). Tax is spread over all lines, and freight over inventory lines (landed cost).
Send stock arriving on a bill either as a bill line or as a receipt in /events/inventory-movements, never both, or it is counted twice.
A void reverses the entry and takes back the stock the bill received. Bills with payments can't be voided (422 bill_has_payments). Under FIFO, a bill whose units have already been partly sold or used can't be voided (422 stock_already_used); record a return to vendor instead. Requires events:write.
Body
Answers
Post a bill payment
POST /events/bill-payments
Sends Vortex-Entity and Idempotency-Key.
Records that bills were paid. SYNC records payments; it never moves money.
amount must equal the total of applied_to (422 totals_mismatch); there are no unapplied vendor credits. Paying more than a bill has open is 422 overpayment. Cash comes out of the undeposited_funds role and every other method out of operating_bank. Requires events:write.
Body
Answers
Post a payroll run
POST /events/payroll-runs
Sends Vortex-Entity and Idempotency-Key.
An approved payroll run: wages, employee and employer taxes, deductions, benefits and net pay, optionally split by dimension. Requires events:write.
Body
Answers
Post inventory movements
POST /events/inventory-movements
Sends Vortex-Entity and Idempotency-Key.
Stock received, adjusted, transferred, written off or returned to a vendor. Sales and invoices deplete stock through their own events, not here.
Every item must already exist as an inventory item (422 unknown_item, 422 not_inventory_item). Receipts and transfers take positive quantities; damage, loss, expired, return_to_vendor and consumption take negative ones; adjustments take either. Stock is costed at weighted average cost, or first in, first out for a business that chose FIFO before any stock moved.
Receipts and returns to vendor post against accounts_payable; adjustments, damage, loss and expiry against inventory_shrinkage; consumption against cost of goods sold. A transfer changes no value, so an event of only transfers is posted with a null journal_entry_id. Requires events:write.

