Refactor of Advanced AR Settlement REST API Methods and URLs

[Jing]

To better standardize the REST APIs for the Advanced AR Settlement feature, Zuora is refactoring the HTTP methods and URLs for some operations.

• From the September 2017 release (R216) to December 2017 release (R219), both the legacy and new methods and URLs will be maintained for the following operations.
• In the October 2017 release (R217), the HTTP method and URL updates will be published to the REST API Reference.
• From the January 2018 release (R220) to March 2018 release (R222), only the new methods and URLs will be maintained for the following operations, but you can still use the legacy ones.
• In the April 2018 release (R223), all the legacy methods and URLs will be permanently removed for the following operations, indicating that you can only use the new ones.

The following table describes the refactor details about the Advanced AR Settlement REST API methods and URLs.

Operation	New Method/URL	Legacy Method/URL
Transfer payment	PUT /v1/payments/{paymentId}/transfer	POST /v1/payments/{paymentId}/accounts
Apply payment	PUT /v1/payments/{paymentId}/apply	POST /v1/payments/{paymentId}/apply
Unapply payment	PUT /v1/payments/{paymentId}/unapply	POST /v1/payments/{paymentId}/unapply
Cancel payment	PUT /v1/payments/{paymentId}/cancel	POST /v1/payments/{paymentId}/cancel
Refund payment	POST /v1/payments/{paymentId}/refunds	POST /v1/payments/{paymentId}/refund
Cancel refund	PUT /v1/refunds/{refundId}/cancel	POST /v1/refunds/{refundId}/cancel
Apply credit memo	PUT /v1/creditmemos/{creditMemoId}/apply	POST /v1/creditmemos/{creditMemoId}/apply
Unapply credit memo	PUT /v1/creditmemos/{creditMemoId}/unapply	POST /v1/creditmemos/{creditMemoId}/unapply
Cancel credit memo	PUT /v1/creditmemos/{creditMemoId}/cancel	POST /v1/creditmemos/{creditMemoId}/cancel
Post credit memo	PUT /v1/creditmemos/{creditMemoId}/post	POST /v1/creditmemos/{creditMemoId}/post
Refund credit memo	POST /v1/creditmemos/{creditmemoId}/refunds	POST /v1/creditmemos/{creditmemoId}/refund
Create credit memo from invoice	POST /v1/invoices/{invoiceId}/creditmemos	POST /v1/creditmemos/invoice/{invoiceId}
Query credit memos by account	N/A	POST /v1/creditmemos/query
Cancel debit memo	PUT /v1/debitmemos/{debitMemoId}/cancel	POST /v1/debitmemos/{debitMemoId}/cancel
Post debit memo	PUT /v1/debitmemos/{debitMemoId}/post	POST /v1/debitmemos/{debitMemoId}/post
Create debit memo from invoice	POST /v1/invoices/{invoiceId}/debitmemos	POST /v1/debitmemos/invoice/{invoiceId}
Create taxation items for credit memo	POST /v1/creditmemos/{creditMemoId}/taxationitems	POST /v1/taxationitems/creditmemo/{memoId}
Create taxation items for debit memo	POST /v1/debitmemos/{debitMemoId}/taxationitems	POST /v1/taxationitems/debitmemo/{memoId}

[ruffrey]

By deprecated, do you mean the now-legacy-methods will be "discouraged from use" or "removed." This article makes it sounds like they will be removed in April 2018.

[Jing]

@ruffrey "Deprecated" in this post means that all the current legacy methods and URLs will be "removed" in the April 2018 release, indicating that customers "cannot use them anymore" from then. Thanks!

[ruffrey]

Thank you for that clarification.

The derm "deprecated" has a different meaning in software development, it means that a feature is discouraged from use but will not break. The language of this post will surely confuse people.

More importantly, making breaking changes to your API while maintaining the same version (v1) begs the question "what does the v1 really mean?"

Here is good article on the kind of API versioning I would expect from something as critical as a payment gateway: https://stripe.com/blog/api-versioning

[Jing]

@ruffrey Thanks very much for your info. I've changed "deprecated" to "removed" to avoid further confusion.

For the "v1" issue, it is actually specific to the Zuora API endpoint design. We have a new Community API feedback forum where you can share your opinions on how our APIs don't fit your purpose well. You could publish a separate post in the API feedback forum to express your concern about API versioning. Thanks.