Skip to content
This repository has been archived by the owner on Apr 23, 2021. It is now read-only.

Latest commit

 

History

History
791 lines (731 loc) · 46.5 KB

README.md

File metadata and controls

791 lines (731 loc) · 46.5 KB

Square Connect Python SDK Technical Reference

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)

Charge the card nonce

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 Models

Documentation For Enums

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

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