Square Connect Python SDK Technical Reference

August 15, 2019 · View on GitHub

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

Requirements

Make sure you have Python 2 >=2.7.9 or Python 3 >= 3.4

Installation & Usage

Option 1: pip install

If the python package is hosted on Github, you can install directly from Github

pip install git+https://github.com/square/connect-python-sdk.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/square/connect-python-sdk.git)

Option 2: Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Getting Started

Please follow the installation procedure:

Then import the package:

import squareconnect

Retrieve your location IDs

from __future__ import print_function

import squareconnect
from squareconnect.rest import ApiException
from squareconnect.apis.locations_api import LocationsApi

# create an instance of the Location API class
api_instance = LocationsApi()
# setup authorization
api_instance.api_client.configuration.access_token = 'YOUR_ACCESS_TOKEN'

try:
    # ListLocations
    api_response = api_instance.list_locations()
    print (api_response.locations)
except ApiException as e:
    print ('Exception when calling LocationApi->list_locations: %s\n' % e)

NOTE: The Transactions API is deprecated as of 2019-08-15. To process payments with the new Payments API you must migrate to the new Square Python SDK.

from __future__ import print_function
import uuid

import squareconnect
from squareconnect.rest import ApiException
from squareconnect.apis.transactions_api import TransactionsApi

# create an instance of the Transaction API class
api_instance = TransactionApi()
# setup authorization
api_instance.api_client.configuration.access_token = 'YOUR_ACCESS_TOKEN'

location_id = 'YOUR_LOCATION_ID'
nonce = 'YOUR_NONCE'

try:
    # Charge
    idempotency_key = str(uuid.uuid1())
    amount = {'amount': 100, 'currency': 'USD'}
    body = {'idempotency_key': idempotency_key, 'card_nonce': nonce, 'amount_money': amount}
    api_response = api_instance.charge(location_id, body)
    print (api_response.transaction)
except ApiException as e:
    print ('Exception when calling TransactionApi->charge: %s\n' % e)

Documentation for API Endpoints

All URIs are relative to Square Connect Documentation

