Java client library for the Square Connect v2 API
Clone or download

README.md

Square Connect Java SDK Maven Central

If you have feedback about the new SDKs, or just want to talk to other Square Developers, request an invite to the new slack community for Square Developers

Requirements

Java 8

Building the API client library requires Maven to be installed.

Installation

Maven users

Add this dependency to your project's POM:

<dependency>
    <groupId>com.squareup</groupId>
    <artifactId>connect</artifactId>
    <version>2.20181212.0</version>
    <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile "com.squareup:connect:2.20181212.0"

Build and Install locally

To install the API client library to your local Maven repository, simply execute:

mvn install

Others

At first generate the JAR by executing:

mvn package

Then manually install the following JARs:

  • target/connect-2.20181212.0.jar
  • target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

import com.squareup.connect.ApiClient;
import com.squareup.connect.ApiException;
import com.squareup.connect.Configuration;
import com.squareup.connect.api.LocationsApi;
import com.squareup.connect.auth.OAuth;
import com.squareup.connect.models.Location;
import com.squareup.connect.models.Location.CapabilitiesEnum;

import java.io.File;
import java.util.*;

public class Example {

    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();

        // Configure OAuth2 access token for authorization: oauth2
        OAuth oauth2 = (OAuth) apiClient.getAuthentication("oauth2");
        oauth2.setAccessToken("YOUR_ACCESS_TOKEN");

        // List all locations
        LocationsApi locationsApi = new LocationsApi();
        locationsApi.setApiClient(apiClient);

        try {
            List<Location> locations = locationsApi.listLocations().getLocations();
            System.out.println(locations);
        } catch (ApiException e) {
            System.err.println("Exception when calling API");
            e.printStackTrace();
        }
    }
}

Documentation for API Endpoints

All URIs are relative to https://connect.squareup.com

