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

# Customers

<AccordionGroup>
  <Accordion title="What is the difference between a 'Customer' and a 'Guest' in Subotiz?">
    Subotiz automatically assigns customer type based on what is in the cart at checkout:

    * **Customer** — created when the cart includes at least one subscription product.
    * **Guest** — created when the cart includes only one-time purchases.

    This distinction is important because it affects how the profile is managed — subscription-related billing, contract IDs, and renewal records are linked to Customer profiles. If a Guest later purchases a subscription using the same identifier such as email address, Subotiz automatically upgrades the profile to a Customer type while retaining the original Customer ID.
  </Accordion>

  <Accordion title="How does Subotiz decide whether to create a new customer profile or reuse an existing one?">
    Subotiz applies a priority-based matching logic to determine whether to reuse an existing profile or create a new one. The system checks identifiers in this order:

    1. **Subotiz Customer ID** — if a valid match exists, it is used directly and contact fields become read-only at checkout.
    2. **External Customer ID** — if no Customer ID match is found, the system checks for a matching External Customer ID.
    3. **Email address** — if neither of the above match, the system checks the email address.

    A new profile is created only if an External Customer ID or email address is provided and no existing profile matches. If only a Subotiz Customer ID is provided and no match is found, no new profile is created.
  </Accordion>

  <Accordion title="What is the External Customer ID and when should I use it?">
    The External Customer ID is an optional identifier that merchants can assign to customer profiles when syncing data from external systems such as a CRM or ERP. It allows you to maintain a consistent reference between Subotiz and your own systems. It is used as a secondary matching identifier — if a Subotiz Customer ID is not provided, the system will check for a matching External Customer ID before trying the email address. It is also the only identifier that can substitute for email when a customer does not have an email address. The External Customer ID must be unique across all customers in the same Subotiz account.
  </Accordion>

  <Accordion title="If a customer previously bought a one-time product as a guest, will they get a new profile when they subscribe later?">
    No, as long as they use the same identifier such as email address. When a guest later purchases a subscription using the same identifier, Subotiz automatically upgrades the existing Guest profile to a Customer profile rather than creating a new one. During this upgrade:

    * the original Customer ID is retained.
    * the customer type is updated to Customer.
    * any missing fields such as name or address are automatically populated when new data becomes available.

    This prevents duplicate profiles and keeps all purchase history consolidated under the same record.
  </Accordion>

  <Accordion title="What file formats and size limits apply to customer import?">
    Customer import in Subotiz supports two file formats: .xlsx and .csv. Files in any other format cannot be imported. The file size must not exceed 10 MB. Additionally, column headers in the template must not be modified or reordered — the system cannot process files where headers have been changed. All fields must be filled according to the required format. If any records fail validation, they are skipped or flagged in the import results, and a detailed error file can be downloaded to identify and correct the issues before reimporting.
  </Accordion>

  <Accordion title="If I import a customer file and the email already exists, will it overwrite or skip the existing record?">
    The behavior depends on whether you enable the overwrite option during the import:

    * **If Overwrite is enabled** — when the imported record matches an existing customer by email or External Customer ID, Subotiz updates the existing profile using the imported data. Empty fields in the import file will not overwrite existing values — only non-empty fields are updated.
    * **If Overwrite is disabled** — any imported record that matches an existing customer is skipped entirely and no changes are made to the existing profile.

    New records without a match are always created regardless of this setting.
  </Accordion>

  <Accordion title="I closed the import dialog while it was processing — did it cancel the import?">
    No. Closing the import dialog does not cancel or interrupt the import process. The system continues processing the file in the background. Once the import is complete, a notification is sent to the message center with the results. From there you can review successfully imported records, failed records, and skipped records, and download the error file if needed. If you need to check the result later, go to the message center or notification area to access the import summary.
  </Accordion>

  <Accordion title="Can I delete a customer who still has active subscriptions?">
    No. If a customer has any active or unfinished subscriptions, deletion is not allowed. The system will prompt you to cancel those subscriptions first before the customer profile can be deleted. Once all active subscriptions are canceled, the deletion can be confirmed. After deletion, the customer profile is permanently removed and cannot be restored. All associated data will no longer be accessible.
  </Accordion>

  <Accordion title="What is custom data on a customer profile and how is it different from the customer's contact information?">
    Custom data is a separate section on the customer profile that stores merchant-defined extension fields for internal reference or external system mapping, such as internal IDs, business tags, or integration keys. Each profile supports up to 40 key-value pairs of custom data. Custom data is informational only — it is not used for customer identification or profile matching, and it does not appear on invoices or affect billing in any way. Contact information such as name, email, and address is used for billing, invoice generation, and checkout pre-fill. Custom data is purely for internal business use.
  </Accordion>

  <Accordion title="How can I find a specific customer quickly when I only have their invoice ID or trade order ID?">
    The customer list search supports Email, Customer ID, and External Customer ID only. However, each customer detail page consolidates all related subscriptions, invoices, and billing records in one place. If you only have an invoice ID or trade order ID, the most efficient path is to search for the invoice or trade order in the Invoices or Trade orders module first, then click through to the linked customer profile from the invoice or order detail page. Alternatively, if you know the customer's email, search directly from the customer list.
  </Accordion>

  <Accordion title="Can a customer have more than one subscription under the same profile?">
    Yes. A single customer profile can be linked to multiple subscription contract IDs, supporting scenarios where a customer subscribes to multiple products or pricing plans. Each subscription contract ID represents a distinct subscription relationship. All subscription records are visible in the Subscriptions section of the customer detail page, where you can see each contract's product name, billing cycle, created date, and Subscription ID. Clicking any Subscription ID opens the full subscription details.
  </Accordion>

  <Accordion title="Can I edit a customer's email address after the profile has been created?">
    The Customer ID is system-generated and cannot be edited. For other fields such as name, address, and email subscription status, these can be updated by opening the customer detail page and clicking Edit in the Basic information section. Email address is optional in Subotiz — if provided, it must be unique within the account. When an existing Customer ID is used during checkout, the contact fields including name and email become read-only in that session, as the system pre-fills data from the existing profile. To update customer information outside of checkout, use the Edit function directly on the customer detail page.
  </Accordion>

  <Accordion title="What is the email subscription field on a customer profile and how is it captured?">
    The email subscription field on a customer profile indicates whether the customer has opted in to receive marketing or service-related emails. This field is captured during the checkout process when the customer interacts with the marketing subscription checkbox, or through an API sync when customer data is imported from an external system. Merchants can use this field to filter customers by their communication preferences in the admin — for example, filtering to view only customers who have opted in before sending marketing campaigns. This field can also be viewed and updated in the customer detail page.
  </Accordion>

  <Accordion title="What customer information does Subotiz automatically collect during checkout?">
    When a customer profile is created during checkout, Subotiz automatically collects available information from the checkout form, payment method, or API request:

    * **Email** — collected from the checkout form or passed via API.
    * **Name** — pulled from the payment method such as the credit card name or PayPal account name.
    * **Phone** — optional and collected from the checkout form or API.
    * **Address** — optional and collected from the payment method or API.
    * **Custom data (Metadata)** — optional and passed via API.

    As long as at least one valid identifier is provided, the system creates the profile and automatically populates fields from available sources.
  </Accordion>

  <Accordion title="In the customer import template, which field is used as the unique identifier — email or External Customer ID?">
    By default, email is used as the unique customer identifier in the import template. If a customer does not have an email address, External Customer ID can be used as the identifier instead. When using External Customer ID as the identifier, the email field can be left empty. Both email and External Customer ID must be unique across all customers — duplicate values across different records will cause import failures. You cannot use both as identifiers for the same record simultaneously; one takes precedence based on availability.
  </Accordion>

  <Accordion title="After a customer import completes, how do I find out which records failed and why?">
    After the import completes, Subotiz displays a summary showing the count of successfully imported records, failed records, and skipped records. If any records failed, click Failed records to download a detailed error file. This file identifies the specific records that could not be imported and the reason for each failure. Review and correct the issues in the file, then re-import only the corrected records. If you closed the import dialog before the task completed, the results and failed records download will be available from the Notifications or message center once the task finishes.
  </Accordion>

  <Accordion title="How can I filter customers to find only those who have subscriptions versus those who only made one-time purchases?">
    In the Customers section of the Subotiz admin, use the Type filter to separate customers by their assigned type:

    * **Customer** — view profiles with at least one subscription product.
    * **Guest** — view profiles that only have one-time purchases.

    You can also combine the Type filter with the Email subscription filter to further narrow results — for example, to find subscription customers who have opted in to marketing emails. These filters help quickly identify different customer segments for operational or communication purposes.
  </Accordion>

  <Accordion title="Can I add custom data to a customer profile after it has been created, and what is the limit?">
    Yes. Custom data can be added or updated at any time from the customer detail page. Click Edit in the Custom data section, then select Add custom data to add key-value pairs. Each customer profile supports up to 40 custom data fields. Existing custom data can also be updated at any time. Custom data is informational only — it is not used for customer identification, profile matching, or billing in any way. It is purely for internal reference such as storing business tags, internal IDs, or external system mapping information.
  </Accordion>
</AccordionGroup>