Customers API

Build with Customers

Integrate with the Customers API to manage profiles and take payment with cards on file.

Customers API

The Customers API can create and manage customer profiles and save credit card information (card on file) for future and recurring payments. This guide provides step-by-step instruction for integrating with the Customers API.

Important

Ask for explicit permission before saving customer contact information or cards on file. For example, you can include a checkbox in your purchase flow (unchecked by default) that the customer can check to specify that they wish to save their card information for future purchases. Abuse of customer contact information may result in your application being disabled without notice.

Prerequisites and assumptions
Permalink Get a link to this section

  • You have a Square Account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activate.

  • You are using HTTPS. HTTPS is required for all production Square API calls. HTTP calls are only supported for developing and testing on localhost.

  • You must follow best practices for collecting information. Abuse of customer contact information may result in your application being disabled without notice.


Additionally, this guide makes the following assumptions:

  • You have read the What It Does page for this product.

  • You can create and run websites on localhost or a development server. If you are new to testing webpages locally, we recommend reading Running Local Web Servers before continuing.

  • You are familiar with basic web development. If you are new to web development, we recommend reading Getting started with the Web by Mozilla.org before continuing.

Information you will need
Permalink Get a link to this section

To use the steps in this guide you will need the following information:

  • A valid access token. Square recommends testing with sandbox credentials whenever possible. See Square API Access Tokens for more information.

Step 1: Add code that collects customer information
Permalink Get a link to this section

Your eCommerce site needs a way to collect customer information. The code below is a minimal HTML form that asks customers to:

  • Provide their name, email, and physical address.

  • Provide consent to save their data in a customer profile.

  • Provide consent to save a credit card on file for future or recurring payments.

Add this code to the page where you want to collect customer information.

To create a Customer object, you'll need to provide at least one of the following fields:

  • given_name

  • family_name

  • company_name

  • email_address

  • phone_number

Read about other available fields in the API reference for CreateCustomer.

<!-- Sample Customer Form-->
<form action="create_customer_request.php" method="post" onsubmit="paymentFormSubmit()" >
    <h2>Save a Customer Profile</h2>
      <label>Name</label>
      <input type="text" id="name" name="name"  placeholder="Name"/>
      <label>Email</label>
      <input type="email" id="email" name="email"  placeholder="Email" required/>

    <h3> Shipping Address </h3>
      <label>Street</label>
      <input type="text" id="streetAddress1" name="streetAddress1"  placeholder="Address Line 1"/>
      <label>Street</label>
      <input type="text" id="streetAddress2" name="streetAddress2"  placeholder="Address Line 2"/>
      <label>City</label>
      <input type="text" id="city" name="city"  placeholder="City"/>
      <label>Zip</label>
      <input type="text" id="zip" name="zip"  placeholder="Zip"/>

    <!--We recommend you ask your customers for consent before saving any customer information.-->
    <p>
      <input type="checkbox" name="checkbox" value="check" required>
      Allow us to save your information to a customer profile.
    </p>

    <!--You must ask your customers for consent before saving credit card information.
    Uncomment this extra checkbox if you want to save cards on file.-->
    <!--
    <p>
      <input type="checkbox" name="checkbox" value="check" required>
      Allow us to save your credit card information for future purchases.
    </p>
    -->
    <input type="submit" id="submit" value="submit" class="btn btn-primary"/>
  </form>

Step 3: Package the customer information
Permalink Get a link to this section

Pull the customer information from your HTML form and package it as a Customer object.

Did you know?

The CreateCustomer endpoint accepts partial addresses. For example, you can save a customer zipcode without including their full street address. Even if you only provide a partial address, the CreateCustomer return object includes an Address object to hold the address information. If you do not explicitly set the country field in an Address object, it has the default value "ZZ"


//Pull in fields from your HTML form
$name = $_POST['name'];
$email = $_POST['email'];
$streetAddress1 = $_POST['street_address_1'];
$streetAddress2 = $_POST['street_address_2'];
$city = $_POST['city'];
$zip = $_POST['zip'];

// Set values in your address object.
$customerAddress = new \SquareConnect\Model\Address();
$customerAddress->setAddressLine1($streetAddress1);
$customerAddress->setAddressLine2($streetAddress2);
$customerAddress->setCity($city);
$customerAddress->setZip($zip);

// Set values in your customer object.
$customer = new \SquareConnect\Model\CreateCustomerRequest();
$customer->setGivenName($name);
$customer->setEmailAddress($email);
$customer->setAddress($customerAddress);

Step 3: Call CreateCustomer
Permalink Get a link to this section

Initialize a default API client with your access token. You can use the default client to create a Customeres API client and send the request object to the CreateCustomer endpoint. For now, we will print the raw result to the screen.

On success, the CreateCustomer endpoint returns your Customer object with 3 new fields:

  • A unique ID: use this value to reference this customer in other API calls.

  • A created on timestamp: the date and time this customer profile was created.

  • A last updated timestamp: the date and time this customer profile was last updated.

Note: This PHP example sets the API host URL to the v2 Sandbox environment. In production, use the default host.

//Replace with your access token
$accessToken = '{REPLACE_ME}';

// Create and configure a new API client object
$defaultApiConfig = new \SquareConnect\Configuration();
$defaultApiConfig->setHost("https://connect.squareupsandbox.com");
$defaultApiConfig->setAccessToken($accessToken);

// Create a Customers API client
$defaultApiClient = new \SquareConnect\ApiClient($defaultApiConfig);
$customersApi = new SquareConnect\Api\CustomersApi($defaultApiClient);

// Call CreateCustomer
try {
    $result = $customersApi->createCustomer($customer);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling CustomersApi->createCustomer: ', $e->getMessage(), PHP_EOL;
}

Next steps

Now that you have a basic build in place, expand on it with these recipes!