Skip to main content
OPLOG’s SalesOrder API provides comprehensive order management capabilities for various business scenarios. This guide covers the essential requirements, configurations, and examples for creating different types of sales orders.

​
Integration Overview

The SalesOrder API is designed to handle multiple business models:
  • E-commerce Integration - Direct website orders with payment processing
  • Marketplace Integration - Orders from platforms like Amazon, Trendyol, etc.
  • B2B Orders - Corporate orders with specialized billing requirements
  • Cross-border Orders - International shipping with currency support
All orders must include unique reference numbers, customer information, and delivery addresses. Optional features like gift services and document attachments enhance the customer experience.

​
Creating Orders

OPLOG’s SalesOrder POST endpoint has several required fields that you need to be aware of:

Quick Start Requirements

Essential Fields: Reference number, sales channel, customer info, addresses, line items, and payment details are mandatory for all orders.

​
Core Requirements

{
  "referenceNumber": "ORD-2025-001"  // Unique order identifier
}
Requirements:
  • Unique identifier for each order in OPLOG.One system
  • Maximum 30 characters
  • Cannot contain ”_” characters
  • Must be unique across all orders
Examples:
  • "ORD-2025-001" ✅
  • "MOBILE_ORDER_123" ❌ (contains underscore)
  • "VERY_LONG_ORDER_REFERENCE_NUMBER_EXAMPLE" ❌ (exceeds 30 chars)
{
  "salesChannel": "mystore.com"  // Channel where order was placed
}
Purpose: Identifies the platform or channel where the order originatedCommon Values:
  • "Trendyol" - Trendyol marketplace
  • "Web" - Website orders
  • "Mobile App" - Mobile application
  • "mystore.com" - Custom domain/channel
  • "b2b.company.com" - B2B portal
{
  "customer": {
    "email": "customer@example.com",     // Unique customer email
    "firstName": "John",                 // Customer's first name
    "lastName": "Smith",                 // Customer's last name
    "phone": "+12125551234"              // Phone with country code
  }
}
Required Fields:
  • email - Must be unique customer email address
  • firstName - Customer’s first name
  • lastName - Customer’s last name
  • phone - Must start with country code
Phone Format Examples:
  • "+12125551234" ✅ (US)
  • "+905551234567" ✅ (Turkey)
  • "+4915512345678" ✅ (Germany)
  • "5551234567" ❌ (missing country code)

​
Address Requirements

Address requirements vary by location and order type. Both shipping and billing addresses follow the same structure.
{
  "shippingAddress": {
    "addressFirstName": "John",           // Recipient first name
    "addressLastName": "Smith",           // Recipient last name
    "addressOne": "123 Main Street",      // Primary address line
    "addressTwo": "Apt 45",               // Secondary address (optional)
    "district": "Manhattan",              // District/State
    "city": "New York",                   // City name
    "country": "United States",           // Country name
    "postalCode": "10001",                // Postal/ZIP code
    "addressPhone": "+12125551234"         // Contact phone
  }
}
Required Fields (All Locations):
  • addressFirstName - Recipient’s first name
  • addressLastName - Recipient’s last name
  • addressOne - Primary address line
  • city - City name
  • country - Country name
  • addressPhone - Phone number with country code
Location-Specific Requirements:🇹🇷 Turkey:
  • district - Must use specified values from Turkey location list
  • city - Must use specified values from Turkey location list
  • postalCode - Optional
🌍 International:
  • postalCode - Mandatory for all international addresses
  • district - Optional (can be state/province)
Optional Fields:
  • addressTwo - Additional address information
  • company - Company name (for corporate orders)
  • taxOffice - Tax office (for billing addresses in Turkey)
  • taxNumber - Tax number (for corporate billing)
Address fields support ISO 19160 format for international standardization.

​
Line Items

Each product in the order requires specific information for proper processing.
{
  "lineItems": [
    {
      "amountInOrder": 2,                    // Quantity ordered
      "sku": "LAPTOP-001",                   // Product identifier
      "productSalePrice": 1200.00,           // Unit price
      "currency": "USD"                      // Currency code
    }
  ]
}
Required Fields:
  • amountInOrder - Quantity of the product being ordered
    • Must be a positive integer
    • Example: 2 for ordering 2 units
  • sku - Unique product identifier
    • Used to identify the specific product in your catalog
    • Example: "LAPTOP-001", "PHONE-PRO-128GB"
  • currency - ISO 4217 currency code
    • Mandatory for Turkey to international orders
    • Mandatory for COD (Cash on Delivery) orders
    • Examples: "USD", "EUR", "TRY", "GBP"
