--- title: Create, change and fill the line buckets of an order slug: create-change-and-fill-the-line-buckets-of-an-order docTags: createdAt: 2026-10-25T21:00:19.009Z --- { "id": "z-ZAHOk509PPxDT1FBeV_", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.nue.io/cpq/orders/{orderId}/line-buckets:apply", "servers": [ { "url": "https://api.nue.io/cpq/orders/{orderId}/line-buckets:apply", "description": "Nue Production API Endpoint" }, { "url": "https://api.sandbox.nue.io/cpq/orders/{orderId}/line-buckets:apply", "description": "Nue Sandbox API Endpoint" } ], "name": "Create, change and fill the line buckets of an order", "description": "

Arrange an order's lines into line buckets.

\n

Create buckets, change their fields, and say which lines belong in each. One call describes the whole arrangement: a bucket is addressed by its own bucketKey, so sending the same key again updates that bucket rather than creating a second. A line moves WHOLE -- splitting a line's quantity across buckets is not supported, and asking for it is refused rather than silently moving the whole line. Lines not mentioned stay where they are, and a line in no bucket lands in the default one. Apply NEVER removes a bucket: one you leave out is left exactly as it was, with its lines. To remove a bucket, use the delete tool. Set validateOnly to see the result without saving.

", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "orderId", "type": "string", "description": "The Order id." } ], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "*/*" ], "default": "*/*" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "

The buckets to create or change, and the lines that go in them

", "customType": "ApplyLineBucketsRequest", "schema": [ { "name": "buckets", "kind": "required", "type": "array", "description": "

Buckets to create or change. At most 200 per call, and at most 800 line updates in total; over either, the call is refused with REQUEST_TOO_LARGE and nothing is saved. A line update is not only a line you name: the first apply on a header whose lines are in no bucket yet also has to move all of those into the default bucket. When there are more of those than one call may move, nothing is saved and the reply says which of two things to do next. ADOPTION_REQUIRED, which is what a PREVIEW returns, means nothing is running yet: send the same request with validateOnly false to start the background job. ADOPTION_IN_PROGRESS means that job is already putting the lines into the default bucket: wait for it, read the buckets to watch how many lines are still in no bucket, and send the same request again once that reaches zero. Never wait on ADOPTION_REQUIRED, and never split the call on either — every call adopts the same lines, so a smaller one does identical work.

", "modelRef": "#/components/schemas/LineBucketInput", "customType": "LineBucketInput[]", "schema": [ { "name": "bucketKey", "kind": "optional", "type": "string", "description": "

Your own stable key for this bucket. Sending the same key again UPDATES that bucket instead of creating a second one, which is what makes a retry safe.

" }, { "name": "bucketId", "kind": "optional", "type": "string", "description": "

The bucket's Salesforce id, as an alternative to bucketKey for a bucket that already exists.

" }, { "name": "name", "kind": "optional", "type": "string", "description": "

The bucket's name, which becomes the order's name.

" }, { "name": "billingAccountId", "kind": "optional", "type": "string", "description": "Billing account for the order this bucket becomes." }, { "name": "primaryContactId", "kind": "optional", "type": "string", "description": "Primary contact for the order this bucket becomes." }, { "name": "startDate", "kind": "optional", "type": "string", "description": "

Start date for the order this bucket becomes, as YYYY-MM-DD. Setting it makes finalize queue a start-date recalculation.

" }, { "name": "billingPeriod", "kind": "optional", "type": "string", "description": "Billing period for the order this bucket becomes." }, { "name": "paymentTerm", "kind": "optional", "type": "string", "description": "Payment term for the order this bucket becomes." }, { "name": "paymentMethod", "kind": "optional", "type": "string", "description": "Payment method for the order this bucket becomes." }, { "name": "billingStreet", "kind": "optional", "type": "string", "description": "Billing street." }, { "name": "billingCity", "kind": "optional", "type": "string", "description": "Billing city." }, { "name": "billingState", "kind": "optional", "type": "string", "description": "Billing state." }, { "name": "billingPostalCode", "kind": "optional", "type": "string", "description": "Billing postal code." }, { "name": "billingCountry", "kind": "optional", "type": "string", "description": "Billing country." }, { "name": "shippingStreet", "kind": "optional", "type": "string", "description": "Shipping street." }, { "name": "shippingCity", "kind": "optional", "type": "string", "description": "Shipping city." }, { "name": "shippingState", "kind": "optional", "type": "string", "description": "Shipping state." }, { "name": "shippingPostalCode", "kind": "optional", "type": "string", "description": "Shipping postal code." }, { "name": "shippingCountry", "kind": "optional", "type": "string", "description": "Shipping country." }, { "name": "fields", "kind": "optional", "type": "map", "description": "

Any other Line Bucket field, keyed by its exact apiName. A field that will not reach the order is reported as a FIELD_NOT_MAPPED warning, and refused outright when failOnUnmappedFields is true.

", "example": "", "customType": "map", "schema": [] }, { "name": "allocations", "kind": "optional", "type": "array", "description": "The lines that belong in this bucket.", "modelRef": "#/components/schemas/LineAllocationInput", "customType": "LineAllocationInput[]", "schema": [ { "name": "lineId", "kind": "required", "type": "string", "description": "

The quote line or order product to move, as the line editor shows it.

" }, { "name": "includeChildLines", "kind": "optional", "type": "boolean", "description": "Carry every child line of a bundle along with it. Defaults to false." } ] } ] }, { "name": "validateOnly", "kind": "optional", "type": "boolean", "description": "Work out the result and return it without saving anything. Defaults to false.", "default": false }, { "name": "failOnUnmappedFields", "kind": "optional", "type": "boolean", "description": "

Refuse the whole call if any field in fields would not reach the order, instead of saving it and warning. Use it when a dropped value is unacceptable, for example a PO number the invoice needs.

" } ], "modelRef": "#/components/schemas/ApplyLineBucketsRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "ApiKeyAuth", "name": "nue-api-key", "kind": "optional", "type": "apiKey", "in": "header" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "The buckets after the change", "jsonExample": "", "isExpanded": true }, { "statusCode": "400", "description": "Bad Request", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "12dp8pYNq5q4Ny7xBs80n", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.nue.io/cpq/orders/{orderId}/line-buckets:apply \\\n --header 'accept: */*' \\\n --header 'content-type: application/json' \\\n --data '{\n \"buckets\": [\n {\n \"allocations\": [\n {\n \"lineId\": \"\"\n }\n ]\n }\n ]\n }'" }, { "id": "2vZne5dK_NHzyejyAqrzZ", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"*/*\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"buckets\": [\n {\n \"allocations\": [\n {\n \"lineId\": \"\"\n }\n ]\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.nue.io/cpq/orders/{orderId}/line-buckets:apply\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "FLFdq3JZP6yZQYVn3A99j", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.nue.io/cpq/orders/{orderId}/line-buckets:apply\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"*/*\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"buckets\": [\n {\n \"allocations\": [\n {\n \"lineId\": \"\"\n }\n ]\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "rRTSh1qiPE-27CTAgzA-8", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.nue.io/cpq/orders/{orderId}/line-buckets:apply\"\n\npayload = json.dumps({\n \"buckets\": [\n {\n \"allocations\": [\n {\n \"lineId\": \"\"\n }\n ]\n }\n ]\n})\nheaders = {\n 'accept': '*/*',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "12dp8pYNq5q4Ny7xBs80n" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// The buckets after the change\n" }, { "id": "response-1-400", "language": "400", "code": "// Bad Request\n" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }