API upgrades

This page summarizes the backward-incompatible changes made to the v1 API Reference.

Starting from May 20, 2024, all versions are in the date format such as 2024-05-20. The versions before this date are the legacy versions in the numbered format such as 196.0, which are still supported for backward compatibility.

To learn how to upgrade to the latest version, see API upgrade guide.

For backward-compatible (non-breaking) changes, see v1 API changelog for more information.


  • We have made the following HTTP status code changes to all v1 operations (except Actions and CRUD operations):

    Any errors containing an error category code now return a standard HTTP status code that aligns with the indication of the error. See the following table for details.

    Previously, any errors with an error category code were designed to return a 200 OK HTTP status code.
    Category CodeError CategoryHTTP Status Code
    10Permission or access denied403 Forbidden
    11Authentication failed401 Unauthorized
    20Invalid format or value400 Bad Request
    21Unknown field in request400 Bad Request
    22Missing required field400 Bad Request
    23Missing required query parameter400 Bad Request
    30Rule restriction400 Bad Request
    40Not found404 Not Found
    45Unsupported request405 Method Not Allowed,
    406 Not Acceptable,
    415 Unsupported Media Type
    50Locking contention409 Conflict
    60Internal error500 Internal Server Error
    61Temporary error500 Internal Server Error
    70Request exceeded limit429 Too Many Requests
    90Malformed request400 Bad Request
    99Integration error500 Internal Server Error






  • We have made the following behavior changes to the returned productRatePlans field of the Product object in the response of the Retrieve a product and List all products operations:
    • For 230.0 and later versions, the value of the productRatePlans field is a URL.
    • For 229.0 and earlier versions, the value of this field was an array of product rate plan details. Note that the array can contain a maximum of 300 product rate plans. Additionally, across all product rate plans, at most 300 product rate plan charges are returned.



  • For the Create an order operation, we have replaced the returned subscriptionNumbers field with a subscriptions field as the container for the subscription number and status on the Order object.


  • We have made the following changes to the Invoice and Collect operation:
    • Replaced the invoiceDate parameter with the documentDate parameter
    • Replaced the invoiceTargetDate parameter with the targetDate parameter



  • When previewing a subscription, we have replaced the invoiceTargetDate field with a targetDate field.
  • We have replaced the includeExistingDraftInvoiceItems parameter with a includeExistingDraftDocItems parameter. The following operations are affected:
  • We have updated the possible values and the default value of the previewType parameter. The following operations are affected:
    • Preview a subscription
    • Update a subscriptionSince 207.0, the possible values are LegalDoc(default), ChargeMetrics, and LegalDocChargeMetrics. Previously, the possible values were InvoiceItem(default), ChargeMetrics, and InvoiceItemChargeMetrics.
  • We have changed the response schema of the Preview a subscription and Update a subscription operations. The following top-level response fields are moved to the invoice container:
    • amount
    • amountWithoutTax
    • taxAmount
    • invoiceItems