Square POS private data API: payments, orders, catalog

Block, Inc. · Payments

Square Point of Sale is the free register app from Block, Inc., the company founded as Square by Jack Dorsey and Jim McKelvey in 2009, and it turns an Android phone or tablet paired with a Square Reader into a checkout for card, contactless, cash and digital-wallet payments. Sellers ring up sales from a keypad or a visual browse grid built from their item library of items, variations and categories, keep open tickets for bar tabs and table service with pre-authorized holds they complete later, and issue full or partial refunds from the refund screen. Order Manager lists open, fulfilled and refunded orders searchable by location, employee and payment state, and transaction history covers every sale, including payments taken offline and captured afterwards. Beyond checkout, the register bundles a loyalty program that accrues and redeems points at the counter, a customer directory with per-buyer profile cards, per-variation inventory tracking that hides sold-out items, a business profile shared with receipts and the Square Online storefront, and a banking applet for the Square Checking debit card, balances, instant deposits and payout reports. It serves US sellers, from cafes and bars to retail counters and mobile vendors, and competes with Clover, Toast and Shopify POS for small-business checkout.

Tenders rung up at the register become payment records carrying amount_money, tip_money, tax_money, payment.source_type and a payment.receipt_number, tied by location_id, order_id and customer_id to the rest of the merchant's books. Pre-authorized tab holds add payment.approved_money when completed, reloaded payments expose capture state and card brand through payment.card_details, and refunds record the original payment_id, a reason and the team_member_id who issued them.

Tickets add the order layer: order.line_items, order.total_money and order.state, searchable by employee_ids and payment_statuses. The item library returns catalog objects with their related_objects, and per-variation stock flags, statuses.tracking_enabled and statuses.sold_count, mark what is tracked and what has sold at each location.

Around the sale sit buyer and merchant records: loyalty accounts with loyalty_account.balance, loyalty_account.enrollment_type and redeemed coupon.discount_money; directory customers with given_name, email_address and phone_number; a business profile with entity.mcc, entity.business_type and entity.iana_time_zone; and Square Checking money with balance_header.available_balance, balance_header.pending_balance and pending deposits carrying pending_settlement_report.net_money and pending_settlement_report.status.

ERP and accounting teams pull completed tickets with amounts, tips, locations and line items into a nightly ledger reconciled against their books; kiosks and second screens look up a buyer's points by loyalty token and post a redemption so the discount lands on the open ticket before capture; treasury tools watch available balance, pending deposits and fees without opening the register; and online storefronts mirror the item library and per-variation stock flags so sold-out variations disappear from both the keypad and the web shop. openData Studio makes these register, loyalty and Checking records callable open data for exactly those integrations.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

Create checkout charge

POST /v1/checkout/charge openbanking

Charges a card, contactless, cash or wallet tender at the register. The charge call is the wire behind the checkout flow and returns the payment id, amounts, status and receipt used on the success screen.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token, JSON body).

source_id
idempotency_key
amount_money
tip_money
tax_money
location_id
order_id
customer_id
autocomplete
payment.id
payment.status
payment.source_type
payment.receipt_number

POST /v1/checkout/charge HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "source_id": "cnon:card-nonce-ok",
  "idempotency_key": "pay-7f3a9c2e",
  "amount_money": {"amount": 1299, "currency": "USD"},
  "tip_money": {"amount": 200, "currency": "USD"},
  "location_id": "LXXXXXXXXXXXX",
  "order_id": "OrdXXXXXXXXXXXX",
  "customer_id": "CXXXXXXXXXXXX",
  "autocomplete": true,
  "note": "Table 12"
}

{
  "payment": {
    "id": "NpyXwGPzL9X5kXgT0example",
    "created_at": "2026-09-27T14:03:11.000Z",
    "updated_at": "2026-09-27T14:03:12.000Z",
    "amount_money": {"amount": 1299, "currency": "USD"},
    "tip_money": {"amount": 200, "currency": "USD"},
    "tax_money": {"amount": 104, "currency": "USD"},
    "status": "COMPLETED",
    "source_type": "CARD",
    "location_id": "LXXXXXXXXXXXX",
    "order_id": "OrdXXXXXXXXXXXX",
    "customer_id": "CXXXXXXXXXXXX",
    "receipt_number": "NpyX",
    "receipt_url": "https://merchant-receipts.example/preview/NpyXwGPzL9X5kXgT0example"
  }
}

Get checkout charge