Class Method HTTP request Description
ApplePayApi registerDomain POST /v2/apple-pay/domains RegisterDomain
CatalogApi batchDeleteCatalogObjects POST /v2/catalog/batch-delete BatchDeleteCatalogObjects
CatalogApi batchRetrieveCatalogObjects POST /v2/catalog/batch-retrieve BatchRetrieveCatalogObjects
CatalogApi batchUpsertCatalogObjects POST /v2/catalog/batch-upsert BatchUpsertCatalogObjects
CatalogApi catalogInfo GET /v2/catalog/info CatalogInfo
CatalogApi deleteCatalogObject DELETE /v2/catalog/object/{object_id} DeleteCatalogObject
CatalogApi listCatalog GET /v2/catalog/list ListCatalog
CatalogApi retrieveCatalogObject GET /v2/catalog/object/{object_id} RetrieveCatalogObject
CatalogApi searchCatalogObjects POST /v2/catalog/search SearchCatalogObjects
CatalogApi updateItemModifierLists POST /v2/catalog/update-item-modifier-lists UpdateItemModifierLists
CatalogApi updateItemTaxes POST /v2/catalog/update-item-taxes UpdateItemTaxes
CatalogApi upsertCatalogObject POST /v2/catalog/object UpsertCatalogObject
CheckoutApi createCheckout POST /v2/locations/{location_id}/checkouts CreateCheckout
CustomersApi createCustomer POST /v2/customers CreateCustomer
CustomersApi createCustomerCard POST /v2/customers/{customer_id}/cards CreateCustomerCard
CustomersApi deleteCustomer DELETE /v2/customers/{customer_id} DeleteCustomer
CustomersApi deleteCustomerCard DELETE /v2/customers/{customer_id}/cards/{card_id} DeleteCustomerCard
CustomersApi listCustomers GET /v2/customers ListCustomers
CustomersApi retrieveCustomer GET /v2/customers/{customer_id} RetrieveCustomer
CustomersApi searchCustomers POST /v2/customers/search SearchCustomers
CustomersApi updateCustomer PUT /v2/customers/{customer_id} UpdateCustomer
InventoryApi batchChangeInventory POST /v2/inventory/batch-change BatchChangeInventory
InventoryApi batchRetrieveInventoryChanges POST /v2/inventory/batch-retrieve-changes BatchRetrieveInventoryChanges
InventoryApi batchRetrieveInventoryCounts POST /v2/inventory/batch-retrieve-counts BatchRetrieveInventoryCounts
InventoryApi retrieveInventoryAdjustment GET /v2/inventory/adjustment/{adjustment_id} RetrieveInventoryAdjustment
InventoryApi retrieveInventoryChanges GET /v2/inventory/{catalog_object_id}/changes RetrieveInventoryChanges
InventoryApi retrieveInventoryCount GET /v2/inventory/{catalog_object_id} RetrieveInventoryCount
InventoryApi retrieveInventoryPhysicalCount GET /v2/inventory/physical-count/{physical_count_id} RetrieveInventoryPhysicalCount
LocationsApi listLocations GET /v2/locations ListLocations
MobileAuthorizationApi createMobileAuthorizationCode POST /mobile/authorization-code CreateMobileAuthorizationCode
OAuthApi obtainToken POST /oauth2/token ObtainToken
OAuthApi renewToken POST /oauth2/clients/{client_id}/access-token/renew RenewToken
OAuthApi revokeToken POST /oauth2/revoke RevokeToken
OrdersApi batchRetrieveOrders POST /v2/locations/{location_id}/orders/batch-retrieve BatchRetrieveOrders
OrdersApi createOrder POST /v2/locations/{location_id}/orders CreateOrder
ReportingApi listAdditionalRecipientReceivableRefunds GET /v2/locations/{location_id}/additional-recipient-receivable-refunds ListAdditionalRecipientReceivableRefunds
ReportingApi listAdditionalRecipientReceivables GET /v2/locations/{location_id}/additional-recipient-receivables ListAdditionalRecipientReceivables
TransactionsApi captureTransaction POST /v2/locations/{location_id}/transactions/{transaction_id}/capture CaptureTransaction
TransactionsApi charge POST /v2/locations/{location_id}/transactions Charge
TransactionsApi createRefund POST /v2/locations/{location_id}/transactions/{transaction_id}/refund CreateRefund
TransactionsApi listRefunds GET /v2/locations/{location_id}/refunds ListRefunds
TransactionsApi listTransactions GET /v2/locations/{location_id}/transactions ListTransactions
TransactionsApi retrieveTransaction GET /v2/locations/{location_id}/transactions/{transaction_id} RetrieveTransaction
TransactionsApi voidTransaction POST /v2/locations/{location_id}/transactions/{transaction_id}/void VoidTransaction
V1EmployeesApi createEmployee POST /v1/me/employees Creates an employee for a business.
V1EmployeesApi createEmployeeRole POST /v1/me/roles Creates an employee role you can then assign to employees.
V1EmployeesApi createTimecard POST /v1/me/timecards Creates a timecard for an employee. Each timecard corresponds to a single shift.
V1EmployeesApi deleteTimecard DELETE /v1/me/timecards/{timecard_id} Deletes a timecard. Deleted timecards are still accessible from Connect API endpoints, but the value of their deleted field is set to true. See Handling deleted timecards for more information.
V1EmployeesApi listCashDrawerShifts GET /v1/{location_id}/cash-drawer-shifts Provides the details for all of a location's cash drawer shifts during a date range. The date range you specify cannot exceed 90 days.
V1EmployeesApi listEmployeeRoles GET /v1/me/roles Provides summary information for all of a business's employee roles.
V1EmployeesApi listEmployees GET /v1/me/employees Provides summary information for all of a business's employees.
V1EmployeesApi listTimecardEvents GET /v1/me/timecards/{timecard_id}/events Provides summary information for all events associated with a particular timecard.
V1EmployeesApi listTimecards GET /v1/me/timecards Provides summary information for all of a business's employee timecards.
V1EmployeesApi retrieveCashDrawerShift GET /v1/{location_id}/cash-drawer-shifts/{shift_id} Provides the details for a single cash drawer shift, including all events that occurred during the shift.
V1EmployeesApi retrieveEmployee GET /v1/me/employees/{employee_id} Provides the details for a single employee.
V1EmployeesApi retrieveEmployeeRole GET /v1/me/roles/{role_id} Provides the details for a single employee role.
V1EmployeesApi retrieveTimecard GET /v1/me/timecards/{timecard_id} Provides the details for a single timecard.
V1EmployeesApi updateEmployee PUT /v1/me/employees/{employee_id} V1 UpdateEmployee
V1EmployeesApi updateEmployeeRole PUT /v1/me/roles/{role_id} Modifies the details of an employee role.
V1EmployeesApi updateTimecard PUT /v1/me/timecards/{timecard_id} Modifies a timecard's details. This creates an API_EDIT event for the timecard. You can view a timecard's event history with the List Timecard Events endpoint.
V1ItemsApi adjustInventory POST /v1/{location_id}/inventory/{variation_id} Adjusts an item variation's current available inventory.
V1ItemsApi applyFee PUT /v1/{location_id}/items/{item_id}/fees/{fee_id} Associates a fee with an item, meaning the fee is automatically applied to the item in Square Register.
V1ItemsApi applyModifierList PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} Associates a modifier list with an item, meaning modifier options from the list can be applied to the item.
V1ItemsApi createCategory POST /v1/{location_id}/categories Creates an item category.
V1ItemsApi createDiscount POST /v1/{location_id}/discounts Creates a discount.
V1ItemsApi createFee POST /v1/{location_id}/fees Creates a fee (tax).
V1ItemsApi createItem POST /v1/{location_id}/items Creates an item and at least one variation for it.
V1ItemsApi createModifierList POST /v1/{location_id}/modifier-lists Creates an item modifier list and at least one modifier option for it.
V1ItemsApi createModifierOption POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options Creates an item modifier option and adds it to a modifier list.
V1ItemsApi createPage POST /v1/{location_id}/pages Creates a Favorites page in Square Register.
V1ItemsApi createVariation POST /v1/{location_id}/items/{item_id}/variations Creates an item variation for an existing item.
V1ItemsApi deleteCategory DELETE /v1/{location_id}/categories/{category_id} Deletes an existing item category.
V1ItemsApi deleteDiscount DELETE /v1/{location_id}/discounts/{discount_id} Deletes an existing discount.
V1ItemsApi deleteFee DELETE /v1/{location_id}/fees/{fee_id} Deletes an existing fee (tax).
V1ItemsApi deleteItem DELETE /v1/{location_id}/items/{item_id} Deletes an existing item and all item variations associated with it.
V1ItemsApi deleteModifierList DELETE /v1/{location_id}/modifier-lists/{modifier_list_id} Deletes an existing item modifier list and all modifier options associated with it.
V1ItemsApi deleteModifierOption DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} Deletes an existing item modifier option from a modifier list.
V1ItemsApi deletePage DELETE /v1/{location_id}/pages/{page_id} Deletes an existing Favorites page and all of its cells.
V1ItemsApi deletePageCell DELETE /v1/{location_id}/pages/{page_id}/cells Deletes a cell from a Favorites page in Square Register.
V1ItemsApi deleteVariation DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id} Deletes an existing item variation from an item.
V1ItemsApi listCategories GET /v1/{location_id}/categories Lists all of a location's item categories.
V1ItemsApi listDiscounts GET /v1/{location_id}/discounts Lists all of a location's discounts.
V1ItemsApi listFees GET /v1/{location_id}/fees Lists all of a location's fees (taxes).
V1ItemsApi listInventory GET /v1/{location_id}/inventory Provides inventory information for all of a merchant's inventory-enabled item variations.
V1ItemsApi listItems GET /v1/{location_id}/items Provides summary information for all of a location's items.
V1ItemsApi listModifierLists GET /v1/{location_id}/modifier-lists Lists all of a location's modifier lists.
V1ItemsApi listPages GET /v1/{location_id}/pages Lists all of a location's Favorites pages in Square Register.
V1ItemsApi removeFee DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id} Removes a fee assocation from an item, meaning the fee is no longer automatically applied to the item in Square Register.
V1ItemsApi removeModifierList DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} Removes a modifier list association from an item, meaning modifier options from the list can no longer be applied to the item.
V1ItemsApi retrieveItem GET /v1/{location_id}/items/{item_id} Provides the details for a single item, including associated modifier lists and fees.
V1ItemsApi retrieveModifierList GET /v1/{location_id}/modifier-lists/{modifier_list_id} Provides the details for a single modifier list.
V1ItemsApi updateCategory PUT /v1/{location_id}/categories/{category_id} Modifies the details of an existing item category.
V1ItemsApi updateDiscount PUT /v1/{location_id}/discounts/{discount_id} Modifies the details of an existing discount.
V1ItemsApi updateFee PUT /v1/{location_id}/fees/{fee_id} Modifies the details of an existing fee (tax).
V1ItemsApi updateItem PUT /v1/{location_id}/items/{item_id} Modifies the core details of an existing item.
V1ItemsApi updateModifierList PUT /v1/{location_id}/modifier-lists/{modifier_list_id} Modifies the details of an existing item modifier list.
V1ItemsApi updateModifierOption PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} Modifies the details of an existing item modifier option.
V1ItemsApi updatePage PUT /v1/{location_id}/pages/{page_id} Modifies the details of a Favorites page in Square Register.
V1ItemsApi updatePageCell PUT /v1/{location_id}/pages/{page_id}/cells Modifies a cell of a Favorites page in Square Register.
V1ItemsApi updateVariation PUT /v1/{location_id}/items/{item_id}/variations/{variation_id} Modifies the details of an existing item variation.
V1LocationsApi listLocations GET /v1/me/locations Provides details for a business's locations, including their IDs.
V1LocationsApi retrieveBusiness GET /v1/me Get a business's information.
V1TransactionsApi createRefund POST /v1/{location_id}/refunds Issues a refund for a previously processed payment. You must issue a refund within 60 days of the associated payment.
V1TransactionsApi listBankAccounts GET /v1/{location_id}/bank-accounts Provides non-confidential details for all of a location's associated bank accounts. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.
V1TransactionsApi listOrders GET /v1/{location_id}/orders Provides summary information for a merchant's online store orders.
V1TransactionsApi listPayments GET /v1/{location_id}/payments Provides summary information for all payments taken by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. See Date ranges for details of inclusive and exclusive dates.
V1TransactionsApi listRefunds GET /v1/{location_id}/refunds Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length.
V1TransactionsApi listSettlements GET /v1/{location_id}/settlements Provides summary information for all deposits and withdrawals initiated by Square to a merchant's bank account during a date range. Date ranges cannot exceed one year in length.
V1TransactionsApi retrieveBankAccount GET /v1/{location_id}/bank-accounts/{bank_account_id} Provides non-confidential details for a merchant's associated bank account. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.
V1TransactionsApi retrieveOrder GET /v1/{location_id}/orders/{order_id} Provides comprehensive information for a single online store order, including the order's history.
V1TransactionsApi retrievePayment GET /v1/{location_id}/payments/{payment_id} Provides comprehensive information for a single payment.
V1TransactionsApi retrieveSettlement GET /v1/{location_id}/settlements/{settlement_id} Provides comprehensive information for a single settlement, including the entries that contribute to the settlement's total.
V1TransactionsApi updateOrder PUT /v1/{location_id}/orders/{order_id} Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

