Funding Instruments

Funding Instruments are the source of campaign budget. Funding Instruments can not be created via the Ads API, they have to be already established by the advertiser’s account manager at Twitter (for credit lines) or via ads.twitter.com (for credit cards) to be available.

To get a list of all funding_instruments on an account, see GET accounts/:account_id/funding_instruments and GET accounts/:account_id/funding_instruments/:funding_instrument_id for the details of a specific one.

Funding Instrument Attributes

Descriptive: account_id, funding instrument id, funding instrument typedescription, and io_header(insertion order header ID). Note that a single io_header may be associated with multiple funding instruments.

Funding ability: able_to_fund and reasons_not_able_to_fund.

Time: created_atupdated_atstart_time, and end_time represented by a string, formatted as “%Y-%m-%dT%l:%M:%S%z”.

Boolean status: pauseddeleted, and cancelled (true or false).

Financial: currency (ISO-4217 format), credit_limit_local_microcredit_remaining_local_micro, and funded_amount_local_micro. The value of a currency is represented in micros. For USD, $5.50 is encoded as 5.50*1e6, or 5,500,000. To represent a “whole value”, you need to multiply the local micro by 1e6 (1_000_000) for all currencies.

Attribute Details

credit_limit_local_micro is only valid for CREDIT_CARD or CREDIT_LINE type funding instruments and represents the credit limit for that instrument.

funded_amount_local_micro is only valid for INSERTION_ORDER type funding instruments and represents the allocated budget.

credit_remaining_local_micro is valid for CREDIT_LINE and AGENCY_CREDIT_LINE type funding instruments. It represents the credit_limit_local_micro minus the amount already spent on that funding instrument. It does not represent the difference between funded_amount_local_micro and the amount spent. We draw a distinction between credit limit and funded amount because they represent different underlying funding methods and spending agreements we have with advertisers.

Types of Funding Instruments

Credit Cards

Typically used by self-serve advertisers (without an account manager).

Credit Lines

These are in the form of insertion orders (IOs) and are set by account managers.

Multi-Handle Credit Lines

Advertisers can fund campaigns across multiple handles with this type of credit line. This feature is enabled by their Twitter Account Manager, associating the different @handles to a specific credit line.

For example, @NikeSB and @NikeFuel can both have access to the @Nike credit line. This funding instrument is available just like any other. You retrieve the data by submitting a GET request to the funding_instrument endpoint. Here is a sample response (note the CREDIT_LINE type).

  GET https://ads-api.twitter.com/5/accounts/a0b1c3/funding_instruments

{
    "request": {
        "params": {
            "account_id": "a0b1c3"
        }
    },
    "data": [
        {
            "start_time": "2013-05-30T04:00:00Z",
            "description": "FakeNike - Credit Line",
            "credit_limit_local_micro": 150000000000,
            "end_time": null,
            "cancelled": false,
            "id": "i1234",
            "paused": false,
            "account_id": "a0b1c3",
            "reasons_not_able_to_fund": [],
            "io_header": null,
            "currency": "USD",
            "funded_amount_local_micro": 0,
            "created_at": "2013-05-30T18:16:38Z",
            "type": "CREDIT_LINE",
            "able_to_fund": true,
            "updated_at": "2013-05-30T18:16:38Z",
            "credit_remaining_local_micro": 123661919751,
            "deleted": false,
        }
    ],
    "data_type": "funding_instrument",
    "total_count": 1,
    "next_cursor": null
}

The only thing particular about this funding instrument is the type and the fact that it is available to all the accounts that were associated to it. Of course, the remaining credit is impacted by all campaigns funded by this instrument, across all accounts sharing it. The details of what accounts are associated to a specific credit line are not available via the API (nor via ads.twitter.com).

For more information on Funding Instrument enumerations, please click here.