Order Management Systems

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	DevOps/Integration Team	One-time setup	Establish automated OMS ↔ Topsort sync
Campaign Creation	Campaign Managers/Sales Teams	Per campaign	Create campaigns automatically from OMS data
Performance Sync	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

Tip

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

// 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

// 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	Create campaigns with bidding strategy, budget, targeting	✅ Available	Full campaign lifecycle management
Assets API	Reference asset URLs in campaigns	✅ Available	Asset management and collections
Reporting API	Pull performance data back to OMS/dashboards	✅ Available	Campaign, vendor, marketplace reports
Auctions API	Configure auction parameters and bidding	✅ Available	Auction configuration

Authentication

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Bulk Campaign Operations

// 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

// 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

Caution

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

1. API Access Setup

   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

2. Webhook Configuration

   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

3. Data Field Mapping

   Map OMS campaign fields to Topsort API parameters:

   • Document field mappings between systems
   • Implement data transformation logic
   • Validate required fields are present

4. Error Handling Implementation

   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

5. Testing and Validation

   Test integration with sandbox data before production:

   • Create test campaigns through OMS workflow
   • Verify campaigns appear correctly in Topsort
   • Test webhook delivery and handling

6. Monitoring and Maintenance

   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 - Digital Asset Management connectivity
• Campaign API Documentation
• Reporting API Documentation

---

Ready to integrate your OMS with Topsort? Contact your account representative to get started with API access and implementation support.