/
Upsert an order change

Upsert an order change

Request

Creates an order change with a specified ID, or replaces the items of a pending order change. A change that is not pending cannot be updated.

Security
SecretApiKey or JWT
Path
idstring, <= 50 characters^[@~\-\.\w]+$required

ID of the resource.

Bodyapplication/json
orderIdstring, <= 50 charactersrequired

ID of the order.

Example:"ord_01HRF27SATGE4Z6PBJE6PD8328"
applyAtstring

Time when the new items are applied.

  • now: The items change immediately. renewalPolicy, prorated, and effectiveTime apply.
  • nextRenewal: The current items stay until the next renewal. The new items are billed on the next renewal invoice. renewalPolicy, prorated, and effectiveTime are not allowed. A later change for the same order supersedes the pending change. The pending change is locked once the next renewal invoice is issued. To remove a pending change, use the DELETE /order-changes/{id} operation. The new items must differ from the current items. One-time sale items that are already on the order remain. A one-time sale item cannot be added with nextRenewal.
Default:"now"
Enum:"now""nextRenewal"
effectiveTimestring, (date-time)

Date and time when the change is applied. If applyAt is set to now, this value is the date from which the renewal time for resetToRecurring and the proration are calculated. If this field is omitted, this value defaults to the current time. If applyAt is set to nextRenewal, this value is read-only and equals the renewal time of the order.

itemsArray of objects, non-emptyrequired

New items for the order. To remove an item, include the items array and exclude the items you want to remove.

renewalPolicystring

How the service periods and trial state of the order are managed when its items change now. Required when applyAt is now. Not allowed when applyAt is nextRenewal.

Enum ValueDescription
resetToRecurring

Resets the service periods, ends any trial, and converts trial-only items to recurring.

retainRecurring

Retains the current service periods, ends any trial, and converts trial-only items to recurring.

retainTrialThenRecurring

Retains the trial until it ends, then converts the item to recurring. Returns a validation error if the order has no trial.

retainTrialOnly

Retains the trial and keeps the item as trial-only. Returns a validation error if the order is not trial-only.

proratedboolean

Specifies whether to give a pro rata credit for the amount of time remaining between the effectiveTime and the end of the current period. Required when applyAt is now. Not allowed when applyAt is nextRenewal.

If renewalTime is retained by setting renewalPolicy to retainRecurring, retainTrialThenRecurring, or retainTrialOnly, a pro rata debit is also applied for the time between effectiveTime and renewalTime, as a percentage of the normal period size.

curl -i -X PUT \
  'https://www.rebilly.com/_mock/catalog/all/order-changes/{id}' \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "orderId": "ord_01HRF27SATGE4Z6PBJE6PD8328",
    "applyAt": "now",
    "effectiveTime": "2019-08-24T14:15:22Z",
    "items": [
      {
        "plan": {
          "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
        },
        "quantity": 0,
        "usageLimits": {
          "softLimit": {
            "quantity": 0
          },
          "hardLimit": {
            "quantity": 0
          },
          "trialLimit": 20.725
        },
        "excludeFromMrr": true
      }
    ],
    "renewalPolicy": "resetToRecurring",
    "prorated": true
  }'

Responses

Order change updated.

Headers
X-RateLimit-Limitinteger

Total number of rate limit tokens for this request within a rate limit period. For more information, see Rate limits.

Example:3600
X-RateLimit-Remaininginteger

Remaining number of rate limit tokens for this request within the rate limit period. For example, in the sandbox environment, rate limits for non-GET endpoints are set at 3000 requests per 10 minutes.

Example:3600
Bodyapplication/json
idstring, <= 50 charactersread-only

ID of the order change.

Example:"ord_chg_0YV7DES3WPC5J8JD8QTVNZBZQ8"
orderIdstring, <= 50 charactersrequired

ID of the order.

Example:"ord_01HRF27SATGE4Z6PBJE6PD8328"
statusstringread-only

Status of the order change.

Enum ValueDescription
pending

Scheduled to apply at the next renewal.

applied

Items of the order are replaced.

canceled

Canceled before the change is applied.

superseded

Replaced by a later change for the same order.

applyAtstring

Time when the new items are applied.

  • now: The items change immediately. renewalPolicy, prorated, and effectiveTime apply.
  • nextRenewal: The current items stay until the next renewal. The new items are billed on the next renewal invoice. renewalPolicy, prorated, and effectiveTime are not allowed. A later change for the same order supersedes the pending change. The pending change is locked once the next renewal invoice is issued. To remove a pending change, use the DELETE /order-changes/{id} operation. The new items must differ from the current items. One-time sale items that are already on the order remain. A one-time sale item cannot be added with nextRenewal.
Default:"now"
Enum:"now""nextRenewal"
effectiveTimestring, (date-time)

Date and time when the change is applied. If applyAt is set to now, this value is the date from which the renewal time for resetToRecurring and the proration are calculated. If this field is omitted, this value defaults to the current time. If applyAt is set to nextRenewal, this value is read-only and equals the renewal time of the order.

lockedTimestring or null, (date-time)read-only

Date and time when the items of a pending change are billed. After this time, the change is locked and cannot be modified until the renewal.

appliedTimestring or null, (date-time)read-only

Date and time when the items of the order are replaced.

quoteIdstring or null, <= 50 charactersread-only

ID of the quote that is used to create the change. This value is null if the change is not created from a quote.

itemsArray of objects, non-emptyrequired

New items for the order. To remove an item, include the items array and exclude the items you want to remove.

renewalPolicystring

How the service periods and trial state of the order are managed when its items change now. Required when applyAt is now. Not allowed when applyAt is nextRenewal.

Enum ValueDescription
resetToRecurring

Resets the service periods, ends any trial, and converts trial-only items to recurring.

retainRecurring

Retains the current service periods, ends any trial, and converts trial-only items to recurring.

retainTrialThenRecurring

Retains the trial until it ends, then converts the item to recurring. Returns a validation error if the order has no trial.

retainTrialOnly

Retains the trial and keeps the item as trial-only. Returns a validation error if the order is not trial-only.

proratedboolean

Specifies whether to give a pro rata credit for the amount of time remaining between the effectiveTime and the end of the current period. Required when applyAt is now. Not allowed when applyAt is nextRenewal.

If renewalTime is retained by setting renewalPolicy to retainRecurring, retainTrialThenRecurring, or retainTrialOnly, a pro rata debit is also applied for the time between effectiveTime and renewalTime, as a percentage of the normal period size.

createdTimestring, (date-time)(CreatedTime)read-only

Date and time when the resource is created. This value is set automatically when the resource is created.

updatedTimestring, (date-time)(UpdatedTime)read-only

Date and time when the resource is updated. This value is set automatically when the resource is updated.

Response
{
  "id": "ord_chg_0YV7DES3WPC5J8JD8QTVNZBZQ8",
  "orderId": "ord_01HRF27SATGE4Z6PBJE6PD8328",
  "status": "pending",
  "applyAt": "now",
  "effectiveTime": "2019-08-24T14:15:22Z",
  "lockedTime": "2019-08-24T14:15:22Z",
  "appliedTime": "2019-08-24T14:15:22Z",
  "quoteId": "string",
  "items": [
    { … }
  ],
  "renewalPolicy": "resetToRecurring",
  "prorated": true,
  "createdTime": "2019-08-24T14:15:22Z",
  "updatedTime": "2019-08-24T14:15:22Z",
  "_links": [
    { … }
  ]
}