Introduction

Lomadee API Documentation

Welcome to Lomadee API

The Lomadee API enables seamless integration and programmatic management of your affiliate campaigns, brands, and orders. Our RESTful API provides comprehensive endpoints to handle all aspects of your affiliate network operations.

Base URL

Environment	URL	Status
Production	https://api.lomadee.com.br	Target URL — use for new integrations
Beta (legacy)	https://api-beta.lomadee.com.br	Available during transition; will be retired soon

The API is moving to api.lomadee.com.br. The api-beta host still works today, but plan to update your base URL before it is shut down. Paths, headers, and response formats are unchanged.

See the Changelog for migration details.

Available Resources

Brands

• List and retrieve all available brands
• Get detailed information about specific brands
• Monitor approval status and access restrictions
• Track brand performance metrics

Channels

• List all affiliate-owned channels (used for link generation)
• Get a specific channel by ID
• Channels belong to the authenticated affiliate (user_id), not to an organization

Campaigns

• List and filter active campaigns
• Campaign types:
  • PersonalCoupon: Unique coupon codes for specific users
  • GenericCoupon: Public coupon codes for general use
  • Offer: Special promotional offers and deals
• Manage campaign lifecycle:
  • Set validity periods
  • Control campaign highlights
  • Update status
  • Organize by categories and tags

Orders

• Query and track completed orders
• Monitor commission status and earnings
• View detailed item information
• Track transaction values and commission rates
• Export order reports

Products

• List and search available products across all brands
• Filter products by price range, brand, and availability
• Access detailed product information including images and specifications
• View pricing, stock levels, and product variants
• Build product catalogs and recommendation systems

Authentication

All API requests require authentication using an API key in the request header:

{
  "headers": {
    "x-api-key": "your-api-key"
  }
}

API keys are provisioned via GraphQL on the open-api service (dashboard JWT in x-api-token). See API Keys for scopes and key formats.

Each affiliate key carries granular scopes. Missing scope returns 403 Forbidden.

Pagination

Pagination shape varies by resource. Query parameters page and limit are supported where noted.

limit ceiling: maximum 20 on list endpoints that generate affiliate links (GET /affiliate/brands, GET /affiliate/campaigns). Values above 20 are clamped silently. Maximum 100 on orders, shortener, and partner list endpoints (clamp silently above 100). GET /affiliate/channels returns at most 20 channels. GET /affiliate/products returns 400 if limit is less than 1 or greater than 100.

Resource	Response pagination field	Default limit	Max limit
Brands	pagination (page, limit, total, totalPages)	20	20
Campaigns	meta	10	20
Orders	meta	10	100
Shortener URLs	meta	10	100
Products	count (total only; no page in body)	5	100
Channels	count (max 20 channels)	—	20

Example with meta (campaigns, orders, shortener):

{
  "data": [],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  }
}

Example with pagination (brands):

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Example with count (products, channels):

{
  "data": [],
  "count": 107
}

Status Codes

• 200: Success - Request completed successfully
• 400: Bad Request - Invalid parameters or malformed request
• 401: Unauthorized - API key missing, invalid, or wrong type
• 403: Forbidden - Valid key without required scope
• 404: Not Found - Resource doesn’t exist
• 429: Too Many Requests - Rate limit exceeded
• 500: Internal Server Error - Server-side error

All error responses follow:

{
  "success": false,
  "message": "Human-readable description",
  "code": "ERROR_CODE"
}

Rate limiting

Global limit: 60 requests per 60 seconds per API key and client IP.

Every response may include:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

When exceeded, the API returns 429 with Retry-After (seconds until retry) and X-RateLimit-Limit, X-RateLimit-Remaining (0), and X-RateLimit-Reset.

API Limits and Quotas

• Rate limiting: 60 requests per 60 seconds (per key + IP)
• Maximum payload size: 1MB per request
• Request timeout: 60 seconds

Best Practices

1. Implement proper error handling
2. Use pagination for large datasets
3. Cache responses when appropriate
4. Monitor rate limits
5. Validate request parameters

Support and Resources

For technical assistance and API-related questions:

1. Comprehensive API Documentation
2. Technical Support Portal
3. Developer Portal with:
   • API Reference
   • Code Examples
   • SDK Downloads
   • Integration Guides