This API retrieves the list of invoices available on Zuora for the requested company.

superadmin can list invoices being available to any company existing in Rainbow.
bp_finance can only list invoices available to their BP company.
Users being both bp_finance and organization_admin can list invoices available for all the companies being in their organization.

Currently only BP DR and BP VAD companies have invoices in Zuora. An error is returned when trying to list invoices for companies which are not BP DR or BP VAD.

Invoices are returned in reverse chronological order by updatedDate.

For more details about the response, see Zuora documentation.

This API retrieves an invoice file available on Zuora. The file is in PDF format.

superadmin can get invoice files belonging to any company existing in Rainbow.
bp_finance can only get invoice files for their BP company.
Users being both bp_finance and organization_admin can get invoice files for all the companies being in their organization.

fileId to provide comes from the response of API GET /api/rainbow/subscription/v1.0/companies/:companyId/invoices (field invoicesFiles.id).

Get an offer from its id

The requested offer must be in the requested company's assigned catalog, otherwise an error 403 is returned.

This API retrieves the list of offers available to the requested company.
The available offers for a company corresponds to the offers being in the catalog assigned to this company.

superadmin and support can list offers being available to any company existing in Rainbow.
business_admin can list only demo offers being available to any company existing in Rainbow.
bp_admin can only list offers available to their own company and offers available to End Customer / BP IR companies for which the BP company is bp_admin's one.
bp_finance can only list offers available to their own company and offers available to End Customer / BP IR companies for which the BP company is bp_finance's one.
organization_admin can only list offers available for all the companies being in their organisation.
company_admin can only list offers available to their own company.
Users being both bp_admin or bp_finance and organization_admin can list offers available for all the companies being in their organization and the End Customers / BP IR being linked to BP companies of the organisation.

Offers which can be sold are flagged with boolean canBeSold set to true.
Other offers (with canBeSold set to false) can't be subscribed using API POST /api/rainbow/subscription/v1.0/companies/{companyId}/subscriptions. For example, free offers like Essential, Beta, Alpha, Enterprise Demo... can't be subscribed directly by customers (Essential is automatically assigned when creating company, Beta, Alpha, Enterprise Demo, ... are reserved for specific companies and can only be assigned by a superadmin).

This API can be used to create a quotation for a given offer for a given company (creation of a subscription in preview mode).

superadmin can create quotation for any company existing in Rainbow.
bp_finance can only create quotation for their own company and for End Customer / BP IR companies for which the BP company is bp_finance's one.
Users being both bp_finance and organization_admin can create quotation for all the companies being in their organization and the End Customers / BP IR being linked to BP companies of the organisation.
Only superadmin and bp_finance can create quotation (for now at least), users with admin role alone are denied.

Only offers with businessModel nb_users or flat_fee or nb_services can be quoted.

The company for which the quotation is performed must be a BP company or be linked to a BP company.

If the BP company have resell businessModel, his bpApplicantNumber must exist in Business Store (i.e. API GET /api/rainbow/subscription/v1.0/companies/check-applicant-number/{bpApplicantNumber} must return true).

Creating a quotation allows to retrieve information regarding amount that the BP will be invoiced if he subscribes to the related paid offer (of updates an existing subscription) for one of his EC / BP IR companies.
Therefore, this API should be called before actually creating or updating the subscription for the offer for this EC / BP IR company.

If the quotation is done for a company which does not have subscribed yet to the requested offer, offerId parameter have to be used.
The list of offers which can be bought can be listed using API GET /api/rainbow/subscription/v1.0/companies/:companyId/offers (warning: the offers already bought are also listed).
Actual subscription to the offer is done by calling API POST /api/rainbow/subscription/v1.0/companies/{companyId}/subscriptions
The offer has to be in the catalog assigned to the company's BP, otherwise an error 403 is returned.

If the quotation is done for a company which already have subscribed to the requested offer, subscriptionId parameter have to be used.
Actual update of the company subscription is done by calling API PUT /api/rainbow/subscription/v1.0/companies/{companyId}/subscriptions/{subscriptionId}

For more information, see Zuora documentation.

/!\ For now, only resell model is managed (i.e. a bp_finance of BP VAD/IR/DR buy a subscription for one of his customer companies (EC) or bp_finance of BP VAD buy a subscription for one of his BP IR).

This API can be used to create a subscription for a company to a given offer.

