Post an event

Post an event which can be used to trigger flows in Recart.

Three preconditions must hold, each of which fails with its own status code:

• the event source (source.category and source.name) is registered for the site via POST /event-sources,
• phoneNumber belongs to an existing subscriber — this endpoint never creates one,
• that subscriber has an active SMS subscription.

A newly registered event source does not become usable instantly. Allow a short delay after creating one before posting the first event against it, and expect the first events to be able to fail with 417 until it has propagated.

Whether a flow is actually listening for the event is not checked. If no active Integration flow uses the event source as its trigger, the event is still accepted and simply results in no message — so confirm the flow is active in the Recart dashboard when events succeed but nothing is sent.

The event is queued for processing, so 200 confirms that it was accepted, not that a message was sent. The 200 response body is the plain-text string OK, not a JSON:API document — do not parse it as JSON.

post

Authorizations

X-Recart-API-KeystringRequired

It can be obtained in Recart account after contacting Support

Body

Responses

200

The event was accepted and queued for processing. The body is the plain-text string OK.

text/plain

stringOptionalExample: OK

400

ERR_BAD_REQUEST — the payload failed validation, in which case detail lists the offending fields, or phoneNumber could not be parsed as a phone number.

application/vnd.api+json

401

ERR_UNAUTHORIZED — the X-Recart-API-Key header is missing.

application/vnd.api+json

403

ERR_FORBIDDEN — the API key is unknown or has been revoked.

application/vnd.api+json

404

ERR_NOT_FOUND — no subscriber exists for phoneNumber. Subscribe the phone number first; posting an event does not create a subscriber.

application/vnd.api+json

415

ERR_UNSUPPORTED_MEDIA_TYPE — Content-Type must be application/vnd.api+json or application/json.

A Content-Type the API cannot parse at all is rejected earlier, before this error format applies, and returns an unstructured plain-text body. A malformed JSON body is rejected the same way, with 400.

application/vnd.api+json

417

ERR_EXPECTATION_FAILED — a precondition on the account is not met. Either no event source is registered for the site with this source.category and source.name pair, or the subscriber exists but does not have an active SMS subscription. The two cases are distinguished by detail.

application/vnd.api+json

500

ERR_INTERNAL_SERVER_ERROR — the event passed validation but the request could not be processed, either because the subscriber could not be looked up or because the event could not be queued. The event was not processed, so it is safe to retry.

Failures reaching an upstream service can also surface as other 5XX statuses with an unstructured body, so treat the whole 5XX range as retryable rather than matching on 500 alone.

application/vnd.api+json

4XX

HTTP Error response

application/vnd.api+json

5XX

HTTP Error response

application/vnd.api+json

post/events

POST /app-integrations/2023-12/events HTTP/1.1
Host: api.recart.com
X-Recart-API-Key: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 181

{
  "data": {
    "type": "events",
    "attributes": {
      "phoneNumber": "[phone]",
      "source": {
        "category": "payment",
        "name": "billing attempt failed"
      },
      "properties": {
        "yourVariableName": "your value"
      }
    }
  }
}

OK