Learn how to manage checkout links. The Checkout API provides endpoints to manage the checkout pages you created.
Checkout API

Manage Checkout

The Checkout API (see Checkout API Overview) provides endpoints to manage the checkout pages you created. You can update, retrieve, or delete the checkout pages.

Update a payment link Permalink Get a link to this section

You can use the UpdatePaymentLink endpoint to update the following payment_link fields.

  • description.

  • checkout_options. You should specify the entire CheckoutOptions object in the update request. If you specify only specific fields, the update operation deletes fields not included in the request.

  • pre_populated_data. You only specify the PrePopulatedData fields that you want to update (or add). If a field you provided in the request does not exist, it gets added.

You cannot update the order_id, version, URL, or timestamp fields.

In the following example, you create a checkout page and then call UpdatePaymentLink to apply the updates.

  1. Create a quick pay checkout page for $125 for auto detailing:

    Create Payment Link
    • 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
    curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \
      -X POST \
      -H 'Square-Version: 2022-06-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "quick_pay": {
          "name": "Auto Detailing",
          "price_money": {
            "amount": 12500,
            "currency": "USD"
          },
          "location_id": "{LOCATION_ID}"
        },
        "pre_populated_data": {
          "buyer_email": "buyer@email.com",
          "buyer_phone_number": "1-415-555-1212",
          "buyer_address": {
            "address_line_1": "1455 MARKET ST #600",
            "country": "US",
            "administrative_district_level_1": "CA",
            "locality": "San Jose",
            "postal_code": "94103"
          }
        },
        "checkout_options": {
          "allow_tipping": true,
          "ask_for_shipping_address": true,
          "custom_fields": [
            {
              "title": "Special Instructions"
            },
            {
              "title": "Would you like to be on mailing list"
            }
          ]
        }
      }'

    The following is an example response:

    • 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
    {
      "payment_link": {
        "id": "OTKXE56AZGRBPAN4",
        "version": 1,
        "order_id": "m1rS3y9B95BWRTVJVs9K3iJD4yLZY",
        "checkout_options": {
          "allow_tipping": true,
          "custom_fields": [
            {
              "title": "Special Instructions",
              "uid": "N3W4FIWOAGI7GMYV62MQ7MQ3"
            },
            {
              "title": "Would you like to be on mailing list",
              "uid": "J7ETDA6UANCFB3UIXJP5AGL6"
            }
          ],
          "ask_for_shipping_address": true
        },
        "pre_populated_data": {
          "buyer_email": "buyer@email.com",
          "buyer_phone_number": "+14155551212",
          "buyer_address": {
            "address_line_1": "1455 MARKET ST #600",
            "locality": "San Jose",
            "administrative_district_level_1": "CA",
            "postal_code": "94103",
            "country": "US"
          }
        },
        "url": "https://sandbox.square.link/u/J1lWcEhY",
        "created_at": "2022-04-22T02:50:39Z"
      }
    }
    
  2. Update the following fields:

    • description. Add a description.

    • checkout_options. Specify a new custom_fields ("Very Special Instructions"). You verify that both the existing custom fields are deleted.

    • pre_populated_data. Specify only the buyer_email and address_line_1 fields. You verify that all other fields are preserved.

    • Specify fields_to_clear to remove checkout_options.allow_tipping.

  3. Run the following UpdatePaymentLink request to apply the updates:

    Update Payment Link
    • 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
    curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links/{id} \
      -X PUT \
      -H 'Square-Version: 2022-06-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "payment_link": {
          "version": 1,
          "description": "updated  description",
          "checkout_options": {
            "custom_fields": [
              {
                "title": "Very special Instructions "
              }
            ]
          },
          "pre_populated_data": {
            "buyer_email": "buyer-updated@email.com",
            "buyer_address": {
              "address_line_1": "1455 MARKET ST #6600"
            }
          }
        },
        "fields_to_clear": [
          "checkout_options.allow_tipping"
        ]
      }'

    Note that fields_to_clear is an array where you provide a comma-separated list of fields to delete. For example:

    This deletes the allow_tipping field from checkout_options and the entire buyer_address from pre_populated_data. To delete the entire checkout_options, specify the following:

Retrieve payment links Permalink Get a link to this section

You can retrieve a specific payment link by ID or all the payment links in the account. The Checkout API provides the RetrievePaymentLinks and ListPaymentLinks endpoints. Try using API Explorer to test these endpoints.

Delete a payment link Permalink Get a link to this section

You can use the DeletePaymentLinks endpoint to delete a payment link you created.

Delete Payment Link
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links/{id} \
  -X DELETE \
  -H 'Square-Version: 2022-06-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

After receiving the request, the endpoint sets the corresponding order state to CANCELED and deletes the checkout link.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.