Orders

An order applies a plan's template to create invoice(s) for a customer, optionally at the appropriate scheduled intervals. A subscription order may also determine if the payment is collected automatically (with autopay set true).

Retrieve a list of orders

Retrieve a list of orders.

Request
Security:
query Parameters
filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

q
string

The partial search of the text fields.

expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. To expand multiple objects, it accepts a comma-separated list of objects (example: expand=recentInvoice,initialInvoice). Available arguments are:

  • recentInvoice
  • initialInvoice
  • customer
  • website

See the expand guide for more info.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200A list of subscriptions was retrieved successfully.
Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
id
string <= 50 characters

The order identifier string.

orderType
required
string
Default: "subscription-order"

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

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: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"
websiteId
required
string <= 50 characters

The website identifier string.

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.

required
Array of objects non-empty
object or null

Order delivery address.

object or null

Order billing address.

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.

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" "suspended" "paused" "abandoned" "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.

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

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.

object

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

customerId
required
string <= 50 characters

The customer identifier string.

renewalReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

renewalReminderNumber
integer

Number of renewal reminder events triggered.

trialReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

trialReminderNumber
integer

Number of renewal reminder events triggered.

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" "switched-plan" "other"
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. If null, the value would coalesce to the risk metadata captured when creating the payment token.

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>

Order updated time.

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

The links related to resource.

Array of RecentInvoiceEmbed (object) or InitialInvoiceEmbed (object) or CustomerEmbed (object) or WebsiteEmbed (object) or LeadSourceEmbed (object) non-empty

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

401Unauthorized access, invalid credentials was used.
403Access forbidden.
get/subscriptions
Request samples
$subscriptions = $client->subscriptions()->search([
    'filter' => 'customerId:testCustomerId',
]);
Response samples
application/json
[
  • {
    }
]

Create an order

Create an order. Consider using the upsert. operation to accomplish this task.

Request
Security:
query Parameters
expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. To expand multiple objects, it accepts a comma-separated list of objects (example: expand=recentInvoice,initialInvoice). Available arguments are:

  • recentInvoice
  • initialInvoice
  • customer
  • website

See the expand guide for more info.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Order resource.

orderType
required
string
Default: "subscription-order"

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

websiteId
required
string <= 50 characters

The website identifier string.

required
Array of objects non-empty
object or null

Order delivery address.

object or null

Order billing address.

couponIds
Array of strings or null

A list of coupons to redeem on the customer and restrict to this subscription. Read more about coupons here.

This parameter respects the following logic:

  • When not passed then applied coupons will not be changed.

  • When empty array passed then all applied coupon redemptions will be canceled.

  • When list of coupons is passed then not applied yet coupons will be applied, already applied coupons will not change their state, applied coupons that are not presented in passed list will be canceled.

If list of applied coupons on pending order will be changed due to this param during update order, Invoice for the order will be reissued.

poNumber
string or null

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

object

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

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

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.

renewalTime
string <date-time>

Subscription renewal time.

customerId
required
string <= 50 characters

The customer identifier string.

object or null

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

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).

Responses
201Order was created.
Response Schema: application/json
id
string <= 50 characters

The order identifier string.

orderType
required
string
Default: "subscription-order"

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

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: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"
websiteId
required
string <= 50 characters

The website identifier string.

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.

required
Array of objects non-empty
object or null

Order delivery address.

object or null

Order billing address.

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.

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" "suspended" "paused" "abandoned" "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.

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

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.

object

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

customerId
required
string <= 50 characters

The customer identifier string.

renewalReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

renewalReminderNumber
integer

Number of renewal reminder events triggered.

trialReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

trialReminderNumber
integer

Number of renewal reminder events triggered.

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" "switched-plan" "other"
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. If null, the value would coalesce to the risk metadata captured when creating the payment token.

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>

Order updated time.

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

The links related to resource.

