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
      "domain_rating": null,
17
      "domain_traffic": null,
18
      "approved_at": null,
19
      "rejected_count": 0,
20
      "rejection_limit": 3,
21
      "concern_status": null,
22
      "price": 28800,
23
      "price_breakdown": [
24
        { "code": "BASE_DR_40", "amount": 24000 },
25
        { "code": "CONTENT_GUIDELINES_20PCT", "amount": 4800 }
26
      ]
27
    }
28
  ],
29
  "price": 28800,
30
  "price_breakdown": [
31
    { "code": "PLACEMENTS_SUBTOTAL", "amount": 28800 }
32
  ],
33
  "created_at": "2026-06-26T10:15:30Z",
34
  "updated_at": "2026-06-26T10:15:30Z",
35
  "launched_at": null
36
}

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.

Domain approval

When a placement reaches PENDING_APPROVAL, the Respona team has proposed a publisher domain and is waiting on you. The proposal is surfaced on the placement:

Poll the placement until its status is PENDING_APPROVAL, then approve or reject the proposed domain. Both need the orders:write scope; a placement outside your workspace returns 404.

Approve

$
curl -X POST https://api.respona.com/rest/api/v1/orders/123/placements/456/approve \
>
  -H "x-api-key: $RESPONA_API_KEY"

The placement moves to APPROVED and approved_at is stamped. The response is the recomputed placement. Approving a placement that is not PENDING_APPROVAL returns 409 Conflict.

Reject

A reason is required and must be non-blank.

$
curl -X POST https://api.respona.com/rest/api/v1/orders/123/placements/456/reject \
>
  -H "x-api-key: $RESPONA_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "reason": "The proposed domain is not relevant to our niche." }'

Rejecting sends the team back to propose a different domain and increments rejected_count. When rejected_count reaches rejection_limit, the placement automatically transitions to REFUNDED and credits are returned per the refund policy. Rejecting a placement that is not PENDING_APPROVAL returns 409 Conflict.

Auto-approve fallback

If you never act on a PENDING_APPROVAL placement, it auto-approves after 28 days. Acting through the API is the way to approve sooner or to reject a domain you do not want.

Concerns

You can raise one concern per placement - a short message thread with the Respona team, with its own RAISED → IN_REVIEW → RESOLVED status that overlays (never replaces) the placement’s fulfillment status via concern_status. Attachments are not supported over the API. See Concerns for the full workflow.