Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Auto reload enables you to automatically load a specified amount into an account when the account balance falls below a defined threshold. Auto reloads execute only when the account balance falls below the trigger value due to spending. They do not execute due to unloading of funds or because of lack of funds when a user or business is first created. You can define auto reloads at the level of an account holder, a card product, or a program. Each auto reload draws from a single funding source. In the case of auto reloads defined at more than one level, the following order of precedence (first to last) determines which auto reload is executed:
1
Account holder
2
Card product
3
Program

​
Create auto reload

Action: POST
Endpoint: /autoreloads Use this endpoint to create an auto reload.

​
Request body

FieldsDescription
active

boolean

Optional		Specifies whether the auto reload is active.

Only one auto reload per level, per object, can be active.

Allowable Values:

true, false

Default value:
true
association

object

Optional		Specifies the scope of the auto reload.

Input no more than one field. If no value is supplied, the auto reload applies at the program level.

Allowable Values:

business_token, card_product_token, user_token
association.business_token

string

Optional		Unique identifier of the business for which the auto reload is configured.

Send a GET request to /businesses to retrieve business tokens.

Allowable Values:

1–36 chars
association.card_product_token

string

Optional		Unique identifier of the card product for which the auto reload is configured.

Send a GET request to /cardproducts to retrieve card product tokens.

Allowable Values:

1–36 chars
association.user_token

string

Optional		Unique identifier of the user for which the auto reload is configured.

Send a GET request to /users to retrieve user tokens.

Allowable Values:

1–36 chars
currency_code

string

Required		Three-digit ISO 4217 currency code.

Allowable Values:

Any currency code allowed by your program
funding_source_address_token

string

Optional		Unique identifier of the funding source address to use for this auto reload.

If your funding source is an ACH account, then a funding_source_address_token is not required. If your funding source is a payment card, you must have at least one funding source address in order to create a GPA order.

Send a GET request to /fundingsources/addresses/user/{user_token} to retrieve address tokens for a user.

Send a GET request to /fundingsources/addresses/business/{business_token} to retrieve address tokens for a business.

Allowable Values:

1–36 chars
funding_source_token

string

Optional		Unique identifier of the funding source to use for this auto reload.

Send a GET request to /fundingsources/user/{user_token} to retrieve funding source tokens for a user.

Send a GET request to /fundingsources/business/{business_token} to retrieve funding source tokens for a business.

Allowable Values:

1–36 chars
order_scope

object

Required		Defines the balance threshold and reload amounts.

Allowable Values:

gpa
order_scope.gpa

object

Optional		Defines the type of order.

Allowable Values:

reload_amount, trigger_amount
order_scope.gpa.reload_amount

decimal

Required		Available balance on the card after the reload has completed.

This value must be greater than or equal to the value of trigger_amount. Note that this is not the same as the amount added to the card, which will vary from reload to reload.

Allowable Values:

0.01 min
order_scope.gpa.trigger_amount

decimal

Required		Threshold that determines when the reload happens.

The reload is triggered when the card balance falls below this amount.

Allowable Values:

0.01 min
token

string

Optional		Unique identifier of the auto reload.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

1–36 chars

​
Sample request body

JSON
{
  "token": "my_user_01_autoreload_01",
  "active": false,
  "currency_code": "USD",
  "association": {
    "user_token": "my_user_01"
  },
  "funding_source_token": "my_program_funding_source_01",
  "order_scope": {
    "gpa": {
      "trigger_amount": 100,
      "reload_amount": 200
    }
  }
}

​
Response body

FieldsDescription
active

boolean

Conditionally returned		Specifies whether the auto reload is active.

This field is returned if it exists in the resource.

Allowable Values:

true, false
association

object

Conditionally returned		Specifies the scope of the auto reload.

Allowable Values:

business_token, card_product_token, user_token
association.business_token

string

Conditionally returned		Unique identifier of the business for which the auto reload is configured.

Allowable Values:

1–36 chars
association.card_product_token

string

Conditionally returned		Unique identifier of the card product for which the auto reload is configured.

Allowable Values:

1–36 chars
association.user_token

string

Conditionally returned		Unique identifier of the user for which the auto reload is configured.

Allowable Values:

1–36 chars
created_time

datetime

Returned		Date and time when the auto reload object was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
currency_code

string

Returned		Three-digit ISO 4217 currency code.

Allowable Values:

Any currency code allowed by your program
funding_source_address_token

string

