API Calls for Change Management

This whitepaper highlights some of the commonly encountered tasks during the couse of business operations.

Cancellation

Invoices may be cancelled with these REST API calls:

DELETE /rest_v1/invoice/[id]?suspendOrders=true
DELETE /rest_v1/invoice?invoiceNumber=[value]&suspendOrders=true

If the suspendOrders parameter is set to true, then all Active Orders that are associated with the Invoice will be suspended. It defaults to false if not provided.

An Order may be cancelled or suspended by changing its "orderStatus".

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

Request payload:

<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.

Note that the recommended practice for a normal customer cancellation is to set the order "endDate". This way the normal billing activities continue, and the customer would receive her final bill during the regular billing cycle. If the plan charges were configured as "pro-rated", then they would be billed proportionately (rather than for a full billing cycle).

Customer Wishes to Change Plans

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_v1/changeOrder?format=xml&currentOrderId=[id]&deleteCurrentOrder=[true | false]&effectiveDate=[yyyy-MM-dd]

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

The XML request for the payload is the same as that for creating a new order. Similarly, the response XML returned is that of the newly created order (i.e., same as doing a GET request on the new order).