Update a plan in an offering

PUT 
https://euwest.api.elasticpath.com/v2/subscriptions/offerings/:offering_uuid/plans/:plan_uuid

Use the unique identifier of the plan in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created.

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
idUUID (string)required
The unique identifier.
Example: 11111111-2222-3333-4444-555555555555
typeSubscriptionOfferingPlanType (string)required
Possible values: [subscription_offering_plan]
Example: subscription_offering_plan
attributes OfferingPlanUpdateAttributes
external_refExternalRefUpdate (string)nullable
A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
Possible values: <= 2048 characters
Example: abc123
namestring
The name of the plan.
Possible values: >= 3 characters and <= 1024 characters
Example: Magazine
descriptionstringnullable
The plan or service description to display to customers.
Possible values: <= 1024 characters
Example: A lovely magazine that is published every month.
skustringnullable
A stock keeping unit for the plan, if appropriate.
Possible values: <= 1024 characters
Example: MAGAZINE1
main_imagestring<uri>nullable
A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use Create a File to upload your file and return an HREF link in the response. An extensive range of media and file extensions are supported.
Possible values: <= 1024 characters
Example: https://magazine.com/cover.jpg
price objectnullable
property name* objectnullable
amountinteger<int64>required
The value as a whole number of the currency's smallest subdivision.
Example: 100
includes_taxboolean
Whether the amount includes any taxes.
Example: true
price_units objectnullable
The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the unit is months and the amount is 1. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.
unitstringrequired
A unit of time, either days or months.
Possible values: [day, month]
Example: day
amountintegerrequired
The number of days or months the period covers.
Possible values: >= 1
Example: 7
feature_configurations object
A map of configurations indicating which features are available for the plan
property name* FeaturePlanConfigurationUpdatenullable
typerequired
Possible values: [access, promotion, usage]
access
object
promotion
tagFeatureTag (string)required
A tag to add to the customer's account when entitled to the feature.
Possible values: non-empty and <= 64 characters, Value must match regular expression ^[0-9A-Za-z_-]+$
Example: digital_library_access
usage
default_valueintegerrequired
The default initial value
Example: 10

Responses

200

Success. The plan details are updated on the offering.

application/json

Schema

Schema

