Create add-on

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

An add-on is given a handle for own reference. The add-on handle can be at most 128 characters. Name will be reflected on the invoice.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Error code HTTP codeDescription
1400Invalid meta data size
10404Subscription plan not found
157404Tax policy not found
169404Entitlement not found
Body Params
string
required
length ≥ 1

Name of add-on. Will be used as order line text.

string

Optional description of add-on

int32
≥ 0

Add-on amount. Required when no pricing block is provided. For add-ons priced with a single per-unit price this reports that price, also when it is configured as a pricing curve. Null for tiered/stepped pricing.

float

Optional vat for add-on. Account default is used if none given.

string
enum
required

Add-on type on_off or quantity. An on_off type cannot be given a quantity when attached to subscription. For quantity type it is possible.
Type can only be updated from on_off to quantity. It is not allowed to change type from quantity to on_off.

Allowed:
string
required
length ≥ 1
^[a-zA-Z0-9_\.\-@]*$

Per account unique handle for the add-on

metadata
object

Custom metadata.

string

Currency for the add-on in ISO 4217 three letter alpha code. If not provided the account default currency will be used.

boolean

Whether the amount is including VAT. Default true.

string
^[a-zA-Z0-9_\.\-@]*$

Optional tax policy handle for add-on. Account default is used if none given.

int32
≥ 1

Minimum allowed quantity for a quantity type add-on, at least 1. Only allowed when type is quantity. When the add-on is attached without a quantity, this value is used as the quantity. A lower quantity, when attaching the add-on or with change_addon_quantity, is rejected with error code 228 (ADD_ON_QUANTITY_OUT_OF_RANGE).

int32
≥ 1

Maximum allowed quantity for a quantity type add-on, at least 1 and not lower than min_units. Only allowed when type is quantity. A higher quantity, when attaching the add-on or with change_addon_quantity, is rejected with error code 228 (ADD_ON_QUANTITY_OUT_OF_RANGE).

boolean

Whether all plans are eligible for this add-on. Defaults to false.

eligible_plans
array of strings, unique

If not all_plans are set to true, then the set of eligible plan handles must be defined.

eligible_plans
entitlements
array of strings, unique

List of entitlement handles for the add-on.

entitlements
pricing
object

Pricing curve of an add-on or of a subscription add-on, used instead of a flat amount. Any pricing other than a per_unit model with a single range requires the ADVANCED_ADDON_PRICING entitlement, otherwise the request is rejected with HTTP 403 and error code 209 (FEATURE_NOT_INCLUDED_IN_PLAN).

string

Cost object number (Kostenträger-Nr.) used for accounting export

string
enum

Billing period for the add-on. Defines the unit of the billing interval, so the add-on is billed on its own schedule instead of together with the subscription plan. If omitted, the add-on is billed on the billing period of the subscription plan. Copied onto the subscription add-on when the add-on is attached, and must fit the billing frequency of the subscription's plan, otherwise attaching it is rejected with error code 211 (BILLING_FREQUENCIES_MISMATCH_ADD_ON). Cannot be changed after the add-on is created.

Allowed:
int32
≥ 1

Billing interval length for the add-on. Defines how many billing periods between each billing. Only applies when billing_period is set, where 1 is used if it is omitted. Cannot be changed after the add-on is created.

Responses

Language
Credentials
Basic
base64
:
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json