---
title: "Get or Create Customer"
openapi: "openapi POST /v1/customers.getOrCreate"
---

import { DynamicParamField } from "/components/dynamic-param-field.jsx";
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";

<Note>
  If the customer already exists and you try to create it again, you will simply be returned the customer object (rather than an error being thrown).
</Note>

### Body Parameters

<DynamicParamField body="customer_id" type="string | null" required>
  Your unique identifier for the customer
</DynamicParamField>

<DynamicParamField body="name" type="string | null">
  Customer's name
</DynamicParamField>

<DynamicParamField body="email" type="string | null">
  Customer's email address
</DynamicParamField>

<DynamicParamField body="fingerprint" type="string | null">
  Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
</DynamicParamField>

<DynamicParamField body="metadata" type="object | null">
  Additional metadata for the customer
</DynamicParamField>

<DynamicParamField body="stripe_id" type="string | null">
  Stripe customer ID if you already have one
</DynamicParamField>

<DynamicParamField body="create_in_stripe" type="boolean">
  Whether to create the customer in Stripe
</DynamicParamField>

<DynamicParamField body="auto_enable_plan_id" type="string">
  The ID of the free plan to auto-enable for the customer
</DynamicParamField>

<DynamicParamField body="send_email_receipts" type="boolean">
  Whether to send email receipts to this customer
</DynamicParamField>

<DynamicParamField body="expand" type="enum[]">
  Customer expand options
</DynamicParamField>


### Response

<DynamicResponseField name="name" type="string | null">
  The name of the customer.
</DynamicResponseField>

<DynamicResponseField name="email" type="string | null">
  The email address of the customer.
</DynamicResponseField>

<DynamicResponseField name="fingerprint" type="string | null">
  A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
</DynamicResponseField>

<DynamicResponseField name="stripe_id" type="string | null">
  Stripe customer ID.
</DynamicResponseField>

<DynamicResponseField name="env" type="'sandbox' | 'live'">
  The environment this customer was created in.
</DynamicResponseField>

<DynamicResponseField name="metadata" type="object">
  The metadata for the customer.
</DynamicResponseField>

<DynamicResponseField name="send_email_receipts" type="boolean">
  Whether to send email receipts to the customer.
</DynamicResponseField>

