Change order items

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

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

ID of the resource.

Request Body schema: application/json

Change items request.

required
Array of objects non-empty

Item details.

Array (non-empty)
required
OriginalPlan (object) or (FlexiblePlan (OneTimeSalePlan (object) or SubscriptionOrderPlan (object) or TrialOnlyPlan (object)))

Plan details.

quantity
required
integer

Number of units of the product on the given plan.

renewalPolicy
required
string

Specifies if the subscription retains its current renewalTime or resets it to a newly calculated renewalTime.

Enum: "reset" "retain"
prorated
required
boolean

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.

effectiveTime
string <date-time>

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.

preview
boolean
Default: false

Specifies if changes to the subscription can be previewed. Subscriptions cannot be changed in preview.

keepTrial
boolean
Default: false

Specifies if the subscription order must retain its active trial. This field is only applicable if renewalPolicy is set to retain.

Responses
201

Order changed.

Response Headers
Location
string <uri>

Location of the related resource.

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

Specifies the type of order. An order may be a subscription or a one-time purchase.

customerId
required
string (CustomerId) <= 50 characters

Customer resource ID.

websiteId
required
string <= 50 characters

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

required
Array of objects (OrderItem) non-empty

Item details.

Array (non-empty)
required
OriginalPlan (object) or (FlexiblePlan (OneTimeSalePlan (object) or SubscriptionOrderPlan (object) or TrialOnlyPlan (object)))

Plan details.

planId
string <= 50 characters
Deprecated

ID of the plan.

quantity
integer

Number of product units in the specified plan.

revision
integer

Revision number that increments with each overriding change to this specific plan item.

isModified
boolean

Specifies if the plan information is modified for this subscription.

isGrandfathered
boolean

Specifies if the current plan revision number is greater than the plan item revision number.

object

Embedded objects that are requested by the expand query parameter.

id
string <= 50 characters

ID of the order.

renewalReminderTime
string or null <date-time>

Date and time when the renewal reminder event triggers.

renewalReminderNumber
integer or null

Number of triggered renewal reminder events.

trialReminderTime
string or null <date-time>

Date and time when the trial reminder event triggers.

trialReminderNumber
integer or null

Number of triggered trial reminder events.

abandonReminderTime
string or null <date-time>

Date and time when the abandon order reminder event triggers.

abandonReminderNumber
integer or null

Number of abandon order reminder events that are triggered.

organizationId
string <= 50 characters

Unique organization identifier. An organization is an entity that represents a company. For more information, see Obtain an organization ID.

status
string

Status of the subscription service. A subscription starts in the pending status, and becomes active when the service period begins.

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

Specifies if the subscription is currently in a trial period.

object

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

enabled
boolean

Specifies if there is a trial for this subscription. Plans without trial prices are free trials.

endTime
string or null <date-time>

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

isTrialOnly
boolean
Default: false

Specifies if a subscription ends after a trial period. If this value is true, recurring settings are ignored.

object or null

Shifts issue time and due time of invoices for this subscription.

This setting overrides plan settings. To use plan settings, set this value to null.

To use multiple plans in one subscription, all plans must have the same billing period, this property enables the customer to subscribe to different plans.

object (IssueTimeShiftInstruction)

Calculation instruction of the billing time.

This is used in conjunction with the service period anchor to calculate the time at which the invoice is issued. For more information, see Service period anchor, billing timing, and invoice time shift.

chronology
required
string

Sequential order of the billing time relative to the start of the service period.

Value: "before"
duration
required
integer >= 1

Amount of time by which to move the invoice issue time or date.

required
TimeUnit (string) or TimePluralUnit (string)

Unit of time.

object (DueTimeShiftInstruction)
Default: {"duration":1,"unit":"hour"}

Calculation instruction of the invoice due time.

This is used in conjunction with the billing anchor to calculate when an invoice is due for payment. For more information, see Service period anchor, billing timing, and invoice time shift.

The sequential order of due time shift is always after the due date.

duration
required
integer >= 1
Default: 1

Amount of time by which to move the invoice due time or date.

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

Unit of time.

object or null

Recurring interval to override plan settings. To use plan settings, set this value to null.

To use multiple plans in one subscription, all plans must have the same recurring period length.

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

Instruction for calculating the service period anchor.

The service period anchor is used, in conjunction with the subscription start time, to calculate when the service period starts and ends.

day
required
integer [ 1 .. 31 ]

Day of the month in which the event occurs. If the month has less days, the last day of the month is selected.

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