Array of RecentInvoiceEmbed (object) or InitialInvoiceEmbed (object) or CustomerEmbed (object) or WebsiteEmbed (object) or LeadSourceEmbed (object) non-empty

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

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid data was sent.
post/subscriptions
Request samples
application/json
{
  • "orderType": "subscription-order",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "couponIds": [
    ],
  • "poNumber": "PO123456",
  • "trial": {
    },
  • "isTrialOnly": false,
  • "invoiceTimeShift": null,
  • "recurringInterval": null,
  • "autopay": true,
  • "startTime": null,
  • "renewalTime": "2019-08-24T14:15:22Z",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "riskMetadata": null,
  • "customFields": {
    }
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "orderType": "subscription-order",
  • "billingStatus": "unpaid",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "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",
  • "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": {
    },
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "renewalReminderTime": "2019-08-24T14:15:22Z",
  • "renewalReminderNumber": 0,
  • "trialReminderTime": "2019-08-24T14:15:22Z",
  • "trialReminderNumber": 0,
  • "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": [
    ]
}

Retrieve an order

Retrieve an order with specified identifier string.

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

The resource identifier string.

query Parameters
expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. To expand multiple objects, it accepts a comma-separated list of objects (example: expand=recentInvoice,initialInvoice). Available arguments are:

  • recentInvoice
  • initialInvoice
  • customer
  • website

See the expand guide for more info.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200Order was retrieved successfully.
Response Schema: application/json
id
string <= 50 characters

The order identifier string.

orderType
required
string
Default: "subscription-order"

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

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: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"
websiteId
required
string <= 50 characters

The website identifier string.

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.

required
Array of objects non-empty
object or null

Order delivery address.

object or null

Order billing address.

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.

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" "suspended" "paused" "abandoned" "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.

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

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.

object

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

customerId
required
string <= 50 characters

The customer identifier string.

renewalReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

renewalReminderNumber
integer

Number of renewal reminder events triggered.

trialReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

trialReminderNumber
integer

Number of renewal reminder events triggered.

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" "switched-plan" "other"
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. If null, the value would coalesce to the risk metadata captured when creating the payment token.

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>

Order updated time.

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

The links related to resource.

Array of RecentInvoiceEmbed (object) or InitialInvoiceEmbed (object) or CustomerEmbed (object) or WebsiteEmbed (object) or LeadSourceEmbed (object) non-empty

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

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
get/subscriptions/{id}
Request samples
$subscription = $client->subscriptions()->load('subscriptionId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "orderType": "subscription-order",
  • "billingStatus": "unpaid",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "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",
  • "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": {
    },
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "renewalReminderTime": "2019-08-24T14:15:22Z",
  • "renewalReminderNumber": 0,
  • "trialReminderTime": "2019-08-24T14:15:22Z",
  • "trialReminderNumber": 0,
  • "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": [
    ]
}

Upsert an order with predefined ID

Create or update an order with predefined identifier string.

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

The resource identifier string.

query Parameters
expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. To expand multiple objects, it accepts a comma-separated list of objects (example: expand=recentInvoice,initialInvoice). Available arguments are:

  • recentInvoice
  • initialInvoice
  • customer
  • website

See the expand guide for more info.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Order resource.

orderType
required
string
Default: "subscription-order"

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

websiteId
required
string <= 50 characters

The website identifier string.

required
Array of objects non-empty
object or null

Order delivery address.

object or null

Order billing address.

couponIds
Array of strings or null

A list of coupons to redeem on the customer and restrict to this subscription. Read more about coupons here.

This parameter respects the following logic:

  • When not passed then applied coupons will not be changed.

  • When empty array passed then all applied coupon redemptions will be canceled.

  • When list of coupons is passed then not applied yet coupons will be applied, already applied coupons will not change their state, applied coupons that are not presented in passed list will be canceled.

If list of applied coupons on pending order will be changed due to this param during update order, Invoice for the order will be reissued.

poNumber
string or null

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

object

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

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

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.

renewalTime
string <date-time>

Subscription renewal time.

customerId
required
string <= 50 characters

The customer identifier string.

object or null

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

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).

Responses
200Order was updated.
Response Schema: application/json
id
string <= 50 characters

The order identifier string.

orderType
required
string
Default: "subscription-order"

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

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: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"
websiteId
required
string <= 50 characters