GET /v1/checkout/charge/{charge_id} openbanking

Reloads a single payment by id so the POS can show capture state, card brand/last-4, amounts and the linked order after an offline or delayed-capture checkout.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

payment.id
payment.created_at
payment.updated_at
payment.amount_money
payment.tip_money
payment.status
payment.location_id
payment.order_id
payment.customer_id
payment.card_details
errors

GET /v1/checkout/charge/NpyXwGPzL9X5kXgT0example HTTP/1.1
Authorization: Bearer <merchant-session>

{
  "payment": {
    "id": "NpyXwGPzL9X5kXgT0example",
    "created_at": "2026-09-27T14:03:11.000Z",
    "updated_at": "2026-09-27T14:03:12.000Z",
    "amount_money": {"amount": 1299, "currency": "USD"},
    "tip_money": {"amount": 200, "currency": "USD"},
    "status": "COMPLETED",
    "location_id": "LXXXXXXXXXXXX",
    "order_id": "OrdXXXXXXXXXXXX",
    "customer_id": "CXXXXXXXXXXXX",
    "card_details": {"status": "CAPTURED", "card": {"card_brand": "VISA", "last_4": "1111"}}
  },
  "errors": []
}

Capture authorized charge

POST /v1/checkout/charge/{charge_id}/capture openbanking

Captures a previously authorized (delayed-capture / pre-auth) payment when the seller taps Complete on the ticket — used for bar tabs and hotel-style holds.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

version_token
payment.id
payment.status
payment.amount_money
payment.approved_money
payment.location_id
payment.order_id

POST /v1/checkout/charge/NpyXwGPzL9X5kXgT0example/capture HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "version_token": "payver_8c21"
}

{
  "payment": {
    "id": "NpyXwGPzL9X5kXgT0example",
    "status": "COMPLETED",
    "amount_money": {"amount": 1299, "currency": "USD"},
    "approved_money": {"amount": 1299, "currency": "USD"},
    "location_id": "LXXXXXXXXXXXX",
    "order_id": "OrdXXXXXXXXXXXX"
  }
}

Create refund

POST /v1/billing/refunds openbanking

Issues a full or partial refund against a completed payment from the POS refund screen, carrying the original payment_id, amount_money and optional reason.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

idempotency_key
amount_money
payment_id
order_id
reason
location_id
team_member_id
refund.id
refund.status
refund.created_at

POST /v1/billing/refunds HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "idempotency_key": "ref-aa12",
  "amount_money": {"amount": 1299, "currency": "USD"},
  "payment_id": "NpyXwGPzL9X5kXgT0example",
  "order_id": "OrdXXXXXXXXXXXX",
  "reason": "Customer returned item",
  "location_id": "LXXXXXXXXXXXX",
  "team_member_id": "TMxxxxxxxx"
}

{
  "refund": {
    "id": "NpyXwGPzL9X5kXgT0example_r1",
    "status": "COMPLETED",
    "amount_money": {"amount": 1299, "currency": "USD"},
    "payment_id": "NpyXwGPzL9X5kXgT0example",
    "order_id": "OrdXXXXXXXXXXXX",
    "location_id": "LXXXXXXXXXXXX",
    "reason": "Customer returned item",
    "created_at": "2026-09-27T15:10:00.000Z"
  }
}

Query tickets

POST /v1/tickets/query opendata

Powers the Order Manager / tickets list: paginated search of open, fulfilled and refunded orders filtered by location, employee, payment state and free-text term.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

merchant_id
location_ids
limit
cursor
search_term
include_refund_orders
employee_ids
payment_statuses
orders
status
localized_prompt_title

POST /v1/tickets/query HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "merchant_id": "MLXXXXXXXXXXXX",
  "location_ids": ["LXXXXXXXXXXXX"],
  "limit": 25,
  "cursor": "",
  "search_term": "Table 12",
  "include_refund_orders": false
}

{
  "status": {"success": true},
  "orders": [
    {
      "id": "OrdXXXXXXXXXXXX",
      "location_id": "LXXXXXXXXXXXX",
      "state": "OPEN",
      "total_money": {"amount": 1499, "currency": "USD"},
      "created_at": "2026-09-27T13:55:00.000Z"
    }
  ],
  "cursor": "eyJvIjoiT3JkIn0",
  "localized_prompt_title": "",
  "localized_prompt_description": ""
}

Get ticket

POST /v1/tickets/get opendata

