REST API
Merchant Ingestion: Learn about how partners providing Cardlytics with comprehensive information about their merchants, including their brands and store locations
Quick Links:
🚀 Try the API → Jump straight into testing the Merchant Ingestion endpoints.
📖 View Complete API Reference → Explore all endpoints, schemas, and examples.
Abstract
This document describes the REST API integration option for merchant data management, designed to enable near real-time updates and easier integration. The REST API JSON schema can be found here. One merchant is processed per request, and the merchant status is inferred from the HTTP method (PUT for upsert, DELETE for removal).
The API processes one merchant record per request. Partners use the endpoint PUT /api/v1/partner/merchants/{external_merchant_id} to create or update merchant records, and DELETE /api/v1/partner/merchants/{external_merchant_id} to remove a merchant. Requests are made using the partner’s own merchant ID and only need to be sent when changes occur. The API responses confirm that requests have been accepted for processing.
This approach streamlines merchant updates and deletions, ensuring efficient and timely data synchronization.
How It Works
- In addition to SFTP, we also provide a REST API to make it easier to enable near real-time merchant updates instead of the daily merchant file dump
- We will use the same JSON schema as defined for SFTP to have 1:1 parity, but with the following differences:
- No Header Record.
- No Merchant Status - it will be derived from the HTTP method, HTTP Method
PUT->merchantStatus=UPSERT”, HTTP MethodDELETE->merchantStatus=DELETED - One Merchant Record at a time.
Recommendations on how to call
- Partner begins with calling the Merchant endpoint
PUT /api/v1/partner/merchants/{external_merchant_id}one merchant at a time within the limits of the RPS. - The partner doesn’t need to resend the same merchant again unless there are any changes to the merchant details or the merchant needs to be taken down.
- To update a merchant, the partner must call the same endpoint
PUT /api/v1/partner/merchants/{external_merchant_id}as used for the creation. - To delete a merchant partner must call the
DELETE /api/v1/partner/merchants/{external_merchant_id}endpoint with no request payload.
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
Create or Update the Merchant details using the self-provided merchant ID
| Hostname (Production) | api.cardlytics.com |
|---|---|
| Hostname (Sandbox) | api-sandbox.cardlytics.com |
| Endpoint | /api/v1/partner/merchants/{external_merchant_id} |
| Method | PUT |
| Content-Type | application/json |
| Request Payload | Payload |
| Response | {"message":"Request accepted for processing", "trace_id": "req-98765" } |
Delete the Merchant using the self-provided merchant ID
| Hostname | api.cardlytics.com |
|---|---|
| Hostname (Sandbox) | api-sandbox.cardlytics.com |
| Endpoint | /api/v1/partner/merchants/{external_merchant_id} |
| Method | DELETE |
| Content-Type | application/json |
| Response | { "message":"Request accepted for processing", "trace_id": "req-98765" } |
Sample Request
{
"merchantId": "12345",
"merchantName": "Luigi's Pizza",
"merchantCategoryCode": "5812",
"merchantUrl": "www.abc.com",
"merchantSubCategories":
[
{
"categoryType": "cuisine",
"categoryItems":
[
"Continental",
"American"
]
}
],
"paymentChannels":
[
"instore"
],
"stores":
[
{
"storeId": "1001",
"storeName": "Luigi's Pizza Main St",
"storeUrl": "www.abc.com/mainSt",
"address1": "123 Main St",
"city": "NEWTOWN",
"state": "CT",
"postalcode": "06470",
"countryCode": "US",
"latitude": "37.7661",
"longitude": "-122.3958",
"storePhoneNumbers":
[
"+18881234567"
],
"storeEmails":
[
"[email protected]"
],
"processorMidChangedFlag": "N",
"processorMidRecords":
[
{
"paymentNetwork": "AmericanExpress",
"processors":
[
{
"processorName": "AmericanExpress",
"amexMids":
[
{
"seNumber": "1234567890"
}
]
}
]
},
{
"paymentNetwork": "MasterCard",
"processors":
[
{
"processorName": "Elavon",
"mcAuthMids":
[
{
"mcAuthLocationId": "111222333",
"mcAuthAcquiringMid": "444445555566666",
"mcAuthICA": "012222"
}
],
"mcClearingMids":
[
{
"mcClearingLocationId": "111222333",
"mcClearingAcquiringMid": "444445555566666",
"mcClearingICA": "12222"
}
]
}
]
},
{
"paymentNetwork": "Visa",
"processors":
[
{
"processorName": "Fiserv",
"processorId": "FISV123",
"visaMids":
[
{
"vmid": "12345678",
"vsid": "11444455"
}
]
},
{
"processorName": "Worldpay",
"processorId": "WORLDPAY99",
"visaMids":
[
{
"vmid": "87654321",
"vsid": "99887766"
}
]
}
]
},
{
"paymentNetwork": "Discover",
"processors":
[
{
"processorName": "Discover",
"discoverMids":
[
{
"discover": "4445040865057"
},
{
"discover": "4445068632298"
}
]
}
]
}
]
}
]
}
Interactive API TestingReady to test the API? 👉 Visit our Interactive API Reference to try out endpoints with real requests.
Updated 5 days ago