---
title: "Schedule a plan change with proration"
method: POST
path: "/orders/{orderId}/schedule-plan-change"
tags: ["orders"]
---

# Schedule a plan change with proration

`POST /orders/{orderId}/schedule-plan-change`

## Request

- Base URL: `https://api.agentpaid.io/api/v1`
- URL: `https://api.agentpaid.io/api/v1/orders/{orderId}/schedule-plan-change`
- Auth: HTTP bearer

Schedules a plan upgrade or downgrade for an order with automatic proration calculation. Credits are applied for the unused portion of the current billing period.

## Path parameters

- `orderId` string, required

## Request body

- ProrationUpgradeRequest: Request to schedule a plan change with proration
  - `orderVersion` integer, required: The current version of the order (for optimistic locking)
  - `effectiveDate` string, date-time, required: The date when the plan change should take effect (ISO 8601 format)
  - `updatedOrderLineAttributes` ProrationAttributeUpdate[], required: The list of order line attributes to update
    - `orderLineAttributeId` string, uuid, required: The ID of the order line attribute to update
    - `newPricing` object, required: The new pricing configuration
    - `newQuantity` number, double: Optional new quantity for the attribute

## Response `200`

Plan change scheduled successfully

- ProrationUpgradeResponse: Response after successfully scheduling a plan change
  - `orderId` string, uuid, required: The ID of the order
  - `amendmentId` string, uuid, required: The ID of the amendment record
  - `version` integer, required: The new version of the order after the amendment
  - `effectiveDate` string, date-time, required: The effective date of the plan change
  - `endedLineIds` string[], required: IDs of order lines that were ended
  - `createdLineIds` string[], required: IDs of new order lines that were created
  - `creditLineIds` string[], required: IDs of credit lines that were created
  - `prorationDetails` ProrationDetail[], required: Detailed proration calculations for each updated attribute
    - `oldAttributeId` string, uuid
    - `newAttributeId` string, uuid
    - `creditLineId` string, uuid
    - `oldPrice` number, double
    - `newPrice` number, double
    - `creditAmount` number, double: The credit amount applied for the unused portion
    - `remainingDays` integer: Number of days remaining in the current billing cycle
    - `totalDaysInCycle` integer: Total number of days in the billing cycle

## Other responses

- `400`: Bad request - Invalid order version, effective date, or attributes
- `403`: Forbidden - Invalid or missing API key
- `404`: Order not found

---

[API](https://skmtc.dev/paid/apis/paid-2.md) - [All operations](https://skmtc.dev/paid/apis/paid-2/llms.txt) - [OpenAPI document](https://skmtc.dev/paid/apis/paid-2/revisions/dbdf4a60ed27?raw)