Optional Fields:
  • productSalePrice - Unit price of the product
    • Used for pricing calculations and invoicing
    • Should match your product catalog pricing
Multiple Products Example:
{
  "lineItems": [
    {
      "amountInOrder": 1,
      "sku": "LAPTOP-001",
      "productSalePrice": 1200.00,
      "currency": "USD"
    },
    {
      "amountInOrder": 2,
      "sku": "MOUSE-WIRELESS",
      "productSalePrice": 25.00,
      "currency": "USD"
    }
  ]
}

​
Payment Options

For COD orders, totalPaymentAmount field is mandatory and must be accurate.
1

Choose Payment Method

Select from Paid, CreditCard, or Cash (COD) based on your business model
2

Set Payment Amount

Ensure totalPaymentAmount matches the order total
3

Specify Currency

Use ISO 4217 currency codes (USD, EUR, TRY, etc.)
{
  "payment": {
    "paymentOption": "Paid",               // Payment method
    "totalPaymentAmount": 2400.00,         // Total amount
    "currency": "USD"                      // Payment currency
  }
}
Required Fields:
  • paymentOption - Payment method used
  • totalPaymentAmount - Total payment amount
  • currency - Payment currency (ISO 4217 code)
Available Payment Options:“Paid” - Pre-paid orders
{
  "payment": {
    "paymentOption": "Paid",
    "totalPaymentAmount": 1200.00,
    "currency": "USD"
  }
}
  • Order already paid through online payment
  • Most common for e-commerce orders
  • No additional payment collection needed
“CreditCard” - Credit card payments
{
  "payment": {
    "paymentOption": "CreditCard",
    "totalPaymentAmount": 1200.00,
    "currency": "USD"
  }
}
  • Credit card payment processed
  • Similar to “Paid” but specifically indicates card payment
“Cash” - Cash on delivery (COD)
{
  "payment": {
    "paymentOption": "Cash",
    "totalPaymentAmount": 1200.00,    // Mandatory for COD
    "currency": "USD"
  }
}
  • Payment collected upon delivery
  • totalPaymentAmount is mandatory and must be accurate
  • Carrier will collect the specified amount

​
Marketplace Integration

Marketplace orders require at least one cargo identification method to be processed successfully.
{
  "cargo": {
    "cargoType": "RegularDelivery",           // Delivery type
    "cargoCarrier": "FedEx",                 // Carrier name (option 1)
    "cargoCode": "726123456789",             // Tracking code (option 2)
    "cargoDocumentUrl": "https://track.com"  // Document URL (option 3)
  }
}
Required Fields:
  • cargoType - Type of delivery service
  • At least one of the following identification methods:
cargoCarrier (Base Method)
{
  "cargo": {
    "cargoType": "RegularDelivery",
    "cargoCarrier": "FedEx"                 // Carrier company name
  }
}
  • Specify the shipping carrier company name
  • Common Carriers: "FedEx", "UPS", "DHL", "USPS", "Amazon Logistics"
  • Can be combined with cargoCode or cargoDocumentUrl for enhanced tracking
cargoCarrier + cargoCode (Recommended)
{
  "cargo": {
    "cargoType": "RegularDelivery",
    "cargoCarrier": "FedEx",
    "cargoCode": "726123456789"             // Tracking number
  }
}
  • Provides both carrier identification and tracking number
  • Alphanumeric tracking code provided by carrier
  • Example formats: "1Z999AA1234567890" (UPS), "1001 2345 6789" (FedEx)
cargoCarrier + cargoDocumentUrl
{
  "cargo": {
    "cargoType": "RegularDelivery",
    "cargoCarrier": "FedEx",
    "cargoDocumentUrl": "https://tracking.example.com/track"
  }
}
  • Combines carrier name with documentation link
  • Must be a valid HTTPS URL
  • Should point to publicly accessible tracking information
Standalone Options (Alternative) You can also use cargoCode or cargoDocumentUrl without cargoCarrier:
{
  "cargo": {
    "cargoType": "RegularDelivery",
    "cargoCode": "726123456789"             // Only tracking code
  }
}

