---
title: Query customer plan assignments
slug: reference/query-customer-plan-assignments
docTags:
createdAt: 2025-03-18T18:28:02.918Z
---
{
"id": "9vvVGPGK8gXYI0ShfJ361",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://app.amberflo.io/payments/pricing/query/customer-plans",
"servers": [
{
"url": "https://app.amberflo.io/payments/pricing/query/customer-plans"
}
],
"name": "Query customer plan assignments",
"description": "Queries customer plan assignments and pricing relationships at specific points in time.\nUse this endpoint to discover which plans are assigned to customers and track pricing changes over time.
\nUse this endpoint to:
\n\n- List plans assigned to specific customers
\n- Find customers assigned to specific plans
\n- Query plan assignments at historical or future dates
\n- Support billing audits and plan management workflows
\n
",
"contentType": "application/json",
"request": {
"pathParameters": [],
"headerParameters": [],
"queryParameters": [],
"bodyDataParameters": [
{
"kind": "optional",
"name": "body",
"type": "object",
"description": "Query parameters for customer plan lookups including time filters, pagination, and search criteria",
"customType": "payment.pricing.customer.indexable.api.IndexableCustomerPricingQuery.in",
"schema": [
{
"name": "timeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp for point-in-time queries, mutually exclusive with timeRange. Must be specified if timeRange is not provided.",
"example": 0
},
{
"name": "timeRange",
"kind": "optional",
"type": "object",
"description": "Time period for range queries, mutually exclusive with timeInSeconds. Must be specified if timeInSeconds is not provided.",
"modelRef": "#/components/schemas/payment.common.TimeRange.in",
"customType": "payment.common.TimeRange.in",
"schema": [
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp marking the beginning of the time range in seconds",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp marking the end of time range or null for open-ended ranges",
"example": 0
}
]
},
{
"name": "filters",
"kind": "optional",
"type": "map",
"description": "Optional key-value filters for WHERE-IN style queries, each key maps to non-empty array of filter values.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "page",
"kind": "optional",
"type": "object",
"description": "Traditional pagination parameters for controlling result page number and size.",
"modelRef": "#/components/schemas/payment.common.Page.in",
"customType": "payment.common.Page.in",
"schema": [
{
"name": "number",
"kind": "optional",
"type": "integer",
"description": "One-indexed page number to retrieve with token required for pages beyond first",
"example": 0
},
{
"name": "size",
"kind": "optional",
"type": "integer",
"description": "Number of items per page with valid range between 1 and 1000 inclusive",
"example": 0
},
{
"name": "token",
"kind": "optional",
"type": "string",
"description": "Pagination token required for navigating to pages beyond the first page",
"example": ""
}
]
},
{
"name": "take",
"kind": "optional",
"type": "object",
"description": "Alternative pagination with limit and ordering controls for result set size and sort direction.",
"modelRef": "#/components/schemas/payment.common.Take.in",
"customType": "payment.common.Take.in",
"schema": [
{
"name": "limit",
"kind": "optional",
"type": "integer",
"description": "Maximum number of results to return for query with minimum value of 1",
"example": 0
},
{
"name": "isAscending",
"kind": "optional",
"type": "boolean",
"description": "Sort order direction with true for ascending and false for descending order",
"example": ""
}
]
}
],
"modelRef": "#/components/schemas/payment.pricing.customer.indexable.api.IndexableCustomerPricingQuery.in",
"isExpanded": true
}
],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "apiKey",
"name": "X-API-KEY",
"kind": "optional",
"type": "apiKey",
"in": "header"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "Returns paginated list of customer plan assignments with pricing details and effective dates",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "Response containing customer plan assignment query results with pagination metadata and the original query specification.",
"customType": "payment.pricing.customer.indexable.api.IndexableCustomerPricingResponse.out",
"schema": [
{
"name": "metadata",
"kind": "optional",
"type": "object",
"description": "Original query parameters as actually executed, providing context for the returned results.",
"modelRef": "#/components/schemas/payment.pricing.customer.indexable.api.IndexableCustomerPricingQuery.out",
"customType": "payment.pricing.customer.indexable.api.IndexableCustomerPricingQuery.out",
"schema": [
{
"name": "timeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp for point-in-time queries, mutually exclusive with timeRange.",
"example": 0
},
{
"name": "timeRange",
"kind": "optional",
"type": "object",
"description": "Time period for range queries, mutually exclusive with timeInSeconds.",
"modelRef": "#/components/schemas/payment.common.TimeRange.in",
"customType": "payment.common.TimeRange.in",
"schema": [
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp marking the beginning of the time range in seconds",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp marking the end of time range or null for open-ended ranges",
"example": 0
}
]
},
{
"name": "filters",
"kind": "optional",
"type": "map",
"description": "Optional key-value filters where each key maps to array of filter values.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "page",
"kind": "optional",
"type": "object",
"description": "Traditional pagination parameters for controlling result page number and size.",
"modelRef": "#/components/schemas/payment.common.Page.in",
"customType": "payment.common.Page.in",
"schema": [
{
"name": "number",
"kind": "optional",
"type": "integer",
"description": "One-indexed page number to retrieve with token required for pages beyond first",
"example": 0
},
{
"name": "size",
"kind": "optional",
"type": "integer",
"description": "Number of items per page with valid range between 1 and 1000 inclusive",
"example": 0
},
{
"name": "token",
"kind": "optional",
"type": "string",
"description": "Pagination token required for navigating to pages beyond the first page",
"example": ""
}
]
},
{
"name": "take",
"kind": "optional",
"type": "object",
"description": "Alternative pagination with limit and ordering controls for result set.",
"modelRef": "#/components/schemas/payment.common.Take.in",
"customType": "payment.common.Take.in",
"schema": [
{
"name": "limit",
"kind": "optional",
"type": "integer",
"description": "Maximum number of results to return for query with minimum value of 1",
"example": 0
},
{
"name": "isAscending",
"kind": "optional",
"type": "boolean",
"description": "Sort order direction with true for ascending and false for descending order",
"example": ""
}
]
}
]
},
{
"name": "pageInfo",
"kind": "optional",
"type": "object",
"description": "Pagination metadata including current page number, total pages, result counts, and navigation tokens.",
"modelRef": "#/components/schemas/payment.common.PageInfo.out",
"customType": "payment.common.PageInfo.out",
"schema": [
{
"name": "pageNumber",
"kind": "optional",
"type": "integer",
"description": "Current page number being returned in this response using one-indexed numbering",
"example": 0
},
{
"name": "pageSize",
"kind": "optional",
"type": "integer",
"description": "Number of items per page configured for this paginated query response",
"example": 0
},
{
"name": "pageToken",
"kind": "optional",
"type": "string",
"description": "Token for accessing the next page of results in subsequent pagination requests",
"example": ""
},
{
"name": "totalPages",
"kind": "optional",
"type": "integer",
"description": "Total number of pages available for this query across all results",
"example": 0
},
{
"name": "totalResults",
"kind": "optional",
"type": "integer",
"description": "Total count of all items available across all pages for this query",
"example": 0
}
]
},
{
"name": "rows",
"kind": "optional",
"type": "array",
"description": "Array of customer product plan assignment rows matching the query criteria.",
"modelRef": "#/components/schemas/payment.pricing.customer.indexable.api.CustomerProductPlanRow.out",
"customType": "payment.pricing.customer.indexable.api.CustomerProductPlanRow.out[]",
"schema": [
{
"name": "productId",
"kind": "optional",
"type": "string",
"description": "Product identifier for the customer's pricing plan assignment.",
"example": ""
},
{
"name": "productPlanId",
"kind": "optional",
"type": "string",
"description": "Specific product plan identifier assigned to this customer.",
"example": ""
},
{
"name": "customerId",
"kind": "optional",
"type": "string",
"description": "Unique identifier of the customer with this plan assignment.",
"example": ""
},
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when this plan assignment became active for the customer.",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when this plan assignment ends or becomes inactive.",
"example": 0
}
]
}
],
"modelRef": "#/components/schemas/payment.pricing.customer.indexable.api.IndexableCustomerPricingResponse.out",
"isExpanded": true
}
]
},
{
"statusCode": "400",
"description": "Invalid query parameters or unsupported filter combinations",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "401",
"description": "Authentication required or invalid API key provided",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "403",
"description": "Insufficient permissions to query customer pricing data",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "404",
"description": "No customer plans found matching the specified criteria",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "500",
"description": "Internal server error occurred while querying customer plans",
"jsonExample": "",
"isExpanded": true
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "JE3lwVApiT6xjrWjrusz-",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://app.amberflo.io/payments/pricing/query/customer-plans \\\n --header 'accept: application/json'"
},
{
"id": "SZ6xr_8Xagx27wKgOgDEJ",
"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: 'POST',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/payments/pricing/query/customer-plans\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "HXxIe88XllGZLV_Nr6Zdg",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/payments/pricing/query/customer-plans\")\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\"\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "KTjGFhGdjywMuwUkwpQWF",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/payments/pricing/query/customer-plans\"\n\npayload = {}\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": "JE3lwVApiT6xjrWjrusz-"
},
"results": {
"languages": [
{
"id": "u4IHv_OKjX7djGPNLNfTY",
"language": "200",
"code": "// Returns paginated list of customer plan assignments with pricing details and effective dates\n{\n \"metadata\": {\n \"timeInSeconds\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": \"\",\n \"endTimeInSeconds\": \"\"\n },\n \"filters\": \"\",\n \"page\": {\n \"number\": \"\",\n \"size\": \"\",\n \"token\": \"\"\n },\n \"take\": {\n \"limit\": \"\",\n \"isAscending\": false\n }\n },\n \"pageInfo\": {\n \"pageNumber\": \"\",\n \"pageSize\": \"\",\n \"pageToken\": \"\",\n \"totalPages\": \"\",\n \"totalResults\": \"\"\n },\n \"rows\": [\n {\n \"productId\": \"\",\n \"productPlanId\": \"\",\n \"customerId\": \"\",\n \"startTimeInSeconds\": \"\",\n \"endTimeInSeconds\": \"\"\n }\n ]\n}"
},
{
"id": "rosOqCSKxUijXUH__mnr4",
"language": "400",
"code": "// Invalid query parameters or unsupported filter combinations\n"
},
{
"id": "0TXnlCrjev4VeLRiE5Su3",
"language": "401",
"code": "// Authentication required or invalid API key provided\n"
},
{
"id": "62lA7tEV2oZM7F5T1FR8I",
"language": "403",
"code": "// Insufficient permissions to query customer pricing data\n"
},
{
"id": "zcII2_c2LdqJ49-Dxp8m2",
"language": "404",
"code": "// No customer plans found matching the specified criteria\n"
},
{
"id": "NBANRdu8DLnu0qxdQnq4n",
"language": "500",
"code": "// Internal server error occurred while querying customer plans\n"
}
],
"selectedLanguageId": "u4IHv_OKjX7djGPNLNfTY"
}
},
"children": [
{
"text": ""
}
]
}