Core Resources

Credits

Plus planRetain

The Credit Account object represents a set of positive and negative credit adjustments that when summed equal an available balance. Credit accounts may not have negative balances. A credit account may be associated with a customer, via the customer_id attribute. A customer may be associated with many credit accounts. A credit adjustment represents a financial adjustment to the balance of a Credit Account. An adjustment of type ‘credit’ results in an increase in the available balance of a credit account, where an adjustment of type ‘debit’ results in a decrease.

Access to the Credits endpoints are only available for merchants using Retain.

Endpoints

POST/credit_accounts
GET/credit_accounts/{id}
PUT/credit_accounts/{id}
GET/credit_accounts
POST/credit_accounts/{id}/credit_adjustments
GET/credit_accounts/{id}/credit_adjustments
GET/credit_adjustments

#The credit account object

Plus planRetain

Attributes

idinteger
Unique numeric identifier for the Credit Account
customer_idinteger
Unique numeric identifier for the customer associated with the credit_account.
available_balancestring
The dollar amount of available credit in the credit account, in the associated Store’s default currency as configured in Recharge
created_atdatetime
The date and time at which the credit account was created.
currency_codestring
The currency code for the credit account.
expires_atdatetime
The date and time at which the credit account expires, and can no longer be adjusted.
initial_valuestring
The initial value of the credit account at the time of creation.
namestring
The name of the credit account
typestring
The type of the credit account. Accepted values are rewards and manual.
updated_atdatetime
The date and time at which the credit account was last updated.

The credit account object

{
  "credit_account": {
    "id": 697470,
    "customer_id": 36885098,
    "available_balance": "10.00",
    "created_at": "2024-07-08T20:40:30+00:00",
    "currency_code": "USD",
    "expires_at": null,
    "initial_value": "1.55",
    "name": "Reward Credit",
    "type": "reward",
    "updated_at": "2024-07-08T20:40:30+00:00"
  }
}

#Create a credit account

POST/credit_accounts

Plus planRetain

Create a new credit account.

Scopewrite_credit_accounts

Body parameters

customer_idintegerRequired
The ID of the customer to create the credit account for.
expires_atdatetime
The date and time at which the credit account expires, and can no longer be adjusted.
initial_valuestring
The initial value of the credit account at the time of creation.
namestringRequired
The name of the credit account.
typestringRequired
The type of the credit account. Accepted values are reward and manual.

POST/credit_accounts

curl 'https://api.rechargeapps.com/credit_accounts' \
 -H 'X-Recharge-Version: 2021-11' \
 -H 'X-Recharge-Access-Token: your_api_token' \
 -d 'customer_id=36885098' \
 -d 'name=Reward Credit' \
 -d 'type=reward' \
 -d 'initial_value=10.00' \
 -d 'expires_at=2026-01-01T00:00:00+00:00'

Response

{
  "credit_account": {
    "id": 697470,
    "customer_id": 36885098,
    "available_balance": "0.00",
    "created_at": "2024-07-08T20:40:30+00:00",
    "currency_code": "USD",
    "expires_at": null,
    "initial_value": "0.45",
    "name": "Reward Credit",
    "type": "reward",
    "updated_at": "2024-07-08T20:40:30+00:00"
  }
}

#Retrieve a credit account

GET/credit_accounts/{id}

Plus planRetain

Retrieve one credit account using credit_account_id.

Scoperead_credit_accounts

GET/credit_accounts/{id}

curl 'https://api.rechargeapps.com/credit_accounts/697470' \
  -H 'X-Recharge-Version: 2021-11' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "credit_account": {
    "id": 697470,
    "customer_id": 36885098,
    "available_balance": "0.00",
    "created_at": "2024-07-08T20:40:30+00:00",
    "currency_code": "USD",
    "expires_at": null,
    "initial_value": "0.45",
    "name": "Reward Credit",
    "type": "reward",
    "updated_at": "2024-07-08T20:40:30+00:00"
  }
}

#Update a credit account

PUT/credit_accounts/{id}

Plus planRetain

Update a credit account name, expiration date or assign to a customer.

Scopewrite_credit_accounts

Body parameters

namestring
The name of the credit account.
customer_idstring
The ID of the customer to assign the credit account to.
expires_atdatetime
The date and time at which the credit account expires, and can no longer be adjusted.

PUT/credit_accounts/{id}

