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

Configure Preset Charges for Quick Payments

You can configure up to three preset charges with the quick amounts settings. Using configured quick amounts settings, the Square Register displays the preset charges in the Quick Amounts dialog box on the checkout screen. The quick amounts settings are seller- and location-dependent. You can call the Catalog API to configure quick amounts manually. Alternatively, Square can determine them automatically based on seller's order history at a location.

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

Mobile POS Quick Amount Configuration dialog

In this example, the Square POS shows the two quick amounts set by the seller for the specific location.

Unlike other catalog objects, a QUICK_AMOUNTS_SETTINGS object does not require items or item variations being added to the catalog item collection. The presence of a CatalogQuickAmountSettings 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, call the UpsertCatalogObject endpoint, specifying QUICK_AMOUNTS_SETTINGS as the object's type property and providing an appropriate CatalogQuickAmountsSettings object on the quick_amounts_settings_data property.

The following cURL command shows how to use the Catalog API to create a QuickAmountsSettings object:

Upsert Catalog Object
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -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": 85,
              "currency": "USD"
            },
            "type": "QUICK_AMOUNT_TYPE_MANUAL",
            "ordinal": 2,
            "score": 100
          }
        ]
      },
      "id": "#quick_amount_1"
    },
    "idempotency_key": "{{YOUR_ITEMPOTENCY_VALUE}}"
  }'

In the request body, the present_at_all_locations field must be set to false to indicate that the resulting quick amounts settings apply to the specified location ({{LOCATION_ID}}) as referenced in the present_at_locations_ids field. In this example, the option field of quick_amounts_settings_data is set to MANUAL. This option lets the seller choose manually created quick amounts as specified herein. You can set option to AUTO to let the seller to choose automatically created quick amounts based on the seller's payment-receiving trends.

On successful creation, a CatalogQuickAmountsSettings object similar to the following one 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": 85,
                "currency": "USD"
              },
              "score": 100,
              "ordinal": 1
            }               
          ]
        }
      },
      "id_mappings": [
        {
          "client_object_id": "#quick_amount_1",
          "object_id": "IXEVKMKA6CWG6CH4MFB32YPV"
        }
      ]
    }

Note

A location can have only one QUICK_AMOUNTS_SETTINGS object configured for it. If you attempt to create a second object of this type, you get an error.

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

To obtain any of the existing QUICK_AMOUNTS_SETTINGS objects for a seller's location, call the SearchCatalogObjects endpoint, specifying QUICK_AMOUNTS_SETTINGS in the object_types list.

The following cURL command shows the API request to retrieve non-deleted quick amounts settings:

Search Catalog Objects
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -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 non-deleted QUICK_AMOUNTS_SETTINGS objects, one per 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": 85,
              "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

To update an existing QUICK_AMOUNTS_SETTINGS object, call the UpsertCatalogObject specifying an CatalogQuickAmountsSettings object whose id field is set to the ID of the existing object and whose quick_amounts_settings_data field contains the updated settings.

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

Upsert Catalog Object
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -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

To disable preset quick amounts, call the UpsertCatalogObject endpoint and specify the option field of the quick_amounts_settings_data object to DISABLE.

Upsert Catalog Object
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -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
    }
  }
}