Loads a single ticket/order by id for the order-detail view, including line items, totals and whether returns should be resolved into the payload.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

order_id
resolve_returns
client_support
order.id
order.location_id
order.state
order.line_items
order.total_money
order.customer_id

POST /v1/tickets/get HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "order_id": "OrdXXXXXXXXXXXX",
  "resolve_returns": true
}

{
  "order": {
    "id": "OrdXXXXXXXXXXXX",
    "location_id": "LXXXXXXXXXXXX",
    "state": "COMPLETED",
    "line_items": [
      {"name": "Latte", "quantity": "1", "total_money": {"amount": 550, "currency": "USD"}}
    ],
    "total_money": {"amount": 1499, "currency": "USD"},
    "customer_id": "CXXXXXXXXXXXX"
  }
}

Query catalog objects

POST /v1/library/query opendata

Searches the merchant item library (items, variations, categories) that populates the POS keypad, visual browse grid and payment-link item picker.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

object_types
include_related_objects
include_deleted_objects
include_inventory
include_counts
limit
cursor
query
objects
related_objects

POST /v1/library/query HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "object_types": ["ITEM", "ITEM_VARIATION", "CATEGORY"],
  "include_related_objects": true,
  "include_deleted_objects": false,
  "include_inventory": true,
  "limit": 50,
  "cursor": ""
}

{
  "objects": [
    {
      "type": "ITEM",
      "id": "ITEM_LATTE",
      "updated_at": "2026-09-20T18:00:00.000Z",
      "item_data": {"name": "Latte", "variations": [{"id": "VAR_LATTE_SM", "item_variation_data": {"name": "Small", "price_money": {"amount": 450, "currency": "USD"}}}]}
    }
  ],
  "related_objects": [],
  "cursor": ""
}

Get rewards account

POST /v1/rewards/account openfinance

Looks up a buyer's loyalty account by token so the register can show points balance, enrollment type and contact mapping before accrue or redeem.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

loyalty_account_token
options
loyalty_account.balance
loyalty_account.contact
loyalty_account.enrolled_at
loyalty_account.enrollment_type
loyalty_account.mappings
status
errors

POST /v1/rewards/account HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "loyalty_account_token": "LoyAccXXXXXXXX"
}

{
  "loyalty_account": {
    "loyalty_account_token": "LoyAccXXXXXXXX",
    "created_at": "2024-03-12T00:00:00Z",
    "enrolled_at": "2024-03-12T10:15:00Z",
    "balance": 420,
    "enrollment_type": "PHONE",
    "contact": {"name": "Alex Rivera", "phone_number": "+14155550123"},
    "mappings": [{"type": "PHONE", "value": "+14155550123"}]
  },
  "status": "SUCCESS",
  "errors": []
}

Redeem reward

POST /v1/rewards/redeem openfinance

Redeems a loyalty reward against the current ticket, returning a coupon token and the updated points balance used on the checkout discount row.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

loyalty_account_token
phone_token
coupon_definition_token
return_coupon_token
idempotence_token
coupon.coupon_token
coupon.discount_money
loyalty_account.balance

POST /v1/rewards/redeem HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "loyalty_account_token": "LoyAccXXXXXXXX",
  "coupon_definition_token": "CpnDef$5OFF",
  "idempotence_token": "redeem-9f2"
}

{
  "coupon": {
    "coupon_token": "CpnXXXXXXXX",
    "discount_money": {"amount": 500, "currency": "USD"},
    "name": "$5 off"
  },
  "loyalty_account": {
    "loyalty_account_token": "LoyAccXXXXXXXX",
    "balance": 170
  }
}

Get business profile
GET /v1/business/profile osint
Returns the signed-in merchant's public profile — legal/doing-business-as name, address, MCC, timezone, contact channels and published flag — used by settings, receipts and the online storefront.
Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).
- entity.name
- entity.nickname
- entity.business_type
- entity.country_code
- entity.street1
- entity.city
- entity.state
- entity.postal_code
- entity.phone
- entity.email
- entity.website
- entity.mcc
- entity.iana_time_zone
- entity.published
- entity.mobile_business
```
GET /v1/business/profile HTTP/1.1
Authorization: Bearer <merchant-session>
```
```
{
  "entity": {
    "name": "River Cafe",
    "nickname": "rivercafe",
    "business_type": "FOOD_AND_DRINK",
    "country_code": "US",
    "street1": "500 3rd St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94107",
    "phone": "+14155550100",
    "email": "[email protected]",
    "website": "https://rivercafe.example",
    "mcc": "5812",
    "iana_time_zone": "America/Los_Angeles",
    "published": true,
    "mobile_business": false
  },
  "success": true
}
```