Extended ISO-8601 format of time.

autopay
boolean
Default: true

Specifies if payment attempts 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 paymentInstrumentId, or the default payment instrument on the subscription.

startTime
string or null <date-time>

Date and time when the subscription starts. If this value is null, the current time is used. This value cannot be more than one service period in the past.

endTime
string or null <date-time>

Date and time when the subscription ends.

renewalTime
string or null <date-time>

Date and time when the subscription renews.

rebillNumber
integer or null

Current billing period number.

Array of objects (UpcomingInvoiceItem)

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

Array
type
required
string

Type of invoice line item.

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

Unit price of the line item.

unitPriceCurrency
required
string (CurrencyCode) = 3 characters

Currency code in ISO 4217 format.

quantity
required
integer

Quantity of the line item.

description
string <= 1000 characters

Description of the line item.

periodStartTime
string <date-time>

Date and time when the period begins for this item.

periodEndTime
string <date-time>

Date and time when the period ends for this item.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

object

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

currency
string (CurrencyCode) = 3 characters

Currency code in ISO 4217 format.

amount
number <double>

Amount of the subtotal.

paymentInstrumentId
string or null <= 50 characters

ID of the payment instrument to use for autopay. If this value is not provided, or if the payment instrument is inactive, the customer's default payment instrument is used.

billingStatus
string

Billing status of the most recent invoice. This value may help you to determine if you should change the service status of the service, such as suspending the service.

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

Currency of the order.

initialInvoiceId
string or null <= 50 characters

ID of the initial invoice.

recentInvoiceId
string or null <= 50 characters

ID of the most recently issued invoice. The invoice might not be paid yet.

object or null

Delivery address of the order.

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

Contact's first name.

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

Contact's last name.

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

Contact's organization.

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

First line of the contact's street address.

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

Second line of the contact's street address.

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

Contact's city of residence.

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

Contact's region of residence.

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

Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see ISO.org.

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

Contact's postal code.

Array of objects (ContactPhoneNumbers)

List of phone numbers associated with the contact.

Array
label
required
string <= 45 characters

Phone number label or name.

value
required
string <= 50 characters

Phone number value.

primary
boolean

Specifies if the phone number is the contact's primary phone number.

Array of objects (ContactEmails)

List of email addresses associated with the contact.

Array
label
required
string <= 45 characters

Email label or name.

value
required
string <email> <= 255 characters

Email address value.

primary
boolean

Specifies if the email address is the contact's primary email address.

dob
string or null <date>

Contact's date of birth in ISO-8601 YYYY-MM-DD format.

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

Contact's job title.

hash
string <= 40 characters

Use this value to compare contacts for identical attribute values.

object or null

Billing address of the order.

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

Contact's first name.

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

Contact's last name.

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

Contact's organization.

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

First line of the contact's street address.

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

Second line of the contact's street address.

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

Contact's city of residence.

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

Contact's region of residence.

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

Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see ISO.org.

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

Contact's postal code.

Array of objects (ContactPhoneNumbers)

List of phone numbers associated with the contact.

Array
label
required
string <= 45 characters

Phone number label or name.

value
required
string <= 50 characters

Phone number value.

primary
boolean

Specifies if the phone number is the contact's primary phone number.

Array of objects (ContactEmails)

List of email addresses associated with the contact.

Array
label
required
string <= 45 characters

Email label or name.

value
required
string <email> <= 255 characters

Email address value.

primary
boolean

Specifies if the email address is the contact's primary email address.

dob
string or null <date>

Contact's date of birth in ISO-8601 YYYY-MM-DD format.

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

Contact's job title.

hash
string <= 40 characters

Use this value to compare contacts for identical attribute values.

activationTime
string or null <date-time>

Date and time when the order is activated.

voidTime
string or null <date-time>

Date and time when the order is voided.

abandonTime
string or null <date-time>

Date and time when the pending order is automatically abandoned. If this value is not passed during order creation, a pending order TTL setting is used to calculate the value.

poNumber
string or null

Purchase order number displayed on the issued invoices.

object (Shipping)

Shipping settings.

amount
required
integer

Shipping amount.

calculator
required
string

Shipping calculator.

notes
string

Notes for the customer displayed on the order invoice.

canceledBy
string or null

Specifies who initiated the cancellation.

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

Category of the cancellation.

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" … 3 more
cancelDescription
string or null <= 255 characters

Description of the cancellation reason in free form.

revision
integer

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 this value is null, this field uses risk metadata that is captured when creating the payment token.

