Orders & Placements

An order is a container for one or more placements. A placement is a single link-placement request — a target URL, an anchor, a quality tier, and optional guidelines. requested_url and quality_tier are required on every placement. Placements are always sub-resources of an order; there is no top-level placement endpoint.

Resource shape

Every order and placement response includes the current price and price_breakdown, recomputed live. All monetary amounts are integer USD cents (1 credit = 1 cent). Field-level detail is in the API Reference; this is the overall shape:

1
{
2
  "order_id": "123",
3
  "title": "Q3 link building",
4
  "status": "DRAFT",
5
  "placements": [
6
    {
7
      "placement_id": "456",
8
      "number": null,
9
      "status": "DRAFT",
10
      "requested_url": "https://example.com/post",
11
      "requested_anchor": "best widgets",
12
      "publisher_url": null,
13
      "quality_tier": "DR_40",
14
      "content_guidelines": "string or null",
15
      "domain_specifications": "string or null",
16
      "price": 28800,
17
      "price_breakdown": [
18
        { "code": "BASE_DR_40", "amount": 24000 },
19
        { "code": "CONTENT_GUIDELINES_20PCT", "amount": 4800 }
20
      ]
21
    }
22
  ],
23
  "price": 28800,
24
  "price_breakdown": [
25
    { "code": "PLACEMENTS_SUBTOTAL", "amount": 28800 }
26
  ],
27
  "created_at": "2026-06-26T10:15:30Z",
28
  "updated_at": "2026-06-26T10:15:30Z",
29
  "launched_at": null
30
}

title defaults to "New order" when omitted on creation. number — the human-facing sequential order number — is assigned when the order is launched, so it is omitted from a draft order and appears once launched.

Order status is one of DRAFT, LAUNCHED, IN_PROGRESS, COMPLETED, REJECTED, REFUNDED. Placement status is one of DRAFT, ORDERED, PENDING_APPROVAL, REJECTED, IN_PROGRESS, APPROVED, LIVE, REFUNDED.

Quality tiers

quality_tier is a string selecting the minimum domain-authority band for the placement:

Pricing modifiers

Two optional fields refine a placement and each add +20% to that placement’s base price. They stack — supplying both adds +40% over the base. Omit a field (or send null) to leave it disabled.

• content_guidelines — free-text editorial instructions for the placed content. Surfaces as a CONTENT_GUIDELINES_20PCT line in the breakdown.
• domain_specifications — free-text constraints on the hosting domain. Surfaces as a DOMAIN_SPECIFICATIONS_20PCT line.

The price_breakdown always itemizes the base band (BASE_<tier>) plus any active modifiers so the total is fully explained. See Credits & Billing for how price maps to credits.

Order state machine

DRAFT ──launch──▶ LAUNCHED ──▶ IN_PROGRESS ──▶ COMPLETED
                                     │
                                     ├──▶ REJECTED
                                     └──▶ REFUNDED

Only DRAFT orders are mutable. Adding, removing, deleting, or re-launching a non-DRAFT order returns 409 Conflict.

Placement state machine

Placements progress independently after launch:

DRAFT ─▶ ORDERED ─▶ IN_PROGRESS ─▶ PENDING_APPROVAL ─▶ APPROVED ─▶ LIVE
                                                            │
                                                            ├─▶ REJECTED
                                                            └─▶ REFUNDED

Terminal states are LIVE, REJECTED, and REFUNDED. Everything else is transient — poll until a placement is terminal. A rejected or refunded placement returns credits per the refund policy.