DOCS

New!

/

20 minute read

August 3, 2019

Orders

The orders resource represents a movement of funds from a funding source into either a general purpose account (GPA) or a merchant-specific account (MSA). By default, every Marqeta account holder (either a user or business) has a GPA. MSAs are created dynamically as needed. Marqeta supports the following types of orders:

GPA Orders GPA orders primarily load funds into an account holder’s GPA. GPA orders can also be used to move funds from an account holder’s funding source into your program’s fee account if you include a fee. GPA orders can be funded by the account holder or your program.

MSA Orders Creating an MSA order is the equivalent of buying credit that can be used later only at a specific group of stores. You specify the group of stores by referencing an existing campaign. You can reference either an explicitly created campaign or the default campaign created whenever you create a merchant (in the latter case, the campaign token equals the merchant token). Creating an MSA order automatically creates an MSA for the account holder and deposits the funds into the account. The MSA funds can be spent only at the stores defined in the MSA order’s associated campaign. MSA orders can be funded by the account holder or your program.

Offer Orders An offer order associates an offer with an account holder and a funding source. As with MSA orders, creating an offer order automatically creates an MSA for the account holder and deposits the funds into the account. The MSA funds can be spent only at the stores defined in the offer order’s associated campaign (in this case the association is by way of the offer). Offer orders can be funded by the account holder or your program. Offer orders differ from MSA orders in that they fund the MSA for more than the amount pulled from the funding source.

Create GPA order

Action: POST
Endpoint: /gpaorders

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to create an order to fund an account holder’s general purpose account (GPA).

If you don’t specify a funding_source_token, the default funding source is used. If you have not specified a default funding source, the first funding source you created is used (it was automatically configured as the default).

You can assess a fee while funding a GPA by using the optional fees array to attach one or more fee resources to the GPA order. When you create a GPA order, the GPA is first credited for the fees, then debited at funding time.

Body field details

Fields Description

token

string, optional

The unique identifier of the GPA order.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other 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:

36 char max

user_token

OR

business_token

string, required

Identifies the owner of the account being funded.

Allowable Values:

Existing user or business token.

Send a GET request to /users to retrieve user tokens or to /businesses to retireive business tokens.

amount

decimal, required

The amount to fund.

Allowable Values:

0.00

currency_code

string, required

The 3-character ISO 4217 currency code.

Allowable Values:

The 3-character ISO 4217 currency code.

"USD" currently supported.

funding_source_token

string, optional

Identifies the funding source to use for this order.

You don’t have to supply a funding source token value in this call if you have a default funding source set up. If you have only one funding source, then this source is used as the default. If you have multiple funding sources and none are configured as the default, then an error is returned.

Allowable Values:

Existing funding source token.

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

funding_source_address_token

string, optional

Identifies the funding source address to use for this offer.

If your funding source is an ACH account, then a funding source address 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:

Existing funding source address token.

Send a GET request to /fundingsources/addresses/user/{token} to retrieve addresses for a specific user.

tags

string, optional

Comma-delimited list of tags describing the order.

Allowable Values:

99 char max

memo

string, optional

Additional descriptive text.

Allowable Values:

255 char max

fees

array of fee_model, optional

Contains attributes that define characteristics of one or more fees.

When more than one fee is assessed, the fees are processed in the order they appear in the array.

Allowable Values:

The fee_model object

Fields Description

token

string, optional

The unique identifier of the fee.

Allowable Values:

Existing fee token.

Send a GET request to /fees to retrieve fee tokens.

memo

string, optional

Additional text that describes the fee transfer.

Allowable Values:

99 char max

tags

string, optional

Comma-delimited list of tags describing the fee.

Allowable Values:

255 char max

Sample request body

{
  "token": "my_gpaorder_01",
  "user_token": "my_user_01",
  "amount": "1000",
  "currency_code": "USD",
  "funding_source_token": "my_program_funding_source_01"
}

Is this helpful?