ipAddress
string or null <ipv4 or ipv6>

Customer's IP address.

fingerprint
string or null <= 50 characters

Customer's device fingerprint. A device fingerprint is a unique token that is used to identify the customer. The device fingerprint is generated based on device attributes, such as: hardware, software, IP address, language, browser, and more.

object or null

HTTP headers.

property name*
additional property
string
object or null

Browser data used for 3D Secure and risk scoring.

colorDepth
required
integer [ 1 .. 48 ]

Browser color depth in bits per pixel. This value is obtained using the screen.colorDepth property.

isJavaEnabled
required
boolean

Specifies if Java is enabled in a browser. This value is obtained from the navigator.javaEnabled property.

language
required
string <= 8 characters

Browser language settings. This value is obtained from the navigator.language property.

screenWidth
required
integer [ 0 .. 65535 ]

Width of the browser screen. This value is obtained from the screen.width property.

screenHeight
required
integer [ 0 .. 65535 ]

Height of the browser screen. This value is obtained from the screen.height property.

timeZoneOffset
required
integer [ -1410 .. 1410 ]

Browser time zone offset in minutes from UTC. A positive offset indicates that the local time is behind UTC. A negative offset indicates that the local time is ahead of UTC. You can find this value using the (new Date()).getTimezoneOffset() property.

object or null

Third-party data used for risk scoring.

kountFraudSessionId
string [ 10 .. 32 ]

Alpha-numeric fraudSessionId as provided by the Kount SDK.

payPalMerchantSessionId
string [ 1 .. 64 ]

PayPal MerchantSessionID as generated by the PayPal Fraudnet SDK.

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

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

isProxy
boolean

Specifies if the customer's IP address is related to a proxy.

isVpn
boolean

Specifies if the customer's IP address is related to a VPN.

isTor
boolean

Specifies if the customer's IP address is related to TOR.

isHosting
boolean

Specifies if the customer's IP address is related to hosting.

vpnServiceName
string or null

VPN service name, if available.

isp
string or null

Internet Service Provider (ISP) name, if available.

country
string or null <= 2 characters

Country ISO Alpha-2 code of the specified IP address.

region
string or null

Region of the specified IP address.

city
string or null

City of the specified IP address.

latitude
number <double>

Latitude of the specified IP address.

longitude
number or null <double>

Longitude of the specified IP address.

postalCode
string or null <= 10 characters

Postal code of the specified IP address.

timeZone
string or null

Time zone of the specified IP address.

accuracyRadius
integer or null

Accuracy radius of the specified IP address, in kilometers.

distance
integer or null

Distance between the customer's IP address and the billing address geolocation, in kilometers.

hasMismatchedBillingAddressCountry
boolean

Specifies if the customer's billing address country and geo-IP address are not the same.

hasMismatchedBankCountry
boolean

Specifies if the customer's bank country and geo-IP address are not the same.

hasMismatchedTimeZone
boolean

Specifies if the customer's browser time zone and the IP address associated time zone are not the same.

hasMismatchedHolderName
boolean

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

hasFakeName
boolean

Specifies if the holder name seems fake.

isHighRiskCountry
boolean

Specifies if the 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.

declinedPaymentInstrumentVelocity
integer

Number of declined transactions for this payment instrument 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

Computed risk score based on all factors.

customFields
object (ResourceCustomFields)
Default: {}

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

Array of objects

Related links.

Array
href
string

Link URL.

rel
string

Type of link.

Enum: "self" "website" "customer" "initialInvoice" "recentInvoice" "approvalUrl" "attachments"
object

Embedded objects that are requested by the expand query parameter.

recentInvoice
object
initialInvoice
object
customer
object
website
object
leadSource
object
shippingRate
object
paymentInstrument
object
upcomingInvoice
object
401

Unauthorized access. Invalid credentials used.

403

Access forbidden.

422

Invalid data 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
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "orderType": "subscription-order",
  • "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  • "renewalReminderTime": "2019-08-24T14:15:22Z",
  • "renewalReminderNumber": 0,
  • "trialReminderTime": "2019-08-24T14:15:22Z",
  • "trialReminderNumber": 0,
  • "abandonReminderTime": "2019-08-24T14:15:22Z",
  • "abandonReminderNumber": 0,
  • "organizationId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "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",
  • "billingStatus": "draft",
  • "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
  • "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",
  • "abandonTime": "2019-08-24T14:15:22Z",
  • "poNumber": "PO123456",
  • "shipping": {
    },
  • "notes": "string",
  • "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": {
    }
}