Installation

Ripllo ships three flavors of tooling. Pick the one that fits how you work:

• SDK — libraries in Node.js, Python, and Go. Best for embedding Ripllo in an application or backend service.
• CLI — ripllo, for scripting and one-off work from a terminal.
• Raw API — if you can't or don't want to add a dependency, the REST API is fully documented and signed with HMAC.

This page covers installing the SDKs and the CLI. If you want raw API access, skip ahead to the API authentication page.

Node.js SDK

The Node SDK is @forjio/ripllo-node:

npm install @forjio/ripllo-node

Or with pnpm / yarn:

pnpm add @forjio/ripllo-node
yarn add @forjio/ripllo-node

It's compatible with Node 18 and later. It ships with TypeScript types out of the box — no @types/* package needed.

Minimal usage:

import { RiplloClient } from '@forjio/ripllo-node';

const ripllo = new RiplloClient({
  keyId: process.env.RIPLLO_KEY_ID,
  secret: process.env.RIPLLO_KEY_SECRET,
});

const codes = await ripllo.discountCodes.list({ limit: 10 });
console.log(codes);

Python SDK

The Python SDK is published on PyPI as ripllo:

pip install ripllo

It supports Python 3.9+. Dependencies: httpx (only).

Minimal usage:

from ripllo import RiplloClient
import os

ripllo = RiplloClient(
    key_id=os.environ["RIPLLO_KEY_ID"],
    secret=os.environ["RIPLLO_KEY_SECRET"],
)

codes = ripllo.discount_codes.list(limit=10)
print(codes)

Go SDK

The Go SDK lives in the same repo as Ripllo itself:

go get github.com/hachimi-cat/ripllo-go

Import it as ripllo:

import ripllo "github.com/hachimi-cat/ripllo-go"

It uses only the Go standard library — no external dependencies. Requires Go 1.22+.

Minimal usage:

package main

import (
    "context"
    "fmt"
    "os"

    ripllo "github.com/hachimi-cat/ripllo-go"
)

func main() {
    client, err := ripllo.NewClient(ripllo.ClientOptions{
        KeyID:  os.Getenv("RIPLLO_KEY_ID"),
        Secret: os.Getenv("RIPLLO_KEY_SECRET"),
    })
    if err != nil {
        panic(err)
    }

    codes, err := client.DiscountCodes.List(context.Background(), ripllo.ListParams{Limit: 10})
    if err != nil {
        panic(err)
    }
    fmt.Println(codes)
}

CLI

The CLI is published as @forjio/ripllo-cli and installs the ripllo binary:

npm install -g @forjio/ripllo-cli

Authenticate once — credentials are stored as an INI profile in ~/.ripllo/credentials:

ripllo auth login --key-id AKIAFULK... --secret fulksk_...
ripllo auth whoami

Then drive any resource. Every command group mirrors an API resource — discount, referral, abandoned-cart, pixel, feed, blog, contacts, contact-lists, broadcasts, marketing-campaigns, funnels, audience-segments, campaigns, programs, collaborations, channels, insights, inbox, merchants, billing, marketplace, creator-profile, affiliator-profile, affiliates, kyc, creator-stats, uploads:

ripllo discount list
ripllo discount get "$CODE_ID"

Anything the CLI doesn't wrap yet, call directly:

ripllo passthrough GET /api/v1/referrals/stats

Global flags, valid on every command:

Flag	Effect
--json	Emit JSON instead of the default table output.
--profile <name>	Use a named credentials profile (default: default).
--api <url>	Override the API base URL.
--on-behalf-of <accountId>	Send X-Ripllo-On-Behalf-Of — platform-admin keys only.
--no-color	Disable ANSI color.

Instead of a stored profile, the CLI also reads RIPLLO_KEY_ID, RIPLLO_SECRET and RIPLLO_API_URL from the environment.

Get your API key

All three SDKs and the CLI need a Ripllo API key. To get one:

1. Sign up at ripllo.com — takes about a minute. See Sign in for the details.
2. Open the dashboard and go to Settings → API keys.
3. Click Create API key.
4. Copy the key_id and secret immediately — we don't show the secret again.

Only the Go SDK reads the environment on its own. The Node and Python clients read nothing: you pass keyId / secret (or key_id / secret) into the constructor, and they raise if you don't. The variable names below are a convention you apply yourself — the samples above just happen to follow it.

Variable	Read automatically by	Purpose
RIPLLO_KEY_ID	Go SDK, CLI	Public key identifier — safe to commit
RIPLLO_SECRET	Go SDK, CLI	Secret key — never commit, never log
RIPLLO_BASE_URL	Go SDK	Optional — only set if you're pointing at staging
RIPLLO_API_URL	CLI	The CLI's equivalent of RIPLLO_BASE_URL

Note the Go SDK and the CLI both use RIPLLO_SECRET, not RIPLLO_KEY_SECRET. If you name your Node/Python variables RIPLLO_KEY_SECRET, that's fine — nothing reads them but your own code.

Don't bake the secret into source. Use your environment's secret manager. For local dev, a gitignored .env file plus dotenv is fine. For production, use AWS Secrets Manager, Vault, or your platform's equivalent.

If you'd rather pass the credentials explicitly:

const ripllo = new RiplloClient({ keyId: 'AKIAFULK...', secret: '...' });

ripllo = RiplloClient(key_id='AKIAFULK...', secret='...')

client, _ := ripllo.NewClient(ripllo.ClientOptions{KeyID: "AKIAFULK...", Secret: "..."})

Partner-billing mode (Storlaunch, others)

If you're a platform admin minting keys that act on behalf of a downstream merchant (the Pattern 2 partner-billing model Storlaunch uses), the SDK accepts an onBehalfOf option:

const ripllo = new RiplloClient({
  keyId: process.env.RIPLLO_KEY_ID,
  secret: process.env.RIPLLO_KEY_SECRET,
  onBehalfOf: 'acc_<merchantAccountId>',
});

This sets the X-Ripllo-On-Behalf-Of header on every request, and Ripllo scopes the call to that merchant's workspace. Only keys with the ripllo:platform:admin scope can use this — ordinary merchant keys get 403 FORBIDDEN_ONBEHALF if they try. See API authentication for the full mechanics.

Sandbox & staging

If you want to test against a non-production Ripllo instance, point the client at staging. Node and Python default to https://ripllo.com and take the override as a constructor argument — setting an environment variable does nothing for them:

const ripllo = new RiplloClient({ keyId, secret, baseUrl: 'https://staging.ripllo.com' });

ripllo = RiplloClient(key_id=key_id, secret=secret, base_url='https://staging.ripllo.com')

The Go SDK and the CLI do read it from the environment:

export RIPLLO_BASE_URL=https://staging.ripllo.com   # Go SDK
export RIPLLO_API_URL=https://staging.ripllo.com    # CLI (or pass --api)

Production keys don't work against staging and vice versa.

Next

You're ready. Head to Concepts to understand the model, or Portal → Discounts to start building.