Getting Started

Nector is a customer engagement and loyalty platform. The merchant API lets your app, website or backend create customers, reward them with coins or offers, let them redeem coins and read the loyalty program configuration.

Base URLs

Server	Use for
`https://platform.nector.io/api/v2/merchant`	All write APIs (POST, PUT)
`https://cachefront.nector.io/api/v2/merchant`	GET APIs. Prefer this host for reads, it is cached and faster

Before You Start

Create an account on merchant.nector.io and set up your loyalty program (earning triggers, redemption offers, tiers, memberships).
Generate your API keys and the signing secret from the dashboard under Settings > API Keys. See Authentication for which key to use where.
Note your workspace id, it is sent on every request.

Required Headers

The following headers are mandatory on every API request.

Header	Description
`x-apikey`	Your Nector API key.
`x-workspaceid`	Your Nector workspace id.
`x-source`	Origin of the request: `web` (browsers and servers) or `mobile` (native apps).

Customer scoped APIs called with a storefront read only key also need x-leadtoken. See Authentication.

Recommended Integration Flow

Load the program settings. Call Fetch Aggreegated Details once on app load to get the coin name, earning ratio, tiers, memberships and other settings. Cache it on the client, the response is cached on our side for up to 10 minutes.
Create the customer. Call Create User from your backend when a customer signs up. customer_id is the mapping between your system and Nector. Store the returned lead _id as well, most APIs accept either.
Fetch the customer. Call Get User to read the wallet balance, tier, membership and referral code.
Render the earning rules. Call Fetch Triggers to list the ways a customer can earn. When the customer completes an action, call Reward Using Trigger with the trigger id. The earning rule (once, once in a period, on count reached and so on) is evaluated on our side, so it is safe to call it on every occurrence.
Render the redemption rules. Call Fetch Aggreegated Offers to list the offers a customer can spend coins on. Call Redeem Offer when they redeem, then Fetch Coupons to show the coupons they own.

📘
Easiest way to start rewarding
Reward Using Trigger is the simplest entry point. The trigger configured on the dashboard decides what is rewarded (coins, offer, email, event or webhook) and how often, so your code only needs the trigger id.

Your First Call

Fetch the program settings with a read only API key.

curl "https://cachefront.nector.io/api/v2/merchant/aggreegateddetails" \
  -H "x-apikey: <your-read-only-api-key>" \
  -H "x-workspaceid: <your-workspace-id>" \
  -H "x-source: web"

Response Format

Every response is a JSON object with meta and data.

On success meta.status is success and data holds the result: item for a single record, items and count for a list.
On failure the HTTP status code is non 200, meta.status is error, meta.code repeats the status code and data.message explains the reason.

{
  "meta": {
    "status": "error",
    "code": 422,
    "request_id": "<uuid>",
    "start_timestamp": "<ISO date>",
    "end_timestamp": "<ISO date>"
  },
  "data": {
    "message": "No discount is available"
  }
}

Error Codes

Code	Meaning
400	Validation failed. Nector enforces strict parameter checks, pass a string where a string is required and so on.
401	API key, workspace id or lead token not valid.
403	Not allowed, for example a write API called with a read only key.
404	Not found.
422	Business rule failed, for example `Lead does not exists` or `Offer is not valid`. `data.message` is safe to show to the customer.
428	Another request for the same customer is in progress, retry after a moment.
429	Rate limit exceeded.
5XX	Unexpected error on our side. Retry with backoff and share `meta.request_id` with support if it persists.

Limits and Rules

A maximum of 60 API calls are allowed per minute. Check your plan usage on the dashboard.
Only UUID v4 is supported for ids.
Never expose a write access API key in a browser or app, use it only from your backend.
Contact [email protected] for help, and include meta.request_id when reporting an issue.

Getting Started

1Pick a language

2Try It!

Base URLs

Before You Start

Required Headers

Recommended Integration Flow

Easiest way to start rewarding

Your First Call

Response Format

Error Codes

Limits and Rules

Loading…