square / square-python-sdk

Python client library for the Square API

Square Python SDK

Use this library to integrate Square payments into your app and grow your business with Square APIs including Catalog, Customers, Employees, Inventory, Labor, Locations, and Orders.

• Requirements
• Installation
• Quickstart
• Usage
• Tests
• SDK Reference
• Deprecated APIs

Requirements

Use of the Python SDK requires:

• Python 3 version 3.7 or higher

Installation

For more information, see Set Up Your Square SDK for a Python Project.

Quickstart

For more information, see Square Python SDK Quickstart.

Usage

For more information, see Using the Square Python SDK.

Tests

First, clone the repo locally and cd into the directory.

git clone https://github.com/square/square-python-sdk.git
cd square-python-sdk

Next, install dependencies.

python3 -m pip install .

Before running the tests, find a sandbox token in your Developer Dashboard and set a SQUARE_SANDBOX_TOKEN environment variable.

export SQUARE_SANDBOX_TOKEN="YOUR SANDBOX TOKEN HERE"

Ensure you have pytest installed:

python3 -m pip install pytest

And lastly, run the tests.

pytest

SDK Reference

Payments

• Payments
• Refunds
• Disputes
• Checkout
• Apple Pay
• Cards
• Payouts

Terminal

• Terminal

Orders

• Orders
• Order Custom Attributes

Subscriptions

• Subscriptions

Invoices

• Invoices

Items

• Catalog
• Inventory

Customers

• Customers
• Customer Groups
• Customer Segments

Loyalty

• Loyalty

Gift Cards

• Gift Cards
• Gift Card Activities

Bookings

• Bookings
• Booking Custom Attributes

Business

• Merchants
• Merchant Custom Attributes
• Locations
• Location Custom Attributes
• Devices
• Cash Drawers

Team

• Team
• Labor

Financials

• Bank Accounts

Online

• Sites
• Snippets

Authorization

• Mobile Authorization
• OAuth

Webhook Subscriptions

• Webhook Subscriptions

Deprecated APIs

The following Square APIs are deprecated:

• Employees - replaced by the Team API. For more information, see Migrate from the Employees API.

• Transactions - replaced by the Orders and Payments APIs. For more information, see Migrate from the Transactions API.

square-python-sdk's Issues

Async

Hi there!

I was wondering whether or not this library will support async anytime soon

Cards Disable Card Endpoint

The following error occurs when trying to disable a card

<ApiResponse [{"errors":[{"category":"INVALID_REQUEST_ERROR","code":"EXPECTED_JSON_BODY","detail":"Expected body to be a JSON object."}]}]>

[FEATURE REQUEST] Add min_modifiers and max_modifiers to Modifier List Objects in List Catalog Endpoint

Is your feature request related to a problem? Please describe.

I'm currently facing a challenge with the Square API's List Catalog endpoint. The response object for MODIFIER_LIST does not contain min_modifiers and max_modifiers attributes. To access that information, I need to call the List Catalog endpoint for ITEM and then merge the two responses, which is inefficient.

Describe the solution you'd like

It would be great if the List Catalog endpoint could include min_modifiers and max_modifiers attributes in the response object for MODIFIER_LIST. This would allow developers to get all necessary information about modifier lists in a single API call, streamlining the process and saving time.

Describe alternatives you've considered

The current workaround is to call the List Catalog endpoint for item and merge the two responses to access min_modifiers and max_modifiers information. However, this is inefficient and time-consuming.

Additional context

Including min_modifiers and max_modifiers attributes in the MODIFIER_LIST response object would simplify the integration process for developers and improve the overall usability of the Square API.

Example MODIFIER_LIST Response:

