Brand Studio selected-plan execution receipt

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://mirrorfactory.com/schemas/selected-plan-execution-receipt.schema.json",
  "title": "Brand Studio selected-plan execution receipt",
  "description": "The terminal selected-plan coverage, request-cost, provider-observation and customer-price receipt.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "plan_hash",
    "domain",
    "market",
    "max_cost_usd",
    "known_cost_usd",
    "held_cost_usd",
    "unknown_requests",
    "actual_cost_usd",
    "account_balance_movement_usd",
    "account_reconciliation",
    "provider_balance_observations",
    "customer_credit_price",
    "requests",
    "coverage",
    "all_selected_legs_passed"
  ],
  "properties": {
    "schema_version": {
      "const": "brand-studio-execution-receipt/v1"
    },
    "plan_hash": {
      "$ref": "#/$defs/sha256"
    },
    "domain": {
      "type": "string",
      "minLength": 1
    },
    "market": {
      "$ref": "#/$defs/market"
    },
    "max_cost_usd": {
      "$ref": "#/$defs/money"
    },
    "known_cost_usd": {
      "$ref": "#/$defs/money"
    },
    "held_cost_usd": {
      "$ref": "#/$defs/money"
    },
    "unknown_requests": {
      "type": "integer",
      "minimum": 0
    },
    "actual_cost_usd": {
      "$ref": "#/$defs/nullableMoney"
    },
    "account_balance_movement_usd": {
      "$ref": "#/$defs/nullableSignedMoney"
    },
    "documented_refunds_usd": {
      "$ref": "#/$defs/nullableMoney",
      "description": "Refunds the provider's own billing rules say are due (uncrawled DataForSEO crawl capacity). An expectation, never an observed credit; known_cost_usd stays the gross."
    },
    "expected_net_cost_usd": {
      "$ref": "#/$defs/nullableMoney",
      "description": "known_cost_usd minus documented_refunds_usd; null while any charge is unknown."
    },
    "balance_match": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "status",
        "difference_usd"
      ],
      "properties": {
        "status": {
          "enum": [
            "matches_expected_net_cost",
            "differs_from_expected_net_cost",
            "not_comparable"
          ]
        },
        "difference_usd": {
          "$ref": "#/$defs/nullableSignedMoney"
        }
      }
    },
    "account_reconciliation": {
      "enum": [
        "not_applicable_no_billed_provider",
        "observed_shared_account_delta_not_attributed",
        "observation_incomplete"
      ]
    },
    "provider_matches": {
      "type": "object",
      "description": "Each billed provider account compared in its own unit: DataForSEO in USD against the ledger net of documented refunds, ScrapeCreators in credits against the credits its calls reported. Movement above the expectation is shared-account traffic, never this pull's spend.",
      "additionalProperties": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "unit",
          "expected",
          "moved",
          "difference"
        ],
        "properties": {
          "status": {
            "enum": [
              "matches_expected",
              "matches_known_charges_unknown_not_billed",
              "matches_known_plus_unknown_at_max",
              "account_moved_more_shared_traffic",
              "account_moved_less_pending_or_refunded",
              "not_comparable"
            ]
          },
          "unit": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "expected": {
            "type": [
              "number",
              "null"
            ]
          },
          "moved": {
            "type": [
              "number",
              "null"
            ]
          },
          "difference": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      }
    },
    "provider_balance_observations": {
      "$ref": "#/$defs/providerObservations"
    },
    "customer_credit_price": {
      "$ref": "#/$defs/customerCreditPrice"
    },
    "requests": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/request"
      }
    },
    "coverage": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/coverage"
      }
    },
    "all_selected_legs_passed": {
      "type": "boolean"
    }
  },
  "$defs": {
    "sha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "money": {
      "type": "number",
      "minimum": 0
    },
    "nullableMoney": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0
    },
    "nullableSignedMoney": {
      "type": [
        "number",
        "null"
      ]
    },
    "nullableCount": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "nullableString": {
      "type": [
        "string",
        "null"
      ]
    },
    "market": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "location_code",
        "language_code",
        "confirmed"
      ],
      "properties": {
        "location_code": {
          "type": "integer",
          "minimum": 1
        },
        "language_code": {
          "type": "string"
        },
        "confirmed": {
          "const": true
        }
      }
    },
    "customerCreditPrice": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "credits",
        "basis",
        "tier",
        "byo_discount_resolved_at_reservation"
      ],
      "properties": {
        "credits": {
          "type": "integer",
          "minimum": 0
        },
        "basis": {
          "const": "existing_hosted_tier_not_provider_dollars"
        },
        "tier": {
          "type": "integer",
          "minimum": 1
        },
        "byo_discount_resolved_at_reservation": {
          "type": "boolean"
        }
      }
    },
    "movement": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "provider",
        "unit",
        "before",
        "after",
        "movement",
        "status",
        "before_status",
        "after_status",
        "before_fetched_at",
        "after_fetched_at",
        "key_last4"
      ],
      "properties": {
        "provider": {
          "type": "string",
          "minLength": 1
        },
        "unit": {
          "type": "string"
        },
        "before": {
          "$ref": "#/$defs/nullableMoney"
        },
        "after": {
          "$ref": "#/$defs/nullableMoney"
        },
        "movement": {
          "$ref": "#/$defs/nullableSignedMoney"
        },
        "status": {
          "enum": [
            "observed_shared_account_delta",
            "observation_incomplete"
          ]
        },
        "diagnostic_boundary_unverified": {
          "type": "boolean"
        },
        "before_status": {
          "type": "string"
        },
        "after_status": {
          "type": "string"
        },
        "before_fetched_at": {
          "$ref": "#/$defs/nullableString"
        },
        "after_fetched_at": {
          "$ref": "#/$defs/nullableString"
        },
        "key_last4": {
          "type": "string",
          "maxLength": 4
        }
      }
    },
    "providerObservations": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "provider_ids",
        "before",
        "after",
        "movements"
      ],
      "properties": {
        "provider_ids": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string"
          }
        },
        "before": {
          "$ref": "#/$defs/nullableString"
        },
        "after": {
          "$ref": "#/$defs/nullableString"
        },
        "movements": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/movement"
          }
        }
      }
    },
    "request": {
      "type": "object",
      "additionalProperties": true,
      "required": [
        "attempt_id",
        "phase",
        "endpoint",
        "method",
        "target",
        "max_cost_usd",
        "actual_cost_usd",
        "task_id",
        "status",
        "leg"
      ],
      "properties": {
        "attempt_id": {
          "type": "string",
          "minLength": 1
        },
        "phase": {
          "enum": [
            "reserved",
            "completed",
            "uncertain"
          ]
        },
        "endpoint": {
          "type": "string",
          "minLength": 1
        },
        "method": {
          "type": "string",
          "minLength": 1
        },
        "target": {
          "type": "string",
          "minLength": 1
        },
        "max_cost_usd": {
          "$ref": "#/$defs/money"
        },
        "actual_cost_usd": {
          "$ref": "#/$defs/nullableMoney"
        },
        "task_id": {
          "$ref": "#/$defs/nullableString"
        },
        "status": {
          "type": "string",
          "minLength": 1
        },
        "leg": {
          "type": "string",
          "minLength": 1
        },
        "response_hash": {
          "$ref": "#/$defs/sha256"
        },
        "budget_exceeded": {
          "type": "boolean"
        },
        "purchase": {
          "type": "boolean"
        }
      }
    },
    "coverageGroup": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "group_id",
        "status",
        "requested",
        "returned",
        "total_available",
        "stop_reason",
        "truncated",
        "reason",
        "scope",
        "task_id",
        "request_ids"
      ],
      "properties": {
        "group_id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "requested": {
          "$ref": "#/$defs/nullableCount"
        },
        "returned": {
          "$ref": "#/$defs/nullableCount"
        },
        "total_available": {
          "$ref": "#/$defs/nullableCount"
        },
        "stop_reason": {
          "$ref": "#/$defs/nullableString"
        },
        "truncated": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "reason": {
          "$ref": "#/$defs/nullableString"
        },
        "scope": {},
        "task_id": {
          "$ref": "#/$defs/nullableString"
        },
        "request_ids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "coverage": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "item_id",
        "requested_groups",
        "max_cost_usd",
        "status"
      ],
      "dependentRequired": {
        "groups": [
          "requested",
          "returned",
          "total_available",
          "stop_reason",
          "truncated"
        ],
        "requested": [
          "groups",
          "returned",
          "total_available",
          "stop_reason",
          "truncated"
        ],
        "returned": [
          "groups",
          "requested",
          "total_available",
          "stop_reason",
          "truncated"
        ],
        "total_available": [
          "groups",
          "requested",
          "returned",
          "stop_reason",
          "truncated"
        ],
        "stop_reason": [
          "groups",
          "requested",
          "returned",
          "total_available",
          "truncated"
        ],
        "truncated": [
          "groups",
          "requested",
          "returned",
          "total_available",
          "stop_reason"
        ]
      },
      "properties": {
        "item_id": {
          "type": "string",
          "minLength": 1
        },
        "requested_groups": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "max_cost_usd": {
          "$ref": "#/$defs/money"
        },
        "groups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/coverageGroup"
          }
        },
        "status": {
          "type": "string",
          "minLength": 1
        },
        "requested": {
          "$ref": "#/$defs/nullableCount"
        },
        "returned": {
          "$ref": "#/$defs/nullableCount"
        },
        "total_available": {
          "$ref": "#/$defs/nullableCount"
        },
        "stop_reason": {
          "$ref": "#/$defs/nullableString"
        },
        "truncated": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "reason": {
          "$ref": "#/$defs/nullableString"
        }
      }
    }
  }
}