Happy Business Starts Here

Zuora Documentation

Refactor of Advanced AR Settlement REST API Methods and URLs

 

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}

 

4 REPLIES 4
Scholar

Re: Refactor of Advanced AR Settlement REST API Methods and URLs

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.

Zuora Documentation

Re: Refactor of Advanced AR Settlement REST API Methods and URLs

@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!

Highlighted
Scholar

Re: Refactor of Advanced AR Settlement REST API Methods and URLs

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

Zuora Documentation

Re: Refactor of Advanced AR Settlement REST API Methods and URLs

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