{"id":10498,"date":"2021-09-17T14:06:06","date_gmt":"2021-09-17T12:06:06","guid":{"rendered":"https:\/\/guide.itscope.com\/?post_type=kb&#038;p=10498"},"modified":"2025-05-19T17:48:59","modified_gmt":"2025-05-19T15:48:59","slug":"structure-of-the-order-document-for-orders-containing-subscription-products","status":"publish","type":"kb","link":"https:\/\/guide.itscope.com\/en\/kb\/structure-of-the-order-document-for-orders-containing-subscription-products\/","title":{"rendered":"Structure of the Order document for orders containing subscription information"},"content":{"rendered":"\n<h2 class=\"wp-block-heading\">Structure of subscription orders<\/h2>\n\n\n\n<p><strong>Order documents with subscription products are only processed starting from API version 2.1.<\/strong><\/p>\n\n\n\n<p>The same structure applies as described in the &#8216;<a href=\"https:\/\/guide.itscope.com\/en\/kb\/structure-of-the-order-document-for-a-standard-purchase-order\/\">Structure of the ORDER document for a standard purchase order<\/a>&#8216; article.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Orders with cloud products<\/h3>\n\n\n\n<p>The following additional information is required for the OpenTrans order when ordering subscription (recurring price) products:<\/p>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>All required information (term duration, unit of the term, billing interval) is provided in <strong>SUBSCRIPTION_INFORMATION<\/strong>.<\/p>\n\n\n\n<p><strong>Term duration (SUBSCRIPTION_PERIOD):<\/strong><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>This field specifies the duration of the contract term for the subscription product<\/li>\n<\/ul>\n\n\n\n<p><strong>Unit of measure for the stated term duration (SUBSCRIPTION_PERIOD_UNIT):<\/strong><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>This field indicates the unit of measure for the stated term duration<\/li>\n\n\n\n<li>For this field, the ISO product unit &#8216;month&#8217; is used<\/li>\n<\/ul>\n\n\n\n<p><strong>Billing interval (BILLING_PERIOD):<\/strong><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>In this field, the time interval for billing of the subscription product is provided<\/li>\n<\/ul>\n\n\n\n<p><strong>Source price (SOURCE_PRICE_AMOUNT):<\/strong><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>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)<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Example of an order with 2 items: 1 subscription item and 1 normal item<\/h3>\n\n\n\n<p>The example file can be downloaded further down in this article at &#8220;Example_ORDER_Laufzeitprodukt_Bestellung.xml&#8221;<\/p>\n\n\n\n<p>Position 1 contains a product with a subscription<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Term 12 months a 49.90\u20ac per month and monthly billing interval.<\/li>\n<\/ul>\n\n\n\n<p>The unit of the billing interval is specified within the <strong>ORDER_ITEM <\/strong>in the <strong>ORDER_UNIT<\/strong>. For a term product, it is mandatory to store all required information in the <strong>ORDER_ITEM<\/strong>, e.g. a monthly billing interval<\/p>\n\n\n\n<p>The subscription block holds the information on how long the term is (<strong>SUBSCRIPTION_PERIOD <\/strong>= 12), which unit the term has (<strong>SUBSCRIPTION_PERIOD_UNIT <\/strong>= MON), i.e. 12 months.<\/p>\n\n\n\n<p>The billing interval (<strong>BILLING_PERIOD<\/strong>=1) of the respective unit of measure (<strong>ORDER_UNIT <\/strong>= MON) and the price of the unit (<strong>PRICE_AMOUNT <\/strong>=49.90\u20ac) are used to determine that 49.99\u20ac is paid monthly.<\/p>\n\n\n\n<p><\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">&lt;ORDER_ITEM&gt;<br>\t&lt;LINE_ITEM_ID&gt;00001&lt;\/LINE_ITEM_ID&gt;<br>\t&lt;PRODUCT_ID&gt;<br>                &lt;ns2:SUPPLIER_PID type=\"supplier_specific\"&gt;123002&lt;\/ns2:SUPPLIER_PID&gt;<br>                &lt;ns2:DESCRIPTION_SHORT&gt;APPLE iPad Pro Wi-Fi 256 GB Grey - 11\" Tablet - 27,9cm-Display&lt;\/ns2:DESCRIPTION_SHORT&gt;<br>\t&lt;\/PRODUCT_ID&gt;<br>\t&lt;QUANTITY&gt;1&lt;\/QUANTITY&gt;<br>\t&lt;!-- <meta charset=\"utf-8\">Unit of measure (ISO product unit for 'month') --&gt;<br><strong>\t&lt;ns2:ORDER_UNIT&gt;MON&lt;\/ns2:ORDER_UNIT&gt;<\/strong><br>\t&lt;PRODUCT_PRICE_FIX&gt;<br><strong>\t\t&lt;ns2:PRICE_AMOUNT&gt;49.99&lt;\/ns2:PRICE_AMOUNT&gt;<\/strong><br>\t&lt;\/PRODUCT_PRICE_FIX&gt;<br>\t&lt;PRICE_LINE_AMOUNT&gt;49.99&lt;\/PRICE_LINE_AMOUNT&gt;<br>\t&lt;CONTRACT_INFORMATION&gt;<br><strong>\t         &lt;SUBSCRIPTION_PERIOD&gt;12&lt;\/SUBSCRIPTION_PERIOD&gt;<br>\t         &lt;SUBSCRIPTION_PERIOD_UNIT&gt;MON&lt;\/SUBSCRIPTION_PERIOD_UNIT&gt;<br>\t         &lt;BILLING_PERIOD&gt;1&lt;\/BILLING_PERIOD&gt;<br><\/strong>        &lt;\/CONTRACT_INFORMATION&gt;<br>&lt;\/ORDER_ITEM&gt;<\/pre>\n\n\n\n<p>The 2nd position is without subscription and costs 1158.00\u20ac, which is why the total amount only includes normal positions.<\/p>\n\n\n\n<p>As a plausibility checking measure, a <strong>TOTAL_RECURRING_AMOUNT<\/strong> can be provided in the <strong>ORDER_SUMMARY<\/strong>. It describes the total sum of all recurring items. The specified <strong>&#8220;type&#8221; <\/strong>of the <strong>TOTAL_RECURRING_AMOUNT<\/strong>  corresponds to the unit of the billing interval as provided in the <strong>ORDER_UNIT<\/strong>. (type=&#8221;MON&#8221;)<\/p>\n\n\n\n<p>This is not a mandatory field, but serves as an overview for all subscription products with recurring prices.<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">&lt;ORDER_SUMMARY&gt;<br>\t&lt;TOTAL_ITEM_NUM&gt;2&lt;\/TOTAL_ITEM_NUM&gt;<br>\t&lt;TOTAL_AMOUNT&gt;1158.00&lt;\/TOTAL_AMOUNT&gt;<br>\t&lt;!-- Total sum for all recurring positions --&gt;<br><strong>\t&lt;TOTAL_RECURRING_AMOUNT type=\"MON\"&gt;49.99&lt;\/TOTAL_RECURRING_AMOUNT&gt;<\/strong><br>&lt;\/ORDER_SUMMARY&gt;<\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">Example of a rental\/leasing order with 1 position at topi<\/h3>\n\n\n\n<p>The example file can be downloaded further down in this article at \u201cExample_ORDER_Laufzeitprodukt_topi-Bestellung.xml\u201d<\/p>\n\n\n\n<p>Position 1 contains a product with a subscription<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Term 36 months a 24.49\u20ac per month and monthly billing interval and the price of 898.50\u20ac that topi pays as a rental service provider for this product from the seller.<\/li>\n<\/ul>\n\n\n\n<p>The unit of the billing interval is specified within the <strong>ORDER_ITEM <\/strong>in the <strong>ORDER_UNIT<\/strong>. For a runtime product, it is mandatory to store all required information in the <strong>ORDER_ITEM<\/strong>, e.g. a billing interval month<\/p>\n\n\n\n<p>The subscription block holds the information on how long the term lasts (<strong>SUBSCRIPTION_PERIOD <\/strong>= 36), which unit the term has (<strong>SUBSCRIPTION_PERIOD_UNIT <\/strong>= MON). So 36 months.<\/p>\n\n\n\n<p>The billing interval (<strong>BILLING_PERIOD<\/strong>=1) of the respective unit of measure (<strong>ORDER_UNIT <\/strong>= MON) and the price of the unit (<strong>PRICE_AMOUNT <\/strong>=24.49\u20ac) determine that 24.49\u20ac is paid monthly.<\/p>\n\n\n\n<p>The basic purchase price of 898.50\u20ac for which Topi buys the item from the seller and is therefore charged by the seller to topi as PAYER is in the field <strong>SOURCE_PRICE_AMOUNT <\/strong>= 898.50.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>&lt;ORDER_ITEM&gt;\n         &lt;LINE_ITEM_ID&gt;00001&lt;\/LINE_ITEM_ID&gt;\n         &lt;PRODUCT_ID&gt;\n            &lt;ns2:SUPPLIER_PID type=\"supplier_specific\"&gt;123456&lt;\/ns2:SUPPLIER_PID&gt;\n            &lt;ns2:DESCRIPTION_SHORT&gt;iPhone 15 - 5G Smartphone - Dual-SIM \/ Interner Speicher 128GB - OLED-Display - 6,1\" - 2556 x 1179 Pixel - 2 x R\u00fcckkamera 48 MP, 12 MP - front camera &lt;\/ns2:DESCRIPTION_SHORT&gt;\n            &lt;ns2:DESCRIPTION_SHORT&gt;12 MP - Schwarz (MTP03ZD\/A)&lt;\/ns2:DESCRIPTION_SHORT&gt;\n         &lt;\/PRODUCT_ID&gt;\n         &lt;QUANTITY&gt;1&lt;\/QUANTITY&gt;\n<strong>         &lt;ns2:ORDER_UNIT&gt;MON&lt;\/ns2:ORDER_UNIT&gt;<\/strong>\n         &lt;PRODUCT_PRICE_FIX&gt;\n<strong>            &lt;ns2:PRICE_AMOUNT&gt;24.49&lt;\/ns2:PRICE_AMOUNT&gt;<\/strong>\n         &lt;\/PRODUCT_PRICE_FIX&gt;\n         &lt;PRICE_LINE_AMOUNT&gt;24.49&lt;\/PRICE_LINE_AMOUNT&gt;\n         &lt;CONTRACT_INFORMATION&gt;\n<strong>            &lt;SUBSCRIPTION_PERIOD&gt;36&lt;\/SUBSCRIPTION_PERIOD&gt;<\/strong>\n<strong>            &lt;SUBSCRIPTION_PERIOD_UNIT&gt;MON&lt;\/SUBSCRIPTION_PERIOD_UNIT&gt;<\/strong>\n<strong>            &lt;BILLING_PERIOD&gt;1&lt;\/BILLING_PERIOD&gt;<\/strong>\n<strong>            &lt;SOURCE_PRICE_AMOUNT&gt;898.50&lt;\/SOURCE_PRICE_AMOUNT&gt;<\/strong>\n         &lt;\/CONTRACT_INFORMATION&gt;\n      &lt;\/ORDER_ITEM&gt;<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Download example Order files<\/h2>\n\n\n\n<p>The example files are provided with XML comments to help convey the <a href=\"https:\/\/guide.itscope.com\/en\/kb\/business-deals-send-method\/\">structure of an ORDER document<\/a>. <\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 &#8216;Structure of the ORDER document &#8230;<\/p>\n","protected":false},"author":5,"featured_media":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"footnotes":""},"kbtopic":[183],"kbtag":[],"class_list":["post-10498","kb","type-kb","status-publish","hentry","kbtopic-api-orders-quotes"],"_links":{"self":[{"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/kb\/10498","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/kb"}],"about":[{"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/types\/kb"}],"author":[{"embeddable":true,"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/users\/5"}],"replies":[{"embeddable":true,"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/comments?post=10498"}],"version-history":[{"count":12,"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/kb\/10498\/revisions"}],"predecessor-version":[{"id":18794,"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/kb\/10498\/revisions\/18794"}],"wp:attachment":[{"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/media?parent=10498"}],"wp:term":[{"taxonomy":"kbtopic","embeddable":true,"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/kbtopic?post=10498"},{"taxonomy":"kbtag","embeddable":true,"href":"https:\/\/guide.itscope.com\/en\/wp-json\/wp\/v2\/kbtag?post=10498"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}