Change an order's items

Change an order's items or quantities and designate when and if there should be pro-rata credits given.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Request Body schema: application/json

Change items request.

required
Array of objects non-empty
Array (non-empty)
required
OriginalPlan (object) or FlexiblePlan (object)
quantity
required
integer

Number of units of the product on the given plan.

renewalPolicy
required
string

The value determines whether the subscription retains its current renewalTime or resets it to a newly calculated renewalTime.

Enum: "reset" "retain"
prorated
required
boolean

Whether or not 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), then a pro rata debit will occur as well, for the amount between the effectiveTime and the renewalTime as a percentage of the normal period size.

effectiveTime
string <date-time>

The date from which the renewal time (for reset operations) and proration calculations are made. If omitted, it will default to the current time.

preview
boolean
Default: false

If set to true, it will not change the subscription. It allows for a way to preview the changes that would be made to a subscription.

keepTrial
boolean
Default: false

If set to true and the subscription order has an active trial, it will use that trial further. Works with 'retain' renewalPolicy only.

Responses
201

Order was changed.

Response Headers
Location
string <uri>

The location of the related resource.

Example: "https://api.rebilly.com/example"
Response Schema: application/json
orderType
required
string
Default: "subscription-order"

Specifies the type of order, a subscription or a one-time purchase.

customerId
required
string <= 50 characters

The customer resource ID. Defaults to UUID v4.

websiteId
required
string <= 50 characters

The website identifier string.

required
Array of objects (OrderItem) non-empty
Array (non-empty)
required
OriginalPlan (object) or FlexiblePlan (object)
planId
string <= 50 characters
Deprecated

The plan identifier string.

quantity
integer

Number of units of the product on the given plan.

revision
integer

Increments with each override change to this specific item.

isModified
boolean

Indicates if the plan information was modified for this subscription.

isGrandfathered
boolean

Indicates if the plan's current revision is greater than this item's plan revision.

Array of ProductEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

id
string <= 50 characters

The order identifier string.

billingStatus
string

The billing status of the most recent invoice. It may help you determine if you should change the service status such as suspending the service.

Enum: "draft" "unpaid" "past-due" "abandoned" "paid" "voided" "refunded" "disputed" "partially-refunded" "partially-paid"
currency
string = 3 characters

The order's currency.

initialInvoiceId
string <= 50 characters

The initial invoice identifier string.

recentInvoiceId
string <= 50 characters

Most recently issued invoice identifier string. It might not be paid yet.

object or null

Order delivery address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

object or null

Order billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

activationTime
string <date-time>

Order activation time.

voidTime
string <date-time>

Order void time.

poNumber
string or null

Purchase order number, will be displayed on the issued invoices.

object (Shipping)

Shipping settings.

calculator
required
string

Shipping calculator.

amount
required
integer

Shipping amount.

notes
string

Notes for the customer which will be displayed on the order invoice.

status
string

The status of the subscription service. A subscription starts in the pending status, and will become active when the service period begins.

Enum: "pending" "active" "canceled" "churned" "paused" "voided" "completed" "trial-ended"
inTrial
boolean

True if the subscription is currently in a trial period.

object

To use plan defaults do not send the trial key, or send a null. value with it.

enabled
boolean

Enable or disable the trial for this subscription. If enabled for plans without trial prices, the trial will be free.

endTime
string <date-time>

Time and date at which the trial ends. If a trial is enabled on this subscription, a value must be provided.

isTrialOnly
boolean
Default: false

Whether a subscription ends after a trial period. Recurring settings are ignored if it's true.

object or null

You can shift issue time and due time of invoices for this subscription. This setting overrides plan settings. To use plan settings, set null. To use multiple plans in one subscription they all must have the same billing period, this property allows to subscribe to different plans.

object (IssueTimeShiftInstruction)

The calculation instruction of billing time. This is used in conjunction with the service period anchor to calculate the time the invoice is issued.

chronology
required
string

The chronology of the billing time relatively to the service period start.

Value: "before"
duration
required
integer >= 1

The number of the units.

required
TimeUnit (string) or TimePluralUnit (string)
object (DueTimeShiftInstruction)
Default: {"duration":1,"unit":"hour"}

The calculation instruction of due time. This is used in conjunction with the billing anchor to calculate due time of invoice. The chronology of due time shift is always after.

duration
required
integer >= 1
Default: 1