Class	Method	HTTP request
ApplePayApi	register_domain	POST /v2/apple-pay/domains
CatalogApi	batch_delete_catalog_objects	POST /v2/catalog/batch-delete
CatalogApi	batch_retrieve_catalog_objects	POST /v2/catalog/batch-retrieve
CatalogApi	batch_upsert_catalog_objects	POST /v2/catalog/batch-upsert
CatalogApi	catalog_info	GET /v2/catalog/info
CatalogApi	delete_catalog_object	DELETE /v2/catalog/object/{object_id}
CatalogApi	list_catalog	GET /v2/catalog/list
CatalogApi	retrieve_catalog_object	GET /v2/catalog/object/{object_id}
CatalogApi	search_catalog_objects	POST /v2/catalog/search
CatalogApi	update_item_modifier_lists	POST /v2/catalog/update-item-modifier-lists
CatalogApi	update_item_taxes	POST /v2/catalog/update-item-taxes
CatalogApi	upsert_catalog_object	POST /v2/catalog/object
CheckoutApi	create_checkout	POST /v2/locations/{location_id}/checkouts
CustomersApi	create_customer	POST /v2/customers
CustomersApi	create_customer_card	POST /v2/customers/{customer_id}/cards
CustomersApi	delete_customer	DELETE /v2/customers/{customer_id}
CustomersApi	delete_customer_card	DELETE /v2/customers/{customer_id}/cards/{card_id}
CustomersApi	list_customers	GET /v2/customers
CustomersApi	retrieve_customer	GET /v2/customers/{customer_id}
CustomersApi	search_customers	POST /v2/customers/search
CustomersApi	update_customer	PUT /v2/customers/{customer_id}
EmployeesApi	list_employees	GET /v2/employees
EmployeesApi	retrieve_employee	GET /v2/employees/{id}
InventoryApi	batch_change_inventory	POST /v2/inventory/batch-change
InventoryApi	batch_retrieve_inventory_changes	POST /v2/inventory/batch-retrieve-changes
InventoryApi	batch_retrieve_inventory_counts	POST /v2/inventory/batch-retrieve-counts
InventoryApi	retrieve_inventory_adjustment	GET /v2/inventory/adjustment/{adjustment_id}
InventoryApi	retrieve_inventory_changes	GET /v2/inventory/{catalog_object_id}/changes
InventoryApi	retrieve_inventory_count	GET /v2/inventory/{catalog_object_id}
InventoryApi	retrieve_inventory_physical_count	GET /v2/inventory/physical-count/{physical_count_id}
LaborApi	create_break_type	POST /v2/labor/break-types
LaborApi	create_shift	POST /v2/labor/shifts
LaborApi	delete_break_type	DELETE /v2/labor/break-types/{id}
LaborApi	delete_shift	DELETE /v2/labor/shifts/{id}
LaborApi	get_break_type	GET /v2/labor/break-types/{id}
LaborApi	get_employee_wage	GET /v2/labor/employee-wages/{id}
LaborApi	get_shift	GET /v2/labor/shifts/{id}
LaborApi	list_break_types	GET /v2/labor/break-types
LaborApi	list_employee_wages	GET /v2/labor/employee-wages
LaborApi	list_workweek_configs	GET /v2/labor/workweek-configs
LaborApi	search_shifts	POST /v2/labor/shifts/search
LaborApi	update_break_type	PUT /v2/labor/break-types/{id}
LaborApi	update_shift	PUT /v2/labor/shifts/{id}
LaborApi	update_workweek_config	PUT /v2/labor/workweek-configs/{id}
LocationsApi	list_locations	GET /v2/locations
MobileAuthorizationApi	create_mobile_authorization_code	POST /mobile/authorization-code
OAuthApi	obtain_token	POST /oauth2/token
OAuthApi	renew_token	POST /oauth2/clients/{client_id}/access-token/renew
OAuthApi	revoke_token	POST /oauth2/revoke
OrdersApi	batch_retrieve_orders	POST /v2/locations/{location_id}/orders/batch-retrieve
OrdersApi	create_order	POST /v2/locations/{location_id}/orders
OrdersApi	search_orders	POST /v2/orders/search
ReportingApi	list_additional_recipient_receivable_refunds	GET /v2/locations/{location_id}/additional-recipient-receivable-refunds
ReportingApi	list_additional_recipient_receivables	GET /v2/locations/{location_id}/additional-recipient-receivables
TransactionsApi	capture_transaction	POST /v2/locations/{location_id}/transactions/{transaction_id}/capture
TransactionsApi	charge	POST /v2/locations/{location_id}/transactions
TransactionsApi	create_refund	POST /v2/locations/{location_id}/transactions/{transaction_id}/refund
TransactionsApi	list_refunds	GET /v2/locations/{location_id}/refunds
TransactionsApi	list_transactions	GET /v2/locations/{location_id}/transactions
TransactionsApi	retrieve_transaction	GET /v2/locations/{location_id}/transactions/{transaction_id}
TransactionsApi	void_transaction	POST /v2/locations/{location_id}/transactions/{transaction_id}/void
V1EmployeesApi	create_employee	POST /v1/me/employees
V1EmployeesApi	create_employee_role	POST /v1/me/roles
V1EmployeesApi	create_timecard	POST /v1/me/timecards
V1EmployeesApi	delete_timecard	DELETE /v1/me/timecards/{timecard_id}
V1EmployeesApi	list_cash_drawer_shifts	GET /v1/{location_id}/cash-drawer-shifts
V1EmployeesApi	list_employee_roles	GET /v1/me/roles
V1EmployeesApi	list_employees	GET /v1/me/employees
V1EmployeesApi	list_timecard_events	GET /v1/me/timecards/{timecard_id}/events
V1EmployeesApi	list_timecards	GET /v1/me/timecards
V1EmployeesApi	retrieve_cash_drawer_shift	GET /v1/{location_id}/cash-drawer-shifts/{shift_id}
V1EmployeesApi	retrieve_employee	GET /v1/me/employees/{employee_id}
V1EmployeesApi	retrieve_employee_role	GET /v1/me/roles/{role_id}
V1EmployeesApi	retrieve_timecard	GET /v1/me/timecards/{timecard_id}
V1EmployeesApi	update_employee	PUT /v1/me/employees/{employee_id}
V1EmployeesApi	update_employee_role	PUT /v1/me/roles/{role_id}
V1EmployeesApi	update_timecard	PUT /v1/me/timecards/{timecard_id}
V1ItemsApi	adjust_inventory	POST /v1/{location_id}/inventory/{variation_id}
V1ItemsApi	apply_fee	PUT /v1/{location_id}/items/{item_id}/fees/{fee_id}
V1ItemsApi	apply_modifier_list	PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	create_category	POST /v1/{location_id}/categories
V1ItemsApi	create_discount	POST /v1/{location_id}/discounts
V1ItemsApi	create_fee	POST /v1/{location_id}/fees
V1ItemsApi	create_item	POST /v1/{location_id}/items
V1ItemsApi	create_modifier_list	POST /v1/{location_id}/modifier-lists
V1ItemsApi	create_modifier_option	POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options
V1ItemsApi	create_page	POST /v1/{location_id}/pages
V1ItemsApi	create_variation	POST /v1/{location_id}/items/{item_id}/variations
V1ItemsApi	delete_category	DELETE /v1/{location_id}/categories/{category_id}
V1ItemsApi	delete_discount	DELETE /v1/{location_id}/discounts/{discount_id}
V1ItemsApi	delete_fee	DELETE /v1/{location_id}/fees/{fee_id}
V1ItemsApi	delete_item	DELETE /v1/{location_id}/items/{item_id}
V1ItemsApi	delete_modifier_list	DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	delete_modifier_option	DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}
V1ItemsApi	delete_page	DELETE /v1/{location_id}/pages/{page_id}
V1ItemsApi	delete_page_cell	DELETE /v1/{location_id}/pages/{page_id}/cells
V1ItemsApi	delete_variation	DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id}
V1ItemsApi	list_categories	GET /v1/{location_id}/categories
V1ItemsApi	list_discounts	GET /v1/{location_id}/discounts
V1ItemsApi	list_fees	GET /v1/{location_id}/fees
V1ItemsApi	list_inventory	GET /v1/{location_id}/inventory
V1ItemsApi	list_items	GET /v1/{location_id}/items
V1ItemsApi	list_modifier_lists	GET /v1/{location_id}/modifier-lists
V1ItemsApi	list_pages	GET /v1/{location_id}/pages
V1ItemsApi	remove_fee	DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id}
V1ItemsApi	remove_modifier_list	DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	retrieve_item	GET /v1/{location_id}/items/{item_id}
V1ItemsApi	retrieve_modifier_list	GET /v1/{location_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	update_category	PUT /v1/{location_id}/categories/{category_id}
V1ItemsApi	update_discount	PUT /v1/{location_id}/discounts/{discount_id}
V1ItemsApi	update_fee	PUT /v1/{location_id}/fees/{fee_id}
V1ItemsApi	update_item	PUT /v1/{location_id}/items/{item_id}
V1ItemsApi	update_modifier_list	PUT /v1/{location_id}/modifier-lists/{modifier_list_id}
V1ItemsApi	update_modifier_option	PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}
V1ItemsApi	update_page	PUT /v1/{location_id}/pages/{page_id}
V1ItemsApi	update_page_cell	PUT /v1/{location_id}/pages/{page_id}/cells
V1ItemsApi	update_variation	PUT /v1/{location_id}/items/{item_id}/variations/{variation_id}
V1LocationsApi	list_locations	GET /v1/me/locations
V1LocationsApi	retrieve_business	GET /v1/me
V1TransactionsApi	create_refund	POST /v1/{location_id}/refunds
V1TransactionsApi	list_bank_accounts	GET /v1/{location_id}/bank-accounts
V1TransactionsApi	list_orders	GET /v1/{location_id}/orders
V1TransactionsApi	list_payments	GET /v1/{location_id}/payments
V1TransactionsApi	list_refunds	GET /v1/{location_id}/refunds
V1TransactionsApi	list_settlements	GET /v1/{location_id}/settlements
V1TransactionsApi	retrieve_bank_account	GET /v1/{location_id}/bank-accounts/{bank_account_id}
V1TransactionsApi	retrieve_order	GET /v1/{location_id}/orders/{order_id}
V1TransactionsApi	retrieve_payment	GET /v1/{location_id}/payments/{payment_id}
V1TransactionsApi	retrieve_settlement	GET /v1/{location_id}/settlements/{settlement_id}
V1TransactionsApi	update_order	PUT /v1/{location_id}/orders/{order_id}

