Order

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/placementapi-com/json-schema/placementapi-com-order-schema.json",
  "title": "Order",
  "description": "An order as listed by GET /v1/orders. Supplier identity is intentionally not exposed anywhere in this API. You are buying from us; which upstream marketplace fulfils a placement is not something you need or can act on.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/placementapi-com-openapi.json#/components/schemas/Order",
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string"
    },
    "status": {
      "$ref": "#/$defs/OrderStatus"
    },
    "offer_id": {
      "type": "string"
    },
    "placement_type": {
      "$ref": "#/$defs/PlacementType"
    },
    "inventory_mode": {
      "$ref": "#/$defs/InventoryMode"
    },
    "site_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "target_url": {
      "type": "string"
    },
    "anchor_text": {
      "type": [
        "string",
        "null"
      ]
    },
    "anchor_plan": {
      "oneOf": [
        {
          "$ref": "#/$defs/AnchorPlan"
        },
        {
          "type": "null"
        }
      ]
    },
    "target_keyword": {
      "type": [
        "string",
        "null"
      ]
    },
    "quantity": {
      "type": "integer"
    },
    "total_credits": {
      "type": "integer",
      "description": "Credits. 1 credit = 1 US cent."
    },
    "ordered_at": {
      "type": "string",
      "format": "date-time"
    },
    "due_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "content": {
      "$ref": "#/$defs/OrderContent"
    },
    "cancellable": {
      "type": "boolean",
      "description": "True while nothing has been sent to a supplier yet."
    },
    "submitted_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "delivered_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "placement_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "delivery_state": {
      "type": "string",
      "enum": [
        "in_progress",
        "on_time",
        "delivered_late",
        "overdue",
        "refund_eligible",
        "unknown_turnaround",
        "closed"
      ],
      "description": "Derived at read time, never stored. `refund_eligible` is a delivery-timing milestone (past due plus the account grace period) judged from the calendar alone; it does not check supplier recovery, does not mean a claim has been filed with a supplier, and is not a refund decision."
    },
    "days_late": {
      "type": [
        "integer",
        "null"
      ]
    },
    "refund_eligible_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the order passes due_at plus the account grace period. Delivery timing only: it does not mean credits have been returned and it is not an automatic credit refund. A credit refund for an order already with a supplier requires that we have recovered from the supplier, plus the supplier's refund window and the account grace period. The customer can ask us to pursue a supplier recovery review at hello@placementapi.com."
    },
    "supplier_report": {
      "type": [
        "string",
        "null"
      ],
      "description": "The supplier's latest word from the check-in loop: completed | on_time | delayed, or null."
    },
    "supplier_report_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "link_audit": {
      "type": [
        "object",
        "null"
      ],
      "description": "Our own audit of the delivered page: link present in served HTML, dofollow, bought anchor intact. Null before the first sweep.",
      "properties": {
        "checked_at": {
          "type": "string"
        },
        "link_found": {
          "type": "boolean"
        },
        "dofollow": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "anchor_matched": {
          "type": [
            "boolean",
            "null"
          ]
        }
      }
    },
    "turnaround_revised": {
      "type": "boolean"
    },
    "outcome": {
      "type": [
        "object",
        "null"
      ],
      "description": "Compact outcome (no per-keyword series). `detail` names GET /v1/orders/{order_id}/outcome. Null until tracking has produced anything.",
      "properties": {
        "days_observed": {
          "type": [
            "integer",
            "null"
          ]
        },
        "latest_checkpoint": {
          "type": [
            "string",
            "null"
          ]
        },
        "keywords": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "keywords_improved": {
          "type": "integer"
        },
        "keywords_declined": {
          "type": "integer"
        },
        "entered_top10": {
          "type": "integer"
        },
        "median_delta": {
          "type": [
            "number",
            "null"
          ]
        },
        "serp_churn": {
          "type": [
            "number",
            "null"
          ]
        },
        "visibility": {
          "type": "object"
        },
        "survival": {
          "type": "object"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ]
        },
        "confidence_note": {
          "type": "string"
        },
        "detail": {
          "type": "string"
        }
      }
    }
  },
  "$defs": {
    "AnchorPlan": {
      "type": "object",
      "description": "Anchor text is a DISTRIBUTION, not a string. Many links with one exact-match anchor is the classic over-optimisation footprint. Mix branded, topical, generic and naked_url anchors.",
      "required": [
        "anchors"
      ],
      "properties": {
        "anchors": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "text",
              "type"
            ],
            "properties": {
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300
              },
              "type": {
                "type": "string",
                "enum": [
                  "branded",
                  "naked_url",
                  "generic",
                  "topical",
                  "partial_match",
                  "exact_match"
                ]
              },
              "weight": {
                "type": "number",
                "exclusiveMinimum": 0,
                "default": 1,
                "description": "Relative weight; normalised across the plan."
              }
            }
          }
        }
      }
    },
    "InventoryMode": {
      "type": "string",
      "enum": [
        "named",
        "pre_approval",
        "blind"
      ],
      "description": "The most important field. 'named' = a specific, identified domain you can inspect before ordering. 'pre_approval' = the vendor proposes candidate domains and the buyer approves them BEFORE placement. 'blind' = a promise (e.g. DR50+, finance) where the domain is assigned at fulfilment with no veto. Only 'named' carries a site_id. Never present a pre_approval or blind offer as though a specific site were secured, and never price-compare a specification against a named domain as the same product."
    },
    "OrderContent": {
      "type": "object",
      "description": "The article on an order: who writes it, what it cost, when it is due.",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "publisher",
            "service",
            "supplied",
            "papi_written"
          ]
        },
        "tier": {
          "type": [
            "string",
            "null"
          ]
        },
        "price_credits": {
          "type": "integer"
        },
        "due_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "if_no_content": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "convert_to_service",
            "cancel",
            null
          ]
        },
        "version": {
          "type": "integer",
          "description": "How many versions have been sent so far."
        },
        "awaiting": {
          "type": "boolean",
          "description": "True in awaiting_content or content_revision_requested: the order is paid and held, not with a supplier."
        }
      }
    },
    "OrderStatus": {
      "type": "string",
      "enum": [
        "ordered",
        "awaiting_content",
        "content_revision_requested",
        "awaiting_operator",
        "submitted_to_vendor",
        "delivered",
        "cancelled",
        "refunded",
        "failed"
      ]
    },
    "PlacementType": {
      "type": "string",
      "enum": [
        "guest_post",
        "niche_edit",
        "link_insert",
        "homepage_link",
        "media_placement"
      ]
    }
  }
}