curl 'https://api.rechargeapps.com/credit_accounts/697470' \
 -H 'X-Recharge-Version: 2021-11' \
 -H 'X-Recharge-Access-Token: your_api_token' \
 -d 'name=Reward Credit' \
 -d 'customer_id=36885098' \
 -d 'expires_at=2026-01-01T00:00:00+00:00'

Response

{
  "credit_account": {
    "id": 697470,
    "customer_id": 36885098,
    "available_balance": "0.00",
    "created_at": "2024-07-08T20:40:30+00:00",
    "currency_code": "USD",
    "expires_at": null,
    "initial_value": "0.45",
    "name": "Reward Credit",
    "type": "reward",
    "updated_at": "2024-07-08T20:40:30+00:00"
  }
}

#List credit accounts

GET/credit_accounts

Plus planRetain

Return a list of credit accounts.

Scoperead_credit_accounts

Query parameters

customer_idstring
Return the list of credit accounts linked to the given Recharge customer_id
customer_idsstring
Return the list of credit accounts linked to any of the given Recharge customer_ids. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error
expires_at_mindatetime
Return the list of credit accounts that expire after the given date (inclusive).
expires_at_maxdatetime
Return the list of credit accounts that expire before the given date (inclusive).
limitstring
The amount of results. Default is 50 while the maximum is 250.

GET/credit_accounts

curl 'https://api.rechargeapps.com/credit_accounts' \
  -H 'X-Recharge-Version: 2021-11' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "next_cursor": "eyJzdGFydGluZ19iZWZvcmVfaWQiOjQ5ODg2NywibGFzdF92YWx1ZSI6NDk4ODY3LCJzb3J0X2J5IjoiaWQtZGVzYyIsImN1cnNvcl9kaXIiOiJuZXh0In0",
  "previous_cursor": null,
  "credit_accounts": [
    {
      "id": 697470,
      "customer_id": 36885098,
      "available_balance": "0.00",
      "created_at": "2024-07-08T20:40:30+00:00",
      "currency_code": "USD",
      "expires_at": null,
      "initial_value": "0.45",
      "name": "Reward Credit",
      "type": "reward",
      "updated_at": "2024-07-08T20:40:30+00:00"
    }
  ]
}

#Create a credit adjustment

POST/credit_accounts/{id}/credit_adjustments

Plus planRetain

Create a new credit adjustment for a specific credit account using credit_account_id.

Scopewrite_credit_adjustments

Body parameters

amountstringRequired
The amount of the credit adjustment.
notestring
The note for the credit adjustment.
typestringRequired
The type of the credit adjustment. Accepted values are debit and credit.
Possible values
debitcredit

Response attributes

idinteger
Unique numeric identifier for the Credit Adjustment.
credit_account_idinteger
Unique numeric identifier for the Credit Account associated with the Credit Adjustment.
amountstring
The dollar amount of the credit adjustment in the indicated currency.
created_atdatetime
The date and time at which the credit adjustment was created.
created_byobject
The resource that created the credit adjustment.
currency_codestring
The currency code of the credit_account associated with the credit_adjustment.
ending_balancestring
The resulting balance of the associated credit_account after the credit_adjustment was applied.
notestring
A note indicating additional information about the credit adjustment.
typestring
The type of the adjustment. Accepted values are 'credit' or 'debit', where credit results in a higher available balance, and debit results in a lower available balance.
updated_atdatetime
The date and time at which the credit adjustment was updated.

POST/credit_accounts/{id}/credit_adjustments

curl -X POST 'https://api.rechargeapps.com/credit_accounts/697470/credit_adjustments' \
  -H 'X-Recharge-Version: 2021-11' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "amount": "10.00",
  "note": "Gift card purchase",
  "type": "debit"
}'

Response

{
  "credit_adjustment": [
    {
      "id": 4866849,
      "credit_account_id": 697470,
      "amount": "0.45",
      "created_at": "2024-08-08T04:06:37+00:00",
      "created_by": {
        "resource_id": null,
        "identifier": "API",
        "type": "external"
      },
      "currency_code": "USD",
      "ending_balance": "0.00",
      "note": "Amount related with order Charge Id: 11888235",
      "type": "debit",
      "updated_at": "2024-08-08T04:06:37+00:00"
    }
  ]
}

#List Credit Adjustments for a Credit Account

GET/credit_accounts/{id}/credit_adjustments

Plus planRetain

Retrieve credit adjustments associated with specific credit account using credit_account_id.

Scoperead_credit_adjustments

Query parameters

limitstring
The amount of results. Default is 50 while the maximum is 250.

