Billing

3 operations in the Adverity Connect API. Replace {{INSTANCE}} and {{KEY}} in the examples with your instance and API key. How authentication works.

List billing objects export

GET/api/billing-objects/export/

API key permissionAuthorization: Read-onlyauthorization:read

Query parameters

formatstring
Selects how an error is rendered. A successful export is always CSV.
One of csv json

Responses

200A CSV file with one row per granted billing object, across every connection you can access. Granted means the object has not been removed and the external grantor (the person who authorized the connection) has granted access to it. For connectors with account hierarchies, every level is a row. The list is flat: no search, ordering or paging. Three cases differ: - Some connectors leave out billing objects that are not billed themselves, such as Google Ads manager (MCC) accounts. - A connection whose connector is not billed per billing object gets one row of its own: the connection name in `Billing Object`, and `Status` `Active`. - A billed connection with no granted billing objects gets no row. Columns: `Workspace`, `Authorization`, `Billing Object`, then the columns of the exported connectors, then `Date Added` and `Date Updated` (`YYYY-MM-DD`) and `Status` (`Active` or `Inactive`).text/csv

Response schema

string

Get billings

GET/api/billings/{id}/

API key permissionAuthorization: Read-onlyauthorization:read

Path parameters

idintegerrequired
The connection id.

Query parameters

orderingstring
Comma-separated created and id; a - prefix sorts descending.
pageinteger
The page number; only used with page_size.
page_sizeinteger
Enables pagination. Without it, all rows are returned.

Responses

200The connection's billing objects that are granted (for a grantor, all visible ones). For connectors with account hierarchies, only the top level; some connectors nest the descendants under `children`.application/json

Response schema

object BillingObjectList

countinteger
Only with page_size.
nextstring · urinullable
Only with page_size.
previousstring · urinullable
Only with page_size.
dataarray of objectrequired
Items · BillingObject
- idintegerrequired
- createdstring · date-timerequirednullable
  Null for manager (MCC) accounts of Google Ads, Keyword Planner, Local Services Ads and the deprecated Google Adwords connector.
- selectablebooleanrequired
  False if the object cannot be switched on or off by itself: an ancestor that is switched on (or, for a grantor, granted) with its descendants locks it, or the connector does not allow selecting it, such as manager accounts of the deprecated Google Adwords connector.
- _metaobjectrequired
  Attributes · BillingObjectMeta
  - urlstring
    A link to the object, if the connector has one. Never sent to a grantor.
- updatedstring · date-timenullable
  Only included with extra info: always on GET /api/billings/{id}/, on PATCH only with add_extra_info=1. Null for manager (MCC) accounts of Google Ads, Keyword Planner, Local Services Ads and the deprecated Google Adwords connector.
- statusone of
  Only included with extra info: always on GET /api/billings/{id}/, on PATCH only with add_extra_info=1. Whether the object is switched on, or, for an external grantor, whether it is granted. An object locked on by a switched-on ancestor is Active. Null only for manager accounts of the deprecated Google Adwords connector.
  - Active - Active
  - Inactive - Inactive
  Attributes
  - BillingObjectStatusEnum
  - NullEnum
- childrenarray of object
  The billing objects one level below this one. Only sent by connectors that nest their hierarchy, such as Google Ads, Keyword Planner, Local Services Ads, the deprecated Google Adwords connector and NoCode connectors; can be empty.
  Recursive: see BillingObject above.
columnsarray of object
Omitted, with empty data, while a reauthorizing grantor waits for the metadata update.
Items · BillingObjectColumn
- namestringrequired
- labelstringrequired
- dataTypestringrequired
  string, unless the connector maps the field to a type such as date.
- isLinkbooleanrequired

Update billings

PATCH/api/billings/{id}/

API key permissionAuthorization: Writeauthorization:write

Path parameters

idintegerrequired
The connection id.

Query parameters

add_extra_infostring
1 adds status and updated to every object.

Request body

application/json

Body schema

object PatchedBillingObjectsUpdateRequest

