> 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/api-reference/customer-service/create.md).

# Create

## Overview

The `Create` RPC creates a customer record at the payment processor. This stores customer information (name, email, phone, address) at the connector level, enabling streamlined future transactions without resending personal details.

**Business Use Case:** When a new customer signs up or makes their first purchase, you create their profile at the payment processor. This customer ID can then be used across multiple payment operations, improving authorization rates through customer history and enabling features like saved payment methods and recurring billing.

## Purpose

**Why create customer profiles at the payment processor?**

| Scenario                     | Benefit                                                  |
| ---------------------------- | -------------------------------------------------------- |
| **Returning customers**      | Faster checkout without re-entering personal information |
| **Recurring billing**        | Link subscriptions to a consistent customer identity     |
| **Multiple payment methods** | Organize stored cards/wallets under one customer         |
| **Unified reporting**        | Track all customer transactions in one view              |

**Key outcomes:**

* Unique `connector_customer_id` for referencing this customer
* Consistent identity across all payment operations
* Foundation for payment method tokenization
* Improved authorization rates for repeat customers

## Request Fields

| Field                    | Type           | Required | Description                                         |
| ------------------------ | -------------- | -------- | --------------------------------------------------- |
| `merchant_customer_id`   | string         | Yes      | Your unique customer reference                      |
| `customer_name`          | string         | No       | Full name of the customer                           |
| `email`                  | SecretString   | No       | Email address of the customer                       |
| `phone_number`           | string         | No       | Phone number of the customer                        |
| `address`                | PaymentAddress | No       | Billing and shipping address information            |
| `metadata`               | SecretString   | No       | Additional metadata for the connector (max 20 keys) |
| `connector_feature_data` | SecretString   | No       | Connector-specific metadata for the transaction     |
| `test_mode`              | bool           | No       | Process as test transaction                         |

## 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 cus\_xxx) |
| `error`                 | ErrorInfo           | Error details if creation failed                |
| `status_code`           | uint32              | HTTP-style status code (200, 400, etc.)         |
| `response_headers`      | map\<string,string> | Connector-specific response headers             |

## Example

### Request (grpcurl)

```bash
grpcurl -H "x-connector: stripe" \
  -H "x-connector-config: {\"config\":{\"Stripe\":{\"api_key\":\"$STRIPE_API_KEY\"}}}" \
  -d '{
    "merchant_customer_id": "cust_user_12345",
    "customer_name": "John Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1-555-123-4567",
    "address": {
      "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "line_1": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "zip_code": "94105",
        "country": "US"
      }
    },
    "metadata": "{\"tier\": \"premium\"}",
    "test_mode": true
  }' \
  localhost:8080 \
  types.CustomerService/Create
```

### Response

```json
{
  "merchant_customer_id": "cust_user_12345",
  "connector_customer_id": "cus_9OhXXXXXXXXXXXX",
  "status_code": 200
}
```

## Next Steps

* [Authorize](/integrations/prism/api-reference/authorize.md) - Create a payment linked to this customer
* [PaymentMethodService.Tokenize](/integrations/prism/api-reference/payment-method-service/tokenize.md) - Store payment methods for this customer
* [SetupRecurring](/integrations/prism/api-reference/setup-recurring.md) - Set up recurring billing with customer reference


---

# 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/api-reference/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.