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.

SecuritySecretApiKey or JWT or ApplicationJWT
Request
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.

Responses
200

A 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
orderType
required
string
Default: "subscription-order"

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

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

websiteId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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

The resource ID. Defaults to UUID v4.

quantity
integer

Number of units of the product on the given plan.

revision
integer

Increments with each override change to this specific item.

isModified
boolean

Indicates if the plan information was modified for this subscription.

isGrandfathered
boolean

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

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

billingStatus
string

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

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

ISO 4217 alphabetic currency code.

initialInvoiceId
string <= 50 characters

The resource ID. Defaults to UUID v4.

recentInvoiceId
string <= 50 characters

The resource ID. Defaults to UUID v4.

object or null

Order delivery address.

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

The contact first name.

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

The contact last name.

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

The contact organization.

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

The contact street address.

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

The contact street address (second line).

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

The contact city.

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

The contact region (state).

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

The contact country ISO Alpha-2 code.

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

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array of objects (ContactEmails)

The list of emails.

dob
string or null <date>

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

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

The contact's job title.

hash
string <= 40 characters

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

object or null

Order billing address.

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

The contact first name.

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

The contact last name.

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

The contact organization.

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

The contact street address.

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

The contact street address (second line).

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

The contact city.

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

The contact region (state).

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

The contact country ISO Alpha-2 code.

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

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array of objects (ContactEmails)

The list of emails.

dob
string or null <date>

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

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

The contact's job title.

hash
string <= 40 characters

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

activationTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

voidTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

poNumber
string or null

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

object (Shipping)

Shipping settings.

calculator
required
string

Shipping calculator.

amount
required
integer

Shipping amount.

notes
string

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

status
string

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

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

True if the subscription is currently in a trial period.

object

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

endTime
required
string <date-time>

The time the trial should end.

enabled
boolean

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

isTrialOnly
boolean
Default: false

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

object or null

The invoice time shift in conjunction with billingTiming allows to setup different billing use cases such as:

  • Bill immediately when the service period starts
  • Bill immediately after the service period ends
  • Bill interval of time before the service period starts
  • Bill interval of time after the service period starts
  • Bill interval of time before the service period ends
  • Bill interval of time after the service period ends It allows to control the billing time.
object (IssueTimeShiftInstruction)

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

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

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

object or null

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

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

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

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>

Read-only timestamp, automatically assigned on back-end.

renewalTime
string <date-time>

Subscription renewal time.

rebillNumber
integer

The current period number.

Array of objects

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

Array
type
required
string

Type of line item.

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

Unit price of the line item.

unitPriceCurrency
required
string = 3 characters

ISO 4217 alphabetic currency code.

quantity
required
integer

Quantity of line item.

description
string

Description of line item.

periodStartTime
string <date-time>

Date-time when the period begins for this item.

periodEndTime
string <date-time>

Date-time when the period ends for this item.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

object

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

currency
string (CurrencyCode) = 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>
renewalReminderTime
string or null <date-time>

Read-only timestamp, automatically assigned on back-end.

renewalReminderNumber
integer or null

Number of renewal reminder events triggered.

trialReminderTime
string or null <date-time>

Read-only timestamp, automatically assigned on back-end.

trialReminderNumber
integer or null

Number of renewal reminder events triggered.

canceledTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

canceledBy
string

Canceled by.

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

Cancel category.

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

Cancel reason description in free form.

revision
integer

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

object or null (Risk metadata)

Risk metadata used for 3DS and risk scoring.

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

object (Browser data)

Browser data used for 3DS and risk scoring.

object (Extra data)

Third party data used for risk scoring.

isProxy
boolean

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

isVpn
boolean

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

isTor
boolean

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

isHosting
boolean

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

vpnServiceName
string

VPN service name, if available.

isp
string

Internet Service Provider name, if available.

country
string <= 2 characters

Country ISO Alpha-2 code for specified ipAddress.

