Campaign management

Funding Instruments

Run in Postman ❯ 

GET accounts/:account_id/funding_instruments

Retrieve details for some or all funding instruments associated with the current account.

Resource URL

https://ads-api.twitter.com/9/accounts/:account_id/funding_instruments

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
count
optional

Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional

Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
funding_instrument_ids
optional

Scope the response to just the desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: lygyi
sort_by
optional

Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional

Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/9/accounts/18ce54d4x5t/funding_instruments

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "start_time": "2016-07-22T04:24:04Z",
      "description": "Visa ending in 0650",
      "credit_limit_local_micro": 200000000,
      "end_time": null,
      "id": "lygyi",
      "entity_status": "ACTIVE",
      "account_id": "18ce54d4x5t",
      "reasons_not_able_to_fund": [],
      "io_header": null,
      "currency": "USD",
      "funded_amount_local_micro": 645940000,
      "created_at": "2016-07-22T04:24:04Z",
      "type": "CREDIT_CARD",
      "able_to_fund": true,
      "updated_at": "2017-04-05T00:25:13Z",
      "credit_remaining_local_micro": null,
      "deleted": false
    }
  ]
}

GET accounts/:account_id/funding_instruments/:funding_instrument_id

Retrieve a specific funding instrument associated with the current account.

Resource URL

https://ads-api.twitter.com/9/accounts/:account_id/funding_instruments/:id

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
funding_instrument_id
required

A reference to the funding instrument you are operating with in the request.

Type: string

Example: lygyi
with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/9/accounts/18ce54d4x5t/funding_instruments/lygyi

Example Response

