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.

Authorizations:
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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"

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.

customerId
required
string <= 50 characters

Unique id for each customer.

websiteId
required
string <= 50 characters

Unique id for each website.

initialInvoiceId
string <= 50 characters

Unique id for the initial invoice.

recentInvoiceId
string <= 50 characters

Unique id for the most recently issued invoice. It might not be paid yet.

required
Array of objects non-empty
object Nullable

Delivery address.

object Nullable

Billing address.

object Nullable

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

activationTime
string <date-time>

Order activation time.

poNumber
string Nullable

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

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.

status
string
Enum: "pending" "completed" "abandoned"

One-time order status.

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.

Request samples

$subscriptions = $client->subscriptions()->search([
    'filter' => 'customerId:testCustomerId',
]);

Response samples

Content type
application/json
[
  • {
    }
]

Create an order

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

Authorizations:
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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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.

customerId
required
string <= 50 characters

Unique id for each customer.

websiteId
required
string <= 50 characters

Unique id for each website.

required
Array of objects non-empty
object Nullable

Delivery address.

object Nullable

Billing address.

object Nullable

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

couponIds
Array of strings Nullable

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 Nullable

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"

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.

customerId
required
string <= 50 characters

Unique id for each customer.

websiteId
required
string <= 50 characters

Unique id for each website.

initialInvoiceId
string <= 50 characters

Unique id for the initial invoice.

recentInvoiceId
string <= 50 characters

Unique id for the most recently issued invoice. It might not be paid yet.

required
Array of objects non-empty
object Nullable

Delivery address.

object Nullable

Billing address.

object Nullable

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

activationTime
string <date-time>

Order activation time.

poNumber
string Nullable

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

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.

status
string
Enum: "pending" "completed" "abandoned"

One-time order status.

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.

Request samples

Content type
application/json
Example
{
  • "orderType": "one-time-order",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "riskMetadata": null,
  • "couponIds": [
    ],
  • "poNumber": "PO123456",
  • "customFields": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "orderType": "one-time-order",
  • "billingStatus": "unpaid",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "initialInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "recentInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "riskMetadata": null,
  • "activationTime": "2019-08-24T14:15:22Z",
  • "poNumber": "PO123456",
  • "revision": 0,
  • "status": "pending",
  • "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.

Authorizations:
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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"

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.

customerId
required
string <= 50 characters

Unique id for each customer.

websiteId
required
string <= 50 characters

Unique id for each website.

initialInvoiceId
string <= 50 characters

Unique id for the initial invoice.

recentInvoiceId
string <= 50 characters

Unique id for the most recently issued invoice. It might not be paid yet.

required
Array of objects non-empty
object Nullable

Delivery address.

object Nullable

Billing address.

object Nullable

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

activationTime
string <date-time>

Order activation time.

poNumber
string Nullable

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

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.

status
string
Enum: "pending" "completed" "abandoned"

One-time order status.

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.

Request samples

$subscription = $client->subscriptions()->load('subscriptionId');

Response samples

Content type
application/json
Example
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "orderType": "one-time-order",
  • "billingStatus": "unpaid",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "initialInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "recentInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "riskMetadata": null,
  • "activationTime": "2019-08-24T14:15:22Z",
  • "poNumber": "PO123456",
  • "revision": 0,
  • "status": "pending",
  • "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.

Authorizations:
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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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.

customerId
required
string <= 50 characters

Unique id for each customer.

websiteId
required
string <= 50 characters

Unique id for each website.

required
Array of objects non-empty
object Nullable

Delivery address.

object Nullable

Billing address.

object Nullable

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

couponIds
Array of strings Nullable

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 Nullable

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"

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.

customerId
required
string <= 50 characters

Unique id for each customer.

websiteId
required
string <= 50 characters

Unique id for each website.

initialInvoiceId
string <= 50 characters

Unique id for the initial invoice.

recentInvoiceId
string <= 50 characters

Unique id for the most recently issued invoice. It might not be paid yet.

required
Array of objects non-empty
object Nullable

Delivery address.

object Nullable

Billing address.

object Nullable

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

activationTime
string <date-time>

Order activation time.

poNumber
string Nullable

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

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.

status
string
Enum: "pending" "completed" "abandoned"

One-time order status.

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.

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"

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.

customerId
required
string <= 50 characters

Unique id for each customer.

websiteId
required
string <= 50 characters

Unique id for each website.

initialInvoiceId
string <= 50 characters

Unique id for the initial invoice.

recentInvoiceId
string <= 50 characters

Unique id for the most recently issued invoice. It might not be paid yet.

required
Array of objects non-empty
object Nullable

Delivery address.

object Nullable

Billing address.

object Nullable

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

activationTime
string <date-time>

Order activation time.

poNumber
string Nullable

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

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.

status
string
Enum: "pending" "completed" "abandoned"

One-time order status.

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.

Request samples

Content type
application/json
Example
{
  • "orderType": "one-time-order",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "riskMetadata": null,
  • "couponIds": [
    ],
  • "poNumber": "PO123456",
  • "customFields": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "orderType": "one-time-order",
  • "billingStatus": "unpaid",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "initialInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "recentInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "riskMetadata": null,
  • "activationTime": "2019-08-24T14:15:22Z",
  • "poNumber": "PO123456",
  • "revision": 0,
  • "status": "pending",
  • "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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Request Body schema: application/json

Change items request.

required
Array of objects non-empty
renewalPolicy
required
string
Enum: "reset" "retain"

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "unpaid" "past-due" "delinquent" "paid" "voided" "refunded" "disputed" "voided"

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.

customerId
required
string <= 50 characters

Unique id for each customer.

websiteId
required
string <= 50 characters

Unique id for each website.

initialInvoiceId
string <= 50 characters

Unique id for the initial invoice.

recentInvoiceId
string <= 50 characters

Unique id for the most recently issued invoice. It might not be paid yet.

required
Array of objects non-empty
object Nullable

Delivery address.

object Nullable

Billing address.

object Nullable

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

activationTime
string <date-time>

Order activation time.

poNumber
string Nullable

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

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.

status
string
Enum: "pending" "completed" "abandoned"

One-time order status.

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.

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "renewalPolicy": "reset",
  • "prorated": true,
  • "effectiveTime": "2019-08-24T14:15:22Z",
  • "preview": false,
  • "keepTrial": false
}

Response samples

Content type
application/json
Example
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "orderType": "one-time-order",
  • "billingStatus": "unpaid",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "initialInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "recentInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "riskMetadata": null,
  • "activationTime": "2019-08-24T14:15:22Z",
  • "poNumber": "PO123456",
  • "revision": 0,
  • "status": "pending",
  • "customFields": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": [
    ]
}

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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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.

