> ## 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.

# Create customer

> Required scope: `partner.customers.write`. The optional `partner.customers.pii` scope controls response PII field population; without it the created customer is returned with PII fields as `null`.



## OpenAPI

````yaml /api-reference/openapi.json post /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:
    post:
      tags:
        - Customers
      summary: Create customer
      description: >-
        Required scope: `partner.customers.write`. The optional
        `partner.customers.pii` scope controls response PII field population;
        without it the created customer is returned with PII fields as `null`.
      operationId: partner.v1.customers.store
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type:
                    - string
                    - 'null'
                  maxLength: 255
                last_name:
                  type:
                    - string
                    - 'null'
                  maxLength: 255
                company_name:
                  type:
                    - string
                    - 'null'
                  maxLength: 255
                email:
                  type:
                    - string
                    - 'null'
                  maxLength: 1000
                phone:
                  type:
                    - string
                    - 'null'
                  maxLength: 50
                address:
                  type: object
                  properties:
                    address_line_one:
                      type: string
                      maxLength: 255
                    address_line_two:
                      type:
                        - string
                        - 'null'
                      maxLength: 255
                    address_line_three:
                      type:
                        - string
                        - 'null'
                      maxLength: 255
                    town:
                      type:
                        - string
                        - 'null'
                      maxLength: 255
                    county:
                      type:
                        - string
                        - 'null'
                      maxLength: 255
                    postcode:
                      type:
                        - string
                        - 'null'
                      maxLength: 255
                    country:
                      type: string
                      maxLength: 255
                  required:
                    - address_line_one
                    - country
              description: >-
                Provide a person name (first_name and last_name) or
                company_name, and at least one contact channel (email or phone).
                When address is present, address_line_one and country are
                required, and postcode is required unless country is IE.
      responses:
        '201':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                success:
                  summary: Example response
                  value:
                    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'
                with_pii:
                  summary: With partner.customers.pii
                  value:
                    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'
        '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.
        '409':
          description: A customer already exists for the supplied email address.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: duplicate_customer
                  message:
                    type: string
                    example: A customer already exists for the supplied email address.
                  existing_customer_id:
                    type: integer
                    example: 101
                required:
                  - error
                  - message
                  - existing_customer_id
        '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:
    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

````