Skip to main content
POST
/
v1
/
lineitems
/
update
Update Line Items
curl --request POST \
  --url https://api.puppetvendors.com/v1/lineitems/update \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "items": [
    {
      "lineItemId": 123,
      "orderId": 123,
      "fields": {},
      "recalculate": true
    }
  ],
  "bySku": "<string>",
  "fields": {},
  "recalculate": true
}
'

​
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.
​
items
array
required
Array of line item update objects (max 100 per request).

​
Example

{
  "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.
​
bySku
string
required
The SKU value to match.
​
fields
object
Fields to update. Required when recalculate is not true. See Updatable Fields below.
​
recalculate
boolean
Set to true to trigger recalculation for all matching line items.

​
Example

{
  "bySku": "SKU-001",
  "fields": {
    "costOfItem": 15.50
  }
}

​
Updatable Fields

Only the following fields are accepted. Unknown fields will be rejected.
FieldTypeDescription
costOfItemNumberCost of goods for this line item. Also updates the SKU cost of goods record (creates one if it does not exist).
commissionNumberCommission amount
commissionPlanStringCommission plan label (e.g. “14%“)
deductionNumberVendor deduction
payoutNumberVendor payout amount
shippingNumberShipping amount
salesNumberSales amount
salesAfterDiscountNumberSales after discount
taxNumberTax amount
tcsNumberTCS amount
taxOnCommissionsNumberTax on commissions
totalGlobalDeductionsNumberGlobal deductions
discountNumberDiscount 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. 
{
  "items": [
    {
      "lineItemId": 12345678901234,
      "orderId": 98765432101234,
      "fields": { "costOfItem": 15.50 },
      "recalculate": true
    }
  ]
}

​
Response

​
Success

Possible status values: "updated", "recalculate_queued", "updated_and_recalculate_queued".
200
{
  "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.
200
{
  "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

422
{
  "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

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

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

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
  }'