Structure of the Order document for orders containing subscription information

Structure of subscription orders

Order documents with subscription products are only processed starting from API version 2.1.

The same structure applies as described in the ‘Structure of the ORDER document for a standard purchase order‘ article.

Orders with cloud products

The following additional information is required for the OpenTrans order when ordering subscription (recurring price) products:

All products with a contract term require information on the duration of the term, the unit specified in the term, the billing interval and the unit of the billing interval.

All required information (term duration, unit of the term, billing interval) is provided in SUBSCRIPTION_INFORMATION.

Term duration (SUBSCRIPTION_PERIOD):

• This field specifies the duration of the contract term for the subscription product

Unit of measure for the stated term duration (SUBSCRIPTION_PERIOD_UNIT):

• This field indicates the unit of measure for the stated term duration
• For this field, the ISO product unit ‘month’ is used

Billing interval (BILLING_PERIOD):

• In this field, the time interval for billing of the subscription product is provided

<CONTRACT_INFORMATION>
	<SUBSCRIPTION_PERIOD>10</SUBSCRIPTION_PERIOD>
	<SUBSCRIPTION_PERIOD_UNIT>MON</SUBSCRIPTION_PERIOD_UNIT>
	<BILLING_PERIOD>1</BILLING_PERIOD>
</CONTRACT_INFORMATION>

The unit of the billing interval is specified within the ORDER_ITEM field, using ORDER_UNIT. For a subscription product, it is mandatory to provide all required information within ORDER_ITEM, e.g.:

<ORDER_ITEM>
	<LINE_ITEM_ID>00001</LINE_ITEM_ID>
	<PRODUCT_ID>
                <ns2:SUPPLIER_PID type="supplier_specific">123002</ns2:SUPPLIER_PID>
                <ns2:DESCRIPTION_SHORT>APPLE iPad Pro Wi-Fi 256 GB Grey - 11" Tablet - 27,9cm-Display</ns2:DESCRIPTION_SHORT>
	</PRODUCT_ID>
	<QUANTITY>1</QUANTITY>
	<!-- Unit of measure (ISO product unit for 'month') -->
	<ns2:ORDER_UNIT>MON</ns2:ORDER_UNIT>
	<PRODUCT_PRICE_FIX>
		<ns2:PRICE_AMOUNT>49.99</ns2:PRICE_AMOUNT>
	</PRODUCT_PRICE_FIX>
	<PRICE_LINE_AMOUNT>49.99</PRICE_LINE_AMOUNT>
	<CONTRACT_INFORMATION>
	         <SUBSCRIPTION_PERIOD>10</SUBSCRIPTION_PERIOD>
	         <SUBSCRIPTION_PERIOD_UNIT>MON</SUBSCRIPTION_PERIOD_UNIT>
	         <BILLING_PERIOD>1</BILLING_PERIOD>
        </CONTRACT_INFORMATION>
</ORDER_ITEM>

As a plausibility checking measure, a TOTAL_RECURRING_AMOUNT can be provided in the ORDER_SUMMARY.

This is not a mandatory field, but serves as an overview for all subscription products with recurring prices.

<ORDER_SUMMARY>
	<TOTAL_ITEM_NUM>2</TOTAL_ITEM_NUM>
	<TOTAL_AMOUNT>1158.00</TOTAL_AMOUNT>
	<!-- Total sum for all recurring positions -->
	<TOTAL_RECURRING_AMOUNT type="MON">49.99</TOTAL_RECURRING_AMOUNT>
</ORDER_SUMMARY>

The specified ‘type’ corresponds to the unit of the billing interval as provided in the ORDER_UNIT.

Orders with contract information

For certain combinations of dealers and manufacturers, additional contract parameters are required so that the order can be processed without consulting the dealer. The necessary parameters can be read out via the product export and can be found under “contractParameter” in the standard and developer format.

The parameters must be stored for the item in the CONTRACT_INFORMATION field under PARAMETERS:

<ORDER_ITEM>
	<LINE_ITEM_ID>00001</LINE_ITEM_ID>
	...
	<CONTRACT_INFORMATION>
		<PARAMETERS>
			<PARAMETER type="purchaseDate">2022-04-12</PARAMETER>
			<PARAMETER type="serial">same</PARAMETER>
		</PARAMETERS>
	</CONTRACT_INFORMATION>
</ORDER_ITEM>

Download example Order files

The example files are provided with XML comments to help convey the structure of an ORDER document. These files can also be used as a reference file for test-sending an order via the ITscope API method business/deals/send to our ‘Partner Test’, DistributorId 10000735.

The Example_ORDER_LaufzeitProdukt_Bestellung.xml file is an order containing one subscription product and one product without recurring prices.