Push a merchant's daily ad spend

POST/api/v1/credit/ad-spend

Name the merchant as on POST /credit/bank-feeds (program_id and external_merchant_id, or credit_line_id); DayZero uses its business, creating it the first time, and gives your token read access to it. Upserts one row per platform (meta, google, tiktok, other), ad account and day; sending a day again replaces it. covered_from..covered_through is the window your figures are complete for (a day in it without a row is no spend), explicitly attested across all platforms and accounts. Only overlapping or adjacent complete windows merge; gaps remain unknown. Row-only pushes never extend completeness. trailing_12m_ad_spend, the ad-spend ratios and marketing_efficiency_ratio_90d read this spend before the ledger (evidence.source: partner_ad_spend) while the window covers 90% of their actual days and the latest complete day is no more than 3 days old. Spend in another currency than the books' is kept, not counted. Changing an existing account/day currency or source operator returns 409.

Operation ID: push_credit_ad_spend·View as markdown·OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Request body

Schema: AdSpendPushRequest

program_idstring

Your program the merchant is applying under. Required without credit_line_id; with it, must be the line's program if sent.

external_merchant_idstring

Your id for the merchant, as on POST /credit/bank-feeds and POST /credit/lines. Required without credit_line_id.

credit_line_idstring

The merchant's open line, when there is one.

merchant_legal_namestring

Names the merchant's DayZero business when this call creates it. Ignored when the business exists.

merchant_business_idstring

The merchant's existing DayZero business, when your token can reach it. Leave it out and DayZero uses the business the merchant was linked to before, or creates one.

daysarray · AdSpendDayItemAdSpendDayItem

Daily spend rows. Sending a day again replaces it. A day with no spend can be left out when the coverage window covers it.

5 fields

platformstringrequired

Where the ads were bought.

One of: meta, google, tiktok, other

spent_onstring · daterequired

The day the spend is for.

spend_centsintegerrequired

What was spent that day, in cents.

currencystringrequired

ISO 4217 currency. Spend in another currency than the merchant's books is kept but not counted (never converted).

account_idstring

Your id for the ad account, when the platform has several. Leave it out for one figure per platform and day.

covered_fromstring · date

First day of an explicit complete window across all platforms and accounts. Supply both bounds to attest omitted days as zero. Row-only pushes do not establish completeness.

covered_throughstring · date

Last day of the explicit complete window. Disjoint windows retain their gaps. Completeness must reach within 3 days of measurement.

Responses

201Successful Response

Schema: SuccessEnvelope_AdSpendPushResponse_

successboolean
messagestring
codestring
dataAdSpendPushResponse

400Bad Request - Invalid input

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

401Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

403Forbidden - Insufficient permissions

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

404Not Found - Resource does not exist

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

409Conflict - Resource already exists or is in an incompatible state

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

422Validation Error

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

Code samples

POST/api/v1/credit/ad-spend

bash

curl -X POST 'https://api.ondayzero.com/api/v1/credit/ad-spend' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "program_id": "string",
  "external_merchant_id": "string",
  "credit_line_id": "string",
  "merchant_legal_name": "string",
  "merchant_business_id": "string",
  "days": []
}'