{'objects': [{'type': 'MODIFIER_LIST',
   'id': 'T6VMUL4IEOAWSF52COGXBXEN',
   'updated_at': '2023-03-19T01:57:37.437Z',
   'created_at': '2023-03-19T01:57:37.437Z',
   'version': 1679191057437,
   'is_deleted': False,
   'present_at_all_locations': False,
   'present_at_location_ids': ['LWRC1JNC0MPE5'],
   'modifier_list_data': {'name': 'Cheese Options',
    'selection_type': 'MULTIPLE',
    'modifiers': [{'type': 'MODIFIER',
      'id': 'XATFMQLJ24IPXPYVVFGBU2LP',
      'updated_at': '2023-03-19T01:57:37.437Z',
      'created_at': '2023-03-19T01:57:37.437Z',
      'version': 1679191057437,
      'is_deleted': False,
      'present_at_all_locations': False,
      'present_at_location_ids': ['LWRC1JNC0MPE5'],
      'modifier_data': {'name': 'Extra Mozzarella Cheese',
       'price_money': {'amount': 173, 'currency': 'USD'},
       'on_by_default': False,
       'ordinal': 0,
       'modifier_list_id': 'T6VMUL4IEOAWSF52COGXBXEN'}},
     {'type': 'MODIFIER',
      'id': 'YFH6MH4K65YZBCMXIY6D63A7',
      'updated_at': '2023-03-19T01:57:37.437Z',
      'created_at': '2023-03-19T01:57:37.437Z',
      'version': 1679191057437,
      'is_deleted': False,
      'present_at_all_locations': False,
      'present_at_location_ids': ['LWRC1JNC0MPE5'],
      'modifier_data': {'name': 'Vegan Mozzarella Cheese',
       'price_money': {'amount': 230, 'currency': 'USD'},
       'on_by_default': False,
       'ordinal': 1,
       'modifier_list_id': 'T6VMUL4IEOAWSF52COGXBXEN'}},
     {'type': 'MODIFIER',
      'id': 'ER5CEXLDA3MWIUBPV7YCVYLA',
      'updated_at': '2023-03-19T01:57:37.437Z',
      'created_at': '2023-03-19T01:57:37.437Z',
      'version': 1679191057437,
      'is_deleted': False,
      'present_at_all_locations': False,
      'present_at_location_ids': ['LWRC1JNC0MPE5'],
      'modifier_data': {'name': 'No Cheese',
       'price_money': {'amount': 0, 'currency': 'USD'},
       'on_by_default': False,
       'ordinal': 2,
       'modifier_list_id': 'T6VMUL4IEOAWSF52COGXBXEN'}}],
    'is_conversational': False}}]}

Example ITEM Response:

{'objects': [{'type': 'ITEM',
   'id': 'BT537LAIQ76ZSIXH37N7DH7J',
   'updated_at': '2023-03-19T02:00:04.154Z',
   'created_at': '2023-03-19T01:57:37.437Z',
   'version': 1679191204154,
   'is_deleted': False,
   'present_at_all_locations': False,
   'present_at_location_ids': ['LWRC1JNC0MPE5'],
   'item_data': {'name': 'Pepperoni Pizza (16")',
    'is_taxable': True,
    'category_id': 'AEVIYSRVJ4Z32BTWDRPBS7DP',
    'modifier_list_info': [{'modifier_list_id': 'T6VMUL4IEOAWSF52COGXBXEN',
      'min_selected_modifiers': 0,
      'max_selected_modifiers': 1,
      'enabled': True},
     {'modifier_list_id': 'YCKYCB3E2PBDMKALMTJSDOM3',
      'min_selected_modifiers': 0,
      'max_selected_modifiers': 7,
      'enabled': True},
     {'modifier_list_id': 'QN5LOUISDYWSFXJ4ICM6RLMV',
      'min_selected_modifiers': 0,
      'max_selected_modifiers': 6,
      'enabled': True}],
    'variations': [{'type': 'ITEM_VARIATION',
      'id': '3X323HKH5EZCJ2RBW7Q7UQ4B',
      'updated_at': '2023-03-19T01:57:37.437Z',
      'created_at': '2023-03-19T01:57:37.437Z',
      'version': 1679191057437,
      'is_deleted': False,
      'present_at_all_locations': False,
      'present_at_location_ids': ['LWRC1JNC0MPE5'],
      'item_variation_data': {'item_id': 'BT537LAIQ76ZSIXH37N7DH7J',
       'name': 'Regular',
       'ordinal': 0,
       'pricing_type': 'FIXED_PRICING',
       'price_money': {'amount': 1825, 'currency': 'USD'},
       'sellable': True,
       'stockable': True}}],
    'product_type': 'REGULAR',
    'ecom_available': True,
    'ecom_visibility': 'VISIBLE',
    'pickup_fulfillment_preferences_id': 'fprefs_127m0930y1bzx0al73xpchtpw',
    'dine_in_fulfillment_preferences_id': 'fprefs_127m0930xlkojwkn3d0g7fohg'}}]}

