Attach a plan

POST 
https://euwest.api.elasticpath.com/v2/subscriptions/offerings/:offering_uuid/plans/attach

After saving an offering, you can attach new plans to it at any time.

Attaching new plans to an offering does not affect any existing 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.

application/json

Body

data OfferingPlanAttachrequired

A list of plan IDs to attach to the offering. See List Plans.

plansUUID (string)[]required

Possible values: >= 1

Responses

200

Success. The subscription plan is attached with the offering.

application/json

Schema

Schema

data OfferingPlan[]
Array [
idUUID (string)
The unique identifier.
Example: 11111111-2222-3333-4444-555555555555
typeSubscriptionOfferingPlanType (string)required
Possible values: [subscription_offering_plan]
Example: subscription_offering_plan
attributes PlanResponseAttributes
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
A name for the plan.
Possible values: >= 3 characters and <= 1024 characters
Example: Monthly
descriptionstring
The plan description to display to customers.
Possible values: <= 1024 characters
Example: A monthly subscription.
billing_interval_typestringrequired
The unit of time that billing intervals are measured.
Possible values: [day, week, month, year]
Example: month
billing_frequencyintegerrequired
The number of intervals between issuing bills.
Possible values: >= 1
Example: 1
trial_periodinteger
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.
Example: 7
plan_lengthintegerrequired
The number of intervals that the subscription runs for.
Possible values: >= 1
Example: 12
end_behaviorstringrequired
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.
Possible values: [close, roll]
Example: close
can_pausebooleanrequired
The subscriber can pause a subscription.
Example: false
can_resumebooleanrequired
The subscriber can resume a paused subscription.
Example: false
can_cancelbooleanrequired
The subscriber can cancel a subscription.
Example: false
base_price_percentagedouble
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.
Possible values: <= 100
Example: 90
fixed_price Price
property name* object
The base price.
amountint64required
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
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
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.
property name* Relationship
anyOf
SingleRelationship
ManyRelationship
meta OfferingPlanMetarequired
price Price
property name* object
The base price.
amountint64required
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
amountint64required
The unformatted amount for the objects.
Example: 100
currencystringrequired
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstringrequired
The formatted amount for the objects.
Example: $1.00
with_tax PriceFormatting
amountint64required
The unformatted amount for the objects.
Example: 100
currencystringrequired
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstringrequired
The formatted amount for the objects.
Example: $1.00
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
ownerstringrequired
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
]

Example (auto)

{
  "data": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "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 [
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"
    }
  ]
}

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

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://euwest.api.elasticpath.com/v2/subscriptions/offerings/:offering_uuid/plans/attach");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer <token>");
var content = new StringContent("{\n  \"data\": {\n    \"plans\": [\n      \"11111111-2222-3333-4444-555555555555\"\n    ]\n  }\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request Collapse all

Base URL

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

Auth

Bearer Token

Parameters

offering_uuid — pathrequired

Body

{
  "data": {
    "plans": [
      "11111111-2222-3333-4444-555555555555"
    ]
  }
}

ResponseClear

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