---
title: "Create customer"
method: POST
path: "/stores/{storeId}/customers"
tags: ["Customer"]
---

# Create customer

`POST /stores/{storeId}/customers`

Registers a customer for the store using their email.
If the customer already exists and is linked to the store, a 409 conflict is returned.
Requires the `stores.customers.create` permission.

## Path parameters

- `storeId` string, uuid, required

## Request body

- CreateCustomerForm — Represents a form for creating customer data, inheriting email validation functionality.
  - `emailAddress` string, email, required — Represents the email address associated with the form.

## Response `200`

The object was successfully created.

- CustomerResponse — Represents a default generic response for API endpoints.
  - `success` boolean, required — Indicates whether the operation or response was successful.
  - `message` string, nullable — A descriptive message providing additional context or information about the response.
  - `code` string, nullable — The error code (if there was an error) to use when referencing the error
  - `data` Customer — Represents a customer registered at Komerza globally
    - `id` string, uuid, required — The unique identifier of the entity
    - `dateCreated` string, date-time, required — The date the entity was created in the database
    - `emailAddress` string, required — Represents the email address of the customer
    - `ipAddress` string, required — Represents the IP address associated with the customer.
    - `storeData` CustomerStoreData[], required — The list of store-scoped data for the customer
      - `id` string, uuid, required — The unique identifier of the entity
      - `dateCreated` string, date-time, required — The date the entity was created in the database
      - `balance` number, double, required — The customer balance, this can be used to buy items on the store with
      - `affiliate` StoreAffiliate — Represents an affiliate associated with a store.
        - `id` string, uuid, required — The unique identifier of the entity
        - `dateCreated` string, date-time, required — The date the entity was created in the database
        - `storeId` string, uuid, required — Unique identifier for the store associated with the affiliate
        - `customerId` string, uuid, required — Unique identifier for the customer associated with the affiliate
        - `isEnabled` boolean, required — Indicates whether the store is affiliated with a user
        - `link` string, required — A link provided to affiliates for tracking and promotional purposes.
        - `returnPercentage` integer, nullable — The percentage of the return that an affiliate receives
        - `percentageOff` integer, nullable — The percentage discount offered by the store affiliate
        - `balance` number, double, required — Represents the balance of the affiliate, typically indicating the amount earned through affiliations.
      - `externalIntegrations` ExternalIntegration[], required — The list of external integrations linked to this customer
        - `id` string, uuid, required — The unique identifier of the entity
        - `dateCreated` string, date-time, required — The date the entity was created in the database
        - `accountId` string, required — The users account identifier, used to identify the account on the platform
        - `platformId` string, required — The ID of the platform which the integration is for
        - `expirationDate` string, date-time, nullable — The date the access token expires
      - `tickets` Ticket[], required — The list of tickets created by the customer
        - `id` string, uuid, required — The unique identifier of the entity
        - `dateCreated` string, date-time, required — The date the entity was created in the database
        - `subject` string, required — Gets or sets the subject or title of the ticket, summarizing the issue or request.
        - `status` 0 | 1 | 2 | 3 | 4, required — The different states of the ticket
        - `customerId` string, uuid, required — The customer who opened the ticket
        - `userId` string, required — The user who owns the store the ticket was made in
        - `storeId` string, uuid, required — The store which the ticket is for
        - `entries` TicketEntry[], required — Gets or sets the list of entries or messages associated with the ticket. These entries represent the conversation or updates related to the ticket.
          - `id` string, uuid, required — The unique identifier of the entity
          - `dateCreated` string, date-time, required — The date the entity was created in the database
          - `name` string, required — The name of the user that posted the entry
          - `message` string, required — The message the user has posted to the ticket
          - `ticketId` string, uuid, required — The ID of the ticket
      - `subscriptions` CustomerSubscription[], required — The list of subscriptions the customer has
        - `id` string, uuid, required — The unique identifier of the entity
        - `dateCreated` string, date-time, required — The date the entity was created in the database
        - `customerId` string, uuid, required — The ID of the customer who owns this subscription
        - `customerStoreDataId` string, uuid, required — The ID of the customer's store-scoped data
        - `storeId` string, uuid, required — The ID of the store this subscription belongs to
        - `productId` string, uuid, required — The ID of the product being subscribed to
        - `variantId` string, uuid, required — The ID of the specific variant being subscribed to
        - `status` 0 | 1 | 2 | 3 | 4, required — The status of a customer subscription
        - `billingInterval` 0 | 1 | 2 | 3 | 4, required — The billing interval for a subscription product
        - `customIntervalDays` integer, nullable — Custom interval in days when Komerza.Database.Entities.Customers.CustomerSubscription.BillingInterval is !:Products.BillingInterval.Custom
        - `price` number, double, required — The price charged per billing interval
        - `currencyCode` string, required — The ISO 4217 currency code for the subscription price
        - `currentPeriodStart` string, date-time, required — The start of the current billing period
        - `currentPeriodEnd` string, date-time, required — The end of the current billing period
        - `cancelAtPeriodEnd` boolean, required — Whether this subscription should be canceled at the end of the current billing period
        - `canceledAt` string, date-time, nullable — The date the subscription was canceled, if applicable
        - `pausedAt` string, date-time, nullable — The date the subscription was paused, if applicable
        - `pauseResumeDate` string, date-time, nullable — The date the subscription should be automatically resumed. Null means indefinite pause (until manual resume).
        - `pauseCount` integer, required — The total number of times this subscription has been paused over its lifetime
        - `gateway` string, required — The payment gateway handling this subscription (e.g., "stripe", "mollie", "square")
        - `gatewaySubscriptionId` string, nullable — The subscription ID within the external payment gateway
        - `gatewayCustomerId` string, nullable — The customer ID within the external payment gateway (denormalized for quick lookups)
        - `autoRenew` boolean, required — Whether this subscription auto-renews through the payment gateway. False for gateways that don't support native recurring billing.
        - `failedPaymentCount` integer, required — The number of consecutive failed payment attempts
        - `lastPaymentFailureDate` string, date-time, nullable — The date of the most recent payment failure
        - `nextRetryDate` string, date-time, nullable — The next scheduled retry date for a failed payment (exponential backoff)
        - `lastReminderSentAt` string, date-time, nullable — The date the last renewal reminder was sent to the customer
        - `metadataJson` string, nullable — Gateway-specific metadata stored as JSON
      - `gatewayCustomerIds` object, required — Gateway-specific customer IDs, keyed by payment method name (e.g. "stripe", "mollie").
      - `stripeCustomerId` string, nullable — The ID of the Stripe customer for the customer
      - `mollieCustomerId` string, nullable — The ID of the Mollie customer for the customer
      - `storeId` string, uuid, required — The ID the customer data is associated with
      - `customerId` string, uuid, required — The ID of the customer the data belongs to
      - `customer` Customer, required — recursive
      - `marketingOptions` EmailMarketingCustomerOptions — The user-defined configuration for customer email marketing
        - `id` string, uuid, required — The unique identifier of the entity
        - `dateCreated` string, date-time, required — The date the entity was created in the database
        - `isEnabled` boolean, required — Whether the customer has opted-in to recieve marketing communications or not from the store
        - `disabledAt` string, date-time, nullable — The date the customer opted out of email marketing
        - `consentSource` string, nullable — How consent was obtained (e.g. "checkout", "import", "manual")
        - `consentTimestamp` string, date-time, nullable — When the customer gave or refused marketing consent
        - `consentIpAddress` string, nullable — The IP address of the customer at the time consent was recorded
        - `consentWithdrawnAt` string, date-time, nullable — When the customer withdrew their marketing consent (unsubscribed)
        - `customerId` string, uuid, required — The ID of the customer this belongs to
        - `customerStoreDataId` string, uuid, required — The ID of the CSD this belongs to
      - `isBlocked` boolean, required — Whether this customer is blocked from purchasing on this store.
      - `blockedNote` string, nullable — An optional note explaining why the customer was blocked.
      - `blockedAt` string, date-time, nullable — The date the customer was blocked, if applicable.
      - `ipAddress` string, required — Represents the IP address the customer created the store data with.

## Other responses

- `400` — The provided form information is not valid, check that the provided data is valid. You can use the 'invalidFields' field to get the list of invalid fields or just use the 'message' field.
- `409` — Customer already exists

---

[API](https://skmtc.net/komerza/apis/komerza-api.md) · [All operations](https://skmtc.net/komerza/apis/komerza-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/komerza/komerza-api/revisions/060e78bc7f80/schema)