Customer Doc

Hello,

Could I find out if the customer reference doc is still available or permanently out ?

Thank you,

square.exceptions.api_exception.APIException HTTP response not OK. for test case responses

Describe the bug
Regression in latest SDK version with payments API raises an exception for test values which indicate a payment failure.

Expected behavior
Following the create payment example from the documentation should not result in an exception when payment fails, instead following the is_error() pattern and only raising an exception when there is an error in making the request.

To Reproduce
Steps to reproduce the bug:

1. Make a request using any of the error mapped source_id test values
2. Observe raised exception square.exceptions.api_exception.APIException: HTTP response not OK.

An example payload body and code which produces this error, but works on the previous SDK version:

{'amount_money': {'amount': 1000, 'currency': 'USD'},
 'app_fee_money': {'amount': 10, 'currency': 'USD'},
 'autocomplete': True,
 'idempotency_key': '61d82da9-43e8-43cf-9977-7f7cbe36be73',
 'location_id': 'MESD3N22DWR0F',
 'note': 'Brief description',
 'reference_id': '123456',
 'source_id': 'cnon:card-nonce-rejected-cvv'}

Full traceback:

Traceback (most recent call last):
  File "test.py", line 37, in <module>
    result = payments_api.create_payment(body)
  File "/home/rechner/workspace/scratch/venv/lib/python3.8/site-packages/square/api/payments_api.py", line 155, in create_payment
    return super().new_api_call_builder.request(
  File "/home/rechner/workspace/scratch/venv/lib/python3.8/site-packages/apimatic_core/api_call.py", line 72, in execute
    return self._response_handler.endpoint_logger(self._endpoint_logger) \
  File "/home/rechner/workspace/scratch/venv/lib/python3.8/site-packages/apimatic_core/response_handler.py", line 76, in handle
    self.validate(response, global_errors)
  File "/home/rechner/workspace/scratch/venv/lib/python3.8/site-packages/apimatic_core/response_handler.py", line 103, in validate
    raise error_case.get_exception_type()(error_case.get_description(), response)
square.exceptions.api_exception.APIException: HTTP response not OK.

Screenshots

Example code

import os
import uuid
import pprint
from square.client import Client

client = Client(
    access_token=os.environ['SQUARE_ACCESS_TOKEN'],
    environment='sandbox'
)

result = client.locations.list_locations()
if result.is_success():
    location_id = result.body['locations'][0]['id']
else:
    print(result.errors)
    exit()

payments_api = client.payments

body = {}
body['source_id'] = 'cnon:card-nonce-rejected-cvv'
body['idempotency_key'] = str(uuid.uuid4())
body['amount_money'] = {}
body['amount_money']['amount'] = 1000
body['amount_money']['currency'] = 'USD'
body['app_fee_money'] = {}
body['app_fee_money']['amount'] = 10
body['app_fee_money']['currency'] = 'USD'
body['autocomplete'] = True
body['location_id'] = location_id
body['reference_id'] = '123456'
body['note'] = 'Brief description'

print("Request body:")
pprint.pprint(body)

result = payments_api.create_payment(body)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

Square SDK version
23.0.0.20221019, tested also with 24.0.0.20221116 and found to have the same issue.

Additional context
I use these premade nonce values to test error conditions in my code. Tests pass on version 22 of the SDK.

Links to models in are broken in the docs

When using the generated docs here on Github, the links to all the models are broken.

For example, the link to "Create Order Request" on Create Orders points to https://github.com/square/square-python-sdk/blob/master/doc/$m/CreateOrderRequest, when it should point to https://github.com/square/square-python-sdk/blob/master/doc/models/create-order-request.md.

This affects my ability to successfully use the documentation as I build software that consumes the API. It's not necessarily unusable (I can manually search through the models folder, but it would certainly be nice if these links were fixed.

Thank you in advance for any help on this issue!

Undelared dependency urllib3

I am doing some spiking for a project and was attempting to run the example code in the README.

Traceback (most recent call last):
  File "sync.py", line 1, in <module>
    from square.client import Client
  File "/usr/local/share/virtualenvs/tap-square/lib/python3.5/site-packages/square/client.py", line 4, in <module>
    from square.configuration import Configuration
  File "/usr/local/share/virtualenvs/tap-square/lib/python3.5/site-packages/square/configuration.py", line 4, in <module>
    from square.http.requests_client import RequestsClient
  File "/usr/local/share/virtualenvs/tap-square/lib/python3.5/site-packages/square/http/requests_client.py", line 6, in <module>
    from urllib3.util.retry import Retry
ImportError: No module named 'urllib3'

square seems to be happy if urllib3 1.25.9 is installed. Is this a good version to use or should something else be pinned in square-python-sdk/setup.py?

ApiResponse into Dataframe

Once instantiated one cannot appropriately update a client.config.access_token.... however as part of standard access_key rotation/refresh it needs to be changed.

See - https://github.com/square/square-python-sdk/blob/master/square/configuration.py access_token is effectively a read-only property (of course you can update config._access_token but should not); this means that you have to instantiate a new client (or new config and ungracefully overwrite config in client) each time you refresh your access token. There should be a function to allow updates of access_token for a given client instantiation (or expose it as a normal property) so that after a refresh token, you can update the token.

Timeout Error

Describe the bug
A clear and concise description of what the bug is.

I've been experiencing consistent timeouts with the Square API. I have verified the credentials I have been using is correct - including access token, application ID, etc. I also recreated the requests using cURL and the requests library and those requests are timing out as well. (I made sure to ping some other public endpoints as well to ensure it wasn't a network issue on my end)