<DynamicResponseField name="subscriptions" type="object[]">
  <Expandable title="properties">
    <DynamicResponseField name="plan" type="object">
      <Expandable title="properties">
        <DynamicResponseField name="name" type="string" />

        <DynamicResponseField name="description" type="string | null" />

        <DynamicResponseField name="group" type="string | null" />

        <DynamicResponseField name="version" type="number" />

        <DynamicResponseField name="add_on" type="boolean" />

        <DynamicResponseField name="auto_enable" type="boolean" />

        <DynamicResponseField name="price" type="object | null">
          <Expandable title="properties">
            <DynamicResponseField name="amount" type="number" />

            <DynamicResponseField name="interval" type="enum" />

            <DynamicResponseField name="interval_count" type="number" />

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="items" type="object[]">
          <Expandable title="properties">
            <DynamicResponseField name="feature_id" type="string" />

            <DynamicResponseField name="included" type="number" />

            <DynamicResponseField name="unlimited" type="boolean" />

            <DynamicResponseField name="reset" type="object | null">
              <Expandable title="properties">
                <DynamicResponseField name="interval" type="enum" />

                <DynamicResponseField name="interval_count" type="number" />

              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="price" type="object | null">
              <Expandable title="properties">
                <DynamicResponseField name="amount" type="number" />

                <DynamicResponseField name="tiers" type="object[]">
                  <Expandable title="properties">
                    <DynamicResponseField name="to" type="number" />

                    <DynamicResponseField name="amount" type="number" />

                  </Expandable>
                </DynamicResponseField>

                <DynamicResponseField name="interval" type="enum" />

                <DynamicResponseField name="interval_count" type="number" />

                <DynamicResponseField name="billing_units" type="number" />

                <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'" />

                <DynamicResponseField name="max_purchase" type="number | null" />

              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="rollover" type="object">
              <Expandable title="properties">
                <DynamicResponseField name="max" type="number | null" />

                <DynamicResponseField name="expiry_duration_type" type="'month' | 'forever'" />

                <DynamicResponseField name="expiry_duration_length" type="number" />

              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="proration" type="object">
              <Expandable title="properties">
                <DynamicResponseField name="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" />

                <DynamicResponseField name="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" />

              </Expandable>
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="free_trial" type="object">
          <Expandable title="properties">
            <DynamicResponseField name="duration_length" type="number" />

            <DynamicResponseField name="duration_type" type="'day' | 'month' | 'year'" />

            <DynamicResponseField name="card_required" type="boolean" />

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="env" type="'sandbox' | 'live'" />

        <DynamicResponseField name="archived" type="boolean" />

        <DynamicResponseField name="base_variant_id" type="string | null" />

        <DynamicResponseField name="customer_eligibility" type="object">
          <Expandable title="properties">
            <DynamicResponseField name="trial_available" type="boolean" />

            <DynamicResponseField name="scenario" type="enum" />

          </Expandable>
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="plan_id" type="string" />

    <DynamicResponseField name="auto_enable" type="boolean" />

    <DynamicResponseField name="add_on" type="boolean" />

    <DynamicResponseField name="status" type="'active' | 'scheduled' | 'expired'" />

    <DynamicResponseField name="past_due" type="boolean" />

    <DynamicResponseField name="canceled_at" type="number | null" />

    <DynamicResponseField name="expires_at" type="number | null" />

    <DynamicResponseField name="trial_ends_at" type="number | null" />

    <DynamicResponseField name="started_at" type="number" />

    <DynamicResponseField name="current_period_start" type="number | null" />

    <DynamicResponseField name="current_period_end" type="number | null" />

    <DynamicResponseField name="quantity" type="number" />

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="purchases" type="object[]">
  <Expandable title="properties">
    <DynamicResponseField name="plan" type="object">
      <Expandable title="properties">
        <DynamicResponseField name="name" type="string" />

        <DynamicResponseField name="description" type="string | null" />

        <DynamicResponseField name="group" type="string | null" />

        <DynamicResponseField name="version" type="number" />

        <DynamicResponseField name="add_on" type="boolean" />

        <DynamicResponseField name="auto_enable" type="boolean" />

        <DynamicResponseField name="price" type="object | null">
          <Expandable title="properties">
            <DynamicResponseField name="amount" type="number" />

            <DynamicResponseField name="interval" type="enum" />

            <DynamicResponseField name="interval_count" type="number" />

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="items" type="object[]">
          <Expandable title="properties">
            <DynamicResponseField name="feature_id" type="string" />

            <DynamicResponseField name="included" type="number" />

            <DynamicResponseField name="unlimited" type="boolean" />

            <DynamicResponseField name="reset" type="object | null">
              <Expandable title="properties">
                <DynamicResponseField name="interval" type="enum" />

                <DynamicResponseField name="interval_count" type="number" />

              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="price" type="object | null">
              <Expandable title="properties">
                <DynamicResponseField name="amount" type="number" />

                <DynamicResponseField name="tiers" type="object[]">
                  <Expandable title="properties">
                    <DynamicResponseField name="to" type="number" />

                    <DynamicResponseField name="amount" type="number" />

                  </Expandable>
                </DynamicResponseField>

                <DynamicResponseField name="interval" type="enum" />

                <DynamicResponseField name="interval_count" type="number" />

                <DynamicResponseField name="billing_units" type="number" />

                <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'" />

                <DynamicResponseField name="max_purchase" type="number | null" />

              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="rollover" type="object">
              <Expandable title="properties">
                <DynamicResponseField name="max" type="number | null" />

                <DynamicResponseField name="expiry_duration_type" type="'month' | 'forever'" />

                <DynamicResponseField name="expiry_duration_length" type="number" />

              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="proration" type="object">
              <Expandable title="properties">
                <DynamicResponseField name="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" />

                <DynamicResponseField name="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" />

              </Expandable>
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="free_trial" type="object">
          <Expandable title="properties">
            <DynamicResponseField name="duration_length" type="number" />

            <DynamicResponseField name="duration_type" type="'day' | 'month' | 'year'" />

            <DynamicResponseField name="card_required" type="boolean" />

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="env" type="'sandbox' | 'live'" />

        <DynamicResponseField name="archived" type="boolean" />

        <DynamicResponseField name="base_variant_id" type="string | null" />

        <DynamicResponseField name="customer_eligibility" type="object">
          <Expandable title="properties">
            <DynamicResponseField name="trial_available" type="boolean" />

            <DynamicResponseField name="scenario" type="enum" />

          </Expandable>
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="plan_id" type="string" />

    <DynamicResponseField name="expires_at" type="number | null" />

    <DynamicResponseField name="started_at" type="number" />

    <DynamicResponseField name="quantity" type="number" />

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="balances" type="object" />

