Checkout recipients

Complete checkout for recipients on an approved partner one-time campaign.

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

This endpoint is only for approved partner workflows configured by Scribeless. Normal API integrations do not need to call it.

When to use checkout

Call this endpoint after adding recipients to an approved partner one-time campaign. Checkout is the step that collects payment and allows those recipients to move toward fulfilment.

You do not need to call checkout for recurring campaigns. If the customer has a subscription set up and the campaign is recurring, billing is handled automatically at the end of the 30-day billing cycle.

Use GET /api/account/status before checkout when you need to check whether the account is ready. billByInvoice indicates whether invoice billing is ready for the account. If billingSetupUrl is present, send the customer to that URL to finish billing setup before expecting checkout to complete.

Headers

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

Request body

Example request

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"
  }'

Payment succeeded

When checkout completes, Scribeless moves eligible pending recipients toward fulfilment. Scribeless attempts automatic payment first. If automatic payment cannot be completed, the response returns the next checkout or payment step instead.

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

invoiceUrl is the hosted Stripe invoice URL for the paid invoice.

Checkout required

If the customer has not provided billing card details yet, or automatic payment cannot be completed, the response includes a Scribeless checkout URL. Send the customer to that URL so they can complete payment setup or payment recovery.

Scribeless returns a partner checkout URL:

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

Recipients remain pending until they have been paid for.

Redirect callback

Scribeless redirects the customer back to redirectUrl after partner checkout completes.

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

Recipient count changes

If you add, remove, or change recipients before the campaign 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 campaign recipients. Paid invoices are only attached to the campaign after payment succeeds.

Notes

• This endpoint is available only for approved partner one-time campaigns.
• Create the campaign with frequency: "oneTime". Do not set billing_method: "oneTimeInvoice" when creating the campaign.
• If a one-time campaign has already been paid or finalized, you cannot add and checkout more recipients on that campaign. Create a new campaign for the next send.

Status codes