objectsarray of object
The billing objects to switch on or off. Only granted objects are changed; others are ignored silently. For a grantor this changes the grant instead. Unless enable_all_billing_objects is true, every billing object of the connection that is not listed is switched off, except descendants locked by a switched-on ancestor; an empty or missing list then switches everything off. For a grantor, unlisted objects keep their grant and lose only the on/off flag (except while reauthorizing the connection).
Items · BillingObjectUpdate
- idintegerrequired
- is_enabledbooleanrequired
isInitialboolean
Switches every billing object of the connection off before the rest of the request is applied. For an external grantor this also withdraws all grants. Ignored while a grantor reauthorizes the connection.
enable_all_billing_objectsbooleannullable
Turn the connection's setting that enables all billing objects on or off (for an external grantor: that grants them). Null or omitted leaves it unchanged.

Responses

200The listed billing objects whose state this request changed: their on/off flag, for a grantor their grant, or for a hierarchy root its "with descendants" flag. Not included: listed objects already in the requested state, objects locked by an ancestor, objects not part of the connection or not granted, unlisted objects that were switched off, and ancestors or descendants changed as a side effect. Exceptions: with `isInitial`, a listed object that was already on is returned; with `enable_all_billing_objects: true`, listed objects that "enable all" switched on are not. `updated` and `status` are included only with `add_extra_info=1`.application/json

Response schema

array of object

idintegerrequired
createdstring · date-timerequirednullable
Null for manager (MCC) accounts of Google Ads, Keyword Planner, Local Services Ads and the deprecated Google Adwords connector.
selectablebooleanrequired
False if the object cannot be switched on or off by itself: an ancestor that is switched on (or, for a grantor, granted) with its descendants locks it, or the connector does not allow selecting it, such as manager accounts of the deprecated Google Adwords connector.
_metaobjectrequired
Attributes · BillingObjectMeta
- urlstring
  A link to the object, if the connector has one. Never sent to a grantor.
updatedstring · date-timenullable
Only included with extra info: always on GET /api/billings/{id}/, on PATCH only with add_extra_info=1. Null for manager (MCC) accounts of Google Ads, Keyword Planner, Local Services Ads and the deprecated Google Adwords connector.
statusone of
Only included with extra info: always on GET /api/billings/{id}/, on PATCH only with add_extra_info=1. Whether the object is switched on, or, for an external grantor, whether it is granted. An object locked on by a switched-on ancestor is Active. Null only for manager accounts of the deprecated Google Adwords connector.
- Active - Active
- Inactive - Inactive
Attributes
- BillingObjectStatusEnum
- NullEnum
childrenarray of object
The billing objects one level below this one. Only sent by connectors that nest their hierarchy, such as Google Ads, Keyword Planner, Local Services Ads, the deprecated Google Adwords connector and NoCode connectors; can be empty.
Items · BillingObject
- idintegerrequired
- createdstring · date-timerequirednullable
  Null for manager (MCC) accounts of Google Ads, Keyword Planner, Local Services Ads and the deprecated Google Adwords connector.
- selectablebooleanrequired
  False if the object cannot be switched on or off by itself: an ancestor that is switched on (or, for a grantor, granted) with its descendants locks it, or the connector does not allow selecting it, such as manager accounts of the deprecated Google Adwords connector.
- _metaobjectrequired
  Attributes · BillingObjectMeta
  - urlstring
    A link to the object, if the connector has one. Never sent to a grantor.
- updatedstring · date-timenullable
  Only included with extra info: always on GET /api/billings/{id}/, on PATCH only with add_extra_info=1. Null for manager (MCC) accounts of Google Ads, Keyword Planner, Local Services Ads and the deprecated Google Adwords connector.
- statusone of
  Only included with extra info: always on GET /api/billings/{id}/, on PATCH only with add_extra_info=1. Whether the object is switched on, or, for an external grantor, whether it is granted. An object locked on by a switched-on ancestor is Active. Null only for manager accounts of the deprecated Google Adwords connector.
  - Active - Active
  - Inactive - Inactive
  Attributes
  - BillingObjectStatusEnum
  - NullEnum
- childrenarray of object
  The billing objects one level below this one. Only sent by connectors that nest their hierarchy, such as Google Ads, Keyword Planner, Local Services Ads, the deprecated Google Adwords connector and NoCode connectors; can be empty.
  Recursive: see BillingObject above.