Square API
Run a full Square Sandbox sale: locations, catalog item, customer, order, card payment, delayed capture and refund.
PaymentsGuided#payments#orders#catalog#customers#refunds#pos
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Square's REST APIs run the commerce side of a Square seller account: business Locations, the Catalog of items and prices, Customers, Orders that itemise a sale, Payments that charge a card (or other source) and Refunds. This guided collection walks through a full sale in the Square Sandbox: set up a catalog item, create a customer, build and price an order, pay for it with a test card token, then refund it.
Get credentials
- Sign in or create a free account at https://developer.squareup.com/apps and open the Developer Console.
- Create an application (any name, for example "Example Store").
- Open the application's Credentials page and choose Sandbox at the top; copy the Sandbox Access token into
accessToken. A production token (Credentials > Production > Show) only works against the production host. - On the same page you can set the application's default API version; this collection pins one with the
Square-Versionheader instead.
Every Square sandbox account comes with a test seller and a default location; sandbox payments never move real money.
Docs: https://developer.squareup.com/docs/build-basics/access-tokens
Authentication
Authorization: Bearer {{accessToken}} on every request (set on the collection). A token from the wrong environment fails with UNAUTHORIZED. Apps acting for other sellers use OAuth (/oauth2/authorize and /oauth2/token); this collection uses a personal access token.
Versioning
Square versions the API by release date (YYYY-MM-DD). Each request here sends Square-Version: {{squareVersion}}. Without the header Square uses the default version set on the app's Credentials page. Check the current version at https://developer.squareup.com/docs/changelog/connect and update the variable when you have tested a newer one.
Base URLs
| Environment | Base URL |
|---|---|
| Sandbox | https://connect.squareupsandbox.com/v2 |
| Production | https://connect.squareup.com/v2 |
Variables and run order
Fill accessToken, then run the folders in order. 1. Start here saves locationId. 2. Catalog saves itemId and variationId. 3. Customers saves customerId. 4. Orders saves orderId and orderTotal. 5. Payments charges the order with the sandbox token cnon:card-nonce-ok and saves paymentId. 6. Refunds refunds part of it. Every create request generates a fresh idempotency_key in a pre-request script, so re-sending a request never charges twice. Amounts are integers in the smallest currency unit (350 = $3.50) and must use the location's currency (USD for a US sandbox seller).
Limits and pricing
The Sandbox is free. Production card processing fees depend on country and how the card is taken: https://squareup.com/us/en/payments/pricing. Square rate-limits API traffic and answers 429 with error code RATE_LIMITED; slow down and retry with backoff.
Common errors
Errors come back as {"errors": [{"category", "code", "detail", "field"}]}.
| code | Meaning | What to do |
|---|---|---|
| UNAUTHORIZED | Token missing, wrong, or for the other environment | Use the Sandbox token with the sandbox host. |
| INSUFFICIENT_SCOPES | OAuth token lacks a permission | Re-authorize with the needed scope. |
| NOT_FOUND | Unknown ID or wrong location | Re-run the request that saves the ID. |
| IDEMPOTENCY_KEY_REUSED | Same key sent with a different body | Generate a new key (the scripts do this). |
| GENERIC_DECLINE / CVV_FAILURE | Card declined (sandbox: a failure token) | Use cnon:card-nonce-ok or ask for another card. |
| RATE_LIMITED | Too many requests | Back off and retry. |
Links
- API reference: https://developer.squareup.com/reference/square
- Sandbox test values: https://developer.squareup.com/docs/devtools/sandbox/payments
- Payments: https://developer.squareup.com/docs/payments-api/overview
- Orders: https://developer.squareup.com/docs/orders-api/what-it-does
- Catalog: https://developer.squareup.com/docs/catalog-api/what-it-does
- OpenAPI spec: https://github.com/square/connect-api-specification
Endpoints 23
1. Start here
- GETList locations
/locationsLists the seller's business locations with id, currency, country, status and capabilities. A 200 proves the token and environment match. The first location's… - GETRetrieve the main location
/locations/mainReads one location; the special ID main returns the seller's main location without knowing its ID. Swap main for {{locationId}} to read a specific one. Useful…
2. Catalog
- POSTCreate a catalog item
/catalog/objectUpserts an ITEM with one ITEM_VARIATION (the sellable, priced version). New objects use temporary IDs starting with #; the response maps them to real IDs in… - GETList catalog items
/catalog/listLists catalog objects of the given types (comma-separated, for example ITEM,CATEGORY,TAX). Results are paged: pass the returned cursor to get the next page.… - POSTSearch catalog items
/catalog/search-catalog-itemsFinds items whose name, description, SKU or UPC contains text_filter, optionally limited to categories, locations or stock levels. Returns items plus a cursor… - GETRetrieve a catalog object
/catalog/object/{{itemId}}Reads one catalog object by ID (here itemId). With include_related_objects=true the response also carries the objects it refers to, such as its category,…
3. Customers
- POSTCreate a customer
/customersCreates a customer profile. At least one of given_name, family_name, company_name, email_address or phone_number is needed. reference_id can hold your own… - POSTSearch customers by email
/customers/searchSearches customer profiles with a filter, here an exact match on email_address (use fuzzy instead of exact for partial matches). Supports limit, cursor and… - GETRetrieve a customer
/customers/{{customerId}}Reads the profile saved in customerId, including its version (needed for optimistic-concurrency updates), group and segment memberships, and creation source.
4. Orders
- POSTCalculate an order (preview)
/orders/calculatePrices an order without saving it: line items, taxes, discounts and the total_money you would charge. Use it to show a cart total. Line items either reference… - POSTCreate an order
/ordersCreates an OPEN order at locationId for two coffees from the catalog plus an ad hoc gift-wrap line, linked to customerId. Saves orderId and the computed… - GETRetrieve an order
/orders/{{orderId}}Reads the order saved in orderId. After the payment completes, state becomes COMPLETED and tenders lists the payment; after a refund the refunds and… - POSTSearch orders
/orders/searchSearches orders across one or more location_ids (required) with filters on state, dates, fulfillment, source or customer, and a sort. Here: open orders at…
5. Payments
- POSTCreate a payment for the order
/paymentsCharges a payment source. In production source_id is a one-time token from the Web Payments or In-App Payments SDK; in the Sandbox use test tokens such as… - POSTTry a declined card
/paymentsSends the sandbox token cnon:card-nonce-declined to see how a decline looks: an error response with category PAYMENT_METHOD_ERROR and a code such as… - POSTAuthorize only (delayed capture)
/paymentsCreates a card payment with autocomplete: false, so the funds are only authorized and the payment stays APPROVED until you complete or cancel it. delay_action… - POSTComplete (capture) the payment
/payments/{{delayedPaymentId}}/completeCaptures an APPROVED payment so the money is actually taken; status becomes COMPLETED. Optional version_token guards against completing a payment that changed… - POSTCancel a payment
/payments/{{delayedPaymentId}}/cancelVoids a payment that is still APPROVED (not completed), releasing the authorization; status becomes CANCELED. It fails for a completed payment, so to try it… - GETGet a payment
/payments/{{paymentId}}Reads the payment saved in paymentId: status, amounts including refunded_money, card details, processing_fee once known, and refund_ids after refunds. - GETList payments
/paymentsLists payments, newest first by default, filtered by time range (begin_time/end_time, RFC 3339), location_id, card last_4, or total. Paged with cursor and…
6. Refunds
- POSTRefund a payment
/refundsRefunds money from a completed payment back to its source. amount_money may be less than the payment for a partial refund (here $5.00); reason is shown to the… - GETGet a refund
/refunds/{{refundId}}Reads the refund saved in refundId to follow its status from PENDING to COMPLETED, along with the processing fee returned and the linked payment and order. - GETList refunds
/refundsLists refunds for the seller, filtered by time range, location_id, status or source_type, newest first with sort_order=DESC. Paged with cursor and limit.
API details
- Base URL
https://connect.squareupsandbox.com/v2https://connect.squareup.com/v2- Authentication
- A bearer token in the Authorization header
- Operations
- 23 operations on 23 pathsPOST 13GET 10
- Main resources
- 1. Start here 22. Catalog 43. Customers 34. Orders 45. Payments 76. Refunds 3
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-18 - Links
- Documentation
How to test the Square API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Square API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “List locations” (GET /locations), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Square API?
Run a full Square Sandbox sale: locations, catalog item, customer, order, card payment, delayed capture and refund. It is listed under Payments and has 23 endpoints.
Who publishes the Square API?
It is listed from Square's public API description (an OpenAPI document), not published by Square on Swastik Codes. Anyone who controls squareup.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Square API?
Its description lists 2 base URLs: https://connect.squareupsandbox.com/v2, https://connect.squareup.com/v2. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the Square API?
With A bearer token in the Authorization header.
How many endpoints does the Square API have?
23 operations on 23 paths (13 POST, 10 GET). The largest groups are 1. Start here, 2. Catalog, 3. Customers, 4. Orders.
Is forking the Square API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.