Updates a plan in an offering

PUT 
/subscriptions/offerings/:offering_uuid/plans/:plan_uuid

Updates a plan in an offering

Request

Path Parameters

offering_uuid UUIDrequired

The unique identifier of the offering.

plan_uuid UUIDrequired

The unique identifier of the plan.

application/json

Body

data OfferingPlanUpdaterequired

id UUID (string)required

The unique identifier.

type SubscriptionOfferingPlanType (string)required

Possible values: [subscription_offering_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 plan details are updated on the offering.

application/json

Schema

Schema

data OfferingPlan

id UUID (string)

The unique identifier.

type SubscriptionOfferingPlanType (string)required

Possible values: [subscription_offering_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.

relationships Relationships

Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.

anyOf

title

meta OfferingPlanMetarequired

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.

display_price DisplayPrice

without_tax PriceFormatting

amount int64required

The unformatted amount for the objects.

currency stringrequired

The three-letter ISO currency code in uppercase, associated with a price.

formatted stringrequired

The formatted amount for the objects.

with_tax PriceFormatting

amount int64required

The unformatted amount for the objects.

currency stringrequired

The three-letter ISO currency code in uppercase, associated with a price.

formatted stringrequired

The formatted amount for the objects.

active_plan ActivePlan (boolean)

Whether a plan is active on a subscription using that offering. The active_plan attribute is null if a plan is not active in a subscription.

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_offering_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"
    },
    "relationships": {
      "plans": {
        "links": {
          "related": "/offerings/:offering-id/plans",
          "self": "/offerings/:offering-id"
        },
        "data": {
          "type": "offering-plan",
          "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
        }
      }
    },
    "meta": {
      "price": {
        "USD": {
          "amount": 100,
          "includes_tax": false
        },
        "GBP": {
          "amount": 90,
          "includes_tax": true
        }
      },
      "display_price": {
        "without_tax": {
          "amount": 100,
          "currency": "USD",
          "formatted": "$1.00"
        },
        "with_tax": {
          "amount": 110,
          "currency": "USD",
          "formatted": "$1.10"
        }
      },
      "active_plan": true,
      "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...