Sample response body

{
  "token": "my_gpaorder_01",
  "amount": 1000,
  "created_time": "2017-05-10T23:00:15Z",
  "last_modified_time": "2017-05-10T23:00:15Z",
  "transaction_token": "156",
  "state": "COMPLETION",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "funding": {
    "amount": 1000,
    "source": {
      "type": "program",
      "token": "**********e_01",
      "active": true,
      "name": "my_program_funding_source_01",
      "is_default_account": false,
      "created_time": "2017-03-31T19:13:23Z",
      "last_modified_time": "2017-03-31T19:13:23Z"
    }
  },
  "funding_source_token": "**********e_01",
  "user_token": "my_user_01",
  "currency_code": "USD"
}

Is this helpful?

Retrieve GPA order

Action: GET
Endpoint: /gpaorders/{token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to retrieve a GPA order.

URL path parameters

Fields Description

token

string, required

Identifies the GPA order to retrieve.

Allowable Values:

Existing GPA order token.

Send a GET request to /transactions?type=gpa.credit to retrieve GPA order tokens.

Sample response body

{
  "token": "my_gpaorder_01",
  "amount": 1000,
  "created_time": "2017-05-10T23:00:15Z",
  "last_modified_time": "2017-05-10T23:00:15Z",
  "transaction_token": "156",
  "state": "COMPLETION",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "funding": {
    "amount": 1000,
    "source": {
      "type": "program",
      "token": "**********e_01",
      "active": true,
      "name": "my_program_funding_source_01",
      "is_default_account": false,
      "created_time": "2017-03-31T19:13:23Z",
      "last_modified_time": "2017-03-31T19:13:23Z"
    }
  },
  "funding_source_token": "**********e_01",
  "user_token": "my_user_01",
  "currency_code": "USD"
}

Is this helpful?

Unload GPA order

Action: POST
Endpoint: /gpaorders/unloads

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to unload a GPA order.

Unloading a GPA order returns funds to the funding source. A GPA unload must be tied to an original GPA order and can be used to return the amount of the original order or a lesser amount.

Body field details

Fields Description

token

string, optional

The unique identifier of the GPA unload.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other 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:

36 char max

amount

decimal, required

The amount of funds to unload (return to funding source).

Allowable Values:

0.00

original_order_token

string, required

Identifies the original GPA order.

Allowable Values:

Existing GPA order token

tags

string, optional

Comma-delimited list of tags describing the order.

Allowable Values:

99 char max

memo

string, optional

Additional descriptive text.

Allowable Values:

255 char max

Sample request body

{
  "token": "my_unload_01",
  "original_order_token": "my_gpaorder_01",
  "amount": 500
}

Is this helpful?

Sample response body

{
  "token": "my_unload_01",
  "amount": 500,
  "created_time": "2017-05-10T23:14:50Z",
  "last_modified_time": "2017-05-10T23:14:50Z",
  "transaction_token": "158",
  "state": "COMPLETION",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "funding": {
    "amount": 500,
    "source": {
      "type": "program",
      "token": "**********e_01",
      "active": true,
      "name": "my_program_funding_source_01",
      "is_default_account": false,
      "created_time": "2017-03-31T19:13:23Z",
      "last_modified_time": "2017-03-31T19:13:23Z"
    }
  },
  "funding_source_token": "**********e_01",
  "original_order_token": "my_gpaorder_01"
}

Is this helpful?

Retrieve a GPA unload

Action: GET
Endpoint: /gpaorders/unloads/{unload_token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to retrieve a specific GPA unload.

URL path parameters

Fields Description

unload_token

string, required

Identifies the GPA unload to retrieve.

Allowable Values:

Existing GPA unload token.

Send a GET request to /gpaorders/unloads to return GPA unload tokens.

Sample response body

{
  "token": "my_unload_01",
  "amount": 500,
  "created_time": "2017-05-10T23:14:50Z",
  "last_modified_time": "2017-05-10T23:14:50Z",
  "transaction_token": "158",
  "state": "COMPLETION",
  "response": {
    "code": "0000",
    "memo": "Approved or completed successfully"
  },
  "funding": {
    "amount": 500,
    "source": {
      "type": "program",
      "token": "**********e_01",
      "active": true,
      "name": "my_program_funding_source_01",
      "is_default_account": false,
      "created_time": "2017-03-31T19:13:23Z",
      "last_modified_time": "2017-03-31T19:13:23Z"
    }
  },
  "funding_source_token": "**********e_01",
  "original_order_token": "my_gpaorder_01"
}

Is this helpful?

List GPA unloads

Action: GET
Endpoint: /gpaorders/unloads

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to list all GPA unloads or GPA unloads associated with a specific user or business.

This endpoint supports field filtering and pagination.

Query parameters

Fields Description

user_token

string, optional

Identifies the user whose associated GPA unloads you want to list.

Allowable Values:

Existing user token.

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

business_token

string, optional

Identifies the business whose associated GPA unloads you want to list.

Allowable Values:

Existing business token.

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

original_order_token

string, optional

Identifies the original GPA order whose associated GPA unloads you want to list.

Allowable Values:

Existing GPA order token.

Send a GET request to /transactions?type=gpa.credit to retrieve GPA order tokens.

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_unload_01",
      "amount": 500,
      "created_time": "2017-05-10T23:14:50Z",
      "last_modified_time": "2017-05-10T23:14:50Z",
      "transaction_token": "158",
      "state": "COMPLETION",
      "response": {
        "code": "0000",
        "memo": "Approved or completed successfully"
      },
      "funding": {
        "amount": 500,
        "source": {
          "type": "program",
          "token": "**********e_01",
          "active": true,
          "name": "my_program_funding_source_01",
          "is_default_account": false,
          "created_time": "2017-03-31T19:13:23Z",
          "last_modified_time": "2017-03-31T19:13:23Z"
        }
      },
      "funding_source_token": "**********e_01",
      "original_order_token": "my_gpaorder_01"
    },
    {
      "token": "3abe8539-3c61-480d-b015-539fb786a2af",
      "amount": 1000,
      "created_time": "2017-03-27T17:19:24Z",
      "last_modified_time": "2017-03-27T17:19:24Z",
      "transaction_token": "2",
      "state": "COMPLETION",
      "funding": {
        "amount": 1000,
        "source": {
          "type": "program",
          "token": "**********ding",
          "active": true,
          "name": "Marqeta Program Funding",
          "is_default_account": false,
          "created_time": "2017-03-13T22:36:53Z",
          "last_modified_time": "2017-03-13T22:36:53Z"
        }
      },
      "funding_source_token": "**********ding",
      "original_order_token": "b9c48f46-0614-442e-8e91-5ce457851b8d"
    }
  ]
}