taxAmount
number <double>

The invoice's taxes amount.

shippingAmount
number <double>

The invoice's shipping amount.

object

Invoice's billing address.

object

Invoice's delivery address.

poNumber
string Nullable

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

Taxes applied to this invoice.

Array of objects

Discounts applied.

autopayScheduledTime
string <date-time>

Invoice autopay scheduled time.

autopayRetryNumber
integer >= 0
Default: 0

Invoice autopay retry number.

status
string
Enum: "draft" "unpaid" "paid" "past-due" "delinquent" "abandoned" "voided" "partially-refunded" "refunded" "disputed"

Invoice status.

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.

customerId
required
string <= 50 characters

The сustomer's ID.

Array of objects (Transaction)

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.

dueReminderTime
string <date-time> Nullable

Time past due reminder event will be triggered.

dueReminderNumber
integer

Number of past due reminder events triggered.

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.

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.

Request samples

Content type
application/json
{
  • "transactionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
}

Response samples

Content type
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,
  • "taxAmount": 0,
  • "shippingAmount": 0,
  • "billingAddress": {
    },
  • "deliveryAddress": {
    },
  • "poNumber": "PO123456",
  • "notes": "string",
  • "items": [
    ],
  • "taxes": [
    ],
  • "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",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "transactions": [
    ],
  • "retryInstruction": {
    },
  • "revision": 0,
  • "dueReminderTime": "2019-08-24T14:15:22Z",
  • "dueReminderNumber": 0,
  • "paymentFormUrl": "string",
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Retrieve a list of cancellations

Retrieve a list of cancellations for all subscriptions.

Authorizations:
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

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

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Cancellation identifier.

subscriptionId
required
string <= 50 characters

Identifier of the canceled subscription order.

proratedInvoiceId
string <= 50 characters

Identifier of the invoice on which the cancellation proration is calculated.

appliedInvoiceId
string <= 50 characters

The identifier of the invoice where the cancellation fees or credits are applied.

canceledBy
string
Default: "customer"
Enum: "merchant" "customer"

Who did the cancellation.

reason
string
Default: "other"
Enum: "did-not-use" "did-not-want" "missing-features" "bugs-or-problems" "do-not-remember" "risk-warning" "contract-expired" "too-expensive" "other" "billing-failure"

Cancellation reason.

description
string <= 255 characters

Cancel reason description in free form.

prorated
boolean
Default: false

Defines if the customer gets a pro-rata credit for the time remaining between churnTime and subscription's next renewal time.

status
string
Default: "confirmed"
Enum: "draft" "confirmed" "completed" "revoked"

"draft" defines that the cancellation isn't applied on an invoice and subscription but can be inspected to see the charge. "confirmed" will set a subscription to be canceled when the churnTime is reached. "completed" is a read-only status which is set by the system when the churnTime is reached. The cancellation may not be changed or deleted when the status is "completed".