The website identifier string.

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.

required
Array of objects non-empty
object or null

Order delivery address.

object or null

Order billing address.

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.

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" "suspended" "paused" "abandoned" "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.

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

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.

object

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

customerId
required
string <= 50 characters

The customer identifier string.

renewalReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

renewalReminderNumber
integer

Number of renewal reminder events triggered.

trialReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

trialReminderNumber
integer

Number of renewal reminder events triggered.

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" "switched-plan" "other"
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. If null, the value would coalesce to the risk metadata captured when creating the payment token.

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>

Order updated time.

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

The links related to resource.

Array of RecentInvoiceEmbed (object) or InitialInvoiceEmbed (object) or CustomerEmbed (object) or WebsiteEmbed (object) or LeadSourceEmbed (object) non-empty

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

201Order was created.
Response Schema: application/json
id
string <= 50 characters

The order identifier string.

orderType
required
string
Default: "subscription-order"

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

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: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"
websiteId
required
string <= 50 characters

The website identifier string.

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.

required
Array of objects non-empty
object or null

Order delivery address.

object or null

Order billing address.

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.

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" "suspended" "paused" "abandoned" "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.

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

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.

object

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

customerId
required
string <= 50 characters

The customer identifier string.

renewalReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

renewalReminderNumber
integer

Number of renewal reminder events triggered.

trialReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

trialReminderNumber
integer

Number of renewal reminder events triggered.

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" "switched-plan" "other"
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. If null, the value would coalesce to the risk metadata captured when creating the payment token.

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>

Order updated time.

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

The links related to resource.

Array of RecentInvoiceEmbed (object) or InitialInvoiceEmbed (object) or CustomerEmbed (object) or WebsiteEmbed (object) or LeadSourceEmbed (object) non-empty

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

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
422Invalid data was sent.
put/subscriptions/{id}
Request samples
application/json
{
  • "orderType": "subscription-order",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "couponIds": [
    ],
  • "poNumber": "PO123456",
  • "trial": {
    },
  • "isTrialOnly": false,
  • "invoiceTimeShift": null,
  • "recurringInterval": null,
  • "autopay": true,
  • "startTime": null,
  • "renewalTime": "2019-08-24T14:15:22Z",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "riskMetadata": null,
  • "customFields": {
    }
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "orderType": "subscription-order",
  • "billingStatus": "unpaid",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "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",
  • "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": {
    },
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "renewalReminderTime": "2019-08-24T14:15:22Z",
  • "renewalReminderNumber": 0,
  • "trialReminderTime": "2019-08-24T14:15:22Z",
  • "trialReminderNumber": 0,
  • "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": [
    ]
}

Change an order's items

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

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Change items request.

required
Array of objects non-empty
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
201Order was changed.
Response Schema: application/json
id
string <= 50 characters

The order identifier string.

orderType
required
string
Default: "subscription-order"

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

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: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"
websiteId
required
string <= 50 characters

The website identifier string.

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.

required
Array of objects non-empty
object or null

Order delivery address.

object or null

Order billing address.

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.

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" "suspended" "paused" "abandoned" "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.

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

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.

object

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

customerId
required
string <= 50 characters

The customer identifier string.

renewalReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

renewalReminderNumber
integer

Number of renewal reminder events triggered.

trialReminderTime
string or null <date-time>

Time renewal reminder event will be triggered.

trialReminderNumber
integer

Number of renewal reminder events triggered.

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" "switched-plan" "other"
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. If null, the value would coalesce to the risk metadata captured when creating the payment token.

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>

Order updated time.

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

The links related to resource.

Array of RecentInvoiceEmbed (object) or InitialInvoiceEmbed (object) or CustomerEmbed (object) or WebsiteEmbed (object) or LeadSourceEmbed (object) non-empty

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

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid 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
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Issue an interim invoice for a subscription order

Issue an interim invoice for a subscription, typically used in conjunction. with plan changes and pro rata adjustments. This process creates an invoice, adds the subscription's line items to the invoice, and issues the invoice, and applies payment to it if a transaction id is supplied.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Issue an interim invoice.

