Square Connect Java SDK Technical Reference

December 17, 2019 · View on GitHub

Square Connect Java SDK Technical Reference

The Square Connect Java SDK is retired (EOL) as of 2019-12-17 and will no longer receive bug fixes or product updates.

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

Option 1: Maven users

Add this dependency to your project's POM:

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

Option 2: Gradle users

Add this dependency to your project's build file:

compile "com.squareup:connect:2.20191120.0"

Option 3: Build and Install locally

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

mvn install -DskipTests

To run tests, you would need to create below accounts.json under travis-ci folder.

{
  "US-Prod": {
    "email": "your_email",
    "access_token": "your_access_token",
    "location_id": "your_location_id",
    "application_id": "your_application_id"
  },
  "US-Prod-Sandbox": {
    "email": "your_email",
    "access_token": "your_sandbox_access_token",
    "location_id": "your_sandbox_location_id",
    "application_id": "your_sandbox_application_id"
  }
}

mvn install

Option 4: Others

At first generate the JAR by executing:

mvn package

Then manually install the following JARs:

target/connect-2.20191120.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 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();
        }
    }
}

How to configure sandbox environment


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 java.io.File;
import java.util.*;

public class Example {

    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        // Set sandbox url
        apiClient.setBasePath('https://connect.squareupsandbox.com');

        // Configure OAuth2 access token for authorization: oauth2
        OAuth oauth2 = (OAuth) apiClient.getAuthentication("oauth2");
        // Set your sandbox token
        oauth2.setAccessToken("YOUR_SANDBOX_ACCESS_TOKEN");

