API reference

The Ripllo API is a REST API that uses JSON for both requests and responses. It's the same API our portal and SDKs use; if you want to integrate Ripllo directly without an SDK, this section covers everything you need.

Base URL

https://ripllo.com

All API routes live under /api/v1. There's no separate api. subdomain — the marketing site and the API share the apex.

For staging:

https://staging.ripllo.com

Staging keys are minted separately from production keys; they don't cross.

Authentication

Every request must be signed. The Ripllo API uses HMAC-SHA256 request signing with an access key ID + secret pair.

Two headers per request:

Header	What it is
Authorization	Ripllo-HMAC-SHA256 keyId=<id>, scope=*, signature=<hex>
X-Ripllo-Timestamp	Current epoch seconds (must be within 300 seconds of server time)

Optional headers:

Header	When to use
Idempotency-Key	For mutating endpoints you might retry. Must be in the string-to-sign if present.
X-Ripllo-On-Behalf-Of	Only for keys with ripllo:platform:admin scope. Rescopes the call to a downstream merchant.

The signing string is:

<METHOD>
<path>             (without query string)
<timestamp>
<sha256-hex(body)>
[<idempotency-key>]    (optional, if present)

See Authentication for the full signing recipe with worked examples.

The SDKs handle all this transparently. You only need to compute signatures manually with raw HTTP.

Response envelope

Every successful API response is wrapped in a uniform envelope — the same @forjio/sdk/http shape every Forjio product uses:

{
  "data": { /* the response payload */ },
  "error": null,
  "meta": {
    "requestId": "req_01H...",
    "timestamp": "2026-05-12T10:42:00Z"
  }
}

List endpoints have a paginated variant with meta.page.nextCursor and meta.page.hasMore.

Errors keep the envelope shape but set error:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "value must be a positive integer",
    "field": "value"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

Resources

The API is organized by resource. Each maps to a section of the dashboard:

Resource	Path prefix
Discount codes	/api/v1/discount-codes
Referrals	/api/v1/referrals
Abandoned cart	/api/v1/abandoned-cart
Pixels	/api/v1/pixels
Feeds	/api/v1/feeds
Blog	/api/v1/blog
Marketing campaigns	/api/v1/marketing-campaigns
Contacts	/api/v1/contacts
Contact lists	/api/v1/contact-lists
Audience segments	/api/v1/audience-segments
Funnels	/api/v1/funnels
Channels	/api/v1/channels
Integrations	/api/v1/integrations
Campaigns (creator marketplace)	/api/v1/campaigns
Programs (affiliate marketplace)	/api/v1/programs
Collaborations	/api/v1/collaborations
Inbox	/api/v1/inbox
Insights	/api/v1/insights
API keys	/api/v1/api-keys
Webhooks	/api/v1/webhooks
Audit log	/api/v1/audit-log
Billing	/api/v1/billing
Admin (partners)	/api/v1/admin

Each resource follows a CRUD-like surface (GET list, GET :id, POST create, PATCH update, DELETE archive) with extras specific to that resource. See the SDK source for the exact method list per resource — the Node SDK is the most readable reference.

Idempotency

Mutating endpoints (POST, PUT, PATCH) accept an Idempotency-Key header. If you send the same key twice within 24 hours, you get back the same response — no duplicate operation. The SDKs auto-generate keys for create-style methods.

Internal flows that take an externalRef (e.g. discount-codes/redeem, abandoned-cart/reminders) are also idempotent on that field — retried partner webhooks won't double-write.

Rate limits

Default limits per workspace:

Endpoint class	Limit
Read (GET)	100 req/sec
Write (POST/PUT/PATCH/DELETE)	20 req/sec

Limits are returned in response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). On exceeding the limit you get 429 Too Many Requests.

Partner billing (X-Ripllo-On-Behalf-Of)

If you're a platform (Storlaunch is the canonical example) calling Ripllo on behalf of one of your merchants, you mint a key with the ripllo:platform:admin scope and set the X-Ripllo-On-Behalf-Of header to the merchant's account ID (acc_<storlaunchAccountId>). Ripllo rescopes the entire request to that merchant's workspace and stamps both the partner ID and the on-behalf-of ID in the audit log.

Ordinary merchant keys (no admin scope) cannot use this header — you get 403 FORBIDDEN_ONBEHALF. See Authentication for the full mechanics.

Next

• Authentication — the full HMAC signing recipe with worked examples.
• SDKs — per-language guides.
• Concepts — the data model the API exposes.