Here are the logs I get:

File "/backend/./www/www/api/auth_controller.py", line 39, in end_square_oauth_flow
sweetspot-backend-1  |     oauth_client = auth.get_square_client(oauth_end_flow.access_token)
sweetspot-backend-1  |   File "/backend/./common/common/square/auth.py", line 48, in get_square_client
sweetspot-backend-1  |     return Client(access_token, settings.SQUARE_ENVIRONMENT)
sweetspot-backend-1  |   File "/usr/local/lib/python3.8/site-packages/square/client.py", line 228, in __init__
sweetspot-backend-1  |     self.config = Configuration(
sweetspot-backend-1  |   File "/usr/local/lib/python3.8/site-packages/square/configuration.py", line 68, in __init__
sweetspot-backend-1  |     super().set_http_client(self.create_http_client())
sweetspot-backend-1  |   File "/usr/local/lib/python3.8/site-packages/square/configuration.py", line 103, in create_http_client
sweetspot-backend-1  |     return RequestsClient(
sweetspot-backend-1  |   File "/usr/local/lib/python3.8/site-packages/apimatic_requests_client_adapter/requests_client.py", line 45, in __init__
sweetspot-backend-1  |     http_client_instance.timeout = timeout

Expected behavior
I expect the API call to immediately return me a response.

To Reproduce
Steps to reproduce the bug:

1. Initiate API Client
2. Pass in Access Token
3. Make request

Screenshots
If applicable, add screenshots to help explain the bug.

Square SDK version
squareup==25.0.0.20221214

Additional context
Run inside local docker container (Fast API)

Loading limit

Hello, while loading the payments it is only loading 100 data entries. When I transform into a DF I only get 100 rows. I know I have more data entries than 100. Is there some limitation while loading with SquareUp's API? If so, how can I change this limit.

Thanks a lot in advance!

TypeError: __init__() got an unexpected keyword argument 'allowed_methods'

i keep getting below error on raspberry pi with python 2.7.16

Traceback (most recent call last):
File "orders.py", line 10, in
environment='sandbox',
File "/home/pi/orders/square/client.py", line 203, in init
additional_headers=additional_headers)
File "/home/pi/orders/square/configuration.py", line 96, in init
self._http_client = self.create_http_client()
File "/home/pi/orders/square/configuration.py", line 127, in create_http_client
retry_methods=self.retry_methods)
File "/home/pi/orders/square/http/requests_client.py", line 40, in init
status_forcelist=retry_statuses, allowed_methods=retry_methods)
TypeError: init() got an unexpected keyword argument 'allowed_methods'