The number of the units.

required
TimeUnit (string) or TimePluralUnit (string)
Default: "hour"
object or null

The recurring interval to override plan settings. To use plan settings, set null. To use multiple plans in one subscription they all must have the same recurring period length, this property allows to subscribe to different plans.

object (ServicePeriodAnchorInstruction)
Default: {"method":"immediately"}

Instruction for calculating the service period anchor. This is used in conjunction with the subscription start to calculate the time the service period starts and ends.

method
required
string
Default: "immediately"
day
required
integer [ 1 .. 31 ]

The day of the month when event will be scheduled. Be aware if the month has less days, the last day of the month will be selected.

time
string (TimeIso8601Extended) ^(([01][0-9]|2[0-3]):([0-5][0-9])(?::([0-5][0...

Extended ISO-8601 format of time.

autopay
boolean
Default: true

Autopay determines if a payment attempt will be automatic.

startTime
string or null <date-time>

Subscription start time. When the value is sent as null, it will use the current time. This value can't be in past more than one service period.

endTime
string <date-time>

Subscription end time.

renewalTime
string <date-time>

Subscription renewal time.

rebillNumber
integer

The current period number.

Array of objects

Subscription line items which queue until the next renewal (or interim) invoice is issued for the subscription.

Array
type
required
string

Type of line item.

Enum: "debit" "credit"
unitPriceAmount
required
number <double>

Unit price of the line item.

unitPriceCurrency
required
string = 3 characters

ISO 4217 alphabetic currency code.

quantity
required
integer

Quantity of line item.

description
string

Description of line item.

periodStartTime
string <date-time>

Date-time when the period begins for this item.

periodEndTime
string <date-time>

Date-time when the period ends for this item.

createdTime
string <date-time>

Date-time when the item was added to the subscription.

object

Subtotal of line items in this subscription (signed value). If credits exceed debits, it will be a negative number.

currency
string (CurrencyCode) = 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>
paymentInstrumentId
string or null <= 50 characters

ID of the payment instrument to use for autopay. If not provided or inactive, the customer's default payment instrument will be used.

renewalReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

renewalReminderNumber
integer or null

Number of renewal reminder events triggered.

trialReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

trialReminderNumber
integer or null

Number of renewal reminder events triggered.

organizationId
string <= 50 characters

Organization ID.

canceledTime
string <date-time>

Subscription order canceled time.

canceledBy
string

Canceled by.

Enum: "merchant" "customer" "rebilly"
cancelCategory
string

Cancel category.

Enum: "billing-failure" "did-not-use" "did-not-want" "missing-features" "bugs-or-problems" "do-not-remember" "risk-warning" "contract-expired" "too-expensive" "never-started" … 2 more
cancelDescription
string <= 255 characters

Cancel reason description in free form.

revision
integer

The number of times the order data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

object or null (Risk metadata)

Risk metadata. If null, the value would coalesce to the risk metadata captured when creating the payment token.

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

property name*
additional property
string
object (Browser data)

Browser data used for 3DS and risk scoring.

colorDepth
required
integer [ 1 .. 48 ]

The browser's color depth in bits per pixel obtained using the screen.colorDepth property.

isJavaEnabled
required
boolean

Whether Java is enabled in a browser or not. Value is returned from the navigator.javaEnabled property.

language
required
string <= 8 characters

The browser's language settings returned from the navigator.language property.

screenWidth
required
integer [ 0 .. 65535 ]

The browser's screen width returned from the screen.width property.

screenHeight
required
integer [ 0 .. 65535 ]

The browser's screen height returned from the screen.height property.

timeZoneOffset
required
integer [ -1410 .. 1410 ]

The browser's time zone offset in minutes from UTC. A positive offset indicates the local time is behind UTC, and negative is ahead. Can find it with (new Date()).getTimezoneOffset() property.

object (Extra data)

Third party data used for risk scoring.

kountFraudSessionId
string [ 10 .. 32 ]

Alpha-numeric fraudSessionId as provided by the Kount SDK.

payPalMerchantSessionId
string [ 1 .. 64 ]

MerchantSessionID as generated by the PayPal Fraudnet SDK.

threatMetrixSessionId
string [ 1 .. 128 ] [a-zA-Z0-9_-]+

A temporary identifier that is unique to the visitor's session and passed to ThreatMetrix.

isProxy
boolean

True if customer's ip address is related to proxy.

isVpn
boolean

True if customer's ip address is related to VPN.

isTor
boolean

True if customer's ip address is related to TOR.

isHosting
boolean

True if customer's ip address is related to hosting.

vpnServiceName
string

VPN service name, if available.

isp
string

Internet Service Provider name, if available.

country
string <= 2 characters

Country ISO Alpha-2 code for specified ipAddress.

region
string

Region for specified ipAddress.

city
string

City for specified ipAddress.

latitude
number <double>

Latitude for specified ipAddress.

longitude
number <double>

Longitude for specified ipAddress.

postalCode
string <= 10 characters

Postal code for specified ipAddress.

timeZone
string

Time zone for specified ipAddress.

accuracyRadius
integer

Accuracy radius for specified ipAddress (kilometers).

distance
integer

Distance between IP Address and Billing Address geolocation (kilometers).

hasMismatchedBillingAddressCountry
boolean

True if the billing address country and geo-IP address are not the same.

hasMismatchedBankCountry
boolean

True if the bank country and geo-IP address are not the same.

hasMismatchedTimeZone
boolean

True if the browser time zone and IP address associated time zone are not the same.

hasMismatchedHolderName
boolean

True if the customer's name from billing address and from customer's primary address are not the same.

hasFakeName
boolean

True if the holder name seems fake.

isHighRiskCountry
boolean

True if geo-IP country or the customer's billing country is considered a high risk country.

paymentInstrumentVelocity
integer

Number of transactions for this payment instrument (based on fingerprint) in the last 24 hours.

deviceVelocity
integer

Number of transactions for this device (based on fingerprint) in the last 24 hours.

ipVelocity
integer

Number of transactions for this ip address in the last 24 hours.

emailVelocity
integer

Number of transactions for this email address in the last 24 hours.

billingAddressVelocity
integer

Number of transactions for this billing address in the last 24 hours.

score
integer

Risk score computed per all the factors.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

createdTime
string <date-time>

Order created time.

updatedTime
string <date-time>

Read-only timestamp updates when the resource is updated.

Array of Self (object) or CustomerLink (object) or InitialInvoiceLink (object) or RecentInvoiceLink (object) or WebsiteLink (object) or ApprovalUrlLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
href
required
string

The link URL.

rel
required
string

The link type.

Value: "self"
Array of RecentInvoiceEmbed (object) or InitialInvoiceEmbed (object) or CustomerEmbed (object) or WebsiteEmbed (object) or LeadSourceEmbed (object) or ShippingRateEmbed (object) or PaymentInstrumentEmbed (object) or UpcomingInvoiceEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

Recent Invoice object.

object (Invoice)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/subscriptions/{id}/change-items
Request samples
application/json
{
  • "items": [
    ],
  • "renewalPolicy": "reset",
  • "prorated": true,
  • "effectiveTime": "2019-08-24T14:15:22Z",
  • "preview": false,
  • "keepTrial": false
}
Response samples
application/json
{
  • "orderType": "subscription-order",
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "billingStatus": "draft",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "currency": "USD",
  • "initialInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "recentInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "activationTime": "2019-08-24T14:15:22Z",
  • "voidTime": "2019-08-24T14:15:22Z",
  • "poNumber": "PO123456",
  • "shipping": {
    },
  • "notes": "string",
  • "status": "pending",
  • "inTrial": true,
  • "trial": {
    },
  • "isTrialOnly": false,
  • "invoiceTimeShift": null,
  • "recurringInterval": null,
  • "autopay": true,
  • "startTime": null,
  • "endTime": "2019-08-24T14:15:22Z",
  • "renewalTime": "2019-08-24T14:15:22Z",
  • "rebillNumber": 0,
  • "lineItems": [
    ],
  • "lineItemSubtotal": {
    },
  • "paymentInstrumentId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "renewalReminderTime": "2019-08-24T14:15:22Z",
  • "renewalReminderNumber": 0,
  • "trialReminderTime": "2019-08-24T14:15:22Z",
  • "trialReminderNumber": 0,
  • "organizationId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "canceledTime": "2019-08-24T14:15:22Z",
  • "canceledBy": "merchant",
  • "cancelCategory": "billing-failure",
  • "cancelDescription": "string",
  • "revision": 0,
  • "riskMetadata": null,
  • "customFields": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": [
    ]
}