Skip to docs content
Browse and search
On this page

Start a checkout

Start a checkout and get one payment page for the person to open. Crypto is the default rail; send paymentRail CARD for a card. A trial is used when the account still has one. The response's next step says what to do: open_payment (give the person paymentUrl, then poll pollUrl), join_discord, or wait. Replaying the same Idempotency-Key returns the same checkout.

POST/api/agent/checkout

Authorization

  • AuthorizationstringheaderrequiredBearer authentication with your TweetStream API key: Bearer <key>.

Headers

  • Idempotency-KeystringheaderrequiredRequired. Generate one key per intended purchase or change and reuse it on retries; the same key returns the same result.
  • X-TweetStream-Setup-ProofstringheaderoptionalOptional. The setupProof returned by email verification; when present, a Discord step includes its join URL.

Body

  • billingCycleenum<string>optional
  • paymentRailenum<string>optional
  • trialenum<string>optional
  • familyenum<string>required
  • planTypeenum<string>required

Response fields

  • checkoutIdstringoptionala string matching the pattern ^pl_[a-z0-9]{1,64}$
  • familyenum<string>required
  • nextobjectrequired
    • messagestringoptionala string at most 500 character(s) long
    • actionenum<string>required
    • methodenum<string>required
    • urlstringrequireda string matching the pattern ^(https|wss):\/\/[^\s]+$
    • whoenum<string>required
  • offerobjectoptional
    • amountDueNowobjectrequired
      • currencyenum<string>required
      • minorstringrequireda string matching the pattern ^(0|[1-9][0-9]*)$
    • modeenum<string>required
    • planNamestringrequired
    • renewalobjectrequired
      • amountobjectrequired
        • currencyenum<string>required
        • minorstringrequireda string matching the pattern ^(0|[1-9][0-9]*)$
      • atstringrequireda string to be decoded into a Date
      • billingCycleenum<string>required
      • thenAmountobjectrequired
        • currencyenum<string>required
        • minorstringrequireda string matching the pattern ^(0|[1-9][0-9]*)$
  • paymentUrlstringoptionala string matching the pattern ^(https|wss):\/\/[^\s]+$
  • reasonenum<string>required
  • statusenum<string>required

Responses

  • 200A replay, the product is already ready, or the person must join Discord first
  • 201Checkout created
  • 202Checkout is being prepared; poll status
  • 400Invalid request, wrong code, or the Terms were not accepted
  • 401Missing or invalid API key, or the setup proof is missing or expired
  • 403The account is restricted, or the request carried a foreign Origin
  • 409Idempotency, checkout, offer or trial conflict
  • 429Rate limit or activation budget reached; retry after retryAfterSeconds
  • 503Temporarily unavailable; retry later