logo

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

Preview an order

Use order preview before making an actual order.

Request
Security:
SecretApiKey or JWT
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json
websiteId
required
string <= 50 characters

The website identifier string.

required
Array of objects non-empty
Array (non-empty)
planId
required
string <= 50 characters

The plan identifier string.

quantity
integer

Number of units of the product on the given plan.

object or null

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

object or null

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

couponIds
Array of strings

The list of coupons applied to the order.

object (Shipping)

Invoice shipping.

calculator
required
string

Shipping calculator.

manual
manual
rebilly
amount
required
integer

The invoice's shipping amount.

Responses
200

Order preview was retrieved.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

422

Invalid data was sent.

post/previews/orders
Request samples
    3 more
    Java
    Go
    Ruby
application/json
{
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "items": [
    ],
  • "billingAddress": {
    },
  • "deliveryAddress": {
    },
  • "couponIds": [
    ],
  • "shipping": {
    }
}
Response samples
application/json
{
  • "currency": "USD",
  • "lineItems": [
    ],
  • "taxes": [
    ],
  • "discounts": [
    ],
  • "subtotalAmount": 0,
  • "taxAmount": 0,
  • "shippingAmount": 0,
  • "discountsAmount": 0,
  • "total": 0,
  • "shipping": {
    }
}

Retrieve a list of orders

Retrieve a list of orders.

Request
Security:
SecretApiKey or JWT
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
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

A list of subscriptions was retrieved successfully.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

get/subscriptions
Request samples
    4 more
    Python
    Java
    Go
    Ruby
$subscriptions = $client->subscriptions()->search([
    'filter' => 'customerId:testCustomerId',
]);
Response samples
application/json
[
  • {
    }
]

Create an order

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

Request
Security:
SecretApiKey or JWT
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
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

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

Order resource.

orderType
required
string
Default: "subscription-order"

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

subscription-order
subscription-order
one-time-order
websiteId
required
string <= 50 characters

The website identifier string.

required
Array of objects non-empty
Array (non-empty)
planId
string <= 50 characters
Deprecated

The plan identifier string.

quantity
integer

Number of units of the product on the given plan.

required
OriginalPlan (object) or FlexiblePlan (object)
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.

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.

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)

Invoice shipping.

calculator
required
string

Shipping calculator.

manual
manual
rebilly
amount
required
integer

The invoice's 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.

enabled
boolean

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

endTime
required
string <date-time>

The time the trial should end.

isTrialOnly
boolean
Default: false

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

object or null

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

object (IssueTimeShiftInstruction)

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

chronology
required
string

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

Value: "before"
duration
required
integer >= 1

The number of the units.

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

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

duration
required
integer >= 1
Default: 1

The number of the units.

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

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

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

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

method
required
string
Default: "immediately"
day-of-month
immediately
day-of-month
day-of-week
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.

customerId
required
string <= 50 characters

The customer identifier string.

object or null

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

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

property name*
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.

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.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

422

Invalid data was sent.

post/subscriptions
Request samples
    5 more
    C#
    Python
    Java
    Go
    Ruby
application/json
subscription-order
subscription-order
one-time-order
{
  • "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
subscription-order
subscription-order
one-time-order
{
  • "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.

Request
Security:
SecretApiKey or JWT
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
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

Order was retrieved successfully.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

404

Resource was not found.

get/subscriptions/{id}
Request samples
    4 more
    Python
    Java
    Go
    Ruby
$subscription = $client->subscriptions()->load('subscriptionId');
Response samples
application/json
subscription-order
subscription-order
one-time-order
{
  • "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": [
    ]
}

Upsert an order with predefined ID

Create or update an order with predefined identifier string.

Request
Security:
SecretApiKey or JWT
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
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

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

Order resource.

orderType
required
string
Default: "subscription-order"

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

subscription-order
subscription-order
one-time-order
websiteId
required
string <= 50 characters

The website identifier string.

required
Array of objects non-empty
Array (non-empty)
planId
string <= 50 characters
Deprecated

The plan identifier string.

quantity
integer

Number of units of the product on the given plan.

required
OriginalPlan (object) or FlexiblePlan (object)
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.

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.

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)

Invoice shipping.

calculator
required
string

Shipping calculator.

manual
manual
rebilly
amount
required
integer

The invoice's 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.

enabled
boolean

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

endTime
required
string <date-time>

The time the trial should end.

isTrialOnly
boolean
Default: false

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

object or null

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

object (IssueTimeShiftInstruction)

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

chronology
required
string

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

Value: "before"
duration
required
integer >= 1

The number of the units.

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

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

duration
required
integer >= 1
Default: 1

The number of the units.

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

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

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

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

method
required
string
Default: "immediately"
day-of-month
immediately
day-of-month
day-of-week
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.

customerId
required
string <= 50 characters

The customer identifier string.

object or null

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

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

property name*
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.

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
200

Order was updated.

201

Order was created.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

put/subscriptions/{id}
Request samples
    5 more
    C#
    Python
    Java
    Go
    Ruby
application/json
subscription-order
subscription-order
one-time-order
{
  • "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
    1 more
    422
application/json
subscription-order
subscription-order
one-time-order
{
  • "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": [
    ]
}

Change an order's items

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

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

The resource identifier string.

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

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

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

Change items request.

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

Number of units of the product on the given plan.

renewalPolicy
required
string

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

Enum: "reset" "retain"
prorated
required
boolean

Whether or not to give a pro rata credit for the amount of time remaining between the effectiveTime and the end of the current period. In addition, if the renewalTime is retained (by setting the renewalPolicy to retain), then a pro rata debit will occur as well, for the amount between the effectiveTime and the renewalTime as a percentage of the normal period size.

effectiveTime
string <date-time>

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

preview
boolean
Default: false

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

keepTrial
boolean
Default: false

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

Responses
201

Order was changed.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

422

Invalid data was sent.

post/subscriptions/{id}/change-items
Request samples
    3 more
    Java
    Go
    Ruby
application/json
{
  • "items": [
    ],
  • "renewalPolicy": "reset",
  • "prorated": true,
  • "effectiveTime": "2019-08-24T14:15:22Z",
  • "preview": false,
  • "keepTrial": false
}
Response samples
application/json
subscription-order
subscription-order
one-time-order
{
  • "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": [
    ]
}

Issue an interim invoice for a subscription order

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

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

The resource identifier string.

header Parameters
Organization-Id
string