POST /subscriptions/{id}/change-items

Changes subscription order items or quantities, and designates if or when pro-rata credits should be given.

Servers

https://api-sandbox.rebilly.com/organizations/{organizationId}
https://api.rebilly.com/organizations/{organizationId}

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Query parameters

Name Type Required Description

Name	Type	Required	Description
`expand`	String	No	Expand a response to receive a full related object in the `_embedded` path. To expand multiple objects, use a comma-separated list. Example: `expand=recentInvoice,initialInvoice`. Available arguments are: `customer` `leadSource` `website` `shippingRate` `initialInvoice` `recentInvoice` `upcomingInvoice` `paymentInstrument` For more information, see Embedded resources.

expand

String

Expand a response to receive a full related object in the _embedded path.

To expand multiple objects, use a comma-separated list. Example: expand=recentInvoice,initialInvoice.

Available arguments are:

customer
leadSource
website
shippingRate
initialInvoice
recentInvoice
upcomingInvoice
paymentInstrument

For more information, see Embedded resources.

Request body fields

Name	Type	Required	Description
`prorated`	Boolean	Yes	Specifies whether to give a pro rata credit for the amount of time remaining between the `effectiveTime` and the end of the current period. In addition, if the `renewalTime` is retained, by setting the `renewalPolicy` to `retain`, a pro rata debit occurs for the amount between the `effectiveTime` and the `renewalTime` as a percentage of the normal period size.
`preview`	Boolean	No	Specifies if changes to the subscription can be previewed. Subscriptions cannot be changed in preview. Default value: false
`items[]`	Array	Yes	Details of items in the order.
`items[].usageLimits`	Object	No	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	No	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.amount`	Number	No	Usage limit amount in the currency of the order.
`items[].usageLimits.softLimit.quantity`	Integer	No	Usage limit quantity.
`items[].usageLimits.trialLimit`		No	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.
`items[].usageLimits.hardLimit`	Object	No	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.hardLimit.amount`	Number	No	Usage limit amount in the currency of the order.
`items[].usageLimits.hardLimit.quantity`	Integer	No	Usage limit quantity.
`items[].quantity`	Integer	No	Number of units of the product on the given plan.
`items[].plan`		Yes	Plan details.
`effectiveTime`	String	No	Date from which the renewal time for `reset` operations and proration calculations are made. If this field is omitted, this value defaults to the current time.
`keepTrial`	Boolean	No	Specifies if the subscription order must retain its active trial. This field is only applicable if `renewalPolicy` is set to `retain`. Default value: false
`renewalPolicy`	String	Yes	Specifies if the subscription retains its current `renewalTime` or resets it to a newly calculated `renewalTime`. Valid values: `"retain"` `"reset"`
`ignoreRecurring`	Boolean	No	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 `keepTrial` value is `true`. For more information, see Trial-only subscription. Default value: false

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.