Place and Provision Orders

Introduction

This article explains how partners can place and provision orders programmatically. This will unlock the possibility to place orders outside the platform, e.g. via Partner's own marketplace and/or CRM/ERP.

Combined with the Get Catalog and Prices APIs, Partners can incorporate their Platform catalog of offers and enable customers to make purchases through the Partner's own marketplace.

Audience: integration developers, business analysts, and software architects.

Placing and Executing an Order:

APIs in scope:

No.1 Create an order

Creates an order based on the defined offer properties (see. Retrieve a pricing plan for the offer) and the price configured (see. Calculate Price for a Pricing Plan). Please note order will be visible on the UI only after an order is executed according to step No.3.

Add-Ons: when creating an offer that includes add-ons, you will need to List all add-ons for an offer that can be selected by the customer. These add-ons can include any additional products, services, or features that the customer can add to their order. You will need to provide details about each addon, including the name, description, and price.

Even though not all add-ons can be purchased as standalone offers, the add-ons have their own "OfferId" that allows you to use APIs associated with offers. For example, to calculate a price of an addon, you can use the "configure an order payload" API. 

After configuring the addon prices, you will then take the addon information and addon price data and use it as input for the "Orderedaddons" parameter when using the Create an order API. This API creates an order with all the selected add-ons, their respective prices, and any other details related to the order.

Overall, the sequence of steps involved in configuring addons for an offer includes listing the available add-ons, processing the return, configuring addon prices using the "configure an order payload" API, and using the resulting add-on information and prices to create an order with the "create an order" API.

Created by:

Partners tend to use a single API user for their integration (e.g. apiuser@appxite.com). As a result, all operations, including order placement will be shown as performed by such user. However, partners would like to attribute the operations to a specific user that places an order in Partner's system (e.g. Marketplace, ERP, etc.). For that purpose, the "Create an order" API supports the X-ApiUser header, allowing partners to indicate the user name of the person who placed an order in their system. This feature enables partners to attribute orders accurately and display the appropriate user name in the "Created by" section of the AppXite Platform.

Example:

Partner has used X-ApiUser = "APITest".

As a result, such user will be visible in the "Order" section as follows:

In addition, the "List all orders" endpoint will return the user indicated in "X-ApiUser" in the "CreatedByApiUser" key.

No.2. Get Terms and Conditions of offers in order (OPTIONAL)

Retrieves the terms and conditions associated with the selected offer.

No.2.1. Check Microsoft Customer Agreement

For Microsoft offers, you will need to follow additional steps to verify that Microsoft systems have records of a signed Microsoft Customer Agreement ("MCA").

This API returns the information on the Microsoft Customer Agreement status based on the selected customer's internal tenant ID. Please use  Retrieve a tenant for the customer to get the InternalId.

Note: In the event that a Microsoft tenant is missing or the customer requires a new tenant, you can use "Microsoft Tenant" APIs to process tenant creation.

No.2.1.1. Customer Microsoft Agreement (MCA) Acceptance

Accepts Microsoft Customer Agreement for the selected tenant based on the provided customer signatory details.

No.3. Execute an order

Executes an order by changing the order status to "Pending Approval" (in the event that Approval is required) or "Provision Started". 

No.3.1. Approve an order 

If an order requires approval, "Approve an order" will change its status from "Pending Approval" to "Provision Started". Approval functionality can be used for credit risk purposes.

For example, a Partner configured order value limits for a specific customer in its ERP. Hence, if a customer places an order exceeding the set limit, such an order will be automatically rejected (see. Reject an order).