Plans

Plans are a template for making a subscription. For example, you may have a plan that has a 30-day free trial followed by a recurring charge of $19.95 per month until canceled. The combination of the plan and a request to make an order will apply those instructions to create the invoices according to the plan's schedule.

Retrieve a list of plans

Retrieve a list of plans.

Request
Security:
query Parameters
filter
string

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

sort
Array of strings

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

limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

q
string

The partial search of the text fields.

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 Plans was retrieved successfully.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

get/plans
Request samples
$plans = $client->plans()->search([
    'filter' => 'name:TestPlan',
]);
Response samples
application/json
[
  • {
    }
]

Create a plan

Create a plan.

Request
Security:
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

Plan resource.

name
required
string

The plan name, displayed on invoices and receipts.

productId
required
string <= 50 characters

The related product ID.

object

Name-value pairs to specify the product options.

property name*
string
currency
required
string 3 characters

ISO 4217 alphabetic currency code.

required
object (PlanPriceFormula)
formula
required
string

The price formula determines what algorithm is used to calculate the invoice price based on a few factors,

  • the quantity in the order (which may be variable if usage pricing, otherwise determined when creating the order)
  • the price brackets data

To determine which formula is correct, please see the price formula documentation.

price
required
number <double>

For the very simple price when it's fixed and does not depend on the quantity chosen by customer.

If the price is 0, it's free.

object

The service interval. For a one-time item, use null.

unit
required
string

The unit of time.

Enum: "day" "week" "month" "year"
length
required
integer

The length of time.

limit
integer

The number of invoices this subscription order will generate (if 1, it will not generate any beyond the initial order creation). For example, set this property to 12, when the periodUnit is month and the periodDuration is 1, for a 1 year contract billed monthly.

billingTiming
string (PlanBillingTiming)
Default: "prepaid"

The billing timing in relation to the service period. For prepaid plans the customer pays when the service period starts, whereas, for postpaid plans, the customer pays when the service period ends.

Enum: "prepaid" "postpaid"
object

The trial. Set null if no trial.

price
required
number <double>

The price of the trial. For a free trial, use 0.

required
object (PlanPeriod)
unit
required
string

The unit of time.

Enum: "day" "week" "month" "year"
length
required
integer

The length of time.

object

The setup. Set null if no setup.

price
required
number <double>

The price of a setup - 0 is a valid value (for free).

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

object

You can shift issue time and due time of invoices for this plan.

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"
Responses
201

Plan was created.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

422

Invalid data was sent.

post/plans
Request samples
application/json
{
  • "name": "string",
  • "productId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "productOptions": {
    },
  • "currency": "USD",
  • "pricing": {
    },
  • "recurringInterval": {
    },
  • "trial": {
    },
  • "setup": {
    },
  • "customFields": {
    },
  • "invoiceTimeShift": {
    }
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "productId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "productOptions": {
    },
  • "currency": "USD",
  • "currencySign": "string",
  • "pricing": {
    },
  • "recurringInterval": {
    },
  • "trial": {
    },
  • "isTrialOnly": true,
  • "setup": {
    },
  • "customFields": {
    },
  • "revision": 0,
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "invoiceTimeShift": {
    },
  • "_links": [
    ]
}

Retrieve a plan

Retrieve a plan with specified identifier string.

Request
Security:
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
Responses
200

Plan was retrieved successfully.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

404

Resource was not found.

get/plans/{id}
Request samples
$plan = $client->plans()->load('planId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "productId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "productOptions": {
    },
  • "currency": "USD",
  • "currencySign": "string",
  • "pricing": {
    },
  • "recurringInterval": {
    },
  • "trial": {
    },
  • "isTrialOnly": true,
  • "setup": {
    },
  • "customFields": {
    },
  • "revision": 0,
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "invoiceTimeShift": {
    },
  • "_links": [
    ]
}

Create or update a Plan with predefined ID

Create or update a Plan with predefined identifier string.

Request
Security:
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

Plan resource.

name
required
string

The plan name, displayed on invoices and receipts.

productId
required
string <= 50 characters

The related product ID.

object

Name-value pairs to specify the product options.

property name*
string
currency
required
string 3 characters

ISO 4217 alphabetic currency code.

required
object (PlanPriceFormula)
formula
required
string

The price formula determines what algorithm is used to calculate the invoice price based on a few factors,

  • the quantity in the order (which may be variable if usage pricing, otherwise determined when creating the order)
  • the price brackets data

To determine which formula is correct, please see the price formula documentation.

price
required
number <double>

For the very simple price when it's fixed and does not depend on the quantity chosen by customer.

If the price is 0, it's free.

object

The service interval. For a one-time item, use null.

unit
required
string

The unit of time.

Enum: "day" "week" "month" "year"
length
required
integer

The length of time.

limit
integer

The number of invoices this subscription order will generate (if 1, it will not generate any beyond the initial order creation). For example, set this property to 12, when the periodUnit is month and the periodDuration is 1, for a 1 year contract billed monthly.

billingTiming
string (PlanBillingTiming)
Default: "prepaid"

The billing timing in relation to the service period. For prepaid plans the customer pays when the service period starts, whereas, for postpaid plans, the customer pays when the service period ends.

Enum: "prepaid" "postpaid"
object

The trial. Set null if no trial.

price
required
number <double>

The price of the trial. For a free trial, use 0.

required
object (PlanPeriod)
unit
required
string

The unit of time.

Enum: "day" "week" "month" "year"
length
required
integer

The length of time.

object

The setup. Set null if no setup.

price
required
number <double>

The price of a setup - 0 is a valid value (for free).

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

object

You can shift issue time and due time of invoices for this plan.

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"
Responses
200

Plan was updated.

201

Plan was created.

401

Unauthorized access, invalid credentials was used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

put/plans/{id}
Request samples
application/json
{
  • "name": "string",
  • "productId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "productOptions": {
    },
  • "currency": "USD",
  • "pricing": {
    },
  • "recurringInterval": {
    },
  • "trial": {
    },
  • "setup": {
    },
  • "customFields": {
    },
  • "invoiceTimeShift": {
    }
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "productId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "productOptions": {
    },
  • "currency": "USD",
  • "currencySign": "string",
  • "pricing": {
    },
  • "recurringInterval": {
    },
  • "trial": {
    },
  • "isTrialOnly": true,
  • "setup": {
    },
  • "customFields": {
    },
  • "revision": 0,
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "invoiceTimeShift": {
    },
  • "_links": [
    ]
}

Delete a Plan

Delete a Plan with predefined identifier string.

Request
Security:
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
Responses
204

Plan was deleted.

401

Unauthorized access, invalid credentials was used.

404

Resource was not found.

409

Conflict.

delete/plans/{id}
Request samples
$client->plans()->delete('planId');
Response samples
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}