DOCS
Developer resources
Community

Collaborate on your project with other Marqeta developers

Sales

Speak with an expert to learn more about Marqeta

/
Guides
Core API

Launch and manage your company's payment card program

Core API Reference

Endpoint definitions and field-level reference

Core API Explorer

Try out all endpoints from your browser

DiVA API

Access the production data behind Marqeta's reporting and analytics tools

DiVA API Reference

Endpoint definitions and field-level reference

20 minute read
November 30, 2022

Auto Reload

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:

  • Account holder

  • Card product

  • Program

Create auto reload
Copy section link

Action: POST
Endpoint: /autoreloads

Sign in to use API widgets
POST

Use this endpoint to create an auto reload.

Request body
Copy section link

Fields Description

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
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Response body
Copy section link

Fields Description

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
Copy section link

JSON
Copied

Is this helpful?

Yes
No

List auto reloads
Copy section link

Action: GET
Endpoint: /autoreloads

Sign in to use API widgets
GET

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
Copy section link

Fields Description

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
Copy section link

Fields Description

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
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Retrieve auto reload
Copy section link

Action: GET
Endpoint: /autoreloads/{token}

Sign in to use API widgets
GET

Use this endpoint to retrieve a specific auto reload object.

URL path parameters
Copy section link

Fields Description

token

string
Required

Unique identifier of the auto reload.

Allowable Values:

Existing auto reload token

URL query parameters
Copy section link

Fields Description

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
Copy section link

Fields Description

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
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Update auto reload
Copy section link

Action: PUT
Endpoint: /autoreloads/{token}

Sign in to use API widgets
PUT

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
Copy section link

Fields Description

token

string
Required

Unique identifier of the auto reload.

Allowable Values:

Existing auto reload token

Request body
Copy section link

Fields Description

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
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Response body
Copy section link

Fields Description

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
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Related materials

Subscribe to our developer newsletter

© 2023 Marqeta, Inc.

• Terms • API Terms • Privacy • Cookies
Back to Marqeta.com