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.

Authorizations:
query Parameters
filter
string

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

sort
Array of strings

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

limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

q
string

The partial search of the text fields.

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

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

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

Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

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

The plan ID.

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.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

currencySign
string

Currency sign.

required
object (PlanPriceFormula)
object

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

object

The trial. Set null if no trial.

isTrialOnly
boolean

Whether a plan has a trial without recurring instructions.

object

The setup. Set null if no setup.

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

revision
integer

Increments when the plan is modified. Compare to materialized subscription items revision.

createdTime
string <date-time>

Plan created time.

updatedTime
string <date-time>

Plan updated time.

object

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

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

$plans = $client->plans()->search([
    'filter' => 'name:TestPlan',
]);

Response samples

Content type
application/json
[
  • {
    }
]

Create a plan

Create a plan.

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

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

Request Body schema: application/json

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.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

required
object (PlanPriceFormula)
object

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

object

The trial. Set null if no trial.

object

The setup. Set null if no setup.

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.

Responses

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

The plan ID.

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.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

currencySign
string

Currency sign.

required
object (PlanPriceFormula)
object

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

object

The trial. Set null if no trial.

isTrialOnly
boolean

Whether a plan has a trial without recurring instructions.

object

The setup. Set null if no setup.

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

revision
integer

Increments when the plan is modified. Compare to materialized subscription items revision.

createdTime
string <date-time>

Plan created time.

updatedTime
string <date-time>

Plan updated time.

object

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

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "name": "string",
  • "productId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "productOptions": {
    },
  • "currency": "USD",
  • "pricing": {
    },
  • "recurringInterval": {
    },
  • "trial": {
    },
  • "setup": {
    },
  • "customFields": {
    },
  • "invoiceTimeShift": {
    }
}

Response samples

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

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

The resource identifier string.

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

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

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

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

The plan ID.

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.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

currencySign
string

Currency sign.

required
object (PlanPriceFormula)
object

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

object

The trial. Set null if no trial.

isTrialOnly
boolean

Whether a plan has a trial without recurring instructions.

object

The setup. Set null if no setup.

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

revision
integer

Increments when the plan is modified. Compare to materialized subscription items revision.

createdTime
string <date-time>

Plan created time.

updatedTime
string <date-time>

Plan updated time.

object

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

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

$plan = $client->plans()->load('planId');

Response samples

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

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

The resource identifier string.

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

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

Request Body schema: application/json

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.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

required
object (PlanPriceFormula)
object

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

object

The trial. Set null if no trial.

object

The setup. Set null if no setup.

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.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

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

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

The plan ID.

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.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

currencySign
string

Currency sign.

required
object (PlanPriceFormula)
object

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

object

The trial. Set null if no trial.

isTrialOnly
boolean

Whether a plan has a trial without recurring instructions.

object

The setup. Set null if no setup.

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

revision
integer

Increments when the plan is modified. Compare to materialized subscription items revision.

createdTime
string <date-time>

Plan created time.

updatedTime
string <date-time>

Plan updated time.

object

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

Array of objects (SelfLink) non-empty

The links related to resource.

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

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

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

The plan ID.

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.

currency
required
string 3 characters

ISO 4217 alphabetic currency code.

currencySign
string

Currency sign.

required
object (PlanPriceFormula)
object

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

object

The trial. Set null if no trial.

isTrialOnly
boolean

Whether a plan has a trial without recurring instructions.

object

The setup. Set null if no setup.

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

revision
integer

Increments when the plan is modified. Compare to materialized subscription items revision.

createdTime
string <date-time>

Plan created time.

updatedTime
string <date-time>

Plan updated time.

object

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

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "name": "string",
  • "productId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "productOptions": {
    },
  • "currency": "USD",
  • "pricing": {
    },
  • "recurringInterval": {
    },
  • "trial": {
    },
  • "setup": {
    },
  • "customFields": {
    },
  • "invoiceTimeShift": {
    }
}

Response samples

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

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

The resource identifier string.

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

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

Responses

Request samples

$client->plans()->delete('planId');

Response samples

Content type
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}