enigmare/v2-crawler
1904
1{"id":"doc-customer_api_best_practices-74879ec3","source":"documentation","title":"Customer API Best Practices","url":"https://developer.squareup.com/docs/customers-api/best-practices","text":"Example:\n```text\n{\n \"customer\": {\n \"email_address\": \"[email protected]\",\n \"phone_number\": \"+1-555-555-0123\",\n \"given_name\": \"John\",\n \"family_name\": \"Doe\"\n },\n \"idempotency_key\": \"unique_idempotency_key\"\n}\n```\n\nExample:\n```text\n{\n \"source_id\": \"card_nonce_or_token\",\n \"customer_id\": \"CUSTOMER_ID\",\n \"amount_money\": {\n \"amount\": 1000,\n \"currency\": \"USD\"\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.876Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":2,"totalLines":26,"estimatedTokens":100}}2{"id":"doc-customers_api-7cf5051e","source":"documentation","title":"Customers API","url":"https://developer.squareup.com/docs/customers-api/what-it-does","text":"Example:\n```text\n{\n \"customer\": {\n \"id\": \"TNQC0TYTWMRSFFQ157KK4V7MVR\",\n \"created_at\": \"2020-03-23T20:21:54.859Z\",\n \"updated_at\": \"2021-07-14T18:25:21.342Z\",\n ...\n \"tax_ids\": {\n \"eu_vat\": \"IE3426675K\"\n }\n }\n}\n```\n\nExample:\n```text\ncurl https://connect.squareupsandbox.com/v2/customers/{CUSTOMER_ID} \\\n-X PUT \\\n-H 'Square-Version: 2022-11-16' \\\n-H 'Authorization: Bearer {ACCESS_TOKEN}' \\\n-H 'Content-Type: application/json' \\\n-H 'X-Clear-Null: true' \\\n-d '{\n \"address\": {\n \"address_line_1\": \"505 Gardenia Lane\",\n \"address_line_2\": null\n },\n \"version\": 1\n}'\n```\n\nExample:\n```text\ncurl https://connect.squareupsandbox.com/v2/customers/{CUSTOMER_ID} \\\n-X PUT \\\n-H 'Square-Version: 2022-11-16' \\\n-H 'Authorization: Bearer {ACCESS_TOKEN}' \\\n-H 'Content-Type: application/json' \\\n-H 'X-Clear-Null: true' \\\n-d '{\n \"address\": null,\n \"version\": 2\n}'\n```\n\nExample:\n```text\ncurl https://connect.squareupsandbox.com/v2/customers/{CUSTOMER_ID} \\\n-X PUT \\\n-H 'Square-Version: 2022-10-19' \\\n-H 'Authorization: Bearer {ACCESS_TOKEN}' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"address\": {\n \"address_line_1\": \"1313 Main St\",\n \"address_line_2\": \"Apt 2B\", \n \"locality\": \"Springfield\",\n \"administrative_district_level_1\": \"MA\",\n \"postal_code\": \"01119\"\n },\n \"version\": 0\n}'\n```\n\nExample:\n```text\ncurl https://connect.squareupsandbox.com/v2/customers/{CUSTOMER_ID} \\\n-X PUT \\\n-H 'Square-Version: 2022-10-19' \\\n-H 'Authorization: Bearer {ACCESS_TOKEN}' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"address\": {},\n \"version\": 1\n}'\n```\n\nExample:\n```text\n{\n \"errors\": [\n {\n \"code\": \"INVALID_PHONE_NUMBER\",\n \"detail\": \"Expected phone_number to be a valid phone number\",\n \"field\": \"phone_number\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"errors\": [\n {\n \"code\": \"INVALID_TIME\",\n \"detail\": \"Expected birthday to be a valid date formatted as `YYYY-MM-DD` or `MM-DD`.\",\n \"field\": \"birthday\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"errors\": [\n {\n \"code\": \"INVALID_VALUE\",\n \"detail\": \"This provided date `January 7` is not valid.\",\n \"field\": \"birthday\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"errors\": [\n {\n \"code\": \"VALUE_TOO_LONG\",\n \"detail\": \"Expected reference_id to contain a string of max length 100\",\n \"field\": \"reference_id\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"errors\": [\n {\n \"code\": \"BAD_REQUEST\",\n \"detail\": \"The field named '{field_name}' is unrecognized (line 4, character 9)\",\n \"field\": \"{field_name}\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"errors\": [\n {\n \"code\": \"INVALID_EMAIL_ADDRESS\",\n \"detail\": \"Expected email_address to be a valid email address\",\n \"field\": \"email_address\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"errors\": [\n {\n \"code\": \"INVALID_VALUE\",\n \"detail\": \"Provided value for `phone_number` is invalid.\",\n \"field\": \"phone_number\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"errors\": [\n {\n \"code\": \"INVALID_VALUE\",\n \"detail\": \"Provided value for `email_address` is invalid.\",\n \"field\": \"email_address\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"errors\": [\n {\n \"code\": \"BAD_REQUEST\",\n \"detail\": \"At least one field must be set to update a customer.\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"customer\": {\n \"id\": \"62Y0FBFDQ0ZHDCGKBYP7FZK474\",\n \"created_at\": \"2020-11-12T03:51:06.371Z\",\n \"updated_at\": \"2021-08-29T00:03:37Z\",\n \"given_name\": \"Amelia\",\n \"family_name\": \"Earhart\",\n \"email_address\": \"[email protected]\",\n ...\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.877Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":15,"totalLines":219,"estimatedTokens":986}}3{"id":"doc-retrieve_customer_profiles-92307be5","source":"documentation","title":"Retrieve Customer Profiles","url":"https://developer.squareup.com/docs/customers-api/use-the-api/retrieve-profiles","text":"Example:\n```text\n{\n \"customer\": {\n \"id\": \"TNQC0TYTWMRSFFQ157KK4V7MVR\",\n \"created_at\": \"2020-04-27T17:28:50.073Z\",\n \"updated_at\": \"2020-05-27T04:43:53Z\",\n \"given_name\": \"John\",\n \"family_name\": \"Doe\",\n \"company_name\": \"Company\",\n \"email_address\": \"[email protected]\",\n \"address\": {\n \"address_line_1\": \"123 Main Street\",\n \"locality\": \"City\",\n \"postal_code\": \"12345\",\n \"country\": \"US\"\n },\n \"phone_number\": \"+12065551212\",\n \"birthday\": \"0000-01-13\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"segment_ids\": [\n \"499XKDADA7682.REACHABLE\"\n ],\n \"version\": 0\n }\n}\n```\n\nExample:\n```text\n{\n \"responses\": {\n \"5CZ99Q9SD8C71SGFD4CR96CBCT\": {\n \"errors\": [\n {\n \"code\": \"NOT_FOUND\",\n \"detail\": \"Customer with ID `5CZ99Q9SD8C71SGFD4CR96CBCT` not found.\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n },\n \"TNQC0TYTWMRSFFQ157KK4V7MVR\": {\n \"customer\": {\n \"id\": \"TNQC0TYTWMRSFFQ157KK4V7MVR\",\n \"created_at\": \"2020-04-27T17:28:50.073Z\",\n \"updated_at\": \"2020-05-27T04:43:53Z\",\n \"given_name\": \"John\",\n \"family_name\": \"Doe\",\n \"company_name\": \"Company\",\n \"email_address\": \"[email protected]\",\n \"address\": {\n \"address_line_1\": \"123 Main Street\",\n \"locality\": \"City\",\n \"postal_code\": \"12345\",\n \"country\": \"US\"\n },\n \"phone_number\": \"+12065551212\",\n \"birthday\": \"0000-01-13\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"segment_ids\": [\n \"499XKDADA7682.REACHABLE\"\n ],\n \"version\": 0\n }\n },\n \"PE6CW5359K3J913DH3PF4PREF8\": {\n \"customer\": {\n \"id\": \"PE6CW5359K3J913DH3PF4PREF8\",\n \"created_at\": \"2024-01-20T00:32:34.43Z\",\n \"updated_at\": \"2024-01-20T00:32:34Z\",\n \"given_name\": \"Vera\",\n \"family_name\": \"Sara\",\n \"email_address\": \"[email protected]\",\n \"phone_number\": \"+14167779999\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"version\": 1\n }\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"customers\": [\n {\n \"id\": \"A537H7KAQWSAF8M8EM1Y23E16M\",\n \"created_at\": \"2021-10-28T20:19:07.692Z\",\n \"updated_at\": \"2024-01-09T20:14:21Z\",\n \"given_name\": \"Amelia\",\n \"family_name\": \"Earhart\",\n \"email_address\": \"[email protected]\",\n \"address\": {\n \"address_line_1\": \"123 Main St\",\n \"locality\": \"Seattle\",\n \"administrative_district_level_1\": \"WA\",\n \"postal_code\": \"98121\",\n \"country\": \"US\"\n },\n \"phone_number\": \"1-212-555-4240\",\n \"note\": \"a customer on seller account\",\n \"reference_id\": \"YOUR_REFERENCE_ID\",\n \"company_name\": \"ACME\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"segment_ids\": [\n \"8QJTJCE6AZSN6.REACHABLE\",\n \"8QJTJCE6AZSN6.CARDS_ON_FILE\",\n \"gv2:8H24YRM74H2030XWJWP9F0MAEW\",\n \"gv2:4TR2NFVP8N63D9K1FZ5E62VD78\"\n ],\n \"version\": 4\n },\n {\n \"id\": \"XVN84NCJS9QWX0N202WX90TJ5R\",\n \"created_at\": \"2024-01-09T23:45:20.789Z\",\n \"updated_at\": \"2024-01-09T23:45:20Z\",\n \"given_name\": \"Sara\",\n \"family_name\": \"Vera\",\n \"email_address\": \"[email protected]\",\n \"address\": {\n \"address_line_1\": \"292 Adelaide St\",\n \"locality\": \"Toronto\",\n \"administrative_district_level_1\": \"ON\",\n \"country\": \"CA\"\n },\n \"phone_number\": \"+14167779999\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"birthday\": \"2000-10-10\",\n \"segment_ids\": [\n \"8QJTJCE6AZSN6.REACHABLE\"\n ],\n \"version\": 0\n },\n {\n \"id\": \"T4BKEYWKMS6G14BQ06Z961H7QW\",\n \"created_at\": \"2020-10-28T19:13:36.64Z\",\n \"updated_at\": \"2021-03-08T22:56:28Z\",\n \"given_name\": \"John\",\n \"family_name\": \"Doe\",\n \"email_address\": \"[email protected]\",\n \"phone_number\": \"2065551012\",\n \"note\": \"\\n// Merged on 2021/03/08. Following fields were not transferred to the current customer:\\nFirst Name: Doe\\nEmail Address: [email protected]\\nPhone Number: (206) 555-1011\\n// Merged on 2021/03/08.\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"MERGE\",\n \"segment_ids\": [\n \"8QJTJCE6AZSN6.REACHABLE\",\n \"8QJTJCE6AZSN6.CARDS_ON_FILE\",\n \"8QJTJCE6AZSN6.LOYALTY_ALL\",\n \"gv2:8H24YRM74H2030XWJWP9F0MAEW\",\n \"gv2:4TR2NFVP8N63D9K1FZ5E62VD78\"\n ],\n \"version\": 1\n },\n {\n \"id\": \"6ZK40WV46EM8M2AVC9ZEF7B018\",\n \"created_at\": \"2024-01-20T00:32:34.533Z\",\n \"updated_at\": \"2024-01-20T12:46:09Z\",\n \"given_name\": \"Silva\",\n \"family_name\": \"Antonio\",\n \"email_address\": \"[email protected]\",\n \"address\": {\n \"address_line_1\": \"1001 Broadway Ave\",\n \"locality\": \"Toronto\",\n \"administrative_district_level_1\": \"ON\",\n \"country\": \"CA\"\n },\n \"phone_number\": \"+14375552222\",\n \"note\": \"Birthday Club member\",\n \"reference_id\": \"refid\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"birthday\": \"0000-07-07\",\n \"segment_ids\": [\n \"8QJTJCE6AZSN6.REACHABLE\"\n ],\n \"version\": 2\n },\n {\n \"id\": \"T9Q21K8PA5MQY3PAZZT2WGGVC0\",\n \"created_at\": \"2023-04-12T20:38:05.255Z\",\n \"updated_at\": \"2023-04-12T20:38:05Z\",\n \"phone_number\": \"2085550988\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"LOYALTY\",\n \"segment_ids\": [\n \"8QJTJCE6AZSN6.LOYALTY_ALL\"\n ],\n \"version\": 0\n },\n {\n \"id\": \"Q8002JB4YQ5SB8A9FPE2476ADMM30NG\",\n \"created_at\": \"2022-10-14T22:51:57.306Z\",\n \"updated_at\": \"2022-10-14T22:51:57Z\",\n \"phone_number\": \"4255550000\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"LOYALTY\",\n \"segment_ids\": [\n \"8QJTJCE6AZSN6.LOYALTY_ALL\"\n ],\n \"version\": 0\n },\n {\n \"id\": \"Q8002VV1DJTRG0TF3A55MAWPZR2EA80\",\n \"created_at\": \"2022-07-16T20:15:11.123Z\",\n \"updated_at\": \"2022-07-16T20:15:11Z\",\n \"phone_number\": \"6095550923\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"LOYALTY\",\n \"segment_ids\": [\n \"8QJTJCE6AZSN6.LOYALTY_ALL\"\n ],\n \"version\": 0\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"customers\": [\n {\n // customer 1 fields\n },\n {\n // customer 2 fields\n },\n {\n // customer 3 fields\n }\n ],\n \"cursor\": \"PNEhVUKBuTOuRIZoUcX5VQ...UE1cVyWmbXhoY\",\n \"count\": 13293\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.878Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":4,"totalLines":263,"estimatedTokens":1733}}4{"id":"doc-manage_customer_profiles-de92b096","source":"documentation","title":"Manage Customer Profiles","url":"https://developer.squareup.com/docs/customers-api/use-the-api/keep-records","text":"Example:\n```text\n{\n \"customer\": {\n \"id\": \"FQWDXGBB2Q9WT1ZD6HKKSE9NQC\",\n \"created_at\": \"2022-05-29T21:14:49.48Z\",\n \"updated_at\": \"2022-05-29T21:14:49Z\",\n \"given_name\": \"John\",\n \"family_name\": \"Doe\",\n \"nickname\": \"Junior\",\n \"email_address\": \"[email protected]\",\n \"address\": {\n \"address_line_1\": \"1955 Broadway\",\n \"locality\": \"Springfield\",\n \"administrative_district_level_1\": \"MA\",\n \"postal_code\": \"01111\"\n },\n \"phone_number\": \"+1 (206) 222-3456\",\n \"company_name\": \"ACME Inc.\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"version\": 0\n }\n}\n```\n\nExample:\n```text\n{\n \"customers\": {\n \"idempotency_key_1\": {\n // customer fields\n },\n \"idempotency_key_2\": {\n // customer fields\n },\n \"idempotency_key_3\": {\n // customer fields\n },\n ...\n }\n}\n```\n\nExample:\n```text\n{\n \"responses\": {\n \"452ea896-f36e-4c5c-95d5-e5aa727b9b2c\": {\n \"customer\": {\n \"id\": \"TFVGJNH46AVMDCZY93KKKF5QW4\",\n \"created_at\": \"2024-01-20T00:32:34.43Z\",\n \"updated_at\": \"2024-01-20T00:32:34Z\",\n \"given_name\": \"Vera\",\n \"family_name\": \"Sara\",\n \"email_address\": \"[email protected]\",\n \"phone_number\": \"+14167779999\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"version\": 0\n }\n },\n \"cbde1ec6-96df-40d4-8019-af9a4fa893ed\": {\n \"customer\": {\n \"id\": \"6ZK40WV46EM8M2AVC9ZEF7B018\",\n \"created_at\": \"2024-01-20T00:32:34.533Z\",\n \"updated_at\": \"2024-01-20T00:32:34Z\",\n \"given_name\": \"Silva\",\n \"family_name\": \"Antonio\",\n \"email_address\": \"[email protected]\",\n \"address\": {\n \"address_line_1\": \"1001 Broadway Ave\",\n \"address_line_2\": \"Apt 1311\",\n \"locality\": \"Toronto\",\n \"administrative_district_level_1\": \"ON\",\n \"country\": \"CA\"\n },\n \"phone_number\": \"+14375552222\",\n \"note\": \"Birthday Club member\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"birthday\": \"0000-07-22\",\n \"version\": 0\n }\n },\n \"716cefbc-3d71-4d7c-bdc8-9c7f84c2d793\": {\n \"errors\": [\n {\n \"code\": \"INVALID_EMAIL_ADDRESS\",\n \"detail\": \"Expected email_address to be a valid email address\",\n \"field\": \"email_address\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"customer\": {\n \"id\": \"FQWDXGBB2Q9WT1ZD6HKKSE9NQC\",\n \"created_at\": \"2022-05-29T21:14:49.48Z\",\n \"updated_at\": \"2022-09-16T09:36:22Z\",\n \"given_name\": \"John\",\n \"family_name\": \"Doe\",\n \"nickname\": \"Junior\",\n \"email_address\": \"[email protected]\",\n \"address\": {\n \"address_line_1\": \"1313 Main St\",\n \"address_line_2\": \"Apt 2B\",\n \"locality\": \"Springfield\",\n \"administrative_district_level_1\": \"MA\",\n \"postal_code\": \"01119\"\n },\n \"phone_number\": \"+1 (206) 222-3456\",\n \"company_name\": \"ACME Inc.\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"birthday\": \"0000-01-13\",\n \"segment_ids\": [\n \"MLYQHTSHXM6E8.REACHABLE\",\n \"gv2:8ESCGMK9GN26570X8VR2AP9W1G\"\n ],\n \"version\": 1\n }\n}\n```\n\nExample:\n```text\n{\n \"customers\": {\n \"customer_id_1\": {\n // customer fields\n },\n \"customer_id_2\": {\n // customer fields\n },\n \"customer_id_3\": {\n // customer fields\n },\n ...\n }\n}\n```\n\nExample:\n```text\n{\n \"responses\": {\n \"6ZK40WV46EM8M2AVC9ZEF7B018\": {\n \"customer\": {\n \"id\": \"6ZK40WV46EM8M2AVC9ZEF7B018\",\n \"created_at\": \"2024-01-20T00:32:34.533Z\",\n \"updated_at\": \"2024-01-20T00:32:34Z\",\n \"given_name\": \"Silva\",\n \"family_name\": \"Antonio\",\n \"email_address\": \"[email protected]\",\n \"address\": {\n \"address_line_1\": \"900 1st Ave\",\n \"locality\": \"Toronto\",\n \"administrative_district_level_1\": \"ON\",\n \"country\": \"CA\"\n },\n \"phone_number\": \"+14375552222\",\n \"note\": \"Birthday Club member\",\n \"company_name\": \"Swatch Design\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"creation_source\": \"THIRD_PARTY\",\n \"birthday\": \"0000-07-22\",\n \"version\": 2\n }\n },\n \"TFVGJNH46AVMDCZY93KKKF5QW4\": {\n \"errors\": [\n {\n \"code\": \"INVALID_EMAIL_ADDRESS\",\n \"detail\": \"Expected email_address to be a valid email address\",\n \"field\": \"email_address\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"responses\": {\n \"W8Q7NZQT08R6V6BSKVVC1VW5B0\": {},\n \"P6BZGEMCPAP4P31Y9M8PWQWE80\": {},\n \"8K35J21GQM4MVXDQTHCQBQDZ58\": {},\n \"1PTNXQXT5J2KS2YF7R80GHP69Z\": {\n \"errors\": [\n {\n \"code\": \"NOT_FOUND\",\n \"detail\": \"Customer with ID `1PTNXQXT5J2KS2YF7R80GHP69Z` not found.\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n }\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.879Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":7,"totalLines":221,"estimatedTokens":1286}}5{"id":"doc-authorize_your_android_application-f6b8f344","source":"documentation","title":"Authorize your Android Application","url":"https://developer.squareup.com/docs/mobile-payments-sdk/android/configure-authorize","text":"Example:\n```text\noverride fun onResume() {\n super.onResume()\n val authorizationManager = MobilePaymentsSdk.authorizationManager()\n // Authorize and handle authorization successes or failures\n callbackReference = authorizationManager.authorize(accessToken, locationId) { result ->\n when (result) {\n is Success -> {\n finishWithAuthorizedSuccess(result.value)\n }\n is Failure -> {\n when (result.errorCode) {\n NO_NETWORK -> // show error message and retry suggestion\n ...\n USAGE_ERROR -> // show error message\n ...\n }\n }\n }\n }\n}\n\noverride fun onPause() {\n super.onPause()\n // Remove the callback reference to prevent memory leaks\n callbackReference?.clear()\n}\n```\n\nExample:\n```text\n{\n \"access_token\": \"EAAAEL_l5ncx260W8yWz2gGO0GtJeFBJqIdHIXZjpQZ_XW-yxh-Tl7MlF8vIE__n\",\n \"token_type\": \"bearer\",\n \"expires_at\": \"2024-05-15T19:36:00Z\",\n \"merchant_id\": \"TVSNN09QQY609\",\n \"refresh_token\": \"EQAAEInZRUFx8bgauwrDjXYIioyCDEB7vyOG0cScx-qfczgTpNtUjAGLResAKOe9\"\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.879Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":2,"totalLines":42,"estimatedTokens":296}}6{"id":"doc-duplicated_customers-776ea1d1","source":"documentation","title":"Duplicated Customers","url":"https://developer.squareup.com/docs/customers-api/duplicated-customers","text":"Example:\n```text\n{\n \"new_customer_id_1\": [\"previous_id_A\", \"previous_id_B\"],\n \"new_customer_id_2\": [\"previous_id_C\", \"previous_id_D\", \"previous_id_E\"]\n}\n```\n\nExample:\n```text\nfrom square import Square\nimport os\nfrom typing import List, Dict, Any\n\ndef get_all_related_customer_ids(current_id: str, id_mapping: Dict[str, List[str]]) -> List[str]:\n \"\"\"\n Given a current (post-merge) customer ID, return all related customer IDs\n (both current and previous)\n\n Args:\n current_id: The current customer profile ID\n id_mapping: Dictionary mapping new IDs to lists of previous IDs\n\n Returns:\n List of all related customer IDs (current ID + all previous IDs)\n \"\"\"\n # Start with the current ID\n all_ids = [current_id]\n\n # Add any previous IDs associated with this current ID\n if current_id in id_mapping:\n all_ids.extend(id_mapping[current_id])\n\n return all_ids\n\ndef search_customer_orders(\n current_id: str, \n id_mapping: Dict[str, List[str]], \n location_ids: List[str],\n client: Square\n) -> List[Dict[str, Any]]:\n \"\"\"\n Search for all orders associated with a customer, including orders\n linked to their previous profiles\n\n Args:\n current_id: The current (post-merge) customer profile ID\n id_mapping: Dictionary mapping new IDs to lists of previous IDs\n location_ids: List of Square location IDs to search\n client: Initialized Square client\n\n Returns:\n List of all orders found across all related customer profiles\n \"\"\"\n # Get all customer IDs (current and previous)\n customer_ids = get_all_related_customer_ids(current_id, id_mapping)\n\n # Create the search query with customer filter\n search_query = {\n \"filter\": {\n \"customer_filter\": {\n \"customer_ids\": customer_ids\n }\n },\n \"sort\": {\n \"sort_field\": \"CLOSED_AT\",\n \"sort_order\": \"DESC\"\n }\n }\n\n try:\n # Search orders using the Square SDK\n result = client.orders.search(\n body={\n \"location_ids\": location_ids,\n \"query\": search_query\n }\n )\n\n if result.is_success():\n return result.body.get('orders', [])\n else:\n print(f\"Error searching orders: {result.errors}\")\n return []\n\n except Exception as e:\n print(f\"Exception when searching orders: {str(e)}\")\n return []\n\n# Example usage:\ndef main():\n # Initialize the Square client\n client = Square(\n access_token=os.environ.get(\"SQUARE_TOKEN\"),\n environment='sandbox' # Use 'production' for production environment\n )\n\n # Example mapping of new IDs to previous IDs\n id_mapping = {\n \"NEW_ID_1\": [\"OLD_ID_A\", \"OLD_ID_B\"],\n \"NEW_ID_2\": [\"OLD_ID_C\", \"OLD_ID_D\"]\n }\n\n # Example location IDs - replace with actual location IDs\n location_ids = [\"057P5VYJ4A5X1\", \"18YC4JDH91E1H\"]\n\n # Search for all orders, including those from previous profiles\n orders = search_customer_orders(\n current_id=\"NEW_ID_1\",\n id_mapping=id_mapping,\n location_ids=location_ids,\n client=client\n )\n\n # Process the orders\n for order in orders:\n print(f\"Order ID: {order.get('id')}\")\n # Process other order fields as needed\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.880Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":2,"totalLines":121,"estimatedTokens":843}}7{"id":"doc-use_customer_webhooks-31659407","source":"documentation","title":"Use Customer Webhooks","url":"https://developer.squareup.com/docs/customers-api/use-the-api/customer-webhooks","text":"Example:\n```text\n{\n \"merchant_id\": \"KTDR6CEPCWXYL\",\n \"type\": \"customer.created\",\n \"event_id\": \"226ea61b-476d-4487-84c8-f68b142976f8\",\n \"created_at\": \"2021-01-21T19:00:04Z\",\n \"data\": {\n \"type\": \"customer\",\n \"id\": \"YBE4YXMS1CT7K4HP1KTXYFBWZ0\",\n \"object\": {\n \"customer\": {\n \"created_at\": \"2021-01-21T19:00:04.693Z\",\n \"creation_source\": \"THIRD_PARTY\",\n \"email_address\": \"[email protected]\",\n \"family_name\": \"Doe\",\n \"given_name\": \"Jane\",\n \"id\": \"YBE4YXMS1CT7K4HP1KTXYFBWZ0\",\n \"phone_number\": \"+12065551212\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"updated_at\": \"2021-01-21T19:00:04Z\",\n \"version\": 0\n }\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"merchant_id\": \"KTDR6CEPCWXYL\",\n \"type\": \"customer.deleted\",\n \"event_id\": \"3af6a667-34cf-42ca-bd76-96b637d8e67f\",\n \"created_at\": \"2021-01-21T19:46:09Z\",\n \"data\": {\n \"type\": \"customer\",\n \"id\": \"YBE4YXMS1CT7K4HP1KTXYFBWZ0\",\n \"deleted\": true,\n \"object\": {\n \"customer\": {\n \"creation_source\": \"THIRD_PARTY\",\n \"email_address\": \"[email protected]\",\n \"family_name\": \"Doe\",\n \"given_name\": \"Jane\",\n \"id\": \"YBE4YXMS1CT7K4HP1KTXYFBWZ0\",\n \"phone_number\": \"+12065551212\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"version\": 11\n }\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"merchant_id\": \"KTDR6CEPCWXYL\",\n \"type\": \"customer.updated\",\n \"event_id\": \"8478cc17-a7b9-40e6-b5fa-692e58794ff5\",\n \"created_at\": \"2021-01-21T19:42:51Z\",\n \"data\": {\n \"type\": \"customer\",\n \"id\": \"YBE4YXMS1CT7K4HP1KTXYFBWZ0\",\n \"object\": {\n \"customer\": {\n \"created_at\": \"2021-01-21T19:00:04.693Z\",\n \"creation_source\": \"THIRD_PARTY\",\n \"email_address\": \"[email protected]\",\n \"family_name\": \"Doe\",\n \"given_name\": \"Jane\",\n \"group_ids\": [\n \"3MEP3VM842KQZXQ9WSBJRTX73H\"\n ],\n \"id\": \"YBE4YXMS1CT7K4HP1KTXYFBWZ0\",\n \"phone_number\": \"+12065551212\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"updated_at\": \"2021-02-10T13:02:15Z\",\n \"version\": 3\n }\n }\n }\n}\n```\n\nExample:\n```text\n\"event_context\": {\n \"merge\": {\n \"from_customer_ids\": [\n // ID of existing customer profile A that was merged and deleted,\n // ID of existing customer profile B that was merged and deleted,\n // ...\n ],\n \"to_customer_id\": // ID of new customer profile C with aggregated properties\n }\n}\n```\n\nExample:\n```text\n{\n \"merchant_id\": \"KTDR6CEPCWXYL\",\n \"type\": \"customer.created\",\n \"event_id\": \"04d6e69f-d3dc-4fb7-a891-beb0cf7e8457\",\n \"created_at\": \"2021-01-21T23:10:38Z\",\n \"data\": {\n \"type\": \"customer\",\n \"id\": \"A9641GZW2H7Z56YYSD41Q12HDW\",\n \"object\": {\n \"customer\": {\n \"address\": {\n \"address_line_1\": \"123 Main Street\",\n \"administrative_district_level_1\": \"WA\",\n \"country\": \"US\",\n \"locality\": \"Seattle\",\n \"postal_code\": \"98104\"\n },\n \"birthday\": \"1998-09-01\",\n \"company_name\": \"ACME Inc\",\n \"created_at\": \"2021-01-21T22:59:16.271Z\",\n \"creation_source\": \"MERGE\",\n \"email_address\": \"[email protected]\",\n \"family_name\": \"Doe\",\n \"given_name\": \"John\",\n \"group_ids\": [\n \"3MEP3VM842KQZXQ9WSBJRTX73H\"\n ],\n \"id\": \"A9641GZW2H7Z56YYSD41Q12HDW\",\n \"note\": \"Favorite: Double-shot Iced Americano\\n// Merged on 2021/01/21. Following fields were not transferred to the current customer:\\nPhone Number: +14065551212\",\n \"phone_number\": \"+14065551112\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"updated_at\": \"2021-01-21T23:10:39Z\",\n \"version\": 0\n },\n \"event_context\": {\n \"merge\": {\n \"from_customer_ids\": [\n \"20R574N4D0VP74N56QTRSKDJ9C\",\n \"P3ZRDK895X1JQCX9D3C4KEF4YG\"\n ],\n \"to_customer_id\": \"A9641GZW2H7Z56YYSD41Q12HDW\"\n }\n }\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"merchant_id\": \"KTDR6CEPCWXYL\",\n \"type\": \"customer.deleted\",\n \"event_id\": \"1cad466e-400a-40a8-84a6-6b8c278acc95\",\n \"created_at\": \"2021-01-21T23:10:38Z\",\n \"data\": {\n \"type\": \"customer\",\n \"id\": \"P3ZRDK895X1JQCX9D3C4KEF4YG\",\n \"deleted\": true,\n \"object\": {\n \"customer\": {\n \"address\": {\n \"address_line_1\": \"123 Main Street\",\n \"administrative_district_level_1\": \"WA\",\n \"country\": \"US\",\n \"locality\": \"Seattle\",\n \"postal_code\": \"98104\"\n },\n \"birthday\": \"1998-09-01\",\n \"company_name\": \"ACME Inc\",\n \"creation_source\": \"DIRECTORY\",\n \"email_address\": \"[email protected]\",\n \"family_name\": \"Doe\",\n \"given_name\": \"John\",\n \"id\": \"P3ZRDK895X1JQCX9D3C4KEF4YG\",\n \"note\": \"Favorite: Double-shot Iced Americano\",\n \"phone_number\": \"+14065551112\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"version\": 10\n },\n \"event_context\": {\n \"merge\": {\n \"from_customer_ids\": [\n \"20R574N4D0VP74N56QTRSKDJ9C\",\n \"P3ZRDK895X1JQCX9D3C4KEF4YG\"\n ],\n \"to_customer_id\": \"A9641GZW2H7Z56YYSD41Q12HDW\"\n }\n }\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"merchant_id\": \"KTDR6CEPCWXYL\",\n \"type\": \"customer.deleted\",\n \"event_id\": \"ca6a30a6-3c58-49ec-b626-5ed733e861ad\",\n \"created_at\": \"2021-01-21T23:10:38Z\",\n \"data\": {\n \"type\": \"customer\",\n \"id\": \"20R574N4D0VP74N56QTRSKDJ9C\",\n \"deleted\": true,\n \"object\": {\n \"customer\": {\n \"creation_source\": \"LOYALTY\",\n \"id\": \"20R574N4D0VP74N56QTRSKDJ9C\",\n \"phone_number\": \"+14065551212\",\n \"preferences\": {\n \"email_unsubscribed\": false\n },\n \"version\": 4\n },\n \"event_context\": {\n \"merge\": {\n \"from_customer_ids\": [\n \"20R574N4D0VP74N56QTRSKDJ9C\",\n \"P3ZRDK895X1JQCX9D3C4KEF4YG\"\n ],\n \"to_customer_id\": \"A9641GZW2H7Z56YYSD41Q12HDW\"\n }\n }\n }\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.880Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":7,"totalLines":242,"estimatedTokens":1534}}8{"id":"doc-create_and_manage_gift_cards_with_customer_integ-781bc2cf","source":"documentation","title":"Create and Manage Gift Cards with Customer Integration","url":"https://developer.squareup.com/docs/customers-api/quick-start","text":"Example:\n```text\nimplementation 'com.squareup:square:35.0.0'\n```\n\nExample:\n```text\n<dependency>\n <groupId>com.squareup</groupId>\n <artifactId>square</artifactId>\n <version>35.0.0</version>\n</dependency>\n```\n\nExample:\n```text\nimport com.squareup.square.SquareClient;\nimport com.squareup.square.Environment;\n\npublic class GiftCardService {\n private final SquareClient client;\n\n public GiftCardService(String accessToken) {\n client = new SquareClient.Builder()\n .environment(Environment.SANDBOX)\n .accessToken(accessToken)\n .build();\n }\n}\n```\n\nExample:\n```text\npublic Customer findOrCreateCustomer(String firstName, String lastName, \n String emailAddress, String streetAddress) throws ApiException {\n\n SearchCustomersRequest searchRequest = new SearchCustomersRequest.Builder()\n .query(new CustomerQuery.Builder()\n .filter(new CustomerFilter.Builder()\n .emailAddress(new CustomerTextFilter.Builder()\n .exact(emailAddress)\n .build())\n .build())\n .build())\n .build();\n\n SearchCustomersResponse searchResponse = client.getCustomersApi()\n .searchCustomers(searchRequest);\n\n if (searchResponse.getCustomers() != null && !searchResponse.getCustomers().isEmpty()) {\n return searchResponse.getCustomers().get(0);\n }\n\n // Customer not found, create new one\n Address address = new Address.Builder()\n .addressLine1(streetAddress)\n .build();\n\n CreateCustomerRequest createRequest = new CreateCustomerRequest.Builder()\n .idempotencyKey(UUID.randomUUID().toString())\n .givenName(firstName)\n .familyName(lastName)\n .emailAddress(emailAddress)\n .address(address)\n .build();\n\n CreateCustomerResponse createResponse = client.getCustomersApi()\n .createCustomer(createRequest);\n\n return createResponse.getCustomer();\n}\n```\n\nExample:\n```text\npublic GiftCard createOrGetGiftCard(Customer customer, Money amount) throws ApiException {\n // First check for existing gift cards\n SearchGiftCardsRequest searchRequest = new SearchGiftCardsRequest.Builder()\n .query(new GiftCardQuery.Builder()\n .filter(new GiftCardFilter.Builder()\n .customerId(customer.getId())\n .build())\n .build())\n .build();\n\n SearchGiftCardsResponse searchResponse = client.getGiftCardsApi()\n .searchGiftCards(searchRequest);\n\n if (searchResponse.getGiftCards() != null && !searchResponse.getGiftCards().isEmpty()) {\n GiftCard existingCard = searchResponse.getGiftCards().get(0);\n // Load additional funds to existing card\n GiftCardActivity activity = new GiftCardActivity.Builder()\n .type(\"LOAD\")\n .locationId(\"YOUR_LOCATION_ID\")\n .giftCardId(existingCard.getId())\n .loadActivityDetails(\n new GiftCardActivityLoad.Builder()\n .amountMoney(amount)\n .build())\n .build();\n\n CreateGiftCardActivityRequest activityRequest = new CreateGiftCardActivityRequest.Builder()\n .idempotencyKey(UUID.randomUUID().toString())\n .giftCardActivity(activity)\n .build();\n\n client.getGiftCardActivitiesApi().createGiftCardActivity(activityRequest);\n return existingCard;\n }\n\n // Create new gift card\n CreateGiftCardRequest createRequest = new CreateGiftCardRequest.Builder()\n .idempotencyKey(UUID.randomUUID().toString())\n .locationId(\"YOUR_LOCATION_ID\")\n .giftCard(new GiftCard.Builder()\n .type(\"DIGITAL\")\n .customerId(customer.getId())\n .build())\n .build();\n\n CreateGiftCardResponse createResponse = client.getGiftCardsApi()\n .createGiftCard(createRequest);\n\n GiftCard newCard = createResponse.getGiftCard();\n\n // Activate the new card with initial balance\n GiftCardActivity activity = new GiftCardActivity.Builder()\n .type(\"ACTIVATE\")\n .locationId(\"YOUR_LOCATION_ID\")\n .giftCardId(newCard.getId())\n .activateActivityDetails(\n new GiftCardActivityActivate.Builder()\n .amountMoney(amount)\n .build())\n .build();\n\n CreateGiftCardActivityRequest activityRequest = new CreateGiftCardActivityRequest.Builder()\n .idempotencyKey(UUID.randomUUID().toString())\n .giftCardActivity(activity)\n .build();\n\n client.getGiftCardActivitiesApi().createGiftCardActivity(activityRequest);\n return newCard;\n}\n```\n\nExample:\n```text\nimport com.squareup.square.SquareClient;\nimport com.squareup.square.Environment;\nimport com.squareup.square.exceptions.ApiException;\nimport com.squareup.square.models.*;\n\nimport java.util.UUID;\n\npublic class GiftCardService {\n private final SquareClient client;\n\n public GiftCardService(String accessToken) {\n client = new SquareClient.Builder()\n .environment(Environment.SANDBOX)\n .accessToken(accessToken)\n .build();\n }\n\n public void processCustomerGiftCard(String firstName, String lastName, \n String emailAddress, String streetAddress, Money amount) throws ApiException {\n\n // Find or create customer\n Customer customer = findOrCreateCustomer(firstName, lastName, emailAddress, streetAddress);\n\n // Create or load gift card\n GiftCard giftCard = createOrGetGiftCard(customer, amount);\n\n System.out.println(\"Gift card processed successfully for customer: \" + \n customer.getGivenName() + \" \" + customer.getFamilyName());\n System.out.println(\"Gift card ID: \" + giftCard.getId());\n }\n\n // ... (include findOrCreateCustomer and createOrGetGiftCard methods from above)\n\n public static void main(String[] args) {\n try {\n GiftCardService service = new GiftCardService(\"YOUR_ACCESS_TOKEN\");\n Money amount = new Money.Builder()\n .amount(10000L) // $100.00\n .currency(\"USD\")\n .build();\n\n service.processCustomerGiftCard(\n \"John\",\n \"Doe\",\n \"[email protected]\",\n \"123 Main St\",\n amount\n );\n } catch (ApiException e) {\n System.err.println(\"Error: \" + e.getMessage());\n }\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.881Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":6,"totalLines":204,"estimatedTokens":1615}}9{"id":"doc-loyalty_api-184c064f","source":"documentation","title":"Loyalty API","url":"https://developer.squareup.com/docs/loyalty-api/overview","text":"Example:\n```text\n{\n \"errors\": [\n {\n \"code\": \"NOT_FOUND\",\n \"detail\": \"Merchant does not have a loyalty program\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"merchant_id\": \"6QJXJGB6AZFN7\",\n \"type\": \"loyalty.account.created\",\n \"event_id\": \"45957f82-1e7e-42a3-9532-a4e787c3344c\",\n \"created_at\": \"2021-07-13T17:37:11Z\",\n \"data\": {\n \"type\": \"loyalty_account\",\n \"id\": \"dd17bfc8-178a-456c-ba4e-dae5813d429f\",\n \"object\": {\n \"loyalty_account\": {\n // loyalty account fields\n }\n }\n }\n}\n```\n\nExample:\n```text\n...\n\"incentive\": {\n \"type\": \"POINTS_MULTIPLIER\",\n \"points_multiplier_data\": {\n \"multiplier\": \"2\" // or \"2.0\", \"2.00\", \"2.000\"\n }\n},\n...\n```\n\nExample:\n```text\n...\n\"incentive\": {\n \"type\": \"POINTS_MULTIPLIER\",\n \"points_multiplier_data\": {\n \"points_multiplier\": 2\n }\n},\n...\n```\n\nExample:\n```text\n{\n \"events\": [\n {\n \"id\": \"bbd1ef00-92ac-3e5f-8887-cd3c6ba29313\",\n \"type\": \"ACCUMULATE_POINTS\",\n \"created_at\": \"2022-09-07T22:31:48Z\",\n \"accumulate_points\": {\n \"loyalty_program_id\": \"8031c1b2-d749-4c76-9c40-ae5472ed2e04\",\n \"points\": 12,\n \"order_id\": \"cb9LSpDgOH3rITBaZ6eIBb9ee4F\"\n },\n \"loyalty_account_id\": \"716cefbc-3d71-4d7c-bdc8-9c7f84c2d793\",\n \"location_id\": \"S8GWD509MEHCA\",\n \"source\": \"LOYALTY_API\"\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"event\": {\n \"id\": \"ee46aafd-1af6-3695-a385-276e2ef0be26\",\n \"type\": \"ACCUMULATE_POINTS\",\n \"created_at\": \"2020-05-08T21:41:12Z\",\n \"accumulate_points\": {\n \"loyalty_program_id\": \"d619f755-2d17-41f3-990d-c04ecedd64dd\",\n \"points\": 6,\n \"order_id\": \"RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY\"\n },\n \"loyalty_account_id\": \"5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd\",\n \"location_id\": \"P034NEENMD09F\",\n \"source\": \"LOYALTY_API\"\n }\n}\n```\n\nExample:\n```text\n...\n\"accrual_rules\": [\n {\n \"accrual_type\": \"CATEGORY\",\n \"points\": 1,\n \"category_data\": {\n \"category_id\": \"7ZERJKO5PVYXCVUHV2JCZ2UG\"\n }\n },\n {\n \"accrual_type\": \"CATEGORY\",\n \"points\": 3,\n \"category_data\": {\n \"category_id\": \"FQKAOJE5C4FIMF5A2URMLW6V\"\n }\n }\n]\n...\n```\n\nExample:\n```text\n...\n\"accrual_rules\": [\n {\n \"accrual_type\": \"ITEM_VARIATION\",\n \"points\": 1,\n \"item_variation_data\": {\n \"item_variation_id\": \"CBZXBUVVTYUBZGQO44RHMR6B\"\n }\n },\n {\n \"accrual_type\": \"ITEM_VARIATION\",\n \"points\": 2,\n \"item_variation_data\": {\n \"item_variation_id\": \"EDILT24Z2NISEXDKGY6HP7XV\"\n }\n }\n]\n...\n```\n\nExample:\n```text\n...\n\"accrual_rules\": [\n {\n \"accrual_type\": \"SPEND\",\n \"points\": 1,\n \"spend_data\": {\n \"amount_money\": {\n \"amount\": 500,\n \"currency\": \"USD\"\n },\n \"excluded_category_ids\": [\n \"7ZERJKO5PVYXCVUHV2JCZ2UG\",\n \"FQKAOJE5C4FIMF5A2URMLW6V\"\n ],\n \"excluded_item_variation_ids\": [\n \"CBZXBUVVTYUBZGQO44RHMR6B\",\n \"EDILT24Z2NISEXDKGY6HP7XV\"\n ],\n \"tax_mode\": \"BEFORE_TAX\"\n }\n }\n]\n...\n```\n\nExample:\n```text\n...\n\"accrual_rules\": [\n {\n \"accrual_type\": \"VISIT\",\n \"points\": 1,\n \"visit_data\": {\n \"minimum_amount_money\": {\n \"amount\": 500,\n \"currency\": \"USD\"\n },\n \"tax_mode\": \"BEFORE_TAX\"\n }\n }\n]\n...\n```\n\nExample:\n```text\n{\n \"program\": {\n // program details\n }\n}\n```\n\nExample:\n```text\n{\n \"programs\": [\n {\n // program details\n }\n ]\n}\n```\n\nExample:\n```text\n{\n \"loyalty_account\":{\n \"id\":\"716cefbc-3d71-4d7c-bdc8-9c7f84c2d793\",\n \"mapping\": {\n \"id\":\"6377d589-3f09-4f00-a0e8-56d7dfc1d2b5\",\n \"phone_number\":\"+16295551234\",\n \"created_at\":\"2020-01-30T00:11:58Z\"\n },\n \"program_id\":\"8031c1b2-d749-4c76-9c40-ae5472ed2e04\",\n \"balance\":0,\n \"lifetime_points\":0,\n \"customer_id\":\"REK96J96AS5AN2Y8Z4HE2Z5NVX\",\n \"created_at\":\"2020-01-30T00:11:58Z\",\n \"updated_at\":\"2020-01-30T00:11:58Z\"\n }\n}\n```\n\nExample:\n```text\n{\n \"loyalty_account\":{\n \"id\":\"716cefbc-3d71-4d7c-bdc8-9c7f84c2d793\",\n \"mappings\":[\n {\n \"id\":\"6377d589-3f09-4f00-a0e8-56d7dfc1d2b5\",\n \"type\":\"PHONE\",\n \"value\":\"+16295551234\",\n \"phone_number\":\"+16295551234\",\n \"created_at\":\"2020-01-30T00:11:58Z\"\n }\n ],\n \"mapping\": {\n \"id\":\"6377d589-3f09-4f00-a0e8-56d7dfc1d2b5\",\n \"type\":\"PHONE\",\n \"value\":\"+16295551234\",\n \"phone_number\":\"+16295551234\",\n \"created_at\":\"2020-01-30T00:11:58Z\"\n },\n \"program_id\":\"8031c1b2-d749-4c76-9c40-ae5472ed2e04\",\n \"balance\":0,\n \"lifetime_points\":0,\n \"customer_id\":\"REK96J96AS5AN2Y8Z4HE2Z5NVX\",\n \"created_at\":\"2020-01-30T00:11:58Z\",\n \"updated_at\":\"2020-01-30T00:11:58Z\"\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.885Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":14,"totalLines":258,"estimatedTokens":1187}}10{"id":"doc-build_on_android-99461ca5","source":"documentation","title":"Build on Android","url":"https://developer.squareup.com/docs/mobile-payments-sdk/android","text":"Example:\n```text\nval trackingConsentState = settingsManager.trackingConsentState\n```\n\nExample:\n```text\n...\ndependencyResolutionManagement {\n repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)\n repositories {\n ...\n maven (\"https://sdk.squareup.com/public/android/\")\n }\n}\n...\n```\n\nExample:\n```text\n...\ndependencies {\n // Your dependencies\n ...\n val squareSdkVersion = \"2.4.0\"\n // Mobile Payments SDK dependency\n implementation(\"com.squareup.sdk:mobile-payments-sdk:$squareSdkVersion\")\n\n // MockReader UI dependency\n implementation(\"com.squareup.sdk:mockreader-ui:$squareSdkVersion\")\n}\n```\n\nExample:\n```text\nclass DemoApplication : Application() {\n override fun onCreate() {\n super.onCreate()\n MobilePaymentsSdk.initialize(getId(), this)\n }\n}\n```\n\nExample:\n```text\noverride fun onResume() {\n super.onResume()\n val authorizationManager = MobilePaymentsSdk.authorizationManager()\n // Authorize and handle authorization successes or failures\n callbackReference = authorizationManager.authorize(accessToken, locationId) { result ->\n when (result) {\n is Success -> {\n finishWithAuthorizedSuccess(result.value)\n }\n is Failure -> {\n when (result.errorCode) {\n NO_NETWORK -> showRetryDialog(result)\n USAGE_ERROR -> showUsageErrorDialog(result)\n }\n }\n }\n }\n}\n\noverride fun onPause() {\n super.onPause()\n // Remove the callback reference to prevent memory leaks\n callbackReference?.clear()\n}\n```\n\nExample:\n```text\noverride fun onCreate() {\n super.onCreate()\n // If in Sandbox - display Mock Reader floating icon\n if (MobilePaymentsSdk.isSandboxEnvironment()) {\n MockReaderUI.show()\n }\n}\n\n// MockReader must hide once deauthorized as it should only be used within the Sandbox environment.\nprivate fun deauthorize() {\n MockReaderUI.hide()\n}\n```\n\nExample:\n```text\nfun startPaymentActivity() {\n val paymentManager = MobilePaymentsSdk.paymentManager()\n // Configure the payment parameters\n val paymentParams = PaymentParameters.Builder(\n amount = Money(100, CurrencyCode.USD),\n paymentAttemptId = UUID.randomUUID().toString(),\n processingMode = processingMode(ProcessingMode.ONLINE_ONLY)\n )\n .referenceId(\"1234\")\n .note(\"Chocolate Cookies and Lemonade\")\n .autocomplete(true)\n .build()\n // Configure the prompt parameters\n val promptParams = PromptParameters(\n mode = PromptMode.DEFAULT,\n additionalPaymentMethods = listOf(Type.KEYED)\n )\n // Start the payment activity\n handle = paymentManager.startPaymentActivity(paymentParams, promptParams) { result ->\n // Callback to handle the payment result\n when (result) {\n is Success -> // show payment details\n is Failure -> // show error message\n }\n }\n}\n\noverride fun onDestroy() {\n handle?.cancel()\n ...\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.886Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":7,"totalLines":123,"estimatedTokens":739}}11{"id":"doc-offline_payments-462702fa","source":"documentation","title":"Offline Payments","url":"https://developer.squareup.com/docs/mobile-payments-sdk/ios/offline-payments","text":"Example:\n```text\nlet paymentSettings = MobilePaymentsSDK.shared.settingsManager.paymentSettings\n\nlet isOfflineProcessingAllowed = paymentSettings.isOfflineProcessingAllowed\nlet offlineTransactionAmountLimit = paymentSettings.offlineTransactionAmountLimit\nlet offlineTotalStoredAmountLimit = paymentSettings.offlineTotalStoredAmountLimit\n```\n\nExample:\n```text\nlet paymentParams = PaymentParameters(\n paymentAttemptID: UUID().uuidString,\n amountMoney: Money(amount: 100, currency: .USD),\n processingMode: .autoDetect\n)\n\nlet paymentHandle = MobilePaymentsSDK.shared.paymentManager.startPayment(\n paymentParams,\n promptParameters: PromptParameters(\n mode: .default,\n additionalMethods: .all\n ),\n from: self,\n delegate: self\n)\n```\n\nExample:\n```text\nlet offlinePaymentQueue = MobilePaymentsSDK.shared.paymentManager.offlinePaymentQueue\n\n// Grab total amount stored \nofflinePaymentQueue.getTotalStoredPaymentsAmount { [weak self] money, error in\n guard let self else { return }\n\n if let error {\n print(\"Error getting total stored payments amount: \\(error)\")\n return\n }\n\n print(\"Total stored amount: \\(money.amount)\")\n}\n\n// Grab offline payments\nofflinePaymentQueue.getPayments { [weak self] offlinePayments, error in\n guard let self else { return }\n\n if let error {\n print(\"Error getting offline payments: \\(error)\")\n return\n }\n\n // Get the total number of payments currently stored\n let totalNumberOfPayments = offlinePayments.count\n\n // Iterate over the offline payments\n offlinePayments.forEach { offlinePayment in\n switch offlinePayment.status {\n case .queued:\n // Payment is retained on the local device; awaiting upload by Mobile Payments SDK.\n break\n case .uploaded:\n // Payment has been successfully uploaded to the Square Server.\n break\n case .failedToUpload:\n // Upload of payment failed due to an unrecoverable error.\n break\n case .failedToProcess:\n // Processing of offline payment by Square Server failed, possibly due to card decline or other transaction issue.\n break\n case .processed:\n // Offline payment has been successfully processed by Square Server and is now visible in the merchant dashboard.\n break\n case .unknown:\n fallthrough\n @unknown default:\n // The status is unknown; verification could not be completed.\n break\n }\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.887Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":3,"totalLines":85,"estimatedTokens":620}}12{"id":"doc-pair_and_manage_card_readers-62e17468","source":"documentation","title":"Pair and Manage Card Readers","url":"https://developer.squareup.com/docs/mobile-payments-sdk/android/pair-manage-readers","text":"Example:\n```text\nfun showSettings() {\n val settingsManager = MobilePaymentsSdk.settingsManager()\n settingsManager.showSettings { result ->\n when (result) {\n is Success -> {\n val settingsClosed = result.value\n logSettingsResult(settingsClosed)\n }\n is Failure -> {\n logSettingsFailure(result.errorCode, result.errorMessage)\n }\n }\n }\n}\n```\n\nExample:\n```text\nfun pairReader() {\n val readerManager = MobilePaymentsSdk.readerManager()\n pairingHandle = readerManager.pairReader { result ->\n when (result) {\n is Success -> {\n val readerFound = result.value\n logPairingResult(readerFound)\n }\n is Failure -> {\n logPairingFailure(result.errorCode, result.errorMessage)\n }\n }\n }\n}\n\nfun onPause() {\n pairingHandle?.stop()\n}\n```\n\nExample:\n```text\nfun observeReaderChanges() {\n val readerManager = MobilePaymentsSdk.readerManager()\n callbackReference = readerManager.setReaderChangedCallback { event ->\n val reader = event.reader\n val change = event.change\n val readerStatus = event.readerStatus\n when (change) {\n ADDED -> // show reader added message \n REMOVED -> // show reader removed message \n else -> // handle other reader status changes \n }\n }\n}\n\nfun onPause() {\n callbackReference?.clear()\n}\n```\n\nExample:\n```text\nprivate fun updateAvailableMethods(view: TextView) {\n val paymentManager = MobilePaymentsSdk.paymentManager()\n // Set up a callback to update the card entry methods when they change\n callbackRef = paymentManager.setAvailableCardEntryMethodChangedCallback { methods ->\n updateCardEntryMethods(view, methods)\n }\n\n // Update the card entry methods immediately\n updateCardEntryMethods(view, paymentManager.getAvailableCardEntryMethods())\n}\n\nprivate fun updateCardEntryMethods(view: TextView, methods: Set<CardEntryMethod>) {\n view.text = when (methods.size) {\n 0 -> \"Reader not connected\"\n 1 -> when (methods.first()) {\n CardEntryMethod.SWIPED -> \"Swipe to pay\"\n CardEntryMethod.CONTACTLESS -> \"Tap to pay\"\n CardEntryMethod.EMV -> \"Insert to pay\"\n }\n // Etc..\n }\n}\n```\n\nExample:\n```text\nfun getReaders() {\n val readerManager = MobilePaymentsSdk.readerManager()\n val readers = readerManager.getReaders()\n // All readers ready to take payments\n val availableReaders = readers.filter {\n it.status == Ready\n }.size\n// All readers accepting tap payments\n val contactlessReaders = readers.filter {\n it.supportedCardEntryMethods.contains(CONTACTLESS)\n }\n// A specific Square reader\n val specificReader = readers.find {\n it.serialNumber == \"4815162342LS815\"\n }\n // Etc..\n}\n```\n\nExample:\n```text\nfun checkFirmwareStatus() {\n val readerManager = MobilePaymentsSdk.readerManager()\n val readers = readerManager.getReaders()\n for (reader in readers) {\n val firmwareInfo = reader.firmwareInfo\n println(\"Firmware version: ${firmwareInfo.version}\")\n when (val status = firmwareInfo.updateStatus) {\n is FirmwareUpdateStatus.None -> println(\"Firmware is up to date\")\n is FirmwareUpdateStatus.Pending -> println(\"Update scheduled for: ${status.updateDate}\")\n is FirmwareUpdateStatus.InProgress -> println(\"Updating: ${status.updatePercentage ?: \"unknown\"}%\")\n }\n }\n}\n```\n\nExample:\n```text\nfun setFirmwareUpdateTime() {\n val readerManager = MobilePaymentsSdk.readerManager()\n val readerSettings = readerManager.readerSettings\n\n // Schedule firmware updates for 2:00 AM\n readerSettings.preferredFirmwareUpdateTime = TimeOfDay(hour = 2, minute = 0)\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.888Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":7,"totalLines":137,"estimatedTokens":962}}13{"id":"doc-gift_cards_api_and_gift_card_activities_api-f26a9022","source":"documentation","title":"Gift Cards API and Gift Card Activities API","url":"https://developer.squareup.com/docs/gift-cards/using-gift-cards-api","text":"Example:\n```text\n{\n \"gift_card_activity\": {\n \"id\": \"gcact_c24da663c0d242f5a29837d8e165bf97\",\n \"type\": \"ACTIVATE\",\n \"location_id\": \"M8AKAD8160XGR\",\n \"created_at\": \"2024-08-11T19:01:14.000Z\",\n \"gift_card_id\": \"gftc:012440e514754c42990f3de4527498dc\",\n \"gift_card_gan\": \"7783320002382646\",\n \"gift_card_balance_money\": {\n \"amount\": 2500,\n \"currency\": \"USD\"\n },\n \"activate_activity_details\": {\n \"amount_money\": {\n \"amount\": 2500,\n \"currency\": \"USD\"\n },\n \"order_id\": \"q8vfn99RLTr7FuMaUtuDG6RHdCcZY\",\n \"line_item_uid\": \"syHOf0zv9OjS2vhkhFozVC\"\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"gift_card_activity\": {\n \"id\": \"gcact_d31b4200f5174fc48cb7138aeae197d0\",\n \"type\": \"REDEEM\",\n \"location_id\": \"M8AKAD8160XGR\",\n \"created_at\": \"2024-08-15T15:57:43.000Z\",\n \"gift_card_id\": \"gftc:065fd3c6e1014c9293bd2d09475ea189\",\n \"gift_card_gan\": \"7783320009623257\",\n \"gift_card_balance_money\": {\n \"amount\": 7450,\n \"currency\": \"USD\"\n },\n \"redeem_activity_details\": {\n \"amount_money\": {\n \"amount\": 2550,\n \"currency\": \"USD\"\n },\n \"payment_id\": \"9WIIrJKZXMgSF9dI7SX9pOlWy7DZY\",\n \"status\": \"COMPLETED\"\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"payment\": {\n \"id\": \"JaHoTpbmK8dofR9cUheOJl9dQVcZY\",\n \"created_at\": \"2024-07-25T17:24:30.345Z\",\n \"updated_at\": \"2024-07-25T17:24:30.444Z\",\n \"amount_money\": {\n \"amount\": 522,\n \"currency\": \"USD\"\n },\n \"status\": \"COMPLETED\",\n \"delay_duration\": \"PT168H\",\n \"source_type\": \"CARD\",\n \"card_details\": {\n \"status\": \"CAPTURED\",\n \"card\": {\n \"card_brand\": \"SQUARE_GIFT_CARD\",\n \"last_4\": \"1923\",\n \"exp_month\": 12,\n \"exp_year\": 2050,\n \"fingerprint\": \"sq-1-y_yFcziMlsxVSomRNQZ7xBaW0F1xxE-6TbcGKl7KOoy3GI1mh094CY4_Ox5RzUN7Vg\",\n \"card_type\": \"DEBIT\",\n \"prepaid_type\": \"PREPAID\",\n \"bin\": \"778332\"\n },\n \"entry_method\": \"KEYED\",\n \"auth_result_code\": \"0\",\n \"card_payment_timeline\": {\n \"authorized_at\": \"2024-07-25T17:24:30.381Z\",\n \"captured_at\": \"2024-07-25T17:24:30.444Z\"\n }\n },\n \"location_id\": \"M8AKAD8160XGR\",\n \"order_id\": \"sYr0y9eUZBoXd2dmXhjvDGOW0e4F\",\n \"total_money\": {\n \"amount\": 522,\n \"currency\": \"USD\"\n },\n \"approved_money\": {\n \"amount\": 522,\n \"currency\": \"USD\"\n },\n \"receipt_url\": \"https://squareupsandbox.com/receipt/preview/JaHoTpbmK8dofR9cUheOJl9dQVcZY\",\n \"delay_action\": \"CANCEL\",\n \"delayed_until\": \"2024-08-01T17:24:30.345Z\",\n \"application_details\": {\n \"square_product\": \"ECOMMERCE_API\",\n \"application_id\": \"sandbox-sq0idb-ioiyW39PwreFzwXoGyLtYg\"\n },\n \"version_token\": \"4WWgYqa7KXd6rIW82VkYxKF36EYkNyx4MGrq0Vxf5cm6o\"\n }\n}\n```\n\nExample:\n```text\n{\n \"gift_card_activity\": {\n \"id\": \"gcact_5a877a9e75d840e990aae654173ed655\",\n \"type\": \"REFUND\",\n \"location_id\": \"M8AKAD8160XGR\",\n \"created_at\": \"2024-08-15T15:59:45.000Z\",\n \"gift_card_id\": \"gftc:065fd3c6e1014c9293bd2d09475ea189\",\n \"gift_card_gan\": \"7783320009623257\",\n \"gift_card_balance_money\": {\n \"amount\": 10000,\n \"currency\": \"USD\"\n },\n \"refund_activity_details\": {\n \"redeem_activity_id\": \"gcact_d31b4200f5174fc48cb7138aeae197d0\",\n \"amount_money\": {\n \"amount\": 2550,\n \"currency\": \"USD\"\n },\n \"payment_id\": \"9WIIrJKZXMgSF9dI7SX9pOlWy7DZY\"\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"refund\": {\n \"id\": \"9WIIrJKZXMgSF9dI7SX9pOlWy7DZY_JnAde8lQt5pt9MLAMZ4UgaXt0sN3ZGqr62Ohx23tGGH\",\n \"status\": \"COMPLETED\",\n \"amount_money\": {\n \"amount\": 1500,\n \"currency\": \"USD\"\n },\n \"payment_id\": \"9WIIrJKZXMgSF9dI7SX9pOlWy7DZY\",\n \"order_id\": \"kayuaH6E5v63RuuaXLSyJa8Qrc4F\",\n \"created_at\": \"2024-08-15T15:59:30.564Z\",\n \"updated_at\": \"2024-08-15T15:59:45.590Z\",\n \"location_id\": \"M8AKAD8160XGR\",\n \"destination_type\": \"CARD\"\n }\n}\n```\n\nExample:\n```text\n{\n \"code\": \"BAD_REQUEST\",\n \"detail\": \"Cannot load balance on this giftcard as the card maximum value has been reached\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n}\n```\n\nExample:\n```text\n{\n \"code\": \"PAYMENT_LIMIT_EXCEEDED\",\n \"detail\": \"The gift card limit for increasing balance reached.\",\n \"category\": \"PAYMENT_METHOD_ERROR\"\n}\n```\n\nExample:\n```text\n{\n \"code\": \"BAD_REQUEST\",\n \"detail\": \"Load amount exceeds maximum buyer daily amount.\",\n \"category\": \"INVALID_REQUEST_ERROR\"\n}\n```\n\nExample:\n```text\n{\n \"code\": \"PAYMENT_LIMIT_EXCEEDED\",\n \"detail\": \"The merchant cannot accrue any more liability.\",\n \"category\": \"PAYMENT_METHOD_ERROR\"\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.889Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":9,"totalLines":190,"estimatedTokens":1148}}14{"id":"doc-offline_payments-d6de5cf3","source":"documentation","title":"Offline Payments","url":"https://developer.squareup.com/docs/mobile-payments-sdk/android/offline-payments","text":"Example:\n```text\nval paymentSettings = MobilePaymentsSdk.settingsManager().getPaymentSettings()\n\nval isOfflineProcessingAllowed = paymentSettings.isOfflineProcessingAllowed\nval offlineTransactionAmountLimit = \n paymentSettings.offlineTransactionAmountLimit\nval offlineTotalStoredAmountLimit = \n paymentSettings.offlineTotalStoredAmountLimit\n```\n\nExample:\n```text\nval paymentManager = MobilePaymentsSdk.paymentManager()\n val baseMoney = Money(100L, USD)\n val builder = PaymentParameters.Builder(\n amount = baseMoney,\n paymentAttemptId = UUID.randomUUID().toString(),\n processingMode = processingMode(ProcessingMode.AUTO_DETECT)\n )\n\n val paymentParameters = builder.build()\n val promptParameters = PromptParameters(\n mode = PromptMode.DEFAULT,\n additionalPaymentMethods = listOf(Type.KEYED)\n )\n\nviewModel.startPaymentActivity(paymentParameters, promptParameters)\n```\n\nExample:\n```text\nval offlineQueue = MobilePaymentsSdk.paymentManager().getOfflinePaymentQueue()\n // Grab total amount stored\n when (val totalStoredAmountResult = offlineQueue.getTotalStoredPaymentAmount()) {\n is Failure -> { … }\n is Success -> {\n val totalStoredAmount = totalStoredAmountResult.value\n }\n }\n\n // Add callback\n val callbackReference = offlineQueue.addGetPaymentsCallback { result ->\n when (result) {\n is Failure -> { … }\n is Success -> {\n val offlinePayments = result.value\n // Number of payments currently stored\n val totalNumberOfPayments = offlinePayments.size\n // Show each OfflinePayment Status to user\n offlinePayments.forEach { offlinePayment ->\n when (offlinePayment.status) {\n OfflineStatus.QUEUED -> {\n //show user via UI\n }\n OfflineStatus.UPLOADED -> {\n //show user via UI\n }\n OfflineStatus.FAILED_TO_PROCESS -> {\n //show user via UI\n }\n OfflineStatus.FAILED_TO_UPLOAD -> {\n //show user via UI\n }\n OfflineStatus.PROCESSED -> {\n //show user via UI\n }\n }\n }\n }\n }\n }\n // Start async getPayments()\n offlineQueue.getPayments()\n\n // clean up when done fetching\n callbackReference.clear()\n```\n\nExample:\n```text\nval paymentManager = MobilePaymentsSdk.paymentManager()\n val handle = paymentManager.startPaymentActivity(paymentParams, promptParams) { result ->\n when (result) {\n is Failure -> { … }\n is Success -> {\n val payment = result.value\n when (payment) {\n is OnlinePayment -> {\n val paymentId = paymentId.id // not nullable\n }\n is OfflinePayment -> {\n val paymentId = payment.id // nullable\n val localPaymentId = payment.localId\n val status = payment.status\n }\n }\n }\n }\n }\n // clean up when done fetching\n handle.cancel()\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.890Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":4,"totalLines":105,"estimatedTokens":810}}15{"id":"doc-pair_and_manage_card_readers-bb6319a1","source":"documentation","title":"Pair and Manage Card Readers","url":"https://developer.squareup.com/docs/mobile-payments-sdk/ios/pair-manage-readers","text":"Example:\n```text\nimport SquareMobilePaymentsSDK\n\nclass <#YourViewController#>: UIViewController {\n private var pairingHandle: PairingHandle?\n\n func startPairing() {\n // `self` must conform to ReaderPairingDelegate\n pairingHandle = MobilePaymentsSDK.shared.readerManager.startPairing(with: self)\n }\n\n func stopPairing() {\n // Manually stop searching for nearby readers.\n pairingHandle?.stop()\n }\n}\n\nextension <#YourViewController#>: ReaderPairingDelegate {\n func readerPairingDidBegin() {\n print(\"Reader pairing did begin!\")\n }\n\n func readerPairingDidSucceed() {\n print(\"Reader Paired!\")\n }\n\n func readerPairingDidFail(with error: Error) {\n // Handle pairing error\n print(\"Error: \\(error.localizedDescription)\")\n }\n}\n```\n\nExample:\n```text\nimport SquareMobilePaymentsSDK\n\nclass <#YourViewController#>: UIViewController {\n\n override func viewDidAppear(_ animated: Bool) {\n super.viewDidAppear(animated)\n // Add this class as an observer to receive reader updates.\n MobilePaymentsSDK.shared.readerManager.add(self)\n }\n\n override func viewDidDisappear(_ animated: Bool) {\n super.viewDidDisappear(animated)\n MobilePaymentsSDK.shared.readerManager.remove(self)\n }\n}\n\nextension <#YourViewController#>: ReaderObserver {\n\n func readerWasAdded(_ readerInfo: ReaderInfo) {\n print(\"Reader Added!\")\n }\n\n func readerWasRemoved(_ readerInfo: ReaderInfo) {\n print(\"Reader Removed!\")\n }\n\n func readerDidChange(_ readerInfo: ReaderInfo, change: ReaderChange) {\n switch change {\n case .batteryDidBeginCharging:\n print(\"Reader is charging.\")\n case .batteryDidEndCharging:\n print(\"Reader not charging\")\n case .batteryLevelDidChange:\n print(\"Reader battery changed to: \\(readerInfo.batteryStatus!.level)\")\n case .statusDidChange:\n print(\"Reader status changed to:\\(readerInfo.statusInfo.status)\")\n @unknown default:\n // Handle other `ReaderChange` events here.\n print(change)\n }\n }\n}\n```\n\nExample:\n```text\nimport SquareMobilePaymentsSDK\nimport UIKit\n\nclass <#YourViewController#>: AvailableCardInputMethodsObserver {\n var availableCardInputMethods = MobilePaymentsSDK.shared.paymentManager.availableCardInputMethods\n\n func viewDidLoad() {\n // Add this class as an observer to receive updates to\n // available card input methods.\n MobilePaymentsSDK.shared.paymentManager.add(self)\n }\n\n public func availableCardInputMethodsDidChange(_ cardInputMethods: CardInputMethods) {\n availableCardInputMethods = cardInputMethods\n\n if availableCardInputMethods.isEmpty {\n print(\"No card readers connected.\")\n } else {\n print(\"Available card input methods: \\(cardInputMethods)\")\n }\n }\n}\n```\n\nExample:\n```text\nimport SquareMobilePaymentsSDK\n\nextension <#YourViewController#> {\n func readyReaderCount() -> Int {\n // You can access all connected readers via \n // `MobilePaymentsSDK.shared.readerManager.readers`\n MobilePaymentsSDK.shared.readerManager.readers.filter {\n $0.statusInfo.status == .ready\n }.count\n }\n\n func hasReadyReader() -> Bool {\n MobilePaymentsSDK.shared.readerManager.readers.contains {\n $0.statusInfo.status == .ready\n }\n }\n}\n```\n\nExample:\n```text\nimport SquareMobilePaymentsSDK\n\nextension <#YourViewController#> {\n func checkFirmwareStatus() {\n for reader in MobilePaymentsSDK.shared.readerManager.readers {\n let firmwareInfo = reader.firmwareInfo\n print(\"Firmware version: \\(firmwareInfo.version ?? \"unknown\")\")\n switch firmwareInfo.updateStatus {\n case .none:\n print(\"Firmware is up to date\")\n case .pending:\n if let updateTime = firmwareInfo.updateTime {\n print(\"Update scheduled for: \\(updateTime)\")\n }\n case .inProgress:\n print(\"Firmware update in progress\")\n case .failed:\n print(\"Firmware update failed\")\n @unknown default:\n break\n }\n }\n }\n}\n```\n\nExample:\n```text\nimport SquareMobilePaymentsSDK\n\nclass <#YourViewController#>: UIViewController, ReaderSettingsObserver {\n\n override func viewDidAppear(_ animated: Bool) {\n super.viewDidAppear(animated)\n MobilePaymentsSDK.shared.readerManager.readerSettings.add(self)\n }\n\n override func viewDidDisappear(_ animated: Bool) {\n super.viewDidDisappear(animated)\n MobilePaymentsSDK.shared.readerManager.readerSettings.remove(self)\n }\n\n func setFirmwareUpdateTime() {\n // Schedule firmware updates for 2:00 AM\n if let time = TimeOfDay(hour: 2, minute: 0) {\n MobilePaymentsSDK.shared.readerManager.readerSettings.preferredFirmwareUpdateTime = time\n }\n }\n\n // MARK: - ReaderSettingsObserver\n\n func readerSettingsDidChange() {\n print(\"Reader settings changed\")\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.891Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":6,"totalLines":187,"estimatedTokens":1294}}16{"id":"doc-authorize_the_mobile_payments_sdk-901fe9d8","source":"documentation","title":"Authorize the Mobile Payments SDK","url":"https://developer.squareup.com/docs/mobile-payments-sdk/ios/configure-authorize","text":"Example:\n```text\nimport SquareMobilePaymentsSDK\n\nclass <#YourViewController#>: UIViewController {\n func authorizeMobilePaymentsSDK(accessToken: String, locationID: String) {\n guard MobilePaymentsSDK.shared.authorizationManager.state == .notAuthorized else {\n return\n }\n\n MobilePaymentsSDK.shared.authorizationManager.authorize(\n withAccessToken: accessToken,\n locationID: locationID) { error in\n guard let authError = error else {\n print(\"Square Mobile Payments SDK successfully authorized.\")\n return\n }\n\n // Handle auth error\n print(\"error: \\(authError.localizedDescription)\")\n }\n }\n}\n```\n\nExample:\n```text\n{\n \"access_token\": \"EAAAEL_EXAMPLE_l5ncx260W8yWz2gGO0GtJeFBJqIdHIXZjpQZ_XW-yxh-Tl7MlF8vIE__n\",\n \"token_type\": \"bearer\",\n \"expires_at\": \"2024-05-15T19:36:00Z\",\n \"merchant_id\": \"ML61OXvVbScCI\",\n \"refresh_token\": \"EXAMPLEzRUFx8bgauwrDjXYIioyCDEB7vyOG0cScx-qfczgTpNtUjAGLResAKOe9\"\n}\n```\n\nExample:\n```text\nfunc deauthorizeMobilePaymentsSDK() {\n MobilePaymentsSDK.shared.authorizationManager.deauthorize {\n // Check authorization status\n print(MobilePaymentsSDK.shared.authorizationManager.state)\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.891Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":3,"totalLines":47,"estimatedTokens":324}}17{"id":"doc-handling_errors-8c3fa646","source":"documentation","title":"Handling Errors","url":"https://developer.squareup.com/docs/mobile-payments-sdk/ios/handling-errors","text":"Example:\n```text\nif let authError = AuthorizationError(rawValue: (error as NSError).code) {\n print(authError.debugInfo) \n}\n```\n\nExample:\n```text\nif let pairingError = ReaderPairingError(rawValue: (error as NSError).code) {\n print(pairingError.debugInfo)\n}\n```\n\nExample:\n```text\nif let updateError = ReaderFirmwareUpdateError(rawValue: (error as NSError).code) {\n print(updateError.debugInfo)\n}\n```\n\nExample:\n```text\nif let paymentError = PaymentError(rawValue: (error as NSError).code) {\n print(paymentError.debugInfo)\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.892Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":4,"totalLines":29,"estimatedTokens":136}}18{"id":"doc-take_a_payment-e0235351","source":"documentation","title":"Take a Payment","url":"https://developer.squareup.com/docs/mobile-payments-sdk/android/take-payments","text":"Example:\n```text\nval paymentParams = PaymentParameters.Builder(\n amount = Money(100, CurrencyCode.USD),\n processingMode = ProcessingMode.AUTO_DETECT,\n allowCardSurcharge = true \n)\n .paymentAttemptId(\"unique-attempt-id\")\n .build()\n```\n\nExample:\n```text\nfun startPaymentActivity() {\n val paymentManager = MobilePaymentsSdk.paymentManager()\n val paymentAttemptId = UUID.randomUUID().toString()\n\n // Configure the payment parameters\n val paymentParams = PaymentParameters.Builder(\n amount = Money(100, CurrencyCode.USD),\n paymentAttemptId = paymentAttemptId,\n processingMode = processingMode(ProcessingMode.AUTO_DETECT),\n allowCardSurcharge = true\n )\n .referenceId(\"1234\")\n .note(\"Chocolate Cookies and Lemonade\")\n .autocomplete(true)\n .build()\n // Configure the prompt parameters\n val promptParams = PromptParameters(\n mode = PromptMode.DEFAULT,\n additionalPaymentMethods = listOf(AdditionalPaymentMethod\n .Type.KEYED)\n )\n // Start the payment activity\n paymentHandle = paymentManager.startPaymentActivity(paymentParams, promptParams) { result ->\n // Handle the payment result\n when (result) {\n is Success -> // show payment details\n is Failure -> // show error message\n }\n }\n}\n\noverride fun onDestroy() {\n paymentHandle?.cancel()\n}\n```\n\nExample:\n```text\nprivate fun handlePaymentResult(result: Result<Payment, PaymentErrorCode>) {\n when (result) {\n is Result.Success -> {\n val payment = result.value\n if (payment is Payment.OnlinePayment) {\n val cardDetails = payment.cardDetails\n val surchargeDetails = cardDetails?.appliedCardSurchargeDetails\n\n if (surchargeDetails != null) {\n val baseSurcharge = surchargeDetails.cardSurchargeMoney\n val taxOnSurcharge = surchargeDetails.taxOnSurchargeMoney\n val totalSurcharge = surchargeDetails.totalSurchargeMoney\n\n // Display surcharge information to customer\n println(\"Base surcharge: ${baseSurcharge.amount} ${baseSurcharge.currencyCode}\")\n println(\"Tax on surcharge: ${taxOnSurcharge?.amount ?: 0} ${baseSurcharge.currencyCode}\")\n println(\"Total surcharge: ${totalSurcharge.amount} ${totalSurcharge.currencyCode}\")\n\n // Use for receipt generation\n generateReceiptWithSurcharge(payment, surchargeDetails)\n } else {\n // No surcharge was applied to this payment\n generateStandardReceipt(payment)\n }\n }\n }\n is Result.Failure -> {\n // Handle payment errors\n handlePaymentError(result.errorCode)\n }\n }\n}\n```\n\nExample:\n```text\nprivate fun showPaymentDetails(payment: Payment, receiptScreen: ReceiptScreen) {\n val cardDetails = (payment as OnlinePayment).cardDetails\n val card = cardDetails!!.card\n receiptScreen.setCardInformation(\n card.cardholderName,\n card.brand,\n card.lastFourDigits\n )\n receiptScreen.setEmvInformation(\n cardDetails.authorizationCode,\n cardDetails.applicationName,\n cardDetails.applicationId\n )\n receiptScreen.setEntryMethod(cardDetails.entryMethod)\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.893Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":4,"totalLines":105,"estimatedTokens":857}}19{"id":"doc-net_sdk-cabcd43b","source":"documentation","title":".NET SDK","url":"https://developer.squareup.com/docs/sdks/dotnet","text":"Example:\n```text\ndotnet add package Square\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.893Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":1,"totalLines":6,"estimatedTokens":15}}20{"id":"doc-java_sdk-6c062cfc","source":"documentation","title":"Java SDK","url":"https://developer.squareup.com/docs/sdks/java","text":"Example:\n```text\n<dependency>\n <groupId>com.squareup</groupId>\n <artifactId>square</artifactId>\n <version>47.0.1.20260715</version>\n</dependency>\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.893Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":1,"totalLines":10,"estimatedTokens":43}}21{"id":"doc-take_a_payment-905000c6","source":"documentation","title":"Take a Payment","url":"https://developer.squareup.com/docs/mobile-payments-sdk/ios/take-payments","text":"Example:\n```text\nextension <#YourViewController#>: PaymentManagerDelegate {\n func paymentManager(_ paymentManager: PaymentManager, didFinish payment: Payment) {\n // You can further inspect each payment once cast\n if let onlinePayment = payment as? OnlinePayment {\n print(\"Online Payment - ID: \\(onlinePayment.id!), status: \\(onlinePayment.status.description)\")\n } else if let offlinePayment = payment as? OfflinePayment {\n print(\"Offline Payment - ID: \\(offlinePayment.localID), status: \\(offlinePayment.status.description)\")\n }\n }\n\n func paymentManager(_ paymentManager: PaymentManager, didFail payment: Payment, withError error: Error) {\n // Handle this the same way as `didFinish`\n }\n\n func paymentManager(_ paymentManager: PaymentManager, didCancel payment: Payment) {\n // Handle this the same way as `didFinish`\n }\n}\n```\n\nExample:\n```text\nimport UIKit\nimport SquareMobilePaymentsSDK\n\nextension <#YourViewController#> {\n func makePaymentParameters() -> PaymentParameters {\n let amount = Money(amount: 100, currency: .USD)\n\n // This is the ID used to reference the payment in your own system. \n let referenceID = \"MY_REFERENCE_ID_1234\"\n\n // This is the ID of the payment attempt for idempotent payment requests.\n let paymentAttemptID = \"paymentAttemptID\"\n\n // allow the payment to be taken online or offline\n let processingMode = processingMode.autoDetect\n\n // allow credit card surcharging for online payments if configured by the merchant\n let allowCardSurcharge = true\n\n // Create the payment parameters\n let paymentParams = PaymentParameters(\n paymentAttemptID: paymentAttemptID,\n amountMoney: amount,\n processingMode: processingMode,\n allowCardSurcharge: allowCardSurcharge\n )\n\n // An optional note to add to the payment.\n paymentParams.note = \"My Note\"\n\n // Optional parameter to associate this payment with a previously created Square order. \n paymentParams.orderID = \"CAISENgvlJ6jLWAzERDzjyHVybY\"\n\n // A user-defined ID to associate with the payment. You can use this field \n // to associate the payment to an entity in an external system.\n paymentParams.referenceID = referenceID\n\n return paymentParams\n }\n}\n```\n\nExample:\n```text\nimport SquareMobilePaymentsSDK\n\nclass <#YourViewController#>: UIViewController {\n\n private var paymentHandle: PaymentHandle?\n\n func startPayment() {\n paymentHandle = MobilePaymentsSDK.shared.paymentManager.startPayment(\n makePaymentParameters(),\n promptParameters: PromptParameters(\n mode: .default,\n additionalMethods: .all\n ),\n from: self,\n delegate: self\n )\n }\n\n func makePaymentParameters() -> PaymentParameters {\n PaymentParameters(\n paymentAttemptID: UUID().uuidString,\n amountMoney: Money(amount: 100, currency: .USD)\n )\n }\n}\n```\n\nExample:\n```text\n// Enable surcharging for this payment\npaymentParams.allowCardSurcharge = true\n\n// Or disable surcharging for this specific payment\npaymentParams.allowCardSurcharge = false\n```\n\nExample:\n```text\nextension YourViewController: PaymentManagerDelegate {\n func paymentManager(_ paymentManager: PaymentManager, didFinish payment: Payment) {\n // Cast to OnlinePayment to access cardDetails\n if let onlinePayment = payment as? OnlinePayment,\n let cardDetails = onlinePayment.cardDetails,\n let surchargeDetails = cardDetails.appliedCardSurchargeDetails {\n\n print(\"Base surcharge amount: \\(surchargeDetails.cardSurchargeMoney)\")\n\n if let taxOnSurcharge = surchargeDetails.taxOnCardSurchargeMoney {\n print(\"Tax on surcharge: \\(taxOnSurcharge)\")\n }\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.894Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":5,"totalLines":121,"estimatedTokens":990}}22{"id":"doc-common_square_api_patterns-d9e38967","source":"documentation","title":"Common Square API Patterns","url":"https://developer.squareup.com/docs/sdks/php/common-square-api-patterns","text":"Example:\n```text\n$customers = $client->customers->list(\n new ListCustomersRequest([\n 'limit' => 10,\n 'sortField' => 'DEFAULT',\n 'sortOrder' => 'DESC'\n ]),\n]);\n\nforeach ($customers as $customer) {\n echo sprintf(\n \"customer: ID: %s Version: %s, Given name: %s, Family name: %s\\n\",\n $customer->getId(),\n $customer->getVersion(),\n $customer->getGivenName(),\n $customer->getFamilyName()\n );\n}\n```\n\nExample:\n```text\n$client->orders->create(\n new CreateOrderRequest([\n 'idempotencyKey' => uniquid(), \n 'order' => new Order([\n 'locationId' => $location['id'],\n ]),\n ]),\n)\n```\n\nExample:\n```text\nuse Square\\Customers\\Requests\\UpdateCustomerRequest\nuse Square\\Exceptions\\SquareApiException;\n\ntry {\n $response = $client->customers->update(\n new UpdateCustomerRequest([\n 'customerId' => 'GZ48C4P2CWVXV7F7K2ZH795RSG',\n 'givenName' => 'Fred',\n 'familyName' => 'Jones',\n 'version' => 7, \n ]),\n );\n\n $customer = $response->getCustomer();\n printf(\"customer updated:<br/>Id: %s, %s, %s, %s<p/>\",\n $customer->getId(),\n $customer->getVersion(),\n $customer->getGivenName(),\n $customer->getFamilyName()\n );\n\n} catch (SquareApiException $e) {\n echo \"SquareApiException occurred: <b/>\";\n echo $e->getMessage() . \"<p/>\";\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.894Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":3,"totalLines":63,"estimatedTokens":357}}23{"id":"doc-square_net_sdk_quickstart-5bc2ae67","source":"documentation","title":"Square .NET SDK Quickstart","url":"https://developer.squareup.com/docs/sdks/dotnet/quick-start","text":"Example:\n```text\ndotnet new console --name Quickstart\n```\n\nExample:\n```text\n{\n \"AppSettings\": {\n \"AccessToken\": \"YOUR-SANDBOX-ACCESS-TOKEN\"\n\n }\n}\n```\n\nExample:\n```text\ndotnet add package Square\ndotnet add package Microsoft.Extensions.Configuration.Json\ndotnet add package Microsoft.Extensions.Configuration\n```\n\nExample:\n```text\nusing Square;\nusing Square.Locations;\n\nusing Microsoft.Extensions.Configuration;\n\nnamespace ExploreLocationsAPI\n{\n public class Program\n {\n private static SquareClient client = null!;\n private static IConfigurationRoot config = null!;\n\n static async Task Main(string[] args)\n {\n var builder = new ConfigurationBuilder()\n .AddJsonFile($\"appsettings.json\", true, true);\n\n config = builder.Build();\n var accessToken = config[\"AppSettings:AccessToken\"];\n\n client = new SquareClient(\n accessToken,\n new ClientOptions\n {\n BaseUrl = SquareEnvironment.Sandbox\n }\n );\n\n await RetrieveLocationsAsync();\n }\n\n static async Task RetrieveLocationsAsync()\n {\n try\n {\n var response = await client.Locations.ListAsync();\n if (response.Locations != null)\n {\n foreach (var location in response.Locations)\n {\n Console.WriteLine($\"location: country = {location.Country} name = {location.Name}\");\n }\n }\n else\n {\n Console.WriteLine(\"No locations found.\");\n }\n }\n catch (SquareApiException e)\n {\n Console.WriteLine(\"SquareApiException occurred:\");\n Console.WriteLine(\"Status Code: {0}\", e.StatusCode);\n Console.WriteLine(\"Error: {0}\", e.Message);\n }\n catch (Exception e)\n {\n Console.WriteLine($\"Exception occurred: {e.Message}\");\n }\n }\n }\n}\n```\n\nExample:\n```text\ndotnet run\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.895Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":5,"totalLines":93,"estimatedTokens":546}}24{"id":"doc-square_php_sdk_quickstart-8dafc7ec","source":"documentation","title":"Square PHP SDK Quickstart","url":"https://developer.squareup.com/docs/sdks/php/quick-start","text":"Example:\n```text\ncomposer require square/square\n```\n\nExample:\n```text\nmkdir quickstart\ncd ./quickstart\n```\n\nExample:\n```text\nSQUARE_ACCESS_TOKEN=yourSandboxAccessToken\n```\n\nExample:\n```text\n<?php\n\nrequire 'vendor/autoload.php';\n\nuse Square\\SquareClient;\nuse Square\\Environments;\nuse Square\\Exceptions\\SquareException;\nuse Dotenv\\Dotenv;\n\n// Load the .env file\n$dotenv = Dotenv::createImmutable(__DIR__);\n$dotenv->load();\n\n$square = new SquareClient(\n token: $_ENV['SQUARE_ACCESS_TOKEN'],\n options: ['baseUrl' => Environments::Sandbox->value // Used by default\n ]\n);\n\ntry {\n $response = $square->locations->list();\n foreach ($response->getLocations() as $location) {\n printf(\n \"%s: %s, %s, %s<p/>\", \n $location->getId(),\n $location->getName(),\n $location->getAddress()?->getAddressLine1(),\n $location->getAddress()?->getLocality()\n );\n }\n} catch (SquareException $e) {\n echo 'Square API Exception occurred: ' . $e->getMessage() . \"\\n\";\n echo 'Status Code: ' . $e->getCode() . \"\\n\";\n}\n?>\n```\n\nExample:\n```text\nphp -S localhost:8000\n```\n\nExample:\n```text\nLHI1YXJ8YSV5Z: Default Test Account, 1600 Pennsylvania Ave NW, Washington\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.895Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":6,"totalLines":66,"estimatedTokens":309}}25{"id":"doc-php_sdk-2e7b9a62","source":"documentation","title":"PHP SDK","url":"https://developer.squareup.com/docs/sdks/php","text":"Example:\n```text\ncomposer require square/square\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.895Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":1,"totalLines":6,"estimatedTokens":17}}26{"id":"doc-common_square_api_patterns-85398f81","source":"documentation","title":"Common Square API Patterns","url":"https://developer.squareup.com/docs/sdks/java/common-square-api-patterns","text":"Example:\n```text\nAsyncCustomersClient customers = client.customers();\n\nint limit = 10;\n\ncustomers\n .list(ListCustomersRequest.builder()\n .limit(limit)\n .sortField(CustomerSortField.DEFAULT)\n .sortOrder(SortOrder.DESC)\n .count(false)\n .build())\n .thenAccept(result -> {\n for (Customer cust : result) {\n System.out.printf(\n \"customer: ID: %s, Version: %s, Given name: %s, Family name: %s\\n\",\n cust.getId().get(),\n cust.getVersion().get(),\n cust.getGivenName().get(),\n cust.getFamilyName().get());\n }\n })\n .exceptionally(exception -> {\n try {\n throw exception.getCause();\n } catch (SquareApiException ae) {\n for (Error err : ae.errors()) {\n System.out.println(err.getCategory());\n System.out.println(err.getCode());\n System.out.println(err.getDetail());\n }\n } catch (Throwable t) {\n t.printStackTrace();\n }\n return null;\n })\n .join();\n```\n\nExample:\n```text\nAsyncCustomersClient customers = client.customers();\n\nUpdateCustomerRequest body = UpdateCustomerRequest.builder()\n .customerId(CUSTOMER_ID)\n .givenName(\"Fred\")\n .familyName(\"Jones\")\n .version(7L)\n .build();\n\ncustomers\n .update(body)\n .thenAccept(result -> {\n Customer cust = result.getCustomer().get();\n System.out.printf(\n \"customer updated:\\n Id: %s, Version:{%s} Given name:{%s}, Family name: {%s}\",\n cust.getId().get(),\n cust.getVersion().get(),\n cust.getGivenName().get(),\n cust.getFamilyName().get());\n })\n .exceptionally(exception -> {\n try {\n throw exception.getCause();\n } catch (SquareApiException ae) {\n for (Error err : ae.errors()) {\n System.out.println(err.getCategory());\n System.out.println(err.getCode());\n System.out.println(err.getDetail());\n }\n } catch (Throwable t) {\n t.printStackTrace();\n }\n return null;\n })\n .join();\n```\n\nExample:\n```text\nAsyncLocationsClient locations = client.locations();\n\nString locationId = \"M8AKAD8160XGR\";\n\nLocation loc = Location.builder()\n .twitterUsername(Nullable.ofNull())\n .websiteUrl(\"https://developer.squareup.com\")\n .build();\n\nUpdateLocationRequest body = UpdateLocationRequest.builder()\n .locationId(locationId)\n .location(loc)\n .build();\n\nlocations\n .update(body)\n .thenAccept(result -> {\n Location location = result.getLocation().get();\n System.out.println(location);\n })\n .exceptionally(exception -> {\n try {\n throw exception.getCause();\n } catch (SquareApiException ae) {\n for (Error err : ae.errors()) {\n System.out.println(err.getCategory());\n System.out.println(err.getCode());\n System.out.println(err.getDetail());\n }\n } catch (Throwable t) {\n t.printStackTrace();\n }\n return null;\n })\n .join();\n```\n\nExample:\n```text\nAsyncOrdersClient orders = client.orders();\n\norders.update(\n body, RequestOptions.builder().addHeader(\"X-Clear-Null\", \"true\").build());\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.895Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":4,"totalLines":127,"estimatedTokens":947}}27{"id":"doc-php_sdk_migration_guide-93f733a4","source":"documentation","title":"PHP SDK Migration Guide","url":"https://developer.squareup.com/docs/sdks/php/migration","text":"Example:\n```text\n// LEGACY\nuse Square\\Legacy\\SquareClient as LegacySquareClient;\n\n$client = new LegacySquareClient(\n config: [\n 'accessToken' => getenv('SQUARE_ACCESS_TOKEN') ?? '',\n 'environment' => 'sandbox',\n ],\n);\n\n// NEW\nuse Square\\Environments;\nuse Square\\SquareClient;\n\n$client = new SquareClient(\n token: getenv('SQUARE_ACCESS_TOKEN') ?? '',\n options: [\n 'baseUrl' => Environments::Sandbox->value,\n ],\n);\n```\n\nExample:\n```text\n<?php\n\nuse Square\\Environments;\nuse Square\\Legacy\\SquareClient as LegacySquareClient;\nuse Square\\Legacy\\Models\\CreateOrderRequest;\nuse Square\\SquareClient;\nuse Square\\Locations\\Requests\\GetLocationsRequest;\n\n$legacyClient = new LegacySquareClient([\n 'accessToken' => getenv('SQUARE_ACCESS_TOKEN') ?? '',\n 'environment' => 'sandbox',\n]);\n\n$client = new SquareClient(\n token: getenv('SQUARE_ACCESS_TOKEN') ?? '',\n options: [\n 'baseUrl' => Environments::Sandbox->value,\n ],\n);\n\nfunction getLocation($client) {\n $response = $client->locations->get(\n new GetLocationsRequest([\n 'locationId' => 'YOUR_LOCATION_ID',\n ]),\n );\n return $response->getLocation();\n}\n\nfunction createOrder($legacyClient, $location) { \n $order = new Order($location['id']);\n $request = new CreateOrderRequest;\n $request->setIdempotencyKey(uniqid());\n $request->setOrder($order);\n return $legacyClient->getOrdersApi()->createOrder($request);\n}\n\n$location = getLocation($client);\n$result = createOrder($legacyClient, $location);\n```\n\nExample:\n```text\n// LEGACY\n$order = new Order($location['id']);\n$request = new CreateOrderRequest;\n$request->setIdempotencyKey(uniqid());\n$request->setOrder($order);\n$legacyClient->getOrdersApi()->createOrder($request);\n```\n\nExample:\n```text\n// NEW\n$client->orders->create(\n new CreateOrderRequest([\n 'idempotencyKey' => uniquid(), \n 'order' => new Order([\n 'locationId' => $location['id'],\n ]),\n ]),\n)\n```\n\nExample:\n```text\n// LEGACY\nuse Square\\Legacy\\SquareClient as LegacySquareClient;\n\n$client = new LegacySquareClient(\n config: [\n 'environment' => 'sandbox',\n ],\n);\n\n// NEW\nuse Square\\Environments;\nuse Square\\SquareClient;\n\n$client = new SquareClient(\n options: [\n 'baseUrl' => Environments::Sandbox->value, // Enums can be accessed with '->value'.\n ],\n);\n```\n\nExample:\n```text\n// LEGACY\n$client->getCustomersApi()->listCustomers();\n```\n\nExample:\n```text\n// NEW\n$client->customers->list();\n```\n\nExample:\n```text\n// NEW\n$client->customers->groups->list();\n```\n\nExample:\n```text\n// LEGACY\n$limit = 10;\n$listCustomersResponse = $legacyClient->getCustomersApi()->listCustomers(\n limit: $limit,\n sortField: 'DEFAULT',\n sortOrder: 'DESC'\n);\n\nwhile (!empty($listCustomersResponse->getCustomers())) {\n $customers = $listCustomersResponse->getCustomers();\n\n foreach ($customers as $customer) {\n echo sprintf(\n \"customer: ID: %s Version: %s, Given name: %s, Family name: %s\\n\",\n $customer->getId(),\n $customer->getVersion(),\n $customer->getGivenName(),\n $customer->getFamilyName()\n );\n }\n\n $cursor = $listCustomersResponse->getCursor();\n if ($cursor) {\n $listCustomersResponse = $legacyClient->getCustomersApi()->listCustomers(\n cursor: $cursor,\n limit: $limit,\n sortField: 'DEFAULT',\n sortOrder: 'DESC'\n );\n } else {\n break;\n }\n}\n\n// NEW\n$customers = $client->customers->list(\n new ListCustomersRequest([\n 'limit' => 10,\n 'sortField' => 'DEFAULT',\n 'sortOrder' => 'DESC'\n ]),\n]);\n\nforeach ($customers as $customer) {\n echo sprintf(\n \"customer: ID: %s Version: %s, Given name: %s, Family name: %s\\n\",\n $customer->getId(),\n $customer->getVersion(),\n $customer->getGivenName(),\n $customer->getFamilyName()\n );\n}\n```\n\nExample:\n```text\n$customers = $client->customers->list(\n new ListCustomersRequest([\n 'limit' => 10,\n 'sortField' => 'DEFAULT',\n 'sortOrder' => 'DESC'\n ]),\n]);\n\nforeach ($customers->getPages() as $page) {\n foreach($customer as $page->getItems()) {\n echo sprintf(\n \"customer: ID: %s Version: %s, Given name: %s, Family name: %s\\n\",\n $customer->getId(),\n $customer->getVersion(),\n $customer->getGivenName(),\n $customer->getFamilyName()\n );\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.896Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":10,"totalLines":210,"estimatedTokens":1122}}28{"id":"doc-square_node_js_sdk_quickstart-aa130ce2","source":"documentation","title":"Square Node.js SDK Quickstart","url":"https://developer.squareup.com/docs/sdks/nodejs/quick-start","text":"Example:\n```text\nmkdir quickstart\ncd ./quickstart\n```\n\nExample:\n```text\nnpm init --yes\n```\n\nExample:\n```text\nnpm install square\n```\n\nExample:\n```text\nconst { SquareClient, SquareEnvironment, SquareError } = require(\"square\");\nrequire('dotenv').config()\n\nconst client = new SquareClient({\n token: process.env.SQUARE_ACCESS_TOKEN,\n environment: SquareEnvironment.Sandbox,\n});\n\nasync function getLocations() {\n try {\n let listLocationsResponse = await client.locations.list();\n\n let locations = listLocationsResponse.locations;\n\n locations.forEach(function (location) {\n console.log(\n location.id + \": \" +\n location.name + \", \" +\n location.address.addressLine1 + \", \" +\n location.address.locality\n );\n });\n } catch (error) {\n if (error instanceof SquareError) {\n error.errors.forEach(function (e) {\n console.log(e.category);\n console.log(e.code);\n console.log(e.detail);\n });\n } else {\n console.log(\"Unexpected error occurred: \", error);\n }\n }\n};\n\ngetLocations();\n```\n\nExample:\n```text\nexport SQUARE_ACCESS_TOKEN=yourSandboxAccessToken\n```\n\nExample:\n```text\nSet-item -Path Env:SQUARE_ACCESS_TOKEN -Value yourSandboxAccessToken\n```\n\nExample:\n```text\nset SQUARE_ACCESS_TOKEN=yourSandboxAccessToken\n```\n\nExample:\n```text\nnode quickstart.js\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.896Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":8,"totalLines":77,"estimatedTokens":338}}29{"id":"doc-build_on_ios-c5147767","source":"documentation","title":"Build on iOS","url":"https://developer.squareup.com/docs/mobile-payments-sdk/ios","text":"Example:\n```text\nlet consentState = trackingConsentManager.getTrackingConsentState()\n```\n\nExample:\n```text\ntrackingConsentManager.setTrackingConsentStateIsGranted(true) // or false\n```\n\nExample:\n```text\nuse_frameworks!\n\npod \"SquareMobilePaymentsSDK\", \"~> 2.4.0\"\n\n# To use a simulated reader device to take sandbox payments, add the optional MockReaderUI:\npod \"MockReaderUI\", \"~> 2.4.0\", configurations: ['Debug']\n```\n\nExample:\n```text\nFRAMEWORKS=\"${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}\"\n\"${FRAMEWORKS}/SquareMobilePaymentsSDK.framework/setup\"\n```\n\nExample:\n```text\nimport UIKit\nimport SquareMobilePaymentsSDK\n\n@UIApplicationMain\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n\n func application(_ application: UIApplication, \n didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {\n\n MobilePaymentsSDK.initialize(\n applicationLaunchOptions: launchOptions, \n squareApplicationID: \"<#your_square_application_id#>\"\n )\n\n return true\n }\n}\n```\n\nExample:\n```text\nimport SquareMobilePaymentsSDK\n\nclass <#YourViewController#>: UIViewController {\n func authorizeMobilePaymentsSDK(accessToken: String, locationID: String) {\n guard MobilePaymentsSDK.shared.authorizationManager.state == .notAuthorized else {\n return\n }\n\n MobilePaymentsSDK.shared.authorizationManager.authorize(\n accessToken: accessToken,\n locationID: locationID) { error in\n if let authError = error {\n // Handle auth error\n print(\"error: \\(authError.localizedDescription)\")\n return\n }\n\n print(\"Square Mobile Payments SDK successfully authorized.\")\n }\n }\n}\n```\n\nExample:\n```text\nimport CoreLocation\n\nclass <#YourViewController#>: UIViewController {\n private lazy var locationManager = CLLocationManager()\n\n // Call this in your app's lifecycle\n func requestLocationPermission() {\n switch CLLocationManager.authorizationStatus() {\n case .notDetermined:\n locationManager.requestWhenInUseAuthorization()\n case .restricted, .denied:\n print(\"Show UI directing the user to the iOS Settings app\")\n case .authorizedAlways, .authorizedWhenInUse:\n print(\"Location services have already been authorized.\")\n @unknown default:\n fatalError()\n }\n }\n}\n```\n\nExample:\n```text\nimport CoreBluetooth\n\nfinal class <#YourViewController#>: ViewController {\n private var centralManager: CBCentralManager?\n\n // Call this in your app's lifecycle\n func requestBluetoothPermissions() {\n guard CBManager.authorization == .notDetermined else {\n return\n }\n\n centralManager = CBCentralManager(\n delegate: self,\n queue: .main,\n options: nil\n )\n }\n}\n\nextension <#YourViewController#>: CBCentralManagerDelegate {\n func centralManagerDidUpdateState(_ central: CBCentralManager) {\n // Check state and prompt for permission if necessary\n }\n}\n```\n\nExample:\n```text\nimport MockReaderUI\n\nprivate lazy var mockReaderUI: MockReaderUI? = {\n do {\n return try MockReaderUI(for: MobilePaymentsSDK.shared)\n } catch {\n assertionFailure(\"Could not instantiate a mock reader UI: \\(error.localizedDescription)\")\n }\n\n return nil\n}()\n\ntry? mockReaderUI?.present()\n```\n\nExample:\n```text\nimport SquareMobilePaymentsSDK\n\nclass <#YourViewController#>: UIViewController {\n\n private var paymentHandle: PaymentHandle?\n\n func startPayment() {\n paymentHandle = MobilePaymentsSDK.shared.paymentManager.startPayment(\n makePaymentParameters(),\n promptParameters: PromptParameters(\n mode: .default,\n additionalMethods: .all\n ),\n from: self,\n delegate: self\n )\n }\n\n func makePaymentParameters() -> PaymentParameters {\n PaymentParameters(\n paymentAttemptID: UUID().uuidString,\n amountMoney: Money(amount: 100, currency: .USD),\n processingMode: processingMode.onlineOnly\n )\n }\n}\n\nextension <#YourViewController#>: PaymentManagerDelegate {\n public func paymentManager(\n _ paymentManager: PaymentManager,\n didFinish payment: Payment\n ) {\n print(\"Payment Did Finish: \\(payment)\")\n }\n\n public func paymentManager(\n _ paymentManager: PaymentManager,\n didFail payment: Payment,\n withError error: Error\n ) {\n // Handle Payment Failed\n print(\"error: \\(error.localizedDescription)\")\n }\n\n public func paymentManager(\n _ paymentManager: PaymentManager,\n didCancel payment: Payment\n ) {\n // Handle Payment Canceled\n }\n}\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.897Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":10,"totalLines":196,"estimatedTokens":1217}}30{"id":"doc-square_java_sdk_quickstart-9c28e23d","source":"documentation","title":"Square Java SDK Quickstart","url":"https://developer.squareup.com/docs/sdks/java/quick-start","text":"Example:\n```text\nmvn archetype:generate \\\n -DinteractiveMode=false \\\n -DgroupId=com.square.examples \\\n -DartifactId=quickstart \\\n -DarchetypeArtifactId=maven-archetype-quickstart\n```\n\nExample:\n```text\ncd quickstart\n```\n\nExample:\n```text\n<project xmlns=\"http://maven.apache.org/POM/4.0.0\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd\">\n <modelVersion>4.0.0</modelVersion>\n <groupId>com.square.examples</groupId>\n <artifactId>quickstart</artifactId>\n <packaging>jar</packaging>\n <version>1.0-SNAPSHOT</version>\n <name>quickstart</name>\n <url>http://maven.apache.org</url>\n <dependencies>\n <dependency>\n <groupId>com.squareup</groupId>\n <artifactId>square</artifactId>\n <version>SDK_VERSION_HERE</version>\n <scope>compile</scope>\n </dependency>\n <dependency>\n <groupId>junit</groupId>\n <artifactId>junit</artifactId>\n <version>3.8.1</version>\n <scope>test</scope>\n </dependency>\n </dependencies>\n <build>\n <plugins>\n <plugin>\n <groupId>org.codehaus.mojo</groupId>\n <artifactId>exec-maven-plugin</artifactId>\n <version>3.0.0</version>\n <configuration>\n <mainClass>com.square.examples.Quickstart</mainClass>\n <cleanupDaemonThreads>false</cleanupDaemonThreads>\n </configuration>\n </plugin>\n <plugin>\n <groupId>org.apache.maven.plugins</groupId>\n <artifactId>maven-compiler-plugin</artifactId>\n <version>3.8.1</version>\n <configuration>\n <source>8</source>\n <target>8</target>\n </configuration>\n </plugin>\n </plugins>\n </build>\n</project>\n```\n\nExample:\n```text\npackage com.square.examples;\n\nimport java.io.IOException;\nimport java.io.InputStream;\nimport java.util.Properties;\n\nimport com.squareup.square.AsyncSquareClient;\nimport com.squareup.square.core.Environment;\nimport com.squareup.square.types.Location;\nimport com.squareup.square.types.Error;\nimport com.squareup.square.core.SquareApiException;\nimport com.squareup.square.types.Address;\n\npublic class Quickstart {\n public static void main(String[] args) {\n InputStream inputStream =\n Quickstart.class.getResourceAsStream(\"/config.properties\");\n Properties prop = new Properties();\n\n try {\n prop.load(inputStream);\n } catch (IOException e) {\n System.out.println(\"Error reading properties file\");\n e.printStackTrace();\n }\n\n AsyncSquareClient client = AsyncSquareClient.builder()\n .token(prop.getProperty(\"SQUARE_ACCESS_TOKEN\"))\n .environment(Environment.SANDBOX)\n .build();\n\n client.locations().list()\n .thenAccept(result -> {\n System.out.println(\"Location(s) for this account:\");\n result.getLocations().ifPresent(locations -> {\n for (Location l : locations) {\n // Build location details safely\n StringBuilder locationInfo = new StringBuilder();\n\n // Add ID if present\n l.getId().ifPresent(id -> locationInfo.append(\"ID: \").append(id));\n\n // Add name if present\n l.getName().ifPresent(name -> \n locationInfo.append(locationInfo.length() > 0 ? \", \" : \"\")\n .append(\"Name: \").append(name));\n\n // Handle address details if present\n l.getAddress().ifPresent(address -> {\n // Add address line 1 if present\n address.getAddressLine1().ifPresent(line1 -> \n locationInfo.append(locationInfo.length() > 0 ? \", \" : \"\")\n .append(\"Address: \").append(line1));\n\n // Add locality (city) if present\n address.getLocality().ifPresent(locality -> \n locationInfo.append(locationInfo.length() > 0 ? \", \" : \"\")\n .append(\"City: \").append(locality));\n });\n\n // Print the complete location information\n System.out.println(locationInfo.toString());\n }\n });\n })\n .exceptionally(exception -> {\n if (exception.getCause() instanceof SquareApiException) {\n SquareApiException apiException = (SquareApiException) exception.getCause();\n apiException.errors().forEach(error -> {\n System.out.println(\"Category: \" + error.getCategory());\n System.out.println(\"Code: \" + error.getCode());\n System.out.println(\"Detail: \" + error.getDetail());\n });\n } else {\n System.out.println(\"An unexpected error occurred:\");\n exception.printStackTrace();\n }\n return null;\n })\n .join();\n }\n}\n```\n\nExample:\n```text\nSQUARE_ACCESS_TOKEN=yourSandboxAccessToken\n```\n\nExample:\n```text\nmvn package -DskipTests\n```\n\nExample:\n```text\nmvn exec:java -Dexec.mainClass=\"com.square.examples.Quickstart\"\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.897Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":7,"totalLines":165,"estimatedTokens":1368}}31{"id":"doc-common_square_api_patterns-b78b3565","source":"documentation","title":"Common Square API Patterns","url":"https://developer.squareup.com/docs/sdks/dotnet/common-square-api-patterns","text":"Example:\n```text\nvar pager = await client.Customers.ListAsync(new ListCustomersRequest\n{\n Limit = 10,\n SortField = CustomerSortField.Default,\n SortOrder = SortOrder.Desc,\n Count = false\n});\n\nawait foreach (var customer in pager)\n{\n Console.WriteLine(\n \"customer: ID: {0} Version: {1}, Given name: {2}, Family name: {3}\", \n customer.Id,\n customer.Version, \n customer.GivenName, \n customer.FamilyName\n );\n}\n```\n\nExample:\n```text\nvar updateCustomer = new UpdateCustomerRequest\n{\n CustomerId = customerId,\n GivenName = \"Fred\",\n FamilyName = \"Jones\",\n Version = 7\n};\n\nvar response = await client.Customers.UpdateAsync(updateCustomer);\nvar customer = response.Customer ?? throw new Exception(\"response.Customer is null\");\nConsole.WriteLine(\"customer updated:\\n Id: {0}, Version: {1} Given name: {2}, Family name: {3}\", \n customer.Id, \n customer.Version, \n customer.GivenName, \n customer.FamilyName\n);\n```\n\nExample:\n```text\nawait client.Locations.UpdateAsync(\n new UpdateLocationRequest\n {\n LocationId = locationId,\n Location = new Location\n {\n WebsiteUrl = \"https://developer.squareup.com\"\n }\n },\n new RequestOptions\n {\n AdditionalBodyProperties = new\n {\n location = new Dictionary<string, object?>\n {\n [\"twitter_username\"] = null\n }\n }\n }\n);\n```\n\nExample:\n```text\n{\n \"location\": {\n \"website_url\": \"https://developer.squareup.com\",\n \"twitter_username\": null\n }\n}\n```\n\nExample:\n```text\nawait client.Orders.UpdateAsync(\n body,\n new RequestOptions\n {\n AdditionalHeaders = new Dictionary<string, string>\n {\n [\"X-Clear-Null\"] = \"true\"\n }\n }\n);\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.898Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":5,"totalLines":91,"estimatedTokens":452}}32{"id":"doc-node_js_sdk-139402c7","source":"documentation","title":"Node.js SDK","url":"https://developer.squareup.com/docs/sdks/nodejs","text":"Example:\n```text\nnpm install square\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.898Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":1,"totalLines":6,"estimatedTokens":14}}33{"id":"doc-common_square_api_patterns-70d90d1c","source":"documentation","title":"Common Square API Patterns","url":"https://developer.squareup.com/docs/sdks/nodejs/common-square-api-patterns","text":"Example:\n```text\nimport { SquareClient, SquareError } from \"square\";\nconst client = new SquareClient({\n token: process.env.SQUARE_ACCESS_TOKEN\n});\n\nlistCustomers();\n\nasync function listCustomers() {\n const limit = 10;\n\n try {\n let customerPager = await client.customers.list({\n limit,\n sortField: \"DEFAULT\",\n sortOrder: \"DESC\"\n });\n for await (const customer of customerPager) {\n console.log(\"customer: ID: \" + customer.id,\n \"Version: \" + customer.version + \",\",\n \"Given name: \" + customer.givenName + \",\",\n \"Family name: \" + customer.familyName);\n }\n } catch (error) {\n if (error instanceof SquareError) {\n console.error(\"Error occurred: \" + error.message);\n } else {\n console.error(\"Unexpected error occurred: \", error);\n }\n }\n}\n```\n\nExample:\n```text\nimport { SquareClient, SquareError } from \"square\";\nimport { randomUUID } from 'crypto';\n\nconst client = new SquareClient({\n token: process.env.SQUARE_ACCESS_TOKEN,\n});\n\nasync function createOrder() {\n try {\n const idempotencyKey = randomUUID();\n const locationId = getLocationId();\n const order = await client.orders.create({\n idempotencyKey: idempotencyKey,\n order: {\n locationId: locationId,\n lineItems: [\n {\n name: \"New Item\",\n quantity: \"1\",\n basePriceMoney: {\n amount: BigInt(100),\n currency: \"USD\",\n },\n },\n ],\n },\n });\n } catch (error) {\n if (error instanceof SquareError) {\n console.error(\"Error occurred: \" + error.message);\n } else {\n console.error(\"Unexpected error occurred: \", error);\n }\n }\n}\n\ncreateOrder();\n```\n\nExample:\n```text\nimport { SquareClient, SquareError } from \"square\";\n\nconst client = new SquareClient({\n token: process.env.SQUARE_ACCESS_TOKEN,\n});\n\nasync function updateCustomer() {\n try {\n let updateCustomerResponse = await client.customers.update(\n {\n customerId: \"GZ48C4P2CWVXV7F7K2ZH795RSG\",\n givenName: \"Fred\",\n familyName: \"Jones\",\n version: BigInt(11)\n }\n );\n } catch (error) {\n if (error instanceof SquareError) {\n console.error(\"Error occurred: \" + error.message);\n } else {\n console.error(\"Unexpected error occurred: \", error);\n }\n }\n}\n\nupdateCustomer();\n```\n\nExample:\n```text\nimport { SquareClient, SquareError } from \"square\";\n\nconst client = new SquareClient({\n token: process.env.SQUARE_ACCESS_TOKEN\n});\n\nasync function updateLocation() {\n try {\n let updateLocationResponse = await client.locations.update({\n locationId: 'M8AKAD8160XGR',\n location: {\n twitterUsername: null,\n websiteUrl: 'https://developer.squareup.com',\n },\n });\n\n console.log(updateLocationResponse.location);\n } catch (error) {\n if (error instanceof SquareError) {\n console.error(\"Error occurred: \" + error.message);\n } else {\n console.error(\"Unexpected error occurred: \", error);\n }\n }\n};\n\nupdateLocation();\n```\n\nExample:\n```text\nawait client.orders.update(\n {\n orderId: \"K1BZGPD0QB7ER26AFXFYKBG9K0\",\n idempotencyKey: idempotencyKey,\n order: {\n locationId: locationId,\n referenceId: null\n },\n },\n {\n headers: {\n \"X-Clear-Null\": \"true\"\n }\n }\n);\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.899Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":5,"totalLines":156,"estimatedTokens":833}}34{"id":"doc-square_ruby_sdk_quickstart-d5f303ff","source":"documentation","title":"Square Ruby SDK Quickstart","url":"https://developer.squareup.com/docs/sdks/ruby/quick-start","text":"Example:\n```text\ngem install square.rb\n```\n\nExample:\n```text\nmkdir quickstart\ncd ./quickstart\n```\n\nExample:\n```text\nSQUARE_ACCESS_TOKEN=yourSandboxAccessToken\n```\n\nExample:\n```text\nrequire 'square'\n\nclient = Square::Client.new(\n token: ENV['SQUARE_ACCESS_TOKEN'],\n base_url: Square::Environment::SANDBOX\n)\n\nbegin\n result = client.locations.list\n\n if result.locations\n result.locations.each do |location|\n printf(\"%s: %s, %s, %s\\n\",\n location.id,\n location.name,\n location.address&.address_line_1,\n location.address&.locality)\n end\n end\n\nrescue => e\n warn \"Error: #{e.message}\"\n if e.respond_to?(:errors) && e.errors\n e.errors.each do |error|\n warn error.category\n warn error.code\n warn error.detail\n end\n end\nend\n```\n\nExample:\n```text\nruby ./quickstart.rb\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.899Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":5,"totalLines":56,"estimatedTokens":216}}35{"id":"doc-square_python_sdk_quickstart-7ce6caae","source":"documentation","title":"Square Python SDK Quickstart","url":"https://developer.squareup.com/docs/sdks/python/quick-start","text":"Example:\n```text\npip install squareup\n```\n\nExample:\n```text\nmkdir quickstart\ncd ./quickstart\n```\n\nExample:\n```text\nSQUARE_ACCESS_TOKEN=yourSandboxAccessToken\n```\n\nExample:\n```text\nfrom square import Square\nfrom square.environment import SquareEnvironment\nfrom square.core.api_error import ApiError\nfrom dotenv import load_dotenv\nimport os\n\nload_dotenv()\n\nclient = Square(\n environment=SquareEnvironment.SANDBOX,\n token=os.environ['SQUARE_ACCESS_TOKEN']\n)\n\ntry:\n response = client.locations.list()\n for location in response.locations:\n print(f\"{location.id}: \", end=\"\")\n print(f\"{location.name}, \", end=\"\")\n print(f\"{location.address}, \", end=\"\")\n\nexcept ApiError as e:\n for error in e.errors:\n print(error.category)\n print(error.code)\n print(error.detail)\n```\n\nExample:\n```text\npython ./quickstart.py\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.899Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":5,"totalLines":51,"estimatedTokens":219}}36{"id":"doc-ruby_sdk-eb117d80","source":"documentation","title":"Ruby SDK","url":"https://developer.squareup.com/docs/sdks/ruby","text":"Example:\n```text\ngem install square.rb\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.899Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":1,"totalLines":6,"estimatedTokens":14}}37{"id":"doc-java_sdk_migration_guide-67219807","source":"documentation","title":"Java SDK Migration Guide","url":"https://developer.squareup.com/docs/sdks/java/migration","text":"Example:\n```text\n// LEGACY\nimport com.squareup.square.legacy.Environment;\nimport com.squareup.square.legacy.SquareClient;\n\nSquareClient client = new SquareClient.Builder()\n .environment(<YOUR_ENVIRONMENT>) // defaults to Environment.PRODUCTION\n .accessToken(\"YOUR_TOKEN\") // defaults to using \"SQUARE_ACCESS_TOKEN\" environment variable\n .build();\n\n// NEW\nimport com.squareup.square.Environment;\nimport com.squareup.square.SquareClient;\n\nSquareClient client = SquareClient.builder()\n .environment(<YOUR_ENVIRONMENT>) // defaults to Environment.PRODUCTION\n .token(\"YOUR_TOKEN\"); // defaults to using \"SQUARE_TOKEN\" environment variable\n .build();\n```\n\nExample:\n```text\npackage com.square.examples;\n\nimport com.squareup.square.SquareClient;\nimport com.squareup.square.core.Environment;\nimport com.squareup.square.legacy.exceptions.ApiException;\nimport com.squareup.square.legacy.models.CreateOrderRequest;\nimport com.squareup.square.legacy.models.CreateOrderResponse;\nimport com.squareup.square.legacy.models.Order;\nimport com.squareup.square.types.GetLocationResponse;\nimport com.squareup.square.types.GetLocationsRequest;\nimport com.squareup.square.types.Location;\nimport java.io.IOException;\nimport java.util.Optional;\nimport java.util.UUID;\n\npublic class SideBySide {\n\n public static void main(String[] args) {\n com.squareup.square.legacy.SquareClient legacyClient = new com.squareup.square.legacy.SquareClient.Builder()\n .accessToken(System.getenv(\"SQUARE_TOKEN\"))\n .environment(com.squareup.square.legacy.Environment.SANDBOX)\n .build();\n\n SquareClient client = SquareClient.builder()\n .token(System.getenv(\"SQUARE_TOKEN\"))\n .environment(Environment.SANDBOX)\n .build();\n\n Location location = getLocation(client).get();\n\n CreateOrderResponse result = createOrder(legacyClient, location);\n }\n\n private static Optional<Location> getLocation(SquareClient client) {\n GetLocationResponse response = client.locations()\n .get(GetLocationsRequest.builder()\n .locationId(\"YOUR_LOCATION_ID\")\n .build());\n return response.getLocation();\n }\n\n private static CreateOrderResponse createOrder(\n com.squareup.square.legacy.SquareClient legacyClient, Location location) {\n try {\n return legacyClient\n .getOrdersApi()\n .createOrder(new CreateOrderRequest.Builder()\n .idempotencyKey(UUID.randomUUID().toString())\n .order(new Order.Builder(location.getId().get()).build())\n .build());\n } catch (ApiException | IOException e) {\n throw new RuntimeException(e);\n }\n }\n}\n```\n\nExample:\n```text\n<dependency>\n <groupId>com.squareup</groupId>\n <artifactId>square</artifactId>\n <version>47.0.1.20260715</version>\n</dependency>\n<dependency>\n <groupId>com.squareup</groupId>\n <artifactId>square-legacy</artifactId>\n <version>47.0.1.20260715</version>\n</dependency>\n```\n\nExample:\n```text\n// LEGACY\nCreatePaymentRequest request = new CreatePaymentRequest.Builder(\"SOURCE_ID\", \"IDEMPOTENCY_KEY\")\n .amountMoney(new Money.Builder().amount(20L).currency(\"USD\").build())\n .tipMoney(new Money.Builder().amount(3L).currency(\"USD\").build())\n .build();\n\n// NEW\nCreatePaymentRequest request = CreatePaymentRequest.builder()\n .sourceId(\"SOURCE_ID\")\n .idempotencyKey(UUID.randomUUID().toString())\n .amountMoney(Money.builder().amount(20L).currency(Currency.USD).build())\n .tipMoney(Money.builder().amount(3L).currency(Currency.USD).build())\n .build();\n```\n\nExample:\n```text\n// LEGACY\nclient.getCustomersApi().listCustomers();\n```\n\nExample:\n```text\n// NEW\nclient.customers().list();\n```\n\nExample:\n```text\n// NEW\nclient.customers().groups().list();\n```\n\nExample:\n```text\n// LEGACY\nimport com.squareup.square.legacy.SquareClient;\nimport com.squareup.square.legacy.models.ListPaymentsResponse;\nimport com.squareup.square.legacy.models.Payment;\nimport java.util.List;\n\nSquareClient legacyClient = new SquareClient.Builder()\n .accessToken(\"YOUR_TOKEN\")\n .build();\n\nListPaymentsResponse response = legacyClient.getPaymentsApi().listPayments(...);\nList<Payment> payments = response.getPayments();\nString cursor = response.getCursor();\n\nfor (Payment payment : payments) {\n System.out.printf(\"payment: ID: %s Created at: %s, Updated at: %s\\n\",\n payment.getId(), payment.getCreatedAt(), payment.getUpdatedAt());\n}\n\nwhile (!response.getCursor().isEmpty()) {\n response = legacyClient.getPaymentsApi().listPayments(..., cursor, ...);\n payments = response.getPayments();\n cursor = response.getCursor();\n\n for (Payment payment : payments) {\n System.out.printf(\"payment: ID: %s Created at: %s, Updated at: %s\\n\",\n payment.getId(), payment.getCreatedAt(), payment.getUpdatedAt());\n }\n}\n\n// NEW\nimport com.squareup.square.SquareClient;\nimport com.squareup.square.core.SyncPagingIterable;\nimport com.squareup.square.types.Payment;\nimport com.squareup.square.types.PaymentsListRequest;\n\nSquareClient square = SquareClient.builder().token(\"YOUR_TOKEN\").build();\n\nSyncPagingIterable<Payment> payments =\n square.payments().list(PaymentsListRequest.builder().total(100L).build());\n\nfor (Payment payment : payments) {\n System.out.printf(\n \"payment: ID: %s Created at: %s, Updated at: %s\\n\",\n payment.getId(), payment.getCreatedAt(), payment.getUpdatedAt());\n}\n```\n\nExample:\n```text\n// First page\nList<Payment> pagePayments = payments.getItems();\nfor (Payment payment : pagePayments) {\n // ...\n}\n\n// Remaining pages\nwhile (payments.hasNext()) {\n pagePayments = payments.nextPage().getItems();\n for (Payment payment : pagePayments) {\n // ...\n }\n}\n```\n\nExample:\n```text\n// LEGACY\nSquareClient legacyClient = new SquareClient.Builder().accessToken(\"YOUR_TOKEN\").build();\n\nListLocationsResponse syncResponse = legacyClient.getLocationsApi().listLocations();\nCompletableFuture<ListLocationsResponse> asyncResponse = legacyClient.getLocationsApi().listLocationsAsync();\n\n// NEW\nSquareClient client = SquareClient.builder().token(\"YOUR_TOKEN\").build();\nAsyncSquareClient asyncClient = AsyncSquareClient.builder().token(\"YOUR_TOKEN\").build();\n\nListLocationsResponse syncResponse = client.locations().list();\nCompletableFuture<ListLocationsResponse> asyncResponse = asyncClient.locations().list();\n```\n\nExample:\n```text\n// LEGACY\nnew Transaction.Builder().clientId(null).build();\n\n// NEW\nTransaction.builder().clientId(Nullable.ofNull()).build();\nTransaction.builder().clientId(Nullable.of(null)).build(); // also valid\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.901Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":11,"totalLines":223,"estimatedTokens":1740}}38{"id":"doc-net_sdk_migration_guide-85a0c2d8","source":"documentation","title":".NET SDK Migration Guide","url":"https://developer.squareup.com/docs/sdks/dotnet/migration","text":"Example:\n```text\nusing Square;\n\n// new\nvar client = new SquareClient(\n token, // optional if you configure SQUARE_TOKEN environment variable\n new ClientOptions\n {\n BaseUrl = SquareEnvironment.Production // default, so you can omit ClientOptions parameter\n }\n);\n\n// legacy\nvar legacyClient = new Square.Legacy.SquareClient.Builder()\n .BearerAuthCredentials(new BearerAuthModel.Builder(token).Build())\n .Environment(Square.Legacy.Environment.Production)\n .Build();\n```\n\nExample:\n```text\nusing Square;\nusing Square.Legacy.Authentication;\nusing Square.Locations;\n\npublic class Program\n{\n public static async Task Main(string[] args)\n {\n var token = Environment.GetEnvironmentVariable(\"SQUARE_TOKEN\") ??\n throw new Exception(\"Missing SQUARE_TOKEN environment variable\");\n\n // LEGACY\n var legacyClient = new Square.Legacy.SquareClient.Builder()\n .BearerAuthCredentials(new BearerAuthModel.Builder(token).Build())\n .Environment(Square.Legacy.Environment.Sandbox)\n .Build();\n\n // NEW\n var client = new SquareClient(\n token,\n new ClientOptions\n {\n BaseUrl = SquareEnvironment.Sandbox\n }\n );\n\n // use new client\n var location = await GetLocationAsync(client);\n // use legacy client\n await CreateOrderAsync(legacyClient, location);\n }\n\n private static async Task<Location> GetLocationAsync(SquareClient client)\n {\n var response = await client.Locations.GetAsync(\n new GetLocationsRequest\n {\n LocationId = \"YOUR_LOCATION_ID\"\n }\n );\n\n return response.Location ?? throw new Exception(\"response.Location is null\");\n }\n\n private static async Task CreateOrderAsync(\n Square.Legacy.SquareClient legacyClient,\n Location location\n )\n {\n await legacyClient\n .OrdersApi\n .CreateOrderAsync(new Square.Legacy.Models.CreateOrderRequest.Builder()\n .IdempotencyKey(Guid.NewGuid().ToString())\n .Order(new Square.Legacy.Models.Order.Builder(location.Id).Build())\n .Build());\n }\n}\n```\n\nExample:\n```text\n// Legacy with builder pattern\nvar request = new Square.Legacy.Models.CreatePaymentRequest.Builder(\"SOURCE_ID\", \"IDEMPOTENCY_KEY\")\n .AmountMoney(new Square.Legacy.Models.Money.Builder().Amount(20L).Currency(\"USD\").Build())\n .TipMoney(new Square.Legacy.Models.Money.Builder().Amount(3L).Currency(\"USD\").Build())\n .Build();\n\n// Legacy with positional constructor parameters\nrequest = new Square.Legacy.Models.CreatePaymentRequest(\n \"SOURCE_ID\",\n Guid.NewGuid().ToString(),\n new Square.Legacy.Models.Money(20L, \"USD\"),\n new Square.Legacy.Models.Money(3L, \"USD\")\n);\n\n// New with property initializers\nvar request = new CreatePaymentRequest\n{\n SourceId = \"SOURCE_ID\",\n IdempotencyKey = Guid.NewGuid().ToString(),\n AmountMoney = new Money\n {\n Amount = 20L,\n Currency = Currency.Usd\n },\n TipMoney = new Money\n {\n Amount = 3L,\n Currency = Currency.Usd\n }\n};\n```\n\nExample:\n```text\n// Legacy\nclient.CustomersApi.ListCustomersAsync()\n```\n\nExample:\n```text\n// New\nclient.Customers.ListAsync()\n```\n\nExample:\n```text\n// New\nclient.Customers.Groups.ListAsync();\n```\n\nExample:\n```text\n// Legacy\nusing Square.Legacy;\nusing Square.Legacy.Authentication;\n\nvar legacyClient = new SquareClient.Builder()\n .BearerAuthCredentials(new BearerAuthModel.Builder(\"YOUR_TOKEN\").Build())\n .Build();\n\nstring? cursor = null;\n\ndo\n{\n var response = await legacyClient.PaymentsApi.ListPaymentsAsync(total: 100, cursor: cursor);\n if (response.Payments is null) break;\n var payments = response.Payments;\n foreach (var payment in payments)\n {\n Console.WriteLine(\n \"payment: ID: {0}, Created at: {1}, Updated at: {2}\",\n payment.Id,\n payment.CreatedAt,\n payment.UpdatedAt\n );\n }\n\n cursor = response.Cursor;\n\n} while (!string.IsNullOrEmpty(cursor));\n\n// New\nusing Square;\nusing Square.Payments;\n\nvar client = new SquareClient(\"YOUR_TOKEN\");\n\nvar payments = await client.Payments.ListAsync(new ListPaymentsRequest{ Limit = 100 });\nawait foreach (var payment in payments)\n{\n Console.WriteLine(\n \"payment: ID: {0}, Created at: {1}, Updated at: {2}\",\n payment.Id,\n payment.CreatedAt,\n payment.UpdatedAt\n );\n}\n```\n\nExample:\n```text\nawait foreach (var page in payments.AsPagesAsync())\n{\n foreach (var payment in page.Items)\n {\n Console.WriteLine(\n \"payment: ID: {0}, Created at: {1}, Updated at: {2}\",\n payment.Id,\n payment.CreatedAt,\n payment.UpdatedAt\n );\n }\n}\n```\n\nExample:\n```text\n// Legacy\nawait legacyClient.LocationsApi.UpdateLocationAsync(\n locationId,\n new Square.Legacy.Models.UpdateLocationRequest.Builder()\n .Location(new Square.Legacy.Models.Location.Builder()\n .WebsiteUrl(\"https://developer.squareup.com\")\n .TwitterUsername(null)\n .Build()\n ).Build()\n);\n\n// New\nawait client.Locations.UpdateAsync(\n new UpdateLocationRequest\n {\n LocationId = locationId,\n Location = new Location\n {\n WebsiteUrl = \"https://developer.squareup.com\"\n }\n },\n new RequestOptions\n {\n AdditionalBodyProperties = new\n {\n location = new Dictionary<string, object?>\n {\n [\"twitter_username\"] = null\n }\n }\n }\n);\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.901Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":9,"totalLines":235,"estimatedTokens":1423}}39{"id":"doc-common_square_api_patterns-bdf4785d","source":"documentation","title":"Common Square API Patterns","url":"https://developer.squareup.com/docs/sdks/ruby/common-square-api-patterns","text":"Example:\n```text\npage = client.customers.list(\n body: {\n limit: 10,\n sort_field: 'DEFAULT',\n sort_order: 'DESC'\n }\n)\n\npage.auto_paging_each do |customer|\n puts(customer.id)\n```\n\nExample:\n```text\nclient.orders.create(\n body: {\n \"idempotency_key\" => SecureRandom.uuid,\n \"order\" => {\n \"location_id\" => location.id\n }\n }\n)\n```\n\nExample:\n```text\nrequire 'square'\n\nbegin\n response = client.customers.update_customer(\n customer_id: \"GZ48C4P2CWVXV7F7K2ZH795RSG\",\n body: {\n given_name: \"Fred\",\n family_name: \"Jones\",\n version: 7\n }\n )\n\n customer = response.data.customer\n puts \"Customer: ID: #{customer.id}, \" \\\n \"Version: #{customer.version}, \" \\\n \"Given name: #{customer.given_name}, \" \\\n \"Family name: #{customer.family_name}\"\n\nrescue Square::SquareError => e\n puts e.response_code\n puts e.errors\nend\n```\n\nExample:\n```text\nclient.locations.update(\n body: { \n location_id=\"M8AKAD8160XGR\",\n location={\n \"website_url\": \"https://developer.squareup.com\",\n \"twitter_username\": None\n }\n }\n)\n```\n\nExample:\n```text\nclient.orders.update(\n body: { \n\t order_id=\"A4BMDU4438ZLB\",\n\t order={\n\t \"website_url\": \"https://developer.squareup.com\",\n\t \"twitter_username\": None\n\t }\n\t },\n\t request_options: {\n headers={\"X-Clear-Null\": \"true\"}\n }\n)\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.902Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":5,"totalLines":82,"estimatedTokens":347}}40{"id":"doc-python_sdk-7781200a","source":"documentation","title":"Python SDK","url":"https://developer.squareup.com/docs/sdks/python","text":"Example:\n```text\npip install squareup\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.902Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":1,"totalLines":6,"estimatedTokens":14}}41{"id":"doc-node_js_sdk_migration_guide-72fb00fd","source":"documentation","title":"Node.js SDK Migration Guide","url":"https://developer.squareup.com/docs/sdks/nodejs/migration","text":"Example:\n```text\n// LEGACY\nimport { Client, Environment } from \"square/legacy\";\nconst client = new Client({\n bearerAuthCredentials: {\n accessToken: process.env.SQUARE_ACCESS_TOKEN,\n },\n environment: Environment.Sandbox,\n});\n\n// NEW\nimport { SquareClient, SquareEnvironment } from \"square\";\nconst client = new SquareClient({\n token: process.env.SQUARE_ACCESS_TOKEN,\n environment: SquareEnvironment.Sandbox,\n});\n```\n\nExample:\n```text\nimport { randomUUID } from \"crypto\";\nimport { Square, SquareClient } from \"square\";\nimport { Client } from \"square/legacy\";\n\nconst client = new SquareClient({\n token: process.env.SQUARE_ACCESS_TOKEN,\n});\n\nconst legacyClient = new Client({\n bearerAuthCredentials: {\n accessToken: process.env.SQUARE_ACCESS_TOKEN!,\n },\n});\n\nasync function getLocation(): Promise<Square.Location> {\n return (\n await client.locations.get({\n locationId: \"YOUR_LOCATION_ID\",\n })\n ).location!;\n}\n\nasync function createOrder() {\n const location = await getLocation();\n await legacyClient.ordersApi.createOrder({\n idempotencyKey: randomUUID(),\n order: {\n locationId: location.id!,\n lineItems: [\n {\n name: \"New Item\",\n quantity: \"1\",\n basePriceMoney: {\n amount: BigInt(100),\n currency: \"USD\",\n },\n },\n ],\n },\n });\n}\n\ncreateOrder();\n```\n\nExample:\n```text\n// LEGACY\nawait client.customersApi.listCustomers(undefined, 10, undefined, \"DESC\");\n```\n\nExample:\n```text\n// NEW\nawait client.customers.list({\n limit: 10,\n sortOrder: \"DESC\",\n});\n```\n\nExample:\n```text\n// LEGACY\nawait client.customersApi.listCustomers();\n```\n\nExample:\n```text\n// NEW\nawait client.customers.list();\n```\n\nExample:\n```text\n// NEW\nawait client.customers.groups.list();\n```\n\nExample:\n```text\n// LEGACY\nconst limit = 10;\nlet listCustomersResponse = await customersApi.listCustomers(\n undefined,\n limit,\n \"DEFAULT\",\n \"DESC\"\n);\n\nwhile (!isEmpty(listCustomersResponse.result)) {\n let customers = listCustomersResponse.result.customers;\n\n customers.forEach(function (cust) {\n console.log(\n \"customer: ID: \" + cust.id,\n \"Version: \" + cust.version + \",\",\n \"Given name: \" + cust.givenName + \",\",\n \"Family name:\" + cust.familyName\n );\n });\n\n let cursor = listCustomersResponse.result.cursor;\n if (cursor) {\n listCustomersResponse = await customersApi.listCustomers(\n cursor,\n limit,\n \"DEFAULT\",\n \"DESC\"\n );\n } else {\n break;\n }\n}\n\n// NEW\nlet customerPager = await client.customers.list({\n limit: 10,\n sortField: \"DEFAULT\",\n sortOrder: \"DESC\",\n});\nfor await (const customer of customerPager) {\n console.log(\n \"customer: ID: \" + customer.id,\n \"Version: \" + customer.version + \",\",\n \"Given name: \" + customer.givenName + \",\",\n \"Family name: \" + customer.familyName\n );\n}\n```\n\nExample:\n```text\nlet customerPager = await client.customers.list({\n limit: 10,\n sortField: \"DEFAULT\",\n sortOrder: \"DESC\",\n});\nconst printCustomers = (customers: Square.Customer[]) => {\n for (const customer of customers) {\n console.log(\n \"customer: ID: \" + customer.id,\n \"Version: \" + customer.version + \",\",\n \"Given name: \" + customer.givenName + \",\",\n \"Family name: \" + customer.familyName\n );\n }\n};\n\nprintCustomers(customerPager.data);\nwhile (customerPager.hasNextPage()) {\n customerPager = await customerPager.getNextPage();\n printCustomers(customerPager.data);\n}\n```\n\nExample:\n```text\nawait client.orders.create({\n idempotencyKey: idempotencyKey,\n order: {\n locationId: locationId,\n lineItems: [\n {\n name: \"New Item\",\n quantity: \"1\",\n basePriceMoney: {\n amount: BigInt(100),\n currency: \"USD\",\n },\n },\n ],\n },\n});\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.902Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":10,"totalLines":197,"estimatedTokens":946}}42{"id":"doc-square_go_sdk_quickstart-68665a3a","source":"documentation","title":"Square Go SDK Quickstart","url":"https://developer.squareup.com/docs/sdks/go/quick-start","text":"Example:\n```text\nmkdir quickstart\ncd quickstart\ngo mod init quickstart\n```\n\nExample:\n```text\ngo get github.com/square/square-go-sdk\n```\n\nExample:\n```text\nimport (\n \"context\"\n \"fmt\"\n \"os\"\n\n square \"github.com/square/square-go-sdk\"\n client \"github.com/square/square-go-sdk/client\"\n option \"github.com/square/square-go-sdk/option\"\n)\n\nfunc main() {\n client := client.NewClient(\n \toption.WithToken(\n os.Getenv(\"SQUARE_ACCESS_TOKEN\"),\n ),\n option.WithBaseURL(square.Environments.Sandbox),\n )\n\n // Get the list of locations\n response, err := client.Locations.List(context.TODO())\n if err != nil {\n \tfmt.Println(err)\n } else {\n \tfor l := range response.Locations {\n \t\tfmt.Printf(\"ID: %s \\n\", *response.Locations[l].ID)\n \t\tfmt.Printf(\"Name: %s \\n\", *response.Locations[l].Name)\n \t\tfmt.Printf(\"Address: %s \\n\", *response.Locations[l].Address.AddressLine1)\n \t\tfmt.Printf(\"%s \\n\", *response.Locations[l].Address.Locality)\n \t}\n\n \tfmt.Println(response)\n }\n}\n```\n\nExample:\n```text\nexport SQUARE_ACCESS_TOKEN=yourSandboxAccessToken\n```\n\nExample:\n```text\nSet-item -Path Env:SQUARE_ACCESS_TOKEN -Value yourSandboxAccessToken\n```\n\nExample:\n```text\nset SQUARE_ACCESS_TOKEN=yourSandboxAccessToken\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.903Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":6,"totalLines":65,"estimatedTokens":306}}43{"id":"doc-python_sdk_migration_guide-06bfaf9a","source":"documentation","title":"Python SDK Migration Guide","url":"https://developer.squareup.com/docs/sdks/python/migration","text":"Example:\n```text\n// LEGACY\nimport os\nfrom square_legacy.client import Client as LegacySquare \n\nclient = LegacySquare(\n environment=\"sandbox\",\n access_token=os.environ.get(\"SQUARE_TOKEN\")\n)\n\n// NEW\nimport os\nfrom square import Square\nfrom square.environment import SquareEnvironment\n\nclient = Square(\n environment=SquareEnvironment.SANDBOX,\n token=os.environ.get(\"SQUARE_TOKEN\")\n)\n```\n\nExample:\n```text\nfrom square_legacy.client import Client as LegacySquare\nfrom square import Square\n\ndef main():\n client = Square(token=os.environ.get(\"SQUARE_TOKEN\"))\n legacy_client = LegacySquare(access_token=os.environ.get(\"SQUARE_TOKEN\"))\n\n # List all payments with the new client.\n new_response = client.payments.list()\n\n # List all payments with the legacy client.\n legacy_response = legacy_client.payments.list_payments()\n```\n\nExample:\n```text\n// LEGACY\nresponse = client.customers.create_customer(\n { \n \"idempotency_key\": str(uuid.uuid4()),\n \"given_name\": 'given-vs1',\n \"family_name\": 'family-vs1',\n \"address\": {\n \"address_line_1\": '1955 Broadway',\n \"address_line_2\": 'Oakland, CA 94612'\n } \n)\n```\n\nExample:\n```text\n// NEW\nresponse = client.customers.create(\n idempotency_key=str(uuid.uuid4()),\n given_name=\"given-vs1\",\n family_name=\"family-vs1\",\n address={\n \"address_line_1\": \"1955 Broadway\",\n \"address_line_2\": \"Oakland, CA 94612\"\n } \n)\n```\n\nExample:\n```text\n// LEGACY\nresponse = client.locations.list_locations()\nlocation = response.body['locations'][0]\nname = location['name']\n\n// NEW\nresponse = client.locations.list()\nlocation_name = response.locations[0]\nname = location.name\n```\n\nExample:\n```text\n// LEGACY\nresponse = client.locations.list_locations()\n\nif response.is_success():\n for location in response.body['locations']:\n print(f\"{location['id']}: \", end=\"\")\n print(f\"{location['name']}, \", end=\"\")\n print(f\"{location['address']['address_line_1']}, \", end=\"\")\n print(f\"{location['address']['locality']}\")\n\nelif response.is_error():\n for error in response.errors:\n print(error['category'])\n print(error['code'])\n print(error['detail'])\n```\n\nExample:\n```text\nfrom square.core.api_error import ApiError\n\ntry:\n response = client.locations.list()\n for location in response.items:\n print(f\"{location.id}: \", end=\"\")\n print(f\"{location.name}, \", end=\"\")\n print(f\"{location.address.address_line_1}, \", end=\"\")\n print(f\"{location.address.locality}\")\n\nexcept ApiError as e:\n for error in e.errors:\n print(error.category)\n print(error.code)\n print(error.detail)\n```\n\nExample:\n```text\n// LEGACY\nresult = client.customers.list_customers(\n limit=10,\n sort_field='DEFAULT',\n sort_order='DESC'\n)\n\nif result.is_success():\n while (result.body != {}):\n for cust in result.body['customers']:\n print(f\"customer: ID: {cust['id']}, \", end=\"\")\n print(f\"Version: {cust['version']}, \", end=\"\")\n print(f\"Given name: {cust['given_name']}, \", end=\"\")\n print(f\"Family name: {cust['family_name']}\")\n\n if (result.cursor):\n result = client.customers.list_customers(\n limit=limit,\n sort_field='DEFAULT',\n sort_order='DESC',\n cursor=result.cursor\n )\n else:\n break\n\nelif result.is_error():\n for error in result.errors:\n print(error['category'])\n print(error['code'])\n print(error['detail'])\n\n// NEW\ntry:\n\t response = client.customers.list(\n\t limit=10,\n\t sort_field='DEFAULT',\n\t sort_order='DESC'\n\t )\n for customer in response:\n print(f\"customer: ID: {customer.id}, \", end=\"\")\n print(f\"Version: {cutomer.version}, \", end=\"\")\n print(f\"Given name: {customer.given_name}, \", end=\"\")\n print(f\"Family name: {customer.family_name}\")\nexcept ApiError as e:\n for error in e.errors:\n print(error.category)\n print(error.code)\n print(error.detail)\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.903Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":8,"totalLines":171,"estimatedTokens":1009}}44{"id":"doc-common_square_api_patterns-596683f7","source":"documentation","title":"Common Square API Patterns","url":"https://developer.squareup.com/docs/sdks/python/common-square-api-patterns","text":"Example:\n```text\ncustomers = client.customers.list(\n limit=10,\n sortField=\"DEFAULT\",\n sortOrder=\"DESC\"\n)\n\nfor customer in customers:\n print(\n f\"Customer: ID: {customer.id}, \"\n f\"Version: {customer.version}, \"\n f\"Given name: {customer.given_name}, \"\n f\"Family name: {customer.family_name}\"\n )\n```\n\nExample:\n```text\nclient.orders.create(\n idempotency_key=str(uuid.uuid4()),\n order={\n \"location_id\": location.id\n }\n)\n```\n\nExample:\n```text\nfrom square.core.api_error import ApiError\n\ntry:\n response = client.customers.update(\n customer_id=\"GZ48C4P2CWVXV7F7K2ZH795RSG\",\n given_name=\"Fred\",\n family_name=\"Jones\",\n version=7\n )\n\n customer = response.customer\n print(\n f\"Customer: ID: {customer.id}, \"\n f\"Version: {customer.version}, \"\n f\"Given name: {customer.given_name}, \"\n f\"Family name: {customer.family_name}\"\n )\n\nexcept ApiError as e:\n print(e.status_code)\n print(e.message)\n```\n\nExample:\n```text\nclient.locations.update(\n location_id=\"M8AKAD8160XGR\",\n location={\n \"website_url\": \"https://developer.squareup.com\",\n \"twitter_username\": None\n }\n)\n```\n\nExample:\n```text\nfrom square.core import RequestOptions\n\nclient.orders.update(\n order_id=\"A4BMDU4438ZLB\",\n order={\n \"reference_id\": \"Order1322\",\n \"ticket_name\": None\n }\n request_options=RequestOptions(\n additional_headers={\"X-Clear-Null\": \"true\"}\n )\n)\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.903Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":5,"totalLines":80,"estimatedTokens":376}}45{"id":"doc-ruby_sdk_migration_guide-6fa766d9","source":"documentation","title":"Ruby SDK Migration Guide","url":"https://developer.squareup.com/docs/sdks/ruby/migration","text":"Example:\n```text\n// LEGACY\nrequire 'square_legacy'\n\nclient = Square::LegacyClient.new(\n bearer_auth_credentials: BearerAuthCredentials.new(\n access_token: ENV['SQUARE_ACCESS_TOKEN']\n ),\n environment: 'sandbox'\n)\n\n// NEW\nrequire 'square'\n\nclient = Square::Client.new(\n base_url: Square::Environment::PRODUCTION,\n token: 'YOUR_API_KEY'\n)\n```\n\nExample:\n```text\nrequire 'square'\nrequire 'square_legacy'\n\nclient = Square::Client.new(token: 'YOUR_API_KEY')\n\nlegacy_client = Square::LegacyClient.new(\n bearer_auth_credentials: BearerAuthCredentials.new(\n access_token: ENV['SQUARE_ACCESS_TOKEN']\n ),\n)\n\n# List all payments with the new client.\nnew_response = client.payments.list()\n\n# List all payments with the legacy client.\nlegacy_response = legacy_client.payments.list_payments()\n```\n\nExample:\n```text\n// LEGACY\nresult = client.customers.create_customer(body: {\n \"given_name\": \"John\",\n \"family_name\": \"Smith\",\n \"address\": {\n \"address_line_1\": \"500 Electric Ave\",\n \"address_line_2\": \"Suite 600\",\n \"locality\": \"New York\",\n \"administrative_district_level_1\": \"NY\",\n \"postal_code\": \"98100\",\n \"country\": \"US\"\n }\n})\n\n// NEW\nresult = client.customers.create(body: {\n \"given_name\": \"John\",\n \"family_name\": \"Smith\",\n \"address\": {\n \"address_line_1\": \"500 Electric Ave\",\n \"address_line_2\": \"Suite 600\",\n \"locality\": \"New York\",\n \"administrative_district_level_1\": \"NY\",\n \"postal_code\": \"98100\",\n \"country\": \"US\"\n }\n})\n```\n\nExample:\n```text\n// LEGACY\nresult = customers_api.create_customer(body: body)\n\nif result.success?\n puts result.data\nelsif result.error?\n warn result.errors\nend\n```\n\nExample:\n```text\nbegin\n result = customers_api.create_customer(body: body)\nrescue Square::SquareError => e\n puts(\"The server could not be reached\")\n puts(e.cause)\nend\n```\n\nExample:\n```text\npage = client.customers.list(\n body: {\n limit: 10,\n sort_field: 'DEFAULT',\n sort_order: 'DESC'\n }\n)\n\npage.auto_paging_each do |customer|\n puts(customer.id)\n```\n\n<|endofdoc|>","metadata":{"transformedAt":"2026-08-18T15:16:46.904Z","totalSectionsIncluded":0,"totalCodeBlocksIncluded":6,"totalLines":109,"estimatedTokens":503}}46