Recipients

Checkout recipients

Create a checkout link for pending one-time recipients.

Use checkout when recipients have been created for one-time billing and need to be paid before fulfilment can start. This includes normal one-time campaigns and custom HTML recipients on accounts without a recurring subscription.

You do not need checkout for recurring campaigns on subscription-backed accounts. Those recipients are billed through the subscription.

POST https://platform.scribeless.co/api/recipients/checkout

When to use checkout

Flow	What to send
One-time campaign recipients	Add recipients to the campaign, then checkout with `campaignId`.
HTML recipients without a subscription	Create HTML recipients, fetch the active cart, then checkout with `cartId`.
Recurring campaign with subscription	Do not call checkout. Billing is handled through the subscription.
HTML recipients with subscription	Do not call checkout. Recipients move straight to `ready`.

Headers

Content-Type: application/json
X-API-Key: YOUR_API_KEY

Checkout a campaign

Use campaignId when you want to checkout one one-time campaign.

curl --request POST 'https://platform.scribeless.co/api/recipients/checkout' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "campaignId": "CAMPAIGN_ID"
  }'

If payment setup or payment recovery is required, Scribeless returns a checkout URL:

{
  "status": "checkout_required",
  "campaignId": "CAMPAIGN_ID",
  "next": "/checkout?sessionId=CHECKOUT_SESSION_SECRET",
  "checkoutUrl": "https://platform.scribeless.co/checkout?sessionId=CHECKOUT_SESSION_SECRET"
}

If automatic invoice payment succeeds, Scribeless returns:

{
  "status": "payment_succeeded",
  "campaignId": "CAMPAIGN_ID",
  "invoiceUrl": "https://invoice.stripe.com/i/..."
}

Redirect after checkout

Send redirectUrl when your integration needs Scribeless to send the customer back to your app after hosted checkout. The redirect URL must use HTTPS.

curl --request POST 'https://platform.scribeless.co/api/recipients/checkout' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "campaignId": "CAMPAIGN_ID",
    "redirectUrl": "https://partner.example.com/scribeless/callback"
  }'

When checkout is required, this returns a hosted checkout URL:

{
  "status": "checkout_required",
  "campaignId": "CAMPAIGN_ID",
  "checkoutUrl": "https://platform.scribeless.co/partner-checkout?sessionId=CHECKOUT_SESSION_SECRET"
}

After checkout completes, Scribeless redirects to redirectUrl:

https://partner.example.com/scribeless/callback?status=payment_succeeded&campaignId=CAMPAIGN_ID

Failed or incomplete payment redirects use status=payment_failed and may include a reason query parameter:

https://partner.example.com/scribeless/callback?status=payment_failed&campaignId=CAMPAIGN_ID&reason=checkout_not_fulfilled

Fetch active cart

Use the active cart for HTML recipients created on an account without a subscription. Scribeless automatically adds the hidden one-time HTML campaign to the active cart.

GET https://platform.scribeless.co/api/carts/active

curl --request GET 'https://platform.scribeless.co/api/carts/active' \
  --header 'X-API-Key: YOUR_API_KEY'

Successful requests return the open cart. If the account does not already have one, Scribeless creates it.

{
  "id": "CART_ID",
  "status": "open",
  "created_at": "2026-06-11T10:00:00.000000+00:00",
  "updated_at": "2026-06-11T10:00:00.000000+00:00",
  "completed_at": null,
  "campaigns": [
    {
      "id": "CART_CAMPAIGN_ID",
      "campaign": {
        "id": "CAMPAIGN_ID",
        "name": "[hidden:html] campaign:a6_postcard:landscape:duplex:envelope-false",
        "render_mode": "html",
        "product": {
          "name": "A6 postcard"
        },
        "metrics": [
          {
            "status": "pending",
            "count": 3
          }
        ]
      }
    }
  ]
}

Checkout active cart

Use cartId when you want to checkout everything currently in the active cart.

curl --request POST 'https://platform.scribeless.co/api/recipients/checkout' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "cartId": "CART_ID"
  }'

Successful cart checkout returns:

{
  "campaignIds": [],
  "next": "/checkout?sessionId=CHECKOUT_SESSION_SECRET",
  "checkoutUrl": "https://platform.scribeless.co/checkout?sessionId=CHECKOUT_SESSION_SECRET"
}

Recipients remain pending until checkout is paid. After payment succeeds, Scribeless marks the paid recipients as ready for fulfilment.

Recipient count changes

If you add, remove, or change recipients before a one-time campaign or cart has been paid for, call checkout again to get a fresh checkout link or payment attempt for the updated recipient count.

Calling checkout again generates a new payment step based on the latest pending recipients. Paid invoices are only attached after payment succeeds.

Notes

API-key checkout supports campaignId or cartId.
API-key checkout does not support campaignIds or recipient ids.
campaignId checkout is only available for one-time campaigns.
Cart checkout is the simplest flow for unpaid HTML recipients.
Checkout URLs include a session secret. Do not log them publicly.
If a one-time campaign has already been paid or finalized, create a new campaign for the next send instead of adding more recipients.

Status codes

Status	Meaning
`200`	Checkout completed or returned the next setup/payment step.
`400`	Missing or invalid `campaignId`, `cartId`, or `redirectUrl`, invalid campaign state, unsupported checkout body, or failed recipient validation.
`401`	Missing, malformed, invalid, or unauthorized API key.
`500`	Checkout failed unexpectedly. Retry or contact support if it persists.

Create HTML recipient

Create a Scribeless recipient from custom HTML.

PNG API

Render Scribeless handwriting text as a PNG.