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

Updates an existing customer with new information, or creates the customer if they do not exist.\nUse this endpoint when you need idempotent customer management that handles both creation and updates.

\n

When updating, you can modify customer details such as name, email, description, and traits. The lifecycle stage and test status cannot be changed through this endpoint. If the customer does not exist, they will be created with the provided information.

\n

Use this endpoint to:

\n\n

Important Note: Use the dedicated lifecycle stage endpoints to change a customer's lifecycle stage. Deleted customers cannot be updated.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [], "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 updated existing customer or created new customer record", "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 attempting to update deleted customer", "jsonExample": "", "isExpanded": true }, { "statusCode": "401", "description": "Authentication required or API key is invalid", "jsonExample": "", "isExpanded": true }, { "statusCode": "403", "description": "Insufficient permissions to modify customer records", "jsonExample": "", "isExpanded": true }, { "statusCode": "500", "description": "Internal server error occurred while updating customer", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "LYqJEB6TS50Kul3KiJv5A", "language": "curl", "label": "cURL", "code": "curl --request PUT \\\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": "eFw_EQ2ApnGpyRhGpksQX", "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: 'PUT',\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": "A8u9kYjDTjKHgkqtqnIMT", "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::Put.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": "rG53L3Tcni2UeDCs8E8T2", "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(\"PUT\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "LYqJEB6TS50Kul3KiJv5A" }, "results": { "languages": [ { "id": "KtVc__R4pmAA1j2muGuev", "language": "200", "code": "// Successfully updated existing customer or created new customer record\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": "BeDs6MmjEVTM9kncbhLjY", "language": "400", "code": "// Invalid customer data, missing required fields, or attempting to update deleted customer\n" }, { "id": "7PauZ1gyFIJrmBKnh_2HR", "language": "401", "code": "// Authentication required or API key is invalid\n" }, { "id": "enRf3_rLln_c117Lv1JOv", "language": "403", "code": "// Insufficient permissions to modify customer records\n" }, { "id": "_o6h3qI_V6K6C5iBsFsvx", "language": "500", "code": "// Internal server error occurred while updating customer\n" } ], "selectedLanguageId": "KtVc__R4pmAA1j2muGuev" } }, "children": [ { "text": "" } ] }