Response attributes

idinteger
Unique numeric identifier for the Credit Adjustment.
credit_account_idinteger
Unique numeric identifier for the Credit Account associated with the Credit Adjustment.
amountstring
The dollar amount of the credit adjustment in the indicated currency.
created_atdatetime
The date and time at which the credit adjustment was created.
created_byobject
The resource that created the credit adjustment.
currency_codestring
The currency code of the credit_account associated with the credit_adjustment.
ending_balancestring
The resulting balance of the associated credit_account after the credit_adjustment was applied.
notestring
A note indicating additional information about the credit adjustment.
typestring
The type of the adjustment. Accepted values are 'credit' or 'debit', where credit results in a higher available balance, and debit results in a lower available balance.
updated_atdatetime
The date and time at which the credit adjustment was updated.

GET/credit_accounts/{id}/credit_adjustments

curl 'https://api.rechargeapps.com/credit_accounts/697470/credit_adjustments' \
  -H 'X-Recharge-Version: 2021-11' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "next_cursor": null,
  "previous_cursor": null,
  "credit_adjustments": [
    {
      "id": 4866849,
      "credit_account_id": 697470,
      "amount": "0.45",
      "created_at": "2024-08-08T04:06:37+00:00",
      "currency_code": "USD",
      "ending_balance": "0.00",
      "note": "Amount related with shop order store.myshopify.com Address Id: 169902120 Charge Id: 1125729345",
      "type": "debit",
      "updated_at": "2024-08-08T04:06:37+00:00"
    },
    {
      "id": 4719708,
      "credit_account_id": 697470,
      "amount": "0.45",
      "created_at": "2024-07-08T20:40:31+00:00",
      "currency_code": "USD",
      "ending_balance": "0.45",
      "note": "3% Cash back on curious tomatoes",
      "type": "credit",
      "updated_at": "2024-07-08T20:40:31+00:00"
    }
  ]
}

#List credit adjustments

GET/credit_adjustments

Plus planRetain

Retrieve a list of credit adjustments.

Scoperead_credit_adjustments

Query parameters

idsstring
Return the list of credit adjustments linked to the given Recharge ids. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error
created_at_minstring
Return the list of credit adjustments created after the given date.
created_at_maxstring
Return the list of credit adjustments created before the given date.
includestring
Only supported value is customer. If customer is included, the response will include the customer object.
limitstring
The amount of results. Default is 50 while the maximum is 250.
undefinedstring
Sort the results by the given field.
updated_at_minstring
Return the list of credit adjustments updated after the given date.
updated_at_maxstring
Return the list of credit adjustments updated before the given date.

Response attributes

idinteger
Unique numeric identifier for the Credit Adjustment.
credit_account_idinteger
Unique numeric identifier for the Credit Account associated with the Credit Adjustment.
amountstring
The dollar amount of the credit adjustment in the indicated currency.
created_atdatetime
The date and time at which the credit adjustment was created.
created_byobject
The resource that created the credit adjustment.
currency_codestring
The currency code of the credit_account associated with the credit_adjustment.
ending_balancestring
The resulting balance of the associated credit_account after the credit_adjustment was applied.
notestring
A note indicating additional information about the credit adjustment.
typestring
The type of the adjustment. Accepted values are 'credit' or 'debit', where credit results in a higher available balance, and debit results in a lower available balance.
updated_atdatetime
The date and time at which the credit adjustment was updated.

GET/credit_adjustments

curl 'https://api.rechargeapps.com/credit_adjustments' \
  -H 'X-Recharge-Version: 2021-11' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "next_cursor": "eyJzdGFydGluZ19iZWZvcmVfaWQiOjQ4NjY4NDksImxhc3RfdmFsdWUiOjQ4NjY4NDksInNvcnRfYnkiOiJpZC1kZXNjIiwiY3Vyc29yX2RpciI6Im5leHQifQ",
  "previous_cursor": null,
  "credit_adjustments": [
    {
      "id": 4866849,
      "credit_account_id": 697470,
      "amount": "0.45",
      "created_at": "2024-08-08T04:06:37+00:00",
      "created_by": {
        "resource_id": null,
        "identifier": "API",
        "type": "external"
      },
      "currency_code": "USD",
      "ending_balance": "0.00",
      "note": "Amount related with shop order shop.myshopify.com. Address Id: 169902120 Charge Id: 1125729345",
      "type": "debit",
      "updated_at": "2024-08-08T04:06:37+00:00"
    }
  ]
}