4.2 Orders API

4.2.1. Retrieve Order:

Returns this object graph: SubscriptionOrder and OrderLineItem collection.

GET /rest/order/[id]?format=xml

GET /rest/order? format=xml&orderNumber=[val]

Sample Output:

<subscriptionOrder id="17">

  <startDate>2010-01-25</startDate>

  <endDate />

  <separateInvoice>

    2

  </separateInvoice>

  <jobCode>JOB-CODE</jobCode> 

  <isAutoPay>false</isAutoPay>

  <dueDateValue>30</dueDateValue>

  <dueDateUnits>Days</dueDateUnits>

  <contractOffering id="7" />

  <invoiceText>Greenlinks Executive membership</invoiceText>

  <lastUpdated>2010-08-08</lastUpdated>

  <contractOfferingName>Executive membership</contractOfferingName>

  <invoiceNotes />

  <orderStatus>Active</orderStatus>

  <totalLifetimeValue>10300.00</totalLifetimeValue>

  <orderNumber>ORD002</orderNumber>

  <dateCreated>2010-08-06</dateCreated>

  <isSeparateInvoice>false</isSeparateInvoice>

  <notes />

  <contractCode>EXEC-MBRSHP</contractCode>

  <customer id="12" />

  <currency id="USD" />

  <billingPeriod>Monthly</billingPeriod>

  <orderLineItems>

    <orderLineItem id="45">

      <position>1</position>

      <contractCharge id="10" />

      <priceCode>SETUP-FEE</priceCode>

      <invoiceText>Initial Membership Fee</invoiceText>

      <lastUpdated>2010-08-08</lastUpdated>

      <isActive>false</isActive>

      <totalLifetimeValue>10000.00</totalLifetimeValue>

      <dateCreated>2010-08-06</dateCreated>

      <quantity>1.0</quantity>

    </orderLineItem>

    <orderLineItem id="46">

      <position>2</position>

      <contractCharge id="11" />

      <priceCode>MNTHLY-FEE</priceCode>

      <invoiceText>Monthly dues</invoiceText>

      <lastUpdated>2010-08-08</lastUpdated>

      <isActive>true</isActive>

      <totalLifetimeValue>300.00</totalLifetimeValue>

      <dateCreated>2010-08-06</dateCreated>

      <quantity>1.0</quantity>

    </orderLineItem>

  </orderLineItems>

  <nextBillableDate>2010-04-25</nextBillableDate>

  <isAutoRenew>true</isAutoRenew>

  <invoices>

    <invoice id="19" />

  </invoices>

</subscriptionOrder>

4.2.2. Retrieve Order List:

Returns a paged list of Orders. The Orders are sorted in descending order by createDate Defaults used if the query string parameters are missing:

• • • offset=0

    • max=50

    • orderStatus = ignored if not defined

    • customerId = ignored if not defined (i.e, returns a list of all orders)

    • createStartTime and createEndTime are optional params and can be used to retrieve a list of records created between the specified date range. Note that if createStartTime is specified and createEndTime is not specified, then createEndTime defaults to the current date/time

    • updateStartTime and updateEndTime are optional params and can be used to retrieve a list of records updated between the specified date range. Note that if updateStartTime is specified and updateEndTime is not specified, then updateEndTime defaults to the current date/time
      
      

GET /rest/orders?format=xml&offset=[n]&max=[m]&status=[orderStatus] &customerId=[id]&createStartTime=[YYYYMMDDHHmm]&createEndTime=[YYYYMMDDHHmm]&updateStartTime=[YYYYMMDDHHmm]&updateEndTime=[YYYYMMDDHHmm]

Note: To get the latest Order for a Customer (assuming each Customer only has one active Order) use this:

  /GET /rest_v1/orders? format=xml&offset=0&max=1&status=Active&customerId=[id]

Sample Output:

<list>

  <subscriptionOrder id="17">

  ...

  </subscriptionOrder>

  <subscriptionOrder id="22">

  ...

  </subscriptionOrder>

</list>

4.2.3. Create a new Order:

The XML that is POSTED should contain the SubscriptionOrder object and the OrderLineItems. It returns the same response as the "GET rest_v1/order /[id]?format=xml"

POST /rest/orders?format=xml

POST /rest/orders?format=xml&extCustomerRef=[code]

POST /rest/orders?format=xml&generateInvoice=true&forceInvoiceGeneration=true

Note: Use the "extCustomerRef" query string parameter if you wish to reference the customer by your assigned customer reference number (rather than the BluBilling assigned numeric customer id).

The "forceInvoiceGeneration" flag can be used only if you want to create an order and immediately generate an invoice for it. This will generate invoice even if next billing date is in future.

The "generateInvoice" flag can be used to create an order and immediately generate an invoice for it. This will generate invoice if billing date is in past or current date. This is useful for pre-paid plans so that the correct amount may be presented to the user for payment. Note that in simple cases it may be possible for the calling application to pre-determine the amount, but in complex cases (e.g., taxes, discounts, pro-rating, tiered pricing, etc.), it would be best to let BluBilling generate an invoice so that the precise amount can be calculated per the configured business rules.

