Skip to content

Add or remove store credit on a customer's balance

POST
/api/subscriptions/credits/adjustments
curl --request POST \
--url https://api.usegro.co/api/subscriptions/credits/adjustments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <X-API-Key>' \
--data '{ "profile_id": "example", "subscription_id": "example", "direction": "add", "amount": 1, "currency_code": "example", "reason": "goodwill", "note": "example", "idempotency_key": "example" }'

Writes one ledger row and moves the balance with it. amount is in the currency’s main unit, not cents (10.50 is $10.50), with at most two decimal places. reason is required; note is optional unless the reason is other. Removing more credit than the customer has (less any credit already on an order being billed) is refused with 422. Send the same idempotency_key on a retry so credit only moves once. Changes made with an API key are recorded with source api.

Media typeapplication/json
object
profile_id
required
string
subscription_id
string
direction
required
string
Allowed values: add remove
amount
required
number
<= 100000
currency_code
string
reason
required
string
Allowed values: goodwill correction refund promotion other
note
string
>= 1 characters <= 500 characters
idempotency_key
string
<= 100 characters
Media typeapplication/json
object
data
object
data
required
object
id
required
string
created_at
string
nullable
type
required
string
Allowed values: earned adjusted redeemed reversed
currency_code
required
string
profile_id
required
string
profile
object
id
string
email
string
full_name
string
is_reversed
required
boolean
amount
required
number
balance_after
required
number
source
required
string
Allowed values: referral earning_rule manual gro_agent mcp api billing loyalty_reward playbook
reason
One of:
string
nullable
note
string
nullable
subscription_id
string
nullable
referral_id
string
nullable
earning_rule_id
string
nullable
shopify_order_id
string
nullable
reverses_transaction_id
string
nullable
actor_type
required
string
Allowed values: user system customer api
actor_name
string
nullable
subscription
object
number
string
id
string
order
object
number
number
nullable
id
string

Example

{
"data": {
"data": {
"type": "earned",
"source": "referral",
"reason": "goodwill",
"actor_type": "user"
}
}
}

Not enough credit, or a missing note for the reason other

Media typeapplication/json