transactionId
string <= 50 characters

If present, applies a payment to the invoice created. If the payment is for the invoice total, it would be marked as paid.

Responses
201Invoice was created.
Response Schema: application/json
id
string <= 50 characters

The invoice ID.

websiteId
required
string <= 50 characters

The website ID.

invoiceNumber
integer

An auto-incrementing number based on the sequence of invoices for any particular customer.

subscriptionId
string <= 50 characters

The related order's ID if available, otherwise null.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

The invoice's amount.

amountDue
number <double>

The invoice's due amount.

subtotalAmount
number <double>

The invoice's subtotal amount.

discountAmount
number <double>

The invoice's discounts amount.

object (InvoiceShipping)

Invoice shipping.

object (InvoiceTax)

Invoice taxes.

object

Invoice's billing address.

object

Invoice's delivery address.

poNumber
string or null

Purchase order number which will be displayed on the invoice.

notes
string

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

Array of objects (InvoiceItem)

Invoice items array.

Array of objects

Discounts applied.

autopayScheduledTime
string <date-time>

Invoice autopay scheduled time.

autopayRetryNumber
integer >= 0
Default: 0

Invoice autopay retry number.

status
string

Invoice status.

Enum: "draft" "unpaid" "paid" "past-due" "delinquent" "abandoned" "voided" "partially-refunded" "refunded" "disputed"
delinquentCollectionPeriod
integer

Delinquent collection period - difference between paidTime and dueTime in days.

collectionPeriod
integer

Collection period - difference between paidTime and issuedTime in days.

abandonedTime
string <date-time>

Invoice abandoned time.

voidedTime
string <date-time>

Invoice voided time.

paidTime
string <date-time>

Invoice paid time.

dueTime
string <date-time>

Invoice due time.

issuedTime
string <date-time>

Invoice issued time.

createdTime
string <date-time>

Invoice created time.

updatedTime
string <date-time>

Invoice updated time.

paymentFormUrl
string <url>

URL where the customer can be redirected to pay for the invoice with one of the methods which are available for this customer. It's an alternative to creating a new transaction with empty methods.

customerId
required
string <= 50 characters

The сustomer's ID.

Array of objects (schemas)

Invoice transactions array.

object

The invoice retry instruction.

revision
integer

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

type
string

Invoice type.

Enum: "initial" "renewal" "interim" "cancellation" "one-time" "refund" "charge"
dueReminderTime
string or null <date-time>

Time past due reminder event will be triggered.

dueReminderNumber
integer

Number of past due reminder events triggered.

Array of SelfLink (object) or CustomerLink (object) or WebsiteLink (object) or OrganizationLink (object) or LeadSourceLink (object) or TransactionAllocationsLink (object) or RecalculateInvoiceLink (object) or SubscriptionLink (object) non-empty

The links related to resource.

Array of CustomerEmbed (object) or WebsiteEmbed (object) or OrganizationEmbed (object) or LeadSourceEmbed (object) non-empty

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

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid data was sent.
post/subscriptions/{id}/interim-invoice
Request samples
application/json
{
  • "transactionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "invoiceNumber": 0,
  • "subscriptionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "currency": "USD",
  • "amount": 0,
  • "amountDue": 0,
  • "subtotalAmount": 0,
  • "discountAmount": 0,
  • "shipping": {
    },
  • "tax": {
    },
  • "billingAddress": {
    },
  • "deliveryAddress": {
    },
  • "poNumber": "PO123456",
  • "notes": "string",
  • "items": [
    ],
  • "discounts": [
    ],
  • "autopayScheduledTime": "2019-08-24T14:15:22Z",
  • "autopayRetryNumber": 0,
  • "status": "draft",
  • "delinquentCollectionPeriod": 0,
  • "collectionPeriod": 0,
  • "abandonedTime": "2019-08-24T14:15:22Z",
  • "voidedTime": "2019-08-24T14:15:22Z",
  • "paidTime": "2019-08-24T14:15:22Z",
  • "dueTime": "2019-08-24T14:15:22Z",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "paymentFormUrl": "string",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "transactions": [