Square API
Developer Home
Developer Docs
Square API

You are viewing an old version of the API
Create checkout

Links a checkoutId to a checkout_page_url that customers will be directed to in order to provide their payment information using a payment processing workflow hosted on connect.squareup.com

Required permissions PAYMENTS_WRITE ORDERS_WRITE

Path Parameters
Name Description
location_id
string
Required

The ID of the business location to associate the checkout with.

Request Body
Name Description
idempotency_key
string
Required

A unique string that identifies this checkout among others you've created. It can be any valid string but must be unique for every order sent to Square Checkout for a given location ID.

The idempotency key is used to avoid processing the same order more than once. If you're unsure whether a particular checkout was created successfully, you can reattempt it with the same idempotency key and all the same other parameters without worrying about creating duplicates.

We recommend using a random number/string generator native to the language you are working in to generate strings for your idempotency keys.

See Idempotency keys for more information.

Max Length 192 Min Length 1
order
Create​Order​Request
Required

The order including line items to be checked out.
additional_recipients
Charge​Request​Additional​Recipient [ ]

The basic primitive of multi-party transaction. The value is optional. The transaction facilitated by you can be split from here.

If you provide this value, the amount_money value in your additional_recipients must not be more than 90% of the total_money calculated by Square for your order. The location_id must be the valid location of the app owner merchant.

This field requires PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission.

This field is currently not supported in sandbox.
ask_for_shipping_address
boolean

If true, Square Checkout will collect shipping information on your behalf and store that information with the transaction information in your Square Dashboard.

Default: false.
merchant_support_email
string

The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the merchant.

If this value is not set, the confirmation page and email will display the primary email address associated with the merchant's Square account.

Default: none; only exists if explicitly set.

Max Length 254
note
string

An optional note to associate with the checkout object.

This value cannot exceed 60 characters.

Max Length 60
pre_populate_buyer_email
string

If provided, the buyer's email is pre-populated on the checkout page as an editable text field.

Default: none; only exists if explicitly set.

Max Length 254
pre_populate_shipping_address
Address

If provided, the buyer's shipping info is pre-populated on the checkout page as editable text fields.

Default: none; only exists if explicitly set.
redirect_url
string

The URL to redirect to after checkout is completed with checkoutId, Square's orderId, transactionId, and referenceId appended as URL parameters. For example, if the provided redirect_url is http://www.example.com/order-complete, a successful transaction redirects the customer to:

http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx

If you do not provide a redirect URL, Square Checkout will display an order confirmation page on your behalf; however Square strongly recommends that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow.

Default: none; only exists if explicitly set.

Max Length 800

Response Fields
Name Description
checkout
Checkout

The newly created checkout. If the same request was made with the same idempotencykey, this will be the checkout created with the idempotencykey.
errors
Error [ ]

Any errors that occurred during the request.

Examples

You are viewing an old version of the API
POST /v2/locations/{location_id}/checkouts
cURL
  • cURL
  • Ruby
  • Python 
curl https://connect.squareup.com/v2/locations/{location_id}/checkouts \
  -X POST \
  -H 'Square-Version: 2019-11-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d "{
    \"idempotency_key\": \"86ae1696-b1e3-4328-af6d-f1e04d947ad6\",
    \"order\": {
      \"reference_id\": \"reference_id\",
      \"line_items\": [
        {
          \"name\": \"Printed T Shirt\",
          \"quantity\": \"2\",
          \"base_price_money\": {
            \"amount\": 1500,
            \"currency\": \"USD\"
          },
          \"discounts\": [
            {
              \"name\": \"7% off previous season item\",
              \"percentage\": \"7\"
            },
            {
              \"name\": \"$3 off Customer Discount\",
              \"amount_money\": {
                \"amount\": 300,
                \"currency\": \"USD\"
              }
            }
          ]
        },
        {
          \"name\": \"Slim Jeans\",
          \"quantity\": \"1\",
          \"base_price_money\": {
            \"amount\": 2500,
            \"currency\": \"USD\"
          }
        },
        {
          \"name\": \"Woven Sweater\",
          \"quantity\": \"3\",
          \"base_price_money\": {
            \"amount\": 3500,
            \"currency\": \"USD\"
          },
          \"discounts\": [
            {
              \"name\": \"$11 off Customer Discount\",
              \"amount_money\": {
                \"amount\": 1100,
                \"currency\": \"USD\"
              }
            }
          ],
          \"taxes\": [
            {
              \"name\": \"Fair Trade Tax\",
              \"percentage\": \"5\"
            }
          ]
        }
      ],
      \"discounts\": [
        {
          \"name\": \"Father's day 12% OFF\",
          \"percentage\": \"12\"
        },
        {
          \"name\": \"Global Sales $55 OFF\",
          \"amount_money\": {
            \"amount\": 5500,
            \"currency\": \"USD\"
          }
        }
      ],
      \"taxes\": [
        {
          \"name\": \"Sales Tax\",
          \"percentage\": \"8.5\"
        }
      ]
    },
    \"additional_recipients\": [
      {
        \"location_id\": \"057P5VYJ4A5X1\",
        \"description\": \"Application fees\",
        \"amount_money\": {
          \"amount\": 60,
          \"currency\": \"USD\"
        }
      }
    ],
    \"ask_for_shipping_address\": true,
    \"merchant_support_email\": \"merchant+support@website.com\",
    \"pre_populate_buyer_email\": \"example@email.com\",
    \"pre_populate_shipping_address\": {
      \"address_line_1\": \"1455 Market St.\",
      \"address_line_2\": \"Suite 600\",
      \"locality\": \"San Francisco\",
      \"administrative_district_level_1\": \"CA\",
      \"postal_code\": \"94103\",
      \"country\": \"US\",
      \"first_name\": \"Jane\",
      \"last_name\": \"Doe\"
    },
    \"redirect_url\": \"https://merchant.website.com/order-confirm\"
  }"
