Integration Options: REST API vs. SFTP
High level overview describing our integration options
Abstract
We offer two integration options for merchant and offer data ingestion: REST API and SFTP. While we strongly recommend REST API integration for its immediacy and ease of use and access to our entire integration package, including our Performance Reporting, SFTP remains available for partners whose needs, data volumes, or operational cadence are better suited to batch file uploads. Both options use the same JSON schema, ensuring consistency regardless of integration choice. Partners may select either method or even combine both, though we encourage picking a single primary integration path for simplicity.
Overview Table: REST API vs. SFTP
| Feature | REST API | SFTP Batch Upload |
|---|---|---|
| Recommended For | Near real-time updates, instant feedback, access to entire integration suite | Large daily data volume changes, scheduled/batch ops |
| Data Ingestion | One record per request | Full file of records per upload |
| Schema | Shared JSON schema (see docs) | Shared JSON schema (see docs) |
| Header Record | N/A | Mandatory |
| Status Field | Inferred from HTTP method | Explicit merchantStatus or offerStatus |
| Update Cadence | As changes occur (event-driven) | Daily (or as needed) |
| Error Handling | Immediate API response (HTTP code) following RFC 9457 | Errors on file processing, reported after |
| File Naming | N/A | Strict naming conventions required |
| Upload Content | Single merchant/offer per request | All current records in one file |
| Partial Updates | Yes (single record per call) | No (full dataset each time) |
| Mixing Allowed? | Yes (with care) | Yes (with care) |
| Typical Use Cases | Dynamic systems, frequent changes | Large, periodic updates, legacy flows |
| Authentication Method | OAuth 2.0 (client credentials) | SSH Key Authentication |
| Authorization Controls | Unique client IDs/secrets, access tokens, possible IP restrictions, API scopes | Unique username, registered public key, allowed IPs, directory permissions |
Integration Support Guide: REST API vs. SFTP
| Feature | REST API (Recommended) | SFTP |
|---|---|---|
| Merchant Ingestion | ✅ Supported | ✅ Supported |
| Offer Ingestion | ✅ Supported | ✅ Supported |
| Redemption Feed | ✅ Supported | ✅ Supported |
| Performance Reporting | ✅ Supported | ❌ Not Supported |
REST API Guard Rails
- Every Partner will be provided with a daily quota of the number of calls they can make, this should be ~ Number of merchant offers
- Every Partner will be provided with an RPS, for example, 10 calls per second
- API will return HTTP 429 if a Partner exceeds the quota of the daily limit or RPS
Additional Notes
- Schema Parity: Both REST API and SFTP use the same JSON schema for merchant and offer ingestion, and use the same CSV schema for redemption feed download. simplifying migration and consistency.
- Mixing Integrations: While possible, we advise choosing one method to avoid data conflicts. For partners that plan to use our entire full suite of APIs, including our Performance Reporting, our REST API is highly recommended-- as it is supported across all of our integration points and won't result in using a mixed or hybrid mode REST API and SFTP.
- Offer Deletions: When offers are deleted via either method, they will remain redeemable for customers who previously activated them until the redemption window (30–45 days) expires.
If you have questions about which integration best fits your needs, contact your technical account manager for guidance.
Updated 5 days ago