Conditionally returned		Unique identifier of the funding source address to use for this auto reload.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars
funding_source_token

string

Conditionally returned		Unique identifier of the funding source to use for this auto reload.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars
last_modified_time

datetime

Returned		Date and time when the auto reload object was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
order_scope

object

Returned		Defines the balance threshold and reload amounts.

Allowable Values:

gpa
order_scope.gpa

object

Conditionally returned		Defines the type of order.

Allowable Values:

reload_amount, trigger_amount
order_scope.gpa.reload_amount

decimal

Returned		Available balance on the card after the reload has completed.

Allowable Values:

0.01 min
order_scope.gpa.trigger_amount

decimal

Returned		Threshold that determines when the reload happens.

The reload is triggered when the card balance falls below this amount.

Allowable Values:

0.01 min
token

string

Conditionally returned		Unique identifier of the auto reload.

This field is always returned.

Allowable Values:

1–36 chars

​
Sample response body

JSON
{
  "token": "my_user_01_autoreload_01",
  "active": false,
  "association": {
    "user_token": "my_user_01"
  },
  "funding_source_token": "my_program_funding_source_01",
  "order_scope": {
    "gpa": {
      "trigger_amount": 100,
      "reload_amount": 200
    }
  },
  "currency_code": "USD",
  "created_time": "2022-11-10T22:15:20Z",
  "last_modified_time": "2022-11-10T22:15:20Z"
}

​
List auto reloads

Action: GET
Endpoint: /autoreloads Use this endpoint to list auto reloads configured for the program or for a specific card product, user, or business. This endpoint supports field filtering and pagination.

​
URL query parameters

FieldsDescription
card_product

string

Optional		Unique identifier of the card product whose auto reloads you want to retrieve.

Allowable Values:

Existing card_product token
user_token

string

Optional		Unique identifier of the user whose auto reloads you want to retrieve.

Allowable Values:

Existing user token
business_token

string

Optional		Unique identifier of the business whose auto reloads you want to retrieve.

Allowable Values:

Existing business token
count

integer

Optional		Number of resources to retrieve.

Allowable Values:

1-10

Default value:
10
start_index

integer

Optional		Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0
fields

string

Optional		Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank
sort_by

string

Optional		Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-lastModifiedTime

​
Response body

FieldsDescription
count

integer

Conditionally returned		Number of resources to retrieve.

This field is returned if there are objects in your returned array.

Allowable Values:

1-10
data

array of objects

Conditionally returned		Array of auto reload objects.

Objects are returned as appropriate to your query.

Allowable Values:

Valid array of one or more auto reload objects
data[].active

boolean

Conditionally returned		Specifies whether the auto reload is active.

This field is returned if it exists in the resource.

Allowable Values:

true, false
data[].association

object

Conditionally returned		Specifies the scope of the auto reload.

Allowable Values:

business_token, card_product_token, user_token
data[].association.business_token

string

Conditionally returned		Unique identifier of the business for which the auto reload is configured.

Allowable Values:

1–36 chars
data[].association.card_product_token

string

Conditionally returned		Unique identifier of the card product for which the auto reload is configured.

Allowable Values:

1–36 chars
data[].association.user_token

string

Conditionally returned		Unique identifier of the user for which the auto reload is configured.

Allowable Values:

1–36 chars
data[].created_time

datetime

Returned		Date and time when the auto reload object was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
data[].currency_code

string

Returned		Three-digit ISO 4217 currency code.

Allowable Values:

Any currency code allowed by your program
data[].funding_source_address_token

string

Conditionally returned		Unique identifier of the funding source address to use for this auto reload.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars
data[].funding_source_token

string

Conditionally returned		Unique identifier of the funding source to use for this auto reload.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars
data[].last_modified_time

datetime

Returned		Date and time when the auto reload object was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
data[].order_scope

object

Returned		Defines the balance threshold and reload amounts.

Allowable Values:

gpa
data[].order_scope.gpa

object

Conditionally returned		Defines the type of order.

Allowable Values:

reload_amount, trigger_amount
data[].order_scope.gpa.reload_amount

decimal

Returned		Available balance on the card after the reload has completed.

Allowable Values:

0.01 min
data[].order_scope.gpa.trigger_amount

decimal

Returned		Threshold that determines when the reload happens.

The reload is triggered when the card balance falls below this amount.

Allowable Values:

0.01 min
data[].token

string

Conditionally returned		Unique identifier of the auto reload.

This field is always returned.

Allowable Values:

