Getting Started

Get up and running with the Zupy Partner API in 4 steps.

Estimated Time: Under 15 minutes

Prerequisites

Your API key (format: zupy_pk_*) — provided by the Zupy team during onboarding
The company ID for the restaurant you’re integrating with
Your integration slug (e.g., repediu) for webhook URLs

Don’t have credentials yet? Contact webmaster@zupy.com.br to start the onboarding process.

Step 1: Verify Your API Key

Test your credentials with a simple customer search:

curl -X GET "https://api.zupy.com/api/v2/customers/?phone=5511987654321" \
  -H "X-API-Key: zupy_pk_your_api_key_here"

import requests

BASE_URL = "https://api.zupy.com/api/v2"
API_KEY = "zupy_pk_your_api_key_here"
HEADERS = {"X-API-Key": API_KEY}

response = requests.get(
    f"{BASE_URL}/customers/",
    params={"phone": "5511987654321"},
    headers=HEADERS,
)
print(response.json())

const BASE_URL = "https://api.zupy.com/api/v2";
const API_KEY = "zupy_pk_your_api_key_here";

const response = await fetch(
  `${BASE_URL}/customers/?phone=5511987654321`,
  { headers: { "X-API-Key": API_KEY } }
);
const data = await response.json();
console.log(data);

Phone format: The phone parameter accepts digits only (e.g., 5511987654321). The API normalizes all phone numbers to E.164 format (+5511987654321) internally, so any input format will match the same customer.

If your key is valid, you receive a 200 response (even if no customers match):

{
  "count": 0,
  "next": null,
  "previous": null,
  "results": []
}

If your key is invalid, you receive a 401 error in RFC 7807 format:

{
  "type": "https://api.zupy.com/errors/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Invalid API key"
}

Step 2: Send a Test Webhook

Send order data to Zupy. Replace {partner} with your integration slug (e.g., repediu). The webhook accepts any JSON payload — Zupy stores it raw and processes it asynchronously using a partner-specific adapter. During onboarding, the Zupy team will map your payload format. For new integrations, use this standard catch-all format:

curl -X POST "https://api.zupy.com/api/v2/webhooks/integrations/{partner}/" \
  -H "X-API-Key: zupy_pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "customer_name": "Maria Santos",
      "customer_phone": "+5511987654321",
      "customer_email": null,
      "customer_cpf": null,
      "order_total": "89.90",
      "order_id": "123456789",
      "order_date": "2026-03-22T14:30:00.000Z",
      "store_cnpj": "12.345.678/0001-90",
      "store_name": "Pizzaria Exemplo"
    }
  ]'

payload = [
    {
        "customer_name": "Maria Santos",
        "customer_phone": "+5511987654321",
        "customer_email": None,
        "customer_cpf": None,
        "order_total": "89.90",
        "order_id": "123456789",
        "order_date": "2026-03-22T14:30:00.000Z",
        "store_cnpj": "12.345.678/0001-90",
        "store_name": "Pizzaria Exemplo",
    }
]

response = requests.post(
    f"{BASE_URL}/webhooks/integrations/{{partner}}/",
    json=payload,
    headers=HEADERS,
)
print(response.json())

const partner = "your_slug"; // e.g., "repediu"
const payload = [
  {
    customer_name: "Maria Santos",
    customer_phone: "+5511987654321",
    customer_email: null,
    customer_cpf: null,
    order_total: "89.90",
    order_id: "123456789",
    order_date: "2026-03-22T14:30:00.000Z",
    store_cnpj: "12.345.678/0001-90",
    store_name: "Pizzaria Exemplo",
  },
];

const response = await fetch(
  `${BASE_URL}/webhooks/integrations/${partner}/`,
  {
    method: "POST",
    headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  }
);
const data = await response.json();
console.log(data);

Already have your own payload format? Send it as-is — Zupy accepts any JSON. During onboarding, the Zupy team will create a mapper for your specific field names, just like we did for Repediu, Saipos, and other partners.

Success response (campos na raiz):

{
  "status": "received",
  "id": "2bxRKmpWJY8lHHqsGfsQQtwCDef"
}

The webhook is processed asynchronously. You receive an immediate 200 with "status": "received". Orders are processed in a background queue (typically within seconds).

Idempotency: Sending the same payload twice returns "status": "duplicate" — no error, no double-processing. Zupy computes a SHA-256 hash of the request body to detect duplicates.

Step 3: Look Up the Customer

After the webhook processes (typically within seconds), search for the customer:

curl -X GET "https://api.zupy.com/api/v2/customers/?phone=5511987654321" \
  -H "X-API-Key: zupy_pk_your_api_key_here"

response = requests.get(
    f"{BASE_URL}/customers/",
    params={"phone": "5511987654321"},
    headers=HEADERS,
)
customers = response.json()["results"]
print(f"Found {len(customers)} customer(s)")

const response = await fetch(
  `${BASE_URL}/customers/?phone=5511987654321`,
  { headers: { "X-API-Key": API_KEY } }
);
const { results: customers } = await response.json();
console.log(`Found ${customers.length} customer(s)`);

Response (campos na raiz):

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "2awTHloSJX7kGGprFerOOsvABcd",
      "full_name": "Maria Santos",
      "email": null,
      "phone": "+5511987654321",
      "cpf": null,
      "birth_date": null,
      "points_balance": 89,
      "points_earned": 89,
      "points_spent": 0,
      "tier": "default",
      "card_number": "ZP-ABC123",
      "join_date": "2026-03-22",
      "last_activity_date": "2026-03-22T14:30:00Z",
      "rfm_segment": "new",
      "program_id": "2awTHmNw8X7kGGpr...",
      "program_name": "Clube Pizzaria Exemplo",
      "company_id": "2awTHkVw8X7kGGpr..."
    }
  ]
}

