> ## Documentation Index
> Fetch the complete documentation index at: https://dev.puppetvendors.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Line Items
> Update report data and cost of goods for line items
## Overview
Update financial fields on line items (report data) and cost of goods records. Supports updating specific line items by ID or bulk-updating all line items matching a SKU.
The endpoint accepts two mutually exclusive modes:
* **Items mode** — update specific line items by Shopify line item ID and order ID
* **By SKU mode** — update all line items matching a SKU
***
## Items Mode
Target specific line items by Shopify line item ID and order ID.
Array of line item update objects (max 100 per request).
Shopify line item ID.
Shopify order ID.
Fields to update. See [Updatable Fields](#updatable-fields) below. Either `fields` or `recalculate` (or both) must be provided.
Set to `true` to trigger recalculation after updating. When combined with `fields`, the fields are written to the DB first, then recalculation is queued.
### Example
```json theme={null}
{
"items": [
{
"lineItemId": 12345678901234,
"orderId": 98765432101234,
"fields": {
"costOfItem": 15.50,
"commission": 5.00
}
}
]
}
```
***
## By SKU Mode
Update all line items matching a SKU value for your shop.
The SKU value to match.
Fields to update. Required when `recalculate` is not `true`. See [Updatable Fields](#updatable-fields) below.
Set to `true` to trigger recalculation for all matching line items.
### Example
```json theme={null}
{
"bySku": "SKU-001",
"fields": {
"costOfItem": 15.50
}
}
```
***
## Updatable Fields
Only the following fields are accepted. Unknown fields will be rejected.
| Field | Type | Description |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `costOfItem` | Number | Cost of goods for this line item. Also updates the SKU cost of goods record (creates one if it does not exist). |
| `commission` | Number | Commission amount |
| `commissionPlan` | String | Commission plan label (e.g. "14%") |
| `deduction` | Number | Vendor deduction |
| `payout` | Number | Vendor payout amount |
| `shipping` | Number | Shipping amount |
| `sales` | Number | Sales amount |
| `salesAfterDiscount` | Number | Sales after discount |
| `tax` | Number | Tax amount |
| `tcs` | Number | TCS amount |
| `taxOnCommissions` | Number | Tax on commissions |
| `totalGlobalDeductions` | Number | Global deductions |
| `discount` | Number | Discount amount |
***
## Recalculate Mode
You can trigger the recalculation pipeline by setting `recalculate: true`. This re-runs the full commission and payout calculations using current shop settings. Recalculation is **asynchronous** — the response confirms it has been queued, not completed.
You can combine `fields` with `recalculate: true` to **update fields first, then recalculate**. This is useful when you want to set a new cost of goods and immediately recalculate the payout based on that value.
```json Update and recalculate theme={null}
{
"items": [
{
"lineItemId": 12345678901234,
"orderId": 98765432101234,
"fields": { "costOfItem": 15.50 },
"recalculate": true
}
]
}
```
```json Recalculate only theme={null}
{
"items": [
{
"lineItemId": 12345678901234,
"orderId": 98765432101234,
"recalculate": true
}
]
}
```
```json Recalculate by SKU theme={null}
{
"bySku": "SKU-001",
"recalculate": true
}
```
***
## Response
### Success
Possible `status` values: `"updated"`, `"recalculate_queued"`, `"updated_and_recalculate_queued"`.
```json 200 theme={null}
{
"success": true,
"updated": 1,
"recalculateQueued": 1,
"results": [
{ "lineItemId": 123, "orderId": 456, "status": "updated_and_recalculate_queued" }
],
"errors": []
}
```
### Partial Failure
When some items succeed and others fail, the response includes both results and errors.
```json 200 theme={null}
{
"success": false,
"updated": 1,
"recalculateQueued": 0,
"results": [
{ "lineItemId": 123, "orderId": 456, "status": "updated" }
],
"errors": [
{ "lineItemId": 999, "orderId": 888, "error": "Line item not found" }
]
}
```
### Validation Error
```json 422 theme={null}
{
"error": "Description of the validation error"
}
```
***
## Important Notes
**Frozen line items** are automatically skipped and reported in the `errors` array.
When `costOfItem` is included in fields, the **SKU cost of goods record** is automatically updated (or created if it does not exist). This ensures future recalculations use the correct COGS value.
* **Shop isolation**: All updates are scoped to your authenticated shop. You cannot update line items belonging to other shops.
* **Max 100 items** per request when using items mode.
* **Mutually exclusive modes**: Provide either `items` or `bySku`, not both.
***
## Examples
### Update cost of goods by SKU
```bash theme={null}
curl -X POST https://api.puppetvendors.com/v1/lineitems/update \
-H "Content-Type: application/json" \
-H "x-access-token: YOUR_JWT_TOKEN" \
-d '{
"bySku": "SKU-001",
"fields": { "costOfItem": 15.50 }
}'
```
### Update specific line items
```bash theme={null}
curl -X POST https://api.puppetvendors.com/v1/lineitems/update \
-H "Content-Type: application/json" \
-H "x-access-token: YOUR_JWT_TOKEN" \
-d '{
"items": [
{
"lineItemId": 12345678901234,
"orderId": 98765432101234,
"fields": {
"costOfItem": 15.50,
"payout": 25.00
}
}
]
}'
```
### Trigger recalculation by SKU
```bash theme={null}
curl -X POST https://api.puppetvendors.com/v1/lineitems/update \
-H "Content-Type: application/json" \
-H "x-access-token: YOUR_JWT_TOKEN" \
-d '{
"bySku": "SKU-001",
"recalculate": true
}'
```