Is this helpful?

Create MSA order

Action: POST
Endpoint: /msaorders

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to create an MSA order resource.

As a result of issuing a POST to /msaorders, Marqeta automatically calculates values for balance and available_balance (purchase amount minus any transactions) and includes them in the response object, in addition to the last transaction date.

Body field details

Fields Description

token

string, optional

The unique identifier of the msaorder.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other 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:

36 char max

campaign_token

string, required

The unique identifier of a campaign.

Allowable Values:

Existing campaign token.

Send a GET request to /campaigns to retrieve existing campaign tokens.

user_token

OR

business_token

string, required

Identifies the account holder whose MSA is credited.

Allowable Values:

Existing user or business token.

Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.

currency_code

string, required

The 3-character ISO 4217 currency code.

Allowable Values:

The 3-character ISO 4217 currency code.

"USD" currently supported.

purchase_amount

decimal, required

The amount of the order.

Allowable Values:

0.00

reward_amount

decimal, optional

The amount to be awarded the account holder if the trigger amount is exceeded.

Allowable Values:

0.00

reward_trigger_amount

decimal, optional

The amount the account holder must spend in order to receive the reward amount.

Allowable Values:

0.00

funding_source_token

string, optional

The unique identifier of the funding source to use for this order.

You don’t have to supply a funding source token value in this call if you have a default funding source set up. If you have only one funding source, then this source is used as the default. If you have multiple funding sources and none are configured as the default, then an error is returned.