        LocationsApi locationsApi = new LocationsApi();
    }
}

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
EmployeesApi	listEmployees	GET /v2/employees	ListEmployees
EmployeesApi	retrieveEmployee	GET /v2/employees/{id}	RetrieveEmployee
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
LaborApi	createBreakType	POST /v2/labor/break-types	CreateBreakType
LaborApi	createShift	POST /v2/labor/shifts	CreateShift
LaborApi	deleteBreakType	DELETE /v2/labor/break-types/{id}	DeleteBreakType
LaborApi	deleteShift	DELETE /v2/labor/shifts/{id}	DeleteShift
LaborApi	getBreakType	GET /v2/labor/break-types/{id}	GetBreakType
LaborApi	getEmployeeWage	GET /v2/labor/employee-wages/{id}	GetEmployeeWage
LaborApi	getShift	GET /v2/labor/shifts/{id}	GetShift
LaborApi	listBreakTypes	GET /v2/labor/break-types	ListBreakTypes
LaborApi	listEmployeeWages	GET /v2/labor/employee-wages	ListEmployeeWages
LaborApi	listWorkweekConfigs	GET /v2/labor/workweek-configs	ListWorkweekConfigs
LaborApi	searchShifts	POST /v2/labor/shifts/search	SearchShifts
LaborApi	updateBreakType	PUT /v2/labor/break-types/{id}	UpdateBreakType
LaborApi	updateShift	PUT /v2/labor/shifts/{id}	UpdateShift
LaborApi	updateWorkweekConfig	PUT /v2/labor/workweek-configs/{id}	UpdateWorkweekConfig
LocationsApi	createLocation	POST /v2/locations	CreateLocation
LocationsApi	listLocations	GET /v2/locations	ListLocations
LocationsApi	retrieveLocation	GET /v2/locations/{location_id}	RetrieveLocation
LocationsApi	updateLocation	PUT /v2/locations/{location_id}	UpdateLocation
MerchantsApi	listMerchants	GET /v2/merchants	ListMerchants
MerchantsApi	retrieveMerchant	GET /v2/merchants/{merchant_id}	RetrieveMerchant
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
OrdersApi	payOrder	POST /v2/orders/{order_id}/pay	PayOrder
OrdersApi	searchOrders	POST /v2/orders/search	SearchOrders
OrdersApi	updateOrder	PUT /v2/locations/{location_id}/orders/{order_id}	UpdateOrder
PaymentsApi	cancelPayment	POST /v2/payments/{payment_id}/cancel	CancelPayment
PaymentsApi	cancelPaymentByIdempotencyKey	POST /v2/payments/cancel	CancelPaymentByIdempotencyKey
PaymentsApi	completePayment	POST /v2/payments/{payment_id}/complete	CompletePayment
PaymentsApi	createPayment	POST /v2/payments	CreatePayment
PaymentsApi	getPayment	GET /v2/payments/{payment_id}	GetPayment
PaymentsApi	listPayments	GET /v2/payments	ListPayments
RefundsApi	getPaymentRefund	GET /v2/refunds/{refund_id}	GetPaymentRefund
RefundsApi	listPaymentRefunds	GET /v2/refunds	ListPaymentRefunds
RefundsApi	refundPayment	POST /v2/refunds	RefundPayment
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	CreateEmployee
V1EmployeesApi	createEmployeeRole	POST /v1/me/roles	CreateEmployeeRole
V1EmployeesApi	createTimecard	POST /v1/me/timecards	CreateTimecard
V1EmployeesApi	deleteTimecard	DELETE /v1/me/timecards/{timecard_id}	DeleteTimecard
V1EmployeesApi	listCashDrawerShifts	GET /v1/{location_id}/cash-drawer-shifts	ListCashDrawerShifts
V1EmployeesApi	listEmployeeRoles	GET /v1/me/roles	ListEmployeeRoles
V1EmployeesApi	listEmployees	GET /v1/me/employees	ListEmployees
V1EmployeesApi	listTimecardEvents	GET /v1/me/timecards/{timecard_id}/events	ListTimecardEvents
V1EmployeesApi	listTimecards	GET /v1/me/timecards	ListTimecards
V1EmployeesApi	retrieveCashDrawerShift	GET /v1/{location_id}/cash-drawer-shifts/{shift_id}	RetrieveCashDrawerShift
V1EmployeesApi	retrieveEmployee	GET /v1/me/employees/{employee_id}	RetrieveEmployee
V1EmployeesApi	retrieveEmployeeRole	GET /v1/me/roles/{role_id}	RetrieveEmployeeRole
V1EmployeesApi	retrieveTimecard	GET /v1/me/timecards/{timecard_id}	RetrieveTimecard
V1EmployeesApi	updateEmployee	PUT /v1/me/employees/{employee_id}	UpdateEmployee
V1EmployeesApi	updateEmployeeRole	PUT /v1/me/roles/{role_id}	UpdateEmployeeRole
V1EmployeesApi	updateTimecard	PUT /v1/me/timecards/{timecard_id}	UpdateTimecard
V1ItemsApi	adjustInventory	POST /v1/{location_id}/inventory/{variation_id}	AdjustInventory
V1ItemsApi	applyFee	PUT /v1/{location_id}/items/{item_id}/fees/{fee_id}	ApplyFee
V1ItemsApi	applyModifierList	PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}	ApplyModifierList
V1ItemsApi	createCategory	POST /v1/{location_id}/categories	CreateCategory
V1ItemsApi	createDiscount	POST /v1/{location_id}/discounts	CreateDiscount
V1ItemsApi	createFee	POST /v1/{location_id}/fees	CreateFee
V1ItemsApi	createItem	POST /v1/{location_id}/items	CreateItem
V1ItemsApi	createModifierList	POST /v1/{location_id}/modifier-lists	CreateModifierList
V1ItemsApi	createModifierOption	POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options	CreateModifierOption
V1ItemsApi	createPage	POST /v1/{location_id}/pages	CreatePage
V1ItemsApi	createVariation	POST /v1/{location_id}/items/{item_id}/variations	CreateVariation
V1ItemsApi	deleteCategory	DELETE /v1/{location_id}/categories/{category_id}	DeleteCategory
V1ItemsApi	deleteDiscount	DELETE /v1/{location_id}/discounts/{discount_id}	DeleteDiscount
V1ItemsApi	deleteFee	DELETE /v1/{location_id}/fees/{fee_id}	DeleteFee
V1ItemsApi	deleteItem	DELETE /v1/{location_id}/items/{item_id}	DeleteItem
V1ItemsApi	deleteModifierList	DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}	DeleteModifierList
V1ItemsApi	deleteModifierOption	DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}	DeleteModifierOption
V1ItemsApi	deletePage	DELETE /v1/{location_id}/pages/{page_id}	DeletePage
V1ItemsApi	deletePageCell	DELETE /v1/{location_id}/pages/{page_id}/cells	DeletePageCell
V1ItemsApi	deleteVariation	DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id}	DeleteVariation
V1ItemsApi	listCategories	GET /v1/{location_id}/categories	ListCategories
V1ItemsApi	listDiscounts	GET /v1/{location_id}/discounts	ListDiscounts
V1ItemsApi	listFees	GET /v1/{location_id}/fees	ListFees
V1ItemsApi	listInventory	GET /v1/{location_id}/inventory	ListInventory
V1ItemsApi	listItems	GET /v1/{location_id}/items	ListItems
V1ItemsApi	listModifierLists	GET /v1/{location_id}/modifier-lists	ListModifierLists
V1ItemsApi	listPages	GET /v1/{location_id}/pages	ListPages
V1ItemsApi	removeFee	DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id}	RemoveFee
V1ItemsApi	removeModifierList	DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}	RemoveModifierList
V1ItemsApi	retrieveItem	GET /v1/{location_id}/items/{item_id}	RetrieveItem
V1ItemsApi	retrieveModifierList	GET /v1/{location_id}/modifier-lists/{modifier_list_id}	RetrieveModifierList
V1ItemsApi	updateCategory	PUT /v1/{location_id}/categories/{category_id}	UpdateCategory
V1ItemsApi	updateDiscount	PUT /v1/{location_id}/discounts/{discount_id}	UpdateDiscount
V1ItemsApi	updateFee	PUT /v1/{location_id}/fees/{fee_id}	UpdateFee
V1ItemsApi	updateItem	PUT /v1/{location_id}/items/{item_id}	UpdateItem
V1ItemsApi	updateModifierList	PUT /v1/{location_id}/modifier-lists/{modifier_list_id}	UpdateModifierList
V1ItemsApi	updateModifierOption	PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}	UpdateModifierOption
V1ItemsApi	updatePage	PUT /v1/{location_id}/pages/{page_id}	UpdatePage
V1ItemsApi	updatePageCell	PUT /v1/{location_id}/pages/{page_id}/cells	UpdatePageCell
V1ItemsApi	updateVariation	PUT /v1/{location_id}/items/{item_id}/variations/{variation_id}	UpdateVariation
V1LocationsApi	listLocations	GET /v1/me/locations	ListLocations
V1LocationsApi	retrieveBusiness	GET /v1/me	RetrieveBusiness
V1TransactionsApi	createRefund	POST /v1/{location_id}/refunds	CreateRefund
V1TransactionsApi	listBankAccounts	GET /v1/{location_id}/bank-accounts	ListBankAccounts
V1TransactionsApi	listOrders	GET /v1/{location_id}/orders	ListOrders
V1TransactionsApi	listPayments	GET /v1/{location_id}/payments	ListPayments
V1TransactionsApi	listRefunds	GET /v1/{location_id}/refunds	ListRefunds
V1TransactionsApi	listSettlements	GET /v1/{location_id}/settlements	ListSettlements
V1TransactionsApi	retrieveBankAccount	GET /v1/{location_id}/bank-accounts/{bank_account_id}	RetrieveBankAccount
V1TransactionsApi	retrieveOrder	GET /v1/{location_id}/orders/{order_id}	RetrieveOrder
V1TransactionsApi	retrievePayment	GET /v1/{location_id}/payments/{payment_id}	RetrievePayment
V1TransactionsApi	retrieveSettlement	GET /v1/{location_id}/settlements/{settlement_id}	RetrieveSettlement
V1TransactionsApi	updateOrder	PUT /v1/{location_id}/orders/{order_id}	UpdateOrder

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:
- BANK_ACCOUNTS_READ: HTTP Method: `GET` Grants read access to bank account information associated with the targeted Square account. For example, to call the Connect v1 ListBankAccounts endpoint.
- CUSTOMERS_READ: HTTP Method: `GET` Grants read access to customer information. For example, to call the ListCustomers endpoint.
- CUSTOMERS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to customer information. For example, to create and update customer profiles.
- EMPLOYEES_READ: HTTP Method: `GET` Grants read access to employee profile information. For example, to call the Connect v1 Employees API.
- EMPLOYEES_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to employee profile information. For example, to create and modify employee profiles.
- INVENTORY_READ: HTTP Method: `GET` Grants read access to inventory information. For example, to call the RetrieveInventoryCount endpoint.
- INVENTORY_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to inventory information. For example, to call the BatchChangeInventory endpoint.
- ITEMS_READ: HTTP Method: `GET` Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.
- ITEMS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to product catalog information. For example, to modify or add to a product catalog.
- MERCHANT_PROFILE_READ: HTTP Method: `GET` Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.
- ORDERS_READ: HTTP Method: `GET` Grants read access to order information. For example, to call the BatchRetrieveOrders endpoint.
- ORDERS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to order information. For example, to call the CreateCheckout endpoint.
- PAYMENTS_READ: HTTP Method: `GET` Grants read access to transaction and refund information. For example, to call the RetrieveTransaction endpoint.
- PAYMENTS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to transaction and refunds information. For example, to process payments with the Payments or Checkout API.
- PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: HTTP Method: `POST`, `PUT`, `DELETE` Allow third party applications to deduct a portion of each transaction amount. Required to use multiparty transaction functionality with the Payments API.
- PAYMENTS_WRITE_IN_PERSON: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to payments and refunds information. For example, to process in-person payments.
- SETTLEMENTS_READ: HTTP Method: `GET` Grants read access to settlement (deposit) information. For example, to call the Connect v1 ListSettlements endpoint.
- TIMECARDS_READ: HTTP Method: `GET` Grants read access to employee timecard information. For example, to call the Connect v2 SearchShifts endpoint.
- TIMECARDS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to employee shift information. For example, to create and modify employee shifts.
- TIMECARDS_SETTINGS_READ: HTTP Method: `GET` Grants read access to employee timecard settings information. For example, to call the GetBreakType endpoint.
- TIMECARDS_SETTINGS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to employee timecard settings information. For example, to call the UpdateBreakType endpoint.

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:

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.
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