Step 4: Check Points Balance

curl -X GET "https://api.zupy.com/api/v2/customers/2awTHloSJX7kGGprFerOOsvABcd/points/" \
  -H "X-API-Key: zupy_pk_your_api_key_here"

customer_id = "2awTHloSJX7kGGprFerOOsvABcd"
response = requests.get(
    f"{BASE_URL}/customers/{customer_id}/points/",
    headers=HEADERS,
)
points = response.json()
print(f"Balance: {points['points_balance']} {points['points_name']}")

const customerId = "2awTHloSJX7kGGprFerOOsvABcd";
const response = await fetch(
  `${BASE_URL}/customers/${customerId}/points/`,
  { headers: { "X-API-Key": API_KEY } }
);
const points = await response.json();
console.log(`Balance: ${points.points_balance} ${points.points_name}`);

Response (campos na raiz):

{
  "customer_id": "2awTHloSJX7kGGprFerOOsvABcd",
  "points_balance": 89,
  "points_earned": 89,
  "points_spent": 0,
  "points_name": "Pontos",
  "last_activity_date": "2026-03-22T14:30:00Z",
  "tier": "default"
}

You’re Integrated!

You’ve successfully verified your API key, sent order data via webhook, looked up a customer, and checked their points balance.

Field Glossary — balances and identifiers

To save you the time we spent figuring this out the first time, here are the partner-visible naming conventions in one table:

Balance fields

Field	Where it appears	What it means
`points_balance`	`GET /customers/{id}/`, `GET /customers/{id}/points/`, OTP verify response	The customer’s current points balance. The stable, always-queryable field.
`new_balance`	`POST /rewards/{id}/redeem/` response, `POST /coupons/{id}/validate/` response	The customer’s balance immediately after the operation. Same number as `points_balance` if you GET-after-POST — included so you don’t have to.
`current_points`	(rare — Wallet / scanner contexts only)	Synonym for `points_balance`. Will be deprecated. Do not write new code against this.
`zupy_balance`	`GET /companies/` response	The company’s Z$ balance (marketing-campaign budget pool). Not a customer balance.
`new_z_balance`	`POST /rewards/{id}/redeem/` response, `POST /coupons/{id}/validate/` response	The customer’s Z$ balance after the operation. Stringified Decimal with 6 places (e.g. `"2418.400000"`).
`z_tokens_used`	`POST /rewards/{id}/redeem/` response, `POST /coupons/{id}/validate/` response	Z$ tokens consumed by this specific operation. `"0.000000"` (zero-as-string) for points-only redemptions.

Coupon identifiers

Field	Format	When to use
`id`	KSUID (e.g. `16a33f27fbbc1801d63d56d2027`)	When you obtained it from a prior API call (redeem response or `/coupons/issued/` list). Always works.
`coupon_code`	`CZ-XXXXXXXX` or `CP-XXXXXXXX` (legacy)	When you have a printed code from the customer’s receipt. The `validate` endpoint accepts this directly (case-insensitive).

See Coupon Lifecycle § Two identifiers, one coupon for the full rationale.

Error Handling

All errors use the RFC 7807 Problem Details format:

{
  "type": "https://api.zupy.com/errors/{error-type}",
  "title": "Human-Readable Title",
  "status": 400,
  "detail": "Specific explanation of what went wrong"
}

Common errors you may encounter:

Status	Type	When It Occurs
401	`authentication-required`	Missing or invalid `X-API-Key` header
403	`permission-denied`	Read-only key attempting a write operation
429	`rate-limit-exceeded`	Too many requests — check `Retry-After` header

Retry logic for rate limits

When you receive a 429 response, wait for the Retry-After header duration before retrying:

import time
import requests

def api_request(method, url, **kwargs):
    """Make an API request with automatic retry on rate limit."""
    max_retries = 3
    for attempt in range(max_retries):
        response = requests.request(method, url, **kwargs)

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 30))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")

async function apiRequest(method, url, options = {}) {
  const maxRetries = 3;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, { method, ...options });

    if (response.status === 429) {
      const retryAfter = parseInt(
        response.headers.get("Retry-After") || "30"
      );
      console.log(`Rate limited. Retrying in ${retryAfter}s...`);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error("Max retries exceeded");
}

Next Steps

Authentication

Learn about access levels, rate limits, OTP, and security best practices

Webhook Setup

Configure webhooks for automatic order processing and customer enrollment

API Reference

Browse all endpoints with request/response schemas

Partner Onboarding

Complete the onboarding checklist for production deployment

Introduction

Guides

Prerequisites

Step 1: Verify Your API Key

Step 2: Send a Test Webhook

Step 3: Look Up the Customer

Step 4: Check Points Balance

You’re Integrated!

Field Glossary — balances and identifiers

Balance fields

Coupon identifiers

Error Handling

Next Steps

Authentication

Webhook Setup

API Reference

Partner Onboarding

​Prerequisites

​Step 1: Verify Your API Key

​Step 2: Send a Test Webhook

​Step 3: Look Up the Customer

​Step 4: Check Points Balance

​You’re Integrated!

​Field Glossary — balances and identifiers

​Balance fields

​Coupon identifiers

​Error Handling

​Next Steps

Authentication

Webhook Setup

API Reference

Partner Onboarding

Prerequisites

Step 1: Verify Your API Key

Step 2: Send a Test Webhook

Step 3: Look Up the Customer

Step 4: Check Points Balance

You’re Integrated!

Field Glossary — balances and identifiers

Balance fields

Coupon identifiers

Error Handling

Next Steps