<DynamicResponseField name="invoices" type="object[]">
  <Expandable title="properties">
    <DynamicResponseField name="plan_ids" type="string[]">
      Array of plan IDs included in this invoice
    </DynamicResponseField>

    <DynamicResponseField name="stripe_id" type="string">
      The Stripe invoice ID
    </DynamicResponseField>

    <DynamicResponseField name="status" type="string">
      The status of the invoice
    </DynamicResponseField>

    <DynamicResponseField name="total" type="number">
      The total amount of the invoice
    </DynamicResponseField>

    <DynamicResponseField name="currency" type="string">
      The currency code for the invoice
    </DynamicResponseField>

    <DynamicResponseField name="hosted_invoice_url" type="string | null">
      URL to the Stripe-hosted invoice page
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="entities" type="object[]">
  <Expandable title="properties">
    <DynamicResponseField name="name" type="string | null">
      The name of the entity
    </DynamicResponseField>

    <DynamicResponseField name="customer_id" type="string | null">
      The customer ID this entity belongs to
    </DynamicResponseField>

    <DynamicResponseField name="feature_id" type="string | null">
      The feature ID this entity belongs to
    </DynamicResponseField>

    <DynamicResponseField name="env" type="'sandbox' | 'live'">
      The environment (sandbox/live)
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="trials_used" type="object[]">
  <Expandable title="properties">
    <DynamicResponseField name="plan_id" type="string" />

    <DynamicResponseField name="customer_id" type="string" />

    <DynamicResponseField name="fingerprint" type="string | null" />

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="rewards" type="object | null">
  <Expandable title="properties">
    <DynamicResponseField name="discounts" type="object[]">
      Array of active discounts applied to the customer
      <Expandable title="properties">
        <DynamicResponseField name="name" type="string">
          The name of the discount or coupon
        </DynamicResponseField>

        <DynamicResponseField name="type" type="'percentage_discount' | 'fixed_discount' | 'free_product' | 'invoice_credits'">
          The type of reward
        </DynamicResponseField>

        <DynamicResponseField name="discount_value" type="number">
          The discount value (percentage or fixed amount)
        </DynamicResponseField>

        <DynamicResponseField name="duration_type" type="'one_off' | 'months' | 'forever'">
          How long the discount lasts
        </DynamicResponseField>

        <DynamicResponseField name="duration_value" type="number | null">
          Number of billing periods the discount applies for repeating durations
        </DynamicResponseField>

        <DynamicResponseField name="currency" type="string | null">
          The currency code for fixed amount discounts
        </DynamicResponseField>

        <DynamicResponseField name="start" type="number | null">
          Timestamp when the discount becomes active
        </DynamicResponseField>

        <DynamicResponseField name="end" type="number | null">
          Timestamp when the discount expires
        </DynamicResponseField>

        <DynamicResponseField name="subscription_id" type="string | null">
          The Stripe subscription ID this discount is applied to
        </DynamicResponseField>

        <DynamicResponseField name="total_discount_amount" type="number | null">
          Total amount saved from this discount
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="referrals" type="object[]">
  <Expandable title="properties">
    <DynamicResponseField name="program_id" type="string" />

    <DynamicResponseField name="customer" type="object">
      <Expandable title="properties">
        <DynamicResponseField name="name" type="string | null" />

        <DynamicResponseField name="email" type="string | null" />

      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="reward_applied" type="boolean" />

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="payment_method" type="any | null" />