openapi: 3.0.3
info:
  title: Square Catalog Customers API
  description: Square API provides payment processing, commerce, customer management, and business operations capabilities for sellers, developers, and merchants. Supports point-of-sale, ecommerce, invoicing, loyalty, gift cards, and more.
  version: 2026-01-22
  contact:
    name: Square Developer Support
    url: https://developer.squareup.com/forums
  termsOfService: https://squareup.com/us/en/legal/general/developer
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://connect.squareup.com/v2
  description: Production
- url: https://connect.squareupsandbox.com/v2
  description: Sandbox
security:
- BearerAuth: []
- OAuth2: []
tags:
- name: Customers
  description: Customer management and engagement
paths:
  /customers:
    get:
      operationId: list-customers
      summary: Block Square List Customers
      description: Lists customer profiles associated with a Square account.
      tags:
      - Customers
      parameters:
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor.
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100
        description: Maximum number of results to return.
      responses:
        '200':
          description: Customers retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomersResponse'
              examples:
                list-customers:
                  summary: List of customers
                  value:
                    customers:
                    - id: JDKYHBWT1D4F8MFH63DBMEN8Y4
                      given_name: Amelia
                      family_name: Earhart
                      email_address: Amelia.Earhart@example.com
                      phone_number: '+11234567890'
                      created_at: '2016-03-23T20:21:54.859Z'
                      updated_at: '2016-03-23T20:21:55Z'
                  x-microcks-default: true
      x-microcks-operation:
        delay: 50
        dispatcher: FALLBACK
    post:
      operationId: create-customer
      summary: Block Square Create Customer
      description: Creates a new customer for a business.
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
            examples:
              create-customer:
                summary: New customer
                value:
                  idempotency_key: 916f88d4-ba1d-11ea-b3de-0242ac130004
                  given_name: Amelia
                  family_name: Earhart
                  email_address: Amelia.Earhart@example.com
                  phone_number: '+11234567890'
                x-microcks-default: true
      responses:
        '200':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCustomerResponse'
              examples:
                created-customer:
                  summary: Created customer
                  value:
                    customer:
                      id: JDKYHBWT1D4F8MFH63DBMEN8Y4
                      given_name: Amelia
                      family_name: Earhart
                      email_address: Amelia.Earhart@example.com
                      phone_number: '+11234567890'
                      created_at: '2016-03-23T20:21:54.859Z'
                      updated_at: '2016-03-23T20:21:55Z'
                  x-microcks-default: true
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
components:
  schemas:
    ListCustomersResponse:
      type: object
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
        cursor:
          type: string
    CreateCustomerResponse:
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
    Customer:
      type: object
      description: Represents a customer profile in a Square seller account.
      properties:
        id:
          type: string
          description: Unique ID for this customer.
          example: JDKYHBWT1D4F8MFH63DBMEN8Y4
        given_name:
          type: string
          description: Customer's first name.
          example: Amelia
        family_name:
          type: string
          description: Customer's last name.
          example: Earhart
        email_address:
          type: string
          format: email
          description: Customer's email address.
          example: Amelia.Earhart@example.com
        phone_number:
          type: string
          description: Customer's phone number.
          example: '+11234567890'
        created_at:
          type: string
          format: date-time
          example: '2016-03-23T20:21:54.859Z'
        updated_at:
          type: string
          format: date-time
          example: '2016-03-23T20:21:55Z'
    CreateCustomerRequest:
      type: object
      properties:
        idempotency_key:
          type: string
          example: 916f88d4-ba1d-11ea-b3de-0242ac130004
        given_name:
          type: string
          example: Amelia
        family_name:
          type: string
          example: Earhart
        email_address:
          type: string
          format: email
          example: Amelia.Earhart@example.com
        phone_number:
          type: string
          example: '+11234567890'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Personal access token for Square API
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://connect.squareup.com/oauth2/authorize
          tokenUrl: https://connect.squareup.com/oauth2/token
          scopes:
            PAYMENTS_READ: Read payments
            PAYMENTS_WRITE: Write payments
            ORDERS_READ: Read orders
            ORDERS_WRITE: Write orders
            CUSTOMERS_READ: Read customers
            CUSTOMERS_WRITE: Write customers
x-generated-from: documentation
x-source-url: https://developer.squareup.com/reference/square