API upgrades

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

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.

2025-08-12

• We have introduced the 27 error category code. This error category code indicates that the request cannot be processed because of an invalid query parameter (filter[], expand[], sort[], and fields[]) of the Object Query API. See the following table for details:

  Category Code	Error Category	HTTP Status Code
  27	Invalid query parameter	400 Bad Request

• We have unified the 4XX and 500 error response formats for Object Query API operations to the following format:
  Copy

  Copied

  {
    "reasons": [
      {
        "code": {error_code},
        "message": "{error_message}"
      }
    ],
    "requestId": "{request_ID}"
  }

  This enhancement ensures that the Object Query API error response is consistent with the v1 API, which potentially simplifies your error-handling effort. The returned error code is a 8-digit code, such as 50000060, following the standard error code convention. See Error codes for details.

  Previously, the 4XX and 500 error response formats for Object Query API operations varied depending on the error scenarios. In some cases, the failed requests returned 200 HTTP status codes. It was also rectified to display the appropriate HTTP status code in the unified error response format.

2024-05-20

• 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 Code	Error Category	HTTP Status Code
  10	Permission or access denied	403 Forbidden
  11	Authentication failed	401 Unauthorized
  20	Invalid format or value	400 Bad Request
  21	Unknown field in request	400 Bad Request
  22	Missing required field	400 Bad Request
  23	Missing required query parameter	400 Bad Request
  30	Rule restriction	400 Bad Request
  40	Not found	404 Not Found
  45	Unsupported request	405 Method Not Allowed, 406 Not Acceptable, 415 Unsupported Media Type
  50	Locking contention	409 Conflict
  60	Internal error	500 Internal Server Error
  61	Temporary error	500 Internal Server Error
  70	Request exceeded limit	429 Too Many Requests
  90	Malformed request	400 Bad Request
  99	Integration error	500 Internal Server Error

337.0

• We have deprecated the paymentId field on the Payment Schedule Item object. The following operations are affected:
  • Add payment schedule items to a custom payment schedule
  • Update a payment schedule
  • Update a payment schedule item
  • Preview the result of payment schedule update
  • Retrieve a payment schedule
  • Retrieve a payment schedule item
  • List payment schedules by customer account
  • Cancel a payment schedule
  • Cancel a payment schedule item
  • Skip a payment schedule item
  • Retry failed payment schedule items

314.0

• We have replaced the batch field with a batches field of the Billing Preview Run object. The following operations are affected:
  • Create a billing preview run
  • Retrieve a billing preview run

257.0

• We have replaced the charges > chargeId parameter with a charges > productRatePlanChargeId parameter when creating a credit memo or debit memo from a charge. The following operations are affected:
  • Create a credit memo from a charge
  • Create a debit memo from a charge
• We have replaced the charges > comment parameter with a charges > description parameter when creating a credit memo or debit memo from a charge. The following operations are affected:
  • Create a credit memo from a charge
  • Create a debit memo from a charge
• We have replaced the comment field with a description field of the Credit Memo Item and Debit Memo Item objects. The following operations are affected:
  • Create a credit memo from an invoice
  • Create a debit memo from an invoice
  • List credit memo items
  • Retrieve a credit memo item
  • List debit memo items
  • Retrieve a debit memo item

239.0

• We have replaced the following fields with the taxationItems field on the respective object:
  • The creditTaxItems field of the Credit Memo Item object
  • The taxItems field of the Debit Memo Item object

  You can access these fields through the following operations:

  • List credit memo items
  • Retrieve a credit memo item
  • List debit memo items
  • Retrieve a debit memo item

230.0

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

224.0

• We have replaced the charges > memoItemAmount field with the charges > amount field on the Credit Memo object created from the product rate plan charge. The following operations are affected:
  • Create a credit memo from a charge
  • Create a debit memo from a charge

223.0

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

215.0

• 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

211.0

• We have replaced the invoiceTargetDate parameter with a targetDate parameter. The following operations are affected:
  • Create a subscription
  • Update a subscription
  • Renew a subscription
  • Cancel a subscription
  • Suspend a subscription
  • Resume a subscription
  • Create an account
• We have replaced the invoice boolean parameter (added in 196.0) with a runBilling parameter. The following operations are affected:
  • Create a subscription
  • Update a subscription
  • Renew a subscription
  • Cancel a subscription
  • Suspend a subscription
  • Resume a subscription
  • Create an account

207.0

• 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:
  • Preview a subscription
  • Update a subscription
• We have updated the possible values and the default value of the previewType parameter. The following operations are affected:
  • Preview a subscription
  • Update a subscription
    Since 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

196.0

• We have replaced the invoiceCollect parameter with a collect parameter. The following operations are affected:
  • Create a subscription
  • Update a subscription
  • Renew a subscription
  • Cancel a subscription
  • Suspend a subscription
  • Resume a subscription
  • Create an account