Stripe Balance Transactions - add operation `POST /v1/customers/{customer}/balance_transactions`

Feature Requests
1

I am able to successfully adjust a Stripe customers account balance by using the:
POST v1/customers/{customers} operation
payload.account_balance

{
  "account_balance": "-3400",
  "description": "testing" // this adds to the customer level description field not the transaction
}

However,

I would like to include a description to that adjustment. It appears that I need a different operation:
POST /v1/customers/cus_????????????/balance_transactions

Which would take a payload that would look like this (which happens from the Stripe Dashboard when you manually adjust the balance):

{
  "amount": "-3400",
  "currency": "usd",
  "description": "This transaction came from Retool - logged in user GDB."
}

I don't see this type of operation in the dropdown.

  1. Am I missing something?
  2. Has anyone been able to do this?
  3. Is this something that Retool would consider adding to the Stripe integration?
2

Hi @George_B,

The change you are doing is directly overriding the customer's account balance without proper paper trail/history. Based on Stripe's API docs, there's no endpoint for balance transactions. BT only records all transactions done within your Stripe account. Check here the type of transactions that BT records: Balance Transaction Types.

If you want to do a refund (which I think you are doing) or deduct something from a customer's balance, use one of the following BT types mentioned in the link above. Charges, Refunds, Payouts, etc. have those endpoints where you can write the description.

If you already have dummy data in the Stripe database, worthwhile to spend some time mapping the different connection of these schemas. Reverse engineer from there and know what endpoints you can use to manipulate the data that you want.

Regards

3

Actually, I do want to override the account balance, I just want to add a note/description as to why for the purposes of a paper trail. We sell software on a subscription basis, monthly and annually, and when a subscription is canceled we credit the account with the prorated dollar amount based on the period of time left on the subscription. We also allow our customers to move apps from one folder to another and those folders have their own Stripe customer instances.

So I want to be able to transfer credit from one Stripe account to another, which I can do but as noted it does not have any description as to where the funds came from and where they went to. I will just have to create a REST API and roll my own Stripe post using this model: Stripe API reference – Balance Transactions – curl

4

@George_B thanks for posting, and @jocen thank you for adding extra context!

It sounds like you have a path forward, even though you're running into some limitations with whether Stripe exposes the option to pass in a description for the specific Stripe endpoints you want to use. If we come across a better way to accomplish this, we'll let you know! Maybe there's another Stripe API expert in the community - glad you've opened the conversation here just in case.

5

@kbn I believe I can accomplish what I want by creating a REST API resource but I have to go through hoops on my end to get the API key needed as security into Stripe goes up pretty high in my organization. I already have access to the standard Stripe resource set up by the powers to be, but it does not have the operation that I need.

I suggest you @kbn ask your dev team to consider adding this operation to your Stripe resource instance to make it more complete.

POST /v1/customers/{customer}/balance_transactions

Here is a Stripe reference to what the payload properties should be:
https://stripe.com/docs/api/customer_balance_transactions/create?lang=curl

As you can see there are only 4 parameters and the Description is one of them, which is the extra one I need that is not available in the operation I was using to post adjustments to the balance: POST v1/customers/{customers}.

6

@George_B, ahh I see. Thanks for the heads up and docs for this. Unfortunately, I don't usually use any POST requests with Stripe since I'm only tackling it on the data side; one of our devs would probably do that integration though but not through retool.

As there's limit to what you can do, better have a discussion with your supervisor and if they can provide you better access.

Thanks

7

Thanks @George_B - I went ahead and converted this post to a Feature Request. This way others can also chime in if this is something they'd be interested in as well. I've also created a mirror ticket internally to look into what it'd take to update this, but don't have a timeline to share. Appreciate you both discussing this here @George_B @jocen!

8

@kbn Many thanks for listening. I will work on my plan "B" in the meantime.

1 Like
9

hey @George_B and @jocen -- circling back to share that the Stripe spec was updated by our engineers a few months back, meaning that it's now possible to make a POST request to the /v1/customers/{customer}/balance_transactions stripe endpoint, among many other endpoint options in the "Operation" dropdown. I was able to successfully do so with a test stripe instance/test customer just now!

Thanks again for sharing your use case and interest in this capability here, and thanks for your patience as the team was able to prioritize getting this update done recently :raised_hands: