Retry forwarding an approved media buy

curl --request POST \
  --url https://api.interchange.io/api/v2/storefront/media-buy-approvals/{mediaBuyId}/retry-forward \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "forceTerminal": false
}
'

import requests

url = "https://api.interchange.io/api/v2/storefront/media-buy-approvals/{mediaBuyId}/retry-forward"

payload = { "forceTerminal": False }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({forceTerminal: false})
};

fetch('https://api.interchange.io/api/v2/storefront/media-buy-approvals/{mediaBuyId}/retry-forward', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "42",
  "kind": "create",
  "storefrontId": "1234",
  "mediaBuyId": "<string>",
  "buyerCustomerId": 0,
  "submittedPayload": "<unknown>",
  "reviewedBy": "<string>",
  "reviewedAt": "2023-11-07T05:31:56Z",
  "reviewerNotes": "<string>",
  "forwardedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "forwardResult": [
    {
      "sourceId": "<string>",
      "status": "<string>",
      "upstreamMediaBuyId": "<string>"
    }
  ]
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

Storefront

Retry forwarding an approved media buy

Re-attempt the upstream forward for an already-approved media buy whose previous forward did not complete. Idempotent: the storefront reuses the same idempotency key, so a source that already received the buy is not double-booked. Returns the approval-queue entry with its refreshed forwarding state. A buy terminalized by a structural failure is recoverable in place with forceTerminal: true, which re-forwards it under the same mediaBuyId and keeps the original approval — the request is refused unless every persisted source route is a failed, unsent leg, so a forced retry cannot duplicate an upstream buy.

POST

media-buy-approvals

{mediaBuyId}

retry-forward

Retry forwarding an approved media buy

curl --request POST \
  --url https://api.interchange.io/api/v2/storefront/media-buy-approvals/{mediaBuyId}/retry-forward \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "forceTerminal": false
}
'

import requests

url = "https://api.interchange.io/api/v2/storefront/media-buy-approvals/{mediaBuyId}/retry-forward"

payload = { "forceTerminal": False }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({forceTerminal: false})
};

fetch('https://api.interchange.io/api/v2/storefront/media-buy-approvals/{mediaBuyId}/retry-forward', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "42",
  "kind": "create",
  "storefrontId": "1234",
  "mediaBuyId": "<string>",
  "buyerCustomerId": 0,
  "submittedPayload": "<unknown>",
  "reviewedBy": "<string>",
  "reviewedAt": "2023-11-07T05:31:56Z",
  "reviewerNotes": "<string>",
  "forwardedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "forwardResult": [
    {
      "sourceId": "<string>",
      "status": "<string>",
      "upstreamMediaBuyId": "<string>"
    }
  ]
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

API key or access token

Path Parameters

mediaBuyId

string

required

Buyer-supplied media buy identifier (AdCP media_buy_id).

Minimum string length: 1

Body

application/json

Request body for retrying forwarding. The terminal override is an operator recovery control and is guarded against duplicate upstream writes.

forceTerminal

boolean

default:false

Allow retrying an incorrectly terminalized approval only when every persisted source route is a failed, unsent leg. The request is rejected if any source has an upstream media-buy or task id.

reason

string

Why this retry is being made — recorded against the attempt so a later reviewer can tell a considered recovery from a reflexive one. Strongly recommended with forceTerminal, which overrides a terminal state in front of an ad server.

Required string length: 1 - 500

Example:

"Dimension-derivation fix shipped in v4.118.0; GAM order absent."

Response

Retry forwarding an approved media buy

An approval-queue entry returned from a retry-forward attempt, carrying the outcome of the dispatch when one ran.

string

required

Surrogate id of the approval row (BIGINT serialized as string).

Example:

"42"

kind

enum<string>

default:create

required

Approval workstream kind. create is an initial create_media_buy approval; update is a material update_media_buy approval for an already-created buy.

Available options:

create,

update

storefrontId

string

required

Storefront the pending buy was submitted to (BIGINT serialized as string).

Example:

"1234"

mediaBuyId

string

required

Buyer-supplied media buy identifier (AdCP media_buy_id). Unique per storefront — re-submitting the same id is idempotent.

buyerCustomerId

integer

required

Customer id of the buyer who submitted the media buy.

Required range: -9007199254740991 <= x <= 9007199254740991

submittedPayload

any

required

Raw AdCP create_media_buy payload as the buyer submitted it, with buyer webhook credentials (push_notification_config / pushNotificationConfig) removed before it reaches operator-facing responses. Not normalized — the operator UI renders a summary directly from this object.

status

enum<string>

required

Lifecycle state. pending until the operator decides; approved once the operator accepts (forwarding upstream happens out-of-band and is reflected by forwardedAt); rejected when the operator declines; revoked for buyer- or system-initiated cancellation after a decision.

Available options:

pending,

approved,

rejected,

revoked

reviewedBy

string | null

required

User id of the operator who recorded the decision (BIGINT serialized as string). Null while pending.

reviewedAt

string<date-time> | null

required

When the operator decision was recorded (ISO 8601). Null while pending.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

reviewerNotes

string | null

required

Operator note attached to the decision. Null while pending.

forwardedAt

string<date-time> | null

required

When forwarding to the underlying sales agent settled (ISO 8601) — stamped both when every source accepted the buy and when the forward was terminalized, because the stamp is also what stops the background worker re-attempting a dead forward. Null means the forward has not been attempted or is still in flight. Read it with the per-source legs to tell a delivered buy from a refused one: a delivered buy carries an upstreamMediaBuyId.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

createdAt

string<date-time>

required

When the buyer submitted the media buy (ISO 8601).

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

updatedAt

string<date-time>

required

When the row was last modified — submission, decision, or forwarding stamp (ISO 8601).

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

forwardOutcome

enum<string>

Result of the dispatch this call triggered. deferred means the retry was accepted and is running asynchronously — poll GET /media-buy-approvals/{mediaBuyId} for the settled result. Absent when no dispatch ran.

Available options:

deferred,

all_completed,

all_submitted,

partial,

all_failed,

precondition_failed

forwardResult

object[]

Per-source forwarding legs for this dispatch. Empty while forwardOutcome is deferred.

Show child attributes

⌘I