/connect-python-sdk

Python client library for the Square Connect APIs

Primary LanguagePythonApache License 2.0Apache-2.0

Square Connect Python SDK Build StatusPyPI version

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

This repository contains the released Python client SDK. Check out our API specification repository for the specification and template files we used to generate this.

Requirements.

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

Installation & Usage

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)

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

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

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

from __future__ import print_function
import uuid

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

# setup authorization
squareconnect.configuration.access_token = 'YOUR_ACCESS_TOKEN'
# create an instance of the Transaction API class
api_instance = TransactionApi()
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 update_customer PUT /v2/customers/{customer_id}
LocationsApi list_locations GET /v2/locations
OrdersApi batch_retrieve_orders POST /v2/locations/{location_id}/orders/batch-retrieve
OrdersApi create_order POST /v2/locations/{location_id}/orders
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:
  • 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

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

# setup authorization
squareconnect.configuration.access_token = 'YOUR_ACCESS_TOKEN'
# create an instance of the V1 Employee API class
api_instance = V1EmployeesApi()
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.