List plans

GET 
/subscriptions/plans

Retrieves a list of all subscription plans.

Filtering

This endpoint supports filtering. For the general syntax, see Filtering.

The following attributes and operators are supported.

Operator	Attribute	Description
eq	external_ref	Equals. Checks if the values of two operands are equal. If they are, the condition is true.

Request

Query Parameters

page[offset] int64

Possible values: <= 10000

The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the page length store setting is used.

page[limit] int64

The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the page length store setting is used.

Responses

200

Success. A list of subscription plans is returned.

application/json

Schema

Schema

data Plan[]
Array [
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.
]
links object
anyOf
title

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"
        }
      }
    }
  ],
  "links": {}
}

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