oauth2

  • Type: OAuth
  • Flow: accessCode
  • Authorization URL: https://connect.squareup.com/oauth2/authorize
  • Scopes:
    • MERCHANT_PROFILE_READ: GET endpoints related to a merchant's business and location entities. Almost all Connect API applications need this permission in order to obtain a merchant's location IDs
    • PAYMENTS_READ: GET endpoints related to transactions and refunds
    • PAYMENTS_WRITE: POST, PUT, and DELETE endpoints related to transactions and refunds. E-commerce applications must request this permission
    • CUSTOMERS_READ: GET endpoints related to customer management
    • CUSTOMERS_WRITE: POST, PUT, and DELETE endpoints related to customer management
    • SETTLEMENTS_READ: GET endpoints related to settlements (deposits)
    • BANK_ACCOUNTS_READ: GET endpoints related to a merchant's bank accounts
    • ITEMS_READ: GET endpoints related to a merchant's item library
    • ITEMS_WRITE: POST, PUT, and DELETE endpoints related to a merchant's item library
    • ORDERS_READ: GET endpoints related to a merchant's orders
    • ORDERS_WRITE: POST, PUT, and DELETE endpoints related to a merchant's orders
    • EMPLOYEES_READ: GET endpoints related to employee management
    • EMPLOYEES_WRITE: POST, PUT, and DELETE endpoints related to employee management
    • TIMECARDS_READ: GET endpoints related to employee timecards
    • TIMECARDS_WRITE: POST, PUT, and DELETE endpoints related to employee timecards
    • PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: Allow third party applications to deduct a portion of each transaction amount.
    • PAYMENTS_WRITE_IN_PERSON: POST, PUT, and DELETE endpoints. Grants write access to transaction and refunds information.
    • INVENTORY_READ: GET endpoints related to a merchant's inventory
    • INVENTORY_WRITE: POST, PUT, and DELETE endpoints related to a merchant's inventory

