This whitepaper highlights some of the commonly encountered tasks during the couse of business operations.
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).
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¤tOrderId=[id]&deleteCurrentOrder=[true | false]&effectiveDate=[yyyy-MM-dd]
POST /rest_v1/changeOrder?format=xml¤tOrderNumber=[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).