---
title: "Upgrade customer to a new plan"
method: POST
path: "/plans/upgrade"
tags: ["plans"]
---

# Upgrade customer to a new plan

`POST /plans/upgrade`

## Request

- Base URL: `https://api.agentpaid.io/api/v1`
- URL: `https://api.agentpaid.io/api/v1/plans/upgrade`
- Auth: HTTP bearer

Upgrades a customer from one plan to another with automatic proration. Credits are applied for the unused portion of the current billing period, and the order is updated with the new plan's pricing.

## Query parameters

- `customerExternalId` string, required
- `oldPlanId` string, uuid, required
- `newPlanId` string, uuid, required

## Response `200`

Plan upgrade completed 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 - Missing required parameters, no matching attributes, or invalid plan configuration
- `403`: Forbidden - Invalid or missing API key
- `404`: Plan, customer, or 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)