2021-02-26 Changelog

Square Customers API Orders API Payments API Connect v1

Version Summary

• Square Version: 2021-02-26
• Java: 9.0.0.20210226
• .NET: 9.0.0
• Node.js: 9.0.0
• PHP: 9.0.0.20210226
• Python: 9.0.0.20210226
• Ruby: 9.0.0.20210226

Details

Link to section

Existing API updates

• Customers API:

  • New webhooks (beta). Square now sends notifications for the following events:

    • customer.created

    • customer.deleted

    • customer.updated

• Orders API:

  • CreateOrder. Removed the location_id field from the request. It was an unused field.

• Payments API:

  • Payment. This type now returns the card_payment_timeline (CardPaymentTimeline) as part of the card_details field.

• v1 Items API:

  • The following endpoints are retired:

    • AdjustInventory: Use the Square Inventory API BatchChangeInventory endpoint.

    • ListInventory: Use the Square Inventory API BatchRetrieveInventoryCounts endpoint.

• v1 Employees.Timecards:

  • The following endpoints are retired:

    • CreateTimecard: Use the Square Labor API CreateShift endpoint.

    • DeleteTimecard: Use the Square Labor API DeleteShift endpoint.

    • ListTimecards: Use the Square Labor API SearchShifts endpoint.

    • RetrieveTimecards: Use the Square Labor API GetShift endpoint.

    • UpdateTimecard: Use the Square Labor API UpdateShift endpoint.

    • ListTimecardEvents: No direct replacement. To learn about replacing the v1 functionality, see the migration guide.

• v1 Employees.CashDrawers:

  • The following endpoints are retired:

    • ListCashDrawerShifts: Use the Square CashDrawerShifts API ListCashDrawerShifts endpoint.

    • RetrieveCashDrawerShift: Use the Square CashDrawerShifts API RetrieveCashDrawerShift endpoint.

• v1 Transactions.BankAccounts:

  • The following endpoints are retired:

    • ListBankAccounts: Use the Square Bank Accounts API ListBankAccounts endpoint.

    • RetrieveBankAccount: Use the Square Bank Accounts API GetBankAccount endpoint.

Link to section

SDKs

• All Square SDKs:

  By default, all SDKs send requests to Square's production (https://connect.squareup.com) or sandbox (https://connect.squareupsandbox.com) hosts based on the client's environment parameter.

  You now have the option to use a custom URL instead. To use a custom URL, follow the example for your language to set the environment parameter to custom and the customUrl parameter to your URL:

  • Java

    Copy

    • 1
    • 2
    • 3

    new SquareClient.Builder()
      .environment(Environment.CUSTOM)
      .customUrl("https://example.com")
    

  • .NET

    Copy

    • 1
    • 2
    • 3

    new Square.SquareClient.Builder()
      .Environment(Environment.Custom)
      .CustomUrl("https://example.com")
    

  • Node.js

    Copy

    • 1
    • 2
    • 3
    • 4

    new Client({
      environment: Environment.Custom,
      customUrl: 'https://example.com'
    });
    

  • PHP

    Copy

    • 1
    • 2
    • 3
    • 4

    new Square\SquareClient([
      'environment' => Environment::CUSTOM,
      'customUrl' => 'https://example.com',
    ]);
    

  • Python

    Copy

    • 1
    • 2
    • 3

    Client(
      environment = 'custom',
      custom_url = 'https://example.com',)
    

  • Ruby

    Copy

    • 1
    • 2
    • 3
    • 4

    Square::Client.new(
      environment: 'custom',
      custom_url: 'https://example.com'
    );
    

• Square .NET SDK:

  Square has overridden the Equals and GetHashCode methods for models:

  • In the Equals override, Square has implemented a field-level comparison.

  • The Square GetHashCode override now ensures that hashes are deterministic and unique for each object.

• Square Node.js SDK:

  Endpoints that return 64-bit integers now return a BigInt object instead of a Number object.

• Connect Node.js SDK: (deprecated)

  The deprecated Connect Node.js SDK is in the security maintenance state. It will not receive any bug fixes or API updates from the Square version 2021-02-26 release. However, the SDK will receive support and security patches until it is retired (end of life) in the second quarter of 2021. For more information, including steps for migrating to the Square Node.js SDK, see the Connect SDK README.

Link to section

Documentation updates

• Catalog API:

  • Update Catalog Objects. Provides programming guidance to update catalog objects.

• Inventory API:

  • List or retrieve inventory. Migrate the retired v1 endpoint of ListInventory to the v2 endpoint of BatchRetrieveInventoryCounts. Compare and contrast the programming patterns between the v1 endpoint of ListInventory and its v2 counterparts of BatchRetrieveInventoryCounts or RetrieveInventoryCount.

  • Adjust or change inventory. Migrate the retired v1 endpoint of AdjustInventory to the v2 endpoint of BatchChangeInventory. Compare and contrast the programming patterns between the v1 endpoint of AdjustInventory and its v2 counterparts of BatchChangeInventory.

• Get Started topic. Revised the Get Started experience. In addition to clarifications, it now includes the use of the Square Sandbox and API Explorer. These are the tools and environments developers use to explore Square APIs.