​
Cargo Types

{
  "cargo": {
    "cargoType": "RegularDelivery"           // Delivery service type
  }
}
Available Cargo Types:“RegularDelivery”
{
  "cargo": {
    "cargoType": "RegularDelivery"
  }
}
  • Standard shipping service
  • Used for Marketplace and WEB orders
  • Normal delivery timeframes (2-5 business days)
  • Most common cargo type
“SamedayDelivery”
{
  "cargo": {
    "cargoType": "SamedayDelivery"
  }
}
  • Same-day delivery service
  • Available for WEB orders received by 09:00 UTC+0
  • Premium service with same-day fulfillment
  • Limited to supported regions
“ManualDelivery”
{
  "cargo": {
    "cargoType": "ManualDelivery"
  }
}
  • Direct courier delivery
  • Used when standard cargo companies are not available
  • Manual handling and special delivery arrangements
  • Typically for high-value or fragile items
Selection Guidelines:
  • Use "RegularDelivery" for standard e-commerce orders
  • Use "SamedayDelivery" for urgent orders (before 09:00 UTC)
  • Use "ManualDelivery" for special handling requirements

​
Value Added Services (VAS)

{
  "vas": {
    "giftVAS": {
      "giftWrap": true,                        // Enable gift wrapping
      "giftNotes": "Happy Birthday! Love, Mom"  // Gift message
    },
    "documentVAS": {
      "documentUrl": "https://example.com/warranty.pdf"  // Document link
    }
  }
}
Gift Services (giftVAS):
{
  "vas": {
    "giftVAS": {
      "giftWrap": true,                        // Enable gift wrapping
      "giftNotes": "Happy Birthday! Love, Mom"  // Single-line message
    }
  }
}
Fields:
  • giftWrap - Boolean to enable/disable gift wrapping
  • giftNotes - Single-line gift message for the recipient
Requirements:
  • Gift notes must be single-line (no line breaks)
  • Keep message concise and appropriate
  • Gift wrapping may incur additional fees
Document Services (documentVAS):
{
  "vas": {
    "documentVAS": {
      "documentUrl": "https://example.com/warranty-document.pdf"
    }
  }
}
Fields:
  • documentUrl - Link to document (warranty, manual, certificate)
Requirements:
  • Must be a publicly downloadable PDF format link
  • HTTPS URL required for security
  • Document should be relevant to the order (warranty, manual, etc.)
Combined VAS Example:
{
  "vas": {
    "giftVAS": {
      "giftWrap": true,
      "giftNotes": "Congratulations on your graduation!"
    },
    "documentVAS": {
      "documentUrl": "https://brand.com/product-manual.pdf"
    }
  }
}
VAS services are optional but enhance customer experience when used appropriately.

​
Currency Support

Currency information is mandatory for international orders from Turkey. Incorrect currency values are the customer’s responsibility.

​
Date Format

All date fields use ISO-8601 format as UTC+0.
Example: "2025-06-17T10:13:41.479Z"

​
Error Handling

Validation Errors

404 Not Found: Mandatory fields missing or invalid values

Business Logic Errors

Blocked Orders: Orders may be blocked due to insufficient stock
Always validate required fields locally before API submission to avoid common errors.

​
Order Examples

