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 | |||
| Operation | Swagger Description | Method | API |
| Create a Product | Creates new product for Seller service | POST | /api/sellers/{sellerId}/services/{serviceId}/products |
| Return a Product | Returns seller service product details | GET | /api/sellers/{sellerId}/services/{serviceId}/products/{id} |
| Return all Products | Returns all seller service products | GET | /api/sellers/{sellerId}/services/{serviceId}/products |
| Update a Product | Updates seller service product | PUT | /api/sellers/{sellerId}/services/{serviceId}/products/{id} |
| Delete a Product | Deletes seller service product | DELETE | /api/sellers/{sellerId}/services/{serviceId}/products/{id} |
| Other | |||
| Retrieve Email Templates | Returns all seller email templates | GET | /api/sellers/{sellerId}/settings/EmailTemplates |
API Examples
| Retrieve the Service | |
|---|---|
| End Point | /api/sellers/{sellerId}/services |
| HTTP Method | GET |
| Request Body | N/A. |
| Successful Example Response | 200[ { "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 Response | 404 |
| Create a Product | |
|---|---|
| End Point | /api/sellers/{sellerId}/services/{serviceId}/products |
| HTTP Method | POST |
| 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 Response | 201 |
| Error Example Response | 400{ "CancelPeriod": [ "CancelPeriod can be set only if CancelTime is set to DeleteAfterSpecifiedTimePeriod" ], "BillingPeriodType": [ "BillingPeriodType can be set only for Type ProductBased." ] } |
Field Definitions
| Field | Description |
| billingType | A choice of whether the product would have one-time or recurring billing RecurringBilling = 0 OneTime = 1 Default value = 0 |
| type | A 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. |
| customer | Determines 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). |
| subscriptionPeriodMonths | Determines 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) |
| paymentFrequencyMonths | The 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) |
| price | The price for the broker. |
| cost | The cost for the seller. |
| recommendedPrice | The price, which is suggested for brokers to use when they sell to organizations. |
| minimumQuantity | The defined minimum amount that can be bought by the organization when creating a subscription. MeteredZero can be set only for metered products |
| maximumQuantity | The 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. |
| startupItemCode | Determines if there’s an upfront fee for the organization.Only available if StartupFee > 0. |
| startupFee | The startup fee price. Product startup fee only available for RecurringBilling. |
| allowUpgrade | Determines 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. |
| allowDowngrade | Determines 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. |
| allowChangesWhenDaysLeft | Period in days where changes in product are allowed. Only available for RecurringBilling and if subscription period months greater than 1 month. |
| productListPriority | The position where this product would be in the list of products. |
| renewalAction | Determines what happens at the end of the subscription periodAutomaticRenewalAutomaticCancelChangeProductFor product billing type OneTime set the value to Automatic Renewal. |
| renewalChangeProductId | Renewal change product identifier. Only available for RecurringBilling and only for renewalAction=ChangeProduct. |
| cancelTime | How the subscription would be cancelled:AutoDeleteAtEndOfSubscriptionImmediatelyDeleteDeleteAfterSpecifiedTimePeriodFor billing type OneTime set the value to ImmediatelyDelete. |
| cancelPeriodType | The cancel period type in months or days. |
| cancelPeriod | The cancel period in days or months. |
| notificationDaysLeft | Determines 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 |
| notificationTemplateId | Id 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. |
| notifyOnExpiration | If set to true, then a notification email is sent on subscription expiration. Only available for RecurringBilling. |
| notifyOnExpirationTemplateId | Identifier 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. |
| enableTrial | Determines if there’s a trial included with the subscription. Only available for RecurringBilling. |
| trialPeriodDays | Trial period in days. Only available for RecurringBilling. |
| enforceTrial | If true, trial period is mandatory. Only available for RecurringBilling. |
| provisioningEmailAddress | The 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. |
| customProperties | Custom Properties Custom properties for a product can be defined and the value set when a subscription is created. |
| welcomeTemplateId | Send 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. |
| allowOneSubscriptionPerProduct | Only one subscription can be created for this product. Default value is false. |
| billingPeriodType | Product billing period types Billing Day = 0 Pro-Rated = 1 Default value = 0 |