Preview an order amendment | Paid

import { PaidClient } from "@paid-ai/paid-node";
const client = new PaidClient({ token: process.env.PAID_API_KEY! });
async function main() {
    const options = await client.amendments.getOrderAmendmentOptions({
        orderId: "ord_5rLZXDFSHNw",
    });
    const plan = await client.amendments.previewOrderAmendment({
        orderId: "ord_5rLZXDFSHNw",
        orderVersion: options.orderVersion,
        intents: [
            {
                type: "updateQuantity",
                orderLineAttributeId: options.lines[0].attributes[0].orderLineAttributeId,
                newQuantity: 3,
                treatment: "prorate",
            },
        ],
    });
    console.log(plan.planHash, plan.moneyEffects);
}
main().catch((err) => {
    console.error(err);
    process.exit(1);
});

{
  "planVersion": 1.1,
  "orderId": "string",
  "orderVersion": 1.1,
  "effectiveDate": "string",
  "operations": {
    "ends": [
      {
        "orderLineAttributeId": "string",
        "intentIndex": 1
      }
    ],
    "replaces": [
      {
        "orderLineAttributeId": "string",
        "newQuantity": 1,
        "intentIndex": 1,
        "newPricing": null,
        "newEndDate": "string"
      }
    ],
    "copies": [
      {
        "orderLineAttributeId": "string",
        "intentIndex": 1
      }
    ],
    "adds": [
      {
        "intentIndex": 1,
        "lineName": "string",
        "lineType": "STANDARD",
        "productId": "string",
        "productAttributeId": "string",
        "quantity": 1,
        "currency": "string",
        "chargeStub": "none",
        "creditGrant": "full"
      }
    ],
    "orderTerm": {
      "newEndDate": "string",
      "intentIndex": 1
    }
  },
  "moneyEffects": [
    {
      "intentIndex": 1,
      "kind": "prorationCredit",
      "amountMinor": 1.1,
      "currency": "string",
      "cycleStart": "string",
      "cycleEnd": "string",
      "remainingDays": 1.1,
      "totalDaysInCycle": 1.1,
      "billing": "inline",
      "orderLineAttributeId": "string",
      "orderLineId": "string"
    }
  ],
  "creditEffects": [
    {
      "intentIndex": 1,
      "kind": "endEntitlement",
      "at": "string",
      "orderLineAttributeId": "string",
      "creditAmount": 1.1,
      "hasInfiniteCredits": true
    }
  ],
  "treatmentsResolved": [
    {
      "intentIndex": 1,
      "axis": "money",
      "value": "none",
      "source": "request",
      "reason": "string"
    }
  ],
  "stateDiff": [
    {
      "intentIndex": 1,
      "change": "added",
      "orderLineAttributeId": "string",
      "orderLineId": "string",
      "before": {
        "quantity": 1.1,
        "unitPriceMinor": 1.1,
        "totalAmountMinor": 1.1,
        "creditCost": 1.1,
        "creditBenefitAmount": 1.1,
        "hasInfiniteCreditBenefits": true,
        "currency": "string",
        "chargeType": "usage",
        "meteredUsage": true,
        "productId": "string"
      },
      "after": {
        "quantity": 1.1,
        "unitPriceMinor": 1.1,
        "totalAmountMinor": 1.1,
        "creditCost": 1.1,
        "creditBenefitAmount": 1.1,
        "hasInfiniteCreditBenefits": true,
        "currency": "string",
        "chargeType": "usage",
        "meteredUsage": true,
        "productId": "string"
      },
      "governsFrom": "string",
      "nextInvoiceAt": "string"
    }
  ],
  "planHash": "string",
  "usageEffects": [
    {
      "intentIndex": 1,
      "kind": "migrateSummaries",
      "orderLineAttributeId": "string"
    }
  ]
}

Compiles amendment intents into a plan (operations, money effects, credit effects, state diff) without executing. The returned planHash can be passed to the execute endpoint for two-phase, drift-guarded execution.

Authentication

AuthorizationBearer

API Key authentication using Bearer token

Path parameters

orderIdstringRequired

Display id of the order (for example ord_5rLZXDFSHNw). Line and attribute ids in amendment bodies are UUIDs from the options response.

Request

Body

orderVersionintegerRequired>=1

Must match orderVersion from the options response. Returns 409 if the order has been amended since.

intentslist of objectsRequired

At least one intent, discriminated by type.

defaultTreatmentenumOptional

Recurring charges pick next-cycle vs settle-now. Usage price changes pick new usage only vs the whole current period.

Response

200

planVersiondouble

Version of the plan format. Currently 1.

orderIdstring

orderVersiondouble

effectiveDatestring

When the amendment takes effect.

operationsobject

Structural writes the amendment executes.

moneyEffectslist of objects or null

Mid-cycle money the amendment moves.

creditEffectslist of objects or null

Credit entitlement changes the amendment causes.

treatmentsResolvedlist of objects or null

The resolved choice for every treatment axis, with its source.

stateDifflist of objects or null

Before and after billed configuration. Not included in planHash.

planHashstring

Pass this to execute for two-phase drift protection.

usageEffectslist of objects or nullOptional

How un-invoiced usage is handled for repriced metered attributes.

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

500

Internal Server Error