--- updatedAt: 2026-03-24T22:29:34.000Z agentTools: projectIndex: https://developers.digitalfemsa.io/llms.txt --- # Create customer Creates a new customer for the authenticated company. Use customers to store and reuse buyer information (for example name, email, phone, and addresses). The created customer can be referenced later when creating orders and other resources. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "contact": { "email": "engineering@femsa.com", "name": "Engineering Femsa", "url": "https://github.com/digitalfemsa/openapi/issues" }, "description": "Femsa sdk", "license": { "name": "MIT-LICENSE", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "title": "Femsa API", "version": "2.1.0" }, "servers": [ { "description": "Femsa main server", "url": "https://api.digitalfemsa.io" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/customers": { "post": { "description": "Creates a new customer for the authenticated company.\n\nUse customers to store and reuse buyer information (for example name, email, phone, and addresses).\nThe created customer can be referenced later when creating orders and other resources.\n", "operationId": "createCustomer", "parameters": [ { "description": "Use for knowing which language to use", "examples": { "es": { "summary": "for spanish request/response", "value": "es" }, "en": { "summary": "for english request/response", "value": "en" } }, "in": "header", "name": "Accept-Language", "required": false, "schema": { "default": "es", "enum": [ "es", "en" ], "type": "string" } }, { "description": "In the case of a holding company, the company id of the child company to which will process the request.", "example": "6441b6376b60c3a638da80af", "in": "header", "name": "X-Child-Company-Id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/customer" }, "responses": { "200": { "content": { "application/vnd.app-v2.1.0+json": { "schema": { "$ref": "#/components/schemas/customer_response" } } }, "description": "successful operation" }, "401": { "content": { "application/vnd.app-v2.1.0+json": { "example": { "details": [ { "message": "Please include your access key in your request.", "param": null, "code": "femsa.errors.authentication.missing_key" } ], "log_id": "507f1f77bcf86cd799439011", "object": "error", "type": "authentication_error" }, "schema": { "$ref": "#/components/schemas/error" } } }, "description": "authentication error" }, "402": { "content": { "application/vnd.app-v2.1.0+json": { "example": { "details": [ { "message": "The order could not be processed.", "code": "femsa.errors.processing.order.used", "debug_message": "The order has already been used." } ], "log_id": "641b6d073cd9a50001515007", "object": "error", "type": "processing_error" }, "schema": { "$ref": "#/components/schemas/error" } } }, "description": "payment required error" }, "422": { "content": { "application/vnd.app-v2.1.0+json": { "example": { "details": [ { "message": "The name does not exist.", "param": "payment_method.name", "code": "femsa.errors.parameter_validation.payment_method.name.nonexistent_token", "debug_message": "The name does not exist." } ], "log_id": "641b6d813cd9a50001515017", "object": "error", "type": "parameter_validation_error" }, "schema": { "$ref": "#/components/schemas/error" } } }, "description": "parameter validation error" }, "500": { "content": { "application/vnd.app-v2.1.0+json": { "example": { "details": [ { "debug_message": "There was a runtime error and Femsa engineers have been notified.", "message": "There was a runtime error and Femsa engineers have been notified.", "param": null, "code": "femsa.errors.api.system.general_failure" } ], "object": "error", "type": "api_error", "log_id": "641b6f2b3cd9a50001515098" }, "schema": { "$ref": "#/components/schemas/error" } } }, "description": "internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a customer", "tags": [ "Customers" ] } } }, "components": { "requestBodies": { "customer": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer" } } }, "description": "requested field for customer", "required": true } }, "schemas": { "page": { "description": "page metadata", "properties": { "next_page_url": { "description": "URL of the next page.", "example": "https://api.femsa.io/resources?limit=10&next=chrg_1", "nullable": true, "type": "string" }, "previous_page_url": { "description": "Url of the previous page.", "example": "https://api.femsa.io/resources?limit=10&previous=chrg_1", "nullable": true, "type": "string" } }, "title": "page metadata", "type": "object" }, "pagination": { "description": "pagination metadata", "properties": { "has_more": { "description": "Indicates if there are more pages to be requested", "example": false, "type": "boolean" }, "object": { "description": "Object type, in this case is list", "example": "list", "type": "string" } }, "required": [ "has_more", "object" ], "title": "pagination metadata", "type": "object" }, "error": { "allOf": [ { "$ref": "#/components/schemas/details" }, { "properties": { "log_id": { "description": "log id", "example": "507f1f77bcf86cd799439011", "nullable": true, "type": "string" }, "type": { "example": "authentication_error", "type": "string" }, "object": { "example": "error", "type": "string" } }, "type": "object" } ], "description": "err model", "title": "error" }, "customer_response": { "description": "customer response", "properties": { "id": { "description": "Customer's ID", "example": "cus_2tHJfJ79KyUwpxTik", "type": "string" }, "object": { "enum": [ "customer" ], "example": "customer", "type": "string" }, "created_at": { "description": "Creation date of the object (Unix timestamp)", "example": 1485151007, "format": "int64", "type": "integer" }, "livemode": { "description": "true if the object exists in live mode or false if the object exists in test mode", "example": true, "type": "boolean" }, "name": { "description": "Customer's name", "example": "Felipe", "nullable": true, "type": "string" }, "email": { "example": "felipe@gmail.com", "format": "email", "nullable": true, "type": "string" }, "phone": { "description": "Customer's phone number", "example": "5215555555555", "nullable": true, "type": "string" }, "corporate": { "description": "true if the customer is a company", "example": false, "type": "boolean" }, "custom_reference": { "description": "Custom reference", "example": "custom_reference", "type": "string" }, "default_fiscal_entity_id": { "example": "fis_ent_2tKqqAfqPi21oCmEJ", "nullable": true, "type": "string" }, "default_shipping_contact_id": { "example": "ship_cont_2tKZsTYcsryyu7Ah8", "nullable": true, "type": "string" }, "metadata": { "additionalProperties": true, "description": "Customer metadata (maps to contextual_data in backend)", "maxProperties": 100, "nullable": true, "type": "object" }, "payment_sources": { "$ref": "#/components/schemas/customer_payment_methods_response" }, "fiscal_entities": { "$ref": "#/components/schemas/customer_fiscal_entities_response" }, "shipping_contacts": { "$ref": "#/components/schemas/customer_response_shipping_contacts" } }, "required": [ "created_at", "id", "livemode", "object" ], "title": "customer_response", "type": "object" }, "customer_fiscal_entities_request": { "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/customer_address" } ] }, "tax_id": { "type": "string" }, "name": { "example": "Femsa", "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" } }, "required": [ "address" ], "title": "fiscal_entity_request", "type": "object" }, "payment_method_cash_response": { "allOf": [ { "$ref": "#/components/schemas/payment_method_response" }, { "description": "use for cash responses", "properties": { "reference": { "example": "93000262276908", "type": "string" }, "barcode": { "example": "93000262276908", "type": "string" }, "barcode_url": { "example": "https://pt-common-s3-stg.s3.amazonaws.com/644ebf80f2243197aad6cd8810375b905b613dbe.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA3UN6375MP4SLLCWV%2F20230203%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230203T215750Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEH4aCXVzLWVhc3QtMSJGMEQCICd79cu7DYu%2F4%2B3HnVVswydgU9yHcE9kmQIIk2TLoZJrAiBVZ0HxVSeboK5lhdQSqADjwQF62XX35jhC%2F2riB0M8uCqQBAj2%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAIaDDc5OTgwMTA4MTY4OCIMXWZds9ZI5hzUdbeGKuQDFreMyeWnWWPqDuGZ2%2BHk6usCr%2Fl096%2FNJh9xtf8htLu56K%2FhWUTx%2BjiqFWM2O%2FF5zTS%2BIV6TqkLDZ%2BQ5Jo1miQrRmR57YDz6uP2Yd1mNZ1ouq5ipnNjUuu5UWCCBAmqyZQsrVmeMQpSV2IB%2BTERCCcW2SukFEYU%2F20%2Fzy5orsoZ8DxOW460IymR3cWBk5u3Xh2cV6Y1RdPEwDEThhqYEF5w%2ByKbLENloMsI%2FUm6sG5PPrO3yQOAP9aK2muLJs9lXQRU%2FL%2FSsmS4FKSUFOqlN6YU%2Bi2Y%2FyGIKAJT2VDkngvz5Sl%2Fadj0j%2BPKftVRV5FcEhySB6Rl%2BSkPN7kVQMJp6pS8hMJ6JCyEA%2BA3eWYdIfKgQhWVXAR4oCBfJ62DH8FU3a7WfSjjpTwfVkiReWen3GGCYfUWETTVKp46MKnJ9PG0CD3KzxKV8VfmEGc5krK%2FI%2F%2BDV2wtSa%2F9qf1%2BK1YYJIK9qZGb25ljUiGhTB4T%2BMUOSQFjetiWUoOJc5Q3Jz%2FXJbiTAMTST39MhdbCgiMgfrc8OGKN5DOVbex33Z7dn0xf%2FOCkSqurhLaG08efKQBdhLNS0RlE9hbg9yZ2ywwtQIF39fI6A7eeH0T11a5HMlvm51u4rAffPHRuEJfwJoIuj%2F2s3QzDg7%2FWeBjqmAbnPOlGfysjrDdvHyG7HVnaX02kdG%2BI3Q4PFOO4Mjaa3ocpjcfPT70%2BZ5a%2FSv5vP0jDLGrLToeM9%2BAUlNepptICRu23a1tLGW4ri0twPA%2FZ4JDTtUUUgdblyG8bKpcUTNp4oOsdmLLBz3FVyr4c2xQbDZSu2zYOtoOxB18W0AC6kIbsMWVU55Bf0mBhPeBWxGrtM4Kw1SgHHlt%2F8vetQi2OwtUcg08c%3D&X-Amz-SignedHeaders=host&X-Amz-Signature=d06dfa41550003359f2aabc8006063a80dfd806a13a54d244024946a76aa9abc", "type": "string" }, "expires_at": { "example": 0, "format": "int64", "type": "integer" }, "provider": { "example": "Oxxo", "type": "string" } }, "type": "object" } ] }, "customer": { "description": "Customer create request.", "properties": { "name": { "description": "Customer's name.", "example": "miguel", "type": "string" }, "email": { "description": "Customer email address.", "example": "miguel@gmail.com", "format": "email", "type": "string" }, "phone": { "description": "Customer phone number.", "example": "+5215555555555", "maxLength": 19, "nullable": true, "type": "string" }, "corporate": { "default": false, "description": "Indicates whether the customer email is corporate.", "example": false, "type": "boolean" }, "custom_reference": { "description": "Merchant-defined reference used to identify the customer in your system.", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Arbitrary metadata associated with the customer.", "type": "object" }, "payment_sources": { "description": "Customer payment sources to be created with the customer (optional).", "items": { "$ref": "#/components/schemas/customer_payment_methods_request" }, "type": "array" }, "fiscal_entities": { "description": "Customer fiscal entities to be created with the customer (optional).", "items": { "$ref": "#/components/schemas/customer_fiscal_entities_request" }, "type": "array" }, "shipping_contacts": { "description": "Customer shipping contacts to be created with the customer (optional).", "items": { "$ref": "#/components/schemas/customer_shipping_contacts" }, "type": "array" } }, "required": [ "email", "name" ], "title": "customer_request", "type": "object" }, "payment_method_cash_request": { "allOf": [ { "$ref": "#/components/schemas/customer_payment_method_request" }, { "properties": { "expires_at": { "description": "Expiration date as unix timestamp (seconds).", "example": 1553273553, "format": "int64", "type": "integer" } }, "type": "object" } ], "title": "payment_method_cash_request" }, "customer_shipping_contacts": { "description": "[Shipping](https://developers.femsa.com/v2.1.0/reference/createcustomershippingcontacts)\ndetails, required in case of sending a shipping. If we do not receive a shipping_contact on the order, the default shipping_contact of the customer will be used.", "properties": { "phone": { "description": "Phone contact", "example": "+525511223344", "type": "string" }, "receiver": { "description": "Name of the person who will receive the order", "example": "Marvin Fuller", "type": "string" }, "between_streets": { "description": "The street names between which the order will be delivered.", "example": "Ackerman Crescent", "type": "string" }, "address": { "$ref": "#/components/schemas/customer_shipping_contacts_address" }, "parent_id": { "type": "string" }, "default": { "nullable": true, "type": "boolean" }, "deleted": { "nullable": true, "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Metadata associated with the shipping contact", "maxProperties": 100, "type": "object" } }, "required": [ "address" ], "title": "customer_shipping_contacts_request", "type": "object" }, "details": { "properties": { "details": { "items": { "$ref": "#/components/schemas/details_error" }, "type": "array" } }, "type": "object" }, "customer_address": { "properties": { "street1": { "example": "Nuevo Leon 254", "type": "string" }, "street2": { "example": "Departamento 404", "type": "string" }, "postal_code": { "example": "06100", "type": "string" }, "city": { "example": "Ciudad de Mexico", "type": "string" }, "state": { "example": "Ciudad de Mexico", "type": "string" }, "country": { "description": "this field follows the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)", "example": "MX", "type": "string" }, "residential": { "default": false, "example": true, "type": "boolean" }, "external_number": { "example": "string", "type": "string" } }, "required": [ "city", "country", "postal_code", "street1" ], "type": "object" }, "payment_method_response": { "properties": { "type": { "type": "string" }, "id": { "example": "src_2s8K1B3PBKDontpi9", "type": "string" }, "object": { "example": "payment_source", "type": "string" }, "created_at": { "example": 1675715413, "format": "int64", "type": "integer" }, "parent_id": { "example": "cus_2s8K1B3PBKDontpi8", "type": "string" } }, "required": [ "created_at", "id", "object", "type" ], "type": "object" }, "customer_payment_method_request": { "description": "Payment method data to attach to a customer.", "properties": { "type": { "description": "Type of payment method.", "example": "cash", "type": "string" } }, "required": [ "type" ], "title": "customer_payment_method_request", "type": "object" }, "customer_payment_methods_data": { "discriminator": { "mapping": { "cash": "payment_method_cash_response", "oxxo_recurrent": "payment_method_cash_response" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/payment_method_cash_response" } ], "title": "customer_payment_methods_data" }, "customer_payment_methods_response": { "allOf": [ { "$ref": "#/components/schemas/pagination" }, { "$ref": "#/components/schemas/page" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/customer_payment_methods_data" }, "title": "customer_payment_methods_data", "type": "array" } }, "title": "customerPaymentMethods", "type": "object" } ], "title": "customer_payment_methods_response" }, "customer_fiscal_entities_data_response": { "allOf": [ { "$ref": "#/components/schemas/customer_fiscal_entities_request" }, { "properties": { "id": { "example": "ship_cont_2tKZsTYcsryyu7Ah8", "type": "string" }, "object": { "example": "shipping_contact", "type": "string" }, "created_at": { "example": 1675715413, "format": "int64", "type": "integer" }, "parent_id": { "example": "cus_2tKcHxhTz7xU5SymF", "type": "string" }, "default": { "type": "boolean" } }, "required": [ "created_at", "id", "object" ], "type": "object" } ], "title": "customer_fiscal_entities_data_response" }, "customer_fiscal_entities_response": { "allOf": [ { "$ref": "#/components/schemas/pagination" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/customer_fiscal_entities_data_response" }, "type": "array" } }, "type": "object" } ], "title": "customer_fiscal_entities_response" }, "customer_shipping_contacts_data_response": { "allOf": [ { "$ref": "#/components/schemas/customer_shipping_contacts" }, { "properties": { "id": { "example": "ship_cont_2tKZsTYcsryyu7Ah8", "type": "string" }, "object": { "example": "shipping_contact", "type": "string" }, "created_at": { "example": 1675715413, "format": "int64", "type": "integer" } }, "required": [ "created_at", "id", "object" ], "type": "object" } ], "title": "customer_shipping_contacts_data_response" }, "customer_response_shipping_contacts": { "allOf": [ { "$ref": "#/components/schemas/pagination" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/customer_shipping_contacts_data_response" }, "type": "array" } }, "type": "object" } ] }, "customer_payment_methods_request": { "oneOf": [ { "$ref": "#/components/schemas/payment_method_cash_request" } ], "title": "customer_payment_methods_request" }, "customer_shipping_contacts_address": { "description": "Address of the person who will receive the order", "properties": { "street1": { "example": "Nuevo Leon 254", "type": "string" }, "street2": { "example": "Departamento 404", "type": "string" }, "postal_code": { "example": "06100", "type": "string" }, "city": { "example": "Ciudad de Mexico", "type": "string" }, "state": { "example": "Ciudad de Mexico", "type": "string" }, "country": { "description": "this field follows the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)", "example": "MX", "type": "string" }, "residential": { "example": true, "nullable": true, "type": "boolean" } }, "type": "object" }, "details_error": { "properties": { "code": { "example": "femsa.errors.authentication.missing_key", "type": "string" }, "param": { "nullable": true, "type": "string" }, "message": { "example": "Acceso no autorizado.", "type": "string" }, "debug_message": { "example": "Please include your access key in your request.", "type": "string" } }, "title": "details_error", "type": "object" } }, "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ```