Home‎ > ‎Developer's Guide‎ > ‎REST Web Service API‎ > ‎

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 />
  <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 customers)



GET /rest/orders?format=xml&offset=[n]&max=[m]&status=[orderStatus] &customerId=[id]

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>
  <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. Other operations on an Order:

Other service calls: rateOrder (contact customer support)

Comments