{
  "request": {
    "params": {
      "funding_instrument_id": "lygyi",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "start_time": "2016-07-22T04:24:04Z",
    "description": "Visa ending in 0650",
    "credit_limit_local_micro": 200000000,
    "end_time": null,
    "id": "lygyi",
    "entity_status": "ACTIVE",
    "account_id": "18ce54d4x5t",
    "reasons_not_able_to_fund": [],
    "io_header": null,
    "currency": "USD",
    "funded_amount_local_micro": 645940000,
    "created_at": "2016-07-22T04:24:04Z",
    "type": "CREDIT_CARD",
    "able_to_fund": true,
    "updated_at": "2017-04-05T00:25:13Z",
    "credit_remaining_local_micro": null,
    "deleted": false
  }
}

POST accounts/:account_id/funding_instruments

SANDBOX ONLY

Create a funding instrument in the sandbox environment.

There is no risk of incurring costs while using a sandbox funding instrument.

Resource URL

https://ads-api-sandbox.twitter.com/9/accounts/:account_id/funding_instruments

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: gq1844
currency
required

The currency, expressed in ISO-4217.

Type: string

Example: USD
start_time
required

The date for the funding instrument to become active and usable, expressed in ISO 8601.

Type: string

Example: 2017-05-19T07:00:00Z
type
required

The type of funding instrument to create.

Type: enum

Possible values: AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED
end_time
sometimes required

The date for the funding instrument to become inactive, expressed in ISO 8601.

Type: string

Example: 2017-05-26T07:00:00Z
credit_limit_local_micro
optional

The total credit available against this funding instrument.

Note: Only applicable to some funding instrument types.

Type: long

Example: 37500000
funded_amount_local_micro
optional

The total budget amount allocated to this funding instrument.

Note: Only applicable to some funding instrument types.

Type: long

Example: 37500000

Example Request

POST https://ads-api-sandbox.twitter.com/9/accounts/gq1844/funding_instruments?currency=USD&start_time=2017-07-10T00:00:00Z&type=INSERTION_ORDER&end_time=2018-01-10T00:00:00Z&funded_amount_local_micro=140000000000

Example Response

{
  "data": {
    "start_time": "2017-07-10T00:00:00Z",
    "description": "(no payment method has been set up yet)",
    "credit_limit_local_micro": null,
    "end_time": "2018-01-10T00:00:00Z",
    "id": "hxtet",
    "entity_status": "ACTIVE",
    "account_id": "gq1844",
    "reasons_not_able_to_fund": [],
    "io_header": null,
    "currency": "USD",
    "funded_amount_local_micro": 140000000000,
    "created_at": "2017-09-09T05:23:28Z",
    "type": "INSERTION_ORDER",
    "able_to_fund": true,
    "updated_at": "2017-09-09T05:23:28Z",
    "credit_remaining_local_micro": null,
    "deleted": false
  },
  "request": {
    "params": {
      "start_time": "2017-07-10T00:00:00Z",
      "end_time": "2018-01-10T00:00:00Z",
      "account_id": "gq1844",
      "currency": "USD",
      "funded_amount_local_micro": 140000000000,
      "type": "INSERTION_ORDER"
    }
  }
}

PUT accounts/:account_id/funding_instruments/:funding_instrument_id

Update the specified partner managed funding instrument, belonging to the current account and current partner application ID. See Partner Managed Funding Instruments for more details on these types of funding instruments.

PMFI specific error codes:

  • FUNDING_INSTRUMENT_EXCEEDS_AVAILABLE_CREDIT_LIMIT
  • FUNDING_INSTRUMENT_ACCESS_NOT_ALLOWED
  • FUNDING_INSTRUMENT_NOT_FOUND
  • FUNDING_INSTRUMENT_SPEND_EXCEED_FUNDED_AMOUNT

Resource URL

https://ads-api.twitter.com/9/accounts/:account_id/funding_instruments/:funding_instrument_id

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: hkk5
funding_instrument_id
required

A reference to the funding instrument you are operating with in the request.

Type: string

Exampple: hw6ie
funded_amount_local_micro
optional

The total budget amount allocated to this funding instrument.

Type: long

Example: 37500000
paused
optional

Whether this funding instrument should be paused.

Type: boolean

Possible values: false, true

Example Request

PUT https://ads-api.twitter.com/9/accounts/hkk5/funding_instruments/hw6ie?funded_amount_local_micro=1000000000

Example Response

{
  "data": {
    "end_time": null,
    "created_at": "2012-11-08T02:31:46Z",
    "updated_at": "2012-11-20T23:20:35Z",
    "account_id": "hkk5",
    "id": "hw6ie",
    "entity_status": "ACTIVE",
    "deleted": false
    "type": "RESELLER",
    "credit_limit_local_micro": null,
    "funded_amount_local_micro": 1000000000,
    "currency": "USD",
    "description": "CustomerName funding instrument",
    "start_time": "2012-11-08T02:31:46",
    "serving_status": "ACTIVE"

  },
  "request": {
    "params": {
      "account_id": "hkk5",
      "funding_instrument_id": "hw6ie",
      "funded_amount_local_micro": 1000000000
    }
  }
}

DELETE accounts/:account_id/funding_instruments/:funding_instrument_id

SANDBOX ONLY

Delete a funding instrument in the sandbox environment.

Resource URL

https://ads-api-sandbox.twitter.com/9/accounts/:account_id/funding_instruments/:funding_instrument_id

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: gq1844
funding_instrument_id
required

A reference to the funding instrument you are operating with in the request.

Type: string

Exampple: hxt82

Example Request

DELETE https://ads-api-sandbox.twitter.com/9/accounts/gq1844/funding_instruments/hxt82

Example Response

{
  "data": {
    "start_time": "2017-08-30T19:23:47Z",
    "description": "(no payment method has been set up yet)",
    "credit_limit_local_micro": 500000000,
    "end_time": null,
    "id": "hxt82",
    "entity_status": "ACTIVE",
    "account_id": "gq1844",
    "reasons_not_able_to_fund": [
      "DELETED"
    ],
    "io_header": null,
    "currency": "USD",
    "funded_amount_local_micro": null,
    "created_at": "2017-08-30T19:23:47Z",
    "type": "CREDIT_CARD",
    "able_to_fund": false,
    "updated_at": "2017-09-09T02:08:30Z",
    "credit_remaining_local_micro": null,
    "deleted": true
  },
  "request": {
    "params": {
      "funding_instrument_id": "hxt82",
      "account_id": "gq1844"
    }
  }
}
Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.