Preview or approve monthly renewal permission

POST

/v1/connections/{id}/monthly-renewal

const url = 'https://api.infiniteaudience.ai/v1/connections/example/monthly-renewal';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"action":"preview","selected_fields":["example"],"max_records_per_month":1,"max_charge_cents_per_month":1,"expires_at":"2026-04-15T12:00:00Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.infiniteaudience.ai/v1/connections/example/monthly-renewal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "action": "preview", "selected_fields": [ "example" ], "max_records_per_month": 1, "max_charge_cents_per_month": 1, "expires_at": "2026-04-15T12:00:00Z" }'

Requires ‘creator’ scope. Requires an owner or admin. Preview does not purchase. Approval binds selected attributes, monthly record/spending limits and current organization billing terms. A stable request ID makes retries safe. Paid scheduling remains subject to rollout availability.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

Organization-owned HubSpot or Klaviyo connection ID.

Request Body^required

application/json

One of:

object
object

object

action

required

string

Allowed value: preview

selected_fields

required

Array<string>

>= 1 items

max_records_per_month

required

integer

>= 1 <= 100000000

max_charge_cents_per_month

required

integer

>= 1

expires_at

string | null format: date-time

Responses

200

Current renewal permission or a non-purchasing preview.

application/json

One of:

object
object

object

authorization

required

One of:

object
null

object

version

required

integer

Allowed value: 1

org_id

required

string

provider

required

string

Allowed values: shopify hubspot klaviyo

connection_id

required

Numeric shop ID for Shopify; provider-prefixed connection ID for HubSpot/Klaviyo.

string

revision

required

string

enabled

required

boolean

scope

required

string

Allowed value: known_expired_connection_identities

selected_fields

required

Array<string>

>= 1 items

max_records_per_month

required

integer

>= 1 <= 100000000

max_charge_cents_per_month

required

integer

>= 1

expires_at

required

string | null format: date-time

currency

required

string

billing_terms_fingerprint

required

string

approved_by

required

string

approved_at

required

string format: date-time

revoked_by

required

string | null

revoked_at

required

string | null format: date-time

Example

{
  "authorization": {
    "version": 1,
    "provider": "shopify",
    "scope": "known_expired_connection_identities"
  }
}

400

Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

validation_error

{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

401

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

missing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the creator scope."
}

404

Resource not found or not accessible to the calling org.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

not_found

{
  "error": "Audience not found"
}

409

Resource state conflicts with the request. For upload analysis this includes FILE_NOT_YET_UPLOADED.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "INVALID_FILTER_SHAPE"
    }
  ]
}

503

A required billing provider partnership is temporarily unavailable.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "INVALID_FILTER_SHAPE"
    }
  ]
}

Preview or approve monthly renewal permission

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

Example

400

Examples

401

Examples

403

Examples

404

Examples

409

Example

503

Example

Request Body^required