# Change subscription items

Creates a quote for requested changes to items and quantities.
This operation applies the requested changes to the subscription when the quote is accepted.

Endpoint: POST /storefront/subscriptions/{id}/change-items
Version: latest
Security: CustomerJWT

## Path parameters:

  - `id` (string, required)
    ID of the resource.

## Request fields (application/json):

  - `effectiveTime` (string)
    Effective time when changes are applied.
    Enum: "now", "next-service-period", "auto"

  - `items` (array)
    Details of items in the subscription.

  - `items.planId` (string, required)
    ID of the plan.
    Example: "plan_0YV7DENSVGDBW9S71XZNNYYQ0X"

  - `items.quantity` (integer)
    Number of units of the product on the given plan.

  - `preview` (boolean)
    Specifies if the quote must be previewed before it is created.
Subscriptions cannot be changed in the preview.
    Example: true

  - `keepTrial` (boolean)
    Specifies whether an active trial remains in the trial state or is upgraded to a paid subscription.
If this field is set to , the trial is converted to a paid subscription.
>  This field applies only to subscriptions that are currently in trial.
    Example: true

  - `autopay` (boolean)
    Specifies if payment attempts for the related subscription are made automatically.
If autopay is enabled, the payment is retrieved from the customer on the renewal date using the payment instrument that is set at ,
or the default payment instrument on the subscription.
    Example: true

  - `includeNextPeriod` (boolean)
    Specifies if next service period amount must be included in the quote.
This is applicable only for  active subscriptions.
    Example: true

## Response 201 fields (application/json):

  - `id` (string)
    ID of the quote.
    Example: "qt_01HXBZMEGPETPHJZH6V4RHBMA8"

  - `type` (string)
    Type of the quote.
When a quote is accepted, quote items and settings are applied to the related order.
    Enum: "change"

  - `acceptanceFulfillment` (array)
    List of  with fulfillment status.

  - `acceptanceFulfillment.condition` (string)
    Enum: "customer", "payment", "organization"

  - `acceptanceFulfillment.isFulfilled` (boolean)

  - `invoiceId` (string)
    ID of the payment invoice.
    Example: "in_0YVF9605RKC62BP14NE2R7V2XT"

  - `status` (string)
    Status of the quote.
    Enum: "draft", "issued", "accepted", "rejected", "canceled", "expired"

  - `websiteId` (string)
    ID of the website.