Sample XML data for the POST above:

<subscriptionOrder>

  <orderStatus>Active</orderStatus>

  <startDate>2010-08-23</startDate>

  <customer id="117" /> <!-- the customer that this order belongs to -->

  <currency id="USD" />

  <isAutoRenew>false</isAutoRenew>

  <separateInvoice>

    2

<!--0=Combine Orders to Single Invoice,1=Separate Invoice, 2=Group Invoice by Job Code-->

  </separateInvoice>

  <jobCode>JOB-CODE</jobCode>

  <dueDateValue>30</dueDateValue>

  <dueDateUnits>Days</dueDateUnits>

  <contractCode>GOLD-PLAN</contractCode> <!-- the Plan associated with this order -->

  <orderLineItems>

    <orderLineItem>

    <position>1</position>

    <quantity>7.0</quantity>

    <priceCode>MNTHLY-CHRG</priceCode> <!-- each charge associated with plan -->

    </orderLineItem>

  </orderLineItems>

</subscriptionOrder>

4.2.4. Update an existing Order:

It returns the same response as the "GET rest_v1/order/[id]?format=xml". Note that this can only be used if the canEdit call returns true (see "Other operations" below)
The only properties that should be updated on an Order that has already generated invoices are the endDate, status and isAutoRenew properties.

PUT /rest/order/[id]?format=xml

PUT /rest/order? format=xml&orderNumber=[val]

Note that if only the status is being changed, then it is possible to send just that new value (rather than the whole subscriptionOrder XML tree):

<subscriptionOrder>

  <orderStatus>Active</orderStatus>

</subscriptionOrder>

The order status can be one of these values:

            Draft                currently being edited, do not use

            Provisioning       future dated order (changed from 'Waiting' to 'Provisioning')

            Active               current order

            Suspended        temporary hold placed by customer or staff

            Complete          past end date, order is complete (changed from 'Finished' to 'Complete')

            Superseded       new order replaces this one as a result of a ChangeOrder

            Canceled           cancelled by user - early termination prior to end date

Note that if an Order is cancelled, the Invoices are not automatically cancelled.

4.2.5. Change Order:

The common scenario of a customer wishing to upgrade or downgrade to another Plan may be handled by a "Change Order". In essense this is the same as terminating the old order on a certain date and then starting a new order, however, a single changeOrder call manages this process atomically and efficiently:

POST /rest/changeOrder?format=xml&currentOrderId=[id]&deleteCurrentOrder=[true | false]&effectiveDate=[yyyy-MM-dd]

POST /rest/changeOrder?format=xml&currentOrderNumber=[orderNumber]&effectiveDate=[yyyy-MM-dd]

4.2.6. Quote Order:

If you wish to generate a quote or estimate, then Quote function allows you to dynamically retrieve the price based on how the Plans/Charges are configured within the BluBilling system. If the calcTax parameter is set to true and you have a 3rd party sales tax enabled, then the address fields are required.

GET /rest/quote?format=xml&contractCode=[planCode]&quantity=[n]&promo=[discountCode]&calcTax=[true| false]&startDate=[yyyy-MM-dd]

If Tax is to be calculated:

GET /rest/quote?format=xml&contractCode=[planCode]&quantity=[n]&promo=[discountCode]&calcTax=[true]&startDate=[yyyy-MM-dd]&addressLine1=[123 Main]&addressCity=[Dallas]&addressState=[TX]&addressZip=[12345]

Sample Output
Note that the the system returns <initialCharges> and <recurringCharges> blocks, thereby separating out one-time charges from recurring ones.

<quote>

    <contractOffering>

        <contractCode>GOLD-PLAN-ANNUAL</contractCode>

        <orderDate>2016-04-30</orderDate>

        <billingPeriod>Yearly</billingPeriod>

        <initialCharges>

            <totalInitialCharges>0</totalInitialCharges>

        </initialCharges>

        <recurringCharges>

            <lineItems>

                <lineItem>

                    <position>1</position>

                    <priceCode>FEE</priceCode>

                    <invoiceText>Gold Plan - Annual</invoiceText>

                    <amount>1200.00</amount>

                    <pricingType>UserEnteredPricing</pricingType>

                    <chargeType>RecurringCharge</chargeType>

                    <quantity>1.0</quantity>

                    <billingPeriodStart>2016-04-30</billingPeriodStart>

                    <billingPeriodEnd>2016-04-30</billingPeriodEnd>

                    <billingPeriodDescription>2016-04-30 to 2017-04-30 (1 year)</billingPeriodDescription>

                    <isProrated>true</isProrated>

                </lineItem>

                <lineItem>

                    <position>2</position>

                    <priceCode>TAX</priceCode>

                    <invoiceText>AK STATE TAX - 6%</invoiceText>

                    <amount>72.00</amount>

                </lineItem>

            </lineItems>

            <totalRecurringCharges>1272.00</totalRecurringCharges>

        </recurringCharges>

        <total>1272.00</total>

    </contractOffering>

</quote>

4.2.7. Other operations on an Order:

Other service calls: rateOrder (contact customer support)