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
Source price (SOURCE_PRICE_AMOUNT):
- The base purchase price of the rental service provider is saved in this field (the field is only set in connection with topi leasing / rental orders)
Example of an order with 2 items: 1 subscription item and 1 normal item
The example file can be downloaded further down in this article at “Example_ORDER_Laufzeitprodukt_Bestellung.xml”
Position 1 contains a product with a subscription
- Term 12 months a 49.90€ per month and monthly billing interval.
The unit of the billing interval is specified within the ORDER_ITEM in the ORDER_UNIT. For a term product, it is mandatory to store all required information in the ORDER_ITEM, e.g. a monthly billing interval
The subscription block holds the information on how long the term is (SUBSCRIPTION_PERIOD = 12), which unit the term has (SUBSCRIPTION_PERIOD_UNIT = MON), i.e. 12 months.
The billing interval (BILLING_PERIOD=1) of the respective unit of measure (ORDER_UNIT = MON) and the price of the unit (PRICE_AMOUNT =49.90€) are used to determine that 49.99€ is paid monthly.
<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>12</SUBSCRIPTION_PERIOD>
<SUBSCRIPTION_PERIOD_UNIT>MON</SUBSCRIPTION_PERIOD_UNIT>
<BILLING_PERIOD>1</BILLING_PERIOD>
</CONTRACT_INFORMATION>
</ORDER_ITEM>
The 2nd position is without subscription and costs 1158.00€, which is why the total amount only includes normal positions.
As a plausibility checking measure, a TOTAL_RECURRING_AMOUNT can be provided in the ORDER_SUMMARY. It describes the total sum of all recurring items. The specified “type” of the TOTAL_RECURRING_AMOUNT corresponds to the unit of the billing interval as provided in the ORDER_UNIT. (type=”MON”)
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>
Example of a rental/leasing order with 1 position at topi
The example file can be downloaded further down in this article at “Example_ORDER_Laufzeitprodukt_topi-Bestellung.xml”
Position 1 contains a product with a subscription
- Term 36 months a 24.49€ per month and monthly billing interval and the price of 898.50€ that topi pays as a rental service provider for this product from the seller.
The unit of the billing interval is specified within the ORDER_ITEM in the ORDER_UNIT. For a runtime product, it is mandatory to store all required information in the ORDER_ITEM, e.g. a billing interval month
The subscription block holds the information on how long the term lasts (SUBSCRIPTION_PERIOD = 36), which unit the term has (SUBSCRIPTION_PERIOD_UNIT = MON). So 36 months.
The billing interval (BILLING_PERIOD=1) of the respective unit of measure (ORDER_UNIT = MON) and the price of the unit (PRICE_AMOUNT =24.49€) determine that 24.49€ is paid monthly.
The basic purchase price of 898.50€ for which Topi buys the item from the seller and is therefore charged by the seller to topi as PAYER is in the field SOURCE_PRICE_AMOUNT = 898.50.
<ORDER_ITEM>
<LINE_ITEM_ID>00001</LINE_ITEM_ID>
<PRODUCT_ID>
<ns2:SUPPLIER_PID type="supplier_specific">123456</ns2:SUPPLIER_PID>
<ns2:DESCRIPTION_SHORT>iPhone 15 - 5G Smartphone - Dual-SIM / Interner Speicher 128GB - OLED-Display - 6,1" - 2556 x 1179 Pixel - 2 x Rückkamera 48 MP, 12 MP - front camera </ns2:DESCRIPTION_SHORT>
<ns2:DESCRIPTION_SHORT>12 MP - Schwarz (MTP03ZD/A)</ns2:DESCRIPTION_SHORT>
</PRODUCT_ID>
<QUANTITY>1</QUANTITY>
<ns2:ORDER_UNIT>MON</ns2:ORDER_UNIT>
<PRODUCT_PRICE_FIX>
<ns2:PRICE_AMOUNT>24.49</ns2:PRICE_AMOUNT>
</PRODUCT_PRICE_FIX>
<PRICE_LINE_AMOUNT>24.49</PRICE_LINE_AMOUNT>
<CONTRACT_INFORMATION>
<SUBSCRIPTION_PERIOD>36</SUBSCRIPTION_PERIOD>
<SUBSCRIPTION_PERIOD_UNIT>MON</SUBSCRIPTION_PERIOD_UNIT>
<BILLING_PERIOD>1</BILLING_PERIOD>
<SOURCE_PRICE_AMOUNT>898.50</SOURCE_PRICE_AMOUNT>
</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.