A website is where an organization obtains a customer.
For more information, see [Obtain an organization ID and website ID](https://www.rebilly.com/docs/settings/organizations-and-websites/#obtain-your-organization-id-and-website-id).
    Example: "web_0YV7DE4Z26DQSA1AC92FBJ7SEG"

  - `customerId` (string)
    ID of the customer resource.
    Example: "cus_0YV7DDSDD1C8DA64KHH2W33CPF"

  - `order` (object)
    Properties of the related order.

  - `order.id` (string)
    ID of the related order.
    Example: "ord_01HVKA5975PJBSQ1SX72G3MSZC"

  - `order.items` (array)
    Items included in the quote.

  - `order.renewalPolicy` (string)
    Specifies if the order retains its current  or resets it to a newly calculated .
    Enum: "reset", "retain"

  - `order.prorated` (boolean)
    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 length.

  - `order.effectiveTime` (string,null)
    Date from which the renewal time for  operations and proration calculations are made.
If this field is omitted, this value defaults to the time of quote acceptance.

  - `order.keepTrial` (boolean)
    Specifies if the order must retain its active trial.
This field is only applicable if  is set to .

  - `order.interimOnly` (boolean)
    Specifies if the quotation invoice must include interim items only.
If this value is set to , all upcoming items are included.

  - `order.usageSettings` (array)
    Usage settings for items with metered billing.

  - `order.usageSettings.productId` (string, required)
    ID of the product to use to transfer usage.
If the  value is ,
and an existing item and a new item are of the same product,
usage can be transferred to the new item.
If a new item of the same product does not exist,
or does not have a metered billing plan,
this transfer is ignored.
    Example: "prod_0YV7DENSVGDBW9S71XZNNYYQ0X"

  - `order.usageSettings.policy` (string, required)
    Policy for removed items that have a metered billing plan.
    Enum: "reset", "transfer"

  - `order.autopay` (boolean,null)
    Specifies if payment attempts for the related order are made automatically.
If autopay is enabled, the payment is retrieved from the customer on the renewal date using the payment instrument that is set at ,
or the default payment instrument on the order.
If this value is , the related order autopay is not affected.

  - `order.shipping` (object)
    Shipping settings.

  - `invoicePreview` (object)
    Preview of the quote invoices.

  - `invoicePreview.currency` (string)
    Currency code in ISO 4217 format.
    Example: "USD"

  - `invoicePreview.initialAmounts` (object)
    Total amounts of the initial invoice.

  - `invoicePreview.initialAmounts.amount` (number)
    Amount of the invoice.

  - `invoicePreview.initialAmounts.subtotalAmount` (number)
    Subtotal amount of the invoice.

  - `invoicePreview.initialAmounts.discountAmount` (number)
    Discount amount that is applied to the invoice.

  - `invoicePreview.initialAmounts.shippingAmount` (number)
    Shipping amount that is applied to the invoice.

  - `invoicePreview.initialAmounts.taxAmount` (number)
    Tax amount that is applied to the invoice.

  - `invoicePreview.recurringAmounts` (object,null)
    Total amounts of the recurring invoice.
This includes recurring items only.
If the quote does not have recurring items, the value of this field is .

  - `invoicePreview.items` (array)
    Invoice items.

  - `invoicePreview.items.quoteItemId` (string)
    ID of the related quote item.
    Example: "qt_itm_01HXCEQNR3F1G2A6RX6HPS3KFY"

  - `invoicePreview.items.type` (string)
    Type of the invoice item.
    Enum: "debit", "credit"

  - `invoicePreview.items.name` (string)
    Name of the invoice item.

  - `invoicePreview.items.description` (string)
    Description of the invoice item.
    Example: "Charge per approved transaction with DCC"

  - `invoicePreview.items.priceDescription` (string)
    Price description of the invoice item.
    Example: "50% of the markup for approved transactions"

  - `invoicePreview.items.unitPrice` (number,null)
    Unit price of the invoice item.

  - `invoicePreview.items.quantity` (integer)
    Quantity of the invoice item.

  - `invoicePreview.items.period` (string,null)
    Date interval of the invoice item.

  - `invoicePreview.items.setupUnitPrice` (number,null)
    Unit price of the invoice item.

  - `invoicePreview.items.trialUnitPrice` (number,null)
    Unit price of the invoice item.

  - `invoicePreview.items.trialPeriod` (string,null)
    Date interval of the invoice item trial.

  - `invoicePreview.items.taxAmount` (number,null)
    Tax amount of the invoice item.

  - `invoicePreview.items.setupTaxAmount` (number,null)
    Tax amount of the setup that is applied to the invoice.

  - `invoicePreview.items.trialTaxAmount` (number,null)
    Tax amount of the trial that is applied to the invoice.

  - `paymentTerms` (string)
    Payment terms for the customer which are displayed on the quote.

  - `expirationTime` (string,null)
    Date and time when the quote expires.
The default expiration time is one month from the time the quote is issued.
In a  state, this field may be .

  - `issuedTime` (string,null)
    Date and time when the quote is issued.

  - `acceptedTime` (string,null)
    Date and time when the quote is accepted.

  - `rejectedTime` (string,null)
    Date and time when the quote is rejected.

  - `canceledTime` (string,null)
    Date and time when the quote is canceled.

  - `createdTime` (string)
    Date and time which is set automatically when the resource is created.

  - `updatedTime` (string)
    Date and time which updates automatically when the resource is updated.

  - `redirectUrl` (string)
    URL to redirect the customer to when a quote is rejected.
The default value is the website URL.

  - `signature` (object)
    Written signature and printed organization name.

  - `signature.showWrittenSignatureLines` (boolean)
    Specifies whether to show written signature lines.

  - `signature.organizationPrintedName` (string,null)
    Printed name of the organization.

  - `tax` (object)
    Taxes.

  - `_links` (array)
    Related links.

  - `_links.href` (string)
    Link URL.

  - `_links.rel` (string)
    Type of link.
If the quote is issued, a customer can be redirected to the  value
to pay the related invoice using one of the methods which are available to the customer.
    Enum: "self", "invoicePaymentFormUrl"

  - `_embedded` (object)
    Embedded objects that are requested by the  query parameter.

  - `_embedded.customer` (object)

  - `_embedded.website` (object)

  - `_embedded.order` (object)

  - `_embedded.invoice` (object)

## 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 404 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.