Skip to content

Creating a Seller Service Product

Products are created under a service and are what organizations will purchase to create a subscription. To create a product, a service identifier is needed to create the product under the right service. If you plan to use email notifications, the email templates should be created in Cloudmore and can be retrieved through API.

NOTE! Creating products can be done through the Cloudmore user interface or API. This guide will focus on API usage.

API Details

SellerServiceProducts
OperationSwagger DescriptionMethodAPI
Create a ProductCreates new product for Seller servicePOST/api/sellers/{sellerId}/services/{serviceId}/products
Return a ProductReturns seller service product detailsGET/api/sellers/{sellerId}/services/{serviceId}/products/{id}
Return all ProductsReturns all seller service productsGET/api/sellers/{sellerId}/services/{serviceId}/products
Update a ProductUpdates seller service productPUT/api/sellers/{sellerId}/services/{serviceId}/products/{id}
Delete a ProductDeletes seller service productDELETE/api/sellers/{sellerId}/services/{serviceId}/products/{id}
Other
Retrieve Email TemplatesReturns all seller email templatesGET/api/sellers/{sellerId}/settings/EmailTemplates

API Examples

Retrieve the Service
End Point/api/sellers/{sellerId}/services
HTTP MethodGET
Request BodyN/A.
Successful Example Response200[ { "id": "8806367b-001a-4632-afb4-27a7fad7660c", "name": "Google Workspace (Integrations Guide Service)", "vendorName": "Google", "allowMultipleUsers": false, "customProperties": [ { "type": "TextBox", "propertyId": "account_id", "name": "Account Id", "defaultValue": "", "visible": true, "mandatory": true, "allowedValues": [ "" ], "appliesToOrganizations": false, "appliesToBrokers": true, "appliesToSeller": false }, { "type": "TextBox", "propertyId": "adminFirstName", "name": "Organization Admin First Name", "defaultValue": "", "visible": true, "mandatory": true, "allowedValues": [ "" ], "appliesToOrganizations": true, "appliesToBrokers": false, "appliesToSeller": false }, { "type": "TextBox", "propertyId": "adminLastName", "name": "Organization Admin Last Name", "defaultValue": "", "visible": true, "mandatory": true, "allowedValues": [ "" ], "appliesToOrganizations": true, "appliesToBrokers": false, "appliesToSeller": false }, { "type": "TextBox", "propertyId": "domain", "name": "Domain", "defaultValue": "", "visible": true, "mandatory": true, "allowedValues": [ "" ], "appliesToOrganizations": true, "appliesToBrokers": true, "appliesToSeller": false }, { "type": "CheckBox", "propertyId": "cloudIdentityExists", "name": "Cloud Identity Exists", "defaultValue": "", "visible": false, "mandatory": false, "allowedValues": [ "" ], "appliesToOrganizations": false, "appliesToBrokers": true, "appliesToSeller": false }, { "type": "TextBox", "propertyId": "customerId", "name": "Customer Id", "defaultValue": "", "visible": false, "mandatory": false, "allowedValues": [ "" ], "appliesToOrganizations": true, "appliesToBrokers": false, "appliesToSeller": false }, { "type": "TextBox", "propertyId": "siteVerificationToken", "name": "Site Verification Token", "defaultValue": "", "visible": false, "mandatory": false, "allowedValues": [ "" ], "appliesToOrganizations": true, "appliesToBrokers": false, "appliesToSeller": false }, { "type": "TextBox", "propertyId": "siteVerification", "name": "Site Verification", "defaultValue": "", "visible": false, "mandatory": false, "allowedValues": [ "" ], "appliesToOrganizations": true, "appliesToBrokers": false, "appliesToSeller": false } ] } ]
Error Example Response404
Create a Product
End Point/api/sellers/{sellerId}/services/{serviceId}/products
HTTP MethodPOST
Request Body{ "type": "Metered", "customer": "Broker", "name": "Google Workspace (pay as you go)", "description": "Add and delete users at any time. You will be billed at the end of the month for the actual number of accounts in service during the month.", "itemCode": "payg", "billingType": "RecurringBilling", "subscriptionPeriodMonths": "M1", "paymentFrequencyMonths": "M1", "price": 10, "cost": 5, "recommendedPrice": 15, "minimumQuantity": 1, "allowUpgrade": false, "allowDowngrade": false, "renewalAction": "AutomaticRenewal", "cancelTime": "AutoDeleteAtEndOfSubscription", "enableTrial": false, "enforceTrial": false, "customProperties": [ { "type": "TextBox", "id": "entitlementId", "name": "Entitlement Id", "defaultValue": "", "visible": false, "mandatory": false } ], "allowOneSubscriptionPerProduct": true }
Successful Example Response201
Error Example Response400{ "CancelPeriod": [ "CancelPeriod can be set only if CancelTime is set to DeleteAfterSpecifiedTimePeriod" ], "BillingPeriodType": [ "BillingPeriodType can be set only for Type ProductBased." ] }

Field Definitions

