> ## Documentation Index > Fetch the complete documentation index at: https://docs.withflex.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or update a customer > Creates a customer. This endpoint upserts by email: if a customer with the same email already exists, that customer is updated with the supplied values instead of a new one being created. A `customer.created` webhook event is fired only when a new customer is created (not on update). If `checkout_session_id` is provided, the referenced checkout session is updated to reference this customer. ## OpenAPI ````yaml /openapi.json post /v1/customers openapi: 3.1.0 info: title: Flex API description: >- The Flex API powers HSA/FSA payment processing for healthcare commerce: checkout sessions, payment intents, subscriptions, customers, refunds, disputes, and eligibility. Authenticate with your partner API key as a Bearer token. All endpoints are scoped to your partner account, and test mode is fully supported via test API keys. version: 0.1.0 servers: - url: https://api.withflex.com security: - BearerAuth: [] tags: - name: Balance Transactions - name: Captures - name: Checkout Sessions - name: Coupons - name: Customers - name: Disputes - name: Events - name: Exports - name: Files - name: Invoices - name: Letters - name: Orders - name: Payment Intents - name: Payment Links - name: Payouts - name: Prices - name: Products - name: Promo Codes - name: Receipts - name: Refunds - name: Setup Intents - name: Shipping Rates - name: Subscriptions paths: /v1/customers: post: tags: - Customers summary: Create or update a customer description: >- Creates a customer. This endpoint upserts by email: if a customer with the same email already exists, that customer is updated with the supplied values instead of a new one being created. A `customer.created` webhook event is fired only when a new customer is created (not on update). If `checkout_session_id` is provided, the referenced checkout session is updated to reference this customer. operationId: v1.customer.create requestBody: description: An envelope wrapping a single customer object. content: application/json: schema: $ref: '#/components/schemas/CustomerBody_for_CreateCustomerRequest' example: customer: first_name: John last_name: Doe email: joh.doe@example.com phone: '+15555555555' employer: Flex shipping: {} checkout_session_id: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA metadata: '{"key": "value"}' required: true responses: '200': description: An envelope wrapping a single customer object. content: application/json: schema: $ref: '#/components/schemas/CustomerBody_for_Customer' example: customer: customer_id: fcus_01HACM7FZ1084XB1GB6053VM0D owner_partner_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA first_name: John last_name: Doe email: joh.doe@example.com phone: '+15555555555' employer: Flex shipping: {} metadata: order_id: '8842' channel: shopify created_at: '2026-06-15T14:30:00Z' test_mode: false '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' example: detail: - loc: - string msg: string type: string '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string security: - BearerAuth: - customers:write components: schemas: CustomerBody_for_CreateCustomerRequest: description: An envelope wrapping a single customer object. type: object required: - customer properties: customer: $ref: '#/components/schemas/CreateCustomerRequest' description: The customer. example: customer: first_name: John last_name: Doe email: joh.doe@example.com phone: '+15555555555' employer: Flex shipping: {} checkout_session_id: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA metadata: '{"key": "value"}' CustomerBody_for_Customer: description: An envelope wrapping a single customer object. type: object required: - customer properties: customer: $ref: '#/components/schemas/Customer' description: The customer. example: customer: customer_id: fcus_01HACM7FZ1084XB1GB6053VM0D owner_partner_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA first_name: John last_name: Doe email: joh.doe@example.com phone: '+15555555555' employer: Flex shipping: {} metadata: order_id: '8842' channel: shopify created_at: '2026-06-15T14:30:00Z' test_mode: false HttpErrorOut: title: HttpError description: The error response returned when a request cannot be completed. type: object required: - code - detail properties: code: description: A short machine-readable error code identifying the type of error. type: string detail: description: A human-readable explanation of what went wrong. type: string example: code: string detail: string HTTPValidationError: description: The error response returned when request validation fails (HTTP 422). type: object required: - detail properties: detail: description: The list of validation errors, one entry per invalid field. type: array items: $ref: '#/components/schemas/ValidationErrorItem' example: detail: - loc: - string msg: string type: string CreateCustomerRequest: description: >- Parameters for creating a customer. If a customer with the same email already exists, that customer is updated with these values instead of a new one being created. type: object required: - email - first_name - last_name - phone properties: first_name: description: The customer's first name. type: string example: John last_name: description: The customer's last name. type: string example: Doe email: description: >- The customer's email address. Used as the natural key: a request matching an existing customer's email updates that customer rather than creating a new one. type: string format: email example: joh.doe@example.com phone: description: >- The customer's phone number. Must be a valid phone number; it is normalized to E.164 format before being stored. type: string format: phone example: '+15555555555' employer: description: The customer's employer. type: - string - 'null' example: Flex shipping: description: The customer's shipping address. anyOf: - $ref: '#/components/schemas/CreateShippingAddress' - type: 'null' checkout_session_id: description: >- ID of a CheckoutSession to associate with this customer. When provided, the checkout session's customer (and its shipping details, if a shipping address is supplied) is updated to reference this customer. type: - string - 'null' example: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA metadata: description: >- Set of key-value pairs you can attach to the customer for storing additional structured information. type: - object - 'null' additionalProperties: type: string example: '{"key": "value"}' example: first_name: John last_name: Doe email: joh.doe@example.com phone: '+15555555555' employer: Flex shipping: line1: 123 Main St line2: Suite 100 city: San Francisco state: CA postal_code: '94107' country: US checkout_session_id: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA metadata: '{"key": "value"}' Customer: description: >- A Customer object represents a customer of your business. Use it to track payments, store reusable payment methods, and reference the customer on checkout sessions, invoices, and subscriptions. type: object required: - created_at - customer_id - email - first_name - last_name - test_mode properties: customer_id: description: The unique identifier for the customer. type: string example: fcus_01HACM7FZ1084XB1GB6053VM0D owner_partner_id: description: >- The partner that owns this customer. When a customer is shared with you by another partner in your organization, this is that sibling partner; otherwise it is your own partner id. type: - string - 'null' example: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA first_name: description: The customer's first name. type: string example: John last_name: description: The customer's last name. type: string example: Doe email: description: The customer's email address. type: string format: email example: joh.doe@example.com phone: description: The customer's phone number. type: - string - 'null' format: phone example: '+15555555555' employer: description: The customer's employer. type: - string - 'null' example: Flex shipping: description: The customer's shipping address. anyOf: - $ref: '#/components/schemas/ShippingAddress' - type: 'null' metadata: description: Metadata associated with the customer. type: - object - 'null' additionalProperties: type: string example: order_id: '8842' channel: shopify created_at: $ref: '#/components/schemas/Timestamptz' description: The time the customer was created. example: '2026-06-15T14:30:00Z' test_mode: description: Whether the customer was created in test mode. type: boolean example: false example: customer_id: fcus_01HACM7FZ1084XB1GB6053VM0D owner_partner_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA first_name: John last_name: Doe email: joh.doe@example.com phone: '+15555555555' employer: Flex shipping: shipping_address_id: fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA line1: 123 Main St line2: Suite 100 city: San Francisco state: CA postal_code: '94107' country: US metadata: order_id: '8842' channel: shopify created_at: '2026-06-15T14:30:00Z' test_mode: false ValidationErrorItem: description: >- Validation errors have their own schema to provide context for invalid requests eg. mismatched types and out of bounds values. There may be any number of these per 422 UNPROCESSABLE ENTITY error. type: object required: - loc - msg - type properties: loc: description: >- The location as a [`Vec`] of [`String`]s -- often in the form `["body", "field_name"]`, `["query", "field_name"]`, etc. They may, however, be arbitarily deep. type: array items: type: string msg: description: The message accompanying the validation error item. type: string type: description: >- The type of error, often "type_error" or "value_error", but sometimes with more context like as "value_error.number.not_ge" type: string example: loc: - string msg: string type: string CreateShippingAddress: description: >- Parameters for supplying a shipping address when creating an object that ships to a customer. type: object properties: line1: description: The first line of the street address (e.g., street number and name). type: - string - 'null' example: 123 Main St line2: description: >- The second line of the street address (e.g., apartment, suite, or unit). type: - string - 'null' example: Suite 100 city: description: City, district, suburb, town, or village. type: - string - 'null' example: San Francisco state: description: State, county, province, or region. type: - string - 'null' example: CA postal_code: description: ZIP or postal code. type: - string - 'null' example: '94107' country: description: Two-letter country code (ISO 3166-1 alpha-2, e.g., `US`). type: - string - 'null' example: US example: line1: 123 Main St line2: Suite 100 city: San Francisco state: CA postal_code: '94107' country: US ShippingAddress: description: >- A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers. type: object required: - shipping_address_id properties: shipping_address_id: description: Unique identifier for the shipping address. type: string example: fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA line1: description: The first line of the street address (e.g., street number and name). type: - string - 'null' example: 123 Main St line2: description: >- The second line of the street address (e.g., apartment, suite, or unit). type: - string - 'null' example: Suite 100 city: description: City, district, suburb, town, or village. type: - string - 'null' example: San Francisco state: description: State, county, province, or region. type: - string - 'null' example: CA postal_code: description: ZIP or postal code. type: - string - 'null' example: '94107' country: description: Two-letter country code (ISO 3166-1 alpha-2, e.g., `US`). type: - string - 'null' example: US example: shipping_address_id: fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA line1: 123 Main St line2: Suite 100 city: San Francisco state: CA postal_code: '94107' country: US Timestamptz: description: >- A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). type: string example: string securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: Use a Bearer token to access this API. ````