Banking card and account details

POST /v1/banking/card-account openbanking

Loads the merchant debit-card and checking-account details (masked PAN, routing, available balance, card status) for the banking applet inside the POS.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

card_details
card_details.last_4
card_details.status
card_details.available_balance
error

POST /v1/banking/card-account HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "instrument_token": "inst_chk_01"
}

{
  "card_details": {
    "last_4": "4421",
    "card_brand": "VISA",
    "status": "ACTIVE",
    "account_number_last_4": "8901",
    "routing_number": "121000248",
    "available_balance": {"amount": 482350, "currency": "USD"}
  },
  "error": null
}

Banking balance summary
POST /v1/banking/balance-summary openbanking
Returns the Balance tab header — available and pending balances for the merchant checking account and instant-deposit features — that the POS banking applet renders at the top of the screen.
Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).
- balance_header
- balance_header.available_balance
- balance_header.pending_balance
- balance_header.instrument_token
- error_message
```
POST /v1/banking/balance-summary HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "client_capability": {"capable_header_type": "BALANCE"}
}
```
```
{
  "balance_header": {
    "available_balance": {"amount": 482350, "currency": "USD"},
    "pending_balance": {"amount": 12500, "currency": "USD"},
    "instrument_token": "inst_chk_01",
    "title": "Checking"
  },
  "error_message": null
}
```

Pending payouts report

POST /v1/banking/settlements/pending openfinance

Lists the current sales batch and pending bank deposits (gross, fees, net, status) that power the POS deposits / payouts report.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

request_params
active_sales_report
pending_settlement_report
pending_settlement_report.settlement_id
pending_settlement_report.net_money
pending_settlement_report.status

POST /v1/banking/settlements/pending HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "request_params": {"location_id": "LXXXXXXXXXXXX"}
}

{
  "active_sales_report": {
    "settlement_id": "setl_today",
    "gross_money": {"amount": 184250, "currency": "USD"},
    "net_money": {"amount": 178900, "currency": "USD"},
    "fee_money": {"amount": 5350, "currency": "USD"}
  },
  "pending_settlement_report": [
    {
      "settlement_id": "setl_2026-09-26",
      "initiated_at": "2026-09-26T23:00:00Z",
      "net_money": {"amount": 96210, "currency": "USD"},
      "status": "PENDING"
    }
  ]
}

Stock tracking status
POST /v1/stock/tracking-status opendata
Returns per-variation inventory-tracking flags for a location so the POS can show stock counts, hide sold-out items and decide whether a sale should decrement inventory.
Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).
- location_id
- statuses
- statuses.catalog_object_id
- statuses.tracking_enabled
- statuses.sold_count
```
POST /v1/stock/tracking-status HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "location_id": "LXXXXXXXXXXXX"
}
```
```
{
  "statuses": [
    {
      "catalog_object_id": "VAR_LATTE_SM",
      "location_id": "LXXXXXXXXXXXX",
      "tracking_enabled": true,
      "sold_count": 42
    }
  ]
}
```

Update customer

PUT /v1/customers/{customer_id} osint

Updates a directory customer from the POS CRM card (name, email, phone, note) after a sale or from the customer-profile screen.

Auth: Logged-in merchant session over an authenticated HTTP API client (Bearer session token).

given_name
family_name
email_address
phone_number
note
version
customer.id
customer.created_at
customer.updated_at

PUT /v1/customers/CXXXXXXXXXXXX HTTP/1.1
Authorization: Bearer <merchant-session>
Content-Type: application/json

{
  "given_name": "Alex",
  "family_name": "Rivera",
  "email_address": "[email protected]",
  "phone_number": "+14155550123",
  "note": "Prefers oat milk",
  "version": 7
}

{
  "customer": {
    "id": "CXXXXXXXXXXXX",
    "given_name": "Alex",
    "family_name": "Rivera",
    "email_address": "[email protected]",
    "phone_number": "+14155550123",
    "note": "Prefers oat milk",
    "created_at": "2024-01-08T16:00:00.000Z",
    "updated_at": "2026-09-27T14:20:00.000Z",
    "version": 8
  }
}

Where teams use this data