python: catalog.create_catalog_image() name should be image_file

Describe the bug
The docs in square website and the actual json code associated with the attribute are not in agreement.

For the python API: catalog.create_catalog_image() name should be image_file. See here for more info

https://stackoverflow.com/questions/77163726/square-api-add-image-with-python-fails

Receiving INTERNAL_SERVER_ERROR error message when OAuth token expires

Per the documentation:

OAuth tokens need to be renewed regularly because they expire after 30 days.

When I invoke the batch_retrieve_catalog_objects method of the catalog API, I receive the following error message:

{
  "errors": [
    {
      "category": "API_ERROR",
      "code": "INTERNAL_SERVER_ERROR",
      "detail": "We were unable to authorize this request due to an internal error."
    }
  ]
}

I reauthorized the application to generate a new OAuth token and the method invocation succeeded.

It seems that INTERNAL_SERVER_ERROR is the incorrect code to return if the token expires, considering there is a ACCESS_TOKEN_EXPIRED error code.

Any ideas on what could be causing the issue?

FWIW, I received this error message at 2020-01-10 12:28:03.381 EST.

Please let me know if any additional information is required or if I should contact support.

create_catalog_image API doesn't seem to work or match API Explorer.

square-python-sdk/square/api/catalog_api.py

Line 244 in da0efa5

.value(image_file)

