This document outlines the behavior and intended usage patterns of the Custom Integration’s Offer API used for integrating external systems with our platform. The API supports two operational modes for offer ingestion: Synchronize and Insert. Each mode impacts how incoming offer data is handled, particularly in relation to existing offers already in the system.
Overview
The API is designed to be flexible and performant for external systems that maintain canonical offer data. It supports the following use cases:
Full replacement of current offers (Synchronize)
Partial update or addition of offers (Insert)
All operations are performed via a POST request to a designated endpoint, submitting a payload of offers with a specified operation mode.
Operation Modes
Synchronize
This mode ensures a 1:1 mapping between the external system and our platform. Any offers not included in the current payload will be Paused.
Suitable for systems where the full list of active offers is known at time of sync.
Offers not present in the request will be considered obsolete and paused
Insert
This mode only adds or updates offers from the payload. Offers not included in the request are untouched.
Suitable for batch-style or pipeline-style uploads.
Useful when incrementally pushing offers from a source of truth.
Detailed Behavior Tree
No Existing Offers in System
If operation =
SynchronizeSend 100 offers → 100 new offers are created.
If operation =
InsertSend 100 offers → 100 new offers are created.
100 Existing Offers in System
If operation = Synchronize
Send the same 100 offers:
If offers are identical → All 100 return:
Offer has the same dataIf offers have changes → Updated offers are overwritten; unchanged offers return:
Offer has the same data
Send 100 new offers:
All existing 100 offers are Paused
100 new offers are created
Send 50 new + 50 existing offers:
50 new offers are created
Any existing offers not in the 50 existing are Paused
For 50 existing offers:
If unchanged → return:
Offer has the same dataIf changed → full offer is updated
If operation = Insert
Send the same 100 offers:
If offers are identical → All 100 return:
Offer has the same dataIf offers have changes → Updated offers are overwritten; unchanged offers return:
Offer has the same data
Send 100 new offers:
100 new offers are created
No existing offers are Paused
Send 50 new + 50 existing offers:
50 new offers are created
No deactivation of any existing offers
For 50 existing offers:
If unchanged → return:
Offer has the same dataIf changed → full offer is updated
Additional Details
Concurrency Notes
Only one concurrent run is allowed.
Neither
SynchronizenorInsertare intended to be run concurrently for the same offer or integration.Insertis safer for asynchronous or higher-frequency pipelines, since it does not remove offers not included in the batch.
Request Limits
Synchronizemode requests are limited to once per day.Insertmode requests are limited to one batch per hour.
Best Practices
Use
Synchronizemode only if you are providing a full list of active offers from the source provider, you want in all of these offers in your GoKart inventory, and you want to maintain that inventory on each additional sync.Use
Insertmode when:You are pushing selective offers updates in chunks.
You are not including the full list of offers from the provider.
You are adding new offers without risk of removing others.
Large payloads, especially those updating many offers, may take additional time to process. Please validate that a previous submission has fully processed before submitting another.
If a request processes and then times out, please refrain from resubmitting the payload for 24 hours. The system will still process the request even if the connection was interrupted.
Always pass a
concurrencyRequestIdfor idempotency and traceability.Track offer statuses post-ingestion via the API’s response summary for
created,updated,unchanged, orpausedactions.
To ensure optimal performance and stability, we ask that you use the POST API with discretion. Your integration strategy should avoid making large, frequent calls or executing concurrent requests, as this can overload our system and degrade performance.
If you are using the API to refresh or retrieve data, we recommend implementing a more efficient strategy that reduces the frequency and size of your requests. Excessive or repeated heavy calls may result in throttling or temporary access limitations to protect platform stability.