POS sales ledger into an ERP
Nightly jobs call the charge-creation and ticket-query endpoints to pull completed tickets with amount_money, tip_money, location_id and order line items, then reconcile them against the merchant's accounting system.
Loyalty balance at the register
A kiosk or second-screen flow looks up the rewards-account endpoint by token, shows the points balance, and posts a reward redemption so the discount lands on the open ticket before capture.
Square Checking cash-flow monitor
Treasury tools read the balance-summary and pending-payouts endpoints to watch available_balance, pending deposits and fee_money without opening the POS UI.
Catalog and stock sync for a second channel
An online storefront mirrors the POS item library via the catalog-query endpoint and per-variation stock-tracking flags so sold-out variations disappear from both the keypad and the web shop.

Frequently asked questions

What payment fields does Square Point of Sale send at checkout?

The checkout charge call carries source_id, idempotency_key, amount_money, tip_money, tax_money, location_id, order_id and customer_id, and returns a payment id, status and receipt_number for the success screen.

How does the app load open tickets and order history?

Order Manager posts a ticket query with merchant_id, location_ids, limit, cursor and search_term, then loads a single ticket by order_id to render line items and totals in the detail view.

Can I read checking balances from the same API surface?

Yes. The banking applet calls a balance-summary endpoint for available and pending balances and a card-account endpoint for masked card, routing and status data.

Where does loyalty live relative to payments?

Loyalty is a separate rewards service: an account lookup returns the loyalty_account_token, balance and contact mappings, and a redemption call attaches a coupon to the current ticket before the payment is captured.

Apps similar to Square Point of Sale: Payment

Clover POS — Fiserv's Clover is an all-in-one register with terminals, an app marketplace, and the option to use third-party processors rather than Square's in-house payments.
Shopify POS — Shopify POS is the in-store register for Shopify merchants, syncing inventory and catalog across an online storefront and physical checkout.
Toast POS — Toast is a restaurant-focused POS with kitchen displays, table management, online ordering and labor tools that Square's general-purpose register does not specialize in.
Lightspeed Retail — Lightspeed Retail is a cloud POS for multi-location stores with supplier catalogs, item variants, barcode printing and inventory reports beyond Square's basic stock tools.
Helcim POS — Helcim is a no-monthly-fee POS on interchange-plus pricing, with invoicing, inventory and CRM aimed at merchants who want a dedicated merchant account instead of Square's flat-rate stack.
PayPal POS — PayPal Point of Sale (formerly Zettle) is a no-contract mobile register with a free app and card reader that also accepts Venmo at in-person checkout.
SumUp — SumUp is a low-overhead mobile card reader and app for pop-up and on-the-go sellers who need card acceptance without a full Square-style register.
Stripe — Stripe is a payments platform with customizable online checkout and APIs, used as an alternative when a business wants developer-built flows rather than Square's packaged POS.

More Payments apps

Topics

Square Point of Sale API
Square POS payments endpoint
Square checkout charge API
Square order manager tickets query
Square loyalty rewards account
Square Checking balance summary
Square pending payouts report
Square catalog item library
Square merchant business profile

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

Square POS private data API: payments, orders, catalog

Screenshots

API surface

Create checkout charge

Get checkout charge

Capture authorized charge

Create refund

Query tickets

Get ticket

Query catalog objects

Get rewards account

Redeem reward

Get business profile

Banking card and account details

Banking balance summary

Pending payouts report

Stock tracking status

Update customer

Data categories

Where teams use this data

POS sales ledger into an ERP

Loyalty balance at the register

Square Checking cash-flow monitor

Catalog and stock sync for a second channel

Frequently asked questions

Apps similar to Square Point of Sale: Payment

More Payments apps

BharatPe for Business

BrasilCard Cliente

C3Pay

Cartão Mais!

Topics

Need this app's data API integrated?

Square POS private data API: payments, orders, catalog

Screenshots

API surface

Create checkout charge

Get checkout charge

Capture authorized charge

Create refund

Query tickets

Get ticket

Query catalog objects

Get rewards account

Redeem reward

Get business profile

Banking card and account details

Banking balance summary

Pending payouts report

Stock tracking status

Update customer

Data categories

Where teams use this data

POS sales ledger into an ERP

Loyalty balance at the register

Square Checking cash-flow monitor

Catalog and stock sync for a second channel

Frequently asked questions

Related apps

Apps similar to Square Point of Sale: Payment

More Payments apps

BharatPe for Business

BrasilCard Cliente

C3Pay

Cartão Mais!

Topics

Need this app's data API integrated?