> ## Documentation Index
> Fetch the complete documentation index at: https://docs.florists.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# List customers

> Required scope: `partner.customers.read`. The optional `partner.customers.pii` scope only controls PII field population; without it customer name, first name, last name, company name, email, phone, and address are returned as `null`.



## OpenAPI

````yaml /api-reference/openapi.json get /customers
openapi: 3.1.0
info:
  title: Digital Florists Partner API
  version: v1
  description: >-
    Orders, customers and products (reads plus customer creation) and outbound
    webhooks. Bearer authentication; per-shop base URL.
servers:
  - url: https://{shop_domain}/api/partner/v1
    description: Shop
    variables:
      shop_domain:
        default: your-shop.example
security:
  - bearerAuth: []
paths:
  /customers:
    get:
      tags:
        - Customers
      summary: List customers
      description: >-
        Required scope: `partner.customers.read`. The optional
        `partner.customers.pii` scope only controls PII field population;
        without it customer name, first name, last name, company name, email,
        phone, and address are returned as `null`.
      operationId: partner.v1.customers.index
      parameters:
        - name: filter[updated_since]
          in: query
          schema:
            type: string
            format: date-time
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: Page size. Values above the maximum are clamped.
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A page of customers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerList'
              examples:
                success:
                  summary: Example response
                  value:
                    data:
                      - type: customer
                        id: 101
                        name: null
                        first_name: null
                        last_name: null
                        company_name: null
                        email: null
                        phone: null
                        address: null
                        created_at: '2026-06-27T10:15:00+01:00'
                        updated_at: '2026-06-27T10:20:00+01:00'
                    links:
                      next: >-
                        https://your-shop.example/api/partner/v1/customers?cursor=eyJleGFtcGxlIjp0cnVlfQ
                      prev: null
                    meta:
                      per_page: 25
                      has_more: true
                with_pii:
                  summary: With partner.customers.pii
                  value:
                    data:
                      - type: customer
                        id: 101
                        name: Ada Lovelace
                        first_name: Ada
                        last_name: Lovelace
                        company_name: Analytical Flowers Ltd
                        email: ada@example.com
                        phone: '+441612345678'
                        address:
                          address_line_one: 10 Example Street
                          address_line_two: null
                          address_line_three: null
                          town: Manchester
                          county: null
                          postcode: M1 1AE
                          country: GB
                        created_at: '2026-06-27T10:15:00+01:00'
                        updated_at: '2026-06-27T10:20:00+01:00'
                    links:
                      next: >-
                        https://your-shop.example/api/partner/v1/customers?cursor=eyJleGFtcGxlIjp0cnVlfQ
                      prev: null
                    meta:
                      per_page: 25
                      has_more: true
        '401':
          $ref: '#/components/responses/AuthenticationException'
          description: >-
            Authentication failed, or the token is missing, invalid, expired, or
            revoked.
        '403':
          $ref: '#/components/responses/ForbiddenError'
          description: >-
            The token lacks the required scope, or API access is not enabled for
            this shop.
        '422':
          $ref: '#/components/responses/ValidationException'
          description: The request failed validation.
        '429':
          $ref: '#/components/responses/RateLimitError'
          description: >-
            Rate limit exceeded. Retry after the period given in the Retry-After
            header.
        '500':
          $ref: '#/components/responses/ServerError'
          description: An unexpected server error occurred.
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
          description: The partner API is temporarily disabled. Retry later.
      security:
        - bearerAuth: []
components:
  schemas:
    CustomerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
        links:
          type: object
          properties:
            next:
              type:
                - string
                - 'null'
            prev:
              type:
                - string
                - 'null'
          required:
            - next
            - prev
        meta:
          type: object
          properties:
            per_page:
              type: integer
              minimum: 1
              maximum: 100
            has_more:
              type: boolean
          required:
            - per_page
            - has_more
      required:
        - data
        - links
        - meta
      title: CustomerList
      example:
        data:
          - type: customer
            id: 101
            name: null
            first_name: null
            last_name: null
            company_name: null
            email: null
            phone: null
            address: null
            created_at: '2026-06-27T10:15:00+01:00'
            updated_at: '2026-06-27T10:20:00+01:00'
        links:
          next: >-
            https://your-shop.example/api/partner/v1/orders?cursor=eyJleGFtcGxlIjp0cnVlfQ
          prev: null
        meta:
          per_page: 25
          has_more: true
    Customer:
      type: object
      properties:
        type:
          type: string
          enum:
            - customer
            - contact
          example: customer
        id:
          type: integer
          example: 101
        name:
          type:
            - string
            - 'null'
          description: Null unless the token also has partner.customers.pii.
          example: null
        first_name:
          type:
            - string
            - 'null'
          description: Null unless the token also has partner.customers.pii.
          example: null
        last_name:
          type:
            - string
            - 'null'
          description: Null unless the token also has partner.customers.pii.
          example: null
        company_name:
          type:
            - string
            - 'null'
          description: Null unless the token also has partner.customers.pii.
          example: null
        email:
          type:
            - string
            - 'null'
          description: >-
            One or more email addresses, semicolon-separated when multiple. Null
            unless the token also has partner.customers.pii.
          example: null
        phone:
          type:
            - string
            - 'null'
          description: Null unless the token also has partner.customers.pii.
          example: null
        address:
          anyOf:
            - type: object
              properties:
                address_line_one:
                  type:
                    - string
                    - 'null'
                  example: 10 Example Street
                address_line_two:
                  type:
                    - string
                    - 'null'
                  example: null
                address_line_three:
                  type:
                    - string
                    - 'null'
                  example: null
                town:
                  type:
                    - string
                    - 'null'
                  example: Manchester
                county:
                  type:
                    - string
                    - 'null'
                  example: null
                postcode:
                  type:
                    - string
                    - 'null'
                  example: M1 1AE
                country:
                  type:
                    - string
                    - 'null'
                  example: GB
              required:
                - address_line_one
                - address_line_two
                - address_line_three
                - town
                - county
                - postcode
                - country
            - type: 'null'
          description: Null unless the token also has partner.customers.pii.
        created_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-06-27T10:15:00+01:00'
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-06-27T10:20:00+01:00'
      required:
        - type
        - id
        - name
        - first_name
        - last_name
        - company_name
        - email
        - phone
        - address
        - created_at
        - updated_at
      title: Customer
      example:
        type: customer
        id: 101
        name: null
        first_name: null
        last_name: null
        company_name: null
        email: null
        phone: null
        address: null
        created_at: '2026-06-27T10:15:00+01:00'
        updated_at: '2026-06-27T10:20:00+01:00'
  responses:
    AuthenticationException:
      description: Unauthenticated
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
            required:
              - error
              - message
    ForbiddenError:
      description: >-
        The token lacks the required scope, or API access is not enabled for
        this shop.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
            required:
              - error
              - message
    ValidationException:
      description: The request failed validation.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable validation overview.
              errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
                description: Validation messages keyed by request field.
            required:
              - error
              - message
              - errors
    RateLimitError:
      description: >-
        Rate limit exceeded. Retry after the period given in the Retry-After
        header.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
              retry_after:
                type:
                  - integer
                  - 'null'
                description: Seconds to wait before retrying.
            required:
              - error
              - message
              - retry_after
    ServerError:
      description: An unexpected server error occurred.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
            required:
              - error
              - message
    ServiceUnavailableError:
      description: The partner API is temporarily disabled. Retry later.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Stable machine-readable error code.
              message:
                type: string
                description: Human-readable error overview.
            required:
              - error
              - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````