--- title: Get customer by id slug: reference/get-customer-by-id docTags: createdAt: 2025-10-28T20:08:37.011Z --- { "id": "37YO30RY1QWoTFId782OD", "type": "api-oas-v2", "data": { "method": "GET", "url": "https://app.amberflo.io/customers/{customerId}", "servers": [ { "url": "https://app.amberflo.io/customers/{customerId}" } ], "name": "Get customer by id", "description": "

Retrieves detailed information for a specific customer using their unique identifier.\nUse this endpoint to view customer profile data, billing address, traits, and lifecycle stage.

\n

Returns the complete customer record including system timestamps and metadata. If the customer does not exist, an empty object is returned for backwards compatibility.

", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "customerId", "type": "string", "description": "Id of the target customer" } ], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [], "formDataParameters": [], "oAuthParameters": [ { "id": "apiKey", "name": "X-API-KEY", "kind": "optional", "type": "apiKey", "in": "header" } ] }, "responses": [ { "statusCode": "200", "description": "Successfully retrieved customer record with complete profile 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 ID format provided in request", "jsonExample": "", "isExpanded": true }, { "statusCode": "401", "description": "Authentication required or API key is invalid", "jsonExample": "", "isExpanded": true }, { "statusCode": "403", "description": "Insufficient permissions to access this customer record", "jsonExample": "", "isExpanded": true }, { "statusCode": "404", "description": "Customer with the specified ID does not exist", "jsonExample": "", "isExpanded": true }, { "statusCode": "500", "description": "Internal server error occurred while retrieving customer", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "V2pStFbR6ts7_5EzHXo6T", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url https://app.amberflo.io/customers/{customerId} \\\n --header 'accept: application/json'" }, { "id": "7z_DcCJC6YJN9qpCDCMlH", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/customers/{customerId}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "PuEr2j9y73oAe00wjFA-q", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/customers/{customerId}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "UEVuoiBAeKGEgXGzQ1v9h", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/customers/{customerId}\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "V2pStFbR6ts7_5EzHXo6T" }, "results": { "languages": [ { "id": "0t_Qk5ACjXL6mmggp3JKY", "language": "200", "code": "// Successfully retrieved customer record with complete profile 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": "ikV_J4t_rWh_aF9pAF8_D", "language": "400", "code": "// Invalid customer ID format provided in request\n" }, { "id": "6dNVRFXqfGmMU0gVwU4u6", "language": "401", "code": "// Authentication required or API key is invalid\n" }, { "id": "rrDh-G63n3v0jCe0THFh8", "language": "403", "code": "// Insufficient permissions to access this customer record\n" }, { "id": "KtzMFn1nvbmzdwJxxGqFg", "language": "404", "code": "// Customer with the specified ID does not exist\n" }, { "id": "B6O9hBZFkSh5RDI2BmW1S", "language": "500", "code": "// Internal server error occurred while retrieving customer\n" } ], "selectedLanguageId": "0t_Qk5ACjXL6mmggp3JKY" } }, "children": [ { "text": "" } ] }