> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Order Management Systems
> Connect Topsort APIs with Order Management Systems for campaign orchestration
export const LastUpdated = ({date, lang = "en"}) => {
const translations = {
en: "Last updated:",
es: "Última actualización:",
pt: "Última atualização:",
fr: "Dernière mise à jour:",
de: "Zuletzt aktualisiert:"
};
const label = translations[lang] || translations.en;
return <>
;
};
# Connecting Topsort with Order Management Systems
**Order Management Systems (OMS)** like Vantage, Boostr, ADvendio, and Placements.io help retailers manage campaign planning, booking, and inventory. You can integrate these systems with Topsort's APIs to automate campaign creation and management.
This guide shows how to integrate OMS with Topsort using existing APIs for automated campaign workflows.
## Workflows
OMS integration involves three main workflows for different roles and timing:
| **Workflow** | **Who** | **When** | **Purpose** |
| ------------------------------------------------------------------- | ----------------------------- | -------------- | --------------------------------------------- |
| [Implementation Guide](#implementation-guide) | DevOps/Integration Team | One-time setup | Establish automated OMS ↔ Topsort sync |
| [Campaign Creation](#creating-campaigns-from-oms-data) | Campaign Managers/Sales Teams | Per campaign | Create campaigns automatically from OMS data |
| [Performance Sync](#retrieving-performance-data-for-oms-dashboards) | Marketing Teams | Ongoing | Pull campaign performance into OMS dashboards |
## How OMS Integration Works
1. **Campaign Planning**: Sales teams plan campaigns in their OMS interface
2. **Automated Creation**: OMS sends campaign data to Topsort via API calls
3. **Real-time Updates**: Webhook notifications keep systems synchronized
4. **Unified Reporting**: Performance data flows back to OMS dashboards
**Enterprise Benefit**: OMS integration eliminates manual campaign setup,
reducing errors and enabling sales teams to manage campaigns at scale without
learning new tools.
## Implementation Example
### Creating Campaigns from OMS Data
**Role:** Campaign Managers/Sales Teams | **Frequency:** Per campaign
```javascript theme={null}
// Campaign data from your OMS
const campaignData = {
name: "Q4 Holiday Campaign - Brand X",
budget: 15000,
startDate: "2024-11-01",
endDate: "2024-12-31",
biddingStrategy: "target_roas",
targetRoas: 4.5,
vendorId: "vendor-123",
};
// Create campaign in Topsort
const response = await fetch("https://api.topsort.com/v2/campaigns", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: campaignData.name,
type: "sponsored_products",
vendor_id: campaignData.vendorId,
bidding_strategy: campaignData.biddingStrategy,
target_roas: campaignData.targetRoas,
budget: {
amount: campaignData.budget,
currency: "USD",
period: "lifetime",
},
start_date: campaignData.startDate,
end_date: campaignData.endDate,
}),
});
const campaign = await response.json();
```
### Webhook Integration for Real-time Updates
```javascript theme={null}
// Set up webhook to receive campaign updates
const webhookPayload = {
url: "https://your-oms.com/webhooks/topsort",
events: ["campaign:create", "campaign:update", "campaign:delete"],
};
await fetch("https://api.topsort.com/v2/webhooks", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify(webhookPayload),
});
// Handle webhook in your OMS
app.post("/webhooks/topsort", (req, res) => {
const { channel, payload } = req.body;
switch (channel) {
case "campaign:create":
updateOMSCampaignStatus(payload.campaign_id, "active");
break;
case "campaign:update":
syncCampaignData(payload);
break;
}
res.status(200).send("OK");
});
```
## API Reference
### Current Topsort APIs for Integration
| API | Integration Use Case | Status | Documentation |
| ------------------------------------------------------------ | --------------------------------------------------------- | ----------- | ------------------------------------- |
| [Campaign API](/en/ad-server/additional-apis/campaign-api) | Create campaigns with bidding strategy, budget, targeting | ✅ Available | Full campaign lifecycle management |
| [Assets API](/en/ad-server/additional-apis/assets-api) | Reference asset URLs in campaigns | ✅ Available | Asset management and collections |
| [Reporting API](/en/ad-server/additional-apis/reporting-api) | Pull performance data back to OMS/dashboards | ✅ Available | Campaign, vendor, marketplace reports |
| [Auctions API](/en/ad-server/auctions/auctions-api) | Configure auction parameters and bidding | ✅ Available | Auction configuration |
### Authentication
```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```
### Bulk Campaign Operations
```javascript theme={null}
// Create multiple campaigns from OMS batch
async function createBulkCampaigns(campaignsList) {
const results = [];
for (const campaignData of campaignsList) {
try {
const response = await fetch("https://api.topsort.com/v2/campaigns", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify(campaignData),
});
const campaign = await response.json();
results.push({ success: true, campaign });
} catch (error) {
results.push({ success: false, error: error.message });
}
}
return results;
}
```
### Retrieving Performance Data for OMS Dashboards
**Role:** Marketing Teams | **Frequency:** Ongoing/Scheduled
```javascript theme={null}
// Pull campaign performance back to OMS
async function syncPerformanceData(campaignId) {
const reportResponse = await fetch(
`https://api.topsort.com/v2/reports/campaigns/${campaignId}`,
{
method: "GET",
headers: {
Authorization: "Bearer YOUR_API_KEY",
},
}
);
const performanceData = await reportResponse.json();
// Update OMS dashboard with performance metrics
await updateOMSDashboard(campaignId, {
impressions: performanceData.impressions,
clicks: performanceData.clicks,
spend: performanceData.spend,
conversions: performanceData.conversions,
});
}
```
## Best Practices
### Data Synchronization
* **Field Mapping**: Map OMS campaign fields to Topsort API parameters
* **Data Validation**: Validate campaign data before sending to Topsort APIs
* **Bulk Operations**: Use batch processing for enterprise-scale campaign management
### Error Handling
* **Retry Logic**: Implement exponential backoff for failed API calls
* **Comprehensive Logging**: Track all API interactions and failures
* **Health Monitoring**: Set up alerts for integration issues
### Security
**Security Requirements**: OMS integrations handle sensitive campaign and
financial data. Ensure proper authentication, data validation, and secure API
key management.
* **API Key Management**: Store API keys securely and rotate regularly
* **Rate Limiting**: Respect API rate limits to avoid throttling
* **Input Sanitization**: Validate all data before sending to APIs
## Implementation Guide
Obtain Topsort API keys and configure authentication:
* Request Advanced API key from your Topsort representative
* Store API keys securely in your environment variables
* Configure authentication headers for all API calls
Set up webhook endpoints for real-time campaign updates:
* Create webhook endpoint in your OMS system
* Register webhook URL with Topsort for campaign events
* Implement handlers for campaign create/update/delete events
Map OMS campaign fields to Topsort API parameters:
* Document field mappings between systems
* Implement data transformation logic
* Validate required fields are present
Build comprehensive error handling and retry logic:
* Implement exponential backoff for failed API calls
* Add comprehensive logging for debugging
* Set up alerts for integration failures
Test integration with sandbox data before production:
* Create test campaigns through OMS workflow
* Verify campaigns appear correctly in Topsort
* Test webhook delivery and handling
Set up ongoing monitoring for the integration:
* Track API call success/failure rates
* Monitor campaign creation performance
* Set up dashboards for integration health
## Related Resources
* [DAM Integration Guide](/en/knowledge-base/ad-server/dam-connectivity) - Digital Asset Management connectivity
* [Campaign API Documentation](/en/ad-server/additional-apis/campaign-api)
* [Reporting API Documentation](/en/ad-server/additional-apis/reporting-api)
***
*Ready to integrate your OMS with Topsort? Contact your account representative to get started with API access and implementation support.*
***