Allowable Values:

Existing funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve funding sources for a user or to /fundingsources/business/{business_token} to retrieve funding sources for a business.

funding_source_address_token

string, optional

The unique identifier of the funding sources address to use for this offer.

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 an MSA order.

Allowable Values:

Existing funding source address token.

Send a GET request to /fundingsources/addresses/user/{token} to retrieve addresses for a specific user or to /fundingsources/addresses/business/{business_token} to retrieve addresses for a specific business.

start_date

string, optional

The start of the valid date range for the msa order.

The start_date field on the response object always includes the time. If the time is omitted from the request, it defaults to midnight.

Allowable Values:

yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

end_date

string, optional

The end of the valid date range for the msaorder.

The end_date field on the response object always includes the time. If the time is omitted from the request, it defaults to midnight.

Allowable Values:

yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

Sample request body

{
    "campaign_token": "my_campaign_01",
    "user_token": "my_user_01",
    "token": "my_msaorder_test_01",
    "currency_code": "USD",
    "purchase_amount": "100.00",
    "funding_source_token": "my_program_funding_source_01"
}

Is this helpful?

Sample response body

{
  "token": "my_msaorder_test_01",
  "user_token": "my_user_01",
  "order_balances": {
    "currency_code": "USD",
    "ledger_balance": 100,
    "available_balance": 100,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": 100,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 100,
        "available_balance": 100,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": 100
      }
    }
  },
  "purchase_amount": 100,
  "currency_code": "USD",
  "active": true,
  "reward_amount": 0,
  "reward_trigger_amount": 0.01,
  "campaign_token": "my_campaign_01",
  "funding": {
    "amount": 100,
    "source": {
      "type": "program",
      "token": "**********e_01",
      "active": true,
      "name": "my_program_funding_source_01",
      "is_default_account": false,
      "created_time": "2017-03-31T19:13:23Z",
      "last_modified_time": "2017-03-31T19:13:23Z"
    }
  },
  "created_time": "2017-05-10T19:11:24Z",
  "last_modified_time": "2017-05-10T19:11:24Z",
  "aggregated_balances": {
    "currency_code": "USD",
    "ledger_balance": 100,
    "available_balance": 100,
    "credit_balance": 0,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 100,
        "available_balance": 100,
        "credit_balance": 0,
        "pending_credits": 0
      }
    }
  },
  "transaction_token": "152"
}

Is this helpful?

Retrieve MSA order

Action: GET
Endpoint: /msaorders/{token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to retrieve a specific MSA order.

URL path parameters

Fields Description

token

string, required

Identifies the MSA order to retrieve.

Allowable Values:

Existing MSA order token.

Send a GET request to /transactions?type=msa.credit to retrieve MSA order tokens.

Sample response body

{
  "token": "my_msaorder_test_01",
  "user_token": "my_user_01",
  "order_balances": {
    "currency_code": "USD",
    "ledger_balance": 100,
    "available_balance": 100,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": 100,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 100,
        "available_balance": 100,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": 100
      }
    }
  },
  "purchase_amount": 100,
  "currency_code": "USD",
  "active": true,
  "reward_amount": 0,
  "reward_trigger_amount": 0.01,
  "campaign_token": "my_campaign_01",
  "funding": {
    "amount": 100,
    "source": {
      "type": "program",
      "token": "**********e_01",
      "active": true,
      "name": "my_program_funding_source_01",
      "is_default_account": false,
      "created_time": "2017-03-31T19:13:23Z",
      "last_modified_time": "2017-03-31T19:13:23Z"
    }
  },
  "created_time": "2017-05-10T19:11:24Z",
  "last_modified_time": "2017-05-10T19:11:24Z",
  "aggregated_balances": {
    "currency_code": "USD",
    "ledger_balance": 100,
    "available_balance": 100,
    "credit_balance": 0,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 100,
        "available_balance": 100,
        "credit_balance": 0,
        "pending_credits": 0
      }
    }
  },
  "transaction_token": "152"
}

