# Change subscription order items Changes subscription order items or quantities, and designates if or when pro-rata credits should be given. Endpoint: POST /subscriptions/{id}/change-items Version: latest Security: SecretApiKey, JWT ## Path parameters: - `id` (string, required) ID of the resource. ## Query parameters: - `expand` (string) Expand a response to receive a full related object in the path. To expand multiple objects, use a comma-separated list. Example: . Available arguments are: - - - - - - - - For more information, see Expand to include embedded objects. ## Request fields (application/json): - `items` (array, required) Details of items in the order. - `items.plan` (any, required) Plan details. - `items.quantity` (integer) Number of units of the product on the given plan. - `items.usageLimits` (object) Specifies the soft and hard usage limit thresholds for an item with a metered billing plan. This value is ignored when the plan is not metered. - `items.usageLimits.softLimit` (object) Defines thresholds for notification purposes. For example, to notify the customer that their usage is near the hard limit of their metered billing plan. This notification informs the customer so that they can upgrade their plan before the hard limit is reached. When the reported usage reaches 75%, 90%, and 100% of the configured limit a specific event is triggered. To notify the customer, a webhook and notification can be configured for this event. This field is useful for accounting and customer success purposes. The usage of metered billing plans can still be reported if the soft limit is reached. - `items.usageLimits.softLimit.quantity` (integer) Usage limit quantity. - `items.usageLimits.softLimit.amount` (number) Usage limit amount in the currency of the order. - `items.usageLimits.hardLimit` (object) Defines a limit where the customer can no longer use the service. Hard limits are used in addition to soft limits. When a soft limit is reached, a customer may receive a notification but the service can still be provided up to the hard limit value so that the customer can upgrade their plan. When the reported usage reaches the configured limit, a specific event is triggered. To notify the customer in the merchant system, or block a service, a webhook and notification can be configured for this event. When the total usage reaches the hard limit quantity, or amount values, metered billing plan usages can no longer be reported. - `items.usageLimits.trialLimit` (any) Defines a usage cap during the trial period of a subscription. This limit is enforced only while the subscription is in its trial phase. When the reported usage reaches the configured trial limit, an event called 'trial-usage-limit-reached' is triggered. To notify the customer or restrict access to the service, a webhook and notification can be configured for this event. Once the trial limit is reached, additional usage cannot be reported unless the trial ends. Example: 20.725 - `renewalPolicy` (string, required) Specifies if the subscription retains its current or resets it to a newly calculated . Enum: "reset", "retain" - `prorated` (boolean, required) Specifies whether to give a pro rata credit for the amount of time remaining between the and the end of the current period. In addition, if the is retained, by setting the to , a pro rata debit occurs for the amount between the and the as a percentage of the normal period size. - `effectiveTime` (string) Date from which the renewal time for operations and proration calculations are made. If this field is omitted, this value defaults to the current time. - `preview` (boolean) Specifies if changes to the subscription can be previewed. Subscriptions cannot be changed in preview. - `keepTrial` (boolean) Specifies if the subscription order must retain its active trial. This field is only applicable if is set to . - `ignoreRecurring` (boolean) Specifies if the subscription order must ignore the recurring settings of items in the order. This field is only applicable if the subscription is trial-only and the value is . For more information, see [Trial-only subscription](https://www.rebilly.com/docs/dev-docs/subscriptions#trial-only-subscription). ## Response 401 fields (application/json): - `status` (integer) HTTP status code. - `type` (string) Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank". - `title` (string) Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem. - `detail` (string) Human-readable explanation that is specific to this occurrence of the problem. - `instance` (string) URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. ## Response 403 fields (application/json): - `status` (integer) HTTP status code. - `type` (string) Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank". - `title` (string) Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem. - `detail` (string) Human-readable explanation that is specific to this occurrence of the problem. - `instance` (string) URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. ## Response 422 fields (application/json): - `status` (integer) HTTP status code. - `type` (string) Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank". - `title` (string) Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem. - `detail` (string) Human-readable explanation that is specific to this occurrence of the problem. - `instance` (string) URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. - `invalidFields` (array) Invalid field details. Example: [{"field":"field1","message":"field1 is invalid"},{"field":"subObject.field2","message":"field2 is invalid"},{"field":"subObject.field2","message":"another error in the field2"}] - `invalidFields.field` (string) Name of the field. Dot notation is used for nested object field names. - `invalidFields.message` (string) Message field. ## Response 429 fields (application/json): - `type` (string) Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank". Example: "about:blank" - `title` (string) Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem. Example: "Rate Limit Exceeded" - `status` (integer) HTTP status code. - `detail` (string) Human-readable explanation that is specific to this occurrence of the problem. Example: "A request cannot be executed because the user has sent too many requests within a certain period of time" - `instance` (string) URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.