Most common order type with pre-paid payment and regular delivery.
{
  "referenceNumber": "ORD-2025-001",
  "salesChannel": "mystore.com",
  "orderCreatedAt": "2025-06-17T10:13:41.479Z",
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "phone": "+12125551234"
  },
  "shippingAddress": {
    "addressFirstName": "John",
    "addressLastName": "Smith",
    "addressOne": "123 Main Street, Apt 45",
    "addressTwo": "Unit 8",
    "district": "Manhattan",
    "city": "New York",
    "country": "United States",
    "addressPhone": "+12125551234"
  },
  "billingAddress": {
    "addressFirstName": "John",
    "addressLastName": "Smith",
    "addressOne": "123 Main Street, Apt 45",
    "district": "Manhattan",
    "city": "New York",
    "country": "United States",
    "addressPhone": "+12125551234"
  },
  "lineItems": [
    {
      "amountInOrder": 2,
      "sku": "LAPTOP-001",
      "productSalePrice": 1200.00,
      "currency": "USD"
    }
  ],
  "payment": {
    "paymentOption": "Paid",
    "totalPaymentAmount": 2400.00,
    "currency": "USD"
  },
  "cargo": {
    "cargoType": "RegularDelivery"
  }
}
Order where payment is collected upon delivery.
{
  "referenceNumber": "COD-2025-002",
  "salesChannel": "mobileapp.com",
  "orderCreatedAt": "2025-06-17T10:13:41.479Z",
  "customer": {
    "email": "customer2@example.com",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "phone": "+14155552345"
  },
  "shippingAddress": {
    "addressFirstName": "Sarah",
    "addressLastName": "Johnson",
    "addressOne": "456 Oak Avenue No:67",
    "district": "Downtown",
    "city": "San Francisco",
    "country": "United States",
    "addressPhone": "+14155552345"
  },
  "billingAddress": {
    "addressFirstName": "Sarah",
    "addressLastName": "Johnson",
    "addressOne": "456 Oak Avenue No:67",
    "district": "Downtown",
    "city": "San Francisco",
    "country": "United States",
    "addressPhone": "+14155552345"
  },
  "lineItems": [
    {
      "amountInOrder": 1,
      "sku": "PHONE-001",
      "currency": "USD"
    }
  ],
  "payment": {
    "paymentOption": "Cash",
    "totalPaymentAmount": 850.00,
    "currency": "USD"
  },
  "cargo": {
    "cargoType": "RegularDelivery"
  }
}
Order with marketplace-specific shipping information.
{
  "referenceNumber": "MP-2025-003",
  "salesChannel": "marketplace.com",
  "orderCreatedAt": "2025-06-17T10:13:41.479Z",
  "customer": {
    "email": "customer3@example.com",
    "firstName": "Michael",
    "lastName": "Brown",
    "phone": "+13235551122"
  },
  "shippingAddress": {
    "addressFirstName": "Michael",
    "addressLastName": "Brown",
    "addressOne": "789 Sunset Boulevard No:123",
    "district": "Hollywood",
    "city": "Los Angeles",
    "country": "United States",
    "addressPhone": "+13235551122"
  },
  "billingAddress": {
    "addressFirstName": "Michael",
    "addressLastName": "Brown",
    "addressOne": "789 Sunset Boulevard No:123",
    "district": "Hollywood",
    "city": "Los Angeles",
    "country": "United States",
    "addressPhone": "+13235551122"
  },
  "lineItems": [
    {
      "amountInOrder": 3,
      "sku": "BOOK-001",
      "productSalePrice": 25.00,
      "currency": "USD"
    }
  ],
  "payment": {
    "paymentOption": "Paid",
    "totalPaymentAmount": 75.00,
    "currency": "USD"
  },
  "cargo": {
    "cargoCarrier": "FedEx",
    "cargoCode": "726123456789",
    "cargoType": "RegularDelivery"
  }
}
B2B order with company information and tax details.
{
  "referenceNumber": "CORP-2025-004",
  "salesChannel": "b2b.mystore.com",
  "orderCreatedAt": "2025-06-17T10:13:41.479Z",
  "customer": {
    "email": "procurement@company.com",
    "firstName": "Robert",
    "lastName": "Wilson",
    "phone": "+12125553456"
  },
  "shippingAddress": {
    "addressFirstName": "Robert",
    "addressLastName": "Wilson",
    "company": "ABC Technology Ltd.",
    "addressOne": "Tech Center Building Floor:5",
    "addressTwo": "Suite 12",
    "district": "Midtown",
    "city": "New York",
    "country": "United States",
    "addressPhone": "+12125553456"
  },
  "billingAddress": {
    "addressFirstName": "Robert",
    "addressLastName": "Wilson",
    "company": "ABC Technology Ltd.",
    "addressOne": "Tech Center Building Floor:5",
    "district": "Midtown",
    "city": "New York",
    "country": "United States",
    "addressPhone": "+12125553456",
    "taxOffice": "Manhattan Tax Office",
    "taxNumber": "1234567890"
  },
  "lineItems": [
    {
      "amountInOrder": 10,
      "sku": "TABLET-001",
      "productSalePrice": 500.00,
      "currency": "USD"
    }
  ],
  "payment": {
    "paymentOption": "Paid",
    "totalPaymentAmount": 5000.00,
    "currency": "USD"
  },
  "cargo": {
    "cargoType": "RegularDelivery"
  }
}
Cross-border order with postal code requirements.
{
  "referenceNumber": "INT-2025-005",
  "salesChannel": "global.mystore.com",
  "orderCreatedAt": "2025-06-17T10:13:41.479Z",
  "customer": {
    "email": "customer@example.de",
    "firstName": "Hans",
    "lastName": "Mueller",
    "phone": "+4915512345678"
  },
  "shippingAddress": {
    "addressFirstName": "Hans",
    "addressLastName": "Mueller",
    "addressOne": "Hauptstraße 123",
    "city": "Berlin",
    "postalCode": "10115",
    "country": "Germany",
    "addressPhone": "+4915512345678"
  },
  "billingAddress": {
    "addressFirstName": "Hans",
    "addressLastName": "Mueller",
    "addressOne": "Hauptstraße 123",
    "city": "Berlin",
    "postalCode": "10115",
    "country": "Germany",
    "addressPhone": "+4915512345678"
  },
  "lineItems": [
    {
      "amountInOrder": 1,
      "sku": "WATCH-001",
      "productSalePrice": 250.00,
      "currency": "EUR"
    }
  ],
  "payment": {
    "paymentOption": "Paid",
    "totalPaymentAmount": 250.00,
    "currency": "EUR"
  },
  "cargo": {
    "cargoType": "RegularDelivery"
  }
}
Order with gift wrapping and value-added services.
{
  "referenceNumber": "GIFT-2025-006",
  "salesChannel": "mystore.com",
  "orderCreatedAt": "2025-06-17T10:13:41.479Z",
  "customer": {
    "email": "customer@example.com",
    "firstName": "Emma",
    "lastName": "Davis",
    "phone": "+12125554567"
  },
  "shippingAddress": {
    "addressFirstName": "Emma",
    "addressLastName": "Davis",
    "addressOne": "321 Broadway Street No:456",
    "district": "SoHo",
    "city": "New York",
    "country": "United States",
    "addressPhone": "+12125554567"
  },
  "billingAddress": {
    "addressFirstName": "Emma",
    "addressLastName": "Davis",
    "addressOne": "321 Broadway Street No:456",
    "district": "SoHo",
    "city": "New York",
    "country": "United States",
    "addressPhone": "+12125554567"
  },
  "lineItems": [
    {
      "amountInOrder": 1,
      "sku": "JEWELRY-001",
      "productSalePrice": 300.00,
      "currency": "USD"
    }
  ],
  "payment": {
    "paymentOption": "Paid",
    "totalPaymentAmount": 300.00,
    "currency": "USD"
  },
  "cargo": {
    "cargoType": "RegularDelivery"
  },
  "vas": {
    "giftVAS": {
      "giftWrap": true,
      "giftNotes": "Happy Birthday! With love..."
    },
    "documentVAS": {
      "documentUrl": "https://example.com/warranty-document.pdf"
    }
  }
}

​
TAG Management

OPLOG.ONE’s TAG management system provides flexible metadata tagging capabilities across various business entities. Organizations can attach custom labels to records, transforming basic data into actionable intelligence for better workflow optimization. The system proves valuable for both operational efficiency and analytics. Teams can quickly identify and process records based on specific criteria - staff can locate items requiring special handling, managers can prioritize high-value transactions, and leadership can analyze performance metrics across different categories. This flexible approach eliminates rigid classification systems, allowing businesses to evolve their tagging strategies as operational needs change.

​
TAG Best Practices for Sales Orders

Sales Team Assignment

Track sales team members and assignments: sales-team-member, account-manager, lead-source

Order Type

Categorize by type: b2b, retail, wholesale, gift-order

Source Tracking

Track order sources: website, mobile-app, marketplace, phone

Special Handling

Mark special requirements: fragile, expedited, white-glove
TAG Usage Examples:
  • Sales Team Tags: sales-team-member,account-manager,lead-source
  • Source Tags: amazon,trendyol,website,mobile-app
  • Special Tags: gift-wrap,international,b2b,wholesale
  • Processing Tags: reviewed,approved,on-hold,expedited
TAG management for sales orders enables enhanced order tracking, custom workflows, and detailed analytics based on your business requirements.