Response JSON 
{
  "checkout": {
    "id": "CAISEHGimXh-C3RIT4og1a6u1qw",
    "checkout_page_url": "https://connect.squareup.com/v2/checkout?c=CAISEHGimXh-C3RIT4og1a6u1qw&l=CYTKRM7R7JMV8",
    "ask_for_shipping_address": true,
    "merchant_support_email": "merchant+support@website.com",
    "pre_populate_buyer_email": "example@email.com",
    "pre_populate_shipping_address": {
      "address_line_1": "1455 Market St.",
      "address_line_2": "Suite 600",
      "locality": "San Francisco",
      "administrative_district_level_1": "CA",
      "postal_code": "94103",
      "country": "US",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "redirect_url": "https://merchant.website.com/order-confirm",
    "order": {
      "location_id": "CYTKRM7R7JMV8",
      "reference_id": "reference_id",
      "line_items": [
        {
          "name": "Printed T Shirt",
          "quantity": "2",
          "taxes": [
            {
              "name": "Sales Tax",
              "type": "ADDITIVE",
              "percentage": "8.5",
              "applied_money": {
                "amount": 103,
                "currency": "USD"
              }
            }
          ],
          "discounts": [
            {
              "name": "7% off previous season item",
              "type": "FIXED_PERCENTAGE",
              "percentage": "7",
              "applied_money": {
                "amount": 210,
                "currency": "USD"
              },
              "scope": "LINE_ITEM"
            },
            {
              "name": "Father's day 12% OFF",
              "type": "FIXED_PERCENTAGE",
              "percentage": "12",
              "applied_money": {
                "amount": 335,
                "currency": "USD"
              },
              "scope": "ORDER"
            },
            {
              "name": "$3 off Customer Discount",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 300,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 300,
                "currency": "USD"
              },
              "scope": "LINE_ITEM"
            },
            {
              "name": "Global Sales $55 OFF",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 5500,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 949,
                "currency": "USD"
              },
              "scope": "ORDER"
            }
          ],
          "base_price_money": {
            "amount": 1500,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 103,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 1794,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1309,
            "currency": "USD"
          }
        },
        {
          "name": "Slim Jeans",
          "quantity": "1",
          "taxes": [
            {
              "name": "Sales Tax",
              "type": "ADDITIVE",
              "percentage": "8.5",
              "applied_money": {
                "amount": 105,
                "currency": "USD"
              }
            }
          ],
          "discounts": [
            {
              "name": "Father's day 12% OFF",
              "type": "FIXED_PERCENTAGE",
              "percentage": "12",
              "applied_money": {
                "amount": 300,
                "currency": "USD"
              },
              "scope": "ORDER"
            },
            {
              "name": "Global Sales $55 OFF",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 5500,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 968,
                "currency": "USD"
              },
              "scope": "ORDER"
            }
          ],
          "base_price_money": {
            "amount": 2500,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 105,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 1268,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1337,
            "currency": "USD"
          }
        },
        {
          "name": "Wooven Sweater",
          "quantity": "3",
          "taxes": [
            {
              "name": "Fair Trade Tax",
              "type": "ADDITIVE",
              "percentage": "5",
              "applied_money": {
                "amount": 228,
                "currency": "USD"
              }
            },
            {
              "name": "Sales Tax",
              "type": "ADDITIVE",
              "percentage": "8.5",
              "applied_money": {
                "amount": 387,
                "currency": "USD"
              }
            }
          ],
          "discounts": [
            {
              "name": "Father's day 12% OFF",
              "type": "FIXED_PERCENTAGE",
              "percentage": "12",
              "applied_money": {
                "amount": 1260,
                "currency": "USD"
              },
              "scope": "ORDER"
            },
            {
              "name": "$11 off Customer Discount",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 1100,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 1100,
                "currency": "USD"
              },
              "scope": "LINE_ITEM"
            },
            {
              "name": "Global Sales $55 OFF",
              "type": "FIXED_AMOUNT",
              "amount_money": {
                "amount": 5500,
                "currency": "USD"
              },
              "applied_money": {
                "amount": 3583,
                "currency": "USD"
              },
              "scope": "ORDER"
            }
          ],
          "base_price_money": {
            "amount": 3500,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 615,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 5943,
            "currency": "USD"
          },
          "total_money": {
            "amount": 5172,
            "currency": "USD"
          }
        }
      ],
      "total_money": {
        "amount": 7818,
        "currency": "USD"
      },
      "total_tax_money": {
        "amount": 823,
        "currency": "USD"
      },
      "total_discount_money": {
        "amount": 9005,
        "currency": "USD"
      }
    },
    "created_at": "2017-06-16T22:25:35Z",
    "additional_recipients": [
      {
        "location_id": "057P5VYJ4A5X1",
        "description": "Application fees",
        "amount_money": {
          "amount": 60,
          "currency": "USD"
        }
      }
    ]
  }
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?