Create and Manage Gift Cards with Customer Integration

Applies to: Customers API | Gift Cards API

Learn how to integrate the Customers API with the Gift Cards API to create or find customers and manage their gift cards.

Prerequisites

Before you begin, you need the following:

A Square account (sign up for a free developer account if you don't have one).
An access token for the Square API. For more information, see Get Started.

The following language-specific requirements are needed to run the code samples:

Java 8 or later
Square Java SDK 35.0.0 or later
Gradle or Maven

Add this dependency to your build.gradle file:

implementation 'com.squareup:square:35.0.0'

Or to your pom.xml file:

<dependency>
  <groupId>com.squareup</groupId>
  <artifactId>square</artifactId>
  <version>35.0.0</version>
</dependency>

Link to section

1. Initialize the Square client

Set up the Square client with your credentials.

import com.squareup.square.SquareClient;
import com.squareup.square.Environment;

public class GiftCardService {
    private final SquareClient client;

    public GiftCardService(String accessToken) {
        client = new SquareClient.Builder()
            .environment(Environment.SANDBOX)
            .accessToken(accessToken)
            .build();
    }
}

Link to section

2. Search for an existing customer

Search for a customer using their email address.

public Customer findOrCreateCustomer(String firstName, String lastName, 
    String emailAddress, String streetAddress) throws ApiException {

    SearchCustomersRequest searchRequest = new SearchCustomersRequest.Builder()
        .query(new CustomerQuery.Builder()
            .filter(new CustomerFilter.Builder()
                .emailAddress(new CustomerTextFilter.Builder()
                    .exact(emailAddress)
                    .build())
                .build())
            .build())
        .build();

    SearchCustomersResponse searchResponse = client.getCustomersApi()
        .searchCustomers(searchRequest);

    if (searchResponse.getCustomers() != null && !searchResponse.getCustomers().isEmpty()) {
        return searchResponse.getCustomers().get(0);
    }

    // Customer not found, create new one
    Address address = new Address.Builder()
        .addressLine1(streetAddress)
        .build();

    CreateCustomerRequest createRequest = new CreateCustomerRequest.Builder()
        .idempotencyKey(UUID.randomUUID().toString())
        .givenName(firstName)
        .familyName(lastName)
        .emailAddress(emailAddress)
        .address(address)
        .build();

    CreateCustomerResponse createResponse = client.getCustomersApi()
        .createCustomer(createRequest);

    return createResponse.getCustomer();
}

Link to section

3. Manage gift cards

Create a new gift card or retrieve existing ones for the customer.

public GiftCard createOrGetGiftCard(Customer customer, Money amount) throws ApiException {
    // First check for existing gift cards
    SearchGiftCardsRequest searchRequest = new SearchGiftCardsRequest.Builder()
        .query(new GiftCardQuery.Builder()
            .filter(new GiftCardFilter.Builder()
                .customerId(customer.getId())
                .build())
            .build())
        .build();

    SearchGiftCardsResponse searchResponse = client.getGiftCardsApi()
        .searchGiftCards(searchRequest);

    if (searchResponse.getGiftCards() != null && !searchResponse.getGiftCards().isEmpty()) {
        GiftCard existingCard = searchResponse.getGiftCards().get(0);
        // Load additional funds to existing card
        GiftCardActivity activity = new GiftCardActivity.Builder()
            .type("LOAD")
            .locationId("YOUR_LOCATION_ID")
            .giftCardId(existingCard.getId())
            .loadActivityDetails(
                new GiftCardActivityLoad.Builder()
                    .amountMoney(amount)
                    .build())
            .build();

        CreateGiftCardActivityRequest activityRequest = new CreateGiftCardActivityRequest.Builder()
            .idempotencyKey(UUID.randomUUID().toString())
            .giftCardActivity(activity)
            .build();

        client.getGiftCardActivitiesApi().createGiftCardActivity(activityRequest);
        return existingCard;
    }

    // Create new gift card
    CreateGiftCardRequest createRequest = new CreateGiftCardRequest.Builder()
        .idempotencyKey(UUID.randomUUID().toString())
        .locationId("YOUR_LOCATION_ID")
        .giftCard(new GiftCard.Builder()
            .type("DIGITAL")
            .customerId(customer.getId())
            .build())
        .build();

    CreateGiftCardResponse createResponse = client.getGiftCardsApi()
        .createGiftCard(createRequest);

    GiftCard newCard = createResponse.getGiftCard();

    // Activate the new card with initial balance
    GiftCardActivity activity = new GiftCardActivity.Builder()
        .type("ACTIVATE")
        .locationId("YOUR_LOCATION_ID")
        .giftCardId(newCard.getId())
        .activateActivityDetails(
            new GiftCardActivityActivate.Builder()
                .amountMoney(amount)
                .build())
        .build();

    CreateGiftCardActivityRequest activityRequest = new CreateGiftCardActivityRequest.Builder()
        .idempotencyKey(UUID.randomUUID().toString())
        .giftCardActivity(activity)
        .build();

    client.getGiftCardActivitiesApi().createGiftCardActivity(activityRequest);
    return newCard;
}

Link to section

Complete example

The following is a complete example showing how to use the service:

import com.squareup.square.SquareClient;
import com.squareup.square.Environment;
import com.squareup.square.exceptions.ApiException;
import com.squareup.square.models.*;

import java.util.UUID;

public class GiftCardService {
    private final SquareClient client;

    public GiftCardService(String accessToken) {
        client = new SquareClient.Builder()
            .environment(Environment.SANDBOX)
            .accessToken(accessToken)
            .build();
    }

    public void processCustomerGiftCard(String firstName, String lastName, 
        String emailAddress, String streetAddress, Money amount) throws ApiException {

        // Find or create customer
        Customer customer = findOrCreateCustomer(firstName, lastName, emailAddress, streetAddress);

        // Create or load gift card
        GiftCard giftCard = createOrGetGiftCard(customer, amount);

        System.out.println("Gift card processed successfully for customer: " + 
            customer.getGivenName() + " " + customer.getFamilyName());
        System.out.println("Gift card ID: " + giftCard.getId());
    }

    // ... (include findOrCreateCustomer and createOrGetGiftCard methods from above)

    public static void main(String[] args) {
        try {
            GiftCardService service = new GiftCardService("YOUR_ACCESS_TOKEN");
            Money amount = new Money.Builder()
                .amount(10000L) // $100.00
                .currency("USD")
                .build();

            service.processCustomerGiftCard(
                "John",
                "Doe",
                "[email protected]",
                "123 Main St",
                amount
            );
        } catch (ApiException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Link to section

Next steps

Learn more about managing customer profiles.
Explore how to manage gift cards on file.
Learn about reloading gift cards.

Docs

Quickstart: Create and Manage Gift Cards with Customer Integration

On this page

Prerequisites

1. Initialize the Square client

2. Search for an existing customer

3. Manage gift cards

Complete example

Next steps

On this page