Customer API Best Practices

Applies to: Customers API | Cards API | Web Payments SDK | In-App Payments SDK | Payments API

Learn about the best practices for creating an application that manages a seller's customer roster using the Customers API.

To be listed in the Square App Marketplace, applications must meet specific requirements aligned with the best practices outlined in this guide. While optional for apps not intended for the App Marketplace, following these practices will help you build more reliable and valuable solutions for Square sellers.

The following requirements outline the essential implementations for managing customer data, processing payments, and storing card information. They're designed to prevent data inconsistencies, ensure accurate payment attribution, and uphold PCI compliance. Each requirement includes links to the relevant API documentation for further guidance.

Duplicate customers in the seller's roster can present challenges to their business and must be addressed manually by the seller or with the help of Square technical support. To avoid creating duplicate customers, you should:

• Use unique identifiers (an email or phone number is recommended) when creating customers.
• Implement logic to detect and prevent duplicate entries for the same customer.

For more information, see Create customer profiles.

Linking a payment to the customer who made it improves the accuracy of sales reporting and ensures that refunds are issued to the correct individual when needed.

• Always supply the correct customer_id when making payment-related API calls.
• This applies to:
  • The Reader SDK.
  • The Point of Sale API.
  • Payment-related APIs.

For more information, see CreatePayment.

• Provide explicit Terms of Service/Privacy Policy stating the storage of credit card information.

For more information, see Cards API.

• Implement a checkbox mechanism to acquire customer consent for storing credit card details.
• Ensure that consent is clearly documented and stored.

For more information, see Cards API.

The following code examples and patterns demonstrate the correct implementation of customer creation and payment processing. Each section includes sample JSON payloads, required fields, and validation steps. Follow these patterns to ensure reliable customer data management and payment attribution.

Before creating a new customer, check to see whether a customer already exists with that email address or phone number. For more information see, Create customer profiles.

{
  "customer": {
    "email_address": "[email protected]",
    "phone_number": "+1-555-555-0123",
    "given_name": "John",
    "family_name": "Doe"
  },
  "idempotency_key": "unique_idempotency_key"
}

• Use an email address or phone number as a unique identifier.
• Always include idempotency keys in create requests.
• Validate contact information before submission.

When processing payments, include the customer_id in your CreatePayment request. This is required for card-on-file payments and recommended for all other payment types. Without a customer_id, Square attempts to match the customer using an email or phone number or creates a new customer record if no match is found.

{
  "source_id": "card_nonce_or_token",
  "customer_id": "CUSTOMER_ID",
  "amount_money": {
    "amount": 1000,
    "currency": "USD"
  }
}

• Include customer_id in all payment requests when available.
• Validate that customer_id exists before making payment calls.
• Handle cases where customer_id might be invalid.

This section details specific implementation patterns for key API features. Each feature includes code-level considerations and common pitfalls to avoid. These practices are based on real integration scenarios and help prevent issues like duplicate customer records or incomplete card storage compliance.

Implementing card-on-file storage requires specific consent mechanisms and privacy policy components to maintain PCI compliance and protect customer data.

• Display a clear consent checkbox.
• Store consent records.
• Include a consent timestamp.
• Link to the Terms of Service.

• Clearly state your card storage policy.
• Describe how customer data will be used.
• Outline your data retention policies.
• Explain customers’ rights and control over their data.

Poor customer data management leads to duplicate records, which breaks customer-based reporting, complicates Point of Sale lookups, and causes redundant customer notifications.

• Check for existing customers before creating new records.
• Use reference keys to link customers with external systems.
• Implement strategies to merge duplicate customer records.
• Perform regular data cleanup to maintain accuracy and consistency.

This guide addresses common integration issues related to customer data integrity and payment processing. Each issue includes identifiable symptoms, step-by-step resolution instructions, and code examples that illustrate effective error handling and recovery strategies.

• Symptom: Multiple records for same customer.
• Resolution:
  1. Search for existing customers using email and phone number before creating a new record.
  2. Use idempotency keys to prevent accidental duplicates.
  3. Implement functionality to merge duplicate records when identified.

• Symptom: Payment failures due to customer_id issues.
• Resolution:
  1. Validate the customer_id before using it in requests.
  2. If validation fails, implement a retry mechanism that includes a customer lookup.
  3. Gracefully handle cases where the customer_id is expired or invalid, with appropriate error messaging and fallback logic.

Monitor key metrics and error patterns to ensure reliable customer operations and quickly detect integration issues. Each metric offers valuable insights into system health and API performance. Set up alerts for anomalies—particularly those related to customer creation and payment processing—to enable fast response and resolution.

• Success rate
• Duplicate detection rate
• Error rates by type

• Customer ID validation success
• Card-on-file usage rates
• Consent-tracking metrics

• Customer creation failures
• Payment integration issues
• Consent-recording failures

• API latency monitoring
• Error resolution time
• Customer lookup performance