Documentation For Authorization

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 product catalog information. For example, to get an item or a list of items.
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 Transactions 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 Transactions API.
PAYMENTS_WRITE_IN_PERSON: HTTP Method: POST, PUT, DELETE Grants write access to transaction 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 v1 ListTimecards endpoint.
TIMECARDS_WRITE: HTTP Method: POST, PUT, DELETE Grants write access to employee timecard information. For example, to create and modify timecards.
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

V1 Endpoints return pagination information via HTTP headers. In order to obtain response headers and extract the batch_token parameter you will need to get it from the response object after each call as follows:

Example

from __future__ import print_function

import squareconnect
from squareconnect.rest import ApiException
from squareconnect.apis.v1_employees_api import V1EmployeesApi

# create an instance of the V1 Employee API class
api_instance = V1EmployeesApi()
# setup authorization
api_instance.api_client.configuration.access_token = 'YOUR_ACCESS_TOKEN'
has_next_page = True
token = None

try:
    while has_next_page:
        # ListEmployeeRoles
        api_response = api_instance.list_employee_roles(batch_token=token)
        print (api_response.locations)

        token = api_instance.api_client.last_response.getbatch_token()
        has_next_page = token != None
except ApiException as e:
    print ('Exception when calling V1EmployeesApi->list_employee_roles: %s\n' % e)

Contributing

Send bug reports, feature requests, and code contributions to the API specifications repository, as this repository contains only the generated SDK code.

License

Copyright 2017 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.