Quickstart

You'll have a working discount code in about five minutes. By the end of this page you'll have:

Signed up for a Ripllo workspace.
Generated an API key.
Created a discount code and redeemed it against a test storefront cart.

If you'd rather read about concepts first, jump to Concepts. If you'd rather install the SDK first, see Installation.

Prerequisites

You'll need:

A working email address — we use Huudis SSO for sign-in, and verifying an email is part of sign-up.
About five minutes.
Either a terminal with curl (to follow this page's examples literally) or an SDK installed (covered in Installation).

You do not need a real Storlaunch storefront or a customer database. The redeem endpoint takes an opaque checkoutSessionId, so a synthetic string is fine for this walkthrough.

Step 5 uses the CLI (npm install -g @forjio/ripllo-cli). Skip it if you'd rather check the dashboard.

Head to ripllo.com and click Get started. We use Huudis as our identity provider — you'll create one Huudis account and use it across every Forjio product (Ripllo, Storlaunch, Plugipay, Fulkruma, LinkSnap, and the rest).

Sign-up takes two clicks:

Enter your email and choose a password.
Click the verification link we send you.

Once you're verified, you land in your first workspace's dashboard.

Workspaces are how Ripllo isolates data. You get one workspace by default, and you can create more for different storefronts or environments. Each workspace has its own discount codes, referral programs, pixels, and API keys.

2. Get an API key

In the dashboard, navigate to Settings → API keys (or go directly to /dashboard/api-keys).

Click Create API key. Give it a name (something like "Quickstart").

Ripllo shows the secret once. Copy both values into your terminal as environment variables:

export RIPLLO_KEY_ID=AKIAFULK...
export RIPLLO_SECRET=fulksk_...

These two names are the ones the CLI reads (along with RIPLLO_API_URL if you need to point it at another environment); ripllo auth login --key-id ... --secret ... stores the same pair in a profile instead. The SDKs read no environment variables at all — you pass the values into the client constructor, so in your own code you can call them whatever you like.

Treat the secret like a password. Anyone with the secret can read and write data in this workspace. We never display it again after creation. If you lose it, revoke the key from the portal and mint a new one.

3. Create a discount code

The simplest end-to-end action is a discount code: a promo code with a value (% or fixed amount), a scope (cart — the whole cart, products — specific product IDs, or tags — a tag filter), and optional usage limits. scope defaults to cart, so you can leave it out.

Create one with the Node SDK:

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

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

const code = await ripllo.discountCodes.create({
  code: 'WELCOME10',
  type: 'percent',
  value: 10,
  currency: 'IDR',
  scope: 'cart',
  maxUsesTotal: 100,
});

console.log('Created:', code.id);

Or with raw curl:

curl -X POST https://ripllo.com/api/v1/discount-codes \
  -H "Content-Type: application/json" \
  -H "Authorization: Ripllo-HMAC-SHA256 keyId=$RIPLLO_KEY_ID, scope=*, signature=<see below>" \
  -H "X-Ripllo-Timestamp: $(date +%s)" \
  -d '{
    "code": "WELCOME10",
    "type": "percent",
    "value": 10,
    "currency": "IDR",
    "scope": "cart",
    "maxUsesTotal": 100
  }'

Ripllo uses HMAC signing — you compute a SHA-256 HMAC of method + path + timestamp + body_hash with your secret key. The exact algorithm is documented in API Authentication. The SDKs handle this for you automatically.

4. Redeem it

Pretend your storefront just took a successful order using WELCOME10. Call redeem to stamp a DiscountRedemption row. Redeem takes the code's id (not the code string) and the amount you actually discounted, in minor units:

const result = await ripllo.discountCodes.redeem({
  accountId: '<your workspace id>',      // must match the key's workspace
  discountCodeId: code.id,               // from step 3
  checkoutSessionId: 'order_test_001',   // any opaque id from your checkout
  customerId: 'cust_test_001',
  appliedAmount: 25000,                  // the discount granted, not the subtotal
  externalSource: 'quickstart',
  externalRef: 'order_test_001',
});

console.log('Redeemed:', result.id, 'newly created:', result.created);

This endpoint is partner-authenticated: the accountId it acts on comes from the signed request, not from the body. With your own workspace key the two are the same — send a different accountId and you get 403 ACCOUNT_MISMATCH. Platform partners signing on a merchant's behalf pass X-Ripllo-On-Behalf-Of instead (see API Authentication).

redeem is idempotent keyed on checkoutSessionId within your workspace — if your payment webhook fires twice, the second call returns the same id with created: false. appliedShipping defaults to 0, and orderGrossIdr is optional but worth sending if you want the discount's revenue to show up in campaign reporting.

5. Verify it worked

Check the dashboard at Dashboard → Discounts and click WELCOME10. You should see the redemption listed with the checkout-session ID, applied amount, and customer ID.

Or from the CLI — note get takes the id printed in step 3, not the code string (a code string returns 404 NOT_FOUND). ripllo discount list shows every code with its id if you didn't keep it:

ripllo discount list
ripllo discount get "$CODE_ID"

You did it — you've created and redeemed your first Ripllo discount code.

What's next

Installation — install the SDK properly for your project.
Concepts — understand the model behind referrals, abandoned-cart, and the rest.
Portal → Discounts — the full discount-code tour.
API reference — every endpoint, every parameter.