Amend an order | Paid | Documentation

import { PaidClient } from "@paid-ai/paid-node";
const client = new PaidClient({ token: process.env.PAID_API_KEY! });
async function main() {
    const result = await client.amendments.executeOrderAmendment({
        orderId: "ord_5rLZXDFSHNw",
        orderVersion: 3,
        planHash: "a1b2c3d4e5f6",
        intents: [
            {
                type: "updateQuantity",
                orderLineAttributeId: "7aa1b2c3-d4e5-6789-abcd-ef0123456789",
                newQuantity: 3,
                treatment: "prorate",
            },
        ],
    });
    console.log(result.amendmentId, result.version);
}
main().catch((err) => {
    console.error(err);
    process.exit(1);
});

{
  "orderId": "string",
  "amendmentId": "string",
  "version": 1.1,
  "effectiveDate": "string",
  "endedLineIds": [
    "string"
  ],
  "createdLineIds": [
    "string"
  ],
  "plan": {
    "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"
      }
    ]
  }
}

Executes amendment intents against an order. One-shot by default; pass the previewed planHash to require the recomputed plan to match (409 PLAN_CONFLICT on drift).

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.

planHashstringOptional

From preview. When set, execute recomputes the plan and returns 409 PLAN_CONFLICT if billing state has drifted. Omit only for one-shot execute.

Response

200

orderIdstring

Display id of the order.

amendmentIdstring

UUID of the recorded amendment.

versiondouble

Order version after the amendment.

effectiveDatestring

When the amendment took effect.

endedLineIdslist of strings or null

UUIDs of order lines the amendment ended.

createdLineIdslist of strings or null

UUIDs of order lines the amendment created.

planobject or null

The compiled plan that was executed. JSON null when no plan was computed.

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

500

Internal Server Error