placementapi-com Checkout API

openapi: 3.2.0
info:
  title: Placement Checkout API
  version: 1.0.0
  description: 'Normalised backlink placement inventory, deduplicated across multiple suppliers, with independent verification, held quotes, ordering, content handling and post-placement outcome tracking. Every price is the buyer price in credits (1 credit = 1 US cent), already normalised from supplier currencies, so the figure you plan with is the figure you are charged. Supplier identity is never exposed.


    Authenticate with a `pk_live_…` API key as a Bearer token. Keys carry scopes: `read` (catalogue, quotes, account reads) and `order` (anything that moves money). An MCP server exposing the same operations as tools is available at https://api.placementapi.com/mcp with the same Bearer key; the tools call these endpoints, so pricing and verification are identical either way. Unknown query parameters and brief fields are refused with 400 rather than ignored.'
  contact:
    email: hello@placementapi.com
  termsOfService: https://placementapi.com/terms
servers:
- url: https://api.placementapi.com
security:
- apiKey: []
tags:
- name: Checkout
  description: Card checkout for a basket, with or without an account.
paths:
  /v1/checkout/basket:
    post:
      tags:
      - Checkout
      operationId: checkout_basket
      summary: Buy a basket by card, with or without an account
      description: 'Auth optional. Without a key: `email` is required, payment creates the account, and the buyer receives a sign-in link with their orders placed. With a customer key: the balance is spent first and only the shortfall is charged; a basket the balance covers is placed immediately with no card (checkout_url null), and an Idempotency-Key header is REQUIRED. A card processing fee (2.9% + 30c, grossed up) is a separate line item. Nothing is charged or ordered by this call itself; orders are placed by the payment webhook once money is captured. A presented-but-invalid key is a 401, not a guest. An optional buyer-approved `max_total_credits` ceiling refuses the checkout with 409 `price_changed` if the reviewed total has risen, so a catalogue move between review and buy is never charged silently; a purchase is only ever placed on an explicit buyer action, never by the comparison itself. Limited to 10 baskets an hour per address and per customer.'
      security:
      - {}
      - apiKey: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: Required when authenticated; optional for guests (the card form is the confirmation).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - return_url
              - lines
              properties:
                email:
                  type: string
                  format: email
                  description: Required when unauthenticated; ignored when a key is sent.
                return_url:
                  type: string
                  format: uri
                  description: https URL on an allowed host; where the buyer is sent back with ?basket=&token= appended.
                max_total_credits:
                  type: integer
                  minimum: 1
                  description: Optional, additive buyer-approved ceiling on the whole basket in credits (placement + content). When the audited total has risen above it, the checkout is refused with 409 `price_changed` carrying `current_total_credits` and `max_total_credits`, and nothing is debited, charged or ordered; the buyer must compare again and accept the current total. Absent, the route behaves exactly as before (`repriced` tolerance unchanged). This is the ceiling the hosted Perch review sends as the total it showed the buyer.
                lines:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    required:
                    - offer_id
                    - target_url
                    properties:
                      offer_id:
                        type: string
                      quote_id:
                        type: string
                      target_url:
                        type: string
                        format: uri
                      anchor_text:
                        type:
                        - string
                        - 'null'
                        maxLength: 300
                      target_keyword:
                        type:
                        - string
                        - 'null'
                        maxLength: 200
                      content_mode:
                        type: string
                        enum:
                        - publisher
                        - service
                        - supplied
                        - papi_written
                      content_tier:
                        type:
                        - string
                        - 'null'
                        maxLength: 60
                        description: A paid writing tier by name when content_mode is service; the cheapest when omitted.
                      if_no_content:
                        type: string
                        enum:
                        - convert_to_service
                        - cancel
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  basket_id:
                    type: string
                  status_token:
                    type: string
                  checkout_url:
                    type:
                    - string
                    - 'null'
                    description: Null when the balance covered everything.
                  status:
                    type: string
                  total_credits:
                    type: integer
                    description: placement_credits + content_credits.
                  placement_credits:
                    type: integer
                  content_credits:
                    type: integer
                    description: Writing fees priced into the basket (service tier or papi_written).
                  fee_cents:
                    type: integer
                  charge_cents:
                    type: integer
                  balance_used_credits:
                    type: integer
                  shortfall_credits:
                    type: integer
                  expires_at:
                    type: string
                    format: date-time
                  replayed:
                    type: boolean
                  lines:
                    type: array
                    items:
                      type: object
        '400':
          description: '`bad_request`, `return_url_not_allowed`, `email_required`, `idempotency_key_required`, `empty_basket`, `anchor_text_required` (with offer_id).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: '`customer_key_required`: the operator token cannot buy.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`repriced` with lines[{ offer_id, was_credits, now_credits }] when a held price moved more than 10%; `price_changed` (with `current_total_credits` and `max_total_credits`) when the basket now costs more than the buyer-approved `max_total_credits` ceiling, in which case nothing is debited or ordered and the buyer must compare again; `basket_already_resolved`; or a line problem such as `offer_not_found` naming the offer.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /v1/checkout/basket/{basket_id}:
    get:
      tags:
      - Checkout
      operationId: checkout_basket_status
      security: []
      summary: How a checkout went
      description: Public and token-gated, because the buyer may have no account yet. Poll after returning from the card form. A wrong token is a 404, not a 403. On `partial`, credits for unplaced lines stay on the buyer's balance. Says nothing else about the customer.
      parameters:
      - name: basket_id
        in: path
        required: true
        schema:
          type: string
      - name: token
        in: query
        required: true
        schema:
          type: string
        description: status_token from the checkout response.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: pending | paid | placed | partial | failed | abandoned.
                  total_credits:
                    type: integer
                  fee_cents:
                    type: integer
                  charge_cents:
                    type: integer
                  balance_used_credits:
                    type: integer
                  lines:
                    type: array
                    items:
                      type: object
                      properties:
                        offer_id:
                          type: string
                        domain:
                          type:
                          - string
                          - 'null'
                        price_credits:
                          type: integer
                        order_id:
                          type:
                          - string
                          - 'null'
                        cancellable:
                          type: boolean
                        error:
                          type:
                          - string
                          - 'null'
                  dashboard_url:
                    type: string
                  email_hint:
                    type:
                    - string
                    - 'null'
                    description: Masked.
        '404':
          description: '`not_found`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  responses:
    RateLimited:
      description: Rate limited. 1,000 requests and 20,000 returned rows per key per hour, a monthly row entitlement that grows with credits purchased, and a maximum offset of 10,000. Carries `Retry-After` and `X-RateLimit-*` / `X-Quota-Rows-*` headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: '`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.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 'Missing, malformed or revoked Bearer credential: `{ error: "unauthorized" }`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Machine-readable code, snake_case.
        detail:
          description: Human-readable explanation, or a zod flatten() object on validation failures.
      additionalProperties: true
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Customer API key (`pk_live_…`) in `Authorization: Bearer <key>`. Issue from POST /v1/keys or the dashboard. Endpoints marked session-only reject API keys.'