search

XeroAPI / Xero-OpenAPI

An OpenAPI description of the Xero API
https://developer.xero.com
MIT License
97 stars 121 forks source link

Request: bulk delete payments #232

Open andrews05 opened 4 years ago

andrews05 commented 4 years ago

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.

SerKnight commented 3 years ago

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.

andrews05 commented 3 years ago

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.