Installation

Ripllo ships two 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.
• 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. 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/saas-ripllo/sdk/go

Import it as ripllo:

import ripllo "github.com/hachimi-cat/saas-ripllo/sdk/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/saas-ripllo/sdk/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)
}

Get your API key

All three SDKs 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.

The convention across SDKs is to read credentials from environment variables:

Variable	Purpose
RIPLLO_KEY_ID	Public key identifier — safe to commit
RIPLLO_KEY_SECRET	Secret key — never commit, never log
RIPLLO_BASE_URL	Optional — only set if you're pointing at staging

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: 'AKIARPLO...', secret: '...' });

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

client, _ := ripllo.NewClient(ripllo.ClientOptions{KeyID: "AKIARPLO...", 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 any SDK at staging:

export RIPLLO_BASE_URL=https://staging.ripllo.com

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.