Orders

Place an order (pay-first)

Debits credits immediately. Requires the order scope and an Idempotency-Key header. With quote_id the held price is charged instead of the live one and the freshness guard is bypassed; without it a stale catalogue price is refused. Content is decided now against what the listing allows: 'supplied' without inline content parks the order in awaiting_content for 14 days; 'papi_written' charges 1,500 credits with the order; inline content is validated first (422, nothing charged). Orders that carry an article are one placement each.

post/v1/orders

Request

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

Headers

Idempotency-Keystring required

Required. A retry without one is indistinguishable from a second purchase and is refused (400 idempotency_key_required) rather than double-charged. A replay with the same key returns the original result with replayed: true.

Request body

offer_idstring required

From /v1/offers or a quote line / alternative.

quote_idstring

Redeem a held price from POST /v1/quote or POST /v1/targets/gap.

target_urlstring uri required

The page the link points at.

anchor_textstring nullable

Omit when order_requirements marks it optional (publisher writes the anchor).

target_keywordstring nullable

The query the page should rank for. Optional and worth sending: it seeds outcome tracking and anchor classification.

target_marketstring nullable

ISO country for the SERP this is judged in. Defaults to US.

target_device'desktop' | 'mobile' | 'null' nullable
quantityinteger
content_mode'publisher' | 'service' | 'supplied' | 'papi_written'

Defaults from order_requirements.content: 'publisher' where the publisher writes, else 'supplied'. Refused (400 content_not_accepted) where the listing does not allow it.

content_tierstring

For 'service': a vendor_label (or tier) from order_requirements.content.options. Defaults to the cheapest paid tier.

if_no_content'convert_to_service' | 'cancel'

What happens when supplied copy misses content.due_at.

Response

Idempotent replay of an earlier order with the same key.

order_idstring
replayedtrue

Changes

No recorded changes to this operation across all 1 revision of this API.