Build an offering

POST 
https://euwest.api.elasticpath.com/v2/subscriptions/offerings/build

An offering includes products and plans; products are combined with one or more plans to form an offering. An offering can include either:

• subscription products. See create a product.
• Product Experience Manager products. See create a product.

Offerings represent a snapshot of their products and plans. If you make updates to products or plans within an offering, the original products and plans are not updated. Only the products and plans within the offering are updated. Alternatively, you can create new products or plans and attach them to an existing offering.

When you are building an offering:

• you can create new plans and products.
• you can modify an existing product and plans. For example, you can modify the product price or any attributes of a plan included in the offering.

Here's how you build an offering:

1. Specify the product to build with the offering. A product can be:

   • subscription products. Specify the subscription product attributes.
   • Product Experience Manager products. Specify the Product Experience Manager product ID in external_ref in ProductAttributes. For the remaining product attributes, you can specify their values to match the values of the existing Product Experience Manager product attributes. However, you can also specify different values, depending on your requirements.

2. Specify the plans to build with the offering. Plans are the rules that govern your subscription, for example, any discount. You can combine and reuse plans for as many products as you want, making it quick and easy to create your subscription offerings. An offering must have at least one plan.

Request

application/json

Body

data BuildOfferingrequired
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 offering.
Possible values: >= 3 characters and <= 1024 characters
Example: Magazine
descriptionstring
The offering description to display to customers.
Possible values: <= 1024 characters
Example: A lovely magazine that is published every month.
proration_policy_idstring
The unique ID or external ref of the proration policy
Example: 11111111-2222-3333-4444-555555555555
configured_features object
Map of feature configurations keyed by product UUID or external_ref
property name* OfferingBuildProductFeatures
A map of configurations indicating which features are available for the product
property name* FeatureProductConfiguration
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
features object[]
Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering
Possible values: >= 1
Array [
anyOf
ExternalRef
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
FeatureAttributes
UUID
string
The unique identifier.
Example: 11111111-2222-3333-4444-555555555555
]
products object[]required
Either references of existing products (id or external_ref) to be attached to the offering or product information to be created directly within the offering
Possible values: >= 1
Array [
anyOf
ExternalRef
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
ProductAttributes
UUID
string
The unique identifier.
Example: 11111111-2222-3333-4444-555555555555
]
plans object[]required
Either references of existing plans (id or external_ref) to be attached to the offering or plan information to be created directly within the offering
Possible values: >= 1
Array [
anyOf
ExternalRef
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
PlanAttributes
UUID
string
The unique identifier.
Example: 11111111-2222-3333-4444-555555555555
]

Responses

201

Success. The new subscription offering is created with the specified subscription products and plans attached to the offering.

application/json

Schema

Schema

data Offering
idUUID (string)
The unique identifier.
Example: 11111111-2222-3333-4444-555555555555
typeSubscriptionOfferingType (string)required
Possible values: [subscription_offering]
Example: subscription_offering
attributes OfferingResponseAttributes
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 offering.
Possible values: >= 3 characters and <= 1024 characters
Example: Magazine
descriptionstring
The offering description to display to customers.
Possible values: <= 1024 characters
Example: A lovely magazine that is published every month.
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 OfferingMetarequired
external_product_refsstring[]required
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",
    "attributes": {
      "external_ref": "abc123",
      "name": "Magazine",
      "description": "A lovely magazine that is published every month.",
      "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": {
      "external_product_refs": [
        "97dddc65-eabd-45d8-b45b-2ece5cfc8c50"
      ],
      "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"
    }
  ]
}

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/build");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer <token>");
var content = new StringContent("{\n  \"data\": {\n    \"external_ref\": \"abc123\",\n    \"name\": \"Magazine\",\n    \"description\": \"A lovely magazine that is published every month.\",\n    \"proration_policy_id\": \"11111111-2222-3333-4444-555555555555\",\n    \"configured_features\": {},\n    \"features\": [\n      \"abc123\",\n      {\n        \"external_ref\": \"abc123\",\n        \"name\": \"Digital library access\",\n        \"description\": \"Access to over 100 ebooks via the digital library.\",\n        \"configuration\": {\n          \"type\": \"access\",\n          \"tag\": \"digital_library_access\"\n        }\n      },\n      \"11111111-2222-3333-4444-555555555555\"\n    ],\n    \"products\": [\n      \"abc123\",\n      {\n        \"external_ref\": \"abc123\",\n        \"name\": \"Magazine\",\n        \"description\": \"A lovely magazine that is published every month.\",\n        \"sku\": \"MAGAZINE1\",\n        \"main_image\": \"https://magazine.com/cover.jpg\",\n        \"price\": {\n          \"USD\": {\n            \"amount\": 100,\n            \"includes_tax\": false\n          },\n          \"GBP\": {\n            \"amount\": 90,\n            \"includes_tax\": true\n          }\n        },\n        \"price_units\": {\n          \"unit\": \"day\",\n          \"amount\": 7\n        }\n      },\n      \"11111111-2222-3333-4444-555555555555\"\n    ],\n    \"plans\": [\n      \"abc123\",\n      {\n        \"external_ref\": \"abc123\",\n        \"name\": \"Monthly\",\n        \"description\": \"A monthly subscription.\",\n        \"billing_interval_type\": \"month\",\n        \"billing_frequency\": 1,\n        \"trial_period\": 7,\n        \"plan_length\": 12,\n        \"end_behavior\": \"close\",\n        \"can_pause\": false,\n        \"can_resume\": false,\n        \"can_cancel\": false,\n        \"base_price_percentage\": 90,\n        \"fixed_price\": {\n          \"USD\": {\n            \"amount\": 100,\n            \"includes_tax\": false\n          },\n          \"GBP\": {\n            \"amount\": 90,\n            \"includes_tax\": true\n          }\n        }\n      },\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

Body

{
  "data": {
    "external_ref": "abc123",
    "name": "Magazine",
    "description": "A lovely magazine that is published every month.",
    "proration_policy_id": "11111111-2222-3333-4444-555555555555",
    "configured_features": {},
    "features": [
      "abc123",
      {
        "external_ref": "abc123",
        "name": "Digital library access",
        "description": "Access to over 100 ebooks via the digital library.",
        "configuration": {
          "type": "access",
          "tag": "digital_library_access"
        }
      },
      "11111111-2222-3333-4444-555555555555"
    ],
    "products": [
      "abc123",
      {
        "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
        }
      },
      "11111111-2222-3333-4444-555555555555"
    ],
    "plans": [
      "abc123",
      {
        "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
          }
        }
      },
      "11111111-2222-3333-4444-555555555555"
    ]
  }
}

ResponseClear

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