If BP company have resell businessModel, his bpApplicantNumber must exist in Business Store (i.e. API GET /api/rainbow/subscription/v1.0/companies/check-applicant-number/{bpApplicantNumber} must return true).
Note: BP IR companies should not have a bpApplicantNumber, as they don't pay directly ALE (their BP VAD does).

superadmin can create subscriptions for every company. superadmin can create subscription even for offers which can't be sold (not paid offers, like beta, Enterprise Demo, ...).
business_admin can create subscriptions for every company. business_admin can create subscription only for demo offers. If business_admin tries to subscribe to an offer that is not a demo offer, request is rejected with a 400 bad request error.
bp_finance can only create subscriptions for End Customer companies / BP IR companies for which bp_finance's company is the BP company.
Users being both bp_finance and organization_admin can create subscription for all the companies being in their organization and the End Customers / BP IR being linked to BP companies of the organisation.
Only superadmin and bp_finance can create subscriptions (for now at least), users with admin role alone are denied.
bp_finance of BP IR companies can only create subscriptions for End Customer companies / their own BP IR companies to pre-paid offers, and only if their VAD have set the fieldadminHasRightToUpdateSubscriptions to true for this BP IR company.

Creating a subscription corresponds to a company buying a paid offer. Therefore, a subscription links a company to an offer.
The list of offers which can be bought can be listed using API GET /api/rainbow/subscription/v1.0/companies/:companyId/offers (warning: the offers already bought are also listed).
The offer has to be in the catalog assigned to the BP company, otherwise an error 403 is returned (except if subscription creation is done by superadmin).

The offers have a businessModel corresponding to the way they are sold.

• Offers with businessModel nb_users or nb_services correspond to offers sold for a given number of users (licences).
  • The number of licences corresponds to the field maxNumberUsers.
  • For offers with businessModel nb_users or nb_services, maxNumberUsers must be provided (it must be > 0).
  • maxNumberUsers corresponds to the maximum number of users who can be assigned to the subscription of this offer.
  • The customer will be billed according to this number of licences bought (and not on the number of users assigned to the subscription).
  • Before creating the actual subscription for offers with businessModel nb_users or nb_services, a quotation can be made using API POST /api/rainbow/subscription/v1.0/companies/:companyId/quotations.
  • Once bought, except for offers with businessModel nb_services, the company subscription can be assigned to as many users as available licences (field maxNumberUsers of subscription objects) using API POST /api/rainbow/admin/v1.0/users/{userId}/profiles/subscriptions/{subscriptionId}.
• Offers with businessModel usage correspond to offers for which billing will be done according to customer consumption (minutes of conference, TB of storage, ...).
  • The customer will be billed according to his consumption (and not on the number of users assigned to the subscription).
  • No quotation can be done before subscribing to offers with businessModel usage (as the invoice will depend of customer consumption)
  • Once bought, the company subscription can be assigned to as many users as desired (there is no maximum number of users who can be assigned to these offers) using API POST /api/rainbow/admin/v1.0/users/{userId}/profiles/subscriptions/{subscriptionId}.
  • Field maxNumberUsers is not used for these offers.

When the subscription is created with this API, all company_admin of the company and all the bp_admin and bp_finance of the BP company linked to this company are notified with the following XMPP message:

<message id="8413b42e-563c-4437-9a53-06f638b5ab69_0"
          type="management"
          from="pcloud_subscription_1@openrainbow.com/172440802160413612281463752830017532"
          to="5abb735b2d3c4e50adde276c50ec489c@@openrainbow.com"
          xmlns="jabber:client">
     <companysubscription xmlns="jabber:iq:configuration" subscriptionId="5808afeb4372eb19547e90cf"
         companyId="58bd63d5dc5ef5eb3fe154c0" action="create">
         <offerId>58072f646237427a3687dc90</offerId>
         <offerName>Enterprise</offerName>
         <profileId>57cd90ddc04fd92e232ae258</profileId>
         <profileName>Enterprise</profileName>
         <status>creating</status>
         <syncOngoing>true</syncOngoing>
         <maxNumberUsers>50</maxNumberUsers>
     </companysubscription>
 </message>

The status field with value creating and the syncOngoing flag indicates that the creation is ongoing on Business Store and Zuora side.
Once the creation is done on their side, all company_admin bp_admin and bp_finance will receive again the same XMPP message with the field status equal to active and syncOngoing equal to false.

If superadmin or business_admin is creating a subscription to a Dial In custom offer, the expirationDate is mandatory. Otherwise, creation is refused with a bad request error (400516).

This API can be used to list all subscriptions subscribed by a company.
All companies have at least a subscription to the default (free) offer.

