List locations (yekar.square.list-locations) | Read | Every location on this Square account, with the ids that payments, orders, inventory and payment links are all scoped to - and the environment (production or sandbox) this connection reads. Locations can trade in DIFFERENT currencies, so amounts from two locations are not directly comparable. Run this first to confirm a connection works. |
List payments (yekar.square.list-payments) | Read | A page of card and cash payments, newest first, optionally for one location or time window. Read the amounts carefully: amount is the charge WITHOUT the tip, tip is separate, total is what the customer paid, refunded is what has gone back, and processingFee is Square's cut - null while a payment is unsettled, which is not the same as zero. Amounts are in minor units of the location's currency. |
Get payment (yekar.square.get-payment) | Read | One payment by id: status, amount, tip, total, how much has been refunded, Square's processing fee, the card brand and last four, and the receipt URL. This is the id Refund payment takes. |
List refunds (yekar.square.list-refunds) | Read | A page of refunds, newest first, optionally by location, status or time window. A PENDING refund has been accepted by Square but has not settled to the customer; REJECTED and FAILED mean the money stayed put. processingFeeReturned is the part of Square's fee that came back with it. |
Search orders (yekar.square.search-orders) | Read | Orders at one or more locations, filtered by state and creation window. Square requires the location ids, so nothing here silently searches only part of a multi-location business. Note an order's total does NOT drop when it is refunded - totalRefunded is reported beside it. Square's own default covers OPEN and COMPLETED orders only. |
Get order (yekar.square.get-order) | Read | One order with its line items (up to 25; lineItemsOmitted counts the rest), taxes, discounts, tip and refunds. Line quantities are decimal STRINGS because Square sells by weight as well as by unit. |
List customers (yekar.square.list-customers) | Read | A page of customer records. Note creationSource: Square creates an INSTANT_PROFILE customer automatically the first time a card is used, so most rows on a busy seller are card profiles rather than people who signed up. To find someone specific, use Search customers. |
Search customers (yekar.square.search-customers) | Read | Find customers by EXACT email, phone or your own reference id. This is exact matching, not a contains-search: a partial email returns nothing rather than the closest thing. Square allows several customers to share an email, so more than one row is a normal result. |
Get customer (yekar.square.get-customer) | Read | One customer by id, including the version that Update customer must send back - Square uses optimistic locking, so an update carrying a stale version is refused rather than overwriting someone else's change. |
Search catalog items (yekar.square.search-catalog-items) | Read | Search the Square catalogue by text, category or stock level. An ITEM carries the name and description; its VARIATIONS carry the price, SKU and inventory tracking - and it is the VARIATION id that Get inventory counts and Set inventory count take. A variation with pricingType: VARIABLE_PRICING has no price by design (the cashier enters it), so a null price there is a fact rather than missing data. |
Get inventory counts (yekar.square.get-inventory-counts) | Read | Stock counts for catalogue VARIATIONS, per location. Square returns one row per variation, location AND state - read only the IN_STOCK rows to answer 'how many can I sell'; SOLD, WASTE and RETURNED_BY_CUSTOMER are separate counts of other things and must not be summed with it. Quantities are decimal strings because Square sells by weight too. |
Refund payment (yekar.square.refund-payment) | Write | Refund a Square payment, fully or partially. Amounts are in MINOR units of the payment's own currency; omit the amount to refund whatever is left. This moves real money back to the customer and cannot be undone. The refund may come back PENDING - issued, but not yet settled to the customer. |
Create customer (yekar.square.create-customer) | Write | Create a customer record. Square does NOT deduplicate on email or phone - running this twice for the same person creates two records. Search first with Search customers, and set referenceId to your own id so the duplicate is findable if one is ever made. |
Update customer (yekar.square.update-customer) | Write | Update a customer's name, company, email, phone, reference id or note. Only the fields you pass change. Pass the version from Get customer to make this a safe compare-and-set: Square refuses the write if someone else changed the record in between, rather than silently overwriting them. |
Set inventory count (yekar.square.set-inventory-count) | Write | Record a physical stock count: set the ABSOLUTE quantity of catalogue variations at a location (not a delta). Square has no compare-and-set for inventory, so a sale that happens between reading the count and writing it WILL be overwritten - re-read immediately before writing. Takes VARIATION ids, not item ids. |
Create payment link (yekar.square.create-payment-link) | Write | Create a Square-hosted checkout link for a one-off amount and return its URL - a page the customer pays on themselves. This charges nobody: it produces a link. The amount is in MINOR units and its currency must match the location's. (This is Square's Quick Pay: an ad-hoc item and price, not a catalogue sale, so catalogue taxes and modifiers do not apply.) |