Create a plan

POST 
/subscriptions/plans

Create a plan

Request

application/json

Body

data PlanCreaterequired

type SubscriptionPlanType (string)required

Possible values: [subscription_plan]

attributes PlanAttributesrequired

external_ref ExternalRef (string)

Possible values: <= 2048 characters

A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

name stringrequired

Possible values: >= 3 characters and <= 1024 characters

A name for the plan.

description string

Possible values: <= 1024 characters

The plan description to display to customers.

billing_interval_type stringrequired

Possible values: [day, week, month, year]

The unit of time that billing intervals are measured.

billing_frequency integerrequired

Possible values: >= 1

The number of intervals between issuing bills.

trial_period integer

The number of intervals from the start of the subscription before billing starts. Used with billing_interval_type. For example, if billing_interval_type is months, and trial_period is 1, the trial period is 1 month.

plan_length integerrequired

Possible values: >= 1

The number of intervals that the subscription runs for.

end_behavior stringrequired

Possible values: [close, roll]

Enables you to specify recurring payments. If end_behavior is roll, customers pay regularly and repeatedly. If end_behavior is close, customers pay a total amount in a limited number of partial payments.

can_pause booleanrequired

The subscriber can pause a subscription.

can_resume booleanrequired

The subscriber can resume a paused subscription.

can_cancel booleanrequired

The subscriber can cancel a subscription.

base_price_percentage double

Possible values: <= 100

A percentage discount on the total cost of any products within an offering. For example, you can configure a percentage that equates the cost of a plan to the total value of all products within the offering, reduced by a percentage. For example, if you specify 10, a 10% discount is applied to the total value of all repeat products in an offering.

fixed_price Price

property name* object

The base price.

amount int64required

The value as a whole number of the currency's smallest subdivision.

includes_tax boolean

Indicates whether the amount includes any taxes.

Responses

201

Success. The subscription plan is created.

application/json

Schema

Schema

data Plan

id UUID (string)

The unique identifier.

type SubscriptionPlanType (string)required

Possible values: [subscription_plan]

attributes PlanAttributesrequired

external_ref ExternalRef (string)

Possible values: <= 2048 characters

A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

name stringrequired

Possible values: >= 3 characters and <= 1024 characters

A name for the plan.

description string

Possible values: <= 1024 characters

The plan description to display to customers.

billing_interval_type stringrequired

Possible values: [day, week, month, year]

The unit of time that billing intervals are measured.

billing_frequency integerrequired

Possible values: >= 1

The number of intervals between issuing bills.

trial_period integer

The number of intervals from the start of the subscription before billing starts. Used with billing_interval_type. For example, if billing_interval_type is months, and trial_period is 1, the trial period is 1 month.

plan_length integerrequired

Possible values: >= 1

The number of intervals that the subscription runs for.

end_behavior stringrequired

Possible values: [close, roll]

Enables you to specify recurring payments. If end_behavior is roll, customers pay regularly and repeatedly. If end_behavior is close, customers pay a total amount in a limited number of partial payments.

can_pause booleanrequired

The subscriber can pause a subscription.

can_resume booleanrequired

The subscriber can resume a paused subscription.

can_cancel booleanrequired

The subscriber can cancel a subscription.

base_price_percentage double

Possible values: <= 100

A percentage discount on the total cost of any products within an offering. For example, you can configure a percentage that equates the cost of a plan to the total value of all products within the offering, reduced by a percentage. For example, if you specify 10, a 10% discount is applied to the total value of all repeat products in an offering.

fixed_price Price

property name* object

The base price.

amount int64required

The value as a whole number of the currency's smallest subdivision.

includes_tax boolean

Indicates whether the amount includes any taxes.

updated_at stringrequired

The date and time a resource was updated.

created_at stringrequired

The date and time a resource was created.

meta PlanMetarequired

owner stringrequired

The owner of a resource, either store or organization.

timestamps Timestampsrequired

updated_at stringrequired

The date and time a resource was updated.

created_at stringrequired

The date and time a resource was created.

Example (from schema)

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "subscription_plan",
    "attributes": {
      "external_ref": "abc123",
      "name": "Monthly",
      "description": "A monthly subscription.",
      "billing_interval_type": "month",
      "billing_frequency": 1,
      "trial_period": 7,
      "plan_length": 12,
      "end_behavior": "close",
      "can_pause": false,
      "can_resume": false,
      "can_cancel": false,
      "base_price_percentage": 90,
      "fixed_price": {
        "USD": {
          "amount": 100,
          "includes_tax": false
        },
        "GBP": {
          "amount": 90,
          "includes_tax": true
        }
      },
      "updated_at": "2017-01-10T11:41:19.244842Z",
      "created_at": "2017-01-10T11:41:19.244842Z"
    },
    "meta": {
      "owner": "store",
      "timestamps": {
        "updated_at": "2017-01-10T11:41:19.244842Z",
        "created_at": "2017-01-10T11:41:19.244842Z"
      }
    }
  }
}

400

Bad request. The request failed validation.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

missing-name

{
  "errors": [
    {
      "title": "Validation Error",
      "status": "400",
      "detail": "data.attributes.name: \"name\" is required"
    }
  ]
}

500

Internal server error. There was a system failure in the platform.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

internal-server-error

{
  "errors": [
    {
      "title": "Internal Server Error",
      "status": "500"
    }
  ]
}

Loading...