Square Knowledge Patch

Square Knowledge Patch

Use this skill for Square API, SDK, catalog, inventory, order, payment, Terminal, Labor, location, reporting, and Web Payments work covered by the topics below. Read the reference file for the area being changed before choosing fields, endpoint names, status values, or migration steps.

Reference index

Breaking changes and deprecations

Replace Customer.cards

With Square API version 2025-01-23, Customer.cards is retired.

• Enumerate cards with ListCards?customer_id=....
• Enumerate gift cards with ListGiftCards?customer_id=....
• CreateCustomerCard and DeleteCustomerCard remain deprecated; no retirement date is given for them here.

Move from Reader SDK

Reader SDK and its Mobile Authorization API were scheduled for retirement on December 31, 2025. Migrate to Mobile Payments SDK and use its authorization methods.

Follow rewritten SDK migration guides

The rewritten SDK generations change class and method shapes and add auto-pagination:

Follow the migration guide for the relevant language when continuing API updates.

Use Timecard equivalents

All Shift endpoints, types, and webhooks are deprecated in favor of Timecard equivalents for create, update, delete, retrieve, and search. GetShift becomes RetrieveTimecard. In GraphQL, timecards replaces the deprecated shifts entry point.

Replace retired loyalty reward definitions

LoyaltyProgramRewardTier.definition is retired. Resolve reward discount details through pricing_rule_reference.

Remove retired inventory movement shapes

As of Square version 2026-07-15, cross-location movement is an ADJUSTMENT with from_location_id and to_location_id. The following are retired:

• TRANSFER
• InventoryTransfer
• RetrieveInventoryTransfer
• InventoryAdjustment.location_id

Responses can expose UNTRACKED plus Square-generated inferred and component adjustments.

Update Web Payments SDK integrations

As of October 1, 2025, Web Payments SDK integrations must run in a secure HTTPS context; insecure HTTP contexts are unsupported.

For ACH:

• ach() no longer requires redirectURI; transactionId is optional.
• Replace deprecated AchChargeTokenOptions.total with separate amount and currency arguments.
• Catch InvalidOptionError for a missing name. PlaidMissingNameError remains for backward compatibility but is no longer emitted.

Token status values now return strings. PaymentRequestEvent and MethodType are string-union types rather than enumerations.

Account for offline-payment retirement

CreatePayment.offline_payment_details was deprecated in August and scheduled for retirement on November 19, 2025.

High-use payment changes

Consolidated card tokenization

In Beta, Card.tokenize() supports a consolidated flow for payment processing, buyer verification, and storing, charging, or both charging and storing a card on file.

Payment diagnostics

• Payment.BuyNowPayLaterDetails.errors and Payment.DigitalWalletDetails.errors expose source-specific failures.
• The card nested under CardPaymentDetails adds created_at and disabled_at.
• New error codes are PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED, PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET, and AMOUNT_TOO_LOW.
• Failed Square gift-card payments always return GIFT_CARD_AVAILABLE_AMOUNT with INSUFFICIENT_FUNDS, even without partial authorization, on every Square API version.

Application-fee allocations

Payment.app_fee_allocations can distribute one application fee among up to three parties. For a refund of a payment that used allocations, set PaymentRefund.app_fee_allocations to control each party's contribution.

Card and wallet details

• Read-only Beta Card fields are hsa_fsa, issuer_alert, and issuer_alert_at; supported Mastercard cards can report ISSUER_ALERT_CARD_CLOSED.
• CreateCard accepts ZIP+4 billing postal_code values such as 12345-6789.
• CardPaymentDetails.wallet_type identifies Apple Pay payments.
• ElectronicMoneyDetails represents Japanese e-money payments and exposes felica_details for FeliCa.

High-use commerce changes

Catalog modifiers

Modifier-list selection constraints can live at list level. Nested modifier lists are available in Beta through CatalogModifier.child_modifier_list_ids. Set include_options on BatchRetrieveCatalogObjects, SearchCatalogItems, or SearchCatalogObjects to include related modifier lists.

Review Catalog, orders, and inventory for the complete new and deprecated modifier field map.

Inventory cost and reasons

In Beta, stock-receiving adjustments accept cost_money and vendor_id, and UpdateInventoryAdjustment can edit a past adjustment's quantity, cost_money, vendor_id, and reason_id. Writing cost or vendor data requires an active Retail Plus, Restaurants Plus, or Restaurants Premium subscription.

Beta adjustment reasons use InventoryAdjustment.reason_id and provide list, retrieve, create, update, delete, and restore operations under /v2/inventory/adjustment-reasons. Change history can be filtered by reason_ids; BatchRetrieveInventoryChanges.sort orders history by occurred_at.

Reporting API

The Beta, cube-based Reporting API uses GET /v1/meta to discover views, cubes, measures, dimensions, and segments, then POST /v1/load to run analytical queries. It supports automatic joins across cubes. Authenticate with a personal access token or an OAuth token carrying REPORTING_READ.

Terminal defaults and surcharges

PaymentOptions.autocomplete defaults to true. The Terminal API can add credit-card surcharges in the US, and payments report seller-added card surcharges.

For the regional Terminal capability matrix, read Terminal, locations, and devices.

Scope discipline

Apply only guidance relevant to the Square surface in the task. Preserve Beta and closed-Beta qualifiers, regional limitations, exact endpoint and field names, and stated retirement wording. Do not infer a completed retirement from a scheduled retirement date.