Record a payment | Flowsery

api-referencePOST

Automatic Tracking Available

If you use Stripe, LemonSqueezy, or Polar, you do not need this endpoint. Payments are tracked automatically when your payment provider is connected.

POSThttps://analytics.flowsery.com/analytics/api/v1/payments

Record a payment and attribute revenue. amount is required; send transactionId and visitorUid or sessionUid when you have them.

Bearer Token (workspace token or website API key)

Workspace Tokens Need a Website Selector

Workspace API tokens can access every website in the workspace. Pass either <code>websiteId</code> or <code>domain</code> so Flowsery knows which website to query or mutate. Website API keys are already scoped to one website, so the selector can be omitted.

Website Selector

Parameter	Type	Description
`websiteId`	`string`	Website ID to use with a workspace API token. Include this field in the JSON body unless you provide domain. Omit when authenticating with a website API key.
`domain`	`string`	Website domain to use with a workspace API token when websiteId is not provided. Include this field in the JSON body. Omit when authenticating with a website API key.

Request Body

Parameter	Type	Description
`amount`REQUIRED	`number`	Required. Amount in major currency units, e.g. 29.99. With isRefund, the amount refunded. 0 records a free_trial goal instead of a payment goal.
`currency`	`string`	ISO 4217 code such as "USD", "EUR" or "GBP". Defaults to "USD" when omitted, not to the website currency.
`transactionId`	`string`	Your own payment ID. It must be unique: a repeated ID is rejected with 409 Conflict, not deduplicated. Send it again with isRefund to mark that payment refunded, and use it to delete the payment later.
`visitorUid`	`string`	Optional Flowsery visitor ID, typically sourced from the _fs_vid cookie on your own backend.
`sessionUid`	`string`	Optional Flowsery session ID, typically sourced from the _fs_sid cookie.
`email`	`string`	Customer email address.
`name`	`string`	Customer name.
`customerId`	`string`	Customer ID from your payment provider.
`isRenewal`	`boolean`	Set to true for recurring payments. Renewals count as revenue but skip the automatic payment goal. Defaults to false.
`isRefund`	`boolean`	Set to true to record a refund. With an existing transactionId it updates that payment's refunded amount instead of adding a record. Defaults to false.
`timestamp`	`string`	ISO 8601 time the payment happened, for backfilling. Defaults to now.

The success payload contains a confirmation message only.

Errors

A request without amount returns 400 Bad Request. A transactionId already recorded for this website returns 409 Conflict, unless isRefund is true.

Example Request (Node.js)

const handler = async (req, res) => {
  const _fs_vid = req.cookies._fs_vid;
  const _fs_sid = req.cookies._fs_sid;

  const response = await fetch(
    "https://analytics.flowsery.com/analytics/api/v1/payments",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${FLOWSERY_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        websiteId: process.env.FLOWSERY_WEBSITE_ID,
        amount: 29.99,
        currency: "USD",
        transactionId: "payment_456",
        visitorUid: _fs_vid,
        sessionUid: _fs_sid,
        email: "buyer@example.com",
      }),
    }
  );

  res.status(200).send("Payment tracked");
};

200

{
  "status": "success",
  "data": [{
    "message": "Payment recorded successfully"
  }]
}