--- updatedAt: 2026-09-11T20:23:09.000Z agentTools: projectIndex: https://docs.staxpayments.com/llms.txt --- # Create Customer Create and store customer records tied to their merchant accounts. # Create Customer The **Create a Customer** endpoint allows merchants to create and store customer records tied to their merchant accounts. This is essential for enabling streamlined future transactions without requiring repeated customer registration. Each customer created is assigned a unique identifier (`customer_id`) using a universally unique identifier (UUID). *** ## Key Features Store customer details such as name, email, and company information Automatically assigns a unique `customer_id` for use in subsequent API calls Supports ISO 3 code for `address_country`, sent to processing gateway when provided Add customer-specific custom fields to capture additional data unique to your business ### Data Validation Requires at least one of the following fields to create a record: `firstname`, `lastname`, `email`, or `company`. At least one of the following fields must be provided to successfully create a customer record: * `firstname` (string): Customer's first name * `lastname` (string): Customer's last name * `email` (string): Customer's email address * `company` (string): Company name associated with the customer * `address_country` (string): The ISO 3 code for the customer's country. This will be sent to the processing gateway if provided. Example: `USA` for the United States * `options` (object): Additional configuration options including custom fields specific to your customer record The `options` parameter allows you to add custom fields that are specific to your customer record. These custom fields can capture additional customer information that's unique to your business requirements. **Important Notes:** - Custom field values are always stored as strings regardless of the specified type - The type field indicates how the value should be interpreted and validated - Custom fields are unique to your customer record and don't affect other customer records ## Response Structure | Code | Response | Description | | ---- | --------------------- | ------------------------------------------------------------------ | | 201 | Success | Customer successfully created. Returns the `customer_id` and data. | | 400 | Bad Request | Missing or invalid required fields. | | 401 | Unauthorized | API key invalid or missing. | | 500 | Internal Server Error | An unexpected error occurred. | **Field Validation**: Ensure at least one required field (`firstname`, `lastname`, `email`, `company`) is present in the payload. **Duplicate Customers**: Creating a customer with duplicate details (e.g., email) will generate a new customer record with a unique `customer_id`. It does not merge existing records. **Country Code Format**: If using `address_country`, confirm it matches the ISO 3 standard to avoid validation errors. **Future Transactions**: The `customer_id` can be used for associating payment methods, transactions, or invoices with this customer. Use meaningful and unique data for customer identification (e.g., email or company) Keep customer information updated by utilizing the Update a Customer endpoint Always verify the API key and ensure your implementation complies with PCI DSS standards # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "stax-api", "version": "0.1" }, "servers": [ { "url": "https://apiprod.fattlabs.com/" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "API key for merchant-level operations. Provides access to merchant-specific endpoints including transactions, payments, customer management, and merchant account settings. This key is scoped to a single merchant account and cannot access partner-level functionality." } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/customer": { "post": { "summary": "Create Customer", "description": "Create and store customer records tied to their merchant accounts.", "operationId": "create-customer", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstname": { "type": "string", "description": "Max: 255. Required if no lastname, email, company supplied" }, "lastname": { "type": "string", "description": "Max: 255. Required if no firstname, email, company supplied" }, "email": { "type": "string", "description": "Max: 255. Required if no firstname, lastname, company supplied" }, "company": { "type": "string", "description": "Max: 255. Required if no firstname, lastname, email supplied" }, "phone": { "type": "string", "description": "Matching regex: /[0-9]{10,15}/" }, "address_1": { "type": "string", "description": "Max: 255" }, "address_2": { "type": "string", "description": "Max: 255" }, "address_city": { "type": "string", "description": "Max: 255" }, "address_state": { "type": "string", "description": "Max: 2 Use the two-letter state abbreviation." }, "address_zip": { "type": "string", "description": "Max: 16" }, "address_country": { "type": "string", "description": "Max: 3" }, "notes": { "type": "string", "description": "Max: 21844. For internal notes only; not visible to customers in invoices or communications." }, "reference": { "type": "string", "description": "Max: 255. This field is for the merchant's internal use." }, "files": { "type": "array", "description": "Array of strings(50) where each index is a valid file_id", "items": { "type": "string" } }, "cc_emails": { "type": "array", "description": "Array of strings(255) where each index is a valid email address.", "items": { "type": "string" } }, "cc_sms": { "type": "array", "description": "Array of strings(255) where each item is a valid phone number.", "items": { "type": "string" } }, "allow_invoice_credit_card_payments": { "type": "boolean" }, "options": { "type": "object", "description": "Additional customer options such as custom fields", "properties": { "customer_custom_fields": { "type": "array", "items": { "properties": { "id": { "type": "string", "description": "Unique identifier for the custom field" }, "name": { "type": "string", "description": "Display name of the custom field" }, "placeholder": { "type": "string", "description": "Placeholder text for the field (can be empty)" }, "required": { "type": "boolean", "description": "Whether the field is required" }, "visible": { "type": "boolean", "description": "Whether the field is visible in the UI" }, "type": { "type": "string", "enum": [ "text" ], "description": "The data type of the field value" }, "value": { "type": "string", "description": "The actual value stored in the custom field" } }, "type": "object" }, "description": "An array of custom field objects that contain additional customer information." } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "id": "59327746-fbca-4fb6-adf0-e88c99245548", "firstname": "John", "lastname": "Smith", "company": "ABC INC", "email": "contact@example.com", "cc_emails": [ "demo@abc.com" ], "phone": "1234567898", "address_1": "123 Rite Way", "address_2": "Unit 12", "address_city": "Orlando", "address_state": "FL", "address_zip": "32801", "address_country": "USA", "notes": null, "reference": "BARTLE", "options": { "customer_custom_fields": [ { "id": "95b5-fce4-08e6-e60b-c26e", "name": "Intenal ID", "placeholder": "Add an internal tracking ID", "required": false, "visible": true, "type": "text", "value": "0123456" } ] }, "created_at": "2017-05-08 19:13:41", "updated_at": "2017-05-08 19:13:41", "deleted_at": null, "gravatar": "//www.gravatar.com/avatar/45357c125af15b6df8864a71a653bea2", "has_address": true, "missing_address_components": [] } } }, "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "59327746-fbca-4fb6-adf0-e88c99245548" }, "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Smith" }, "company": { "type": "string", "example": "ABC INC" }, "email": { "type": "string", "example": "contact@example.com" }, "cc_emails": { "type": "array", "items": { "type": "string", "example": "demo@abc.com" } }, "phone": { "type": "string", "example": "1234567898" }, "address_1": { "type": "string", "example": "123 Rite Way" }, "address_2": { "type": "string", "example": "Unit 12" }, "address_city": { "type": "string", "example": "Orlando" }, "address_state": { "type": "string", "example": "FL" }, "address_zip": { "type": "string", "example": "32801" }, "address_country": { "type": "string", "example": "USA" }, "notes": {}, "reference": { "type": "string", "example": "BARTLE" }, "options": {}, "created_at": { "type": "string", "example": "2017-05-08 19:13:41" }, "updated_at": { "type": "string", "example": "2017-05-08 19:13:41" }, "deleted_at": {}, "gravatar": { "type": "string", "example": "//www.gravatar.com/avatar/45357c125af15b6df8864a71a653bea2" }, "has_address": { "type": "boolean", "example": true, "default": true }, "missing_address_components": { "type": "array" } } } } } }, "422": { "description": "422", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"firstname\": [\n \"The firstname field is required when none of lastname / email / company are present.\"\n ],\n \"lastname\": [\n \"The lastname field is required when none of firstname / email / company are present.\"\n ],\n \"email\": [\n \"The email field is required when none of firstname / lastname / company are present.\"\n ],\n \"company\": [\n \"The company field is required when none of firstname / lastname / email are present.\"\n ]\n}" } }, "schema": { "type": "object", "properties": { "firstname": { "type": "array", "items": { "type": "string", "example": "The firstname field is required when none of lastname / email / company are present." } }, "lastname": { "type": "array", "items": { "type": "string", "example": "The lastname field is required when none of firstname / email / company are present." } }, "email": { "type": "array", "items": { "type": "string", "example": "The email field is required when none of firstname / lastname / company are present." } }, "company": { "type": "array", "items": { "type": "string", "example": "The company field is required when none of firstname / lastname / email are present." } } } } } } } } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```