data OfferingPlan
idUUID (string)
The unique identifier.
Example: 11111111-2222-3333-4444-555555555555
typeSubscriptionOfferingPlanType (string)required
Possible values: [subscription_offering_plan]
Example: subscription_offering_plan
attributes OfferingPlanResponseAttributes
external_refExternalRef (string)
A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
Possible values: <= 2048 characters
Example: abc123
namestringrequired
The name of the plan.
Possible values: >= 3 characters and <= 1024 characters
Example: Magazine
descriptionstring
The plan or service description to display to customers.
Possible values: <= 1024 characters
Example: A lovely magazine that is published every month.
skustring
A stock keeping unit for the plan, if appropriate.
Possible values: <= 1024 characters
Example: MAGAZINE1
main_imagestring<uri>
A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use Create a File to upload your file and return an HREF link in the response. An extensive range of media and file extensions are supported.
Possible values: <= 1024 characters
Example: https://magazine.com/cover.jpg
price Price
property name* object
The base price.
amountinteger<int64>required
The value as a whole number of the currency's smallest subdivision.
Example: 100
includes_taxboolean
Indicates whether the amount includes any taxes.
Example: true
price_units object
The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the unit is months and the amount is 1. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.
unitstringrequired
A unit of time.
Possible values: [day, month]
Example: day
amountintegerrequired
The number of days or months the period covers.
Possible values: >= 1
Example: 7
updated_atstringrequired
The date and time a resource was updated.
Example: 2017-01-10T11:41:19.244842Z
created_atstringrequired
The date and time a resource was created.
Example: 2017-01-10T11:41:19.244842Z
feature_configurations objectrequired
A map of configurations indicating which features are available for the plan
property name* FeaturePlanConfiguration
typerequired
Possible values: [access, promotion, usage]
access
object
promotion
tagFeatureTag (string)required
A tag to add to the customer's account when entitled to the feature.
Possible values: non-empty and <= 64 characters, Value must match regular expression ^[0-9A-Za-z_-]+$
Example: digital_library_access
usage
default_valueintegerrequired
The default initial value
Example: 10
relationships Relationships
Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.
property name* Relationship
anyOf
SingleRelationship
ManyRelationship
meta PlanMetarequired
prices object
A list of plan prices for each of its pricing options.
property name* OfferingPlanPriceForPricingOption
price Price
property name* object
The base price.
amountinteger<int64>required
The value as a whole number of the currency's smallest subdivision.
Example: 100
includes_taxboolean
Indicates whether the amount includes any taxes.
Example: true
display_price DisplayPrice
without_tax PriceFormatting
amountinteger<int64>required
The unformatted amount for the objects.
Example: 100
currencystring<string>required
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstring<string>required
The formatted amount for the objects.
Example: $1.00
with_tax PriceFormatting
amountinteger<int64>required
The unformatted amount for the objects.
Example: 100
currencystring<string>required
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstring<string>required
The formatted amount for the objects.
Example: $1.00
display_price DisplayPrice
without_tax PriceFormatting
amountinteger<int64>required
The unformatted amount for the objects.
Example: 100
currencystring<string>required
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstring<string>required
The formatted amount for the objects.
Example: $1.00
with_tax PriceFormatting
amountinteger<int64>required
The unformatted amount for the objects.
Example: 100
currencystring<string>required
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstring<string>required
The formatted amount for the objects.
Example: $1.00
ownerstring<string>required
The owner of a resource, either store or organization.
Example: store
timestamps Timestampsrequired
updated_atstringrequired
The date and time a resource was updated.
Example: 2017-01-10T11:41:19.244842Z
created_atstringrequired
The date and time a resource was created.
Example: 2017-01-10T11:41:19.244842Z
active_planActivePlan (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.
Example: true

Example (auto)

{
  "data": {
    "id": "11111111-2222-3333-4444-555555555555",
    "type": "subscription_offering_plan",
    "attributes": {
      "external_ref": "abc123",
      "name": "Magazine",
      "description": "A lovely magazine that is published every month.",
      "sku": "MAGAZINE1",
      "main_image": "https://magazine.com/cover.jpg",
      "price": {
        "USD": {
          "amount": 100,
          "includes_tax": false
        },
        "GBP": {
          "amount": 90,
          "includes_tax": true
        }
      },
      "price_units": {
        "unit": "day",
        "amount": 7
      },
      "updated_at": "2017-01-10T11:41:19.244842Z",
      "created_at": "2017-01-10T11:41:19.244842Z",
      "feature_configurations": {}
    },
    "relationships": {
      "pricing-options": {
        "links": {
          "related": "/offerings/:offering-id/pricing-options",
          "self": "/offerings/:offering-id"
        },
        "data": {
          "type": "offering-pricing-option",
          "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
        }
      }
    },
    "meta": {
      "prices": {},
      "display_price": {
        "without_tax": {
          "amount": 100,
          "currency": "USD",
          "formatted": "$1.00"
        },
        "with_tax": {
          "amount": 110,
          "currency": "USD",
          "formatted": "$1.10"
        }
      },
      "owner": "store",
      "timestamps": {
        "updated_at": "2017-01-10T11:41:19.244842Z",
        "created_at": "2017-01-10T11:41:19.244842Z"
      },
      "active_plan": true
    }
  }
}

400

Bad request. The request failed validation.

application/json

Schema

Schema

errors Error[]required
Array [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
metaobject
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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 [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
metaobject
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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 [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
metaobject
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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 [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
metaobject
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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 [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
metaobject
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

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

Authorization: http

name: BearerTokentype: httpscheme: bearer

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

Request Collapse all

Base URL

https://euwest.api.elasticpath.com/v2

Auth

Bearer Token

Parameters

offering_uuid — pathrequired

plan_uuid — pathrequired

Body

{
  "data": {
    "id": "11111111-2222-3333-4444-555555555555",
    "type": "subscription_offering_plan",
    "attributes": {
      "external_ref": "abc123",
      "name": "Magazine",
      "description": "A lovely magazine that is published every month.",
      "sku": "MAGAZINE1",
      "main_image": "https://magazine.com/cover.jpg",
      "price": {
        "USD": {
          "amount": 100,
          "includes_tax": false
        },
        "GBP": {
          "amount": 90,
          "includes_tax": true
        }
      },
      "price_units": {
        "unit": "day",
        "amount": 7
      },
      "feature_configurations": {}
    }
  }
}

ResponseClear

Click the Send API Request button above and see the response here!