Is this helpful?

Update MSA order

Action: PUT
Endpoint: /msaorders/{token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to update an MSA order. Only values of fields in the request are modified; all others are left unchanged.

URL path parameters

Fields Description

token

string, required

Identifies the MSA order to update.

Allowable Values:

Existing MSA order token.

Send a GET request to /transactions?type=msa.credit to retrieve MSA orders.

Body field details

Fields Description

active

boolean, optional

Determines whether the msa order is active or inactive.

Allowable Values:

true, false;

Default value: true

start_date

string, optional

The start of the valid date range for the MSA order.

The start_date field on the response object always includes the time. If the time is omitted from the request, it defaults to midnight.

Allowable Values:

yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

end_date

string, optional

The end of the valid date range for the MSA order.

The end_date fields on the response object always includes the time. If the time is omitted from the request, it defaults to midnight.

Allowable Values:

yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

Sample request body

{
    "active": false
}

Is this helpful?

Sample response body

{
  "token": "my_msaorder_test_01",
  "user_token": "my_user_01",
  "order_balances": {
    "currency_code": "USD",
    "ledger_balance": 100,
    "available_balance": 100,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": 100,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 100,
        "available_balance": 100,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": 100
      }
    }
  },
  "purchase_amount": 100,
  "currency_code": "USD",
  "active": false,
  "reward_amount": 0,
  "reward_trigger_amount": 0.01,
  "campaign_token": "my_campaign_01",
  "funding": {
    "amount": 100,
    "source": {
      "type": "program",
      "token": "**********e_01",
      "active": true,
      "name": "my_program_funding_source_01",
      "is_default_account": false,
      "created_time": "2017-03-31T19:13:23Z",
      "last_modified_time": "2017-03-31T19:13:23Z"
    }
  },
  "created_time": "2017-05-10T19:11:24Z",
  "last_modified_time": "2017-05-10T23:28:38Z",
  "aggregated_balances": {
    "currency_code": "USD",
    "ledger_balance": 100,
    "available_balance": 100,
    "credit_balance": 0,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 100,
        "available_balance": 100,
        "credit_balance": 0,
        "pending_credits": 0
      }
    }
  },
  "transaction_token": "152"
}

Is this helpful?

Unload MSA order

Action: POST
Endpoint: /msaorders/unloads

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to unload an MSA order.

Body field details

Fields Description

token

string, optional

The unique identifier of the MSA order unload.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other 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:

36 char max

amount

decimal, required

Specifies the amount of the MSA order to unload.

Allowable Values:

0.00

Must be less than or equal to the amount of the order.

original_order_token

string, required

Identifies the MSA order to unload.

Allowable Values:

Existing MSA order token.

Send a GET request to /transactions?type=msa.credit to retrieve MSA orders.

tags

string, optional

Comma-delimited list of tags describing the MSA order unload.

Allowable Values:

255 char max

memo

string, optional

Memo or note describing the MSA order unload.

Allowable Values:

255 char max

Sample request body

{
  "token": "my_msaunload_01",
  "amount": "3.00",
  "original_order_token": "my_msaorder_test_01"
}

Is this helpful?

Sample response body