Going based on the API Explorer (https://developer.squareup.com/explorer/square/catalog-api/create-catalog-image) this should be "file" and not image_file. I'm not even sure what Python code the explorer is using as it succeeds, but if you try and use file= it will fail as there is no file argument in the definition of create_catalog_image.

Call:

    def add_image(self, card: Card) -> dict:
        """Adds a product's image to a card

        Parameters:
            card (Card): The card we are adding the image to.

        Returns:
            dict: The response from the Square API.
        """
        # Create a Square client
        client = Client(access_token=self.access_token)

        file_name = path.splitext(path.basename(card.image_url))[0] + '.jpg'
        file_path = path.join(self.image_path, card.chapter_code, file_name)
        image_file = (file_path, "rb")

        item_id = ShopIDLink().select().where(
            ShopIDLink.card_id == card.card_id,
            ShopIDLink.shop_flag == SHOP_FLAG
        ).first().shop_id

        # Prepare image payload
        image_payload = {
            'idempotency_key': str(uuid4()),
            'object_id': item_id,
            'image': {
                'type': 'IMAGE',
                'id': f'#{str(uuid4())}',
                'image_data': {
                    'name': str(card.card_name),
                }
            },
            'is_primary': True
        }

        try:
            response = client.catalog.create_catalog_image(
                request=image_payload,
                file=image_file
            )
            print(f'Payload: {image_payload}')
            return response.body
        except Exception as e:
            print(f'Payload: {image_payload}')
            print(f'Error adding product: {e}')
            return {'error': str(e)}

Error:

{'error': "CatalogApi.create_catalog_image() got an unexpected keyword argument 'file'"}

If you try and use image_file argument, it'll give you the following error: {'error': "'tuple' object has no attribute 'name'"}

Type annotations

Hi,

I was wondering if there was any plans to add type annotations to the Python SDK.

Thanks!

ModuleNotFoundError: No module named 'square.client'; 'square' is not a package

Hi, I'm currently trying to install this, and when I do pip install squareup or even pip install git+https://github.com/square/square-python-sdk.git it shows that it installed fine

(venv)$ pip install squareup
Requirement already satisfied: squareup in ./venv/lib/python3.6/site-packages (12.0.0.20210616)
Requirement already satisfied: jsonpickle<1.0,>=0.7.1 in ./venv/lib/python3.6/site-packages (from squareup) (0.9.6)
Requirement already satisfied: cachecontrol<1.0,>=0.11.7 in ./venv/lib/python3.6/site-packages (from squareup) (0.12.6)
Requirement already satisfied: python-dateutil<3.0,>=2.5.3 in ./venv/lib/python3.6/site-packages (from squareup) (2.8.1)
Requirement already satisfied: requests<3.0,>=2.9.1 in ./venv/lib/python3.6/site-packages (from squareup) (2.25.1)
Requirement already satisfied: deprecation>=2.0.6 in ./venv/lib/python3.6/site-packages (from squareup) (2.1.0)
Requirement already satisfied: msgpack>=0.5.2 in ./venv/lib/python3.6/site-packages (from cachecontrol<1.0,>=0.11.7->squareup) (1.0.2)
Requirement already satisfied: packaging in ./venv/lib/python3.6/site-packages (from deprecation>=2.0.6->squareup) (21.0)
Requirement already satisfied: six>=1.5 in ./venv/lib/python3.6/site-packages (from python-dateutil<3.0,>=2.5.3->squareup) (1.16.0)
Requirement already satisfied: certifi>=2017.4.17 in ./venv/lib/python3.6/site-packages (from requests<3.0,>=2.9.1->squareup) (2021.5.30)
Requirement already satisfied: idna<3,>=2.5 in ./venv/lib/python3.6/site-packages (from requests<3.0,>=2.9.1->squareup) (2.10)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in ./venv/lib/python3.6/site-packages (from requests<3.0,>=2.9.1->squareup) (1.26.5)
Requirement already satisfied: chardet<5,>=3.0.2 in ./venv/lib/python3.6/site-packages (from requests<3.0,>=2.9.1->squareup) (4.0.0)
Requirement already satisfied: pyparsing>=2.0.2 in ./venv/lib/python3.6/site-packages (from packaging->deprecation>=2.0.6->squareup) (2.4.7)

But then when I try and import, I get this

(venv)$ python
Python 3.6.13 (default, May  3 2021, 02:51:47) 
[GCC 9.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from square.client import Client
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/john/PycharmProjects/backgroundremoverapp/square.py", line 1, in <module>
    from square.client import Client
ModuleNotFoundError: No module named 'square.client'; 'square' is not a package
>>> 

I also did this

(venv)$pip -V
pip 21.1.3 from /home/john/PycharmProjects/backgroundremoverapp/venv/lib/python3.6/site-packages/pip (python 3.6)
(venv)$ python -V
Python 3.6.13

But if I do a which square or which squareup it returns nothing. Any help would be appreciated

how to get all order?

Upgrading the jsonpickle dependency

The jsonpickle version you are using is a bit outdated, wonder if you could update it to a more recent version.
In your setup.py file versions allowed are >=0.7.1, <1.0, those versions are from 2018.

You requirements.txt says: ~=1.4, >= 1.4.1, those versions are about a year old.

When we install the sdk from pypi, the setup.py version is leading, so the jsonpickle version is <1.0. Is that intentional? Especially given your requirements.txt has a version 2 years younger..

When combined with other dependencies this leads to dependency clashes.

Example Paging?

Looking for examples on

1. where to look in results to tell if we need to page
2. how to do the paging requests

for listing locations/orders/transactions