Update a plan

PUT 
/subscriptions/plans/:plan_uuid

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the plan is not updated.

Request

Path Parameters

plan_uuid UUIDrequired

The unique identifier of the plan.

application/json

Body

data PlanUpdaterequired

id UUID (string)required

The unique identifier.

type SubscriptionPlanType (string)required

Possible values: [subscription_plan]

attributes PlanUpdateAttributesrequired

external_ref ExternalRefUpdate (string)nullable

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 string

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

description stringnullable

Possible values: <= 1024 characters

The plan description to display to customers.

billing_interval_type string

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

The unit of time in which billing intervals are measured.

billing_frequency integer

Possible values: >= 1

The number of intervals between issuing bills.

trial_period integernullable

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 integer

Possible values: >= 1

The length of time for which a subscription plan is valid. For example, six months after which the plan is renewed.

end_behavior string

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 boolean

The subscriber can pause a subscription.

can_resume boolean

The subscriber can resume a paused subscription.

can_cancel boolean

The subscriber can cancel a subscription.

base_price_percentage doublenullable

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 objectnullable

property name* objectnullable

amount int64required

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

includes_tax boolean

Whether the amount includes any taxes.

Responses

200

Success. The details of the plan are updated.

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"
    }
  ]
}

403

Forbidden. The operation is forbidden on this entity.

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"
        ]
      }
    }
  ]
}

not-found

{
  "errors": [
    {
      "title": "Permission denied",
      "status": "404",
      "detail": "Permission denied: plan tenancy mismatch"
    }
  ]
}

404

Not found. The requested entity does not exist.

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"
        ]
      }
    }
  ]
}

not-found

{
  "errors": [
    {
      "title": "Not Found",
      "status": "404",
      "detail": "No plan found"
    }
  ]
}

409

Write conflict. Unable to perform the operation at this time.

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"
        ]
      }
    }
  ]
}

Example

{
  "errors": [
    {
      "title": "Write Conflict",
      "status": "409"
    }
  ]
}

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