{
  "token": "my_msaunload_01",
  "user_token": "my_user_01",
  "order_balances": {
    "currency_code": "USD",
    "ledger_balance": 97,
    "available_balance": 97,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": -3
  },
  "amount": 3,
  "currency_code": "USD",
  "active": true,
  "campaign_token": "my_campaign_01",
  "created_time": "2017-05-10T23:32:59Z",
  "last_modified_time": "2017-05-10T23:32:59Z",
  "aggregated_balances": {
    "currency_code": "USD",
    "ledger_balance": 97,
    "available_balance": 97,
    "credit_balance": 0,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 97,
        "available_balance": 97,
        "credit_balance": 0,
        "pending_credits": 0
      }
    }
  },
  "original_order_token": "my_msaorder_test_01",
  "transaction_token": "159"
}

Is this helpful?

Retrieve MSA unload

Action: GET
Endpoint: /msaorders/unloads/{unload_token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to retrieve a specific MSA order unload.

URL path parameters

Fields Description

unload_token

string, required

Identifies the MSA order unload to retrieve.

Allowable Values:

Existing MSA order unload token.

Send a GET request to /msaorders/unloads to retrieve MSA order unload tokens.

Sample response body

{
  "token": "my_msaunload_01",
  "user_token": "my_user_01",
  "order_balances": {
    "currency_code": "USD",
    "ledger_balance": 97,
    "available_balance": 97,
    "credit_balance": 0,
    "pending_credits": 0,
    "impacted_amount": -3
  },
  "amount": 3,
  "currency_code": "USD",
  "active": true,
  "campaign_token": "my_campaign_01",
  "created_time": "2017-05-10T23:32:59Z",
  "last_modified_time": "2017-05-10T23:32:59Z",
  "aggregated_balances": {
    "currency_code": "USD",
    "ledger_balance": 97,
    "available_balance": 97,
    "credit_balance": 0,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 97,
        "available_balance": 97,
        "credit_balance": 0,
        "pending_credits": 0
      }
    }
  },
  "original_order_token": "my_msaorder_test_01",
  "transaction_token": "159"
}

Is this helpful?

List MSA unloads

Action: GET
Endpoint: /msaorders/unloads

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to list all MSA order unloads or MSA order unloads associated with a specific user or business.

To narrow your result set to unloads associated with a particular account holder or MSA order, include the appropriate parameters from the following Query Parameters table. This endpoint also supports query parameters for field filtering, pagination, and sorting.

Query parameters

Fields Description

user_token

string, optional

Identifies the user whose associated MSA unloads you want to list.

Allowable Values:

Existing user token.

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

business_token

string, optional

Identifies the business whose associated MSA unloads you want to list.

Allowable Values:

Existing business token.

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

original_order_token

string, optional

Identifies the original MSA order whose associated GPA unloads you want to list.

Allowable Values:

Existing MSA order token.

Send a GET request to /transactions?type=msa.credit to retrieve MSA orders.

Sample response body

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "my_msaunload_01",
      "user_token": "my_user_01",
      "order_balances": {
        "currency_code": "USD",
        "ledger_balance": 97,
        "available_balance": 97,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": -3
      },
      "amount": 3,
      "currency_code": "USD",
      "active": true,
      "campaign_token": "my_campaign_01",
      "created_time": "2017-05-10T23:32:59Z",
      "last_modified_time": "2017-05-10T23:32:59Z",
      "aggregated_balances": {
        "currency_code": "USD",
        "ledger_balance": 97,
        "available_balance": 97,
        "credit_balance": 0,
        "pending_credits": 0,
        "balances": {
          "USD": {
            "currency_code": "USD",
            "ledger_balance": 97,
            "available_balance": 97,
            "credit_balance": 0,
            "pending_credits": 0
          }
        }
      },
      "original_order_token": "my_msaorder_test_01",
      "transaction_token": "159"
    }
  ]
}

Is this helpful?

Create offer order

Action: POST
Endpoint: /offerorders

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to create an offer order.

Body field details

Fields Description

token

string, optional

The unique identifier of the offer order.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other 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:

36 char max

user_token

OR

business_token

string, required

Identifies the account holder whose MSA will be credited.

Allowable Values:

Existing user or business token.

