---
title: "Your orders"
method: GET
path: "/v1/orders"
tags: ["Orders"]
---

# Your orders

`GET /v1/orders`

## Request

- Base URL: `https://api.placementapi.com`
- URL: `https://api.placementapi.com/v1/orders`
- Auth: HTTP bearer

Newest first, with delivery state derived at read time, our latest link audit, and a compact observed outcome. `since` matches orders placed OR delivered at or after it (inclusive); a cancellation of an older order is not surfaced by it — re-read pending orders.

## Query parameters

- `status` 'ordered' | 'awaiting_content' | 'content_revision_requested' | 'awaiting_operator' | 'submitted_to_vendor' | 'delivered' | 'cancelled' | 'refunded' | 'failed'
- `since` string, date-time
- `target_url` string, uri
- `target_domain` string
- `limit` integer

## Response `200`

OK

- object
  - `count` integer
  - `filters` object: The filters as applied.
  - `orders` Order[]
    - `order_id` string
    - `status` 'ordered' | 'awaiting_content' | 'content_revision_requested' | 'awaiting_operator' | 'submitted_to_vendor' | 'delivered' | 'cancelled' | 'refunded' | 'failed'
    - `offer_id` string
    - `placement_type` 'guest_post' | 'niche_edit' | 'link_insert' | 'homepage_link' | 'media_placement'
    - `inventory_mode` 'named' | 'pre_approval' | 'blind': 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.
    - `site_id` string, nullable
    - `target_url` string
    - `anchor_text` string, nullable
    - `anchor_plan` AnchorPlan: 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.
      - `anchors` object[], required
        - `text` string, required
        - `type` 'branded' | 'naked_url' | 'generic' | 'topical' | 'partial_match' | 'exact_match', required
        - `weight` number: Relative weight; normalised across the plan.
    - `target_keyword` string, nullable
    - `quantity` integer
    - `total_credits` integer: Credits. 1 credit = 1 US cent.
    - `ordered_at` string, date-time
    - `due_at` string, date-time, nullable
    - `content` OrderContent: The article on an order: who writes it, what it cost, when it is due.
      - `mode` 'publisher' | 'service' | 'supplied' | 'papi_written'
      - `tier` string, nullable
      - `price_credits` integer
      - `due_at` string, date-time, nullable
      - `if_no_content` 'convert_to_service' | 'cancel' | 'null', nullable
      - `version` integer: How many versions have been sent so far.
      - `awaiting` boolean: True in awaiting_content or content_revision_requested: the order is paid and held, not with a supplier.
    - `cancellable` boolean: True while nothing has been sent to a supplier yet.
    - `submitted_at` string, date-time, nullable
    - `delivered_at` string, date-time, nullable
    - `placement_url` string, nullable
    - `delivery_state` 'in_progress' | 'on_time' | 'delivered_late' | 'overdue' | 'refund_eligible' | 'unknown_turnaround' | 'closed': 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` integer, nullable
    - `refund_eligible_at` string, date-time, nullable: 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` string, nullable: The supplier's latest word from the check-in loop: completed | on_time | delayed, or null.
    - `supplier_report_at` string, nullable
    - `link_audit` object, nullable: Our own audit of the delivered page: link present in served HTML, dofollow, bought anchor intact. Null before the first sweep.
      - `checked_at` string
      - `link_found` boolean
      - `dofollow` boolean, nullable
      - `anchor_matched` boolean, nullable
    - `turnaround_revised` boolean
    - `outcome` object, nullable: Compact outcome (no per-keyword series). `detail` names GET /v1/orders/{order_id}/outcome. Null until tracking has produced anything.
      - `days_observed` integer, nullable
      - `latest_checkpoint` string, nullable
      - `keywords` object[]
      - `keywords_improved` integer
      - `keywords_declined` integer
      - `entered_top10` integer
      - `median_delta` number, nullable
      - `serp_churn` number, nullable
      - `visibility` object
      - `survival` object
      - `confidence` 'low' | 'medium' | 'high'
      - `confidence_note` string
      - `detail` string

## Other responses

- `400`: Malformed request. `error` is `bad_request` (with a zod `detail`), `invalid_json`, or `unknown_parameter` / `unknown_field` (with `unknown[]` and `accepted[]`).
- `401`: Missing, malformed or revoked Bearer credential: `{ error: "unauthorized" }`.
- `403`: `insufficient_scope` when the key lacks the `order` scope; `customer_key_required` when the operator token is used where a customer must be attributable.
- `503`: `server_misconfigured` when the store is not configured; `upstream_unfunded` when the measurement provider's prepaid balance is exhausted (fresh profiles, gap maps and SERPs pause; cached results and catalogue are unaffected); `upstream_unavailable` on a provider error; `payments_unavailable` when card payments are not configured.

---

[API](https://skmtc.dev/placementapi/apis/placement-api.md) · [All operations](https://skmtc.dev/placementapi/apis/placement-api/llms.txt) · [OpenAPI document](https://skmtc.dev/placementapi/apis/placement-api/revisions/fc4e7866eaf7?raw)