"External_id" for agreements

• It is possible to update the external_id. But the parameter is meant as a unique identifier, chosen by the merchant, which shouldn’t change. On our side we have the "agreement_id, which never changes regardless of what happens to the agreement. That is the counterpart to the external_id on your side. It should stay the same, so we can trace the full history of the agreement. 
• The customer can see the external_id in the app.
• Our recommendation is, that the external_id is the users agreement id or reference with you. So that it does not seem confusing for the user. And if they have more than one Subscriptions agreement with you, they should be able to see which Subscriptions agreement is connected to which merchant agreement.
• The external_id is included in the request body of the success and cancel callback. 
• Maximum length is 64 characters

external_id for payments 

•  When utilizing callbacks, it is important that you evaluate your usage of external_id, as it will be included in the request body of the refund callback, as well in the reference number and bank statement. The merchant is responsible for setting the external_id. If the merchant is using instant transfer, then the reference number will be the external_id for recurring payments and one-off payments. Merchant can set Instant transfers themsleves in the MobilePay Portal. Read more about reconciling subscriptions payments here. 
• The customer can also see the payment external_id in the app. 
• Our recommendation is that the external_id is unique for each payment.
• Maximum length is 30 characters (this will soon be larger).

external_id for refunds

• You can see how external_id for refund is implemented https://mobilepaydev.github.io/MobilePay-Subscriptions/refund 
• The same goes for the refunds, the external_id will be included in the request body of the refund callback

Updating the external_id

• This is done using the PATCH /api/merchants/me/agreements/{agreementId} endpoint.