Skip to main content

SocialLadder Public API Production Changelog

Written by Marshall
Updated over 6 months ago

This document contains a changelog for the SocialLadder Public APIs

Release: October 20, 2025

Endpoints: /SocialLadderAPI/api/v1/portal/agent/* and /SocialLadderAPI/api/v1/automation/*

Changes:

  • Beta API Endpoints Removed from Swagger Documentation

Reason for Removal:

These endpoints are part of the SL Agent AI automation platform currently in beta testing. They were inadvertently exposed in the public Swagger documentation before the feature was ready for general availability.

Functional Impact:

  • Public Documentation: These endpoints no longer appear at https://socialladder.rkiapps.com/swagger/ui/index#

  • Functionality: The endpoints remain fully functional for internal/beta users with proper authentication

  • Existing Integrations: No impact - these were beta endpoints with no public integrations

  • API Access: Endpoints still accessible via direct API calls with valid automation-scoped API keys

Release: September 19, 2025

Endpoint: POST /SocialLadderAPI/api/v1/ambassador/{ambassadorId}/vanityCode (Enhanced)

Changes:

  • Added isPromotional parameter to distinguish between standard and promotional voucher codes

  • Enhanced error handling to return proper response messages

  • Improved validation to check response codes before returning success

Functional Impact:

  • Supports creation of promotional codes with specific tracking

  • Better error handling returns specific error messages (duplicate code, invalid code, etc.)

  • Enables differentiation between regular ambassador codes and temporary promotional codes

  • Campaign managers can track promotional code performance separately

Breaking Change: No (Optional parameter with default value)

Endpoint: PUT /SocialLadderAPI/api/v1/ambassador/{ambassadorId}/vanityCode (Enhanced)

Changes:

  • Updated error messages from "vanity code" to "voucher code" for consistency

  • Changed "Vanity code not found" to "Voucher code not found" in 404 response

Functional Impact:

  • Consistent terminology in API responses

  • Aligns with product naming conventions (voucher code instead of vanity code)

  • No functional change, only messaging improvement

Breaking Change: No (Error message wording only)

NEW Endpoint: GET /SocialLadderAPI/api/v2/ambassador/{ambassadorId}/vanityCode

Changes:

  • New v2 endpoint returning ALL vanity codes for an ambassador with promotional flag

  • Returns array of codes instead of single first code

  • Includes IsPromotional flag for each code

Response Example:

{
  "DiscountCodes": [
    {
      "DiscountCode": "AMBASSADOR2025",
      "IsPromotional": false
    },
    {
      "DiscountCode": "SUMMER50",
      "IsPromotional": true
    },
    {
      "DiscountCode": "FLASH24HR",
      "IsPromotional": true
    }
  ]
}

Comparison with v1:

  • v1: Returns only first code as single string (GET /api/v1/ambassador/{id}/vanityCode)

  • v2: Returns all codes with promotional flag (GET /api/v2/ambassador/{id}/vanityCode)

Functional Impact:

  • API consumers can see all codes assigned to ambassador, not just primary code

  • Distinguish between standard and promotional codes for analytics

  • Support use cases where ambassadors have multiple active codes

  • Better tracking of promotional campaign performance

Breaking Change: No (New endpoint, v1 unchanged)

Migration Guidance:

  • v1 endpoint remains available for backward compatibility

  • Use v2 when you need complete list of codes or promotional tracking

  • v1 returns first code only - suitable for single-code ambassadors

Release: June 4, 2025

Endpoint: POST /SocialLadderAPI/api/v1/sso/autoregister (Enhanced)

Changes:

  • Enhanced auto-registration endpoint for programmatic ambassador creation

  • Handles race conditions when multiple registration requests are made simultaneously

  • Updated to use new stored procedure for better performance

  • Enhanced logging for failure case debugging

Key Features:

  • Race condition handling prevents duplicate profile creation

  • Empty custom field values handled gracefully (not rejected)

  • Empty vanity codes allowed (system will generate unique code)

  • Atomic database operations prevent partial registrations

  • Detailed logging captures request data on failure

Functional Impact:

  • Enables bulk ambassador onboarding from external systems

  • Prevents duplicate profile creation during concurrent requests

  • Improves integration reliability with CRM systems

  • Better error handling and debugging capabilities

Breaking Change: No (Enhanced functionality)

Release: May 23, 2025

Endpoint: GET /SocialLadderAPI/api/v1/ambassador

Changes:

  • Added activeOnly parameter to filter results by ambassador status

  • When true, excludes ambassadors with "Unsubscribed" or "Unregistered" status

  • Helps API consumers get only actionable ambassadors

Functional Impact:

  • Simplifies filtering to active ambassadors

  • Reduces data transfer for API consumers who only need active users

  • Improves performance by filtering at database level

  • Useful for integrations that sync active ambassadors only

Breaking Change: No (Optional parameter with default value preserves existing behavior)

All Endpoints: Infrastructure Change

Changes:

  • Changed base class from ApiController to BaseApiController

  • Added Request.Properties["AreaId"] = AreaId for improved logging on GET v2, POST v2, and PUT v2 endpoints

  • Added using SCS.Controllers; namespace

Functional Impact:

  • Improved API logging and tracking capabilities

  • Better debugging support with area context in logs

  • No breaking changes to API behavior or response models

Breaking Change: No

Release: May 12, 2025

Endpoint: POST /api/v1/conversion, POST /api/v2/conversion, PUT /api/v2/conversion

Changes:

  • Removed duplicate SKU validation that blocked conversions with duplicate line items

  • Removed error: "Duplicate SKU on line items is not currently supported"

Functional Impact:

  • API now accepts conversions with duplicate SKUs (e.g., same product purchased multiple times)

  • Eliminated BadRequest (400) errors for valid use cases

  • Critical fix for merchants selling multiple quantities of same SKU in single order

Breaking Change: No (Expanded functionality)

Release: April 30, 2025

Endpoint: POST /api/v2/conversion, PUT /api/v2/conversion

Changes:

  • Added proper HttpResponseException handling to preserve error details

  • Added new catch block before generic Exception handler

Functional Impact:

  • Validation errors now return proper status codes (e.g., 400 BadRequest, 401 Unauthorized)

  • Error messages are preserved and returned to API clients

  • Improved debugging experience for API consumers

  • Better distinction between validation errors and unexpected errors

Breaking Change: No

Release: April 18, 2025

Endpoint: GET /api/v1/conversion, GET /api/v2/conversion

Changes:

  • Fixed pagination logic to only return PreviousPageURL when exactly 200 records are returned

Functional Impact:

  • PreviousPageURL now only appears when there are more pages to fetch (200 = max page size)

  • Clients can now reliably determine if more data is available

  • Last page returns empty string for PreviousPageURL instead of URL to same page

  • Prevents infinite pagination loops

Breaking Change: No (Improved behavior)

Release: April 11, 2025

Endpoint: GET /api/v1/conversion, GET /api/v2/conversion

Changes:

  • Enabled PreviousPageURL in GET responses for pagination support

  • Previously commented out, now actively returns pagination URL

  • Sets empty string when no more pages available

Functional Impact:

  • Clients can now paginate through conversion data using PreviousPageURL

  • Improved URL construction using GetHostFromHTTPRequestMessage for better proxy support

  • Response now includes beforeID parameter for next page navigation

Breaking Change: No (New functionality)

Release: April 2, 2025

Endpoint: POST /api/v1/conversion, PUT /api/v1/conversion, POST /api/v2/conversion, PUT /api/v2/conversion

Changes:

  • Added API Key validation against Shop Code for all POST and PUT endpoints

  • Added new 401 Unauthorized error: "Invalid ApiKey for Shop Code"

  • Updated POST v2 to pass areaId parameter to APIConversion method

  • Modified isResidual parameter handling from ternary to logical AND

Functional Impact:

  • Enhanced security: API key must now match the shop code in the request

  • Prevents cross-shop data submission with valid but wrong API key

  • Multi-shop merchants must use correct API key for each shop

  • Returns 401 Unauthorized if shop code doesn't match API key

Breaking Change: Yes - Previously accepted requests may now be rejected if wrong API key used for shop

Endpoint: POST /SocialLadderAPI/api/v1/sso/autoregister

Changes:

  • Fixed handling of empty custom data field values

  • Fixed handling of empty vanity code values

  • Previously rejected empty values, now accepts and handles appropriately

Functional Impact:

  • More flexible API - optional fields truly optional

  • Reduces integration errors from empty string values

  • System auto-generates vanity codes when needed

Breaking Change: No (Expanded functionality)

Release: March 31, 2025

NEW Endpoint: POST /SocialLadderAPI/api/v1/sso/autoregister

Changes:

  • Initial implementation of auto-register endpoint

  • Enables programmatic ambassador registration for external integrations

  • Supports custom data fields and vanity code assignment

Request Model:

{
  "apiKey": "your-api-key",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+15551234567",
  "customDataFields": [
    {"key": "membershipLevel", "value": "Gold"},
    {"key": "sponsor", "value": "ABC123"}
  ],
  "vanityCode": "JOHN2025",
  "sendWelcomeEmail": true
}

Response Model:

{
  "Result": 1,
  "ResponseMessage": "Ambassador registered successfully",
  "Data": {
    "ambassadorId": 12345,
    "profileUrl": "https://brand.socialladder.com/ambassador/JOHN2025",
    "trackingLink": "https://brand.socialladder.com/r/JOHN2025"
  }
}

Functional Impact:

  • Automates ambassador onboarding from external systems (CRM, e-commerce)

  • Eliminates manual data entry

  • Maintains data consistency across platforms

  • Supports white-label deployments with custom vanity codes

Breaking Change: No (New endpoint)

Release: March 28, 2025

Endpoint: POST /api/v2/conversion

Changes:

  • Removed isResidual and originalOrderID as separate URL parameters

  • These values now come only from the request body (conversion object)

  • Cleaned up parameter list and Swagger documentation

Functional Impact:

  • Simplified API signature - reduced parameter count

  • IsResidual and OriginalOrderId now sourced from request body only

  • Eliminated potential conflict between URL parameters and body properties

  • Cleaner Swagger documentation

Breaking Change: Yes - Clients using URL parameters isResidual or originalOrderID must move to body properties

Release: March 28, 2025

Endpoint: GET /api/v1/conversion, POST /api/v1/conversion, PUT /api/v1/conversion

Changes:

  • Reverted response and request models to V1-specific types

  • Changed from generic models to versioned models for v1 endpoints

Model Changes:

  • Response: AmbassadorConversionAPIResponseModel → AmbassadorConversionAPIResponseModelV1

  • POST Request: AmbassadorConversionRequest → AmbassadorConversionRequestV1

  • PUT Request: AmbassadorConversionPutRequest → AmbassadorConversionRequest

Functional Impact:

  • Isolated v1 and v2 API models to prevent version conflicts

  • v1 models maintain backward compatibility without v2 fields

  • PUT endpoint model changed from AmbassadorConversionPutRequest to generic AmbassadorConversionRequest

  • Prepares for long-term support of both v1 and v2 endpoints

Breaking Change: No (Internal model changes, same JSON structure)

Release: March 27, 2025

Endpoint: PUT /api/v2/conversion

Changes:

  • Added AreaId parameter to ConversionManager.UpdateConversion() call

  • Added using Newtonsoft.Json; namespace for JSON handling

  • Enables logging of conversion updates with area context

Functional Impact:

  • Backend can now log which area made the update request

  • Improved audit trail for conversion modifications

  • Better debugging and support for multi-area accounts

  • Enables tracking of return reasons and change history

Breaking Change: No

Release: March 27, 2025

Endpoint: GET /api/v2/conversion

Changes:

  • Renamed query parameter from maxUpdateDate to minUpdateDate

  • Changed filter logic from "at or before" to "at or after"

Functional Impact:

  • Changed from historical filter (before date) to recent filter (after date)

  • More useful for incremental sync scenarios

  • Clients can fetch conversions updated since last sync

  • Better alignment with common API integration patterns

Breaking Change: Yes - Parameter name and logic changed. Clients using maxUpdateDate must update to minUpdateDate and reverse date logic.

Release: March 26, 2025

NEW Endpoint: GET /api/v2/conversion (BETA)

Changes:

  • Created new v2 GET endpoint with enhanced filtering capabilities

  • Added parameters: trackingKey, showDeletedProducts, minUpdateDate

  • Routes to new ConversionManager.GetConversionsForAPI() method instead of legacy UserManager

  • Includes pagination support with PreviousPageURL

New Parameters:

  • trackingKey - The tracking key of ambassador's link</param>

  • showDeletedProducts - Include returned items on the result?</param>

  • minUpdateDate - Show conversions updated at or after date</param>

Functional Impact:

  • Filter conversions by ambassador tracking key

  • Include or exclude returned/refunded products

  • Incremental sync support via minUpdateDate

  • Uses enhanced ConversionManager with product-level details

  • Better performance and more granular data access

Breaking Change: No (New endpoint)

Release: March 26, 2025

NEW Endpoint: POST /api/v2/conversion (BETA)

Changes:

  • Created new v2 POST endpoint with automatic calculation of totals from line items

  • Added support for ProductList with automatic TransAmount and TransUnits calculation

  • Added support for customer data: CustomerID, CustomerFirstName, CustomerLastName

  • Added support for residual/subscription conversions: IsResidual, OriginalOrderId

  • Added duplicate SKU validation (removed in later release)

  • Routes to same CampaignManager.APIConversion() with additional parameters

New Request Body Fields:

  • ProductList - Array of line items with SKU, Value, Units, etc.

  • CustomerID - External customer identifier

  • CustomerFirstName - Customer first name

  • CustomerLastName - Customer last name

  • IsResidual - Boolean flag for subscription/recurring payments

  • OriginalOrderId - Reference to original order for residual conversions

Functional Impact:

  • Submit detailed line-item data for commission calculation

  • Automatic total calculation eliminates manual math errors

  • Support for subscription/recurring revenue tracking

  • Customer data stored with conversion for reporting

  • Better attribution and commission accuracy at product level

Breaking Change: No (New endpoint)

Release: March 26, 2025

NEW Endpoint: PUT /api/v2/conversion (BETA)

Changes:

  • Created new v2 PUT endpoint for updating conversions

  • Routes to new ConversionManager.UpdateConversion() instead of CampaignManager.UpdateITBAttribution()

  • Supports updating line-item level data

  • Added duplicate SKU validation (removed in later release)

  • More comprehensive update support than v1

Functional Impact:

  • Enhanced update capabilities beyond just amount and units

  • Product-level updates supported via ProductList

  • Better validation and error handling

  • Consistent with v2 POST endpoint model structure

Breaking Change: No (New endpoint)

Release: March 18, 2025

Endpoint: GET /api/v1/conversion

Changes:

  • Updated documentation to indicate trackingKey and showDeletedProducts parameters are "Not functional until 03/26"

  • Added stubbed out placeholders "Test" data responses for upcoming V2 endpoints

Functional Impact:

  • Preview of upcoming v2 functionality in v1 endpoint signature

  • Test data injection for specific client areas during development

  • Parameters documented but not yet functional

  • Enabled testing of new response model structure before v2 launch

Breaking Change: No (Parameters ignored, documentation only)

Release: March 18, 2025

Endpoint: POST /api/v1/conversion

Changes:

  • Updated documentation to indicate new parameters "Not functional until 03/26"

  • Added conversionCookieGUID, isResidual, originalOrderID to method signature (not yet used)

Functional Impact:

  • Preview of upcoming functionality

  • Parameters accepted but not processed

  • Swagger documentation updated to show future capabilities

  • No behavior changes

Breaking Change: No

Endpoint: PUT /api/v1/conversion

Changes:

  • Changed request model from AmbassadorConversionRequest to AmbassadorConversionPutRequest

  • Specialized model for PUT operations

Functional Impact:

  • Dedicated model for PUT operations with appropriate fields

  • Clearer API contract for update operations

  • May exclude create-only fields from PUT request model

Breaking Change: No (Same JSON structure expected)

NEW Endpoint: PUT /SocialLadderAPI/api/v1/ambassador/{ambassadorId}/vanityCode

Changes:

  • New endpoint to update vanity code status (activate or delete/deactivate)

  • Allows programmatic management of ambassador discount codes

  • Supports "ACTIVE" and "DELETED" status values

Request Example:

PUT /SocialLadderAPI/api/v1/ambassador/12345/vanityCode?apiKey=abc123&vanityCode=AMBASSADOR2025&status=DELETED

Response Example (Success):

{
  "DiscountCode": "AMBASSADOR2025"
}

Error Responses:

  • 401 Unauthorized: Invalid API key

  • 400 BadRequest: Empty vanity code

  • 400 BadRequest: Invalid status (must be 'ACTIVE' or 'DELETED')

  • 400 BadRequest: Invalid ambassador ID (not in area)

  • 404 NotFound: Vanity code not found for ambassador

  • 500 InternalServerError: Unexpected error

Functional Impact:

  • Enables programmatic code lifecycle management (activate/deactivate codes)

  • Supports automated code rotation for security

  • Integration with e-commerce platforms for temporary promotional codes

  • Allows deactivation of codes without permanent deletion (can be reactivated)

Use Cases:

  1. Security: Deactivate compromised codes immediately via API

  2. Code Rotation: Automated rotation of ambassador codes for compliance

  3. Seasonal Campaigns: Activate/deactivate codes based on campaign schedule

Breaking Change: No (New endpoint)

Release: August 29, 2024

Endpoint: POST /api/v1/conversion

Changes:

  • Updated source parameter value from "Conversion API" to "SL API - Conversion"

  • Standardized source naming convention

Functional Impact:

  • Changed source attribution label in backend logging and reporting

  • Standardized naming convention across API endpoints

  • No change to API behavior or validation

Breaking Change: No

NOTE: For Changelogs prior to August 2024 - Reach out to Support.

Did this answer your question?