region
string

Region for specified ipAddress.

city
string

City for specified ipAddress.

latitude
number <double>

Latitude for specified ipAddress.

longitude
number <double>

Longitude for specified ipAddress.

postalCode
string <= 10 characters

Postal code for specified ipAddress.

timeZone
string

Time zone for specified ipAddress.

accuracyRadius
integer

Accuracy radius for specified ipAddress (kilometers).

distance
integer

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

hasMismatchedBillingAddressCountry
boolean

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

hasMismatchedBankCountry
boolean

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

hasMismatchedTimeZone
boolean

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

hasMismatchedHolderName
boolean

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

hasFakeName
boolean

True if the holder name seems fake.

isHighRiskCountry
boolean

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

paymentInstrumentVelocity
integer

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

deviceVelocity
integer

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

ipVelocity
integer

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

emailVelocity
integer

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

billingAddressVelocity
integer

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

score
integer

Risk score computed per all the factors.

customFields
object (ResourceCustomFields)
Default: {}

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

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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 (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

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

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

Array (non-empty)
Any of:

Recent Invoice object.

object (Invoice)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

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.

SecuritySecretApiKey or JWT
Request
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.

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

The resource ID. Defaults to UUID v4.

websiteId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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

The resource ID. Defaults to UUID v4.

quantity
integer

Number of units of the product on the given plan.

object or null

Order delivery address.

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

The contact first name.

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

The contact last name.

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

The contact organization.

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

The contact street address.

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

The contact street address (second line).

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

The contact city.

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

The contact region (state).

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

The contact country ISO Alpha-2 code.

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

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

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

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

The contact's job title.

object or null

Order billing address.

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

The contact first name.

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

The contact last name.

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

The contact organization.

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

The contact street address.

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

The contact street address (second line).

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

The contact city.

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

The contact region (state).

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

The contact country ISO Alpha-2 code.

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

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

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

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

The contact's job title.

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 (Shipping)

Shipping settings.

calculator
required
string

Shipping calculator.

amount
required
integer

Shipping amount.

notes
string

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

object

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

endTime
required
string <date-time>

The time the trial should end.

enabled
boolean

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

isTrialOnly
boolean
Default: false

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

object or null

The invoice time shift in conjunction with billingTiming allows to setup different billing use cases such as:

  • Bill immediately when the service period starts
  • Bill immediately after the service period ends
  • Bill interval of time before the service period starts
  • Bill interval of time after the service period starts
  • Bill interval of time before the service period ends
  • Bill interval of time after the service period ends It allows to control the billing time.
object (IssueTimeShiftInstruction)

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

chronology
required
string

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

Value: "before"
duration
required
integer >= 1

The number of the units.

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

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

duration
required
integer >= 1
Default: 1

The number of the units.

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

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

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

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

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

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

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

Extended ISO-8601 format of time.

autopay
boolean
Default: true

Autopay determines if a payment attempt will be automatic.

startTime
string or null <date-time>

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

renewalTime
string <date-time>

Subscription renewal time.

object or null (Risk metadata)

Risk metadata used for 3DS and risk scoring.

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

property name*
additional property
string
object (Browser data)

Browser data used for 3DS and risk scoring.

colorDepth
required
integer [ 1 .. 48 ]

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

isJavaEnabled
required
boolean

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

language
required
string <= 8 characters

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

screenWidth
required
integer [ 0 .. 65535 ]

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

screenHeight
required
integer [ 0 .. 65535 ]

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

timeZoneOffset
required
integer [ -1410 .. 1410 ]

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

object (Extra data)

Third party data used for risk scoring.

kountFraudSessionId
string [ 10 .. 32 ]

Alpha-numeric fraudSessionId as provided by the Kount SDK.

payPalMerchantSessionId
string [ 1 .. 64 ]

MerchantSessionID as generated by the PayPal Fraudnet SDK.

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

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

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
201

Order was created.

Response Schema: application/json
orderType
required
string
Default: "subscription-order"

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

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

websiteId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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

The resource ID. Defaults to UUID v4.

quantity
integer

Number of units of the product on the given plan.

revision
integer

Increments with each override change to this specific item.

isModified
boolean

Indicates if the plan information was modified for this subscription.

isGrandfathered
boolean

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

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

billingStatus
string

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

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

ISO 4217 alphabetic currency code.

initialInvoiceId
string <= 50 characters

The resource ID. Defaults to UUID v4.

recentInvoiceId
string <= 50 characters

The resource ID. Defaults to UUID v4.

object or null

Order delivery address.

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

The contact first name.

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

The contact last name.

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

The contact organization.

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

The contact street address.

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

The contact street address (second line).

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

The contact city.

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

The contact region (state).

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

The contact country ISO Alpha-2 code.

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

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

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

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

The contact's job title.

hash
string <= 40 characters

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

object or null

Order billing address.

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

The contact first name.

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

The contact last name.

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

The contact organization.

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

The contact street address.

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

The contact street address (second line).

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

The contact city.

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

The contact region (state).

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

The contact country ISO Alpha-2 code.

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

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

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

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

The contact's job title.

hash
string <= 40 characters

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

activationTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

voidTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

poNumber
string or null

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

object (Shipping)

Shipping settings.

calculator
required
string

Shipping calculator.

amount
required
integer

Shipping amount.

notes
string

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

status
string

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

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

True if the subscription is currently in a trial period.

object

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

endTime
required
string <date-time>

The time the trial should end.

enabled
boolean

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

isTrialOnly
boolean
Default: false

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

object or null

The invoice time shift in conjunction with billingTiming allows to setup different billing use cases such as:

  • Bill immediately when the service period starts
  • Bill immediately after the service period ends
  • Bill interval of time before the service period starts
  • Bill interval of time after the service period starts
  • Bill interval of time before the service period ends
  • Bill interval of time after the service period ends It allows to control the billing time.
object (IssueTimeShiftInstruction)

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

chronology
required
string

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

Value: "before"
duration
required
integer >= 1

The number of the units.

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

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

duration
required
integer >= 1
Default: 1

The number of the units.

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

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

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

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

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

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

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

Extended ISO-8601 format of time.

autopay
boolean
Default: true

Autopay determines if a payment attempt will be automatic.

startTime
string or null <date-time>

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

endTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

renewalTime
string <date-time>

Subscription renewal time.

rebillNumber
integer

The current period number.

Array of objects

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

Array
type
required
string

Type of line item.

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

Unit price of the line item.

unitPriceCurrency
required
string = 3 characters

ISO 4217 alphabetic currency code.

quantity
required
integer

Quantity of line item.

description
string

Description of line item.

periodStartTime
string <date-time>

Date-time when the period begins for this item.

periodEndTime
string <date-time>

Date-time when the period ends for this item.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

object

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

currency
string (CurrencyCode) = 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>
renewalReminderTime
string or null <date-time>

Read-only timestamp, automatically assigned on back-end.

renewalReminderNumber
integer or null

Number of renewal reminder events triggered.

trialReminderTime
string or null <date-time>

Read-only timestamp, automatically assigned on back-end.

trialReminderNumber
integer or null

Number of renewal reminder events triggered.

canceledTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

canceledBy
string

Canceled by.

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

Cancel category.

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

Cancel reason description in free form.

revision
integer

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

object or null (Risk metadata)

Risk metadata used for 3DS and risk scoring.

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

property name*
additional property
string
object (Browser data)

Browser data used for 3DS and risk scoring.

colorDepth
required
integer [ 1 .. 48 ]

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

isJavaEnabled
required
boolean

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

language
required
string <= 8 characters

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

screenWidth
required
integer [ 0 .. 65535 ]

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

screenHeight
required
integer [ 0 .. 65535 ]

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

timeZoneOffset
required
integer [ -1410 .. 1410 ]

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

object (Extra data)

Third party data used for risk scoring.

kountFraudSessionId
string [ 10 .. 32 ]

Alpha-numeric fraudSessionId as provided by the Kount SDK.

payPalMerchantSessionId
string [ 1 .. 64 ]

MerchantSessionID as generated by the PayPal Fraudnet SDK.

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

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

isProxy
boolean

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

isVpn
boolean

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

isTor
boolean

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

isHosting
boolean

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

vpnServiceName
string

VPN service name, if available.

isp
string

Internet Service Provider name, if available.

country
string <= 2 characters

Country ISO Alpha-2 code for specified ipAddress.

region
string

Region for specified ipAddress.

city
string

City for specified ipAddress.

latitude
number <double>

Latitude for specified ipAddress.

longitude
number <double>

Longitude for specified ipAddress.

postalCode
string <= 10 characters

Postal code for specified ipAddress.

timeZone
string

Time zone for specified ipAddress.

accuracyRadius
integer

Accuracy radius for specified ipAddress (kilometers).

distance
integer

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

hasMismatchedBillingAddressCountry
boolean

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

hasMismatchedBankCountry
boolean

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

hasMismatchedTimeZone
boolean

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

hasMismatchedHolderName
boolean

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

hasFakeName
boolean

True if the holder name seems fake.

isHighRiskCountry
boolean

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

paymentInstrumentVelocity
integer

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

deviceVelocity
integer

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

ipVelocity
integer

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

emailVelocity
integer

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

billingAddressVelocity
integer

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

score
integer

Risk score computed per all the factors.

customFields
object (ResourceCustomFields)
Default: {}

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

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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 (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

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

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

Array (non-empty)
Any of:

Recent Invoice object.

object (Invoice)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/subscriptions
Request samples
application/json
{
  • "orderType": "subscription-order",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "couponIds": [
    ],
  • "poNumber": "PO123456",
  • "shipping": {
    },
  • "notes": "string",
  • "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": "draft",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "currency": "USD",
  • "initialInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "recentInvoiceId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "deliveryAddress": {
    },
  • "billingAddress": {
    },
  • "activationTime": "2019-08-24T14:15:22Z",
  • "voidTime": "2019-08-24T14:15:22Z",
  • "poNumber": "PO123456",
  • "shipping": {
    },
  • "notes": "string",
  • "status": "pending",
  • "inTrial": true,
  • "trial": {
    },
  • "isTrialOnly": false,
  • "invoiceTimeShift": null,
  • "recurringInterval": null,
  • "autopay": true,
  • "startTime": null,
  • "endTime": "2019-08-24T14:15:22Z",
  • "renewalTime": "2019-08-24T14:15:22Z",
  • "rebillNumber": 0,
  • "lineItems": [
    ],
  • "lineItemSubtotal": {
    },
  • "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.

SecuritySecretApiKey or JWT or ApplicationJWT
Request
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.

Responses
200

Order was retrieved successfully.

Response Schema: application/json
orderType
required
string
Default: "subscription-order"

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

customerId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

websiteId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

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

The resource ID. Defaults to UUID v4.

quantity
integer

Number of units of the product on the given plan.

revision
integer

Increments with each override change to this specific item.

isModified
boolean

Indicates if the plan information was modified for this subscription.

isGrandfathered
boolean

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

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

billingStatus
string

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

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

ISO 4217 alphabetic currency code.

initialInvoiceId
string <= 50 characters

The resource ID. Defaults to UUID v4.

recentInvoiceId
string <= 50 characters

The resource ID. Defaults to UUID v4.

object or null

Order delivery address.

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

The contact first name.

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

The contact last name.

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

The contact organization.

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

The contact street address.

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

The contact street address (second line).

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

The contact city.

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

The contact region (state).

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

The contact country ISO Alpha-2 code.

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

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

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

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

The contact's job title.