Request: updateOrCreatePayments
andrews05 opened this issue · comments
We currently have a plural createPayments PUT action as well as a singular createPayment POST action.
The singular POST action doesn't really serve any purpose over the plural PUT action, so I would like to suggest replacing it with updateOrCreatePayments. The primary purpose of this would be to allow bulk deleting multiple payments in one call (this is not something that is shown in the Xero API docs, but it still works as expected).
It would also provide some consistency with other endpoints which use the same actions.
I'm a bit unclear on this as is. I know Xero's endpoints sometime swap the functionality for PUT and POST as to what would be expected.
Just based on docs we seem to use:
PUT Payments
Use this method to apply payments to approved AR and AP invoices or refund AR or AP credit notes.
put:
security:
- OAuth2: [accounting.transactions]
tags:
- Accounting
operationId: createPayments
POST Payments
Use this method to delete (reverse) payments to invoices, credit notes, prepayments & overpayments. Note that payments created via batch payments and receipts are not supported. Payments cannot be modified, only created and deleted.
post:
security:
- OAuth2: [accounting.transactions]
tags:
- Accounting
operationId: createPayment
Are you proposing renaming the POST function to updateOrCreatePayments?
I think that it is a breaking change for what I'm not sure is possible. I'd have to triple check but wasn't sure if you can update existing, past the soft delete.
What I'm wanting is to be able to delete multiple payments in one call. Xero's POST endpoint is used for this purpose, but the open API currently defines createPayment as the POST action. My understanding was the open API doesn't support multiple actions for the same endpoint and method, which is why defining a separate deletePayments POST action is not possible, is that correct?
So what I'm suggesting is that the createPayment action is redundant and could be replaced with a different action for bulk deletion. The name updateOrCreatePayments was simply a suggestion for consistency with other similar actions, if you wanted to keep the ability to create as well. (But you're right, the only 'update' possible is to set the status to deleted)
Yes, it would be a breaking change but it would open functionality which is currently possible.