superadmin, business_admin and support can list subscriptions of all companies existing in Rainbow.
business_admin can list only demo subscriptions of all companies existing in Rainbow.
bp_admin can only list subscriptions of End Customer companies for which their bp_admin's company is the BP company.
bp_finance can only list subscriptions of End Customer companies for which their bp_finance's company is the BP company.
organization_admin can only list subscriptions of companies under their organisation.
company_admin can list subscriptions only for their company.

If format is full, data regarding user assignment is added for each subscription:

• If the company owning the subscription is a BP with bpType=IR and the subscription has businessModel=nb_users, the following fields are computed and added to the subscription data:
  • nbBPLicences: the number of licences available for this subscription (equal to maxNumberUsers),
  • nbAssignedBPUsers: the number of licences assigned to BP users for this subscription,
  • nbLicencesAssignedToECs: the number of licences assigned to users of EC companies under the BP IR for which subscription have been bought (linked to the BP IR's subscription)
  • nbLicencesUsed: the number of licences used for this subscription (equal to nbAssignedBPUsers + nbLicencesAssignedToECs)
  • nbFreeLicences: the number of licences available for this subscription (equal to nbBPLicences - nbLicencesUsed)
  • numberAssignedUsers: the number of licences assigned for this subscription (equal to nbLicencesUsed). Added for compatibility so that in all cases this field is set.
• Otherwise, the following field is computed and added to the subscription data:
  • numberAssignedUsers: the number of licences assigned to company users for this subscription.

Example: GET https://openrainbow.com/api/rainbow/subscription/v1.0/companies/569ce8c8f9336c471b98eda1/subscriptions?format=full

This API can be used to delete or terminate a given company subscription.

superadmin can delete subscriptions for every company. superadmin can delete subscription even for offers which can't be sold (not paid offers, like beta, Enterprise Demo, ...).
business_admin can delete subscriptions for every company. business_admin can delete subscription only for demo offers. If business_admin user tries to delete a subscription that is not about a demo offer, an error 400 bad request is thrown.
bp_finance can only delete subscriptions for End Customer companies for which the bp_finance's company is the BP company.

Subscriptions to prepaid offers can be terminated using this API only during the month the subscription was created (e.g. if subscription was created the 15th of september, it can be cancelled until the 1st of october. After that subscription can't be cancelled).
Prepaid offers auto renewal can be cancelled using API PUT /api/rainbow/subscription/v1.0/companies/:companyId/subscriptions/:subscriptionId and it will be terminated when expirationDate will be reached.
Subscriptions not being in Business Store / Zuora are deleted (i.e. subscriptions to free offers like beta, Enterprise Demo, ...) from Rainbow database.
Others subscriptions (known on Zuora) are tagged with status terminated.
Default subscription can't be deleted.

When the subscription is deleted/terminated, the profile of all users being linked to this subscription is updated (the profile linking to this subscription is removed).

When the subscription is deleted, all company_admin of the company and all the bp_admin and bp_finance of the BP company linked to this company are notified with the following XMPP message:

<message id="8413b42e-563c-4437-9a53-06f638b5ab69_0" type="management"
    from="pcloud_subscription_1@openrainbow.com/172440802160413612281463752830017532"
    to="5abb735b2d3c4e50adde276c50ec489c@@openrainbow.com"
    xmlns="jabber:client">
    <companysubscription xmlns="jabber:iq:configuration"
    subscriptionId="5808afeb4372eb19547e90cf"
    companyId="58bd63d5dc5ef5eb3fe154c0" action="delete"></companysubscription>
</message>

This API can be used to get a subscription of a company.

superadmin and support can get subscriptions of all companies existing in Rainbow.
business_admin can get only demo subscriptions of all companies existing in Rainbow.
bp_admin can only get subscriptions of End Customer companies for which their bp_admin's company is the BP company.
bp_finance can only get subscriptions of End Customer companies for which their bp_finance's company is the BP company.
organization_admin can only get subscriptions of companies under their organisation.
company_admin can get subscriptions only for their company.

Data regarding user assignment is computed and returned for the requested subscription:

• If the company owning the subscription is a BP with bpType=IR and the subscription has businessModel=nb_users, the following fields are computed and added to the subscription data:
  • nbBPLicences: the number of licences available for this subscription (equal to maxNumberUsers),
  • nbAssignedBPUsers: the number of licences assigned to BP company's users for this subscription,
  • nbLicencesAssignedToECs: the number of licences affected to EC companies under the BP IR for which subscription have been bought (linked to the BP IR's subscription)
  • nbLicencesUsed: the number of licences used for this subscription (equal to nbAssignedBPUsers + nbLicencesAssignedToECs)
  • nbFreeLicences: the number of licences available for this subscription (equal to nbBPLicences - nbLicencesUsed)
  • numberAssignedUsers: the number of licences assigned for this subscription (equal to nbLicencesUsed).
• Otherwise, the following field is computed and added to the subscription data:
  • numberAssignedUsers: the number of licences assigned to company's users for this subscription.

Example: GET https://openrainbow.com/api/rainbow/subscription/v1.0/companies/569ce8c8f9336c471b98eda1/subscriptions/5808afeb4372eb19547e90cf

This API can be used to update a given company subscription.

Currently only maxNumberUsers can be updated, so update is restricted to subscriptions linked to offers having businessModel nb_users.
Now also autoRenew and autoRenewToMonthly can be updated using this API. In this case, update is limited to subscriptions to prepaid offers

The subscription can only be updated if it is not synchronizing with Business Store and Zuora (i.e. syncOngoing must be equal to false).

If BP company have resell businessModel, his bpApplicantNumber must exist in Business Store (i.e. API GET /api/rainbow/subscription/v1.0/companies/check-applicant-number/{bpApplicantNumber} must return true).
Note: BP IR companies should not have a bpApplicantNumber, as they don't pay directly ALE (their BP VAD does).

business_admin can update demo subscriptions for all existing companies. If business_admin user tries to update a subscription that is not about a demo offer, an error 400 bad request is thrown.
bp_finance can only update subscriptions for End Customer companies for which the bp_finance's company is the BP company.
company_admin can only update subscriptions for their own company (except if their company is linked to a BP IR company, in that case they are not allowed to update subscriptions of their company).
bp_admin or bp_finance can forbid administrators of his End Customer companies to:

• update subscriptions (company flag adminHasRightToUpdateSubscriptions),
• decrease maxNumberUsers of his subscriptions (company flag adminAllowedUpdateSubscriptionsOps set to increase_only),

maxNumberUsers of subscriptions to prepaid offers can be increase to any value.
maxNumberUsers of subscriptions to prepaid offers can be decreased ONLY if a prepaid addon has been created during the month of the request (e.g. if a prepaid addon is created the 15th of september with 10 licenses, I'll be able to decrease the maxNumberUsers up to 10 licenses and until the 1st of october). This feature allows admin to cancel an addon to a prepaid subscription.
maxNumberUsers of monthly subscriptions can be increase to any value.
maxNumberUsers of monthly subscriptions can only be decreased to remove "free" licences, i.e. licences which are not already assigned to users (updated maxNumberUsers must be greater or equal to numberAssignedUsers). To remove additional licences, admin first have to un-assign licences to some users using API DELETE /api/rainbow/admin/v1.0/users/{userId}/profiles/subscriptions/{subscriptionId}.

When the subscription is updated, all company_admin of the company and all the bp_admin and bp_finance of the BP company linked to this company are notified with the following XMPP message:

<message id="8413b42e-563c-4437-9a53-06f638b5ab69_0"
          type="management"
          from="pcloud_subscription_1@openrainbow.com/172440802160413612281463752830017532"
          to="5abb735b2d3c4e50adde276c50ec489c@@openrainbow.com"
          xmlns="jabber:client">
     <companysubscription xmlns="jabber:iq:configuration" subscriptionId="5808afeb4372eb19547e90cf"
         companyId="58bd63d5dc5ef5eb3fe154c0" action="update">
         <offerId>58072f646237427a3687dc90</offerId>
         <offerName>Enterprise</offerName>
         <profileId>57cd90ddc04fd92e232ae258</profileId>
         <profileName>Enterprise</profileName>
         <status>active</status>
         <syncOngoing>true</syncOngoing>
         <maxNumberUsers>50</maxNumberUsers>
     </companysubscription>
</message>

The syncOngoing flag indicates that the update is being synchronizing with Business Store and Zuora. It will not be possible to update again the subscription as long the synchronization is ongoing.
Once the synchronization is done, all company_admin, bp_admin and bp_finance will receive the same XMPP message with the value syncOngoing equal to false.

This API can be used to get features available to the company through its subscriptions.

Subscriptions bring to the company features (through a profile depending of the subscribed offer). Each subscription has his own list of features with their own value.

Company can have several subscriptions (if the company has subscribed to commercial offers). By default, company has at least a subscription to the default offer (i.e. Essential).

This API allows to aggregate all features from all company's subscriptions, listing therefore all available features for this company.

superadmin and support can get company features of all companies existing in Rainbow. bp_admin can only get company features of End Customer companies for which their bp_admin's company is the BP company. bp_finance can only get company features of End Customer companies for which their bp_finance's company is the BP company. organization_admin can only get company features of companies under their organisation. company_admin can get company features only for their company. user can get company features only for their company.

Example: GET https://openrainbow.com/api/rainbow/subscription/v1.0/companies/569ce8c8f9336c471b98eda1/subscriptions/features

This API can be used to list counters regarding all offers subscribed by a BP company and its customers / resellers.
This API can only be used for BP companies (whatever the bpType).

For each subscribed offer, this API returns:

• the number of licences bought:
• myCompanyNbLicences: the number of licences bought by the BP company itself
• myCustomersNbLicences: the number of licences bought by the BP company's EC companies
• myResellersNbLicences: if the BP company is a VAD, the number of licences bought by all its BP IR companies and all the EC companies of these BP IR companies.
• the number of licences assigned to users:
• myCompanyNumberAssignedUsers: the number of licences assigned to users of the BP company itself
• myCustomersNumberAssignedUsers: the number of licences assigned to users of the BP company's EC companies
• myResellersNumberAssignedUsers: if the BP company is a VAD, the number of users assigned to all of its BP IR companies and all of the EC companies of these BP IR companies.

Warning: for now, this API doesn't count the number of licences for prepaid offers for BP IR (myResellersNbLicences)

This API can be used to get default subscription of a company (i.e. subscription to default Rainbow offer).

superadmin, business_admin and support can get default subscription of all companies existing in Rainbow.
bp_admin can only get default subscription of End Customer companies for which their bp_admin's company is the BP company.
bp_finance can only get default subscription of End Customer companies for which their bp_finance's company is the BP company.
organization_admin can only get default subscription of companies under their organisation.
company_admin can get default subscription only for their company.

Example: GET https://openrainbow.com/api/rainbow/subscription/v1.0/companies/569ce8c8f9336c471b98eda1/subscriptions/default

This API can be used to list prepaid subscriptions ending soon

superadmin and support can list prepaid subscriptions of any company(ies) existing in Rainbow.
bp_finance can only list prepaid subscriptions of End Customer companies linked to their BP company.
company_admin can only list prepaid subscriptions of his own End Customer company.

Example: GET https://openrainbow.com/api/rainbow/subscription/v1.0/companies/569ce8c8f9336c471b98eda1/subscriptions/prepaid

This API can be used to list users having a given subscription in their profile

superadmin and support can get users attached to any company subscriptions existing in Rainbow.
bp_admin can only retrieve users attached to subscriptions of End Customer companies linked to their BP company.
bp_finance can only retrieve users attached to subscriptions of End Customer companies linked to their BP company.
organization_admin can only retrieve users attached to subscriptions of companies under their organisation.
company_admin can only retrieve users attached to subscriptions of their company.

Example: GET https://openrainbow.com/api/rainbow/subscription/v1.0/companies/569ce8c8f9336c471b98eda1/subscriptions/5808afeb4372eb19547e90cf/users

This API can be used to upload pre paid offers from ACTIS file, to set in the given company subscriptions.
Rules:

• ACTIS file has to be sent directly in http body (no JSon).
• Two format are supported: one plain XML file (extension .xpo2), and one zipped file (extension .SAP).
• By default, ACTIS file size is limited to 4 MB.
• If the company requesting the subscription(s) creation is a BP VAD, the requested offers must be prepaid offers.

The API only returns status code > 200 if the requested companyId (from URL) is not a BP company or if the provided file couldn't be parsed (wrong format, XML without the expected structure).
Otherwise, the API returns with a status code 200 and the following data are returned:

• The created subscription(s) (if any) in field data,
• A report regarding the import process in field report (file parsing, offers and companies used),
• The potential non blocking errors which may have occurred during the import process in warning field,
• The potential blocking errors which may have occurred during the import process in error field.

Node that if BP company is a DR, IRCOMPANY section of Actis file is not validated (as the data in this section will be the one of the DR company)

Please note that creation steps will NOT BE EXECUTED if parameter 'preview=true' is set.
This mode is used to check the validity of a given ACTIS file, and to show all the actions that should be performed in standard mode ('preview' not set or set to false).