1–36 chars
end_index

integer

Conditionally returned		Sort order index of the last resource in the returned array.

This field is returned if there are objects in your returned array.

Allowable Values:

Any integer
is_more

boolean

Conditionally returned		A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are objects in your returned array.

Allowable Values:

true, false
start_index

integer

Conditionally returned		Sort order index of the first resource in the returned array.

This field is returned if there are objects in your returned array.

Allowable Values:

Any integer

​
Sample response body

JSON
{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "my_user_01_autoreload_01",
      "active": false,
      "funding_source_token": "my_program_funding_source_01",
      "association": {
        "user_token": "my_user_01"
      },
      "order_scope": {
        "gpa": {
          "trigger_amount": 100,
          "reload_amount": 200
        }
      },
      "currency_code": "USD",
      "created_time": "2022-11-10T22:15:20Z",
      "last_modified_time": "2022-11-10T22:21:59Z"
    }
  ]
}

​
Retrieve auto reload

Action: GET
Endpoint: /autoreloads/{token} Use this endpoint to retrieve a specific auto reload object.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the auto reload.

Allowable Values:

Existing auto reload token

​
URL query parameters

FieldsDescription
fields

string

Optional		Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

​
Response body

FieldsDescription
active

boolean

Conditionally returned		Specifies whether the auto reload is active.

This field is returned if it exists in the resource.

Allowable Values:

true, false
association

object

Conditionally returned		Specifies the scope of the auto reload.

Allowable Values:

business_token, card_product_token, user_token
association.business_token

string

Conditionally returned		Unique identifier of the business for which the auto reload is configured.

Allowable Values:

1–36 chars
association.card_product_token

string

Conditionally returned		Unique identifier of the card product for which the auto reload is configured.

Allowable Values:

1–36 chars
association.user_token

string

Conditionally returned		Unique identifier of the user for which the auto reload is configured.

Allowable Values:

1–36 chars
created_time

datetime

Returned		Date and time when the auto reload object was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
currency_code

string

Returned		Three-digit ISO 4217 currency code.

Allowable Values:

Any currency code allowed by your program
funding_source_address_token

string

Conditionally returned		Unique identifier of the funding source address to use for this auto reload.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars
funding_source_token

string

Conditionally returned		Unique identifier of the funding source to use for this auto reload.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars
last_modified_time

datetime

Returned		Date and time when the auto reload object was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
order_scope

object

Returned		Defines the balance threshold and reload amounts.

Allowable Values:

gpa
order_scope.gpa

object

Conditionally returned		Defines the type of order.

Allowable Values:

reload_amount, trigger_amount
order_scope.gpa.reload_amount

decimal

Returned		Available balance on the card after the reload has completed.

Allowable Values:

0.01 min
order_scope.gpa.trigger_amount

decimal

Returned		Threshold that determines when the reload happens.

The reload is triggered when the card balance falls below this amount.

Allowable Values:

0.01 min
token

string

Conditionally returned		Unique identifier of the auto reload.

This field is always returned.

Allowable Values:

1–36 chars

​
Sample response body

JSON
{
  "token": "my_user_01_autoreload_01",
  "active": false,
  "funding_source_token": "my_program_funding_source_01",
  "association": {
    "user_token": "my_user_01"
  },
  "order_scope": {
    "gpa": {
      "trigger_amount": 100,
      "reload_amount": 200
    }
  },
  "currency_code": "USD",
  "created_time": "2022-11-10T22:15:20Z",
  "last_modified_time": "2022-11-10T22:21:59Z"
}

​
Update auto reload

Action: PUT
Endpoint: /autoreloads/{token} Use this endpoint to update an auto reload. Only values of parameters in the request are modified; all others are left unchanged.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the auto reload.

Allowable Values:

Existing auto reload token

​
Request body

FieldsDescription
active

boolean

Optional		Specifies whether the auto reload is active.

Only one auto reload per level, per object, can be active.

Allowable Values:

true, false

Default value:
true
association

object

Optional		Specifies the scope of the auto reload.

Input no more than one field. If no value is supplied, the auto reload applies at the program level.

Allowable Values:

business_token, card_product_token, user_token
association.business_token

string

Optional		Unique identifier of the business for which the auto reload is configured.

Send a GET request to /businesses to retrieve business tokens.

Allowable Values:

1–36 chars
association.card_product_token

string

Optional		Unique identifier of the card product for which the auto reload is configured.

Send a GET request to /cardproducts to retrieve card product tokens.

