Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Catalog API

Configure Catalog Quick Amount Settings

Quick amount settings configure the Square Register to show up to three preset amounts in the Quick Amount dialog box on the checkout screen. These amounts are set on a seller and location-specific basis. The amounts can be manually set by the API or calculated by Square based on the seller's payment patterns at the location.

When a QUICK_AMOUNTS_SETTINGS catalog object is created for a location, a seller at that location sees a POS quick amount configuration screen with the settings from the QUICK_AMOUNTS_SETTINGS object:

Mobile POS Quick Amount Configuration dialog

In the previous example, the POS is set to show quick amount buttons for the two amounts provided by the seller.

This example shows you how to create a quick amount settings catalog object for a location. Unlike other catalog objects, this object does not add items or item variations to the catalog item collection. The presence of a CatlogQuickAmountSettings object only configures and enables quick amount values.

Create a quick amount setting Permalink Get a link to this section

To create a QUICK_AMOUNTS_SETTINGS object as shown in the example, run the following cURL command and note that:

  1. The id field value "#quick_amount_1" starts with # to indicate that a new object is to be inserted.

  2. present_at_all_locations is false.

  3. The id of a location to apply quick amount settings is set.

  4. The option field is set to MANUAL, indicating the Square Register uses the two quick amounts defined in this object.

    curl https://connect.squareup.com/v2/catalog/object \
      -X POST \
      -H 'Square-Version: 2020-04-22' \
      -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
      -H 'Content-Type: application/json' \
      -d '{
        "object": {
          "type": "QUICK_AMOUNTS_SETTINGS",
          "is_deleted": false,
          "present_at_all_locations": false,
          "present_at_location_ids": [
            "{{LOCATION_ID}}"
          ],
          "quick_amounts_settings_data": {
            "option": "MANUAL",
            "amounts": [
              {
                "amount": {
                  "amount": 855,
                  "currency": "USD"
                },
                "type": "QUICK_AMOUNT_TYPE_MANUAL",
                "ordinal": 1,
                "score": 100
              },
              {
                "amount": {
                  "amount": 55,
                  "currency": "USD"
                },
                "type": "QUICK_AMOUNT_TYPE_MANUAL",
                "ordinal": 2,
                "score": 100
              }
            ]
          },
          "id": "#quick_amount_1"
        },
        "idempotency_key": "{{YOUR_ITEMPOTENCY_VALUE}}"
      }'
    

    On successful creation, an object like the following is returned:

    {
      "catalog_object": {
        "type": "QUICK_AMOUNTS_SETTINGS",
        "id": "IXEVKMKA6CWG6CH4MFB32YPV",
        "updated_at": "2020-04-17T20:50:44.31Z",
        "version": 1587156644310,
        "is_deleted": false,
        "present_at_all_locations": false,
        "present_at_location_ids": [
          "{{LOCATION_ID}}"
        ],
        "quick_amounts_settings_data": {
          "option": "MANUAL",
          "eligible_for_auto_amounts": false,
          "amounts": [
            {
              "type": "QUICK_AMOUNT_TYPE_MANUAL",
              "amount": {
                "amount": 855,
                "currency": "USD"
              },
              "score": 100,
              "ordinal": 1
            },
            {
              "type": "QUICK_AMOUNT_TYPE_MANUAL",
              "amount": {
                "amount": 55,
                "currency": "USD"
              },
              "score": 100,
              "ordinal": 1
            }               
          ]
        }
      },
      "id_mappings": [
        {
          "client_object_id": "#quick_amount_1",
          "object_id": "IXEVKMKA6CWG6CH4MFB32YPV"
        }
      ]
    }
    

    Note

    A location is limited to one QUICK_AMOUNTS_SETTINGS object. If you attempt to create a second object of this type, an error is returned.

Get an existing quick amount setting Permalink Get a link to this section

Use the SearchCatalogObjects endpoint to return any QUICK_AMOUNTS_SETTINGS objects that exist for a seller's locations:

curl https://connect.squareup.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "include_deleted_objects": false,
    "include_related_objects": true,
    "object_types": [
      "QUICK_AMOUNTS_SETTINGS"
    ]
  }'

The response returns an array of QUICK_AMOUNTS_SETTINGS objects that are not deleted, one object for each location:

{
  "objects": [
    {
      "type": "QUICK_AMOUNTS_SETTINGS",
      "id": "CP4I57JIFFVMRSZU63WPH6UD",
      "updated_at": "2020-04-17T20:58:19.397Z",
      "version": 1587157099397,
      "is_deleted": false,
      "present_at_all_locations": false,
      "present_at_location_ids": [
        "{{LOCATION_ID}}"
      ],
      "quick_amounts_settings_data": {
        "option": "MANUAL",
        "eligible_for_auto_amounts": true,
        "amounts": [
          {
            "type": "QUICK_AMOUNT_TYPE_MANUAL",
            "amount": {
              "amount": 855,
              "currency": "USD"
            },
            "score": 100,
            "ordinal": 1
          },
          {
            "type": "QUICK_AMOUNT_TYPE_MANUAL",
            "amount": {
              "amount": 55,
              "currency": "USD"
            },
            "score": 100,
            "ordinal": 1
          }             
        ]
      }
    }
  ],
  "latest_time": "2020-04-17T22:37:22.213Z"
}

Update a quick amount setting Permalink Get a link to this section

Update an existing QUICK_AMOUNTS_SETTINGS object by sending a request like the following cURL example.

Set the id field to the object_id value in the previous response. Set the version to the version returned in the previous response.

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "blart445",
    "object": {
      "id": "CP4I57JIFFVMRSZU63WPH6UD",
      "type": "QUICK_AMOUNTS_SETTINGS",
      "present_at_location_ids": [
        "{{LOCATION_ID}}"
      ],
      "present_at_all_locations": false,
      "quick_amounts_settings_data": {
        "option": "MANUAL",
        "eligible_for_auto_amounts": false,
        "amounts": [
          {
            "amount": {
              "amount": 1500,
              "currency": "USD"
            },
            "type": "QUICK_AMOUNT_TYPE_MANUAL",
            "ordinal": 1,
            "score": 100
          }
        ]
      },
      "version": 1587157099397
    }
  }'

Disable quick amounts Permalink Get a link to this section

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "blart_blart4",
    "object": {
      "id": "CP4I57JIFFVMRSZU63WPH6UD",
      "type": "QUICK_AMOUNTS_SETTINGS",
      "present_at_location_ids": [
        "{{LOCATION_ID}}"
      ],
      "quick_amounts_settings_data": {
        "option": "DISABLED",
        "eligible_for_auto_amounts": true
      },
      "is_deleted": false,
      "present_at_all_locations": false,
      "version": 1587157099397
    }
  }'

The response returns:

{
  "catalog_object": {
    "type": "QUICK_AMOUNTS_SETTINGS",
    "id": "CP4I57JIFFVMRSZU63WPH6UD",
    "updated_at": "2020-04-17T22:37:22.213Z",
    "version": 1587163042213,
    "is_deleted": false,
    "present_at_all_locations": false,
    "present_at_location_ids": [
      "{{LOCATION_ID}}"
    ],
    "quick_amounts_settings_data": {
      "option": "DISABLED",
      "eligible_for_auto_amounts": false
    }
  }
}