Square POS private data API: payments, orders, catalog

Block, Inc. · Payments

Square Point of Sale is the register app merchants use to take card, contactless, cash and wallet payments. Behind checkout it creates charges, queries open tickets and order history, and reads loyalty balances, checking-account figures and pending payouts from the same authenticated merchant session. The surface below is an illustrative map of that data API.

Square Point of Sale is Block's in-person checkout app for card, contactless, cash and wallet tenders. Behind the register, ticket, catalog, loyalty, checking and deposits screens it exchanges authenticated JSON calls carrying payments, orders, catalog objects, loyalty accounts, inventory tracking and merchant balance data.

Screenshots

API surface

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

Illustrative example reconstructed from the app's interface — not a live capture.

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"
  }
}

Derived from the app's interface; endpoint details are illustrative, not a live capture.

Reconstructed from the app's checkout and tender-selection flow
Matches the fields shown on the post-sale success and receipt screens

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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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": []
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the transaction-history and payment-detail screens
- Corresponds to the delayed-capture status check after offline checkout
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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"
  }
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the open-ticket Complete action
- Matches the pre-auth / bar-tab hold flow in the register UI

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

Illustrative example reconstructed from the app's interface — not a live capture.

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"
  }
}

Derived from the app's interface; endpoint details are illustrative, not a live capture.

Reconstructed from the transaction-list refund flow
Matches the fields collected on the refund confirmation screen

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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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": ""
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the Order Manager tickets list and its filters
- Matches the paginated result set behind the order search bar
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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"
  }
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the order-detail screen opened from the tickets list
- Matches the line-item and totals rendering of a single ticket
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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": ""
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the item-library browse and keypad search flows
- Matches the item/variation/category objects rendered in the register grid
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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": []
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the loyalty lookup attached to a ticket
- Matches the points-balance card shown before accrue or redeem
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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
  }
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the reward-picker and discount-row flow at checkout
- Matches the coupon application and updated balance shown after redemption
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the business settings and receipt-branding screens
- Matches the merchant identity fields shown across receipts and the storefront
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the banking applet's card detail screen
- Matches the masked card and routing fields shown in the checking section
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the Balance tab header in the banking applet
- Matches the available/pending figures shown at the top of the banking screen
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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"
    }
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the deposits and payouts report screens
- Matches the gross/fee/net breakdown shown per settlement batch
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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
    }
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the stock badges and sold-out states on the keypad
- Matches the per-variation tracking flags consulted during a sale
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
Illustrative example reconstructed from the app's interface — not a live capture.
```
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
  }
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the customer directory edit flow
- Matches the contact fields editable on the customer-profile card

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.

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.

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

More Payments apps

inyad Konnash: Bookkeeping App

Paytm

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

More Payments apps

inyad Konnash: Bookkeeping App

Paytm

Topics

Need this app's data API integrated?