FieldDescription
billingTypeA choice of whether the product would have one-time or recurring billing
RecurringBilling = 0
OneTime = 1
Default value = 0
typeA choice if the price is determined by quantity (ProductBased) or usage (Metered)
ProductBased = 0
Metered = 1
Default value = 0
This field is only applicable for recurring billing.
customerDetermines who would see the product or service plan
Broker = 0
Enterprise = 1
Default value = 0
name*The main product identifier used throughout the platform.
description*A longer description about the product.
itemCode*Unique code for that item. Also known as SKU (Stock Keeping Unit).
subscriptionPeriodMonthsDetermines how many months a subscription will last for:
M0 = 0 (Billed Once)
M1 = 1 month
M12 = 12 months
M24 = 24 months
M36 = 36 months
M48 = 48 months
M60 = 60 months

RecurringBilling
Values starting from M1 (1) are available
OneTime
Set the value to “M0” (0)
paymentFrequencyMonthsThe payment frequency in months
M0 = 0 (Billed Once)
M1 = 1 month
M3 = 3 months
M6 = 6 months
M12 = 12 months
M24 = 24 months
M36 = 36 months
M48 = 48 months
M60 = 60 months

RecurringBilling
“M0” (0) not available
If the subscription period month is M1 (1), monthly, then only M1 (1) should be selected.
Payment frequency cannot be greater than the subscription period months
OneTimeSet the value to “M0” (0)
priceThe price for the broker.
costThe cost for the seller.
recommendedPriceThe price, which is suggested for brokers to use when they sell to organizations.
minimumQuantityThe defined minimum amount that can be bought by the organization when creating a subscription. MeteredZero can be set only for metered products
maximumQuantityThe defined maximum amount that can be bought by the organization when creating a subscription. Maximum quantity of product is only available for recurring billing and for product based.
startupItemCodeDetermines if there’s an upfront fee for the organization.Only available if StartupFee > 0.
startupFeeThe startup fee price.
Product startup fee only available for RecurringBilling.
allowUpgradeDetermines if the product allows for downgrading.Only available for RecurringBilling and if subscription period months greater than 1 month.When set to true, the value in property AllowChangesWhenDaysLeft will be set to 0.
allowDowngradeDetermines if the product allows for downgrading.
Only available for RecurringBilling and if the subscription period months greater than 1 month.
When set to true, the value in the property AllowChangesWhenDaysLeft will be set to 0.
allowChangesWhenDaysLeftPeriod in days where changes in product are allowed.
Only available for RecurringBilling and if subscription period months greater than 1 month.
productListPriorityThe position where this product would be in the list of products.
renewalActionDetermines what happens at the end of the subscription periodAutomaticRenewalAutomaticCancelChangeProductFor product billing type OneTime set the value to Automatic Renewal.
renewalChangeProductIdRenewal change product identifier.
Only available for RecurringBilling and only for renewalAction=ChangeProduct.
cancelTimeHow the subscription would be cancelled:AutoDeleteAtEndOfSubscriptionImmediatelyDeleteDeleteAfterSpecifiedTimePeriodFor billing type OneTime set the value to ImmediatelyDelete.
cancelPeriodTypeThe cancel period type in months or days.
cancelPeriodThe cancel period in days or months.
notificationDaysLeftDetermines if and when the “Days left” email will be sent outOnly available for SellerServiceProductType.
ServicePlan
D0 = 0 days left
D1 = 1 day left
D3 = 3 days left
D7 = 7 days left
D14 = 14 days left
D30 = 30 days left
D60 = 60 days left
D90 = 90 days left
notificationTemplateIdId of the email template which is used for notification.
Only available for RecurringBilling.
Available templates can be retrieved with call to /api/sellers/{sellerId}/settings/EmailTemplates.
notifyOnExpirationIf set to true, then a notification email is sent on subscription expiration.
Only available for RecurringBilling.
notifyOnExpirationTemplateIdIdentifier of the email template which is used for notification.
Only available for RecurringBilling.
Available templates can be retrieved with call to /api/sellers/{sellerId}/settings/EmailTemplates.
enableTrialDetermines if there’s a trial included with the subscription.
Only available for RecurringBilling.
trialPeriodDaysTrial period in days.
Only available for RecurringBilling.
enforceTrialIf true, trial period is mandatory.
Only available for RecurringBilling.
provisioningEmailAddressThe email address for provisioning requests.
This field is mandatory for services having provisioning
Action = Email.
For services with provisioning
Action = ServiceConnector this field must not be filled.
customPropertiesCustom Properties Custom properties for a product can be defined and the value set when a subscription is created.
welcomeTemplateIdSend a notification message to organization users when they create a subscription. Option will be disabled if template id is not provided.
Available templates can be retrieved with call to /api/sellers/{sellerId}/settings/EmailTemplates.
allowOneSubscriptionPerProductOnly one subscription can be created for this product. Default value is false.
billingPeriodTypeProduct billing period types
Billing Day = 0
Pro-Rated = 1
Default value = 0