{"openapi":"3.1.0","info":{"title":"GET /api/v1/meta-ads/reconciliation","version":"1.0.0","description":"Meta ad spend vs. charges in the books"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/meta-ads/reconciliation":{"get":{"tags":["meta-ads"],"summary":"Meta ad spend vs. charges in the books","description":"Compare what Meta reports as spend with the Meta charges (FACEBK, META ADS, ...) that reached the books through bank and card feeds, per calendar month (or one window) and per currency, with the spend still unbilled at each period's edges and a status per period. Also lists Meta charges booked outside Advertising & Marketing. Read-only.","operationId":"meta_ads_reconciliation","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"First day, YYYY-MM-DD (default: first day of the month two months ago)","title":"Since"},"description":"First day, YYYY-MM-DD (default: first day of the month two months ago)"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Last day, YYYY-MM-DD (default: today)","title":"Until"},"description":"Last day, YYYY-MM-DD (default: today)"},{"name":"period","in":"query","required":false,"schema":{"enum":["month","window"],"type":"string","description":"'month' for calendar months, 'window' for one period","default":"month","title":"Period"},"description":"'month' for calendar months, 'window' for one period"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_MetaAdsReconciliationResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"meta_ads_reconciliation_api_v1_meta_ads_reconciliation_get"}}},"components":{"schemas":{"MetaAdsBillingStatementOut":{"properties":{"id":{"type":"string","title":"Id"},"ad_account_id":{"type":"string","title":"Ad Account Id"},"reference":{"type":"string","title":"Reference"},"evidence_reference":{"type":"string","title":"Evidence Reference"},"period_start":{"type":"string","format":"date","title":"Period Start"},"period_end":{"type":"string","format":"date","title":"Period End"},"currency":{"type":"string","title":"Currency"},"spend_minor":{"type":"integer","title":"Spend Minor"},"tax_minor":{"type":"integer","title":"Tax Minor"},"credits_minor":{"type":"integer","title":"Credits Minor"},"opening_payable_minor":{"type":"integer","title":"Opening Payable Minor"},"closing_payable_minor":{"type":"integer","title":"Closing Payable Minor"},"charge_allocations":{"additionalProperties":{"type":"integer"},"type":"object","title":"Charge Allocations"},"confirmed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Confirmed At"},"confirmed_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confirmed By"},"reported_spend_minor":{"type":"integer","title":"Reported Spend Minor"},"allocated_charges_minor":{"type":"integer","title":"Allocated Charges Minor"},"spend_difference_minor":{"type":"integer","title":"Spend Difference Minor"},"balance_difference_minor":{"type":"integer","title":"Balance Difference Minor"},"status":{"type":"string","enum":["draft","incomplete","different","reconciled"],"title":"Status"},"issues":{"items":{"type":"string"},"type":"array","title":"Issues"},"evidence_method":{"type":"string","const":"human_reviewed_statement","title":"Evidence Method","default":"human_reviewed_statement"}},"type":"object","required":["id","ad_account_id","reference","evidence_reference","period_start","period_end","currency","spend_minor","tax_minor","credits_minor","opening_payable_minor","closing_payable_minor","charge_allocations","reported_spend_minor","allocated_charges_minor","spend_difference_minor","balance_difference_minor","status"],"title":"MetaAdsBillingStatementOut"},"MetaAdsNotComparableAccount":{"properties":{"ad_account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ad Account Id"},"meta_account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Meta Account Id"},"account_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Name"},"currency":{"type":"string","title":"Currency"},"reported_spend_minor":{"type":"integer","title":"Reported Spend Minor"}},"additionalProperties":true,"type":"object","required":["currency","reported_spend_minor"],"title":"MetaAdsNotComparableAccount","description":"An ad account whose currency no Meta charge in the books uses."},"MetaAdsReconciliationCharge":{"properties":{"transaction_id":{"type":"string","title":"Transaction Id"},"date":{"type":"string","format":"date","title":"Date"},"amount_minor":{"type":"integer","title":"Amount Minor","description":"Charge in the currency's minor unit; a refund is negative"},"currency":{"type":"string","title":"Currency"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"counterparty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counterparty"},"account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id","description":"Bank or card account the charge posted to"},"account_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Name"},"category_ledger_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Ledger Id"},"category_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Name","description":"Where the charge is booked; null when uncategorized"},"is_advertising":{"type":"boolean","title":"Is Advertising","description":"Booked to an Advertising & Marketing ledger (or a sub-account)"}},"additionalProperties":true,"type":"object","required":["transaction_id","date","amount_minor","currency","is_advertising"],"title":"MetaAdsReconciliationCharge","description":"One Meta charge (or refund) found in the bank and card feeds."},"MetaAdsReconciliationCurrency":{"properties":{"currency":{"type":"string","title":"Currency"},"is_business_currency":{"type":"boolean","title":"Is Business Currency","default":false},"meta_data_from":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Meta Data From","description":"First day with Meta spend in this currency"},"meta_data_through":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Meta Data Through","description":"Last day every ad account in this currency covers"},"reported_spend_minor":{"type":"integer","title":"Reported Spend Minor","default":0},"charged_minor":{"type":"integer","title":"Charged Minor","default":0},"periods":{"items":{"$ref":"#/components/schemas/MetaAdsReconciliationPeriodRow"},"type":"array","title":"Periods"}},"additionalProperties":true,"type":"object","required":["currency"],"title":"MetaAdsReconciliationCurrency"},"MetaAdsReconciliationPeriodRow":{"properties":{"start":{"type":"string","format":"date","title":"Start"},"end":{"type":"string","format":"date","title":"End"},"currency":{"type":"string","title":"Currency"},"status":{"type":"string","enum":["matched","under_billed","over_billed","no_charges","no_meta_data","pending"],"title":"Status","description":"Estimated comparison, not verified billing reconciliation. matched: charges cover the spend within tolerance; under_billed: fewer charges than spend; over_billed: more charges than spend; no_charges: spend but no Meta charge at all; no_meta_data: nothing pulled from Meta for the period; pending: Meta may still bill it"},"reported_spend_minor":{"type":"integer","title":"Reported Spend Minor","description":"What Meta reports for the period"},"charged_minor":{"type":"integer","title":"Charged Minor","description":"Meta charges posted in the period, net"},"difference_minor":{"type":"integer","title":"Difference Minor","description":"charged_minor - reported_spend_minor"},"billed_for_period_minor":{"type":"integer","title":"Billed For Period Minor","description":"Charges attributed to this period's spend: posted from billing_lag_days after the start to billing_lag_days after the end. The status compares this with the reported spend"},"opening_unbilled_minor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Opening Unbilled Minor","description":"Spend reported but not yet charged when the period opened"},"closing_unbilled_minor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Closing Unbilled Minor","description":"Spend reported but not yet charged when the period closed"},"tolerance_minor":{"type":"integer","title":"Tolerance Minor"},"charges":{"items":{"$ref":"#/components/schemas/MetaAdsReconciliationCharge"},"type":"array","title":"Charges"},"charges_truncated":{"type":"boolean","title":"Charges Truncated","default":false}},"additionalProperties":true,"type":"object","required":["start","end","currency","status","reported_spend_minor","charged_minor","difference_minor","billed_for_period_minor","tolerance_minor"],"title":"MetaAdsReconciliationPeriodRow","description":"Meta's reported spend against the charges in the books for one period."},"MetaAdsReconciliationResponse":{"properties":{"statement_reconciliations":{"items":{"$ref":"#/components/schemas/MetaAdsBillingStatementOut"},"type":"array","title":"Statement Reconciliations","description":"Separately reviewed supplier evidence; an estimated period match alone never verifies billing"},"comparison_basis":{"type":"string","const":"estimated","title":"Comparison Basis","default":"estimated"},"billing_verified":{"type":"boolean","title":"Billing Verified","default":false},"limitations":{"items":{"type":"string"},"type":"array","title":"Limitations"},"since":{"type":"string","format":"date","title":"Since"},"until":{"type":"string","format":"date","title":"Until"},"period":{"type":"string","enum":["month","window"],"title":"Period"},"business_currency":{"type":"string","title":"Business Currency"},"billing_lag_days":{"type":"integer","title":"Billing Lag Days"},"advertising_ledger_name":{"type":"string","title":"Advertising Ledger Name","description":"The ledger Meta charges are expected in"},"currencies":{"items":{"$ref":"#/components/schemas/MetaAdsReconciliationCurrency"},"type":"array","title":"Currencies","description":"One block per currency, never mixed"},"not_comparable":{"items":{"$ref":"#/components/schemas/MetaAdsNotComparableAccount"},"type":"array","title":"Not Comparable","description":"Ad accounts billed in a currency with no matching charges"},"miscategorized":{"items":{"$ref":"#/components/schemas/MetaAdsReconciliationCharge"},"type":"array","title":"Miscategorized","description":"Meta charges in the window booked outside Advertising & Marketing"},"miscategorized_truncated":{"type":"boolean","title":"Miscategorized Truncated","default":false}},"additionalProperties":true,"type":"object","required":["since","until","period","business_currency","billing_lag_days","advertising_ledger_name"],"title":"MetaAdsReconciliationResponse"},"SuccessEnvelope_MetaAdsReconciliationResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/MetaAdsReconciliationResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[MetaAdsReconciliationResponse]"},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}