Allowable Values:

1–36 chars
association.user_token

string

Optional		Unique identifier of the user for which the auto reload is configured.

Send a GET request to /users to retrieve user tokens.

Allowable Values:

1–36 chars
currency_code

string

Optional		Three-digit ISO 4217 currency code.

Allowable Values:

Any currency code allowed by your program
funding_source_address_token

string

Optional		Unique identifier of the funding source address to use for this auto reload.

If your funding source is an ACH account, then a funding_source_address_token is not required. If your funding source is a payment card, you must have at least one funding source address in order to create a GPA order.

Allowable Values:

1–36 chars

Existing funding source address token.

Send a GET request to /fundingsources/addresses/user/{user_token} to retrieve address tokens for a user.

Send a GET request to /fundingsources/addresses/business/{business_token} to retrieve address tokens for a business.
funding_source_token

string

Optional		Unique identifier of the funding source to use for this auto reload.

Allowable Values:

1–36 chars

Existing funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve funding source tokens for a user.

Send a GET request to /fundingsources/business/{business_token} to retrieve funding source tokens for a business.
order_scope

object

Optional		Defines the balance threshold and reload amounts.

Allowable Values:

gpa
order_scope.gpa

object

Optional		Defines the type of order.

Allowable Values:

reload_amount, trigger_amount
order_scope.gpa.reload_amount

decimal

Required		Available balance on the card after the reload has completed.

This value must be greater than or equal to the value of trigger_amount. Note that this is not the same as the amount added to the card, which will vary from reload to reload.

Allowable Values:

0.01 min
order_scope.gpa.trigger_amount

decimal

Required		Threshold that determines when the reload happens.

The reload is triggered when the card balance falls below this amount.

Allowable Values:

0.01 min
token

string

Optional		The token in the path parameter takes precedence over the token body field.

Allowable Values:

1–36 chars

​
Sample request body

JSON
{
  "order_scope": {
    "gpa": {
      "trigger_amount": 250,
      "reload_amount": 500
    }
  }
}

​
Response body

FieldsDescription
active

boolean

Conditionally returned		Specifies whether the auto reload is active.

This field is returned if it exists in the resource.

Allowable Values:

true, false
association

object

Conditionally returned		Specifies the scope of the auto reload.

Allowable Values:

business_token, card_product_token, user_token
association.business_token

string

Conditionally returned		Unique identifier of the business for which the auto reload is configured.

Allowable Values:

1–36 chars
association.card_product_token

string

Conditionally returned		Unique identifier of the card product for which the auto reload is configured.

Allowable Values:

1–36 chars
association.user_token

string

Conditionally returned		Unique identifier of the user for which the auto reload is configured.

Allowable Values:

1–36 chars
created_time

datetime

Returned		Date and time when the auto reload object was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
currency_code

string

Returned		Three-digit ISO 4217 currency code.

Allowable Values:

Any currency code allowed by your program
funding_source_address_token

string

Conditionally returned		Unique identifier of the funding source address to use for this auto reload.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars
funding_source_token

string

Conditionally returned		Unique identifier of the funding source to use for this auto reload.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars
last_modified_time

datetime

Returned		Date and time when the auto reload object was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
order_scope

object

Returned		Defines the balance threshold and reload amounts.

Allowable Values:

gpa
order_scope.gpa

object

Conditionally returned		Defines the type of order.

Allowable Values:

reload_amount, trigger_amount
order_scope.gpa.reload_amount

decimal

Returned		Available balance on the card after the reload has completed.

Allowable Values:

0.01 min
order_scope.gpa.trigger_amount

decimal

Returned		Threshold that determines when the reload happens.

The reload is triggered when the card balance falls below this amount.

Allowable Values:

0.01 min
token

string

Conditionally returned		Unique identifier of the auto reload.

This field is always returned.

Allowable Values:

1–36 chars

​
Sample response body

JSON
{
  "token": "my_user_01_autoreload_01",
  "active": false,
  "funding_source_token": "my_program_funding_source_01",
  "association": {
    "user_token": "my_user_01"
  },
  "order_scope": {
    "gpa": {
      "trigger_amount": 250,
      "reload_amount": 500
    }
  },
  "currency_code": "USD",
  "created_time": "2022-11-10T22:15:20Z",
  "last_modified_time": "2022-11-10T22:25:00Z"
}

Related topics

Program TransfersLoadsErrors3DS Automated Decision Service ReportingExploring the DiVA API