canceledTime
string <date-time>

The cancellation time (when the status is confirmed which is by default unless specified "draft").

createdTime
string <date-time>

The time of resource creation (when it is posted).

churnTime
required
string <date-time>

The time when the subscription will be deactivated.

Array of objects

Items to be added to the new invoice. Proration item is generated and added automatically.

lineItemSubtotal
number

Subtotal of the line items which will be added after the subscription's cancellation.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

curl -i -X GET \
  'https://api-sandbox.rebilly.com/subscription-cancellations?limit=0&offset=0&filter=string&sort=string' \
  -H 'Organization-Id: 4f6cf35x-2c4y-483z-a0a9-158621f77a21' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
[
  • {
    }
]

Cancel an order

Cancel an order or preview the cancellation parameters before that.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Request Body schema: application/json

Cancellation resource.

subscriptionId
required
string <= 50 characters

Identifier of the canceled subscription order.

canceledBy
string
Default: "customer"
Enum: "merchant" "customer"

Who did the cancellation.

reason
string
Default: "other"
Enum: "did-not-use" "did-not-want" "missing-features" "bugs-or-problems" "do-not-remember" "risk-warning" "contract-expired" "too-expensive" "other" "billing-failure"

Cancellation reason.

description
string <= 255 characters

Cancel reason description in free form.

prorated
boolean
Default: false

Defines if the customer gets a pro-rata credit for the time remaining between churnTime and subscription's next renewal time.

status
string
Default: "confirmed"
Enum: "draft" "confirmed" "completed" "revoked"

"draft" defines that the cancellation isn't applied on an invoice and subscription but can be inspected to see the charge. "confirmed" will set a subscription to be canceled when the churnTime is reached. "completed" is a read-only status which is set by the system when the churnTime is reached. The cancellation may not be changed or deleted when the status is "completed".

churnTime
required
string <date-time>

The time when the subscription will be deactivated.

Array of objects

Items to be added to the new invoice. Proration item is generated and added automatically.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Cancellation identifier.

subscriptionId
required
string <= 50 characters

Identifier of the canceled subscription order.

proratedInvoiceId
string <= 50 characters

Identifier of the invoice on which the cancellation proration is calculated.

appliedInvoiceId
string <= 50 characters

The identifier of the invoice where the cancellation fees or credits are applied.

canceledBy
string
Default: "customer"
Enum: "merchant" "customer"

Who did the cancellation.

reason
string
Default: "other"
Enum: "did-not-use" "did-not-want" "missing-features" "bugs-or-problems" "do-not-remember" "risk-warning" "contract-expired" "too-expensive" "other" "billing-failure"

Cancellation reason.

description
string <= 255 characters

Cancel reason description in free form.

prorated
boolean
Default: false

Defines if the customer gets a pro-rata credit for the time remaining between churnTime and subscription's next renewal time.

status
string
Default: "confirmed"
Enum: "draft" "confirmed" "completed" "revoked"

"draft" defines that the cancellation isn't applied on an invoice and subscription but can be inspected to see the charge. "confirmed" will set a subscription to be canceled when the churnTime is reached. "completed" is a read-only status which is set by the system when the churnTime is reached. The cancellation may not be changed or deleted when the status is "completed".

canceledTime
string <date-time>

The cancellation time (when the status is confirmed which is by default unless specified "draft").

createdTime
string <date-time>

The time of resource creation (when it is posted).

churnTime
required
string <date-time>

The time when the subscription will be deactivated.

Array of objects

Items to be added to the new invoice. Proration item is generated and added automatically.

lineItemSubtotal
number

Subtotal of the line items which will be added after the subscription's cancellation.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "subscriptionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "canceledBy": "customer",
  • "reason": "other",
  • "description": "string",
  • "prorated": false,
  • "status": "confirmed",
  • "churnTime": "2019-08-24T14:15:22Z",
  • "lineItems": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "subscriptionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "proratedInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "appliedInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "canceledBy": "customer",
  • "reason": "other",
  • "description": "string",
  • "prorated": false,
  • "status": "confirmed",
  • "canceledTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "churnTime": "2019-08-24T14:15:22Z",
  • "lineItems": [
    ],
  • "lineItemSubtotal": 49.95,
  • "_links": [
    ]
}

Retrieve an order сancellation

Retrieve an order сancellation with specified identifier string.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Cancellation identifier.

subscriptionId
required
string <= 50 characters

Identifier of the canceled subscription order.

proratedInvoiceId
string <= 50 characters

Identifier of the invoice on which the cancellation proration is calculated.

appliedInvoiceId
string <= 50 characters

The identifier of the invoice where the cancellation fees or credits are applied.

