--- title: Create a customer slug: reference/create-a-customer docTags: createdAt: 2025-10-28T20:08:37.011Z --- { "id": "1JiuHLXRxGGS7iAwV3-iC", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://app.amberflo.io/customers", "servers": [ { "url": "https://app.amberflo.io/customers" } ], "name": "Create a customer", "description": "

Creates a new customer record in your account with the provided details.\nUse this endpoint to onboard new customers before tracking their usage or billing them.

\n

The customer will be assigned the default lifecycle stage from your account settings unless specified otherwise. You can optionally create the customer in Stripe by using the autoCreateCustomerInStripe query parameter.

\n

Use this endpoint to:

\n\n

Important Note: The customerId must be unique within your account. If the customer already exists, this request will fail.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [ { "kind": "optional", "name": "autoCreateCustomerInStripe", "type": "string", "description": "

Indicates whether to create the customer in your Stripe account or not.

\n

Its Stripe id is saved as the stripeId trait after it is created there.

\n

When set to if_payment_provider, then it will only be created in Stripe if the paymentProviderName trait is set to STRIPE

" } ], "bodyDataParameters": [ { "kind": "optional", "name": "body", "type": "object", "description": "Customer information required to create or update a customer in the system.", "customType": "customer.CustomerDetails.in", "schema": [ { "name": "customerId", "kind": "required", "type": "string", "description": "Id of the customer, as it exists in your system.", "example": "" }, { "name": "customerName", "kind": "required", "type": "string", "description": "Name of the customer, as it exists in your system.", "example": "" }, { "name": "customerEmail", "kind": "optional", "type": "string", "description": "Email of the customer, as it exists in your system.", "example": "" }, { "name": "description", "kind": "optional", "type": "string", "description": "Description of the customer.", "example": "" }, { "name": "enabled", "kind": "optional", "type": "boolean", "deprecated": true, "description": "Warning: Deprecated\nDetermines whether the customer is active or not. Setting it to false deactivates the customer. Only relevant when updating a customer.\n\nNote that this field is superseded by the `lifecycleStage` one, which allows finer grained control. When `enabled = false` means `lifecycleStage = OFFBOARDED`, other lifecycle stages mean `enabled = true` and vice-versa.", "example": "" }, { "name": "test", "kind": "optional", "type": "boolean", "description": "Determines whether the customer is a test customer. Can only be set once during creation. Test customers can be excluded from certain operations.\n\nDefaults to `false`.", "example": "" }, { "name": "lifecycleStage", "kind": "optional", "type": "string", "description": "The lifecycle stage of a customer. The lifecycle stage of a customer determines which features of the system are enabled for it.\n\nValid lifecycle stages are:\n- `ONBOARDING` - Only usage is tracked.\n- `TRAIL` - Both usage and billing data are tracked but customer will not be charged.\n- `ACTIVE` - Both usage and billing data are tracked and customer will be charged.\n- `OFFBOARDED` - Only usage is tracked.\n\nDefault: `ACTIVE`", "modelRef": "#/components/schemas/customer.CustomerLifecycleStage.in", "customType": "customer.CustomerLifecycleStage.in", "schema": [] }, { "name": "traits", "kind": "optional", "type": "map", "description": "Reference metadata to integrate with external systems like billing.\n\nThe following traits are used by Amberflo:\n- `stripeId` for [integrating with Stripe](doc:stripe);\n- `awsm.customerIdentifier` for [integrating with AWS Marketplace](doc:associating-customers-with-aws-marketplace);\n- `currency` for the customer's currency, following the ISO standard.\n", "example": "", "customType": "map", "schema": [] }, { "name": "address", "kind": "optional", "type": "object", "description": "Tax address of the customer.", "modelRef": "#/components/schemas/customer.CustomerAddress.in", "customType": "customer.CustomerAddress.in", "schema": [ { "name": "line1", "kind": "required", "type": "string", "description": "Street address line including building number and street name.", "example": "" }, { "name": "state", "kind": "optional", "type": "string", "description": "State or province name. Required for US addresses, optional for other countries.", "example": "" }, { "name": "city", "kind": "required", "type": "string", "description": "City or municipality name where the customer is located.", "example": "" }, { "name": "postalCode", "kind": "optional", "type": "string", "description": "Postal or ZIP code for the address. Required for US addresses, optional for other countries.", "example": "" }, { "name": "country", "kind": "required", "type": "string", "description": "Country name for the customer's tax address.", "example": "" } ] } ], "modelRef": "#/components/schemas/customer.CustomerDetails.in", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "apiKey", "name": "X-API-KEY", "kind": "optional", "type": "apiKey", "in": "header" } ] }, "responses": [ { "statusCode": "200", "description": "Successfully created new customer record with generated timestamps and metadata", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "Complete customer record with system-generated fields and timestamps.", "customType": "customer.CustomerDetails.out", "schema": [ { "name": "createTime", "kind": "optional", "type": "integer", "description": "Creation time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (milliseconds)", "example": 0 }, { "name": "updateTime", "kind": "optional", "type": "integer", "description": "Update time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (milliseconds)", "example": 0 }, { "name": "deleteTime", "kind": "optional", "type": "integer", "description": "Timestamp when the customer was deleted, in Unix time (milliseconds). Null if not deleted.", "example": 0 }, { "name": "customerId", "kind": "required", "type": "string", "description": "Id of the customer, as it exists in your system.", "example": "" }, { "name": "customerName", "kind": "required", "type": "string", "description": "Name of the customer, as it exists in your system.", "example": "" }, { "name": "customerEmail", "kind": "optional", "type": "string", "description": "Email of the customer, as it exists in your system.", "example": "" }, { "name": "description", "kind": "optional", "type": "string", "description": "Description of the customer.", "example": "" }, { "name": "enabled", "kind": "optional", "type": "boolean", "deprecated": true, "description": "Warning: Deprecated\nDetermines whether the customer is active or not. Setting it to false deactivates the customer. Only relevant when updating a customer.\n\nNote that this field is superseded by the `lifecycleStage` one, which allows finer grained control. When `enabled = false` means `lifecycleStage = OFFBOARDED`, other lifecycle stages mean `enabled = true` and vice-versa.", "example": "" }, { "name": "test", "kind": "optional", "type": "boolean", "description": "Determines whether the customer is a test customer. Can only be set once during creation. Test customers can be excluded from certain operations.\n\nDefaults to `false`.", "example": "" }, { "name": "lifecycleStage", "kind": "optional", "type": "string", "description": "The lifecycle stage of a customer. The lifecycle stage of a customer determines which features of the system are enabled for it.\n\nValid lifecycle stages are:\n- `ONBOARDING` - Only usage is tracked.\n- `TRAIL` - Both usage and billing data are tracked but customer will not be charged.\n- `ACTIVE` - Both usage and billing data are tracked and customer will be charged.\n- `OFFBOARDED` - Only usage is tracked.\n\nDefault: `ACTIVE`", "modelRef": "#/components/schemas/customer.CustomerLifecycleStage.out", "customType": "customer.CustomerLifecycleStage.out", "schema": [] }, { "name": "deactivateTimeStamp", "kind": "optional", "type": "integer", "description": "Timestamp when the customer was last deactivated, in Unix time (milliseconds).", "example": 0 }, { "name": "traits", "kind": "optional", "type": "map", "description": "Reference metadata to integrate with external systems like billing.\n\nThe following traits are used by Amberflo:\n- `stripeId` for [integrating with Stripe](doc:stripe);\n- `awsm.customerIdentifier` for [integrating with AWS Marketplace](doc:associating-customers-with-aws-marketplace);\n- `currency` for the customer's currency, following the ISO standard.\n", "example": "", "customType": "map", "schema": [] }, { "name": "address", "kind": "optional", "type": "object", "description": "Tax address of the customer.", "modelRef": "#/components/schemas/customer.CustomerAddress.out", "customType": "customer.CustomerAddress.out", "schema": [ { "name": "verified", "kind": "optional", "type": "boolean", "description": "Indicates whether the address has been validated through the address verification system.", "example": "" }, { "name": "line1", "kind": "required", "type": "string", "description": "Street address line including building number and street name.", "example": "" }, { "name": "state", "kind": "optional", "type": "string", "description": "State or province name. Required for US addresses, optional for other countries.", "example": "" }, { "name": "city", "kind": "required", "type": "string", "description": "City or municipality name where the customer is located.", "example": "" }, { "name": "postalCode", "kind": "optional", "type": "string", "description": "Postal or ZIP code for the address. Required for US addresses, optional for other countries.", "example": "" }, { "name": "country", "kind": "required", "type": "string", "description": "Country name for the customer's tax address.", "example": "" } ] } ], "modelRef": "#/components/schemas/customer.CustomerDetails.out", "isExpanded": true } ] }, { "statusCode": "400", "description": "Invalid customer data, missing required fields, or customer ID already exists", "jsonExample": "", "isExpanded": true }, { "statusCode": "401", "description": "Authentication required or API key is invalid", "jsonExample": "", "isExpanded": true }, { "statusCode": "403", "description": "Insufficient permissions to create customer records", "jsonExample": "", "isExpanded": true }, { "statusCode": "500", "description": "Internal server error occurred while creating customer", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "SZPrF00a7c3F3FJaSaB65", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://app.amberflo.io/customers \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"customerId\": \"\",\n \"customerName\": \"\",\n \"address\": {\n \"line1\": \"\",\n \"city\": \"\",\n \"country\": \"\"\n }\n }'" }, { "id": "oXHvYKkDsZJ-2BMbSdG66", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"customerId\": \"\",\n \"customerName\": \"\",\n \"address\": {\n \"line1\": \"\",\n \"city\": \"\",\n \"country\": \"\"\n }\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/customers\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "8921asiAbx4W_vOsFToFY", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/customers\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"customerId\": \"\",\n \"customerName\": \"\",\n \"address\": {\n \"line1\": \"\",\n \"city\": \"\",\n \"country\": \"\"\n }\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "I15OLsVm_Ldc8vOgWNZX4", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/customers\"\n\npayload = json.dumps({\n \"customerId\": \"\",\n \"customerName\": \"\",\n \"address\": {\n \"line1\": \"\",\n \"city\": \"\",\n \"country\": \"\"\n }\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "SZPrF00a7c3F3FJaSaB65" }, "results": { "languages": [ { "id": "VUXTycL3SN9TKn2dyTdqA", "language": "200", "code": "// Successfully created new customer record with generated timestamps and metadata\n{\n \"createTime\": \"\",\n \"updateTime\": \"\",\n \"deleteTime\": \"\",\n \"customerId\": \"\",\n \"customerName\": \"\",\n \"customerEmail\": \"\",\n \"description\": \"\",\n \"enabled\": false,\n \"test\": false,\n \"lifecycleStage\": \"\",\n \"deactivateTimeStamp\": \"\",\n \"traits\": \"\",\n \"address\": {\n \"verified\": false,\n \"line1\": \"\",\n \"state\": \"\",\n \"city\": \"\",\n \"postalCode\": \"\",\n \"country\": \"\"\n }\n}" }, { "id": "QrcuIo_xKrQgd5b58V7Ub", "language": "400", "code": "// Invalid customer data, missing required fields, or customer ID already exists\n" }, { "id": "RZJpVGsvoSXoZq8Owazns", "language": "401", "code": "// Authentication required or API key is invalid\n" }, { "id": "Hb6U5S_LaiatAPiIvZO4T", "language": "403", "code": "// Insufficient permissions to create customer records\n" }, { "id": "zKQRwKv9oRaTrfc21DHLx", "language": "500", "code": "// Internal server error occurred while creating customer\n" } ], "selectedLanguageId": "VUXTycL3SN9TKn2dyTdqA" } }, "children": [ { "text": "" } ] }