Build an offering

POST 
/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_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

The name of the offering.

description string

Possible values: <= 1024 characters

The offering description to display to customers.

products object[]required

Possible values: >= 1

Either IDs of existing products to be attached to the plan or product information to be created directly within the plan

Array [

anyOf

UUID

string

ProductAttributes

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

The name of the product.

description string

Possible values: <= 1024 characters

The product or service description to display to customers.

sku string

Possible values: <= 1024 characters

A stock keeping unit for the product, if appropriate.

main_image uri

Possible values: <= 1024 characters

A URL from which an image or file for the product 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.

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.

price_units object

The timeframe during which the product 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 products that all have different prices. Rather than having to create separate plans for each product, you can specify the timeframe during which the product price is applicable and then create one plan that determines the billing frequency for those products.

unit stringrequired

Possible values: [day, month]

A unit of time.

amount integerrequired

Possible values: >= 1

The number of days or months the period covers.

]

plans UUID (string)[]required

Possible values: >= 1

The IDs of the plans to attach to the offering.

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

id UUID (string)

The unique identifier.

type SubscriptionOfferingType (string)required

Possible values: [subscription_offering]

attributes OfferingAttributesrequired

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

The name of the offering.

description string

Possible values: <= 1024 characters

The offering description to display to customers.

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 OfferingMetarequired

external_product_refs string[]required

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

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