oauth2ClientSecret

  • Type: API key
  • API key parameter name: Authorization
  • Location: HTTP header

Pagination of V1 Endpoints

V1 Endpoints return pagination information via HTTP headers. In order to obtain response headers and extract the batch_token parameter you will need to follow the following steps:

  1. Use the full information endpoint methods of each API to get the response HTTP Headers. They are named as their simple counterpart with a WithHttpInfo suffix. Hence listEmployeeRoles would be called listEmployeeRolesWithHttpInfo. This method returns a CompleteResponse object with the response data deserialized along with a helper to retrieve the token if present.

  2. Use String batchToken = completeResponse.getBatchToken(); to extract the token and proceed to get the following page if a token is present.

Example

// Import classes:
//import .ApiClient;
//import .ApiException;
//import .Configuration;
//import .CompleteResponse;
//import .auth.*;
//import .api.V1EmployeesApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

V1EmployeesApi apiInstance = new V1EmployeesApi();
String order = "order_example"; // String | The order in which employees are listed in the response, based on their created_at field.Default value: ASC
Integer limit = 56; // Integer | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
String batchToken = null;
try {
    do {
        CompleteResponse<List<V1EmployeeRole>> completeResponse = apiInstance.listEmployeeRoles(order, limit, batchToken);
        System.out.println(completeResponse.getData());

        batchToken = completeResponse.getBatchToken();
    } while (batchToken != null);
} catch (ApiException e) {
    System.err.println("Exception when calling V1EmployeesApi#listEmployeeRoles");
    e.printStackTrace();
}

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Author

developers@squareup.com