> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integrations/prism/python/customer-service/create.md).

# Create

## Overview

The `create` method creates a customer record in the payment processor system. Storing customer details streamlines future transactions and can improve authorization rates by establishing a payment history.

**Business Use Case:** A new user signs up for your e-commerce platform. Create their customer profile to enable faster checkout on future purchases and to organize their payment history.

## Purpose

**Why create customer records?**

| Scenario            | Benefit                                         |
| ------------------- | ----------------------------------------------- |
| **Faster checkout** | Returning customers skip entering details       |
| **Payment history** | Track all payments by customer                  |
| **Fraud scoring**   | Established customers have better risk profiles |
| **Subscriptions**   | Required for recurring billing setup            |

**Key outcomes:**

* Customer ID for future transactions
* Stored customer profile at processor
* Foundation for payment method storage

## Request Fields

| Field                  | Type   | Required | Description                    |
| ---------------------- | ------ | -------- | ------------------------------ |
| `merchant_customer_id` | string | Yes      | Your unique customer reference |
| `email`                | string | No       | Customer email address         |
| `name`                 | string | No       | Customer full name             |
| `phone`                | string | No       | Customer phone number          |
| `description`          | string | No       | Internal description           |
| `metadata`             | dict   | No       | Additional data (max 20 keys)  |

## Response Fields

| Field                   | Type           | Description                                       |
| ----------------------- | -------------- | ------------------------------------------------- |
| `merchant_customer_id`  | string         | Your customer reference (echoed back)             |
| `connector_customer_id` | string         | Connector's customer ID (e.g., Stripe's cus\_xxx) |
| `status`                | CustomerStatus | Current status: ACTIVE                            |
| `status_code`           | int            | HTTP-style status code (200, 422, etc.)           |

## Example

### SDK Setup

```python
from hyperswitch_prism import CustomerClient

customer_client = CustomerClient(
    connector='stripe',
    api_key='YOUR_API_KEY',
    environment='SANDBOX'
)
```

### Request

```python
request = {
    "merchant_customer_id": "cust_user_12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "description": "Premium plan subscriber"
}

response = await customer_client.create(request)
```

### Response

```python
{
    "merchant_customer_id": "cust_user_12345",
    "connector_customer_id": "cus_xxx",
    "status": "ACTIVE",
    "status_code": 200
}
```

## Common Patterns

### Customer Onboarding Flow

```mermaid
sequenceDiagram
    participant App as Your App
    participant CS as Prism
    participant PP as Payment Provider

    Note over App: User signs up
    App->>CS: 1. create customer
    CS->>PP: Create customer record
    PP-->>CS: Return connector_customer_id
    CS-->>App: Return customer ID
    Note over App: Store customer ID
```

**Flow Explanation:**

1. **Create customer** - When a user creates an account, call `create` with their profile information.
2. **Store IDs** - Save both `merchant_customer_id` and `connector_customer_id` in your database.
3. **Use for payments** - Reference this customer in future payment operations.

## Best Practices

* Create customers at account signup, not first purchase
* Use consistent `merchant_customer_id` format
* Store `connector_customer_id` for future reference
* Include email to enable customer communications from processor

## Error Handling

| Error Code | Meaning         | Action                                  |
| ---------- | --------------- | --------------------------------------- |
| `409`      | Customer exists | Use existing customer or update instead |
| `422`      | Invalid data    | Check email format, name length, etc.   |

## Next Steps

* [Payment Method Service](/integrations/prism/python/payment-method-service.md) - Store payment methods for customer
* [Payment Service](/integrations/prism/python/payment-service.md) - Process payments with customer ID
* [Recurring Payment Service](/integrations/prism/python/recurring-payment-service.md) - Set up subscriptions for customer


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hyperswitch.io/integrations/prism/python/customer-service/create.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.