canceledBy
string
Default: "customer"
Enum: "merchant" "customer"

Who did the cancellation.

reason
string
Default: "other"
Enum: "did-not-use" "did-not-want" "missing-features" "bugs-or-problems" "do-not-remember" "risk-warning" "contract-expired" "too-expensive" "other" "billing-failure"

Cancellation reason.

description
string <= 255 characters

Cancel reason description in free form.

prorated
boolean
Default: false

Defines if the customer gets a pro-rata credit for the time remaining between churnTime and subscription's next renewal time.

status
string
Default: "confirmed"
Enum: "draft" "confirmed" "completed" "revoked"

"draft" defines that the cancellation isn't applied on an invoice and subscription but can be inspected to see the charge. "confirmed" will set a subscription to be canceled when the churnTime is reached. "completed" is a read-only status which is set by the system when the churnTime is reached. The cancellation may not be changed or deleted when the status is "completed".

canceledTime
string <date-time>

The cancellation time (when the status is confirmed which is by default unless specified "draft").

createdTime
string <date-time>

The time of resource creation (when it is posted).

churnTime
required
string <date-time>

The time when the subscription will be deactivated.

Array of objects

Items to be added to the new invoice. Proration item is generated and added automatically.

lineItemSubtotal
number

Subtotal of the line items which will be added after the subscription's cancellation.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

curl -i -X GET \
  https://api-sandbox.rebilly.com/subscription-cancellations/:id \
  -H 'Organization-Id: 4f6cf35x-2c4y-483z-a0a9-158621f77a21' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "subscriptionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "proratedInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "appliedInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "canceledBy": "customer",
  • "reason": "other",
  • "description": "string",
  • "prorated": false,
  • "status": "confirmed",
  • "canceledTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "churnTime": "2019-08-24T14:15:22Z",
  • "lineItems": [
    ],
  • "lineItemSubtotal": 49.95,
  • "_links": [
    ]
}

Cancel an order

Cancel a subscription.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Request Body schema: application/json

Cancellation resource.

subscriptionId
required
string <= 50 characters

Identifier of the canceled subscription order.

canceledBy
string
Default: "customer"
Enum: "merchant" "customer"

Who did the cancellation.

reason
string
Default: "other"
Enum: "did-not-use" "did-not-want" "missing-features" "bugs-or-problems" "do-not-remember" "risk-warning" "contract-expired" "too-expensive" "other" "billing-failure"

Cancellation reason.

description
string <= 255 characters

Cancel reason description in free form.

prorated
boolean
Default: false

Defines if the customer gets a pro-rata credit for the time remaining between churnTime and subscription's next renewal time.

status
string
Default: "confirmed"
Enum: "draft" "confirmed" "completed" "revoked"

"draft" defines that the cancellation isn't applied on an invoice and subscription but can be inspected to see the charge. "confirmed" will set a subscription to be canceled when the churnTime is reached. "completed" is a read-only status which is set by the system when the churnTime is reached. The cancellation may not be changed or deleted when the status is "completed".

churnTime
required
string <date-time>

The time when the subscription will be deactivated.

Array of objects

Items to be added to the new invoice. Proration item is generated and added automatically.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

Cancellation identifier.

subscriptionId
required
string <= 50 characters

Identifier of the canceled subscription order.

proratedInvoiceId
string <= 50 characters

Identifier of the invoice on which the cancellation proration is calculated.

appliedInvoiceId
string <= 50 characters

The identifier of the invoice where the cancellation fees or credits are applied.

canceledBy
string
Default: "customer"
Enum: "merchant" "customer"

Who did the cancellation.

reason
string
Default: "other"
Enum: "did-not-use" "did-not-want" "missing-features" "bugs-or-problems" "do-not-remember" "risk-warning" "contract-expired" "too-expensive" "other" "billing-failure"

Cancellation reason.

description
string <= 255 characters

Cancel reason description in free form.

prorated
boolean
Default: false

Defines if the customer gets a pro-rata credit for the time remaining between churnTime and subscription's next renewal time.

status
string
Default: "confirmed"
Enum: "draft" "confirmed" "completed" "revoked"

"draft" defines that the cancellation isn't applied on an invoice and subscription but can be inspected to see the charge. "confirmed" will set a subscription to be canceled when the churnTime is reached. "completed" is a read-only status which is set by the system when the churnTime is reached. The cancellation may not be changed or deleted when the status is "completed".

canceledTime
string <date-time>

The cancellation time (when the status is confirmed which is by default unless specified "draft").

createdTime
string <date-time>

The time of resource creation (when it is posted).

churnTime
required
string <date-time>

The time when the subscription will be deactivated.

Array of objects

Items to be added to the new invoice. Proration item is generated and added automatically.

lineItemSubtotal
number

Subtota