Send a GET request to /users to retreive user tokens or to /businesses to retrieve business tokens.

offer_token

string, required

Identifies the offer funded by this order.

Allowable Values:

Existing offer token.

Send a GET request to /offers to retrieve offer tokens.

funding_source_token

string, optional

The unique identifier of the funding source to use for this order.

You must have at least one funding source in order to create an order. You don’t have to supply a funding_source_token value in this call if you have a default funding source set up. If you have only one funding source, then this source is used as the default. If you have multiple funding sources and none are configured as the default, then an error is returned.

Allowable Values:

Existing funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve funding sources for a specific user or to /fundingsources/business/{business_token} to retrieve retrieve funding sources for a specific business.

funding_source_address_token

string, optional

The unique identifier of the funding sources address to use for this offer.

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 an offer order. If you have multiple funding source addresses and none are configured as the default, then an error is returned.

Allowable Values:

Existing funding source address token.

Send a GET request to /fundingsources/addresses/user/{token} to retrieve addresses for a specific user or to /fundingsources/addresses/business/{business_token} to retrieve addresses for a specific business.

Sample request body

{
  "token": "my_offerorder_0100",
  "user_token": "my_user_01",
  "offer_token": "may_offer",
  "funding_source_token": "my_program_funding_source_01"
}

Is this helpful?

Sample response body

{
  "created_time": "2017-05-10T23:49:14Z",
  "last_modified_time": "2017-05-10T23:49:14Z",
  "user_token": "my_user_01",
  "token": "my_offerorder_0100",
  "order_balances": {
    "currency_code": "USD",
    "ledger_balance": 200,
    "available_balance": 250,
    "credit_balance": 50,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 200,
        "available_balance": 250,
        "credit_balance": 50,
        "pending_credits": 0
      }
    }
  },
  "order_aggregated_balances": {
    "currency_code": "USD",
    "ledger_balance": 297,
    "available_balance": 347,
    "credit_balance": 50,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 297,
        "available_balance": 347,
        "credit_balance": 50,
        "pending_credits": 0
      }
    }
  },
  "offer": {
    "token": "may_offer",
    "active": true,
    "name": "May_offer",
    "purchase_amount": 200,
    "reward_amount": 50,
    "reward_trigger_amount": 200,
    "campaign_token": "my_campaign_01",
    "currency_code": "840",
    "created_time": "2017-05-10T23:46:44Z",
    "last_modified_time": "2017-05-10T23:46:44Z"
  }
}

Is this helpful?

Retrieve offer order

Action: GET
Endpoint: /offerorders/{token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to retrieve a specific offer order.

URL path parameters

Fields Description

token

string, required

Identifies the offer order to retrieve.

Allowable Values:

Existing offer order token

Sample response body

{
  "created_time": "2017-05-10T23:49:14Z",
  "last_modified_time": "2017-05-10T23:49:14Z",
  "user_token": "my_user_01",
  "token": "my_offerorder_0100",
  "order_balances": {
    "currency_code": "USD",
    "ledger_balance": 200,
    "available_balance": 250,
    "credit_balance": 50,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 200,
        "available_balance": 250,
        "credit_balance": 50,
        "pending_credits": 0
      }
    }
  },
  "order_aggregated_balances": {
    "currency_code": "USD",
    "ledger_balance": 297,
    "available_balance": 347,
    "credit_balance": 50,
    "pending_credits": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 297,
        "available_balance": 347,
        "credit_balance": 50,
        "pending_credits": 0
      }
    }
  },
  "offer": {
    "token": "my_offer",
    "active": true,
    "name": "May_offer",
    "purchase_amount": 200,
    "reward_amount": 50,
    "reward_trigger_amount": 200,
    "campaign_token": "my_campaign_01",
    "currency_code": "840",
    "created_time": "2017-05-10T23:46:44Z",
    "last_modified_time": "2017-05-10T23:46:44Z"
  }
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.