# Bulk Update Campaign Source: https://developer.lulacommerce.com/api-reference/campaigns/bulk-update-campaign POST {{micro_service_base_url}}/stores/company/{{company_id}}/campaigns/bulk Update multiple campaigns simultaneously with the same changes, ideal for bulk campaign management and maintenance operations. This endpoint allows you to apply the same updates to multiple campaigns at once, streamlining campaign management for scenarios where you need to modify several campaigns with identical changes. Bulk updates are processed as a single transaction. If any campaign update fails, the entire operation is rolled back to maintain data consistency. ### Path Parameters The unique identifier of the company that owns the campaigns ### Request Body Array of campaign IDs to update Object containing the updates to apply to all specified campaigns New campaign name (will be applied to all campaigns) New campaign description New start date (YYYY-MM-DD format) New end date (YYYY-MM-DD format) New status: "active", "inactive", "scheduled", "expired" Additional campaign settings to update ### Response Indicates whether the bulk update was successful Confirmation message or error details Array of campaign IDs that were updated Echo of the updates that were applied Number of campaigns successfully updated Array of campaigns that failed to update with error details Campaign ID that failed Error message for this campaign Error code for troubleshooting Timestamp when the bulk update was processed ### Request Example ```json { "campaignIds": [ 1000013 ], "updates": { "name": "Get the Turkey club combo $10.99", "description": "Hey! You can avail the opportunity this time and get benefits by choosing 'Get the Turkey club combo $10.99'", "end_date": "2025-03-25", "start_date": "2025-12-31", "status": "inactive" } } ``` ### Response Example ```json { "success": true, "message": "Bulk update completed successfully", "campaignIds": [ 1000013 ], "updates": { "name": "Get the Turkey club combo $10.99", "description": "Hey! You can avail the opportunity this time and get benefits by choosing 'Get the Turkey club combo $10.99'", "end_date": "2025-03-25", "start_date": "2025-12-31", "status": "inactive" }, "updated_count": 1, "failed_updates": [], "timestamp": "2024-01-15T16:45:00Z" } ``` The bulk update process follows these steps: 1. **Validation**: All campaign IDs are validated for existence and permissions 2. **Pre-Check**: Updates are validated against business rules for each campaign 3. **Transaction Start**: Database transaction begins to ensure consistency 4. **Sequential Updates**: Each campaign is updated in sequence 5. **Error Handling**: Any failures trigger rollback of all changes 6. **Confirmation**: Successful completion commits all changes 7. **Notification**: Affected systems are notified of changes **Transaction Safety**: Bulk updates use database transactions to ensure either all campaigns are updated successfully or none are modified, maintaining data consistency. **Performance Consideration**: For large numbers of campaigns (>50), consider breaking the update into smaller batches to avoid timeout issues and improve processing speed. ### Use Cases **Seasonal Campaign Management** * Update end dates for all seasonal campaigns * Change status of holiday campaigns to inactive * Extend successful campaigns across multiple products **Compliance Updates** * Update campaign descriptions for regulatory compliance * Modify campaign terms across all active promotions * Apply uniform changes for legal requirements **Brand Standardization** * Update campaign naming conventions * Standardize descriptions across campaigns * Apply consistent messaging and branding **Performance Optimization** * Pause underperforming campaigns simultaneously * Extend high-performing campaigns * Adjust timing based on analytics insights **Administrative Maintenance** * Archive completed campaigns * Update campaign ownership or management * Apply system-wide configuration changes ### Error Handling **Partial Failure Response** ```json { "success": false, "message": "Bulk update completed with errors", "campaignIds": [1000013, 1000014, 1000015], "updated_count": 2, "failed_updates": [ { "campaign_id": "1000015", "error": "Campaign not found", "error_code": "CAMPAIGN_NOT_FOUND" } ], "timestamp": "2024-01-15T16:45:00Z" } ``` **Validation Error** ```json { "success": false, "message": "Validation failed for bulk update", "error_code": "VALIDATION_ERROR", "validation_errors": [ { "field": "end_date", "error": "End date must be after start date" } ] } ``` **Transaction Rollback** ```json { "success": false, "message": "Bulk update failed and was rolled back", "error_code": "TRANSACTION_FAILED", "rollback_reason": "Database constraint violation", "affected_campaigns": 0 } ``` **Impact Assessment**: Bulk updates affect multiple campaigns simultaneously. Ensure you understand the impact on active promotions, customer experience, and store operations before proceeding. ### Best Practices **Planning** * Test bulk updates on a small subset first * Verify campaign IDs before executing large updates * Consider timing of updates relative to customer activity **Data Validation** * Ensure all update fields are valid for all target campaigns * Check date ranges and status transitions for consistency * Validate permissions for all campaigns being updated **Monitoring** * Monitor system performance during large bulk updates * Track success rates and error patterns * Set up alerts for bulk update failures **Recovery Planning** * Have rollback procedures ready for failed updates * Maintain backups before large bulk operations * Document changes for audit and troubleshooting ### Limitations **Campaign Limits** * Maximum 100 campaigns per bulk update request * Processing timeout after 5 minutes * Memory limitations for very large updates **Field Restrictions** * Some fields may not be suitable for bulk updates * Campaign-specific settings cannot be bulk updated * Image uploads not supported in bulk operations **Status Constraints** * Some status transitions may not be allowed for all campaigns * Campaign dependencies may prevent bulk status changes * Business rules apply to each campaign individually # Campaigns Overview Source: https://developer.lulacommerce.com/api-reference/campaigns/campaigns-overview Comprehensive campaign management system for creating, managing, and tracking marketing campaigns and promotions across your stores. # Campaigns Service The Campaigns service provides a comprehensive platform for creating, managing, and tracking marketing campaigns and promotional activities across your store network. This service enables you to design targeted marketing initiatives, manage promotional codes, and analyze campaign performance. The Campaigns service integrates seamlessly with your store operations, allowing you to create sophisticated marketing strategies that drive customer engagement and increase sales. ## 🎯 Key Features ### Campaign Management * **Multi-Store Campaigns**: Create campaigns that span across multiple store locations * **Flexible Scheduling**: Set precise start and end dates for campaign activation * **Status Control**: Manage campaign states (active, inactive, scheduled, expired) * **Rich Media Support**: Include images and multimedia content in campaigns * **Performance Tracking**: Monitor campaign effectiveness and ROI ### Promotion Engine * **Discount Types**: Support for percentage-based, fixed amount, and BOGO promotions * **Automatic Application**: Smart promotion application based on customer behavior * **Product Targeting**: Target specific products, categories, or entire inventory * **Code Management**: Generate and manage promotional codes for customer use * **Usage Limits**: Set redemption limits and customer usage restrictions ### Advanced Targeting * **Item-Level Targeting**: Apply promotions to specific products or SKUs * **Category Targeting**: Target entire product categories or subcategories * **Store-Specific Campaigns**: Create location-specific marketing initiatives * **Customer Segmentation**: Target specific customer groups or demographics * **Time-Based Activation**: Schedule campaigns for optimal timing ## 🏗️ Campaign Architecture ### Campaign Hierarchy ``` Company ├── Campaigns │ ├── Campaign Details │ ├── Store Associations │ └── Promotions │ ├── Promotion Rules │ ├── Discount Logic │ └── Product Targeting ``` ### Campaign Lifecycle 1. **Creation**: Define campaign objectives, timeline, and targeting 2. **Configuration**: Set up promotions, discounts, and rules 3. **Store Linking**: Associate campaigns with specific store locations 4. **Activation**: Launch campaigns according to schedule 5. **Monitoring**: Track performance and customer engagement 6. **Optimization**: Adjust campaigns based on real-time data 7. **Completion**: End campaigns and analyze final results ## 📊 Campaign Types **Seasonal Campaigns** * Holiday promotions and seasonal sales * Back-to-school, summer, winter campaigns * Special event marketing (Valentine's Day, Mother's Day, etc.) **Product Launch Campaigns** * New product introductions * Featured product spotlights * Limited-time offerings **Customer Retention Campaigns** * Loyalty program promotions * Welcome campaigns for new customers * Win-back campaigns for inactive customers **Revenue Optimization Campaigns** * Clearance and inventory management * Upselling and cross-selling initiatives * Bundle promotions and combo deals ## 🎨 Promotion Strategies ### Discount Mechanisms * **Percentage Discounts**: 10% off, 25% off selected items * **Fixed Amount Discounts**: $5 off orders over $50 * **Buy One Get One (BOGO)**: Various BOGO configurations * **Bundle Deals**: Product combination discounts * **Free Shipping**: Shipping cost elimination thresholds ### Application Methods * **Automatic Application**: Discounts applied based on cart contents * **Promotional Codes**: Customer-entered discount codes * **Loyalty Integration**: Member-exclusive pricing and benefits * **Time-Limited Offers**: Flash sales and limited-time promotions ## 🔧 Integration Capabilities ### Store Operations * **POS Integration**: Seamless integration with point-of-sale systems * **Inventory Management**: Real-time inventory consideration for campaigns * **Order Processing**: Automatic discount application during checkout * **Customer Database**: Integration with customer profiles and history ### Analytics & Reporting * **Performance Metrics**: Campaign ROI, conversion rates, engagement * **Sales Impact**: Revenue attribution and lift analysis * **Customer Insights**: Behavior analysis and segmentation data * **Competitive Analysis**: Market positioning and pricing insights ## 🎯 Business Benefits **Increased Revenue** * Drive sales through targeted promotions * Increase average order value with strategic discounting * Optimize pricing strategies based on customer response **Customer Engagement** * Enhance customer loyalty through personalized offers * Improve customer acquisition with attractive promotions * Increase repeat purchase rates through retention campaigns **Operational Efficiency** * Automate promotional processes and discount application * Streamline campaign management across multiple locations * Reduce manual intervention in promotional activities **Data-Driven Insights** * Gain deep understanding of customer preferences * Optimize marketing spend through performance analytics * Improve future campaign effectiveness based on historical data ## 🚀 Getting Started ### Basic Campaign Setup 1. **Define Objectives**: Establish clear campaign goals and KPIs 2. **Create Campaign**: Set up basic campaign information and timeline 3. **Design Promotions**: Configure discount rules and targeting 4. **Link Stores**: Associate campaign with relevant store locations 5. **Launch & Monitor**: Activate campaign and track performance ### Best Practices * **Clear Objectives**: Define measurable goals for each campaign * **Target Audience**: Understand your customer segments and preferences * **Testing Strategy**: A/B test different promotional approaches * **Performance Monitoring**: Regularly review campaign metrics and adjust * **Customer Communication**: Ensure clear and compelling promotional messaging ## 📈 Success Metrics ### Key Performance Indicators * **Conversion Rate**: Percentage of campaign views that result in purchases * **Revenue Impact**: Total revenue generated from campaign activities * **Customer Acquisition**: Number of new customers acquired through campaigns * **Engagement Rate**: Customer interaction and participation levels * **Return on Investment**: Campaign costs versus revenue generated The Campaigns service is designed to scale with your business growth, supporting everything from single-store promotions to complex multi-location marketing initiatives. Start with simple campaigns to understand customer response patterns, then gradually implement more sophisticated targeting and promotional strategies. ## 🔗 Related Services * **Orders Service**: Campaign promotions automatically apply to qualifying orders * **Inventory Service**: Real-time inventory data ensures promotional accuracy * **Customer Service**: Customer profiles enable personalized campaign targeting * **Analytics Service**: Comprehensive reporting and performance analysis * **Store Management**: Store-specific campaign configuration and management # Create Campaign Source: https://developer.lulacommerce.com/api-reference/campaigns/create-campaign POST {{micro_service_base_url}}/stores/company/{{company_id}}/campaigns Create a new marketing campaign for a company with detailed configuration including scheduling, targeting, and media assets. This endpoint allows you to create comprehensive marketing campaigns for your company. Campaigns can include rich media content, precise scheduling, and detailed targeting criteria to maximize marketing effectiveness. New campaigns are created in the specified status and can be immediately associated with stores and promotions for complete marketing campaign setup. ### Path Parameters The unique identifier of the company creating the campaign ### Request Body Campaign name for identification and management Detailed description of the campaign objectives and content Campaign start date (YYYY-MM-DD format) Campaign end date (YYYY-MM-DD format) Campaign status: "active", "inactive", "scheduled", "expired" Base64 encoded image data for campaign visual assets ### Response Unique campaign identifier Company identifier this campaign belongs to Campaign name Campaign description Campaign start date Campaign end date Current campaign status URL to the uploaded campaign image ID of the user who created the campaign ID of the user who last updated the campaign Campaign creation timestamp Campaign last update timestamp Deletion timestamp (null for active campaigns) ### Request Example ```json { "description": "Spring seasonal promotion featuring fresh products and outdoor essentials", "end_date": "2025-03-25", "start_date": "2025-12-31", "name": "Spring Fresh Campaign", "status": "active", "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==" } ``` ### Response Example ```json { "id": "1000010", "company_id": "1000058", "description": "Spring seasonal promotion featuring fresh products and outdoor essentials", "end_date": "2025-03-25", "start_date": "2025-12-31", "name": "Spring Fresh Campaign", "status": "active", "image": "https://lula-stores-service-staging.s3.amazonaws.com/company/1000058/campaigns/1000010/1744591882710.webp", "created_by": "1000418", "updated_by": "1000418", "updated_at": "2025-04-14T00:51:22.994Z", "created_at": "2025-04-14T00:51:22.994Z", "deletedAt": null } ``` When a campaign is created, the following processes occur: 1. **Validation**: Campaign data is validated for completeness and consistency 2. **Image Processing**: Base64 image is processed and uploaded to cloud storage 3. **ID Generation**: Unique campaign identifier is generated 4. **Database Storage**: Campaign details are stored with audit information 5. **Status Initialization**: Campaign is set to specified initial status 6. **Availability Setup**: Campaign becomes available for store association and promotion creation **Image Processing**: Campaign images are automatically processed, optimized, and stored in cloud storage. The response includes the final image URL for use in marketing materials. **Date Validation**: Ensure end\_date is after start\_date and both dates are in the future for scheduled campaigns. Past dates are allowed for historical campaign tracking. ### Campaign Status Guide **active** * Campaign is currently running and accepting customers * Promotions are being applied to qualifying orders * Campaign is visible in customer-facing applications **inactive** * Campaign is created but not currently running * Promotions are not being applied * Campaign can be activated when ready **scheduled** * Campaign is set to start at a future date * System will automatically activate when start\_date arrives * Useful for planned marketing initiatives **expired** * Campaign has passed its end\_date * No longer accepting new customers * Historical data remains available for analysis ### Error Responses **Invalid Date Range** ```json { "error": "Invalid date range", "message": "End date must be after start date", "code": "INVALID_DATE_RANGE" } ``` **Company Not Found** ```json { "error": "Company not found", "message": "The specified company does not exist", "code": "COMPANY_NOT_FOUND" } ``` **Image Processing Error** ```json { "error": "Image processing failed", "message": "Unable to process the provided image data", "code": "IMAGE_PROCESSING_ERROR" } ``` **Validation Error** ```json { "error": "Validation failed", "message": "Required fields are missing or invalid", "code": "VALIDATION_ERROR", "details": { "name": "Campaign name is required", "description": "Description cannot be empty" } } ``` **Image Size**: Campaign images should be optimized for web use. Large images may cause processing delays or failures. Recommended maximum size is 2MB. ### Use Cases **Seasonal Campaigns** * Holiday promotions (Christmas, Halloween, Valentine's Day) * Seasonal product features (summer drinks, winter clothing) * Weather-based campaigns (rainy day specials, heat wave promotions) **Product Launch Campaigns** * New product introductions with special pricing * Limited edition product features * Brand partnership campaigns **Customer Acquisition Campaigns** * Welcome campaigns for new customers * Referral program promotions * Social media engagement campaigns **Revenue Optimization Campaigns** * Clearance campaigns for slow-moving inventory * Upselling campaigns for high-margin products * Bundle promotion campaigns # Delete Campaign Source: https://developer.lulacommerce.com/api-reference/campaigns/delete-campaign DELETE {{stores_service_api_base_url}}/stores/{{store_id}}/status Delete a campaign and all associated data including promotions, store associations, and historical records. This endpoint permanently removes a campaign and all its associated data from the system. This includes promotions, store associations, usage statistics, and historical performance data. Campaign deletion is irreversible. All associated promotions will be deactivated immediately, and historical data will be permanently lost. Consider archiving campaigns instead of deletion for data retention. ### Path Parameters The unique identifier of the company that owns the campaign The unique identifier of the campaign to delete ### Query Parameters Current local date for audit and timezone purposes (e.g., "Nov 15 2024 03:46:34") Force deletion even if campaign has active promotions or associations Whether to create an archive backup before deletion ### Response Indicates whether the deletion was successful Confirmation message or error details The ID of the deleted campaign Timestamp when the deletion occurred Summary of what was deleted along with the campaign Number of promotions that were deleted Number of store associations that were removed Number of historical records that were archived Location where archived data was stored (if archive\_data=true) ### Response Example ```json { "success": true, "message": "Campaign successfully deleted", "campaign_id": "1000010", "deleted_at": "2024-01-15T16:45:00Z", "affected_items": { "promotions_deleted": 3, "store_associations_removed": 5, "historical_records_archived": 1247 }, "archive_location": "s3://campaign-archives/company-1000058/campaign-1000010-20240115.json" } ``` When a campaign is deleted, the following occurs in sequence: 1. **Validation**: Verify deletion permissions and campaign status 2. **Promotion Deactivation**: Immediately stop all active promotions 3. **Store Disassociation**: Remove campaign from all associated stores 4. **Data Archival**: Create backup of all campaign data (if enabled) 5. **Record Deletion**: Remove campaign and related records from active database 6. **Cache Invalidation**: Clear all cached campaign data across systems 7. **Audit Logging**: Record deletion event for compliance and tracking **Data Archival**: By default, campaign data is archived before deletion. This allows for potential data recovery and historical analysis while removing the campaign from active systems. **Alternative to Deletion**: Consider setting campaign status to "inactive" or "archived" instead of deletion to preserve historical data while removing the campaign from customer-facing systems. ### Pre-Deletion Checks **Active Promotions Check** * Verifies if campaign has active promotions * Warns about customer impact of immediate deactivation * Requires force\_delete=true to proceed with active promotions **Store Associations Check** * Identifies all stores currently using the campaign * Estimates impact on store operations * Provides list of affected store locations **Historical Data Check** * Calculates amount of historical data that will be lost * Estimates analytics impact * Recommends archival before deletion **Dependency Check** * Identifies other campaigns that reference this campaign * Checks for integration dependencies * Verifies no business-critical dependencies exist ### Use Cases **Campaign Cleanup** * Remove test or duplicate campaigns * Clean up failed campaign launches * Eliminate outdated promotional campaigns **Compliance Requirements** * Delete campaigns containing expired promotional content * Remove campaigns with data privacy concerns * Comply with data retention policies **System Maintenance** * Remove campaigns that are causing system issues * Clean up campaigns with corrupted data * Eliminate campaigns that are no longer relevant **Business Restructuring** * Delete campaigns from discontinued product lines * Remove campaigns from closed store locations * Eliminate campaigns that don't align with new business strategy ### Error Responses **Campaign Not Found** ```json { "success": false, "message": "Campaign not found", "error_code": "CAMPAIGN_NOT_FOUND", "campaign_id": "invalid-id" } ``` **Active Promotions Prevent Deletion** ```json { "success": false, "message": "Cannot delete campaign with active promotions", "error_code": "ACTIVE_PROMOTIONS_EXIST", "active_promotions": 3, "suggestion": "Set force_delete=true to override" } ``` **Insufficient Permissions** ```json { "success": false, "message": "Insufficient permissions to delete campaign", "error_code": "PERMISSION_DENIED", "required_role": "campaign_admin" } ``` **Dependency Conflict** ```json { "success": false, "message": "Campaign cannot be deleted due to dependencies", "error_code": "DEPENDENCY_CONFLICT", "dependencies": [ "Linked to active store integrations", "Referenced by reporting system" ] } ``` **Immediate Impact**: Campaign deletion immediately affects all customer-facing systems. Active promotions will stop working instantly, which may impact customer experience and pending orders. ### Recovery Options **Archive Recovery** * Archived data can be restored within 30 days * Requires administrative approval * May not restore all system integrations **Backup Systems** * System backups may contain campaign data * Recovery requires technical intervention * Data consistency cannot be guaranteed **Manual Reconstruction** * Campaign settings can be manually recreated * Historical performance data will be lost * Promotions and associations must be rebuilt # Get Campaign Details Source: https://developer.lulacommerce.com/api-reference/campaigns/get-campaign-details GET {{micro_service_base_url}}/stores/company/{{company_id}}/campaigns/{{campaign_id}} Retrieve comprehensive details for a specific campaign including full configuration, associated stores, and performance metrics. This endpoint provides complete details for a specific campaign, including all configuration settings, associated store information, linked promotions, and performance analytics. This endpoint returns the most comprehensive campaign information available, ideal for campaign editing, detailed analysis, and administrative oversight. ### Path Parameters The unique identifier of the company that owns the campaign The unique identifier of the campaign to retrieve details for ### Response Unique campaign identifier Company identifier this campaign belongs to Campaign name Detailed campaign description Campaign start date (YYYY-MM-DD) Campaign end date (YYYY-MM-DD) Current campaign status URL to campaign image asset ID of the user who created the campaign ID of the user who last updated the campaign Campaign creation timestamp Campaign last update timestamp Deletion timestamp (null for active campaigns) List of stores linked to this campaign Store unique identifier Store display name Association status Association timestamp List of promotions associated with this campaign Promotion unique identifier Promotional code Promotion type Promotion status Number of times used Campaign performance analytics Total campaign impressions Total conversions generated Conversion rate percentage Total revenue attributed to campaign Average order value from campaign ### Example Response Since no specific response was provided, here's the expected comprehensive structure: ```json { "id": "1000010", "company_id": "1000058", "name": "Spring Fresh Campaign", "description": "Spring seasonal promotion featuring fresh products and outdoor essentials", "start_date": "2025-03-01", "end_date": "2025-05-31", "status": "active", "image": "https://lula-stores-service-staging.s3.amazonaws.com/company/1000058/campaigns/1000010/1744591882710.webp", "created_by": "1000418", "updated_by": "1000418", "created_at": "2025-04-14T00:51:22.994Z", "updated_at": "2025-04-14T00:51:22.994Z", "deletedAt": null, "associated_stores": [ { "store_id": "store_001", "store_name": "Downtown Location", "status": "active", "linked_at": "2025-04-14T01:00:00.000Z" } ], "promotions": [ { "promotion_id": "promo_001", "code": "SPRING25", "type": "percentage", "status": "active", "usage_count": 45 } ], "performance_metrics": { "total_views": 1250, "total_conversions": 89, "conversion_rate": 7.12, "revenue_generated": "4,567.89", "average_order_value": "51.32" } } ``` **Complete Information**: This endpoint provides the most comprehensive view of a campaign, including all related data needed for campaign management and analysis. **Performance Monitoring**: Use the performance\_metrics data to assess campaign effectiveness and make data-driven decisions about campaign optimization. ### Use Cases **Campaign Editing** * Retrieve current campaign configuration for editing * View all campaign settings before making changes * Understand campaign scope and associations **Performance Analysis** * Analyze campaign effectiveness and ROI * Compare performance across different campaigns * Identify successful campaign elements **Administrative Oversight** * Review campaign compliance and settings * Audit campaign changes and history * Monitor campaign associations and relationships **Customer Service** * Answer customer questions about active campaigns * Understand promotion details for support inquiries * Verify campaign eligibility and requirements ### Error Responses **Campaign Not Found** ```json { "error": "Campaign not found", "message": "The specified campaign does not exist", "code": "CAMPAIGN_NOT_FOUND" } ``` **Company Mismatch** ```json { "error": "Campaign not found", "message": "Campaign does not belong to the specified company", "code": "CAMPAIGN_COMPANY_MISMATCH" } ``` **Access Denied** ```json { "error": "Access denied", "message": "You do not have permission to view this campaign", "code": "ACCESS_DENIED" } ``` **Sensitive Information**: Campaign details may include sensitive business information. Ensure proper access controls are in place when displaying this data. # Get Campaigns Source: https://developer.lulacommerce.com/api-reference/campaigns/get-campaigns GET {{micro_service_base_url}}/stores/company/{{company_id}}/campaigns Retrieve a list of all campaigns for a company with pagination, filtering, and sorting capabilities. This endpoint provides comprehensive access to all campaigns associated with a company. It supports pagination, filtering by status, and sorting to efficiently manage large numbers of campaigns. This endpoint returns essential campaign information optimized for list views and campaign management interfaces. For detailed campaign information, use the Get Campaign Details endpoint. ### Path Parameters The unique identifier of the company whose campaigns you want to retrieve ### Query Parameters Maximum number of campaigns to return per request (max 100) Number of campaigns to skip for pagination Sort order for campaigns: "ASC" (ascending) or "DESC" (descending) Filter campaigns by status: "active", "inactive", "scheduled", "expired" Search campaigns by name or description Filter campaigns starting after this date (YYYY-MM-DD) Filter campaigns starting before this date (YYYY-MM-DD) ### Response Array of campaign objects Unique campaign identifier Campaign name URL to campaign image asset Campaign start date (YYYY-MM-DD) Campaign end date (YYYY-MM-DD) Current campaign status Pagination information for the response Total number of campaigns matching filters Current page number (calculated from offset and limit) Total number of pages available Whether there are more campaigns available Whether there are previous campaigns available ### Response Example ```json [ { "id": "1000007", "image": "https://lula-stores-service-staging.s3.amazonaws.com/company/1000058/campaigns/1000007/1741976976661.webp", "name": "Summer Essentials Campaign", "start_date": "2025-06-01", "end_date": "2025-08-31", "status": "active" }, { "id": "1000008", "image": "https://lula-stores-service-staging.s3.amazonaws.com/company/1000058/campaigns/1000008/1741977281470.webp", "name": "Back to School Special", "start_date": "2025-08-15", "end_date": "2025-09-15", "status": "scheduled" }, { "id": "1000009", "image": "https://lula-stores-service-staging.s3.amazonaws.com/company/1000058/campaigns/1000009/1741977365382.webp", "name": "Holiday Season Promotions", "start_date": "2025-11-01", "end_date": "2025-12-31", "status": "scheduled" }, { "id": "1000010", "image": "https://lula-stores-service-staging.s3.amazonaws.com/company/1000058/campaigns/1000010/1744591882710.webp", "name": "Spring Fresh Campaign", "start_date": "2025-03-01", "end_date": "2025-05-31", "status": "active" } ] ``` **Get Active Campaigns Only** ``` GET {{micro_service_base_url}}/stores/company/{{company_id}}/campaigns?status=active ``` **Search Campaigns by Name** ``` GET {{micro_service_base_url}}/stores/company/{{company_id}}/campaigns?search=summer ``` **Get Campaigns with Pagination** ``` GET {{micro_service_base_url}}/stores/company/{{company_id}}/campaigns?limit=10&offset=20 ``` **Get Upcoming Campaigns** ``` GET {{micro_service_base_url}}/stores/company/{{company_id}}/campaigns?status=scheduled&order=ASC ``` **Filter by Date Range** ``` GET {{micro_service_base_url}}/stores/company/{{company_id}}/campaigns?start_date_from=2025-06-01&start_date_to=2025-12-31 ``` **Performance Optimization**: Use pagination (limit and offset) when dealing with companies that have many campaigns to ensure fast response times and efficient resource usage. **Search Functionality**: The search parameter performs case-insensitive matching against both campaign names and descriptions, making it easy to find specific campaigns. ### Campaign Status Overview **active**: Currently running campaigns * Promotions are being applied * Visible to customers * Within start and end date range **inactive**: Paused or disabled campaigns * Not currently applying promotions * Hidden from customers * Can be reactivated at any time **scheduled**: Future campaigns * Set to start automatically on start\_date * Not yet visible to customers * Can be modified before activation **expired**: Past campaigns * End date has passed * No longer applying promotions * Archived for historical reference ### Use Cases **Campaign Dashboard** * Display overview of all active campaigns * Monitor campaign performance at a glance * Quick access to campaign management actions **Campaign Planning** * Review upcoming scheduled campaigns * Plan campaign calendars and timing * Identify gaps in marketing coverage **Performance Analysis** * Compare active vs inactive campaigns * Analyze campaign timing and duration * Identify successful campaign patterns **Campaign Administration** * Bulk campaign management operations * Search and filter for specific campaigns * Organize campaigns by status and timing ### Error Responses **Company Not Found** ```json { "error": "Company not found", "message": "The specified company does not exist", "code": "COMPANY_NOT_FOUND" } ``` **Invalid Parameters** ```json { "error": "Invalid parameters", "message": "Limit must be between 1 and 100", "code": "INVALID_PARAMETERS" } ``` **Invalid Date Format** ```json { "error": "Invalid date format", "message": "Date must be in YYYY-MM-DD format", "code": "INVALID_DATE_FORMAT" } ``` **Large Result Sets**: When requesting campaigns without pagination, large companies may experience slower response times. Always use pagination for production applications. # Link Campaign to Stores Source: https://developer.lulacommerce.com/api-reference/campaigns/link-campaign-to-stores GET {{stores_service_api_base_url}}/stores/company/{{company_id}}/campaigns/{{campaign_id}}/stores Retrieve and manage the association between campaigns and store locations, including store-specific campaign configurations. This endpoint manages the relationship between campaigns and store locations, allowing you to see which stores are associated with a campaign and manage store-specific campaign configurations. Campaign-store associations determine where campaigns are active and visible to customers. Each association can have store-specific settings and configurations. ### Path Parameters The unique identifier of the company that owns the campaign The unique identifier of the campaign to retrieve store associations for ### Query Parameters Filter associations by status: "active", "inactive", "pending" Filter by store type: "retail", "online", "franchise", "corporate" Filter stores by geographical region Include store-specific campaign configurations in the response ### Response The campaign identifier Name of the campaign Total number of stores associated with this campaign Array of store association details Unique store identifier Store display name Store classification (retail, online, franchise, corporate) Geographical region of the store Status of the campaign-store association Timestamp when the association was created Timestamp of the last association update Store-specific campaign configuration (if include\_config=true) Store-specific campaign messaging Store-specific promotions Store-specific display preferences Store-specific timing adjustments Summary statistics for campaign-store associations Count of associations by status Count of associations by store type Count of associations by region High-level performance metrics across associated stores ### Response Example ```json { "campaign_id": "1000010", "campaign_name": "Spring Fresh Campaign", "total_associated_stores": 15, "store_associations": [ { "store_id": "store_001", "store_name": "Downtown Location", "store_type": "retail", "region": "Northeast", "association_status": "active", "linked_at": "2025-04-14T01:00:00.000Z", "last_updated": "2025-04-14T01:00:00.000Z", "store_specific_config": { "custom_messaging": "Spring Fresh - Now Available Downtown!", "local_promotions": ["LOCAL10", "DOWNTOWN15"], "display_settings": { "banner_position": "header", "highlight_color": "#00FF00" }, "scheduling_overrides": { "extended_hours": true, "weekend_only": false } } }, { "store_id": "store_002", "store_name": "Mall Location", "store_type": "retail", "region": "Northeast", "association_status": "active", "linked_at": "2025-04-14T01:15:00.000Z", "last_updated": "2025-04-14T01:15:00.000Z" } ], "association_summary": { "by_status": { "active": 12, "inactive": 2, "pending": 1 }, "by_store_type": { "retail": 10, "online": 3, "franchise": 2 }, "by_region": { "Northeast": 8, "Southeast": 4, "West": 3 }, "performance_overview": { "total_campaign_views": 5420, "total_conversions": 324, "average_conversion_rate": 5.97 } } } ``` **Store Selection Strategies:** * **Geographic Targeting**: Associate campaigns with stores in specific regions * **Store Type Targeting**: Target specific store formats (retail, online, franchise) * **Performance-Based**: Associate with high-performing store locations * **Test Markets**: Use select stores for campaign testing before full rollout **Configuration Options:** * **Custom Messaging**: Store-specific campaign messaging and branding * **Local Promotions**: Store-exclusive promotional codes and offers * **Display Settings**: Store-specific visual presentation preferences * **Scheduling**: Store-specific timing and duration adjustments **Store-Specific Configurations**: Each store can have unique campaign settings while maintaining the overall campaign structure. This allows for localized marketing while maintaining brand consistency. **Performance Tracking**: Use the association summary data to identify which store types or regions are performing best with the campaign, helping optimize future campaign targeting. ### Use Cases **Regional Campaign Management** * Roll out campaigns to specific geographical regions * Test campaigns in select markets before wider deployment * Customize campaigns for local preferences and regulations **Store Performance Analysis** * Identify which stores are most effective for campaigns * Compare campaign performance across store types * Optimize store selection for future campaigns **Localized Marketing** * Create store-specific messaging and promotions * Adjust campaign timing for local events and preferences * Customize visual presentation for different store formats **Campaign Optimization** * Monitor real-time performance across associated stores * Adjust store associations based on performance data * Scale successful campaigns to additional store locations ### Error Responses **Campaign Not Found** ```json { "error": "Campaign not found", "message": "The specified campaign does not exist", "code": "CAMPAIGN_NOT_FOUND" } ``` **No Store Associations** ```json { "campaign_id": "1000010", "campaign_name": "Spring Fresh Campaign", "total_associated_stores": 0, "store_associations": [], "message": "No stores are currently associated with this campaign" } ``` **Access Denied** ```json { "error": "Access denied", "message": "You do not have permission to view store associations for this campaign", "code": "ACCESS_DENIED" } ``` **Privacy Considerations**: Store association data may include sensitive business information about store performance and configurations. Ensure appropriate access controls are in place. ### Managing Associations **Adding Store Associations** * Use POST endpoint to create new campaign-store associations * Specify store-specific configurations during creation * Bulk association operations for multiple stores **Updating Associations** * Modify store-specific campaign settings * Update association status (activate/deactivate) * Adjust scheduling and display preferences **Removing Associations** * Deactivate campaign for specific stores * Remove associations while preserving historical data * Bulk removal operations for campaign cleanup **Monitoring Performance** * Track campaign effectiveness per store * Identify underperforming associations * Optimize based on store-specific analytics # Create Promotion Source: https://developer.lulacommerce.com/api-reference/campaigns/promotions/create-promotion POST {{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions Create a new promotion within a specific campaign, including discount rules, eligibility criteria, and promotional mechanics. This endpoint creates promotional offers within campaigns, enabling businesses to offer discounts, special deals, and incentives to drive customer engagement and sales. Promotions are campaign-specific marketing tools that provide customers with discounts, special offers, or incentives. Each promotion operates within the context of a parent campaign. ### Path Parameters The unique identifier of the company creating the promotion The unique identifier of the campaign that will contain this promotion ### Request Body Display name for the promotion (e.g., "Spring Sale 20% Off") Type of promotion: "percentage\_discount", "fixed\_amount\_discount", "buy\_x\_get\_y", "free\_shipping", "bundle\_deal", "loyalty\_bonus" Detailed description of the promotion offer Unique promotional code customers can use (auto-generated if not provided) Discount calculation rules and parameters The discount amount (percentage for percentage\_discount, fixed amount for fixed\_amount\_discount) Maximum discount amount for percentage-based discounts Minimum purchase amount required to apply the discount Product categories eligible for the discount Specific items excluded from the promotion Customer and order eligibility requirements Customer segments eligible for the promotion Restrict promotion to first-time customers Required customer loyalty tiers Geographic regions where promotion is valid Promotion usage restrictions and limits Maximum total number of times promotion can be used Maximum times a single customer can use the promotion Maximum daily usage across all customers Promotion timing and availability schedule When the promotion becomes active (ISO 8601 format) When the promotion expires (ISO 8601 format) Time-based availability restrictions Visual presentation and marketing settings Marketing message displayed to customers Text for promotional banners Visual style for promotion badges Display priority (1-10, higher shows first) Whether to automatically apply the promotion without requiring a code Whether this promotion can be combined with other promotions ### Request Example ```json { "promotion_name": "Spring Fresh 20% Off", "promotion_type": "percentage_discount", "description": "Get 20% off all fresh produce items during our Spring Fresh campaign", "promotion_code": "SPRING20", "discount_rules": { "discount_value": 20, "max_discount_amount": 50.00, "min_purchase_amount": 25.00, "applicable_categories": ["fresh_produce", "organic_items"], "excluded_items": ["premium_organics"] }, "eligibility_criteria": { "customer_segments": ["regular_customers", "premium_members"], "first_time_customers_only": false, "loyalty_tier_requirements": ["bronze", "silver", "gold"], "geographic_restrictions": ["northeast_region"] }, "usage_limits": { "total_usage_limit": 1000, "per_customer_limit": 3, "daily_usage_limit": 100 }, "schedule": { "start_date": "2025-04-14T00:00:00.000Z", "end_date": "2025-05-14T23:59:59.000Z", "time_restrictions": { "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"], "hours_of_day": { "start": "08:00", "end": "20:00" } } }, "display_settings": { "promotional_message": "Save 20% on Fresh Spring Produce!", "banner_text": "SPRING20 - Fresh Savings All Month Long", "badge_style": "seasonal_green", "priority_level": 8 }, "auto_apply": false, "stackable": true } ``` ### Response Unique identifier for the created promotion Parent campaign identifier Display name of the promotion Type of promotion created Promotional code (generated if not provided) Current promotion status ("draft", "scheduled", "active", "paused", "expired") Complete discount configuration as created Customer eligibility requirements Usage restrictions and current usage statistics Promotion timing and availability Visual presentation configuration Initial promotion tracking metrics Current usage count Number of unique customers who used promotion Total discount amount provided Promotion conversion rate Timestamp when the promotion was created User who created the promotion ### Response Example ```json { "promotion_id": "promo_spring_001", "campaign_id": "1000010", "promotion_name": "Spring Fresh 20% Off", "promotion_type": "percentage_discount", "promotion_code": "SPRING20", "status": "scheduled", "discount_rules": { "discount_value": 20, "max_discount_amount": 50.00, "min_purchase_amount": 25.00, "applicable_categories": ["fresh_produce", "organic_items"], "excluded_items": ["premium_organics"] }, "eligibility_criteria": { "customer_segments": ["regular_customers", "premium_members"], "first_time_customers_only": false, "loyalty_tier_requirements": ["bronze", "silver", "gold"], "geographic_restrictions": ["northeast_region"] }, "usage_limits": { "total_usage_limit": 1000, "per_customer_limit": 3, "daily_usage_limit": 100, "current_usage": { "total_used": 0, "today_used": 0, "remaining_uses": 1000 } }, "schedule": { "start_date": "2025-04-14T00:00:00.000Z", "end_date": "2025-05-14T23:59:59.000Z", "time_restrictions": { "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"], "hours_of_day": { "start": "08:00", "end": "20:00" } } }, "display_settings": { "promotional_message": "Save 20% on Fresh Spring Produce!", "banner_text": "SPRING20 - Fresh Savings All Month Long", "badge_style": "seasonal_green", "priority_level": 8 }, "auto_apply": false, "stackable": true, "performance_metrics": { "total_uses": 0, "unique_customers": 0, "total_discount_given": 0.00, "conversion_rate": 0.00 }, "created_at": "2025-04-14T01:00:00.000Z", "created_by": "marketing_admin_001" } ``` **Percentage Discounts** * Most common promotion type * Easy for customers to understand * Can include maximum discount caps **Fixed Amount Discounts** * Specific dollar amount off purchase * Effective for higher-value items * Clear value proposition **Buy X Get Y Promotions** * Encourage bulk purchases * Drive inventory movement * Increase average order value **Free Shipping Offers** * Reduce cart abandonment * Increase online conversion rates * Often combined with minimum purchase requirements **Bundle Deals** * Cross-sell related products * Increase transaction value * Simplify customer decision-making **Loyalty Bonuses** * Reward repeat customers * Increase customer retention * Build long-term relationships **Promotion Codes**: If no promotion code is provided, the system will auto-generate a unique code based on the promotion name and type. Custom codes must be unique within the company. **Performance Optimization**: Set appropriate usage limits to control promotion costs while maximizing customer engagement. Monitor performance metrics to optimize future promotions. ### Validation Rules **Naming Requirements** * Promotion names must be unique within the campaign * Names should be descriptive and customer-friendly * Maximum length of 100 characters **Discount Rules Validation** * Percentage discounts must be between 0.01% and 100% * Fixed amounts must be positive values * Minimum purchase amounts must be greater than discount amounts **Schedule Validation** * Start date must be in the future or current date * End date must be after start date * Maximum promotion duration of 365 days **Usage Limits Validation** * All usage limits must be positive integers * Per-customer limits cannot exceed total usage limits * Daily limits should consider expected traffic **Code Validation** * Promotion codes must be alphanumeric * Minimum length of 4 characters, maximum of 20 * Cannot contain profanity or reserved words ### Error Responses **Invalid Discount Configuration** ```json { "error": "Invalid discount rules", "message": "Discount percentage cannot exceed 100%", "code": "INVALID_DISCOUNT_RULES" } ``` **Duplicate Promotion Code** ```json { "error": "Promotion code already exists", "message": "The promotion code 'SPRING20' is already in use", "code": "DUPLICATE_PROMOTION_CODE" } ``` **Invalid Schedule** ```json { "error": "Invalid promotion schedule", "message": "End date must be after start date", "code": "INVALID_SCHEDULE" } ``` **Campaign Not Found** ```json { "error": "Campaign not found", "message": "The specified campaign does not exist or is not accessible", "code": "CAMPAIGN_NOT_FOUND" } ``` **Budget Considerations**: Carefully configure usage limits and maximum discount amounts to control promotional costs. Monitor usage patterns to prevent budget overruns. ### Best Practices **Strategic Planning** * Align promotions with business objectives * Consider seasonal trends and customer behavior * Set realistic but attractive discount levels **Technical Configuration** * Use meaningful promotion codes * Set appropriate usage limits * Configure proper eligibility criteria **Performance Monitoring** * Track key metrics from launch * Monitor usage patterns for optimization * Adjust limits based on performance **Customer Experience** * Write clear, compelling promotional messages * Ensure easy redemption process * Provide transparent terms and conditions **Legal Compliance** * Include necessary disclaimers * Comply with regional promotion regulations * Maintain fair and transparent practices # Delete Promotion Source: https://developer.lulacommerce.com/api-reference/campaigns/promotions/delete-promotion DELETE {{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}} Delete a promotion with comprehensive safety checks, data archival options, and impact assessment to protect business operations. This endpoint provides controlled deletion of promotions with built-in safety mechanisms to prevent accidental loss of valuable marketing data and ensure minimal disruption to ongoing business operations. Promotion deletion is a permanent action with significant business implications. The system implements multiple safety checks and offers archival options to protect against accidental data loss while maintaining operational integrity. ### Path Parameters The unique identifier of the company that owns the promotion The unique identifier of the campaign containing the promotion The unique identifier of the promotion to delete ### Query Parameters Force deletion despite safety warnings (requires elevated permissions) Whether to archive promotion data before deletion for future reference Whether to preserve analytics data in campaign-level reporting Security token required for high-impact deletions ### Request Body Business justification for deleting the promotion Confirmation that user understands the deletion impact List of alternative actions considered before deletion Alternative action that was considered Why this alternative was not chosen Specific preferences for data handling during deletion Keep customer usage records for compliance and analytics Maintain aggregated performance data for reporting Keep financial impact data for accounting purposes Remove personally identifiable information while preserving analytics ### Request Example ```json { "deletion_reason": "Promotion was created in error and conflicts with existing campaign strategy. No customer usage has occurred.", "impact_acknowledgment": true, "alternative_actions_considered": [ { "action": "Pause promotion instead of deletion", "reason_rejected": "Promotion was never intended to be active and creates confusion in campaign management" }, { "action": "Modify promotion to align with strategy", "reason_rejected": "Core concept conflicts with brand guidelines and cannot be salvaged" } ], "data_retention_preferences": { "preserve_customer_usage_history": true, "preserve_performance_metrics": true, "preserve_financial_records": true, "anonymize_customer_data": false } } ``` ### Response Unique identifier for this deletion operation The ID of the deleted promotion Parent campaign identifier Status of the deletion: "completed", "archived", "pending\_approval", "blocked" Results of pre-deletion safety validations Verification of current promotion usage Analysis of systems or processes depending on this promotion Assessment of financial implications Regulatory and policy compliance verification Summary of data preservation actions taken Reference to archived promotion data Timestamp when data was archived How long archived data will be retained Latest date for potential data recovery Comprehensive analysis of deletion effects Number of customers who used this promotion Number of orders that included this promotion Total revenue associated with deleted promotion Effect on reporting and analytics systems System-generated recommendations for similar promotions Type of alternative action recommended Detailed recommendation description Anticipated result of following the recommendation Available options for reversing the deletion Whether promotion can be recovered from archive Latest date for successful recovery Limitations or restrictions on data recovery Compliance and audit trail information Reference to detailed audit log Any required regulatory notifications Compliance with data retention policies Timestamp when the deletion was completed User who performed the deletion Method used for deletion (soft\_delete, archive\_delete, hard\_delete) ### Response Example ```json { "deletion_id": "del_promo_spring_001_20250420", "promotion_id": "promo_spring_001", "campaign_id": "1000010", "deletion_status": "completed", "safety_checks": { "active_usage_check": { "status": "passed", "current_active_users": 0, "pending_transactions": 0, "message": "No active usage detected" }, "dependency_check": { "status": "passed", "dependent_systems": [], "external_references": 0, "message": "No system dependencies found" }, "financial_impact_check": { "status": "warning", "total_revenue_impact": 18450.32, "outstanding_commitments": 0, "message": "Promotion generated significant revenue but no outstanding commitments" }, "compliance_check": { "status": "passed", "regulatory_requirements": "met", "data_retention_compliance": "compliant", "message": "All compliance requirements satisfied" } }, "archival_summary": { "archived_data_location": "archive://promotions/2025/spring_campaign/promo_spring_001", "archived_at": "2025-04-20T16:00:00.000Z", "archive_retention_period": "7 years", "recoverable_until": "2025-05-20T16:00:00.000Z" }, "impact_assessment": { "customers_affected": 189, "orders_impacted": 247, "revenue_impact": 18450.32, "analytics_impact": { "historical_reports": "preserved", "trend_analysis": "adjusted", "comparative_metrics": "normalized" } }, "alternative_recommendations": [ { "recommendation_type": "similar_promotion", "description": "Create a new seasonal promotion with similar discount structure but updated branding", "expected_outcome": "Maintain customer engagement while aligning with current strategy" }, { "recommendation_type": "customer_retention", "description": "Send targeted offers to customers who used the deleted promotion", "expected_outcome": "Minimize customer dissatisfaction from promotion removal" } ], "rollback_options": { "recovery_possible": true, "recovery_deadline": "2025-05-20T16:00:00.000Z", "recovery_limitations": [ "Some real-time metrics may need recalculation", "Customer-facing promotion codes will need regeneration", "Integration with external systems may require reactivation" ] }, "compliance_records": { "audit_log_entry": "audit_2025_04_20_promotion_deletion_001", "regulatory_notifications": [], "data_retention_compliance": { "customer_data": "preserved_as_required", "financial_records": "archived_per_policy", "analytics_data": "anonymized_and_retained" } }, "deleted_at": "2025-04-20T16:00:00.000Z", "deleted_by": "marketing_manager_002", "deletion_method": "archive_delete" } ``` **Soft Delete** * Promotion marked as deleted but data remains in active database * Can be easily recovered without data loss * Continues to appear in some administrative interfaces * Recommended for temporary removal or accidental deletions **Archive Delete** * Promotion data moved to secure archival storage * Active database cleaned of promotion references * Requires archive recovery process to restore * Balances data protection with system performance **Hard Delete** * Complete removal of promotion data from all systems * Cannot be recovered once completed * Only recommended for test data or invalid promotions * Requires special authorization and safety overrides **Recovery Window**: Deleted promotions can typically be recovered within 30 days using archived data. After this period, recovery may require special procedures or may not be possible. **Best Practice**: Before deleting promotions with significant usage history, consider deactivating them instead. This preserves data integrity while removing them from active use. ### Safety Check Details **Active Usage Validation** * Check for customers currently using promotion codes * Verify no pending transactions with promotion applied * Confirm no scheduled automatic applications * Validate no active customer communication references **System Dependency Analysis** * Scan for integration system references * Check analytics dashboard dependencies * Verify no automated marketing workflows using promotion * Confirm no customer service tool dependencies **Financial Impact Assessment** * Calculate total revenue generated by promotion * Identify any outstanding financial commitments * Assess impact on revenue projections * Verify no pending refund or adjustment requirements **Compliance and Legal Review** * Check data retention policy requirements * Verify regulatory compliance for deletion * Confirm audit trail preservation * Validate customer privacy regulation compliance **Business Process Impact** * Analyze effect on campaign performance metrics * Assess impact on customer journey mapping * Review effect on A/B testing and experimentation * Confirm no impact on loyalty program calculations ### Error Responses **Active Usage Prevention** ```json { "error": "Cannot delete active promotion", "message": "Promotion has 15 customers currently using codes and 3 pending transactions", "code": "ACTIVE_USAGE_DETECTED", "details": { "active_users": 15, "pending_transactions": 3, "suggested_action": "Deactivate promotion and wait for usage completion" } } ``` **Safety Check Failure** ```json { "error": "Safety check failed", "message": "Promotion has system dependencies that prevent deletion", "code": "SAFETY_CHECK_FAILED", "failed_checks": [ "dependency_check", "financial_impact_check" ] } ``` **Insufficient Permissions** ```json { "error": "Insufficient permissions", "message": "High-impact promotion deletion requires administrator approval", "code": "PERMISSION_DENIED", "required_permission": "promotion_delete_high_impact" } ``` **Confirmation Required** ```json { "error": "Confirmation token required", "message": "This deletion requires additional security confirmation", "code": "CONFIRMATION_REQUIRED", "confirmation_method": "email_token" } ``` **High-Impact Deletions**: Promotions with significant customer usage, revenue impact, or system dependencies require additional approvals and may be blocked from immediate deletion. ### Alternative Actions **Deactivation Instead of Deletion** * Preserves all historical data and analytics * Removes promotion from customer-facing systems * Maintains compliance and audit trails * Can be reactivated if needed in the future **Archival Without Deletion** * Moves promotion to archived status * Removes from active management interfaces * Preserves all data for future reference * Maintains complete historical integrity **Modification for Compliance** * Update promotion to meet current requirements * Adjust settings to align with new policies * Preserve customer value while ensuring compliance * Maintain business continuity **Gradual Phase-Out** * Reduce promotion visibility over time * Stop new customer acquisition * Allow existing users to complete usage * Minimize disruption to customer experience ### Recovery Procedures **Immediate Recovery (0-24 hours)** * Simple restoration from recent backups * Full data integrity preserved * Minimal system reconfiguration required * Complete restoration of all functionality **Short-term Recovery (1-30 days)** * Restoration from archived data * Some real-time metrics may need recalculation * Integration systems may require reactivation * Customer codes may need regeneration **Long-term Recovery (30+ days)** * Complex recovery process required * May involve data reconstruction * Some real-time data may be lost * Requires administrator approval and technical support **Recovery Limitations** * Real-time usage statistics may reset * Some integration configurations may be lost * Customer notification may be required * Performance metrics may show discontinuity ### Business Impact Considerations **Customer Relationship Impact** * Effect on customer satisfaction and loyalty * Impact on repeat purchase behavior * Influence on customer lifetime value * Potential for negative customer feedback **Financial Implications** * Loss of promotion-driven revenue * Impact on profit margin calculations * Effect on budget and forecasting * Implications for ROI analysis **Marketing Strategy Effects** * Impact on campaign performance metrics * Effect on customer segmentation * Influence on future promotion planning * Consequences for brand positioning **Operational Considerations** * Effect on staff training and procedures * Impact on customer service operations * Influence on inventory planning * Consequences for partner relationships # Get All Promotions Source: https://developer.lulacommerce.com/api-reference/campaigns/promotions/get-all-promotions GET {{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions Retrieve a comprehensive list of all promotions within a campaign, with advanced filtering, sorting, and analytics capabilities. This endpoint provides access to all promotions within a specific campaign, offering powerful filtering and sorting options to help businesses manage their promotional strategies effectively. This endpoint supports extensive filtering and pagination capabilities, making it ideal for promotion management dashboards, analytics reporting, and bulk operations across multiple promotions. ### Path Parameters The unique identifier of the company that owns the promotions The unique identifier of the campaign containing the promotions ### Query Parameters Filter by promotion status: "all", "draft", "scheduled", "active", "paused", "expired", "completed" Filter by promotion type: "percentage\_discount", "fixed\_amount\_discount", "buy\_x\_get\_y", "free\_shipping", "bundle\_deal", "loyalty\_bonus" Filter promotions created after this date (ISO 8601 format) Filter promotions created before this date (ISO 8601 format) Filter promotions starting after this date Filter promotions ending before this date Filter by performance level: "high\_performing", "moderate", "low\_performing", "no\_usage" Filter by discount range: "0-10", "10-25", "25-50", "50+" Filter promotions available to specific customer segment Search in promotion names, descriptions, and codes Sort field: "created\_at", "name", "status", "performance", "usage\_count", "start\_date", "end\_date" Sort direction: "asc" or "desc" Page number for pagination Number of promotions per page (max 100) Include performance metrics in the response Include archived/deleted promotions in results Include summary statistics for the filtered set ### Response The campaign identifier Name of the parent campaign Total number of promotions matching filters Pagination information for the results Current page number Total number of pages Items per page Total items across all pages Whether there are more pages Whether there are previous pages Summary of filters applied to the query Array of promotion objects matching the search criteria Unique identifier for the promotion Display name of the promotion Type of promotion Promotional code for customer use Current promotion status Brief description of the promotion Summary of discount configuration Primary discount amount/percentage Type of discount applied Maximum discount amount Minimum purchase requirement Promotion timing information Promotion start date Promotion end date Total promotion duration Time remaining until expiration Key performance indicators (if requested) Total number of promotion uses Number of unique customers Promotion conversion rate Total discount amount provided Total revenue generated Return on investment Overall performance rating Current usage status and limits Maximum total uses allowed Current number of uses Remaining uses available Percentage of limit used When the promotion was created User who created the promotion When the promotion was last modified Aggregate statistics for the filtered promotion set Count of promotions by status Count of promotions by type Aggregate performance metrics Overall usage statistics Financial impact summary ### Response Example ```json { "campaign_id": "1000010", "campaign_name": "Spring Fresh Campaign", "total_promotions": 8, "pagination": { "current_page": 1, "total_pages": 1, "per_page": 25, "total_items": 8, "has_next": false, "has_previous": false }, "filters_applied": { "status": "all", "include_metrics": true, "sort_by": "created_at", "sort_order": "desc" }, "promotions": [ { "promotion_id": "promo_spring_001", "promotion_name": "Spring Fresh 20% Off", "promotion_type": "percentage_discount", "promotion_code": "SPRING20", "status": "active", "description": "Get 20% off all fresh produce items", "discount_summary": { "discount_value": 20, "discount_type": "percentage", "max_discount": 50.00, "min_purchase": 25.00 }, "schedule": { "start_date": "2025-04-14T00:00:00.000Z", "end_date": "2025-05-14T23:59:59.000Z", "duration_days": 30, "time_remaining": "18 days" }, "performance_metrics": { "total_uses": 247, "unique_customers": 189, "conversion_rate": 15.8, "total_discount_given": 3247.85, "revenue_impact": 18450.32, "roi": 468.2, "performance_rating": "high_performing" }, "usage_limits": { "total_limit": 1000, "current_usage": 247, "remaining_uses": 753, "usage_percentage": 24.7 }, "created_at": "2025-04-14T01:00:00.000Z", "created_by": "marketing_admin_001", "last_updated": "2025-04-20T14:30:00.000Z" }, { "promotion_id": "promo_spring_002", "promotion_name": "Buy 2 Get 1 Free Organics", "promotion_type": "buy_x_get_y", "promotion_code": "ORGANIC3", "status": "active", "description": "Buy 2 organic items, get 1 free", "discount_summary": { "discount_value": 33.33, "discount_type": "buy_x_get_y", "max_discount": null, "min_purchase": 0.00 }, "schedule": { "start_date": "2025-04-15T00:00:00.000Z", "end_date": "2025-04-30T23:59:59.000Z", "duration_days": 15, "time_remaining": "3 days" }, "performance_metrics": { "total_uses": 89, "unique_customers": 76, "conversion_rate": 12.4, "total_discount_given": 1247.32, "revenue_impact": 5680.45, "roi": 355.5, "performance_rating": "moderate" }, "usage_limits": { "total_limit": 500, "current_usage": 89, "remaining_uses": 411, "usage_percentage": 17.8 }, "created_at": "2025-04-15T09:00:00.000Z", "created_by": "marketing_admin_001", "last_updated": "2025-04-15T09:00:00.000Z" } ], "summary_statistics": { "status_breakdown": { "active": 5, "scheduled": 2, "draft": 1, "paused": 0, "expired": 0, "completed": 0 }, "type_breakdown": { "percentage_discount": 4, "buy_x_get_y": 2, "fixed_amount_discount": 1, "free_shipping": 1 }, "performance_summary": { "total_uses_across_all": 542, "total_unique_customers": 387, "average_conversion_rate": 14.2, "total_discount_given": 7845.67, "total_revenue_impact": 34567.89, "average_roi": 440.6 }, "usage_summary": { "total_usage_capacity": 3500, "total_current_usage": 542, "average_usage_percentage": 18.5, "promotions_near_limit": 0 }, "financial_summary": { "total_revenue_generated": 34567.89, "total_discounts_provided": 7845.67, "net_revenue_impact": 26722.22, "average_order_value_with_promotions": 73.45 } } } ``` **Status-Based Filtering** * Filter by current promotion lifecycle stage * Identify promotions requiring attention * Separate active campaigns from drafts and archives * Track promotion performance by status **Performance-Based Filtering** * High-performing: Above average conversion and ROI * Moderate: Meeting baseline performance metrics * Low-performing: Below threshold performance * No usage: Promotions with zero customer engagement **Date Range Filtering** * Creation date ranges for administrative tracking * Active date ranges for operational planning * Expiration tracking for renewal planning * Seasonal promotion identification **Customer Segment Filtering** * Target-specific customer group promotions * Loyalty tier-based promotion management * Geographic region-specific campaigns * Demographic-targeted promotion analysis **Performance Ratings**: Promotions are automatically rated based on conversion rates, ROI, and usage patterns compared to campaign averages and historical benchmarks. **Bulk Operations**: Use filtering to identify groups of promotions for bulk operations like status changes, performance analysis, or strategic planning. ### Search Capabilities **Text Search** * Search across promotion names for quick identification * Full-text search in promotion descriptions * Promotional code pattern matching * Creator and modifier user search **Advanced Query Syntax** * Combine multiple filters for precise results * Use wildcards in text searches * Date range combinations * Performance threshold combinations **Saved Searches** * Create frequently-used filter combinations * Share search configurations across team members * Set up alerts for specific promotion criteria * Automate reporting based on saved filters **Smart Suggestions** * System suggests relevant filters based on search patterns * Recommendation of similar promotions * Identification of optimization opportunities * Performance benchmark comparisons ### Sorting and Organization **Performance-Based Sorting** * Sort by conversion rate for effectiveness analysis * Order by ROI for financial impact review * Arrange by usage count for popularity assessment * Organize by revenue impact for business value **Temporal Sorting** * Chronological creation order for administrative tracking * Start date sorting for campaign planning * End date sorting for renewal management * Last modified sorting for recent changes **Alphabetical Organization** * Name-based sorting for easy browsing * Code-based organization for systematic review * Creator-based grouping for team management * Status-based clustering for workflow optimization **Custom Sort Combinations** * Multi-field sorting for complex organization * Priority-based arrangement for urgent actions * Performance-time combinations for trend analysis * Status-performance matrices for strategic review ### Error Responses **Invalid Filter Parameters** ```json { "error": "Invalid filter parameter", "message": "Invalid promotion_type: 'invalid_type'", "code": "INVALID_FILTER_VALUE", "valid_values": ["percentage_discount", "fixed_amount_discount", "buy_x_get_y", "free_shipping", "bundle_deal", "loyalty_bonus"] } ``` **Date Range Errors** ```json { "error": "Invalid date range", "message": "created_after date must be before created_before date", "code": "INVALID_DATE_RANGE" } ``` **Pagination Errors** ```json { "error": "Invalid pagination", "message": "Page number must be positive and limit cannot exceed 100", "code": "INVALID_PAGINATION", "max_limit": 100 } ``` **Campaign Not Found** ```json { "error": "Campaign not found", "message": "The specified campaign does not exist or is not accessible", "code": "CAMPAIGN_NOT_FOUND" } ``` **Large Result Sets**: When querying campaigns with many promotions, use pagination and filtering to maintain good performance. The system may timeout on very large unfiltered requests. ### Use Cases and Applications **Campaign Management** * Monitor all promotions within a campaign * Identify underperforming promotions for optimization * Track campaign-wide promotional success * Plan promotion renewal and extension strategies **Performance Analysis** * Compare promotion effectiveness across types * Identify best-performing promotional strategies * Analyze customer response patterns * Benchmark promotion performance against goals **Operational Management** * Track promotion usage and capacity planning * Identify promotions requiring urgent attention * Manage promotion lifecycle and renewals * Coordinate marketing team efforts **Strategic Planning** * Analyze historical promotion performance * Identify successful promotion patterns * Plan future promotional strategies * Optimize promotion portfolio composition **Financial Reporting** * Calculate total promotional impact on revenue * Assess discount costs across all promotions * Analyze ROI for promotional investments * Support budget planning and allocation ### Integration with Analytics **Dashboard Integration** * Real-time promotion performance dashboards * Campaign-level promotional analytics * Customer engagement tracking * Financial impact visualization **Export Capabilities** * CSV export for offline analysis * Integration with business intelligence tools * Custom report generation * Automated reporting schedules **API Integration** * Webhook notifications for promotion events * Real-time data feeds for external systems * Integration with marketing automation platforms * Custom analytics solution connectivity **Data Warehouse Integration** * Historical data archiving * Long-term trend analysis * Cross-campaign comparison analytics * Predictive modeling support # Get Promotion Details Source: https://developer.lulacommerce.com/api-reference/campaigns/promotions/get-promotion GET {{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}} Retrieve comprehensive details for a specific promotion, including performance metrics, usage statistics, and configuration settings. This endpoint provides complete information about a specific promotion within a campaign, including real-time performance data, customer usage patterns, and detailed configuration settings. This endpoint returns comprehensive promotion data including current performance metrics, which is essential for monitoring promotion effectiveness and making data-driven optimization decisions. ### Path Parameters The unique identifier of the company that owns the promotion The unique identifier of the campaign containing the promotion The unique identifier of the promotion to retrieve ### Query Parameters Include detailed performance metrics in the response Include historical usage data and trends Time period for metrics: "today", "week", "month", "all" Include customer segment analysis data ### Response Unique identifier for the promotion Parent campaign identifier Display name of the promotion Type of promotion (percentage\_discount, fixed\_amount\_discount, etc.) Promotional code customers use to redeem Detailed description of the promotion Current promotion status (draft, scheduled, active, paused, expired, completed) Complete discount configuration and rules The discount amount or percentage Maximum discount amount for percentage-based discounts Minimum purchase amount required Product categories eligible for the discount Specific items excluded from the promotion Customer and order eligibility requirements Customer segments eligible for the promotion Whether restricted to first-time customers Required customer loyalty tiers Geographic regions where promotion is valid Promotion usage restrictions and current statistics Maximum total number of uses allowed Maximum uses per individual customer Maximum daily usage across all customers Real-time usage statistics Promotion timing and availability schedule When the promotion becomes active When the promotion expires Time-based availability restrictions Timezone for schedule interpretation Visual presentation and marketing settings Marketing message displayed to customers Text for promotional banners Visual style for promotion badges Display priority level Comprehensive promotion performance data Total number of times promotion was used Number of unique customers who used promotion Total discount amount provided to customers Total revenue generated from promotion usage Percentage of promotion views that converted to usage Average order value for promotion users Percentage of customers who used promotion multiple times Historical usage data and trends (if requested) Date of usage data point Number of uses on this date Revenue generated on this date Total discount given on this date Customer segment performance analysis (if requested) Performance metrics broken down by customer segment Customer segments with highest engagement Usage distribution across geographic regions Whether promotion is automatically applied Whether promotion can be combined with others Timestamp when promotion was created User who created the promotion Timestamp of last modification User who last modified the promotion ### Response Example ```json { "promotion_id": "promo_spring_001", "campaign_id": "1000010", "promotion_name": "Spring Fresh 20% Off", "promotion_type": "percentage_discount", "promotion_code": "SPRING20", "description": "Get 20% off all fresh produce items during our Spring Fresh campaign", "status": "active", "discount_rules": { "discount_value": 20, "max_discount_amount": 50.00, "min_purchase_amount": 25.00, "applicable_categories": ["fresh_produce", "organic_items"], "excluded_items": ["premium_organics"] }, "eligibility_criteria": { "customer_segments": ["regular_customers", "premium_members"], "first_time_customers_only": false, "loyalty_tier_requirements": ["bronze", "silver", "gold"], "geographic_restrictions": ["northeast_region"] }, "usage_limits": { "total_usage_limit": 1000, "per_customer_limit": 3, "daily_usage_limit": 100, "current_usage": { "total_used": 247, "today_used": 18, "remaining_uses": 753, "unique_customers": 189, "usage_percentage": 24.7 } }, "schedule": { "start_date": "2025-04-14T00:00:00.000Z", "end_date": "2025-05-14T23:59:59.000Z", "time_restrictions": { "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"], "hours_of_day": { "start": "08:00", "end": "20:00" } }, "timezone": "America/New_York" }, "display_settings": { "promotional_message": "Save 20% on Fresh Spring Produce!", "banner_text": "SPRING20 - Fresh Savings All Month Long", "badge_style": "seasonal_green", "priority_level": 8 }, "performance_metrics": { "total_uses": 247, "unique_customers": 189, "total_discount_given": 3247.85, "total_revenue_impact": 18450.32, "conversion_rate": 15.8, "average_order_value": 74.72, "repeat_usage_rate": 23.3, "roi": 468.2 }, "usage_history": [ { "date": "2025-04-14", "daily_uses": 23, "daily_revenue": 1654.50, "daily_discount": 208.90 }, { "date": "2025-04-15", "daily_uses": 31, "daily_revenue": 2187.30, "daily_discount": 287.45 } ], "customer_segment_analysis": { "segment_performance": [ { "segment": "regular_customers", "usage_count": 156, "conversion_rate": 14.2, "average_order_value": 68.45 }, { "segment": "premium_members", "usage_count": 91, "conversion_rate": 18.7, "average_order_value": 85.32 } ], "top_performing_segments": ["premium_members", "regular_customers"], "geographic_distribution": { "northeast_region": { "usage_count": 247, "conversion_rate": 15.8, "revenue_impact": 18450.32 } } }, "auto_apply": false, "stackable": true, "created_at": "2025-04-14T01:00:00.000Z", "created_by": "marketing_admin_001", "last_updated": "2025-04-20T14:30:00.000Z", "updated_by": "marketing_manager_002" } ``` **Usage Metrics** * **Total Uses**: Number of times the promotion code was successfully applied * **Unique Customers**: Count of individual customers who used the promotion * **Repeat Usage Rate**: Percentage of customers who used the promotion multiple times **Financial Metrics** * **Total Discount Given**: Sum of all discount amounts provided * **Revenue Impact**: Total revenue generated from orders using the promotion * **ROI**: Return on investment calculated as (Revenue - Discount) / Discount **Conversion Metrics** * **Conversion Rate**: Percentage of promotion exposures that resulted in usage * **Average Order Value**: Mean order amount for promotion users * **Usage Percentage**: Percentage of total usage limit consumed **Real-Time Data**: Performance metrics are updated in real-time, providing current usage statistics and performance indicators for active promotions. **Optimization Insights**: Use customer segment analysis and usage history to identify the most effective promotion strategies and optimize future campaigns. ### Status Definitions **Draft** * Promotion is created but not yet scheduled * Can be freely edited and modified * Not visible to customers **Scheduled** * Promotion is configured and waiting for start date * Limited editing capabilities * Not yet active for customers **Active** * Promotion is currently running and available * Customers can use the promotion code * Performance metrics are being tracked **Paused** * Temporarily disabled by administrator * Can be reactivated without losing configuration * Not available to customers during pause **Expired** * Promotion has passed its end date * No longer available for new usage * Historical data remains accessible **Completed** * Promotion reached its usage limit before expiration * No longer available for new usage * All limits have been exhausted ### Error Responses **Promotion Not Found** ```json { "error": "Promotion not found", "message": "The specified promotion does not exist", "code": "PROMOTION_NOT_FOUND" } ``` **Campaign Mismatch** ```json { "error": "Campaign mismatch", "message": "The promotion does not belong to the specified campaign", "code": "CAMPAIGN_MISMATCH" } ``` **Access Denied** ```json { "error": "Access denied", "message": "You do not have permission to view this promotion", "code": "ACCESS_DENIED" } ``` **Invalid Metrics Period** ```json { "error": "Invalid metrics period", "message": "Metrics period must be one of: today, week, month, all", "code": "INVALID_METRICS_PERIOD" } ``` **Performance Impact**: Including usage history and customer segment analysis significantly increases response size. Use these options judiciously based on actual needs. ### Data Analysis Use Cases **Performance Monitoring** * Track real-time promotion effectiveness * Monitor usage patterns and trends * Identify peak usage periods **Customer Behavior Analysis** * Understand which customer segments respond best * Analyze repeat usage patterns * Identify geographic performance variations **Financial Impact Assessment** * Calculate true ROI of promotional campaigns * Understand cost vs. revenue relationship * Optimize discount levels for maximum impact **Strategic Planning** * Use historical data for future promotion planning * Identify successful promotion characteristics * Optimize timing and targeting strategies ### Integration with Analytics **Business Intelligence Systems** * Export promotion performance data * Integrate with existing BI dashboards * Create custom analytics reports **Marketing Automation** * Trigger follow-up campaigns based on usage * Segment customers based on promotion behavior * Automate promotion optimization **Inventory Management** * Track promotion impact on inventory movement * Adjust stock levels based on promotion performance * Plan inventory for future promotional periods **Customer Relationship Management** * Update customer profiles with promotion usage * Create targeted segments for future campaigns * Track customer lifetime value impact # Update Promotion Source: https://developer.lulacommerce.com/api-reference/campaigns/promotions/update-promotion PUT {{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}} Update an existing promotion's configuration, including discount rules, eligibility criteria, scheduling, and display settings. This endpoint allows modification of existing promotions while maintaining data integrity and ensuring business rules are followed. Different fields have varying update restrictions based on promotion status. Promotion updates are subject to status-based restrictions. Active promotions have limited modifiable fields to prevent disruption to ongoing customer experiences, while draft promotions can be freely modified. ### Path Parameters The unique identifier of the company that owns the promotion The unique identifier of the campaign containing the promotion The unique identifier of the promotion to update ### Request Body Updated display name for the promotion Updated detailed description of the promotion offer Updated discount calculation rules and parameters Updated discount amount (restrictions apply for active promotions) Updated maximum discount amount for percentage-based discounts Updated minimum purchase amount required Updated product categories eligible for the discount Updated specific items excluded from the promotion Updated customer and order eligibility requirements Updated customer segments eligible for the promotion Updated restriction to first-time customers Updated required customer loyalty tiers Updated geographic regions where promotion is valid Updated promotion usage restrictions and limits Updated maximum total number of times promotion can be used Updated maximum times a single customer can use the promotion Updated maximum daily usage across all customers Updated promotion timing and availability schedule Updated promotion start date (restrictions apply for active promotions) Updated promotion end date Updated time-based availability restrictions Updated visual presentation and marketing settings Updated marketing message displayed to customers Updated text for promotional banners Updated visual style for promotion badges Updated display priority (1-10, higher shows first) Action to perform on promotion status: "activate", "pause", "resume", "deactivate" Updated setting for automatic application without requiring a code Updated setting for combination with other promotions Reason for the update (for audit trail) ### Request Example ```json { "promotion_name": "Spring Fresh 25% Off - Extended", "description": "Get 25% off all fresh produce items during our extended Spring Fresh campaign", "discount_rules": { "discount_value": 25, "max_discount_amount": 75.00, "min_purchase_amount": 20.00, "applicable_categories": ["fresh_produce", "organic_items", "seasonal_items"], "excluded_items": ["premium_organics"] }, "usage_limits": { "total_usage_limit": 1500, "per_customer_limit": 5, "daily_usage_limit": 150 }, "schedule": { "end_date": "2025-05-31T23:59:59.000Z", "time_restrictions": { "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday"], "hours_of_day": { "start": "06:00", "end": "22:00" } } }, "display_settings": { "promotional_message": "Save 25% on Fresh Spring Produce - Extended Through May!", "banner_text": "SPRING20 - Even More Fresh Savings!", "priority_level": 9 }, "stackable": true, "update_reason": "Extending promotion due to high customer engagement and positive ROI" } ``` ### Response Unique identifier for the updated promotion Parent campaign identifier Updated display name of the promotion Current promotion status after update List of fields that were successfully updated List of fields that could not be updated due to restrictions Field that was rejected Reason for rejection Current value that remains unchanged Complete updated discount configuration Updated customer eligibility requirements Updated usage restrictions with current statistics Updated promotion timing and availability Updated visual presentation configuration Estimated impact of changes on promotion performance Projected change in usage patterns Estimated revenue impact of changes Notes about customer experience changes Non-blocking warnings about the updated configuration Timestamp of this update User who performed the update Recent update history for audit purposes When the update occurred User who made the update List of modified fields Reason for the update ### Response Example ```json { "promotion_id": "promo_spring_001", "campaign_id": "1000010", "promotion_name": "Spring Fresh 25% Off - Extended", "status": "active", "updates_applied": [ "promotion_name", "description", "discount_rules.discount_value", "discount_rules.max_discount_amount", "discount_rules.applicable_categories", "usage_limits.total_usage_limit", "usage_limits.per_customer_limit", "schedule.end_date", "schedule.time_restrictions", "display_settings.promotional_message", "display_settings.banner_text", "display_settings.priority_level" ], "updates_rejected": [ { "field": "discount_rules.min_purchase_amount", "reason": "Cannot decrease minimum purchase amount for active promotion with existing usage", "current_value": "25.00" } ], "discount_rules": { "discount_value": 25, "max_discount_amount": 75.00, "min_purchase_amount": 25.00, "applicable_categories": ["fresh_produce", "organic_items", "seasonal_items"], "excluded_items": ["premium_organics"] }, "eligibility_criteria": { "customer_segments": ["regular_customers", "premium_members"], "first_time_customers_only": false, "loyalty_tier_requirements": ["bronze", "silver", "gold"], "geographic_restrictions": ["northeast_region"] }, "usage_limits": { "total_usage_limit": 1500, "per_customer_limit": 5, "daily_usage_limit": 150, "current_usage": { "total_used": 247, "today_used": 18, "remaining_uses": 1253, "unique_customers": 189 } }, "schedule": { "start_date": "2025-04-14T00:00:00.000Z", "end_date": "2025-05-31T23:59:59.000Z", "time_restrictions": { "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday"], "hours_of_day": { "start": "06:00", "end": "22:00" } } }, "display_settings": { "promotional_message": "Save 25% on Fresh Spring Produce - Extended Through May!", "banner_text": "SPRING20 - Even More Fresh Savings!", "badge_style": "seasonal_green", "priority_level": 9 }, "performance_impact": { "estimated_usage_change": "Increased usage expected due to higher discount and extended availability", "revenue_impact_estimate": "Positive impact expected despite higher discount due to extended duration", "customer_impact_notes": [ "Existing customers will see improved offer", "Extended weekend availability may increase usage", "Higher discount may attract new customer segments" ] }, "validation_warnings": [ "Increasing discount from 20% to 25% will reduce profit margins", "Extended end date overlaps with Memorial Day weekend - consider holiday impact" ], "last_updated": "2025-04-20T15:45:00.000Z", "updated_by": "marketing_manager_002", "update_history": [ { "timestamp": "2025-04-20T15:45:00.000Z", "updated_by": "marketing_manager_002", "fields_changed": ["discount_value", "usage_limits", "schedule.end_date"], "reason": "Extending promotion due to high customer engagement and positive ROI" }, { "timestamp": "2025-04-15T10:30:00.000Z", "updated_by": "marketing_admin_001", "fields_changed": ["display_settings.banner_text"], "reason": "Updated banner text for clarity" } ] } ``` **Draft Status** * All fields can be freely modified * No restrictions on changes * Updates take effect immediately **Scheduled Status** * Most fields can be updated * Start date can be modified if not within 24 hours * Promotion code cannot be changed **Active Status** * Limited field updates allowed * Cannot decrease discount value or minimum purchase amounts * Cannot restrict eligibility criteria * Can extend end date and increase usage limits * Display settings can be updated **Paused Status** * Same restrictions as active status * Can modify status to resume or deactivate * Schedule modifications allowed **Expired/Completed Status** * No modifications allowed except for display settings * Updates primarily for archival and reporting purposes * Cannot reactivate expired promotions **Update Safety**: The system prevents updates that could negatively impact customers who have already used the promotion or are in the process of using it. **Performance Optimization**: When updating active promotions, monitor performance metrics closely to ensure changes have the desired effect on customer engagement and business objectives. ### Field Update Rules **Discount Rules** * Cannot decrease discount percentage for active promotions * Cannot decrease maximum discount amount if customers have used higher amounts * Cannot increase minimum purchase amount for active promotions * Adding categories is allowed, removing requires validation **Usage Limits** * Can increase limits at any time * Cannot decrease below current usage levels * Per-customer limits cannot exceed total limits * Daily limits adjust automatically if needed **Schedule Changes** * Cannot move start date to the past * Can extend end date for any status except expired * Time restrictions can be expanded but not reduced for active promotions * Timezone changes require special validation **Eligibility Criteria** * Cannot make criteria more restrictive for active promotions * Can expand customer segments and geographic regions * Loyalty tier requirements can be relaxed but not tightened * New restrictions apply only to future usage ### Status Actions **Activate** * Move from draft or scheduled to active * Requires valid configuration and future or current start date * Begins tracking performance metrics **Pause** * Temporarily disable active promotion * Preserves configuration and usage statistics * Can be resumed later **Resume** * Reactivate a paused promotion * Continues from where it left off * No configuration reset required **Deactivate** * Permanently disable promotion before natural expiration * Cannot be reactivated * Preserves all historical data ### Error Responses **Invalid Update for Status** ```json { "error": "Invalid update for promotion status", "message": "Cannot decrease discount value for active promotion", "code": "INVALID_UPDATE_FOR_STATUS", "current_status": "active", "rejected_field": "discount_rules.discount_value" } ``` **Validation Failure** ```json { "error": "Validation failed", "message": "End date must be after start date", "code": "VALIDATION_FAILED", "field": "schedule.end_date" } ``` **Usage Limit Conflict** ```json { "error": "Usage limit conflict", "message": "Cannot set total usage limit below current usage count", "code": "USAGE_LIMIT_CONFLICT", "current_usage": 247, "requested_limit": 200 } ``` **Promotion Not Found** ```json { "error": "Promotion not found", "message": "The specified promotion does not exist", "code": "PROMOTION_NOT_FOUND" } ``` **Customer Impact**: Updates to active promotions may affect customer experience. Consider the timing of updates and communicate significant changes to customers when appropriate. ### Best Practices **Planning Updates** * Review current usage patterns before making changes * Consider customer impact of modifications * Test changes in staging environment when possible * Document reasons for updates for audit trail **Active Promotion Updates** * Prefer extending rather than restricting benefits * Update display settings for immediate customer visibility * Monitor performance impact after changes * Communicate significant changes to customer service team **Performance Monitoring** * Track metrics before and after updates * Set up alerts for unexpected usage pattern changes * Review customer feedback for update impact * Adjust based on real-world performance data **Compliance and Audit** * Maintain detailed update logs * Include business justification for changes * Follow approval processes for significant modifications * Ensure regulatory compliance for promotional changes ### Integration Considerations **Frontend Applications** * Updated display settings reflect immediately * Cache invalidation may be required * Mobile app synchronization timing * Real-time notification systems **Analytics Systems** * Performance metric recalculation * Historical data integrity maintenance * Reporting dashboard updates * Trend analysis adjustments **Customer Communications** * Email marketing system updates * Push notification content changes * Website banner modifications * Social media content coordination **Business Operations** * Inventory planning adjustments * Staff training on promotion changes * Customer service preparation * Financial impact assessment # Update Campaign Source: https://developer.lulacommerce.com/api-reference/campaigns/update-campaign PUT {{stores_service_api_base_url}}/stores/company/{{company_id}}/campaigns/{{campaign_id}}/stores Update an existing campaign's configuration including name, description, schedule, and targeting parameters. This endpoint allows you to modify existing campaign settings including basic information, scheduling, targeting criteria, and promotional parameters. Updates are applied immediately and affect all associated stores and promotions. Campaign updates are immediately effective and will impact any active promotions or store associations. Consider the timing of updates for campaigns that are currently running. ### Path Parameters The unique identifier of the company that owns the campaign The unique identifier of the campaign to update ### Request Body Updated campaign name Updated campaign description Unique campaign identifier for internal tracking Updated campaign start time (ISO 8601 format) Updated campaign end time (ISO 8601 format) Updated campaign status: "active", "inactive", "scheduled", "expired" ### Response Indicates whether the update was successful Confirmation message or error details The ID of the updated campaign List of fields that were successfully updated Whether changes take effect immediately Timestamp when the update was applied ### Request Example ```json { "name": "Bi-Yearly Specials", "description": "Bi-yearly promotions and special offers for customers", "campaign_identifier": "BI_YEARLY_SPECIALS", "starts_at": "2024-01-01T00:00:00.000Z", "ends_at": "2999-12-31T23:59:59.000Z", "status": "active" } ``` ### Response Example ```json { "success": true, "message": "Campaign successfully updated", "campaign_id": "1000010", "updated_fields": [ "name", "description", "campaign_identifier", "starts_at", "ends_at", "status" ], "effective_immediately": true, "timestamp": "2024-01-15T14:30:00Z" } ``` When a campaign is updated, the following components are affected: **Immediate Changes:** * Campaign visibility in customer applications * Promotion availability and application * Store association effectiveness * Marketing material display **Scheduling Changes:** * Start/end time modifications affect promotion windows * Status changes immediately activate or deactivate campaigns * Future scheduling adjustments plan automatic activation **Store Impact:** * All associated stores receive updated campaign information * POS systems sync new campaign parameters * Customer-facing displays update automatically **Timing Considerations**: Updates to active campaigns take effect immediately. For scheduled changes, consider creating new campaigns or using the scheduling features instead of updating active campaigns. **Version Control**: The system maintains an audit trail of all campaign changes. You can track who made changes and when for compliance and analysis purposes. ### Update Scenarios **Campaign Extension** * Extend successful campaigns beyond original end date * Adjust start dates for delayed campaign launches * Modify timing based on performance data **Status Management** * Activate scheduled campaigns early * Pause active campaigns temporarily * Reactivate previously inactive campaigns **Content Updates** * Update campaign descriptions for clarity * Modify campaign names for better recognition * Adjust campaign identifiers for tracking **Performance Optimization** * Modify campaigns based on analytics data * Adjust targeting based on customer response * Update promotional parameters for better results ### Error Responses **Campaign Not Found** ```json { "success": false, "message": "Campaign not found", "error_code": "CAMPAIGN_NOT_FOUND", "campaign_id": "invalid-id" } ``` **Invalid Date Range** ```json { "success": false, "message": "End date must be after start date", "error_code": "INVALID_DATE_RANGE" } ``` **Campaign Not Modifiable** ```json { "success": false, "message": "Campaign cannot be modified in current status", "error_code": "CAMPAIGN_NOT_MODIFIABLE", "current_status": "expired" } ``` **Validation Error** ```json { "success": false, "message": "Field validation failed", "error_code": "VALIDATION_ERROR", "validation_errors": [ { "field": "name", "error": "Campaign name must be unique within company" } ] } ``` **Active Campaign Updates**: Modifying active campaigns affects real-time promotions and customer experience. Consider the impact on current customers and orders in progress. ### Field Validation **name** * Maximum length: 200 characters * Must be unique within the company * Cannot be empty if provided **description** * Maximum length: 1000 characters * Supports basic formatting * Optional field **campaign\_identifier** * Must be unique across all campaigns * Alphanumeric and underscore characters only * Used for API and system integration **starts\_at / ends\_at** * Must be valid ISO 8601 timestamp * End time must be after start time * Past dates allowed for historical campaigns **status** * Must be valid status value * Status transitions must follow business rules * Some status changes may require additional permissions # Get Job Status Of Ingestion Source: https://developer.lulacommerce.com/api-reference/catalog/get-job-status GET {{micro_service_base_url}}/inventory-service-v2/jobs/14109 This endpoint allows you to check the status of a background job, typically used to monitor the progress of bulk product uploads and inventory ingestion processes. This endpoint provides status information for asynchronous jobs such as CSV uploads, JSON bulk imports, and inventory updates. Use this to track the progress and completion status of your data ingestion operations. Job IDs are typically returned from other endpoints that initiate background processing tasks. ### Path Parameters The unique identifier of the job you want to check ### Response The response structure will depend on the job type and current status. Common response fields include: Current job status (e.g., "pending", "processing", "completed", "failed") Job completion percentage (0-100) Job creation timestamp Last status update timestamp Error details if the job failed Poll this endpoint periodically to monitor long-running import jobs. Most jobs complete within a few minutes, but large datasets may take longer. Job status information may only be available for a limited time after completion. Check job status promptly after initiating background tasks. # Get Store Inventory Source: https://developer.lulacommerce.com/api-reference/catalog/get-store-inventory GET {{micro_service_base_url}}/inventory/v2/{{store_id}}/inventory This endpoint retrieves the complete inventory for a specific store, including product details, pricing, quantities, and category information. This endpoint returns a paginated list of all products in your store's inventory with comprehensive details including pricing, stock levels, and category information. ### Query Parameters Maximum number of items to return per page Number of items to skip for pagination Filter by product active status Minimum price filter (in cents) Maximum price filter (in cents) Field to order results by Sort direction. Values: "ASC" or "DESC" ### Response Array of inventory items Internal item ID Product image URL Product name Product description Product size Product category information Category ID Category name Category display order Creation timestamp Last update timestamp Product price Product UPC code Available quantity External product identifier Store identifier Whether the product can be edited Display item price Whether product is available on DoorDash Whether product is available on Uber Eats Whether product is available on Grub Hub ### Response Example ```json [ { "id": "58", "image": "https://lula-inventory-service-staging.s3.amazonaws.com/images/1000019/Candy/1014132_1749556811814.webp", "name": "Wrigley's 5 Rain Spearmint Mega Pack", "description": "35 sticks", "size": "", "category": { "id": "ae8c7e12-4372-4266-9859-42d07559131b", "name": "Candy", "category_order": "2100", "createdAt": "2021-10-21T15:15:12.217Z", "updatedAt": "2021-10-21T15:15:12.217Z" }, "price": "99.80", "upc": "22000017901", "quantity": 50, "external_id": "22000017901", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "is_editable": true, "dsp_item_price": 129.74, "is_added_to_doordash": false, "is_added_to_ubereats": false, "is_added_to_grub_hub": false } ] ``` Use the limit and offset parameters to implement pagination for large inventories. The active parameter helps filter between active and inactive products. # Modifiers Overview Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers Create and manage product customization options with modifier groups, enabling customers to personalize their orders with sizes, add-ons, and variations. Modifier groups are powerful tools that allow you to create customizable product options. They enable customers to personalize their orders by selecting from predefined choices like sizes, add-ons, cooking preferences, and other variations. ## What are Modifier Groups? Modifier groups organize related customization options into logical categories. For example: * **Size Options**: Small, Medium, Large * **Add-ons**: Extra cheese, bacon, avocado * **Preparation**: Rare, medium, well-done * **Flavors**: Vanilla, chocolate, strawberry ## Key Components ### Modifier Groups The container that defines: * **Quantity Rules**: Minimum and maximum selections required * **Pricing Rules**: Free options vs. premium add-ons * **Display Order**: How options appear to customers * **Status**: Active or inactive modifier groups ### Modifier Options Individual choices within a group: * **Store Items**: Products that serve as customization options * **Pricing**: Additional cost for premium options * **Availability**: Active or inactive options ### Item Mappings Links between products and modifier groups: * **Product Association**: Which items can be customized * **Group Assignment**: Which modifier groups apply to each product ## Management Operations Set up new modifier groups with custom rules and constraints Add, remove, and organize customization choices Associate products with relevant modifier groups Review configurations and make adjustments as needed ## Business Benefits ### Enhanced Customer Experience * **Personalization**: Customers can customize orders to their preferences * **Clarity**: Organized options make selection easier * **Flexibility**: Support for complex product variations ### Operational Efficiency * **Centralized Management**: Modify options across multiple products simultaneously * **Automated Pricing**: Consistent pricing rules for add-ons and variations * **Order Accuracy**: Structured customization reduces confusion ### Revenue Optimization * **Upselling**: Premium options increase average order value * **Menu Flexibility**: Easily adapt to seasonal or promotional changes * **Customer Satisfaction**: Better customization leads to higher satisfaction ## Best Practices * Group related options together (e.g., all size options in one group) * Use clear, descriptive names for groups and options * Set appropriate minimum and maximum selection limits * Consider the logical flow of customer decision-making * Use free options for basic choices (e.g., size selections) * Apply additional charges for premium add-ons * Keep pricing simple and transparent * Consider offering free options to encourage customization * Only link relevant modifier groups to products * Avoid overwhelming customers with too many options * Test the customer experience before launching * Regularly review and optimize modifier assignments Changes to modifier groups immediately affect customer ordering experience. Test modifications in a staging environment when possible. Start with simple modifier groups and gradually add complexity as you learn what works best for your customers and operations. # Create Modifier Group Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers/create-modifier-group POST {{micro_service_base_url}}/inventory/stores/{{store_id}}/modifier-groups/ This endpoint creates a new modifier group for a store. Modifier groups allow you to organize customization options that can be applied to menu items. This endpoint creates a new modifier group that can be used to organize customization options for your menu items. Modifier groups define the rules and constraints for how customers can customize their orders. Modifier groups are essential for managing product customizations like sizes, add-ons, and variations. ### Body Name of the modifier group. Example: "MG007" Description of the modifier group. Example: "Modifier group for drinks" The unique identifier of the store Minimum number of options customer must select Maximum number of options customer can select Display order precedence for the modifier group Type of options in this group. Example: "Customization" Maximum number of free options allowed Maximum quantity for each option Status of the modifier group. Values: "active" or "inactive" Array of modifier option IDs to associate with this group Array of store item IDs to link with this modifier group ### Request Example ```json { "name": "MG007", "description": "Modifier group for drinks", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "min_quantity": 0, "max_quantity": 2, "precedence": 0, "option_type": "Customization", "max_free_options": 0, "max_options_qty": 2, "status": "active", "modifier_options": ["2edc15af-2552-45a2-a149-d670279e27f3","cfb70950-996e-4dd4-8b43-60b86fb9cc17"], "linked_store_items": ["3dbe1e78-c746-4940-8db8-ef468c738324","3dbe1e78-c746-4940-8db8-ef468c738324"] } ``` ### Response This endpoint processes the request and creates the modifier group. No response body is provided upon successful creation. Use modifier groups to organize related customization options like "Size Options", "Add-ons", or "Preparation Methods". Ensure that min\_quantity is not greater than max\_quantity, and that the linked store items exist in your inventory. # Create Modifier Group Linked Items Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers/create-modifier-group-linked-items POST {{micro_service_base_url}}/inventory/stores/{{store_id}}/modifier-groups/{{modifier_group_id}}/mappings This endpoint links store items to a modifier group, allowing those items to use the customization options defined in the modifier group. This endpoint creates mappings between store items and modifier groups, enabling customers to customize specific products with the options available in the modifier group. For example, linking beverages to a "Size" modifier group. Linked items will display the modifier group's options as customization choices for customers. ### Path Parameters The unique identifier of the store The unique identifier of the modifier group ### Body Array of store items to link with this modifier group ID of the store item to link to the modifier group Status of the link. Values: "active" or "inactive" ### Request Example ```json [ { "store_item_id": "12e14a84-ee4f-48e6-ad31-4daa956ae161", "status": "active" }, { "store_item_id": "0bc5fbc2-5882-4a48-9ba5-e30997a3b027", "status": "active" }, { "store_item_id": "6f040fbc-b531-42fc-8c2a-5966a03bb4cd", "status": "active" }, { "store_item_id": "b2d2e7d4-619d-478d-97d7-ba72590ae4e0", "status": "active" } ] ``` ### Response Indicates if the operation was successful Array of successfully linked items ID of the modifier group ID of the linked store item Status of the link Array of item IDs that were already linked to this modifier group Success message describing the operation result ### Response Example ```json { "success": true, "linkedItems": [ { "modifier_group_id": "1000118", "store_item_id": "b2d2e7d4-619d-478d-97d7-ba72590ae4e0", "status": "active" } ], "alreadyExisting": [ "1000025", "1000089", "1000024" ], "message": "Store item modifier group mappings created successfully" } ``` Items that are already linked to the modifier group will be listed in the "alreadyExisting" array and won't be duplicated. Only items with "active" status will be available for customer customization. Use "inactive" to temporarily disable customization for specific items. # Create Modifier Group Options Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers/create-modifier-group-options POST {{micro_service_base_url}}/inventory/stores/{{store_id}}/modifier-groups/{{modifier_group_id}}/options This endpoint adds new options to an existing modifier group. These options represent the individual choices customers can select within a modifier group. This endpoint creates new options within an existing modifier group. Each option represents a specific choice that customers can make when customizing their order, such as "Small", "Medium", "Large" for a size modifier group. Options must be associated with existing store items and modifier groups. ### Path Parameters The unique identifier of the store The unique identifier of the modifier group ### Body Array of modifier option objects to create ID of the store item to use as an option ID of the modifier group this option belongs to Additional price for this option (can be 0) Status of the option. Values: "active" or "inactive" ### Request Example ```json [ { "store_item_id": "3e3e0adb-5555-4832-9632-8bb71d861281", "modifier_group_id": "{{modifier_group_id}}", "price": 0, "status": "active" } ] ``` ### Response Array of created modifier option objects Creation timestamp Last update timestamp External identifier for the option Internal option ID Associated store item ID Parent modifier group ID Option price Option status Display order precedence Default quantity for this option Deletion timestamp (null if not deleted) ### Response Example ```json [ { "createdAt": "2024-04-24T07:41:30.249Z", "updatedAt": "2024-04-24T07:41:30.249Z", "external_id": "ac873a62-7370-488f-9f09-d83d4ca932d8", "id": "1000008", "store_item_id": "3e3e0adb-5555-4832-9632-8bb71d861281", "modifier_group_id": "1000000", "price": "0.00", "status": "active", "precedence": 0, "default_qty": 0, "deletedAt": null } ] ``` Set price to 0 for options that don't add extra cost. Use positive values for premium options or add-ons. Ensure the store\_item\_id exists in your inventory before creating the option. # Delete Linked Items From Modifier Group Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers/delete-linked-items-from-modifier-group DELETE {{micro_service_base_url}}/inventory/stores/{{store_id}}/modifier-groups/{{modifier_group_id}}/mappings This endpoint removes the association between store items and a modifier group, preventing those items from using the modifier group's customization options. This endpoint removes the link between store items and a modifier group. After unlinking, customers will no longer see the modifier group's customization options for those specific items. Removing item mappings will immediately affect customer ordering experience. Ensure this change aligns with your menu strategy. ### Path Parameters The unique identifier of the store The unique identifier of the modifier group ### Body Array of mapping IDs to delete from the modifier group ### Request Example ```json [1000024, 1000025] ``` ### Response Indicates if the operation was successful Array of mapping IDs that were successfully deleted Array of mapping IDs that could not be deleted (may not exist or have dependencies) Success message describing the operation result ### Response Example ```json { "success": true, "deletedLinkedItems": [ 1000025 ], "notDeletedLinkedItems": [ 1000024 ], "message": "Store item modifier group mapping deleted successfully" } ``` Mappings that couldn't be deleted may be referenced by pending orders or have other active dependencies. Before deleting mappings, consider if any active orders depend on these customization options. This helps prevent order fulfillment issues. # Delete Modifier Group Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers/delete-modifier-group DELETE {{micro_service_base_url}}/inventory/stores/{{store_id}}/modifier-groups/{{modifier_group_id}} This endpoint permanently deletes a modifier group and all its associated options and mappings. Use with caution as this action cannot be undone. This endpoint completely removes a modifier group from your store, including all its options and item mappings. Once deleted, customers will no longer see any customization options that were provided by this modifier group. This action permanently deletes the modifier group and cannot be undone. Ensure you have backups if needed and verify that no active orders depend on this modifier group. ### Path Parameters The unique identifier of the store The unique identifier of the modifier group to delete ### Response Indicates if the deletion was successful Success message confirming the deletion ### Response Example ```json { "success": true, "message": "Modifier group 1000000 deleted successfully" } ``` No request body is required for this endpoint. The modifier group ID in the URL path specifies which group to delete. Deleting a modifier group will also remove all associated options and item mappings. Consider exporting or backing up the configuration if you might need to recreate it later. Before deleting, consider setting the modifier group status to "inactive" to test the impact on your menu without permanent deletion. # Delete Modifier Group Option From Modifier Group Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers/delete-modifier-group-option DELETE {{micro_service_base_url}}/inventory/stores/{{store_id}}/modifier-groups/{{modifier_group_id}}/options This endpoint removes specific options from a modifier group. Use this to eliminate unwanted customization choices or clean up outdated options. This endpoint allows you to remove specific options from a modifier group. This is useful when you want to discontinue certain customization choices or clean up options that are no longer relevant. Deleting modifier options will remove them from all associated menu items. This action cannot be undone. ### Path Parameters The unique identifier of the store The unique identifier of the modifier group ### Body Array of modifier option IDs to delete from the group ### Request Example ```json [ 1000218, 1000219 ] ``` ### Response Indicates if the operation was successful Array of option IDs that were successfully deleted Array of option IDs that could not be deleted (may not exist or have dependencies) Success message describing the operation result ### Response Example ```json { "success": true, "deletedOptions": [ 1000218 ], "notDeletedOptions": [ 1000219 ], "message": "Modifier options deleted successfully" } ``` Options that couldn't be deleted may be referenced by existing orders or have other dependencies. Check the "notDeletedOptions" array for details. Consider setting options to "inactive" status instead of deleting them if you want to preserve historical order data. # Get List Of Modifier Groups Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers/get-list-of-modifier-groups GET {{micro_service_base_url}}/inventory/stores/{{store_id}}/modifier-groups/ This endpoint retrieves a list of all modifier groups for a specific store, with options for filtering, searching, and pagination. This endpoint returns a comprehensive list of modifier groups configured for your store. You can filter by status, search by name, and control the ordering of results to find specific modifier groups quickly. This endpoint provides an overview of all your customization options, helping you manage and organize your menu modifiers effectively. ### Path Parameters The unique identifier of the store ### Query Parameters Number of records to skip for pagination Search term to filter modifier groups by name Sort order for results. Values: "ASC" or "DESC" Filter by modifier group status. Values: "active" or "inactive" ### Response Array of modifier group objects Unique identifier for the modifier group Name of the modifier group Minimum number of options customer must select Maximum number of options customer can select Display order precedence Type of options in this group Maximum number of free options allowed Maximum quantity for each option Current status of the modifier group Comma-separated list of linked option names Comma-separated list of linked item names ### Response Example ```json [ { "id": "1000054", "name": "Choose your Sandwich Type", "min_quantity": 1, "max_quantity": 1, "precedence": 0, "option_type": "Customization", "max_free_options": 0, "max_options_qty": null, "status": "active", "linked_options": "Small,Large,Wrap", "linked_items": "Build Your Own Sandwich,Build Your Own Sandwich,Build Your Own Sandwich" }, { "id": "1000055", "name": "Choice of Meat", "min_quantity": 1, "max_quantity": 1, "precedence": 0, "option_type": "Customization", "max_free_options": 0, "max_options_qty": null, "status": "active", "linked_options": "Egg Salad,Roast Beef,Honey Ham,Turkey,Salami,Crandberry Walnut Chicken Salad,In-Store Made Chicken Salad,Buffalo Style Chicken Salad,Tuna Salad", "linked_items": "Build Your Own Sandwich,Build Your Own Sandwich,Build Your Own Sandwich,Build Your Own Sandwich,Build Your Own Sandwich,Build Your Own Sandwich,Build Your Own Sandwich,Build Your Own Sandwich,Build Your Own Sandwich" } ] ``` Use the search\_string parameter to quickly find specific modifier groups by name. The status filter helps you view only active or inactive groups. The linked\_options and linked\_items fields provide a quick overview of what's connected to each modifier group without needing additional API calls. # Get Modifier Group Details Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers/get-modifier-group-details GET {{micro_service_base_url}}/inventory/stores/{{store_id}}/modifier-groups/{{modifier_group_id}} This endpoint retrieves comprehensive details about a specific modifier group, including all its options, linked items, and complete configuration. This endpoint provides detailed information about a specific modifier group, including all associated options, linked store items, and complete configuration details. This is useful for reviewing or auditing modifier group setups. This endpoint returns the complete structure of a modifier group, making it ideal for detailed analysis or debugging configuration issues. ### Path Parameters The unique identifier of the store The unique identifier of the modifier group ### Response Array containing the modifier group details (typically one object) Unique identifier for the modifier group Name of the modifier group Minimum number of options customer must select Maximum number of options customer can select Display order precedence Type of options in this group Associated store identifier Maximum number of free options allowed Maximum quantity for each option Current status of the modifier group External identifier for the modifier group Creation timestamp Last update timestamp Deletion timestamp (null if not deleted) Description of the modifier group Number of items linked to this modifier group Number of options in this modifier group Array of linked store items with full details Array of all options in this modifier group with full details ### Response Example ```json [ { "id": "1000124", "name": "MG Test 3 - Updated", "min_quantity": 0, "max_quantity": 2, "precedence": 0, "option_type": "Customization", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "max_free_options": 0, "max_options_qty": 2, "status": "active", "external_id": "5606aa02-34ce-4ed1-819b-b76bc81151c0", "createdAt": "2024-05-02T00:57:35.628Z", "updatedAt": "2024-05-02T00:58:01.654Z", "deletedAt": null, "description": "Modifier group for drinks", "linked_items_count": "2", "options_count": "3", "store_item_modifier_groups_mapping": [ { "id": "1000094", "store_item_id": "3dbe1e78-c746-4940-8db8-ef468c738324", "modifier_group_id": "1000124", "createdAt": "2024-05-02T00:57:36.280Z", "updatedAt": "2024-05-02T00:57:36.280Z", "deletedAt": null, "storeItem": { "id": "3dbe1e78-c746-4940-8db8-ef468c738324", "name": "Build Your Own Sandwich", "description": "With your choice of bread, meat, cheese and toppings.", "price": "6.99" } } ], "options": [ { "id": "1000346", "modifier_group_id": "1000124", "price": "0.00", "store_item_id": "2edc15af-2552-45a2-a149-d670279e27f3", "status": "active", "precedence": 0, "external_id": "22b222b1-a5ed-4907-a4e5-71f52e2ab7ab", "default_qty": 0, "storeItem": { "id": "2edc15af-2552-45a2-a149-d670279e27f3", "name": "Small", "price": "0.0" } } ] } ] ``` Use this endpoint to get a complete overview of a modifier group's configuration, including all linked items and available options. The response includes nested objects for linked store items and options, providing complete details without requiring additional API calls. # Update Modifier Group Source: https://developer.lulacommerce.com/api-reference/catalog/modifiers/update-modifier-group PUT {{micro_service_base_url}}/inventory/stores/{{store_id}}/modifier-groups/ This endpoint updates the properties of existing modifier groups. You can modify settings like name, description, quantity limits, and other configuration options. This endpoint allows you to update the configuration of existing modifier groups. You can change various properties such as the name, description, quantity constraints, and status while preserving existing options and mappings. Updates to modifier groups will immediately affect how customers see and interact with customization options for linked products. ### Path Parameters The unique identifier of the store ### Body Array of modifier group objects to update The unique identifier of the modifier group to update Updated name for the modifier group Updated description for the modifier group The store identifier (must match the path parameter) Updated minimum number of options customer must select Updated maximum number of options customer can select Updated display order precedence Updated option type (e.g., "Customization") Updated maximum number of free options allowed Updated maximum quantity for each option Updated status. Values: "active" or "inactive" ### Request Example ```json [ { "id": "{{modifier_group_id}}", "name": "MG Test 3 - Updated", "description": "Modifier group for drinks", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "min_quantity": 0, "max_quantity": 2, "precedence": 0, "option_type": "Customization", "max_free_options": 0, "max_options_qty": 2, "status": "active" } ] ``` ### Response The number of modifier groups that were successfully updated ### Response Example ```json { "total_updated_records": 1 } ``` You can update multiple modifier groups in a single request by including multiple objects in the array. Ensure that min\_quantity does not exceed max\_quantity, and that the changes align with your current menu structure to avoid customer confusion. Setting status to "inactive" will hide the modifier group from customer view without deleting it, allowing you to reactivate it later if needed. # Get Recommended Products Source: https://developer.lulacommerce.com/api-reference/catalog/recommended-products GET {{micro_service_base_url}}/inventory/store/{{store_id}}/item/{{store_item_id}}/recommended-products This endpoint retrieves a list of recommended products for a specific item in your store. These recommendations can be used to suggest complementary or related products to customers. This endpoint returns product recommendations based on the specified store item. The recommendations are typically generated based on purchasing patterns, product categories, and other relevant factors. Recommended products are automatically generated by the system based on various factors including customer behavior and product relationships. ### Path Parameters The unique identifier of the store The unique identifier of the item for which to get recommendations ### Response Array of recommended product objects Unique product identifier Internal item identifier Store identifier Array of product image URLs Product name Product description Product size Product price Unit count information Whether the product can be sold independently Whether the product is currently active Available quantity Whether the product setup is completed ### Response Example ```json [ { "id": "4e634630-cf39-4a68-b74a-f4c631eaeb11", "item_id": "bf9480e2-7ae1-4085-b72b-0141695a4fcb", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "images": [ "https://lula-inventory-service-staging.s3.amazonaws.com/images/449235c1-3d04-4519-998b-40d2a621e5e0/Snacks/4e634630-cf39-4a68-b74a-f4c631eaeb11_1730116849516.webp" ], "name": "Keebler Big Snack Pack Club Cheddar Sandwich Crackers", "description": "1.8 oz", "size": "1.8 oz", "price": "0.99", "unit_count": "", "sell_independently": true, "active": true, "quantity": 1, "completed": true }, { "id": "7bff1fcd-ee1f-4e38-a80c-b90d68d56502", "item_id": "1a1cf0c9-4036-45e2-bfb3-ccd032d634d6", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "images": [ "https://lula-inventory-service-staging.s3.amazonaws.com/images/449235c1-3d04-4519-998b-40d2a621e5e0/Snacks/7bff1fcd-ee1f-4e38-a80c-b90d68d56502_1730116813067.webp" ], "name": "Slim Jim Monster Size Smoked Snack Stick Tabasco", "description": "1.94 oz", "size": "1.94 oz", "price": "3.49", "unit_count": "", "sell_independently": true, "active": true, "quantity": 1, "completed": true } ] ``` Use recommended products to create cross-selling opportunities and improve customer experience by suggesting relevant items. The recommendation algorithm considers factors like product categories, customer purchase history, and seasonal trends to provide relevant suggestions. # Catalog Updates Source: https://developer.lulacommerce.com/api-reference/catalog/updates Manage and update your store's product catalog with bulk operations, inventory management, and product recommendations. The Catalog service provides comprehensive tools for managing your store's product inventory, including bulk updates, individual product management, and advanced features like modifiers and recommendations. ## Product Management ### Bulk Operations * **Upsert Products using CSV**: Upload product data in bulk using CSV files * **Upsert Products using JSON**: Create or update products using JSON arrays * **Upsert Inventory**: Update inventory levels, prices, and status for existing products ### Inventory Management * **Get Store Inventory**: Retrieve complete inventory listings with filtering and pagination * **Get Job Status**: Monitor the progress of background processing tasks ### Product Enhancement * **Get Recommended Products**: Retrieve AI-generated product recommendations for cross-selling ## Modifier Groups Modifier groups allow you to create customizable options for your products, such as sizes, add-ons, and variations. ### Management Operations * **Create Modifier Group**: Set up new customization categories * **Update Modifier Group**: Modify existing group settings * **Delete Modifier Group**: Remove modifier groups and all associated data * **Get List Of Modifier Groups**: Browse all modifier groups with search and filtering * **Get Modifier Group Details**: View complete configuration and linked items ### Option Management * **Create Modifier Group Options**: Add specific choices within modifier groups * **Delete Modifier Group Options**: Remove unwanted customization options ### Item Linking * **Create Modifier Group Linked Items**: Associate products with modifier groups * **Delete Linked Items**: Remove product associations from modifier groups ## Key Features Efficiently update large inventories using CSV uploads or JSON batch operations Monitor stock levels, prices, and product status with instant updates Create flexible modifier groups for product variations and add-ons Leverage AI-powered product recommendations to boost sales ## Getting Started 1. **Set Up Products**: Use bulk upload endpoints to populate your catalog 2. **Configure Modifiers**: Create modifier groups for customizable products 3. **Link Products**: Associate products with relevant modifier groups 4. **Monitor Status**: Use job status endpoints to track processing progress Start with small test batches when using bulk operations to ensure your data format is correct before processing large inventories. # Upsert Inventory Source: https://developer.lulacommerce.com/api-reference/catalog/upsert-inventory POST {{micro_service_base_url}}/inventory-service-v2/companies/1000019/store/449235c1-3d04-4519-998b-40d2a621e5e0/inventory This endpoint allows you to update inventory information for specific products in a store. You can modify quantity, status, price, and location for existing products using their external_id. This endpoint updates inventory details for products that already exist in your store. Use this to adjust stock levels, prices, product status, and storage locations. This endpoint only updates existing products. To add new products, use the Upsert Products endpoints. ### Body An array of inventory update objects The external ID of the product to update. Example: "22000017901" Updated quantity for the product. Example: 50 Product status. Values: "active" or "inactive" Updated price for the product. Example: 99.8 Updated location for the product. Example: "WAREHOUSE-CDT" ### Request Example ```json [ { "external_id": "22000017901", "quantity": 50, "status": "inactive", "price": 99.8, "location": "WAREHOUSE-CDT" }, { "external_id": "28400324434", "quantity": 50, "status": "active", "price": 9, "location": "WAREHOUSE-CDT" }, { "external_id": "22000017895", "quantity": 1, "status": "active", "price": 19.12, "location": "Jayy-B" } ] ``` ### Response This endpoint processes the inventory updates asynchronously. No immediate response body is provided. The system will process your inventory updates in the background. Changes will be reflected in your store's inventory once processing is complete. Setting quantity to 0 will mark the product as out of stock. Use "inactive" status to temporarily disable a product from being sold. # Upsert Products using CSV Source: https://developer.lulacommerce.com/api-reference/catalog/upsert-products-csv POST {{micro_service_base_url}}/inventory-service-v2/companies/1000019/products/bulk/csv This endpoint allows you to upload and upsert products in bulk using a CSV file. The CSV file should contain product information that will be processed and updated in your inventory. This endpoint processes CSV files containing product data and updates your store's inventory accordingly. All products in the CSV will be validated against our validation rules before being processed. Only products that pass all validation rules will be inserted or updated in your inventory. ### Body The CSV file containing product data to be uploaded and processed ### Response This endpoint processes the file asynchronously. No immediate response body is provided. The system will process your CSV file in the background. You can check the status of the ingestion job using the Get Job Status endpoint. Make sure your CSV file follows the correct format with all required fields to ensure successful processing. # Upsert Products using JSON Source: https://developer.lulacommerce.com/api-reference/catalog/upsert-products-json POST {{micro_service_base_url}}/inventory-service-v2/companies/1000019/products/bulk This endpoint allows you to create or update products in bulk using a JSON array. Send an array of product objects to add new products or update existing ones in your inventory. This endpoint processes JSON data containing product information and updates your store's inventory. Products with existing external\_id values will be updated, while new external\_id values will create new products. All products will be validated using our validation rules. Only products that pass all rules will be inserted or updated. ### Body An array of product objects to be created or updated Product identification in your internal system. Example: "22000006660" Product name. Example: "Wrigley's Gum Slim Pack" Product price in cents. Example: 179 Product quantity in store's inventory. Example: 1 Product category. Example: "Candy" Product UPC code. Example: "022000006660" Product image URL. Example: "[https://menu-item-images-bucket.s3.amazonaws.com/resized/7ff6bdd404ed31cfb89c07f2bb51043c.png](https://menu-item-images-bucket.s3.amazonaws.com/resized/7ff6bdd404ed31cfb89c07f2bb51043c.png)" Product description. Example: "15 pieces" Product brand name Product location in store Whether the product is active Product size. Example: "15 pieces" Product unit count ### Request Example ```json [ { "external_id": "22000006660", "name": "Wrigley's Gum Slim Pack", "price": 179, "quantity": 1, "category": "Candy", "upc": "022000006660", "image_url": "https://menu-item-images-bucket.s3.amazonaws.com/resized/7ff6bdd404ed31cfb89c07f2bb51043c.png", "description": "15 pieces", "brand": "", "location": "", "active": true, "size": "15 pieces", "unit_count": "" }, { "external_id": "22000017871", "name": "Wrigley's Extra Long Lasting Flavor Sugar Free Spearmint", "price": 399, "quantity": 1, "category": "Candy", "upc": "022000017871", "image_url": "https://menu-item-images-bucket.s3.amazonaws.com/resized/4ff745159f0d5e535d408b707acb7fa9.png", "description": "35 count", "brand": "", "location": "", "active": true, "size": "35 count", "unit_count": "" } ] ``` ### Response This endpoint processes the data asynchronously. No immediate response body is provided. The system will process your product data in the background. You can monitor the processing status using the Get Job Status endpoint. Products with the same external\_id as existing products will be updated with the new information provided. # Create Company Source: https://developer.lulacommerce.com/api-reference/companies/create-company POST https://api-staging.luladelivery.store/stores/company This endpoint creates a new company in the system. Companies serve as the parent entity for stores and manage business-level information including contact details, addresses, and operational status. This endpoint allows you to create a new company with all necessary business information. The company will be assigned a unique ID and can then be used to create and manage stores under its umbrella. Company name. Example: "Salman's Company" Company contact email address. Example: "[test@company.com](mailto:test@company.com)" Company address information Primary address line. Example: "123 Main Street" City name. Example: "Philadelphia" State or province. Example: "PA" ZIP or postal code. Example: "19104" Company contact phone number. Example: "090078601" Company website URL. Example: "[https://www.lulaconvenience.com/](https://www.lulaconvenience.com/)" Note the correct spelling is "website" not "webiste" Company logo URL or base64 encoded image Company banner image URL or base64 encoded image Company profile image URL or base64 encoded image Custom header text for receipts Employer Identification Number. Example: "0000" Company operational status. Example: "On Boarding" * On Boarding * Live * Off Boarding * Churned * Suspended Type of company classification. Example: "Mid-Market" * Enterprise * Mid-Market * Small Business * Startup Company active status. Use 1 for active, 0 for inactive Setting to 0 will deactivate the company and all associated stores Associated HubSpot contact ID for CRM integration. Example: 12121212121212 ### Request Example ```json { "name": "Salman's Company", "email": "test@company.com", "address": { "line_1": "123 Main Street", "city": "Philadelphia", "state": "PA", "zip": "19104" }, "phone_number": "090078601", "website": "https://www.lulaconvenience.com/", "logo": "", "banner": "", "profile_image": "", "receipt_header": "", "ein": "0000", "status": "On Boarding", "company_type": "Mid-Market", "active": 1, "hubspot_id": 12121212121212 } ``` ### Response Unique company identifier generated by the system Unique identifier for the company's address record Company name as provided in the request Company contact email address Company contact phone number Company logo URL or encoded image Company banner image URL or encoded image Company profile image URL or encoded image Custom receipt header text Employer Identification Number Current company operational status Company classification type Company active status (1 = active, 0 = inactive) Associated HubSpot contact ID Timestamp of last update (ISO 8601 format) Timestamp of creation (ISO 8601 format) Company website URL ID of user who created the company record ID of user who last updated the company record Timestamp of deletion (null if not deleted) ### Response Example ```json { "id": "1000003", "address_id": "480c9c0c-50b8-4911-89db-e63d68c6f58a", "name": "Salman's Company", "email": "test@company.com", "phone_number": "090078601", "logo": "", "banner": "", "profile_image": "", "receipt_header": "", "ein": "0000", "status": "On Boarding", "company_type": "Mid-Market", "active": 1, "hubspot_id": "12121212121212", "updated_at": "2023-06-19T15:22:31.591Z", "created_at": "2023-06-19T15:22:31.591Z", "website": null, "created_by": null, "updated_by": null, "deleted_at": null } ``` # Delete Company Source: https://developer.lulacommerce.com/api-reference/companies/delete-company DELETE https://api-staging.luladelivery.store/stores/company/{company_id} This endpoint permanently deletes a company from the system. This is a destructive operation that will remove the company and potentially affect all associated stores, orders, and data. Use with extreme caution. This endpoint permanently removes a company from the system. This is an irreversible operation that will delete the company record and may cascade to associated entities like stores, orders, and customer data. **Destructive Operation:** This action cannot be undone. All company data, associated stores, and related information will be permanently deleted from the system. ### Path Parameters The unique identifier of the company to delete ### Prerequisites Before deleting a company, ensure: Export any important company data, reports, or configurations that you may need later Handle all associated stores - either delete them separately or transfer them to another company Ensure all pending orders are completed or properly handled Complete any outstanding payments, refunds, or billing processes Notify customers about service discontinuation if applicable Disconnect any third-party integrations and clean up API connections ### Deletion Impact Complete company profile including business information and settings All associated address records All stores under this company may be affected (depending on system configuration) Admin and user accounts associated with this company will lose access Historical order data may be affected (check system retention policies) HubSpot connections and other CRM integrations will be severed ### Response Indicates whether the deletion operation was successful ### Response Example ```json { "success": true } ``` ### Error Scenarios The specified company\_id does not exist in the system **Status Code:** 404 Company has active stores that must be handled first **Status Code:** 409 **Solution:** Delete or transfer all stores before deleting the company Company has pending or processing orders **Status Code:** 409 **Solution:** Wait for orders to complete or cancel them manually User doesn't have permission to delete companies **Status Code:** 403 **Solution:** Ensure you have admin-level permissions ### Alternative Approaches Set the company's `active` status to 0 instead of deleting **Benefits:** Preserves data while preventing new operations Change company status to "Off Boarding" or "Churned" **Benefits:** Maintains audit trail and historical data Export company data before deletion for archival purposes **Benefits:** Retains important business information for compliance **Best Practice:** Consider using the Update Company endpoint to set `active: 0` or change status to "Churned" instead of permanent deletion. This preserves valuable business data while effectively removing the company from active operations. **Compliance:** Ensure deletion complies with data retention policies, GDPR requirements, and any regulatory obligations in your jurisdiction. # Get Company Details Source: https://developer.lulacommerce.com/api-reference/companies/get-company-details GET https://api-staging.luladelivery.store/stores/company This endpoint retrieves company information from the system. You can fetch either all companies or specific company details by providing a company ID. The response includes company details, address information, and associated store counts. This endpoint provides comprehensive company information including business details, address, operational status, and the number of associated stores. It supports both retrieving all companies and fetching specific company details. ## Get All Companies Retrieves a list of all companies in the system with summary information including total counts. ### Query Parameters Specific company ID to retrieve details for a single company. If not provided, returns all companies. ### Response - All Companies Total number of stores across all companies Total number of companies in the system Array of company objects Unique company identifier Company name Current operational status (On Boarding, Live, Off Boarding, etc.) Primary contact person for the company Company address information Unique address identifier Primary address line Secondary address line (optional) City name ZIP or postal code State or province Country (optional) Store count information Number of stores associated with this company ## Get Specific Company When a `company_id` is provided, returns detailed information for that specific company. ### Response - Single Company Returns an array with a single company object containing the same structure as described above. ### Response Examples #### All Companies Response ```json { "totalStoresCount": 12, "totalCompaniesCount": 16, "companies": [ { "id": "1000008", "name": "Lula Demo Company\n", "status": null, "point_of_contact": null, "addresses": { "id": "8b9ab17c-5dbb-4080-8719-a3a2e9226584", "line_1": "3230 Market Street", "line_2": null, "city": "Philadelphia", "zip": "19104", "state": "PA", "country": null }, "stores": { "stores_count": "1" } }, { "id": "1000016", "name": "Salman's Company", "status": "On Boarding", "point_of_contact": null, "addresses": { "id": "44cf546d-3deb-459c-883d-ceb47e94451a", "line_1": "39 Block Q, Phase 2 Johar Town", "line_2": null, "city": "Lahore", "zip": "54782", "state": "Punjab", "country": null }, "stores": { "stores_count": "1" } } ] } ``` #### Single Company Response ```json [ { "id": "1000022", "name": "Salman's Company", "status": "On Boarding", "point_of_contact": "lula delivery", "addresses": { "id": "1359b612-3f09-430b-9bf1-5fc1460c8535", "line_1": "39 Block Q, Phase 2 Johar Town", "line_2": null, "city": "Lahore", "zip": "54782", "state": "Punjab", "country": null }, "stores": { "stores_count": "7" } } ] ``` **Usage Tips:** * Use without parameters to get an overview of all companies and their store counts * Include `company_id` parameter to get detailed information for a specific company * The `stores_count` field helps you understand the scale of each company's operations * `point_of_contact` field may be null if no contact person is assigned Some companies may have null values for status or point\_of\_contact fields. Always check for null values when processing the response. # Offboard Company Source: https://developer.lulacommerce.com/api-reference/companies/offboard-company PUT https://api-staging.luladelivery.store/stores/company/{company_id}/offboard This endpoint initiates the offboarding process for a company. Offboarding is a controlled process that safely transitions a company out of active service while preserving important data and ensuring proper closure of operations. This endpoint starts the offboarding process for a company, which is a safer alternative to permanent deletion. Offboarding allows for a controlled wind-down of operations while maintaining data integrity and compliance requirements. ### What is Offboarding? Offboarding is a structured process that: * Gracefully transitions the company out of active service * Preserves historical data for compliance and reporting * Ensures proper closure of ongoing operations * Maintains audit trails for business purposes * Allows for potential reactivation if needed **Offboarding vs Deletion:** Unlike deletion, offboarding preserves all company data while marking the company as no longer active. This approach is recommended for compliance and business continuity. ### Path Parameters The unique identifier of the company to offboard ### Offboarding Process Company status is automatically changed to "Off Boarding" All associated stores are marked for offboarding Stores may be deactivated or marked as "Off Boarding" depending on configuration System prevents new orders while allowing existing orders to complete Inventory updates are disabled to prevent new stock changes User accounts are disabled or restricted to view-only access Third-party integrations are paused or disconnected safely All historical data, reports, and configurations are preserved ### Post-Offboarding Effects Status automatically set to "Off Boarding" All stores become unavailable for new orders Most write operations are disabled, read operations may be restricted Company and stores are hidden from customer-facing applications Admin users get read-only access for reporting and data export Billing cycles may be adjusted or terminated based on configuration ### Response Indicates whether the offboarding process was successfully initiated ### Response Example ```json { "success": true } ``` ### Reactivation Process Reactivation typically requires manual intervention from support team Business requirements and conditions may need to be reviewed System integrity and data consistency checks are performed Services are restored incrementally to ensure stability ### Best Practices Notify all stakeholders before initiating offboarding Send advance notice to customers, partners, and internal teams Export critical business data before offboarding Generate reports for sales, inventory, and customer data Allow time for pending orders to complete naturally Offboarding with pending orders may affect customer experience Complete all financial transactions and settlements Ensure all payments, refunds, and fees are properly processed Properly disconnect third-party services and integrations Update webhook URLs and disable API keys to prevent errors ### Error Scenarios The specified company\_id does not exist **Status Code:** 404 Company is already in "Off Boarding" or "Churned" status **Status Code:** 409 Company has active orders that may be affected **Status Code:** 200 (Success with warning) **Note:** Process continues but active orders are flagged for attention User lacks permission to offboard companies **Status Code:** 403 **Timing Considerations:** Plan offboarding during low-activity periods to minimize impact on customers and operations. Consider timezone differences if serving multiple regions. **Compliance:** Offboarding maintains compliance with data retention requirements while safely removing companies from active service. This approach is preferred over deletion for regulated industries. # Update Company Source: https://developer.lulacommerce.com/api-reference/companies/update-company PUT https://api-staging.luladelivery.store/stores/company/{company_id} This endpoint updates an existing company's information in the system. You can modify any company details including business information, contact details, address, and operational status. All fields are optional - only provide the fields you want to update. This endpoint allows you to update any aspect of a company's information. You only need to include the fields you want to modify in the request body. The system will update only the provided fields while keeping other information unchanged. Updated company name. Example: "Salman's Company New" Updated company contact email address. Example: "[salmansaeedpaul@gmail.com](mailto:salmansaeedpaul@gmail.com)" Updated company address information Updated primary address line. Example: "39 Block Q, Phase 2 Johar Town" Updated city name. Example: "Lahore" Updated state or province. Example: "Punjab" Updated ZIP or postal code. Example: "54782" Updated company contact phone number. Example: "090078601" Updated company website URL. Example: "[https://www.lulaconvenience.com/](https://www.lulaconvenience.com/)" Note the correct spelling is "website" not "webiste" Updated company logo URL or base64 encoded image Updated company banner image URL or base64 encoded image Updated company profile image URL or base64 encoded image Updated custom header text for receipts Updated Employer Identification Number. Example: "0000" Updated company operational status. Example: "Churned" * On Boarding * Live * Off Boarding * Churned * Suspended Changing status to "Churned" or "Suspended" may affect store operations Updated type of company classification. Example: "Mid-Market" * Enterprise * Mid-Market * Small Business * Startup Updated company active status. Use 1 for active, 0 for inactive Setting to 0 will deactivate the company and all associated stores Updated HubSpot contact ID for CRM integration. Example: 12121212121212 ### Path Parameters The unique identifier of the company to update ### Request Example ```json { "name": "Salman's Company New", "email": "salmansaeedpaul@gmail.com", "address": { "line_1": "39 Block Q, Phase 2 Johar Town", "city": "Lahore", "state": "Punjab", "zip": "54782" }, "phone_number": "090078601", "website": "https://www.lulaconvenience.com/", "logo": "", "banner": "", "profile_image": "", "receipt_header": "", "ein": "0000", "status": "Churned", "company_type": "Mid-Market", "active": 1, "hubspot_id": 12121212121212 } ``` ### Response Indicates whether the update operation was successful ### Response Example ```json { "success": true } ``` **Partial Updates:** You can update individual fields without affecting others. For example, to only update the company name, send just `{"name": "New Company Name"}`. **Address Updates:** When updating address information, you can update individual address fields without providing the complete address object. **Status Changes:** Be careful when changing company status, as it may affect: * Store operations and availability * Order processing capabilities * Integration with third-party services * Billing and subscription status **Validation:** The system will validate all provided fields according to the same rules used during company creation. Invalid data will result in an error response. # CSV Item Ingestion Source: https://developer.lulacommerce.com/api-reference/csvItemsIngestion CSV support for item ingestion ## CSV File Reference Here are the accepted and required CSV fields: | Column Header | Description | Required | | ------------- | --------------------------------------------------------------------------- | -------- | | external\_id | ID from your source system, used to update existing items, can be a UPC/SKU | \* | | name | Name of the product | \* | | size | Size of the product (e.g 12 oz), if size is not applicable use "NA" | \* | | price | Price of the item in cents (e.g. 799), must be less than 349999 | \* | | category | Used for grouping item on marketplace (see list of categories below) | \* | | upc | The 12-digit UPC/GTIN | | | image | An image URL for the item | | | quantity | >0 to set in-stock | \* | | unit\_count | The number of items (e.g 6 pack) | | | description | A brief description of the product, less than 350 characters | | | brand | the product brand | | | location | where to find item in store | | | active | 1 = active, 0 = inactive, use to hide/show the product | \* | ### [Get the Lula Sample CSV](https://lula-brand.s3.amazonaws.com/Lula_Sample_CSV.csv) ## Categories List List of all categories and the order with which they are presented on the marketplace. If a category is not used it will not appear. Note, Tobacco products are restricted from the delivery marketplaces. | Categories | Order | | ---------------------------- | ----- | | Featured Favorites | 1 | | Thin crust pizza | 2 | | Original crust pizza | 3 | | Pizza | 4 | | Wings | 5 | | Wing Bites | 6 | | Chicken | 7 | | Sandwiches | 8 | | Sides | 9 | | Breakfast | 10 | | Quick Meals | 11 | | Deli Items | 12 | | Fresh Food | 13 | | Prepared Foods | 14 | | Hot Foods | 15 | | Beer | 16 | | Single Beer | 17 | | Wine | 18 | | Alcohol | 19 | | Seltzer | 20 | | Energy Drinks & Electrolytes | 21 | | Soda | 22 | | Water | 23 | | Coffee | 24 | | Juice and Tea | 25 | | Fountain | 26 | | Beverages | 27 | | Snacks | 28 | | Candy | 29 | | Bakery | 30 | | Ice Cream | 31 | | Grocery | 32 | | Frozen | 33 | | Milk | 34 | | Medicine | 35 | | Health | 36 | | Personal Care | 37 | | Bath & Beauty | 38 | | Cleaning | 39 | | Household | 40 | | Automotive | 41 | | Baby | 42 | | Pet Care | 43 | | Others | 44 | | Tobacco | 45 | # Get Job Source: https://developer.lulacommerce.com/api-reference/endpoint/get-job GET https://api-staging.luladelivery.store/inventory/ingestion/{id} Get information about an ingestion job. The Job ID ### Response # Post items for ingestion Source: https://developer.lulacommerce.com/api-reference/endpoint/post-items-for-ingestion POST https://api-staging.luladelivery.store/inventory/ingestion/ This endpoint takes a JSON body and updates your inventory for the store. We post the JSON body containing the inventory items and the store gets updated with the items. All items will be validated using our validation rules. Only items that pass all rules will be inserted. Product name. Example: "Coca Cola Classic" Product category. Example: "Soda" If an invalid category is sent, it will be automatically set to "Others" * Alcohol * Baby * Bakery * Bath & Beauty * Beer * Beverages * Breakfast * Candy * Chicken * Cleaning * Coffee * Deli Items * Energy Drinks & Electrolytes * Featured Favorites * Fresh Food * Frozen * Grocery * Health * Household * Ice Cream * Juice and Tea * Medicine * Milk * Original crust pizza * Others * Personal Care * Pet Care * Pizza * Prepared Foods * Quick Meals * Sandwiches * Seltzer * Sides * Single Beer * Snacks * Soda * Thin crust pizza * Water * Wine * Wing Bites * Wings Product size. Example: "12 oz" If product doesn't contain a size, the text "NA" can be used instead Product quantity in Store's inventory. Example: 99 Minimum allowed quantity: 0 Send `0` to mark this product as Out of Stock Product price in cents. Example: 265 Minimum allowed price: 0. Maximum allowed price: 34999 Product identification in your internal system. Example: "1234\_5678" If a product with same External ID already exists in your Store, it will be updated Product UPC. Example: "49000012521" Product image URL. Example: "[https://go-upc.s3.amazonaws.com/images/68916944.jpeg](https://go-upc.s3.amazonaws.com/images/68916944.jpeg)" We prefer images with size 1600x900 Product location. Example: "Counter" Product description. Example: "Soda. Pop. Soft drink. Sparkling beverage. Whatever you call it, nothing compares to the refreshing, crisp taste of Coca-Cola Original Taste" Maximum allowed description length: 350 characters Product brand. Example: "Coca Cola" Product unit count. Example: "12 Pack" Product status If set to `false`, the product will be considered removed from your Store ### Body ### Response # Upload CSV file for item ingestion Source: https://developer.lulacommerce.com/api-reference/endpoint/upload-csv POST https://api-staging.luladelivery.store/inventory/ingestion/csv This endpoint takes a CSV file and updates your inventory for the store. We upload the CSV file contanining the inventory items and the store gets updated with the items. All items will be validated using our validation rules. Only items that pass all rules will be inserted. Product name. Example: "Coca Cola Classic" Product category. Example: "Soda" If an invalid category is sent, it will be automatically set to "Others" * Alcohol * Baby * Bakery * Bath & Beauty * Beer * Beverages * Breakfast * Candy * Chicken * Cleaning * Coffee * Deli Items * Energy Drinks & Electrolytes * Featured Favorites * Fresh Food * Frozen * Grocery * Health * Household * Ice Cream * Juice and Tea * Medicine * Milk * Original crust pizza * Others * Personal Care * Pet Care * Pizza * Prepared Foods * Quick Meals * Sandwiches * Seltzer * Sides * Single Beer * Snacks * Soda * Thin crust pizza * Water * Wine * Wing Bites * Wings * Hot Foods * Automotive * Fountain * Tobacco Product size. Example: "12 oz" If product doesn't contain a size, the text "NA" can be used instead Product quantity in Store's inventory. Example: 99 Minimum allowed quantity: 0 Send `0` to mark this product as Out of Stock Product price in cents. Example: 265 Minimum allowed price: 0. Maximum allowed price: 34999 Product identification in your internal system. Example: "1234\_5678" If a product with same External ID already exists in your Store, it will be updated Product UPC. Example: "49000012521" Product image URL. Example: "[https://go-upc.s3.amazonaws.com/images/68916944.jpeg](https://go-upc.s3.amazonaws.com/images/68916944.jpeg)" We prefer images with size 1600x900 Product location. Example: "Counter" Product description. Example: "Soda. Pop. Soft drink. Sparkling beverage. Whatever you call it, nothing compares to the refreshing, crisp taste of Coca-Cola Original Taste" Maximum allowed description length: 350 characters Product brand. Example: "Coca Cola" Product unit count. Example: "12 Pack" Product status If set to `0`, the product will be considered removed from your Store ### Body ### Response # Upload JSON file for item ingestion Source: https://developer.lulacommerce.com/api-reference/endpoint/upload-json POST https://api-staging.luladelivery.store/inventory/ingestion/ This endpoint takes a JSON file and updates your inventory for the store. We upload the JSON file containing the inventory items and the store gets updated with the items. All items will be validated using our validation rules. Only items that pass all rules will be inserted. Product name. Example: "Coca Cola Classic" Product category. Example: "Soda" If an invalid category is sent, it will be automatically set to "Others" * Alcohol * Baby * Bakery * Bath & Beauty * Beer * Beverages * Breakfast * Candy * Chicken * Cleaning * Coffee * Deli Items * Energy Drinks & Electrolytes * Featured Favorites * Fresh Food * Frozen * Grocery * Health * Household * Ice Cream * Juice and Tea * Medicine * Milk * Original crust pizza * Others * Personal Care * Pet Care * Pizza * Prepared Foods * Quick Meals * Sandwiches * Seltzer * Sides * Single Beer * Snacks * Soda * Thin crust pizza * Water * Wine * Wing Bites * Wings * Hot Foods * Automotive * Fountain * Tobacco Product size. Example: "12 oz" If product doesn't contain a size, the text "NA" can be used instead Product quantity in Store's inventory. Example: 99 Minimum allowed quantity: 0 Send `0` to mark this product as Out of Stock Product price in cents. Example: 265 Minimum allowed price: 0. Maximum allowed price: 34999 Product identification in your internal system. Example: "1234\_5678" If a product with same External ID already exists in your Store, it will be updated Product UPC. Example: "49000012521" Product image URL. Example: "[https://go-upc.s3.amazonaws.com/images/68916944.jpeg](https://go-upc.s3.amazonaws.com/images/68916944.jpeg)" We prefer images with size 1600x900 Product location. Example: "Counter" Product description. Example: "Soda. Pop. Soft drink. Sparkling beverage. Whatever you call it, nothing compares to the refreshing, crisp taste of Coca-Cola Original Taste" Maximum allowed description length: 350 characters Product brand. Example: "Coca Cola" Product unit count. Example: "12 Pack" Product status If set to `false`, the product will be considered removed from your Store ### Body ### Response # JSON Item Ingestion Source: https://developer.lulacommerce.com/api-reference/jsonItemsIngestion The json items are ingested into the system by uploading through an API. ## JSON File Reference Here's a sample of valid JSON for sending to the API for ingest. ```JSON [ { "name": "12 Dove Relaxing Lavender Oil Chamomile Body Wash", "category": "Personal Care", "size": "24 oz", "quantity": 10, "price": 899, "external_id": "10001", "description": "Get clean and fresh", "brand": "Dove", "unit_count": "1", "location": "3A", "active": true }, { "name": "5-Hour Energy Shot Pomegranate", "category": "Personal Care", "size": "1.93 oz", "quantity": 20, "price": 374, "external_id": "10002", "description": "Energy in pomegranate flavor", "brand": "5-Hour Energy", "unit_count": "1", "location": "Counter", "active": true }, { "name": "7Up", "category": "Soda", "size": "1 l bottle", "quantity": 30, "price": 289, "external_id": "10003", "description": "Fresh and delicious", "brand": "7up", "unit_count": "1", "location": "Freezer-4", "active": true }, { "name": "7Up Lemon Lime Soda", "category": "Soda", "size": "20 oz bottle", "quantity": 40, "price": 249, "external_id": "10004", "description": "Thirst quenching", "brand": "7up", "unit_count": "1", "location": "Freezer-2", "active": true }, { "name": "7 Days Soft Croissant Chocolate Filling", "category": "Snacks", "size": "6 ct", "quantity": 50, "price": 249, "external_id": "10005", "description": "Flaky and buttery goodness", "brand": "7 Days", "unit_count": "6", "location": "2B", "active": true } ] ``` # Create Store Menu Source: https://developer.lulacommerce.com/api-reference/menus/create-store-menu POST /stores/{{store_id}}/menu/ Create a new menu for a specific store with customizable operating hours and configuration settings. This endpoint creates a new menu for a store, allowing businesses to define multiple menus with different operating hours, status settings, and configurations. Store menus define when and how products are available to customers. Each menu can have unique operating hours for different days of the week and can be set as default or specialized menus. ### Path Parameters The unique identifier of the store for which to create the menu ### Request Body Display name for the menu (e.g., "Weekend Menu", "Holiday Hours") Whether this menu should be the default menu for the store Menu status: "active" or "inactive" Array of operating hours for each day of the week Day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday) Opening time in HH:MM format (24-hour) Closing time in HH:MM format (24-hour) Whether the store is closed on this day ### Request Example ```json { "menu_name": "menu-23", "is_default": false, "status": "active", "menu_hours": [ { "day_of_week": 0, "open_time": "09:00", "close_time": "17:00", "is_closed": false }, { "day_of_week": 1, "open_time": "09:00", "close_time": "17:00", "is_closed": false }, { "day_of_week": 2, "open_time": "09:00", "close_time": "17:00", "is_closed": false }, { "day_of_week": 3, "open_time": "09:00", "close_time": "17:00", "is_closed": false }, { "day_of_week": 4, "open_time": "09:00", "close_time": "17:00", "is_closed": false }, { "day_of_week": 5, "open_time": "09:00", "close_time": "17:00", "is_closed": false }, { "day_of_week": 6, "open_time": "09:00", "close_time": "17:00", "is_closed": false } ] } ``` ### Response Unique identifier for the created menu Display name of the menu Store identifier this menu belongs to Whether this is the default menu for the store Current menu status (ACTIVE/INACTIVE) ID of the user who created the menu External system menu identifier (if applicable) Timestamp when the menu was created Timestamp when the menu was last updated Array of operating hours with complete configuration Unique identifier for the menu hour entry Day of the week Opening time Closing time Whether closed on this day Parent menu identifier Creator user ID Creation timestamp Last update timestamp ### Response Example ```json { "id": "d4710f37-0490-4c53-a553-a907f3d202c7", "menu_name": "menu-23", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "is_default": false, "status": "ACTIVE", "created_by_id": "1000418", "updatedAt": "2024-09-13T10:47:26.104Z", "createdAt": "2024-09-13T10:47:26.104Z", "external_menu_id": null, "created_by": null, "updated_by": null, "updated_by_id": null, "last_live_at": null, "archived_at": null, "deletedAt": null, "menu_hours": [ { "id": "48a18cca-f744-427b-b1bd-9e8eff7b98b1", "day_of_week": 0, "open_time": "09:00", "close_time": "17:00", "is_closed": false, "menu_id": "d4710f37-0490-4c53-a553-a907f3d202c7", "created_by_id": "1000418", "updatedAt": "2024-09-13T10:47:26.114Z", "createdAt": "2024-09-13T10:47:26.114Z", "created_by": null, "updated_by": null, "updated_by_id": null, "deletedAt": null }, { "id": "a26d4683-025d-4803-8e00-1efd4bdcc5d2", "day_of_week": 1, "open_time": "09:00", "close_time": "17:00", "is_closed": false, "menu_id": "d4710f37-0490-4c53-a553-a907f3d202c7", "created_by_id": "1000418", "updatedAt": "2024-09-13T10:47:26.114Z", "createdAt": "2024-09-13T10:47:26.114Z", "created_by": null, "updated_by": null, "updated_by_id": null, "deletedAt": null }, { "id": "69655f6e-3485-47a3-bfad-cd105d5b2f03", "day_of_week": 2, "open_time": "09:00", "close_time": "17:00", "is_closed": false, "menu_id": "d4710f37-0490-4c53-a553-a907f3d202c7", "created_by_id": "1000418", "updatedAt": "2024-09-13T10:47:26.114Z", "createdAt": "2024-09-13T10:47:26.114Z", "created_by": null, "updated_by": null, "updated_by_id": null, "deletedAt": null }, { "id": "66d2e767-fef4-4853-a7f8-4cb9ff1cf203", "day_of_week": 3, "open_time": "09:00", "close_time": "17:00", "is_closed": false, "menu_id": "d4710f37-0490-4c53-a553-a907f3d202c7", "created_by_id": "1000418", "updatedAt": "2024-09-13T10:47:26.187Z", "createdAt": "2024-09-13T10:47:26.187Z", "created_by": null, "updated_by": null, "updated_by_id": null, "deletedAt": null }, { "id": "f0f02560-5de3-4bfe-9cc6-3c64d4fc065c", "day_of_week": 4, "open_time": "09:00", "close_time": "17:00", "is_closed": false, "menu_id": "d4710f37-0490-4c53-a553-a907f3d202c7", "created_by_id": "1000418", "updatedAt": "2024-09-13T10:47:26.187Z", "createdAt": "2024-09-13T10:47:26.187Z", "created_by": null, "updated_by": null, "updated_by_id": null, "deletedAt": null }, { "id": "135b483c-88f5-46e4-8454-bec28f73957d", "day_of_week": 5, "open_time": "09:00", "close_time": "17:00", "is_closed": false, "menu_id": "d4710f37-0490-4c53-a553-a907f3d202c7", "created_by_id": "1000418", "updatedAt": "2024-09-13T10:47:26.187Z", "createdAt": "2024-09-13T10:47:26.187Z", "created_by": null, "updated_by": null, "updated_by_id": null, "deletedAt": null }, { "id": "4dae188e-82b6-43ac-84f8-cbf9debcde93", "day_of_week": 6, "open_time": "09:00", "close_time": "17:00", "is_closed": false, "menu_id": "d4710f37-0490-4c53-a553-a907f3d202c7", "created_by_id": "1000418", "updatedAt": "2024-09-13T10:47:26.187Z", "createdAt": "2024-09-13T10:47:26.187Z", "created_by": null, "updated_by": null, "updated_by_id": null, "deletedAt": null } ] } ``` **Operating Hours Planning** * Define clear opening and closing times for each day * Consider customer traffic patterns when setting hours * Use consistent time formats (24-hour) for clarity * Plan for different hours on weekends vs weekdays **Menu Naming Strategy** * Use descriptive names that indicate the menu purpose * Include time periods or special conditions in names * Maintain consistent naming conventions across stores * Consider seasonal or promotional menu names **Default Menu Management** * Only one menu per store should be set as default * Default menus should have the most comprehensive hours * Consider customer expectations when setting default hours * Regular review of default menu effectiveness **Day of Week Values**: Days are numbered 0-6 where 0 = Sunday, 1 = Monday, 2 = Tuesday, 3 = Wednesday, 4 = Thursday, 5 = Friday, 6 = Saturday. **Time Format**: All times should be provided in 24-hour format (HH:MM) for consistency and to avoid AM/PM confusion. ### Use Cases **Standard Business Hours** * Create menus with consistent weekday and weekend hours * Set appropriate opening and closing times for customer expectations * Configure closed days for businesses that don't operate 7 days a week **Seasonal Menus** * Create special menus for holiday seasons * Temporary menus for promotional periods * Limited-time menu configurations **Multi-Shift Operations** * Breakfast, lunch, and dinner menus with different hours * Late-night menus for extended operations * Special event menus with unique timing **Store-Specific Variations** * Location-based menu hours (mall vs street locations) * Regional preferences and local regulations * Franchise-specific menu configurations ### Error Handling **Invalid Time Format** ```json { "error": "Invalid time format", "message": "Time must be in HH:MM format", "field": "menu_hours.open_time" } ``` **Missing Required Fields** ```json { "error": "Validation failed", "message": "menu_name is required", "field": "menu_name" } ``` **Store Not Found** ```json { "error": "Store not found", "message": "The specified store does not exist" } ``` **Invalid Day of Week** ```json { "error": "Invalid day_of_week", "message": "day_of_week must be between 0 and 6" } ``` **Multiple Default Menus**: Setting multiple menus as default for the same store may cause conflicts. Ensure only one menu per store is marked as default. # Delete Store Menu Source: https://developer.lulacommerce.com/api-reference/menus/delete-store-menu DELETE /stores/{{store_id}}/menu/{{menu_id}} Delete a specific menu from a store, removing all associated menu hours and configurations. This endpoint permanently removes a menu from a store, including all associated operating hours and menu item associations. Menu deletion is a permanent operation that removes all menu configuration data. Consider the impact on customer experience and ensure proper backup procedures before deletion. ### Path Parameters The unique identifier of the store that owns the menu The unique identifier of the menu to delete **Data Removal** * Complete menu configuration is permanently deleted * All associated menu hours are removed * Menu item associations are cleared * Menu rules and conditions are deleted **Business Impact** * Customers will no longer see this menu * Associated operating hours become unavailable * Menu-specific item visibility rules are removed * Default menu status transfers if applicable **System Dependencies** * Orders referencing this menu may be affected * Analytics and reporting data remains for historical purposes * External system integrations may need updates * Cached menu data will be cleared **Default Menu Protection**: Most systems prevent deletion of default menus to ensure store operational continuity. Set another menu as default before attempting to delete the current default menu. **Permanent Operation**: Menu deletion cannot be undone. Ensure you have proper backups and confirm the deletion is intended before proceeding. ### Use Cases **Menu Cleanup** * Remove outdated seasonal menus * Delete test menus created during setup * Clean up duplicate or incorrect menu configurations * Remove menus no longer needed for operations **Menu Consolidation** * Merge multiple similar menus into one * Simplify menu management by reducing options * Standardize menu configurations across locations * Remove redundant menu variations **Operational Changes** * Delete menus when changing business models * Remove menus for discontinued services * Clean up after store format changes * Update menus for new operational requirements **Error Correction** * Remove incorrectly configured menus * Delete menus created with wrong parameters * Clean up after failed menu setup attempts * Remove test data from production systems ### Safety Considerations **Menu Status Verification** * Confirm the menu is not currently active * Verify no current customer orders reference this menu * Check if menu is set as store default * Ensure no critical business processes depend on this menu **Data Backup Procedures** * Export menu configuration before deletion * Save menu hours and item associations * Document menu rules and conditions * Archive historical performance data **Alternative Actions** * Consider deactivating instead of deleting * Archive menu for potential future use * Transfer menu items to another menu * Update menu status to inactive first **System Impact Assessment** * Check external system integrations * Verify analytics and reporting impacts * Confirm customer-facing system updates * Test menu synchronization after deletion ### Error Handling **Menu Not Found** ```json { "error": "Menu not found", "message": "The specified menu does not exist" } ``` **Default Menu Protection** ```json { "error": "Cannot delete default menu", "message": "Set another menu as default before deleting this menu" } ``` **Active Menu Deletion** ```json { "error": "Cannot delete active menu", "message": "Deactivate the menu before deletion" } ``` **Permission Denied** ```json { "error": "Insufficient permissions", "message": "You do not have permission to delete menus" } ``` **Store Not Found** ```json { "error": "Store not found", "message": "The specified store does not exist" } ``` ### Best Practices **Pre-Deletion Planning** * Review menu usage analytics before deletion * Identify any dependencies or integrations * Plan for customer communication if necessary * Schedule deletion during low-traffic periods **Verification Steps** * Double-check menu ID and store ID * Confirm menu is not referenced in active orders * Verify menu is not the store's default menu * Ensure proper authorization for the deletion **Post-Deletion Procedures** * Verify menu is no longer accessible * Update any documentation referencing the deleted menu * Monitor systems for any related errors * Confirm customer-facing changes are reflected properly **Documentation and Audit** * Log the reason for menu deletion * Document who performed the deletion and when * Record any business impact or customer notifications * Maintain audit trail for compliance purposes ### Alternative Approaches **Menu Deactivation** * Set menu status to "inactive" instead of deleting * Preserves menu configuration for potential reactivation * Maintains historical data and associations * Allows for easy restoration if needed **Menu Archival** * Move menu to an archived state * Preserve configuration while removing from active use * Maintain data for reporting and analytics * Enable future reference or restoration **Menu Modification** * Update menu instead of deleting * Change operating hours to remove availability * Modify menu items to empty set * Maintain menu structure while removing functionality **Graceful Transition** * Create replacement menu before deletion * Transfer menu items to new menu * Update default menu designation * Ensure continuous service availability ### Integration Considerations **Customer-Facing Systems** * Mobile apps will no longer display the deleted menu * Website menu listings will be updated * Point-of-sale systems will remove menu references * Order management systems will handle legacy references **Analytics and Reporting** * Historical data remains available for analysis * Current reporting will exclude the deleted menu * Performance metrics will reflect the menu removal * Trend analysis will show the deletion point **External Partners** * Third-party delivery platforms may need updates * POS integrations require menu synchronization * Inventory management systems may need adjustment * Marketing platforms should update menu references **Administrative Systems** * Admin dashboards will remove menu from active lists * User permissions related to the menu are cleaned up * Audit logs maintain deletion records * Backup systems should retain historical menu data ### Recovery Options **Immediate Recovery** * Contact system administrator immediately after accidental deletion * Provide menu ID and store ID for recovery attempts * Check if soft deletion is implemented for recovery * Restore from recent database backups if available **Data Reconstruction** * Use exported menu configuration to recreate menu * Reference historical data for menu hours reconstruction * Restore menu item associations from backup data * Recreate menu rules based on documentation **Prevention Measures** * Implement confirmation dialogs for menu deletion * Require manager approval for menu deletions * Set up automated backups of menu configurations * Use staging environments for testing menu changes **Business Continuity** * Create temporary menu to maintain operations * Use backup menu configurations during recovery * Communicate with customers about temporary changes * Document lessons learned for future prevention # Get All Active Menu of Store Source: https://developer.lulacommerce.com/api-reference/menus/get-all-active-menu-of-store GET /stores/{{store_id}}/menu/ Retrieve all active menus for a specific store, providing essential menu information for operational and customer-facing applications. This endpoint returns all active menus associated with a specific store, providing essential information for menu management and customer-facing applications. This endpoint focuses on active menus only, making it ideal for customer-facing applications and operational systems that need to display currently available menu options. ### Path Parameters The unique identifier of the store to retrieve active menus for **Menu Status Requirements** * Only menus with "active" status are returned * Inactive or archived menus are excluded from results * Deleted menus are not included in the response * Draft menus are filtered out of the results **Operational Considerations** * Active menus represent current customer offerings * These menus are available for order processing * Operating hours determine actual availability within active menus * Menu rules and item associations apply to active menus **Customer Experience** * Active menus are what customers see in applications * These menus drive ordering and checkout processes * Menu availability affects customer purchasing decisions * Real-time status ensures accurate customer information **Real-Time Data**: This endpoint provides real-time menu status information, ensuring customers and operational systems have access to current menu availability. **Performance Optimization**: Since this endpoint filters for active menus only, it typically returns faster responses and is optimized for frequent access by customer-facing applications. ### Use Cases **Customer-Facing Applications** * Mobile app menu displays * Website menu listings * Point-of-sale system menu options * Kiosk menu presentations **Operational Systems** * Order management system integration * Inventory tracking and management * Staff training and reference materials * Kitchen display system coordination **Partner Integrations** * Delivery platform menu synchronization * Third-party ordering system integration * Marketing platform data feeds * Analytics and reporting systems **Administrative Functions** * Current menu status monitoring * Active menu performance tracking * Operational dashboard displays * Real-time business intelligence ### Response Format **Menu Object Array** * Array of active menu objects * Each menu contains complete configuration data * Operating hours included for each menu * Item counts and statistics provided **Essential Menu Information** * Menu identification and naming * Current status and configuration * Operating schedule details * Item and category statistics **Metadata and Timestamps** * Creation and modification dates * User information for audit trails * External system integration IDs * Deletion and archival status ### Integration Patterns **Real-Time Menu Display** * Fetch active menus for immediate display * Update menu information based on current time * Filter by operating hours for current availability * Refresh data periodically for accuracy **Caching Strategies** * Cache active menu data for performance * Implement cache invalidation on menu updates * Balance data freshness with response speed * Consider user location and time zone factors **Error Handling** * Handle cases where no active menus exist * Provide fallback options for system failures * Implement graceful degradation for partial failures * Log errors for operational monitoring **Performance Optimization** * Minimize request frequency for high-traffic applications * Use appropriate data compression * Implement efficient data parsing * Monitor response times and optimize accordingly ### Business Logic **Menu Activation Criteria** * Menu must have "active" status * Store must be operational and accessible * Menu configuration must be complete and valid * Operating hours must be properly configured **Time-Based Availability** * Active menus may still be time-restricted * Operating hours determine actual customer access * Special schedules may override default availability * Holiday and event schedules affect menu access **Priority and Default Handling** * Default menus take precedence in customer displays * Menu priority affects ordering in lists * Specialized menus may override default options * Business rules determine menu presentation order **Dynamic Updates** * Menu status changes are reflected immediately * Real-time updates ensure accurate customer information * System synchronization maintains consistency * Operational changes are propagated quickly ### Error Scenarios **No Active Menus** ```json { "message": "No active menus found for this store", "data": [], "store_id": "store-123" } ``` **Store Not Found** ```json { "error": "Store not found", "message": "The specified store does not exist", "store_id": "invalid-store-id" } ``` **Access Denied** ```json { "error": "Access denied", "message": "Insufficient permissions to access store menus" } ``` **Service Unavailable** ```json { "error": "Service temporarily unavailable", "message": "Menu service is currently experiencing issues" } ``` ### Performance Considerations **Response Time Optimization** * Active menu filtering reduces response size * Database indexing on menu status improves query speed * Caching strategies reduce server load * Efficient data serialization minimizes transfer time **Scalability Factors** * High-frequency access patterns expected * Multiple concurrent requests from customer applications * Peak usage during meal times and promotional periods * Geographic distribution of requests **Resource Management** * Database connection pooling for concurrent access * Memory management for large menu datasets * Network bandwidth optimization for mobile clients * CPU resource allocation for real-time processing **Monitoring and Alerts** * Response time monitoring for performance tracking * Error rate tracking for service reliability * Usage pattern analysis for capacity planning * Alert systems for performance degradation ### Data Consistency **Real-Time Updates** * Menu status changes are immediately reflected * Operating hour modifications take effect instantly * Item availability updates are propagated quickly * System-wide synchronization ensures consistency **Cache Management** * Appropriate cache invalidation on menu changes * Consistent data across multiple application instances * Time-based cache expiration for data freshness * Geographic cache distribution for global applications **Synchronization Protocols** * Database replication ensures data availability * Event-driven updates maintain system consistency * Conflict resolution for concurrent modifications * Audit trails for change tracking and rollback **Quality Assurance** * Data validation ensures menu integrity * Automated testing verifies API reliability * Monitoring systems track data quality metrics * Error detection and correction mechanisms # Get Menu List Source: https://developer.lulacommerce.com/api-reference/menus/get-menu-list GET /stores/{{store_id}}/menu/list?status=active&sortBy=categories&sortDirection=desc&name=all Retrieve a list of all menus for a specific store with filtering, sorting, and detailed menu information including operating hours and item counts. This endpoint returns a comprehensive list of all menus associated with a store, including detailed menu configuration, operating hours, and statistical information about menu contents. The menu list provides essential information for menu management, including item counts, category statistics, and operating schedules, making it ideal for administrative dashboards and operational planning. ### Path Parameters The unique identifier of the store to retrieve menus for ### Query Parameters Filter menus by status: "active", "inactive", "all" Sort criteria: "name", "created\_date", "categories", "items" Sort direction: "asc" or "desc" Filter by menu name or "all" for all menus ### Response The response is an array of menu objects with comprehensive information: Unique identifier for the menu Display name of the menu External system menu identifier (if applicable) Store identifier this menu belongs to Whether this is the default menu for the store User ID who created the menu User ID who last updated the menu Creator's user identifier Last updater's user identifier Timestamp when the menu was created Timestamp when the menu was last updated Array of operating hours for the menu Unique identifier for the menu hour entry Parent menu identifier Opening time in HH:MM format Closing time in HH:MM format Day of the week (0=Sunday, 6=Saturday) Whether closed on this day Creator user ID Last updater user ID Creation timestamp Last update timestamp Total number of items in this menu Number of unique categories in this menu Number of modifier items in this menu ### Response Example ```json [ { "id": "dc1c117b-142d-437a-b56f-ffa39e417c6e", "menu_name": "All", "external_menu_id": "3c4d66ab-f372-4d4a-a14a-c2b7d9cee682", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "is_default": true, "created_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "updated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "created_by_id": "1000049", "last_updated_by": "1000049", "updated_by_id": "1000049", "createdAt": "2023-02-09T12:03:55.124Z", "updatedAt": "2024-08-05T10:14:39.875Z", "deletedAt": null, "menu_hours": [ { "id": "fb8ef97e-4a0f-4d36-9c1b-3e96b2b43cd6", "menu_id": "dc1c117b-142d-437a-b56f-ffa39e417c6e", "open_time": "00:00", "close_time": "23:59", "day_of_week": 3, "is_closed": false, "created_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "updated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "created_by_id": "1000049", "last_updated_by": "1000049", "updated_by_id": "1000049", "createdAt": "2023-07-04T12:42:24.108Z", "updatedAt": "2024-08-05T10:14:39.890Z", "deletedAt": null }, { "id": "f6e0f9c2-2aa9-4c7c-afa5-08a23e9f832f", "menu_id": "dc1c117b-142d-437a-b56f-ffa39e417c6e", "open_time": "00:00", "close_time": "23:59", "day_of_week": 5, "is_closed": false, "created_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "updated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "created_by_id": "1000049", "last_updated_by": "1000049", "updated_by_id": "1000049", "createdAt": "2023-07-04T12:42:24.108Z", "updatedAt": "2024-08-05T10:14:39.890Z", "deletedAt": null }, { "id": "37a519b3-70c2-4c10-980e-637af2541343", "menu_id": "dc1c117b-142d-437a-b56f-ffa39e417c6e", "open_time": "00:00", "close_time": "23:59", "day_of_week": 6, "is_closed": false, "created_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "updated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "created_by_id": "1000049", "last_updated_by": "1000049", "updated_by_id": "1000049", "createdAt": "2023-07-04T12:42:24.108Z", "updatedAt": "2024-08-05T10:14:39.890Z", "deletedAt": null }, { "id": "fc0f9a16-b178-4bd5-af2c-8208a48029ea", "menu_id": "dc1c117b-142d-437a-b56f-ffa39e417c6e", "open_time": "00:00", "close_time": "23:59", "day_of_week": 4, "is_closed": false, "created_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "updated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "created_by_id": "1000049", "last_updated_by": "1000049", "updated_by_id": "1000049", "createdAt": "2023-07-04T12:42:24.108Z", "updatedAt": "2024-08-05T10:14:39.890Z", "deletedAt": null }, { "id": "6f87e48c-fb01-45d7-b208-4f6f0b0053ea", "menu_id": "dc1c117b-142d-437a-b56f-ffa39e417c6e", "open_time": "00:00", "close_time": "23:59", "day_of_week": 1, "is_closed": false, "created_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "updated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "created_by_id": "1000049", "last_updated_by": "1000049", "updated_by_id": "1000049", "createdAt": "2023-07-04T12:42:24.108Z", "updatedAt": "2024-08-05T10:14:39.889Z", "deletedAt": null }, { "id": "0d3856d7-662d-4006-9e78-1d2b81279721", "menu_id": "dc1c117b-142d-437a-b56f-ffa39e417c6e", "open_time": "00:00", "close_time": "23:59", "day_of_week": 2, "is_closed": false, "created_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "updated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "created_by_id": "1000049", "last_updated_by": "1000049", "updated_by_id": "1000049", "createdAt": "2023-07-04T12:42:24.108Z", "updatedAt": "2024-08-05T10:14:39.889Z", "deletedAt": null }, { "id": "3c4d66ab-f372-4d4a-a14a-c2b7d9cee682", "menu_id": "dc1c117b-142d-437a-b56f-ffa39e417c6e", "open_time": "00:30", "close_time": "23:59", "day_of_week": 0, "is_closed": false, "created_by": null, "updated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "created_by_id": "1000049", "last_updated_by": "1000049", "updated_by_id": "1000049", "createdAt": "2023-07-18T09:37:05.335Z", "updatedAt": "2024-08-05T10:14:39.889Z", "deletedAt": null } ], "total_item_count": "2320", "unique_category_count": "11", "modifier_item_count": "0" } ] ``` **Item Count Metrics** * **total\_item\_count**: All individual items available in this menu * **unique\_category\_count**: Number of distinct product categories * **modifier\_item\_count**: Items that serve as modifiers for other products **Operating Hours Analysis** * Multiple entries per day indicate split operating hours * Different days can have different operating schedules * Sunday hours may differ from weekday schedules **Menu Performance Indicators** * Large item counts indicate comprehensive menus * High category counts suggest diverse product offerings * Modifier counts show customization options available **Time Format**: All times are displayed in 24-hour format (HH:MM) for consistency across different regions and to avoid AM/PM confusion. **Filtering Options**: Use the query parameters to efficiently find specific menus, especially in stores with many menu configurations. ### Use Cases **Administrative Dashboard** * Display all store menus for management overview * Show menu statistics for operational planning * Compare menu configurations across different stores * Monitor menu performance and utilization **Operational Planning** * Review operating hours for scheduling staff * Analyze menu complexity for training purposes * Plan inventory based on menu item counts * Coordinate marketing efforts with menu availability **System Integration** * Sync menu data with external systems * Update point-of-sale systems with current menus * Integrate with delivery platform APIs * Coordinate with inventory management systems **Business Analysis** * Compare menu performance across different configurations * Analyze the relationship between menu complexity and sales * Track menu evolution over time * Support decision-making for menu optimization ### Filtering and Sorting **Status Filtering** * **active**: Only show currently active menus * **inactive**: Show deactivated menus for review * **all**: Display all menus regardless of status **Sorting Options** * **name**: Alphabetical sorting by menu name * **created\_date**: Chronological sorting by creation date * **categories**: Sort by number of unique categories * **items**: Sort by total item count **Name Filtering** * Specific menu name for targeted retrieval * "all" parameter to retrieve all menus * Partial name matching for flexible searches **Direction Control** * **asc**: Ascending order (A-Z, oldest first, smallest first) * **desc**: Descending order (Z-A, newest first, largest first) ### Data Analysis **Menu Complexity Analysis** * High item counts may indicate comprehensive offerings * Low category counts might suggest specialization * Modifier counts show customization capabilities **Operating Schedule Patterns** * Consistent hours across days indicate standard operations * Variable hours suggest flexible business models * Multiple time slots per day show complex scheduling **Menu Management Insights** * Recent update timestamps indicate active management * Creation dates show menu lifecycle patterns * External menu IDs suggest third-party integrations **Performance Optimization** * Compare item counts with sales performance * Analyze category distribution for marketing insights * Use modifier counts to plan customization strategies ### Error Handling **Store Not Found** ```json { "error": "Store not found", "message": "The specified store does not exist" } ``` **Invalid Query Parameters** ```json { "error": "Invalid parameter", "message": "sortBy must be one of: name, created_date, categories, items" } ``` **No Menus Found** ```json { "data": [], "message": "No menus found for the specified criteria" } ``` **Access Denied** ```json { "error": "Access denied", "message": "Insufficient permissions to view store menus" } ``` ### Integration Considerations **API Response Handling** * Handle array responses appropriately * Process nested menu\_hours data correctly * Account for null values in optional fields * Implement proper error handling for edge cases **Data Caching Strategies** * Cache menu list data for frequently accessed stores * Implement cache invalidation on menu updates * Consider real-time updates for operational systems * Balance performance with data freshness requirements **External System Synchronization** * Use external\_menu\_id for third-party integration * Maintain mapping between internal and external IDs * Handle synchronization conflicts gracefully * Implement proper error recovery mechanisms **Performance Considerations** * Limit request frequency for large stores * Implement pagination for stores with many menus * Use appropriate filtering to reduce response size * Monitor API performance and optimize as needed # Get Store Menu Timings Source: https://developer.lulacommerce.com/api-reference/menus/get-store-menu-timings GET /stores/{{store_id}}/menu/timing?menu_ids={{menu_ids}} Retrieve specific timing information for selected menus, providing detailed operating hours and availability schedules. This endpoint returns detailed timing information for specific menus within a store, allowing applications to determine menu availability based on current time and operating schedules. Menu timing information is crucial for determining real-time menu availability and ensuring customers see only menus that are currently operational based on the store's schedule. ### Path Parameters The unique identifier of the store that owns the menus ### Query Parameters Comma-separated list of menu IDs to retrieve timing information for **Real-Time Availability** * Determine which menus are currently available * Check if menus will be available at future times * Calculate remaining time until menu closes * Identify upcoming menu availability windows **Operational Planning** * Plan staff schedules based on menu operating hours * Coordinate inventory management with menu availability * Schedule maintenance during menu closure periods * Align marketing campaigns with menu operating hours **Customer Experience** * Display accurate menu availability to customers * Show countdown timers for menu closing times * Provide advance notice of menu availability changes * Enable pre-ordering for future menu availability periods **System Integration** * Synchronize with point-of-sale systems * Coordinate with delivery platform schedules * Update inventory systems based on menu timing * Integrate with marketing automation platforms **Multiple Menu Support**: This endpoint can retrieve timing information for multiple menus simultaneously, making it efficient for applications that need to check availability across several menu options. **Time Zone Considerations**: Menu timing information should be interpreted in the store's local time zone for accurate availability calculations. ### Use Cases **Customer Application Features** * Show current menu availability status * Display "opening soon" or "closing soon" messages * Enable advance ordering for future menu periods * Provide estimated wait times for menu availability **Operational Management** * Monitor menu availability across multiple locations * Plan staff scheduling based on menu operating hours * Coordinate marketing campaigns with menu availability * Manage inventory replenishment timing **Partner Integration** * Synchronize delivery platform availability * Update third-party ordering systems * Coordinate with marketing automation tools * Integrate with business intelligence systems **Administrative Functions** * Monitor menu timing compliance * Analyze menu utilization patterns * Optimize menu schedules for business performance * Generate operational reports and insights ### Timing Calculation Logic **Daily Schedule Processing** * Each menu can have multiple time periods per day * Days of the week are processed independently * Closed days are clearly identified in timing data * Special schedules override default timing **Current Time Evaluation** * System compares current time to menu operating hours * Time zone conversion ensures accurate local time comparison * Overlap periods are handled for complex schedules * Transition times are calculated for opening/closing events **Future Availability Prediction** * Next available period calculation for closed menus * Remaining operating time for currently open menus * Weekly schedule projection for advance planning * Holiday and special event schedule integration **Complex Schedule Handling** * Multiple opening periods per day (e.g., lunch breaks) * Overnight operations crossing midnight * Seasonal schedule variations * Emergency schedule modifications ### Response Data Structure **Menu Timing Objects** * Individual timing data for each requested menu * Current availability status (open/closed) * Next availability window information * Complete weekly schedule details **Operating Hours Details** * Start and end times for each operating period * Day of week specifications * Closed day indicators * Special schedule annotations **Availability Calculations** * Time remaining until closure (for open menus) * Time until next opening (for closed menus) * Duration of next available period * Weekly availability summary **Metadata and Context** * Menu identification and naming * Store time zone information * Last update timestamps * Schedule version information ### Performance Optimization **Efficient Data Retrieval** * Optimized queries for multiple menu timing data * Indexed database operations for fast response * Cached timing calculations for frequently requested menus * Minimized data transfer for mobile applications **Real-Time Processing** * Immediate timing calculations based on current time * Dynamic availability status determination * Efficient schedule comparison algorithms * Optimized time zone conversion processing **Scalability Considerations** * Concurrent request handling for high-traffic periods * Database connection pooling for multiple menu queries * Memory-efficient data structures for timing calculations * Load balancing for geographic distribution **Caching Strategies** * Menu timing data caching with appropriate expiration * Schedule calculation result caching * Time zone conversion result caching * Strategic cache invalidation on schedule updates ### Integration Best Practices **Request Optimization** * Batch multiple menu IDs in single requests * Cache timing data appropriately for application needs * Implement efficient polling strategies for real-time updates * Use compression for large timing datasets **Error Handling** * Handle cases where menu IDs don't exist * Manage time zone conversion errors gracefully * Implement fallback behavior for service failures * Provide meaningful error messages to applications **Data Processing** * Parse timing data efficiently for application use * Handle complex schedule patterns appropriately * Implement proper time zone handling * Cache processed timing calculations when possible **User Experience** * Display timing information clearly to users * Provide advance notice of menu closing times * Show alternative menu options when current menus are closed * Update timing displays in real-time ### Error Handling **Invalid Menu IDs** ```json { "error": "Invalid menu IDs", "message": "One or more menu IDs do not exist", "invalid_ids": ["invalid-menu-id-1", "invalid-menu-id-2"] } ``` **Store Not Found** ```json { "error": "Store not found", "message": "The specified store does not exist", "store_id": "invalid-store-id" } ``` **No Timing Data** ```json { "message": "No timing data available for specified menus", "menu_ids": ["menu-1", "menu-2"] } ``` **Service Error** ```json { "error": "Timing service unavailable", "message": "Unable to retrieve timing information at this time" } ``` ### Business Applications **Revenue Optimization** * Maximize menu availability during peak demand periods * Optimize staff scheduling based on menu timing patterns * Coordinate promotional activities with menu availability * Analyze timing impact on customer behavior and sales **Customer Satisfaction** * Provide accurate menu availability information * Reduce customer frustration with unavailable menus * Enable advance planning for customer orders * Improve overall customer experience with reliable timing data **Operational Efficiency** * Streamline staff scheduling based on menu operating hours * Optimize inventory management with timing-based planning * Coordinate maintenance activities during menu closure periods * Improve resource allocation across multiple menu periods **Strategic Planning** * Analyze menu timing effectiveness for business growth * Identify opportunities for schedule optimization * Support expansion planning with timing pattern analysis * Enable data-driven decisions for menu schedule adjustments # Create Menu Item Source: https://developer.lulacommerce.com/api-reference/menus/menu-items/create-menu-item POST /stores/{{store_id}}/menu/items?active=true Add items to specific menus within a store, controlling which products appear in different menu configurations through category and item-level management. This endpoint manages the association of items with specific menus, allowing precise control over which products are available in each menu configuration. Menu item management provides granular control over product visibility, enabling businesses to create specialized menus for different times, customer segments, or operational requirements. ### Path Parameters The unique identifier of the store to add menu items for ### Query Parameters Whether to set the menu items as active upon creation ### Request Body Array of menu identifiers to add items to Array of category identifiers to include in the menus (adds all items in these categories) Array of specific item identifiers to exclude from the menu Array of specific item identifiers to include in the menu ### Request Example ```json { "menu_ids": [ "813f8ac7-cae5-4d2d-92ef-d6798547f95c" ], "category_ids": [], "excluded_ids": [], "included_ids": [ "c81d64ff-0651-48af-ab61-9b503be9f020", "3e3e0adb-5555-4832-9632-8bb71d861281" ] } ``` ### Response Confirmation message indicating the operation result Whether the operation completed successfully ### Response Example ```json { "message": "Store item(s) menu updated", "success": true } ``` **Category-Based Management** * Add entire product categories to menus efficiently * Maintain category associations for new items * Simplify menu management for large inventories * Enable automatic inclusion of new category items **Individual Item Control** * Precise control over specific item visibility * Override category-based inclusions with specific exclusions * Handle special items that don't fit standard categories * Support custom menu configurations **Hybrid Approach** * Combine category and individual item management * Use category inclusion with specific item exclusions * Create complex menu structures with precise control * Balance efficiency with customization needs **Inclusion Priority**: Individual item inclusions and exclusions take precedence over category-based selections, allowing for fine-tuned menu control. **Batch Operations**: Use multiple menu\_ids to apply the same item configuration across several menus simultaneously, improving efficiency for multi-menu updates. ### Use Cases **Specialized Menu Creation** * Create breakfast menus with specific morning items * Build lunch menus excluding breakfast-only products * Design dinner menus with premium items * Develop limited-time offer menus with promotional items **Category-Based Menu Building** * Include entire beverage category in all menus * Add all dessert items to dinner menus * Include fresh produce in healthy eating menus * Add seasonal items to special event menus **Selective Item Management** * Exclude high-cost items from discount menus * Include only available items in current inventory menus * Add featured items to promotional menus * Remove discontinued items from all menus **Multi-Menu Coordination** * Apply consistent item sets across franchise locations * Coordinate promotional items across multiple menus * Standardize core offerings while allowing customization * Manage inventory-driven menu changes ### Item Selection Logic **Processing Order** 1. **Category Inclusion**: All items from specified categories are added 2. **Individual Inclusion**: Specific items from included\_ids are added 3. **Exclusion Processing**: Items in excluded\_ids are removed 4. **Final Validation**: Ensure all included items are valid and available **Conflict Resolution** * Excluded items override category inclusions * Individual inclusions override category-based exclusions * Invalid item IDs are silently skipped * Empty arrays are processed without errors **Inventory Integration** * Only available inventory items can be included * Out-of-stock items may be automatically excluded * Seasonal availability affects item inclusion * Real-time inventory updates influence menu item visibility ### Validation Rules **Menu Validation** * All menu IDs must exist and belong to the specified store * Menus must be in a valid state for item assignment * User must have permissions to modify the specified menus * Menu configuration must support the requested item types **Item Validation** * All item IDs must correspond to valid inventory items * Items must be available for the store location * Items must be compatible with menu requirements * Category IDs must exist in the store's catalog **Business Rules** * Alcohol items may require special menu designation * Age-restricted items need appropriate menu labeling * Seasonal items are validated for current availability * Promotional items require valid campaign associations ### Error Handling **Invalid Menu IDs** ```json { "error": "Invalid menu IDs", "message": "One or more menu IDs do not exist or are not accessible", "invalid_menus": ["invalid-menu-id"] } ``` **Invalid Item IDs** ```json { "error": "Invalid item IDs", "message": "Some items could not be found in inventory", "invalid_items": ["invalid-item-id-1", "invalid-item-id-2"] } ``` **Store Access Error** ```json { "error": "Store access denied", "message": "Insufficient permissions to modify menus for this store" } ``` **Empty Request** ```json { "error": "Invalid request", "message": "At least one of category_ids or included_ids must be specified" } ``` ### Best Practices **Planning and Strategy** * Plan menu item associations based on business goals * Consider customer preferences and purchasing patterns * Align menu items with inventory management strategies * Coordinate with marketing and promotional campaigns **Efficient Operations** * Use category-based inclusion for large-scale menu updates * Leverage batch operations for multiple menu updates * Implement validation checks before submitting requests * Monitor item availability for menu accuracy **Quality Control** * Verify item associations after menu updates * Test menu functionality from customer perspective * Review menu performance after item changes * Maintain consistency across related menus **Performance Optimization** * Batch multiple menu updates when possible * Use appropriate granularity for item management * Monitor system performance during large updates * Implement proper error handling and retry logic ### Integration Patterns **Inventory Integration** * Sync menu items with current inventory levels * Automatically update menu availability based on stock * Handle inventory-driven item exclusions * Coordinate with procurement and supply chain systems **Point-of-Sale Integration** * Update POS systems with current menu item associations * Ensure consistent item availability across all channels * Coordinate pricing and promotional information * Sync modifier and customization options **Customer-Facing Systems** * Update mobile apps and websites with current menu items * Ensure consistent customer experience across platforms * Coordinate with ordering and delivery systems * Maintain real-time accuracy for customer-facing displays **Analytics and Reporting** * Track menu item performance and customer preferences * Analyze the impact of menu changes on sales * Generate insights for menu optimization * Support data-driven menu management decisions ### Menu Item Lifecycle **Item Addition Process** * Validate item eligibility for menu inclusion * Configure item-specific menu settings * Update all related systems and platforms * Monitor customer response and performance **Ongoing Management** * Regular review of menu item performance * Adjustment based on inventory and seasonal factors * Coordination with promotional and marketing activities * Optimization based on customer feedback and analytics **Item Removal Process** * Plan removal strategy to minimize customer disruption * Update all systems and customer-facing platforms * Archive historical data for analysis and reporting * Document reasons for removal for future reference **Performance Monitoring** * Track individual item contribution to menu success * Monitor customer engagement with specific items * Analyze seasonal and promotional performance patterns * Use data insights to optimize future menu configurations # Delete Menu Item Source: https://developer.lulacommerce.com/api-reference/menus/menu-items/delete-menu DELETE /stores/{{store_id}}/menus/{{menu_id}}/items/{{item_id}} Remove specific items from store menus, providing precise control over product visibility and menu composition for optimal customer experience. This endpoint enables the targeted removal of individual items from specific menus, allowing businesses to fine-tune their menu offerings and respond quickly to inventory changes or business requirements. Deleting menu items immediately affects customer-facing systems and may impact ongoing orders. Consider the timing and customer impact before removing items from active menus. ### Path Parameters The unique identifier of the store containing the menu The unique identifier of the menu to remove the item from The unique identifier of the item to remove from the menu ### Response Confirmation message indicating the operation result Whether the deletion operation completed successfully ### Response Example ```json { "message": "Item removed from menu successfully", "success": true } ``` **Immediate Removal** * Remove items that are no longer available * Handle emergency inventory shortages * Respond to food safety or quality concerns * Remove discontinued products quickly **Planned Removal** * Coordinate with inventory management * Time removal with promotional end dates * Plan around customer usage patterns * Coordinate with marketing campaigns **Gradual Phase-Out** * Remove from new customer-facing menus first * Maintain availability for existing orders * Allow for inventory depletion * Minimize customer experience disruption **Order Impact**: Items removed from menus may still be available for modification of existing orders depending on your order management configuration. **Batch Operations**: For removing multiple items, consider using the bulk menu update endpoints rather than individual deletion calls to improve performance. ### Use Cases **Inventory Management** * Remove items that are out of stock * Handle supply chain disruptions * Manage seasonal item availability * Control inventory levels through menu visibility **Product Lifecycle Management** * Remove discontinued products * Phase out underperforming items * Update menus for new product launches * Manage promotional item lifecycles **Operational Requirements** * Remove items due to equipment maintenance * Handle staffing limitations affecting preparation * Adjust menus for special events or hours * Respond to regulatory or safety requirements **Menu Optimization** * Remove items with poor performance metrics * Simplify menus for improved customer experience * Adjust offerings based on customer feedback * Optimize menus for specific time periods ### Deletion Impact Analysis **Customer Experience Impact** * Immediate removal from customer-facing systems * Potential impact on customer satisfaction if popular items are removed * Effect on customer ordering patterns and preferences * Consideration for regular customers who expect specific items **Operational Impact** * Immediate effect on kitchen operations and preparation * Impact on staff training and menu knowledge requirements * Changes to ordering and procurement processes * Effect on inventory management and waste reduction **Business Impact** * Potential revenue impact from removed items * Effect on average order value and customer spending * Impact on competitive positioning and menu differentiation * Consideration for promotional and marketing campaigns **System Integration Impact** * Updates required across all integrated systems * Impact on mobile apps and online ordering platforms * Changes needed in point-of-sale systems * Updates for third-party delivery platforms ### Validation and Safety Checks **Menu Validation** * Verify menu ID exists and belongs to the specified store * Confirm user has permissions to modify the menu * Check menu is in a valid state for modifications * Ensure menu is not locked due to ongoing operations **Item Validation** * Verify item ID exists in the specified menu * Confirm item is currently associated with the menu * Check for any special restrictions on item removal * Validate timing constraints for item removal **Business Rule Validation** * Check for active promotions using the item * Verify no pending orders contain the item * Confirm removal doesn't violate minimum menu requirements * Validate against any franchise or corporate restrictions **System State Validation** * Ensure systems are ready for the update * Verify no ongoing synchronization processes * Check for any maintenance modes that might affect the operation * Confirm all dependent systems are available ### Error Handling **Invalid Menu or Item** ```json { "error": "Invalid menu or item", "message": "Menu ID or item ID not found or not associated", "details": { "menu_id": "813f8ac7-cae5-4d2d-92ef-d6798547f95c", "item_id": "invalid-item-id" } } ``` **Permission Denied** ```json { "error": "Permission denied", "message": "Insufficient permissions to delete items from this menu" } ``` **Item Not in Menu** ```json { "error": "Item not found in menu", "message": "The specified item is not currently associated with this menu" } ``` **Business Rule Violation** ```json { "error": "Business rule violation", "message": "Item cannot be removed due to active promotions or pending orders", "details": { "active_promotions": 2, "pending_orders": 5 } } ``` ### Best Practices **Planning and Communication** * Plan item removals during low-traffic periods * Communicate changes to staff and customers when appropriate * Coordinate with marketing and operations teams * Document reasons for removal for future analysis **Timing Considerations** * Avoid removing items during peak ordering times * Consider customer usage patterns and preferences * Coordinate with promotional campaigns and events * Time removals to minimize customer disruption **Monitoring and Follow-up** * Monitor customer feedback after item removal * Track impact on overall menu performance * Analyze changes in ordering patterns * Document lessons learned for future menu management **System Coordination** * Ensure all integrated systems are updated * Verify customer-facing platforms reflect changes * Coordinate with third-party delivery platforms * Maintain consistency across all touchpoints ### Recovery and Rollback **Immediate Recovery** * Use the create menu item endpoint to re-add accidentally removed items * Verify all systems reflect the restoration * Communicate restoration to affected staff and customers * Monitor for any lingering system inconsistencies **Data Recovery** * Retrieve item configuration from system backups if needed * Restore associated promotional and pricing information * Recreate any custom modifiers or specifications * Verify all historical data integrity **Process Improvement** * Review deletion procedures to prevent future mistakes * Implement additional validation checks if needed * Improve staff training on menu management procedures * Document improved processes for consistent application **Customer Communication** * Address customer concerns about item availability * Provide clear communication about restoration * Offer alternatives or compensation if appropriate * Use feedback to improve future menu management ### Integration Considerations **Real-time Updates** * Ensure immediate propagation to customer-facing systems * Update point-of-sale systems in real-time * Synchronize with mobile apps and online ordering platforms * Coordinate with third-party delivery services **Data Consistency** * Maintain data integrity across all integrated systems * Handle potential synchronization delays gracefully * Implement proper error handling for integration failures * Monitor for and resolve any consistency issues **Performance Optimization** * Batch deletions when removing multiple items * Optimize update processes for large menu changes * Minimize system load during peak operation times * Implement efficient caching strategies **Audit and Compliance** * Maintain detailed logs of all deletion operations * Track user actions for accountability and analysis * Ensure compliance with data retention requirements * Support audit trails for business and regulatory needs ### Menu Management Workflow **Regular Maintenance** * Schedule regular reviews of menu item performance * Identify candidates for removal based on data analysis * Plan systematic cleanup of outdated or underperforming items * Maintain optimal menu size and composition **Dynamic Management** * Respond quickly to inventory changes and shortages * Adjust menus based on seasonal availability * Handle emergency situations requiring immediate item removal * Support flexible business operations **Strategic Planning** * Align item removal with broader business strategy * Support new product introductions by removing outdated items * Optimize menu composition for target customer segments * Balance menu diversity with operational efficiency **Continuous Improvement** * Use deletion data to inform future menu planning * Analyze patterns in item removal and customer response * Refine deletion processes based on operational experience * Develop best practices for sustainable menu management # Update Menu Item Source: https://developer.lulacommerce.com/api-reference/menus/menu-items/update-menu-item PUT /stores/{{store_id}}/menus/{{menu_id}}/items/{{item_id}} Modify menu item properties, availability, and configuration within specific menus to maintain accurate and optimized menu offerings. This endpoint provides comprehensive menu item update capabilities, allowing businesses to adjust item properties, pricing, availability, and other menu-specific configurations while maintaining system consistency. Menu item updates enable dynamic menu management, allowing businesses to respond to inventory changes, promotional requirements, and operational needs in real-time. ### Path Parameters The unique identifier of the store containing the menu The unique identifier of the menu containing the item to update The unique identifier of the item to update ### Request Body Controls whether the item is available for ordering in this menu Custom pricing for this item within this specific menu (overrides base item price) Controls the display order of the item within the menu Menu-specific description that overrides the default item description Array of promotional tags specific to this menu item association Menu-specific modifier configurations for this item ### Request Example ```json { "is_available": true, "menu_specific_price": 12.99, "display_order": 5, "menu_item_description": "Fresh grilled salmon with seasonal vegetables", "promotional_tags": ["featured", "healthy"], "menu_item_modifiers": { "cooking_preferences": ["medium", "well-done"], "side_options": ["rice", "vegetables", "salad"] } } ``` ### Response Confirmation message indicating the operation result Whether the update operation completed successfully Details of the updated menu item configuration ### Response Example ```json { "message": "Menu item updated successfully", "success": true, "updated_item": { "item_id": "c81d64ff-0651-48af-ab61-9b503be9f020", "menu_id": "813f8ac7-cae5-4d2d-92ef-d6798547f95c", "is_available": true, "menu_specific_price": 12.99, "display_order": 5, "last_updated": "2024-01-15T10:30:00Z" } } ``` **Availability Management** * Control item availability without removing from menu * Handle temporary shortages or supply chain issues * Manage seasonal item availability * Support time-based availability controls **Pricing Optimization** * Implement menu-specific pricing strategies * Support promotional pricing for specific menus * Test price points across different menu configurations * Maintain competitive pricing while maximizing margins **Display and Ordering** * Optimize item positioning within menus * Highlight popular or promoted items through ordering * Create logical groupings and flow * Enhance customer discovery and selection experience **Content Customization** * Tailor descriptions for specific menu contexts * Highlight different features for different customer segments * Support localization and customization requirements * Enhance marketing and promotional messaging **Menu-Specific Settings**: Updates apply only to the specific menu-item association. The base item properties remain unchanged unless specifically modified through item management endpoints. **Batch Updates**: For updating multiple items with similar changes, consider implementing batch update logic in your application to reduce API calls and improve performance. ### Use Cases **Dynamic Availability Management** * Toggle item availability based on inventory levels * Handle equipment maintenance affecting specific items * Manage staffing limitations for complex preparations * Control availability during special events or promotions **Promotional Campaigns** * Update pricing for limited-time offers * Add promotional tags and descriptions * Adjust display order to feature promoted items * Configure special modifiers for promotional periods **Seasonal Adjustments** * Update descriptions to reflect seasonal ingredients * Adjust pricing for seasonal cost variations * Modify availability based on seasonal supply * Update promotional tags for seasonal marketing **Menu Optimization** * Reorder items based on performance data * Update descriptions based on customer feedback * Adjust pricing based on market analysis * Optimize modifier configurations for efficiency ### Update Field Details **Availability Control** * `is_available`: Controls immediate customer access to the item * Affects all customer-facing systems and ordering platforms * Does not remove the item from the menu structure * Enables quick response to operational changes **Pricing Management** * `menu_specific_price`: Overrides base item pricing for this menu * Supports menu-specific pricing strategies * Enables promotional pricing without affecting other menus * Maintains pricing flexibility across different contexts **Display Optimization** * `display_order`: Controls item position within menu sections * Lower numbers appear first in the display order * Enables strategic positioning of high-margin or popular items * Supports logical grouping and customer flow optimization **Content Customization** * `menu_item_description`: Menu-specific item description * Overrides base item description for this menu context * Supports targeted messaging for specific customer segments * Enables localization and customization **Promotional Enhancement** * `promotional_tags`: Array of tags for marketing and display * Supports visual highlighting in customer interfaces * Enables filtering and categorization for promotions * Provides metadata for analytics and reporting **Modifier Configuration** * `menu_item_modifiers`: Menu-specific modifier settings * Allows different modifier options per menu * Supports context-appropriate customization options * Enables menu-specific operational workflows ### Validation Rules **Menu and Item Validation** * Menu ID must exist and belong to the specified store * Item ID must exist and be associated with the specified menu * User must have appropriate permissions for menu modifications * Menu must be in a valid state for updates **Data Validation** * Pricing values must be positive numbers with appropriate precision * Display order must be a valid integer * Description length must be within system limits * Promotional tags must be from approved tag sets **Business Rule Validation** * Price changes must comply with business pricing policies * Availability changes must consider inventory and operational constraints * Display order changes must maintain menu structure integrity * Modifier configurations must be valid for the item type **System Validation** * All referenced modifiers and options must exist * Promotional tags must be valid and active * Price formats must match system requirements * Description content must meet content policy requirements ### Error Handling **Invalid Menu Item Association** ```json { "error": "Menu item not found", "message": "The specified item is not associated with this menu", "details": { "menu_id": "813f8ac7-cae5-4d2d-92ef-d6798547f95c", "item_id": "invalid-item-id" } } ``` **Invalid Price Value** ```json { "error": "Invalid price", "message": "Menu specific price must be a positive number", "provided_value": -5.99 } ``` **Permission Denied** ```json { "error": "Permission denied", "message": "Insufficient permissions to update items in this menu" } ``` **Business Rule Violation** ```json { "error": "Business rule violation", "message": "Price change exceeds maximum allowed variance from base price", "details": { "base_price": 10.99, "requested_price": 25.99, "max_variance": "50%" } } ``` ### Best Practices **Planning and Strategy** * Plan updates during low-traffic periods when possible * Consider the impact on customer experience and ordering patterns * Coordinate updates with marketing and promotional campaigns * Document reasons for changes for future analysis **Data Management** * Validate data before sending update requests * Use appropriate data types and formats * Maintain consistency across related menu items * Implement proper error handling and retry logic **Performance Optimization** * Batch related updates when possible * Use targeted updates rather than full item replacement * Monitor system performance during large-scale updates * Implement efficient caching strategies **Quality Assurance** * Verify updates are reflected in customer-facing systems * Test ordering functionality after significant changes * Monitor customer feedback and ordering patterns * Implement rollback procedures for problematic updates ### Integration Patterns **Real-time Synchronization** * Ensure immediate propagation to all customer-facing systems * Update point-of-sale systems with current item configurations * Synchronize with mobile apps and online ordering platforms * Coordinate with third-party delivery and ordering services **Inventory Integration** * Sync availability updates with inventory management systems * Automatically adjust availability based on stock levels * Coordinate pricing updates with cost management systems * Integrate with procurement and supply chain systems **Analytics and Reporting** * Track update patterns and their impact on sales * Monitor customer response to pricing and availability changes * Generate insights for menu optimization strategies * Support data-driven decision making **Customer Experience Integration** * Ensure consistent presentation across all customer touchpoints * Update search and recommendation algorithms with new configurations * Maintain accurate nutritional and allergen information * Support personalization and customer preference systems ### Menu Item Lifecycle Management **Introduction Phase** * Set initial availability and pricing * Configure promotional tags for new item launches * Optimize display order for customer discovery * Monitor performance and adjust configuration accordingly **Growth and Optimization** * Adjust pricing based on demand and cost analysis * Optimize display order based on customer behavior * Update descriptions based on customer feedback * Fine-tune modifier configurations for operational efficiency **Maturity Management** * Maintain optimal pricing and positioning * Adjust availability based on inventory optimization * Update promotional strategies based on market position * Monitor competitive positioning and adjust accordingly **Decline and Phase-out** * Gradually reduce visibility through display order adjustments * Implement clearance pricing strategies * Manage availability during inventory depletion * Plan removal strategy while maintaining customer satisfaction ### Performance Monitoring **Customer Impact Analysis** * Track ordering patterns before and after updates * Monitor customer feedback and satisfaction scores * Analyze impact on average order value and frequency * Measure customer discovery and selection rates **Operational Impact Assessment** * Monitor kitchen efficiency and preparation times * Track inventory turnover and waste reduction * Analyze staff efficiency with updated configurations * Measure overall operational performance changes **Business Performance Metrics** * Track revenue impact of pricing and availability changes * Monitor profit margin improvements from optimization * Analyze competitive positioning and market share * Measure ROI of menu management activities **System Performance Monitoring** * Track API response times and system performance * Monitor integration effectiveness across platforms * Analyze data consistency and synchronization success * Measure customer experience quality across touchpoints # Get Menu Rules Source: https://developer.lulacommerce.com/api-reference/menus/menu-rules/get-menu-rules GET /stores/{{store_id}}/menu-rules Retrieve comprehensive menu rules and business logic configurations that govern menu behavior, item availability, and operational constraints for a specific store. This endpoint provides access to the complete set of menu rules that control menu behavior, item availability, pricing logic, and operational constraints, enabling sophisticated menu management and automation. Menu rules provide the business logic layer that automates menu management, ensuring consistent application of business policies, operational constraints, and customer experience requirements. ### Path Parameters The unique identifier of the store to retrieve menu rules for ### Query Parameters Filter rules by type (availability, pricing, display, operational) Return only currently active rules Filter rules that apply to a specific menu Include detailed rule configuration and metadata ### Response Array of menu rule objects with complete configuration details Total number of rules for the store Number of currently active rules Summary of rules by category and type ### Response Example ```json { "rules": [ { "rule_id": "rule_123", "rule_name": "Breakfast Hour Availability", "rule_type": "availability", "is_active": true, "priority": 1, "conditions": { "time_range": { "start": "06:00", "end": "11:00" }, "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"] }, "actions": { "set_availability": true, "apply_to_items": ["breakfast_menu_items"] }, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "total_count": 15, "active_count": 12, "rule_categories": { "availability": 8, "pricing": 4, "display": 2, "operational": 1 } } ``` **Availability Rules** * Time-based item availability controls * Inventory-driven availability automation * Seasonal and event-based availability * Staff and equipment availability constraints **Pricing Rules** * Dynamic pricing based on demand and time * Promotional pricing automation * Competitive pricing adjustments * Cost-based pricing calculations **Display Rules** * Item ordering and positioning logic * Promotional highlighting and featuring * Category and section organization * Customer segment-based display **Operational Rules** * Kitchen capacity and preparation constraints * Delivery and pickup availability * Special event and holiday modifications * Compliance and regulatory requirements **Rule Hierarchy**: Rules are applied in priority order, with higher priority rules taking precedence over lower priority ones when conflicts arise. **Performance Optimization**: Use filtering parameters to retrieve only the specific rules you need, especially when dealing with stores that have extensive rule configurations. ### Use Cases **Automated Availability Management** * Automatically enable breakfast items during morning hours * Disable alcohol sales outside permitted hours * Control seasonal item availability based on calendar dates * Manage item availability based on inventory levels **Dynamic Pricing Strategies** * Implement happy hour pricing for beverages * Apply surge pricing during peak demand periods * Offer time-based discounts for slow periods * Automatically adjust pricing based on competitive analysis **Operational Efficiency** * Limit complex item availability during busy periods * Adjust menu based on staffing levels * Control delivery availability based on weather conditions * Manage special event menu configurations **Customer Experience Optimization** * Highlight popular items during peak hours * Feature healthy options during fitness-focused time periods * Promote comfort food during bad weather * Customize menu display based on customer preferences ### Rule Structure Details **Rule Metadata** * `rule_id`: Unique identifier for the rule * `rule_name`: Human-readable name for management purposes * `rule_type`: Category of rule (availability, pricing, display, operational) * `is_active`: Whether the rule is currently enabled * `priority`: Execution order when multiple rules apply **Condition Configuration** * `time_range`: Specific time periods when the rule applies * `days_of_week`: Specific days when the rule is active * `date_range`: Specific date periods for seasonal or event rules * `inventory_conditions`: Stock level thresholds that trigger the rule * `weather_conditions`: Weather-based triggers for rule activation * `customer_segments`: Specific customer types the rule applies to **Action Specification** * `set_availability`: Control item or menu availability * `adjust_pricing`: Modify pricing with specific calculations * `update_display_order`: Change item positioning and visibility * `apply_promotions`: Activate or modify promotional campaigns * `send_notifications`: Trigger staff or system notifications **Scope and Targeting** * `apply_to_items`: Specific items affected by the rule * `apply_to_categories`: Categories affected by the rule * `apply_to_menus`: Specific menus where the rule applies * `exclude_items`: Items to exclude from rule application ### Rule Types and Examples **Availability Rules** ```json { "rule_type": "availability", "conditions": { "time_range": {"start": "23:00", "end": "06:00"}, "inventory_threshold": {"min": 5} }, "actions": { "set_availability": false, "apply_to_categories": ["alcohol", "complex_preparations"] } } ``` **Pricing Rules** ```json { "rule_type": "pricing", "conditions": { "time_range": {"start": "15:00", "end": "17:00"}, "days_of_week": ["monday", "tuesday", "wednesday"] }, "actions": { "adjust_pricing": {"type": "percentage", "value": -20}, "apply_to_categories": ["beverages", "appetizers"] } } ``` **Display Rules** ```json { "rule_type": "display", "conditions": { "customer_segment": "health_conscious", "time_range": {"start": "11:00", "end": "14:00"} }, "actions": { "update_display_order": {"promote": true}, "apply_to_items": ["salads", "low_calorie_options"] } } ``` **Operational Rules** ```json { "rule_type": "operational", "conditions": { "weather_condition": "rain", "staff_count": {"min": 3} }, "actions": { "set_availability": true, "apply_to_categories": ["comfort_food", "hot_beverages"] } } ``` ### Rule Evaluation Process **Evaluation Sequence** 1. **Condition Assessment**: All rule conditions are evaluated against current context 2. **Priority Sorting**: Applicable rules are sorted by priority (highest first) 3. **Conflict Resolution**: Higher priority rules override lower priority ones 4. **Action Execution**: Rule actions are applied in priority order 5. **Result Validation**: Final menu state is validated for consistency **Context Evaluation** * Current date and time are compared against rule conditions * Inventory levels are checked against rule thresholds * Weather data is evaluated for weather-dependent rules * Customer segment information is used for targeted rules * Staff and operational data is considered for operational rules **Conflict Resolution** * Rules with the same priority are processed in creation order * Explicit exclusions override general inclusions * Availability rules take precedence over display rules * Safety and compliance rules have highest priority **Performance Optimization** * Rules are cached and evaluated efficiently * Only applicable rules are processed based on current context * Rule evaluation results are cached for consistent application * System monitors rule performance and execution times ### Rule Management Insights **Rule Performance Analysis** * Track rule activation frequency and patterns * Monitor rule impact on sales and customer behavior * Analyze rule conflict frequency and resolution * Measure rule execution performance and system impact **Business Impact Assessment** * Evaluate rule effectiveness in achieving business goals * Monitor customer satisfaction impact of rule applications * Analyze operational efficiency improvements from automation * Assess revenue impact of pricing and availability rules **Rule Optimization Opportunities** * Identify redundant or conflicting rules * Optimize rule conditions for better targeting * Simplify complex rule hierarchies * Improve rule performance through better condition design **Compliance and Audit Support** * Track rule changes and modifications over time * Maintain audit trails for regulatory compliance * Document rule rationale and business justification * Support compliance reporting and verification ### Error Handling **Store Not Found** ```json { "error": "Store not found", "message": "The specified store ID does not exist or is not accessible" } ``` **Invalid Filter Parameters** ```json { "error": "Invalid filter", "message": "The specified rule_type is not valid", "valid_types": ["availability", "pricing", "display", "operational"] } ``` **Permission Denied** ```json { "error": "Permission denied", "message": "Insufficient permissions to view menu rules for this store" } ``` **System Error** ```json { "error": "System error", "message": "Unable to retrieve menu rules due to system maintenance", "retry_after": "2024-01-15T11:00:00Z" } ``` ### Best Practices **Rule Design Principles** * Keep rule conditions simple and easy to understand * Use descriptive names and documentation for complex rules * Avoid creating conflicting rules whenever possible * Design rules with clear business objectives in mind **Performance Considerations** * Use filtering to retrieve only necessary rules * Monitor rule execution performance and optimize as needed * Avoid overly complex condition logic that impacts performance * Cache rule results appropriately for consistent application **Maintenance and Monitoring** * Regularly review rule effectiveness and business impact * Remove or update obsolete rules that no longer serve business needs * Monitor for unintended rule interactions and conflicts * Maintain documentation of rule purpose and expected behavior **Integration Strategy** * Ensure rule data is used consistently across all systems * Coordinate rule changes with operational procedures * Integrate rule monitoring with business intelligence systems * Use rule data to inform menu optimization strategies ### Integration Patterns **Real-time Rule Application** * Integrate rule evaluation with menu display systems * Apply rules in real-time for customer-facing applications * Coordinate rule application across multiple channels * Ensure consistent rule application across all touchpoints **Business Intelligence Integration** * Feed rule data into analytics and reporting systems * Track rule performance and business impact * Generate insights for rule optimization * Support data-driven rule management decisions **Operational System Integration** * Connect rules with inventory management systems * Integrate with staff scheduling and capacity planning * Coordinate with weather and external data sources * Support compliance and regulatory reporting requirements **Customer Experience Integration** * Apply rules to personalize customer menu experiences * Use rules to optimize recommendation engines * Integrate with loyalty and customer segmentation systems * Support dynamic pricing and promotional strategies ### Menu Rule Lifecycle **Rule Creation and Testing** * Design rules with clear business objectives * Test rules in staging environments before production deployment * Validate rule logic and expected outcomes * Document rule purpose and expected behavior **Active Rule Monitoring** * Monitor rule activation and performance regularly * Track business impact and customer response * Identify opportunities for rule optimization * Address any unintended consequences promptly **Rule Optimization and Updates** * Regularly review rule effectiveness and relevance * Update rules based on business changes and new requirements * Optimize rule performance and execution efficiency * Maintain rule documentation and rationale **Rule Retirement and Cleanup** * Identify and remove obsolete or redundant rules * Archive historical rule data for analysis * Document lessons learned for future rule development * Maintain clean and efficient rule configurations # Get Menu Rules by ID Source: https://developer.lulacommerce.com/api-reference/menus/menu-rules/get-menu-rules-by-id GET /stores/{{store_id}}/menu-rules/{{rule_id}} Retrieve detailed configuration and status information for a specific menu rule, including its conditions, actions, execution history, and performance metrics. This endpoint provides comprehensive details about a specific menu rule, enabling detailed analysis, troubleshooting, and optimization of individual rule configurations and their business impact. Individual rule retrieval provides deep insights into rule behavior, execution patterns, and business impact, supporting data-driven optimization and troubleshooting of menu automation logic. ### Path Parameters The unique identifier of the store containing the menu rule The unique identifier of the menu rule to retrieve ### Query Parameters Include rule execution history and performance metrics Include business impact analysis and effectiveness metrics Date range for historical data (format: YYYY-MM-DD,YYYY-MM-DD) ### Response Complete rule configuration and metadata Current rule status and next scheduled evaluation Historical execution records and outcomes (if requested) Business impact metrics and effectiveness analysis (if requested) ### Response Example ```json { "rule": { "rule_id": "rule_456", "rule_name": "Happy Hour Beverage Pricing", "rule_type": "pricing", "is_active": true, "priority": 10, "conditions": { "time_range": { "start": "15:00", "end": "18:00" }, "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"], "date_exceptions": ["2024-12-25", "2024-01-01"] }, "actions": { "adjust_pricing": { "type": "percentage", "value": -25, "round_to": 0.05 }, "apply_promotional_tag": "happy_hour" }, "scope": { "apply_to_categories": ["beverages", "appetizers"], "exclude_items": ["premium_wine", "specialty_cocktails"], "affected_item_count": 23 }, "effective_date_range": { "start_date": "2024-02-01", "end_date": "2024-03-31" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-20T14:45:00Z", "created_by": "manager_user_123" }, "execution_status": { "current_status": "inactive", "last_execution": "2024-01-19T17:00:00Z", "next_evaluation": "2024-01-22T15:00:00Z", "execution_count_today": 0, "total_executions": 45, "last_execution_result": "success" }, "execution_history": [ { "execution_time": "2024-01-19T17:00:00Z", "execution_result": "success", "items_affected": 23, "duration_ms": 125, "conditions_met": true, "actions_executed": ["adjust_pricing", "apply_promotional_tag"] } ], "impact_analysis": { "revenue_impact": { "total_discount_applied": 1250.75, "affected_orders": 89, "average_order_increase": 15.5 }, "customer_engagement": { "happy_hour_orders": 89, "repeat_customers": 34, "customer_satisfaction_score": 4.2 }, "operational_metrics": { "kitchen_efficiency": "improved", "inventory_turnover": "increased", "staff_feedback": "positive" } } } ``` **Configuration Details** * Complete rule setup including conditions and actions * Scope definition and affected items/categories * Priority and conflict resolution information * Effective date ranges and scheduling details **Execution Information** * Current rule status and evaluation schedule * Historical execution patterns and success rates * Performance metrics and execution timing * Error logs and troubleshooting information **Business Impact Analysis** * Revenue impact from rule applications * Customer behavior changes and engagement metrics * Operational efficiency improvements * Competitive positioning and market response **Performance Metrics** * Rule execution frequency and patterns * System performance impact and optimization opportunities * Integration effectiveness across platforms * Customer satisfaction and experience metrics **Data Availability**: Historical and impact analysis data may have retention limits. Specify appropriate date ranges to ensure you receive the data you need for analysis. **Performance Monitoring**: Use the execution history to identify optimization opportunities and troubleshoot rule performance issues for better business outcomes. ### Use Cases **Rule Performance Optimization** * Analyze execution patterns to optimize rule timing * Identify performance bottlenecks in rule evaluation * Optimize rule conditions for better targeting * Improve rule effectiveness through data-driven adjustments **Business Impact Assessment** * Measure revenue impact of pricing and promotional rules * Analyze customer response to availability changes * Evaluate operational efficiency improvements * Assess competitive positioning and market response **Troubleshooting and Debugging** * Investigate unexpected rule behavior or conflicts * Analyze execution failures and error patterns * Validate rule logic against business requirements * Identify integration issues with external systems **Compliance and Auditing** * Review rule changes and approval history * Validate rule compliance with business policies * Generate audit reports for regulatory requirements * Document rule effectiveness for business reviews ### Execution Status Details **Current Status Values** * `active`: Rule is currently executing actions * `inactive`: Rule conditions are not met * `scheduled`: Rule is waiting for next evaluation time * `disabled`: Rule is manually disabled * `error`: Rule has encountered execution errors * `expired`: Rule has passed its effective date range **Execution Timing** * `last_execution`: When the rule was last evaluated * `next_evaluation`: When the rule will be evaluated next * `execution_count_today`: Number of executions in the current day * `total_executions`: Lifetime execution count for the rule **Performance Metrics** * `execution_duration`: Time taken for rule evaluation and action execution * `success_rate`: Percentage of successful rule executions * `error_frequency`: Rate of execution errors and failures * `system_impact`: Resource utilization during rule execution **Result Information** * `items_affected`: Number of items impacted by the rule * `actions_executed`: List of actions successfully completed * `conditions_met`: Which conditions triggered the rule execution * `conflict_resolution`: How conflicts with other rules were resolved ### Historical Analysis **Execution Patterns** * Daily, weekly, and monthly execution frequency * Seasonal patterns and trends in rule activation * Correlation between rule execution and business events * Peak execution times and system load patterns **Success and Failure Analysis** * Success rates and common failure modes * Error patterns and system integration issues * Performance degradation trends over time * Recovery patterns after system issues **Business Impact Trends** * Revenue impact trends over time * Customer behavior changes and adaptation patterns * Operational efficiency improvements and challenges * Competitive response and market dynamics **Optimization Opportunities** * Timing optimization based on execution patterns * Condition refinement for better targeting * Action optimization for improved effectiveness * Performance improvements through better rule design ### Impact Analysis Metrics **Revenue Impact** * `total_discount_applied`: Cumulative discount amount from pricing rules * `revenue_increase`: Revenue growth attributed to rule optimization * `average_order_value_change`: Impact on customer spending patterns * `profit_margin_impact`: Effect on business profitability **Customer Engagement** * `affected_orders`: Number of orders impacted by the rule * `repeat_customers`: Customer retention and repeat business * `customer_satisfaction_score`: Customer experience metrics * `new_customer_acquisition`: Attraction of new customers through rule benefits **Operational Metrics** * `kitchen_efficiency`: Impact on food preparation and service * `inventory_turnover`: Effect on inventory management and waste * `staff_productivity`: Impact on staff efficiency and workload * `delivery_performance`: Effect on delivery and fulfillment operations **Market Position** * `competitive_advantage`: Competitive positioning improvements * `market_share_impact`: Effect on market position and customer capture * `brand_perception`: Impact on brand image and customer perception * `pricing_competitiveness`: Positioning relative to market pricing ### Error Handling **Rule Not Found** ```json { "error": "Rule not found", "message": "The specified rule ID does not exist for this store", "details": { "store_id": "store_123", "rule_id": "invalid_rule_id" } } ``` **Permission Denied** ```json { "error": "Permission denied", "message": "Insufficient permissions to view detailed rule information" } ``` **Invalid Date Range** ```json { "error": "Invalid date range", "message": "The specified date range is invalid or exceeds maximum allowed period", "details": { "provided_range": "2024-01-01,2025-01-01", "maximum_days": 90 } } ``` **Data Not Available** ```json { "error": "Data not available", "message": "Historical data for the requested period is not available", "details": { "requested_date_range": "2023-01-01,2023-12-31", "available_from": "2024-01-01" } } ``` ### Best Practices **Regular Monitoring** * Schedule regular reviews of rule performance and impact * Monitor execution patterns for optimization opportunities * Track business impact metrics consistently * Identify and address performance issues promptly **Data-Driven Optimization** * Use execution history to optimize rule timing and conditions * Analyze impact metrics to improve rule effectiveness * Identify successful patterns for replication across other rules * Use performance data to guide rule design decisions **Troubleshooting Strategy** * Review execution history when investigating issues * Analyze error patterns to identify systematic problems * Use impact analysis to assess the severity of rule issues * Implement monitoring alerts for critical rule failures **Business Intelligence Integration** * Integrate rule data with broader business analytics * Use rule impact metrics in business performance dashboards * Correlate rule effectiveness with broader business outcomes * Support strategic decision-making with rule performance data ### Analytics and Reporting **Performance Dashboard Creation** * Create visualizations of rule execution patterns * Monitor business impact trends over time * Track customer satisfaction and engagement metrics * Display operational efficiency improvements **Comparative Analysis** * Compare rule effectiveness across different time periods * Analyze performance variations by day of week or season * Compare similar rules across different stores or locations * Benchmark rule performance against business objectives **Predictive Analytics** * Forecast rule impact based on historical patterns * Predict optimal timing for rule modifications * Anticipate customer response to rule changes * Model business impact of proposed rule modifications **ROI Analysis** * Calculate return on investment for rule automation * Measure cost savings from operational efficiency * Analyze revenue impact relative to implementation costs * Evaluate long-term business value of rule strategies ### Integration with Business Intelligence **Data Export and Integration** * Export rule data for integration with BI tools * Create data pipelines for real-time analytics * Integrate with existing business intelligence platforms * Support custom reporting and analysis requirements **Real-time Monitoring** * Implement real-time rule performance dashboards * Create alerts for rule performance anomalies * Monitor business impact in real-time * Support rapid response to rule issues **Strategic Planning Support** * Use rule data to inform menu strategy decisions * Support competitive analysis and positioning * Guide investment in menu automation capabilities * Inform customer experience optimization strategies **Compliance and Governance** * Generate compliance reports for audit requirements * Track rule changes and their business justification * Monitor adherence to business policies and guidelines * Support regulatory reporting and documentation needs ### Rule Optimization Workflow **Regular Review Process** 1. **Performance Assessment**: Analyze execution patterns and success rates 2. **Impact Evaluation**: Measure business impact and customer response 3. **Optimization Identification**: Identify opportunities for improvement 4. **Testing and Validation**: Test proposed changes in controlled environments 5. **Implementation**: Deploy optimized rules with monitoring 6. **Monitoring and Feedback**: Track improvements and gather feedback **Data-Driven Decision Making** * Use historical execution data to guide optimization decisions * Leverage impact analysis to prioritize optimization efforts * Apply statistical analysis to identify significant patterns * Test hypotheses through controlled rule modifications **Continuous Learning** * Document lessons learned from rule optimization efforts * Share best practices across teams and locations * Build organizational knowledge about effective rule design * Develop expertise in menu automation and optimization # Upsert Menu Rules Source: https://developer.lulacommerce.com/api-reference/menus/menu-rules/upsert-menu-rules PUT /stores/{{store_id}}/menu-rules Create or update menu rules that control menu behavior, item availability, pricing logic, and operational constraints to automate menu management and ensure consistent business policy application. This endpoint enables comprehensive menu rule management through upsert operations, allowing businesses to create new rules or update existing ones with sophisticated automation logic for menu behavior and business policy enforcement. Menu rule upserts provide powerful automation capabilities, enabling businesses to implement complex business logic that automatically adjusts menus based on time, inventory, weather, customer segments, and operational conditions. ### Path Parameters The unique identifier of the store to create or update menu rules for ### Request Body Unique identifier for the rule (if updating existing rule) Human-readable name for the rule for management purposes Type of rule: availability, pricing, display, or operational Whether the rule should be active upon creation/update Rule execution priority (higher numbers execute first) Rule activation conditions and triggers Actions to execute when rule conditions are met Items, categories, or menus the rule applies to Start and end dates for rule effectiveness ### Request Example ```json { "rule_name": "Happy Hour Beverage Pricing", "rule_type": "pricing", "is_active": true, "priority": 10, "conditions": { "time_range": { "start": "15:00", "end": "18:00" }, "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"], "date_exceptions": ["2024-12-25", "2024-01-01"] }, "actions": { "adjust_pricing": { "type": "percentage", "value": -25, "round_to": 0.05 }, "apply_promotional_tag": "happy_hour" }, "scope": { "apply_to_categories": ["beverages", "appetizers"], "exclude_items": ["premium_wine", "specialty_cocktails"] }, "effective_date_range": { "start_date": "2024-02-01", "end_date": "2024-03-31" } } ``` ### Response Unique identifier of the created or updated rule Confirmation message indicating the operation result Whether the upsert operation completed successfully Complete configuration of the created or updated rule ### Response Example ```json { "rule_id": "rule_456", "message": "Menu rule created successfully", "success": true, "rule_details": { "rule_id": "rule_456", "rule_name": "Happy Hour Beverage Pricing", "rule_type": "pricing", "is_active": true, "priority": 10, "created_at": "2024-01-15T10:30:00Z", "next_evaluation": "2024-01-15T15:00:00Z" } } ``` **Time-Based Automation** * Schedule automatic menu changes throughout the day * Implement seasonal availability and pricing * Handle special events and holiday modifications * Coordinate with business hours and operational schedules **Inventory-Driven Rules** * Automatically adjust availability based on stock levels * Implement dynamic pricing based on inventory costs * Handle supply chain disruptions automatically * Optimize inventory turnover through menu adjustments **Customer-Centric Rules** * Personalize menus based on customer segments * Implement loyalty program benefits automatically * Adjust offerings based on customer behavior patterns * Optimize for customer satisfaction and engagement **Operational Efficiency Rules** * Adjust menus based on staffing levels * Handle equipment maintenance and capacity constraints * Optimize for kitchen efficiency and preparation times * Coordinate with delivery and pickup operations **Rule Conflicts**: When multiple rules affect the same items, rules with higher priority values take precedence. Design your rule hierarchy carefully to avoid unintended conflicts. **Testing Strategy**: Use effective date ranges and the is\_active flag to test new rules safely before full deployment. Start with specific date ranges and limited scope for validation. ### Rule Types and Examples **Availability Rules** ```json { "rule_type": "availability", "conditions": { "time_range": {"start": "22:00", "end": "06:00"}, "inventory_threshold": {"operator": "less_than", "value": 10} }, "actions": { "set_availability": false, "send_notification": { "type": "staff_alert", "message": "Low inventory items disabled overnight" } }, "scope": { "apply_to_categories": ["perishable_items"] } } ``` **Dynamic Pricing Rules** ```json { "rule_type": "pricing", "conditions": { "weather_condition": {"type": "temperature", "operator": "greater_than", "value": 85}, "time_range": {"start": "11:00", "end": "16:00"} }, "actions": { "adjust_pricing": {"type": "percentage", "value": -15}, "apply_promotional_tag": "beat_the_heat" }, "scope": { "apply_to_categories": ["cold_beverages", "ice_cream"] } } ``` **Display Optimization Rules** ```json { "rule_type": "display", "conditions": { "customer_segment": "health_conscious", "days_of_week": ["monday", "tuesday", "wednesday"] }, "actions": { "update_display_order": {"boost_factor": 5}, "apply_promotional_tag": "healthy_choice", "feature_in_section": "recommended" }, "scope": { "apply_to_items": ["salads", "grilled_proteins", "fresh_juices"] } } ``` **Operational Rules** ```json { "rule_type": "operational", "conditions": { "staff_count": {"operator": "less_than", "value": 4}, "order_volume": {"operator": "greater_than", "value": 50} }, "actions": { "set_availability": false, "send_notification": { "type": "manager_alert", "message": "Complex items disabled due to high volume and low staffing" } }, "scope": { "apply_to_items": ["complex_preparations", "made_to_order_items"] } } ``` ### Condition Configuration **Time-Based Conditions** * `time_range`: Specific hours of the day * `days_of_week`: Specific days when rule applies * `date_range`: Specific calendar periods * `date_exceptions`: Specific dates to exclude * `recurring_schedule`: Complex recurring patterns **Inventory Conditions** * `inventory_threshold`: Stock level triggers * `cost_variance`: Pricing based on cost changes * `supplier_availability`: Supply chain status * `expiration_proximity`: Perishable item management **Environmental Conditions** * `weather_condition`: Weather-based triggers * `temperature_range`: Temperature-specific rules * `seasonal_conditions`: Season-based automation * `external_events`: Special event considerations **Operational Conditions** * `staff_count`: Staffing level requirements * `equipment_status`: Equipment availability * `order_volume`: Current demand levels * `delivery_capacity`: Delivery operation status **Customer Conditions** * `customer_segment`: Specific customer types * `loyalty_tier`: Customer loyalty levels * `order_history`: Customer behavior patterns * `demographic_data`: Customer demographic information ### Action Configuration **Availability Actions** * `set_availability`: Enable or disable items/categories * `adjust_availability_window`: Modify time-based availability * `inventory_reserve`: Reserve inventory for specific purposes * `capacity_limit`: Limit order quantities **Pricing Actions** * `adjust_pricing`: Percentage or fixed amount changes * `apply_discount`: Specific discount configurations * `surge_pricing`: Demand-based price increases * `bundling_offers`: Create promotional bundles **Display Actions** * `update_display_order`: Change item positioning * `feature_items`: Highlight specific items * `category_promotion`: Promote entire categories * `personalized_recommendations`: Customer-specific suggestions **Communication Actions** * `send_notification`: Alert staff or customers * `update_descriptions`: Modify item descriptions * `apply_promotional_tag`: Add marketing tags * `social_media_post`: Automated social media updates **Integration Actions** * `update_external_systems`: Sync with third-party platforms * `trigger_workflow`: Initiate business processes * `log_analytics_event`: Track business intelligence data * `inventory_adjustment`: Automatic inventory management ### Validation Rules **Structure Validation** * Rule name must be unique within the store * Rule type must be from approved list * Priority must be a positive integer * Conditions and actions must have valid structure **Logic Validation** * Condition logic must be evaluable * Action specifications must be executable * Scope definitions must reference valid items/categories * Date ranges must be logically consistent **Business Rule Validation** * Pricing adjustments must be within allowed ranges * Availability changes must comply with business policies * Promotional actions must align with marketing guidelines * Operational rules must respect safety and compliance requirements **System Validation** * Referenced items and categories must exist * Integration endpoints must be accessible * Notification channels must be configured * External data sources must be available ### Error Handling **Invalid Rule Configuration** ```json { "error": "Invalid rule configuration", "message": "Rule conditions contain invalid logic", "details": { "field": "conditions.inventory_threshold", "issue": "Invalid operator 'not_equal_to'" } } ``` **Business Rule Violation** ```json { "error": "Business rule violation", "message": "Pricing adjustment exceeds maximum allowed variance", "details": { "requested_adjustment": -50, "maximum_allowed": -30 } } ``` **Conflicting Rule Priority** ```json { "error": "Rule conflict", "message": "Rule with same priority already exists for overlapping scope", "details": { "conflicting_rule_id": "rule_123", "suggested_priority": 11 } } ``` **Invalid Scope Reference** ```json { "error": "Invalid scope", "message": "Referenced items or categories do not exist", "details": { "invalid_items": ["non_existent_item"], "invalid_categories": ["invalid_category"] } } ``` ### Best Practices **Rule Design Principles** * Start with simple rules and add complexity gradually * Use descriptive names that clearly indicate rule purpose * Document rule rationale and expected business impact * Design rules with clear start and end conditions **Priority Management** * Leave gaps in priority numbers for future rule insertion * Group related rules with similar priority ranges * Use higher priorities for safety and compliance rules * Document priority hierarchy and conflict resolution strategy **Testing and Validation** * Test rules in staging environment before production deployment * Use effective date ranges for safe rule rollout * Monitor rule impact and adjust as needed * Implement rollback procedures for problematic rules **Performance Optimization** * Design efficient condition logic to minimize evaluation time * Use specific scopes rather than broad category applications * Monitor rule execution performance and optimize as needed * Cache rule results appropriately for consistent application ### Rule Management Strategies **Phased Implementation** * Start with simple availability and pricing rules * Gradually add operational and display optimization rules * Implement customer segmentation rules after data collection * Build complex multi-condition rules based on experience **Business Alignment** * Align rules with overall business strategy and goals * Coordinate rule development with marketing and operations teams * Ensure rules support customer experience objectives * Integrate rules with loyalty and promotional programs **Continuous Improvement** * Regularly review rule effectiveness and business impact * Optimize rules based on performance data and customer feedback * Retire outdated rules that no longer serve business needs * Evolve rule complexity as business needs mature **Compliance and Governance** * Ensure rules comply with regulatory requirements * Implement approval processes for high-impact rules * Maintain audit trails for rule changes and impacts * Document rule governance and change management procedures ### Integration Considerations **Real-time Rule Engine** * Implement efficient rule evaluation for real-time menu updates * Ensure consistent rule application across all customer touchpoints * Coordinate rule execution with system performance requirements * Handle rule conflicts and exceptions gracefully **Data Integration** * Integrate with inventory management for real-time stock data * Connect with weather services for environmental conditions * Sync with staff scheduling systems for operational rules * Coordinate with customer data platforms for segmentation **External System Coordination** * Update point-of-sale systems with rule-driven changes * Sync with mobile apps and online ordering platforms * Coordinate with third-party delivery services * Integrate with marketing automation platforms **Analytics and Monitoring** * Track rule activation frequency and business impact * Monitor rule performance and execution efficiency * Generate insights for rule optimization and business intelligence * Support compliance reporting and audit requirements ### Rule Lifecycle Management **Rule Development Lifecycle** * **Planning**: Define business objectives and rule requirements * **Design**: Create rule logic and validate against requirements * **Testing**: Validate rule behavior in controlled environments * **Deployment**: Implement rules with appropriate safeguards * **Monitoring**: Track rule performance and business impact * **Optimization**: Refine rules based on data and feedback * **Retirement**: Remove obsolete rules and archive historical data **Version Control and Change Management** * Maintain version history for all rule changes * Implement approval workflows for rule modifications * Document change rationale and expected impact * Coordinate rule changes with business operations **Performance and Optimization** * Monitor rule execution performance and system impact * Optimize rule logic for efficiency and accuracy * Balance rule complexity with system performance * Continuously improve rule effectiveness and business value # Menus Service Overview Source: https://developer.lulacommerce.com/api-reference/menus/menus-overview Comprehensive guide to the Menus service for managing store menus, menu items, operating hours, and menu rules within the Lula Commerce platform. # Menus Service The Menus service provides comprehensive menu management capabilities for retail stores, enabling businesses to create, manage, and optimize their product offerings across different time periods, locations, and customer segments. ## Core Capabilities ### Menu Management * **Store Menu Creation**: Create customized menus for individual store locations * **Menu Configuration**: Configure menu settings, operating hours, and availability * **Menu Synchronization**: Sync menus across multiple store locations * **Dynamic Menu Updates**: Real-time menu modifications and status changes ### Operating Hours Management * **Weekly Schedules**: Configure different operating hours for each day of the week * **Multiple Time Slots**: Support for multiple opening/closing periods per day * **Holiday Management**: Special scheduling for holidays and events * **Time Zone Support**: Automatic time zone handling for multi-location businesses ### Menu Item Control * **Item Inclusion/Exclusion**: Granular control over which items appear in specific menus * **Category Management**: Organize menu items by categories and subcategories * **Bulk Operations**: Efficiently manage multiple menu items simultaneously * **Real-time Updates**: Instant menu item availability changes ### Rule-Based Menu Logic * **Conditional Display**: Show/hide items based on complex business rules * **Automated Operations**: Rules for automatically adding or removing items * **Multi-criteria Logic**: Rules based on categories, tags, names, and modifiers * **Flexible Operators**: Support for equals, contains, exists, and negation operators ## Business Benefits ### Operational Efficiency * **Centralized Management**: Single interface for managing all store menus * **Automated Synchronization**: Reduce manual work with bulk menu operations * **Real-time Updates**: Instant menu changes across all customer touchpoints * **Time-based Control**: Automatic menu adjustments based on operating hours ### Customer Experience * **Accurate Availability**: Customers see only available items during operating hours * **Personalized Menus**: Different menu configurations for different customer segments * **Consistent Experience**: Synchronized menus across multiple store locations * **Dynamic Content**: Real-time menu updates based on inventory and business rules ### Business Intelligence * **Menu Performance**: Track which menu configurations drive the most engagement * **Item Analytics**: Understand which items are most popular across different menus * **Operational Insights**: Analyze the impact of menu changes on business metrics * **Compliance Tracking**: Monitor menu rule compliance and effectiveness ## Service Architecture ### Menu Hierarchy ``` Store ├── Multiple Menus ├── Menu Configuration ├── Operating Hours ├── Menu Items └── Menu Rules ``` ### Integration Points * **Inventory Service**: Real-time inventory data for menu item availability * **Catalog Service**: Product information and categorization * **Store Service**: Store-specific configurations and settings * **Orders Service**: Menu data for order processing and validation ## Key Features **Dynamic Menu Configuration** * Multiple menus per store for different purposes * Default menu settings with override capabilities * Status management (active, inactive, draft) * External menu ID integration for third-party systems **Sophisticated Scheduling** * Day-of-week specific operating hours * Multiple time slots per day * Closed day handling * Special event scheduling **Intelligent Item Management** * Category-based item inclusion/exclusion * Individual item control * Bulk item operations * Real-time availability updates **Advanced Rule Engine** * Add/remove items based on conditions * Multiple criteria per rule * Logical operators (equals, contains, exists, not\_equals, not\_contains, not\_exists) * Subject types (category, item\_name, global\_item\_tag, modifier\_group) ## Use Cases ### Multi-Location Management * **Chain Stores**: Maintain consistent menus across multiple locations * **Franchise Operations**: Allow individual customization within brand guidelines * **Regional Variations**: Adapt menus for local preferences and regulations * **Centralized Control**: Manage all locations from a single administrative interface ### Time-Based Operations * **Breakfast/Lunch/Dinner**: Different menus for different meal periods * **Seasonal Menus**: Automatic switching based on calendar dates * **Limited-Time Offers**: Temporary menu items with automatic removal * **Holiday Specials**: Special menus for holidays and events ### Inventory Integration * **Stock-Based Availability**: Hide items when inventory is low * **Automatic Updates**: Real-time menu updates based on inventory changes * **Bulk Adjustments**: Mass menu changes during inventory updates * **Compliance Management**: Ensure menu accuracy with inventory levels ### Business Rules Implementation * **Promotional Items**: Automatically add promotional items to relevant menus * **Category Management**: Show/hide entire categories based on conditions * **Modifier Integration**: Menu rules based on available modifiers * **Tag-Based Logic**: Use item tags for sophisticated menu control ## Technical Specifications ### API Endpoints Structure * **Main Menu Operations**: Create, update, delete, and retrieve store menus * **Menu Item Management**: Control individual items within menus * **Menu Rules**: Configure automated menu logic and conditions * **Synchronization**: Bulk operations across multiple stores ### Data Model * **Menu Objects**: Complete menu configuration with metadata * **Menu Hours**: Detailed scheduling information with timezone support * **Menu Items**: Item associations with inclusion/exclusion logic * **Menu Rules**: Complex rule definitions with conditional logic ### Performance Considerations * **Caching Strategy**: Efficient caching for frequently accessed menu data * **Real-time Updates**: WebSocket support for instant menu changes * **Bulk Operations**: Optimized endpoints for large-scale menu management * **Query Optimization**: Efficient filtering and searching capabilities This comprehensive Menus service enables businesses to create sophisticated, dynamic menu management systems that enhance both operational efficiency and customer experience while providing the flexibility needed for complex retail operations. # Sync Menu For All Stores Source: https://developer.lulacommerce.com/api-reference/menus/sync-menu-for-all-stores POST /stores/menu/sync Synchronize menu configurations across multiple stores, allowing for bulk menu updates and coordination with external partners. This endpoint enables bulk menu synchronization across multiple store locations, facilitating consistent menu management and integration with external delivery platforms. Menu synchronization is essential for multi-location businesses to maintain consistent offerings across all stores while allowing for partner-specific customizations and configurations. ### Request Body Array of store identifiers to synchronize menus for User authentication identifier for the synchronization operation Array of partner platform names to synchronize with (e.g., "GrubHub", "DoorDash", "UberEats") ### Request Example ```json { "store_ids": ["449235c1-3d04-4519-998b-40d2a621e5e0"], "cognito_id": "b9b1a9d2-b70c-4364-a363-9854fb850e35", "partners": ["GrubHub"] } ``` **Multi-Store Coordination** * Synchronizes menu configurations across specified stores * Maintains consistency in menu offerings and availability * Coordinates operating hours and menu item associations * Ensures uniform customer experience across locations **Partner Platform Integration** * Updates external delivery platform menus * Synchronizes item availability and pricing * Coordinates operating hours with partner systems * Maintains data consistency across multiple platforms **Bulk Operation Benefits** * Reduces manual effort for multi-location updates * Ensures simultaneous updates across all specified stores * Minimizes timing discrepancies between store updates * Provides centralized control over menu configurations **Authentication Required**: The cognito\_id parameter is required for user authentication and audit trail purposes during bulk synchronization operations. **Partner Coordination**: Synchronization with external partners may take additional time to complete as it involves API calls to third-party systems. ### Use Cases **Chain Store Management** * Update menu configurations across all franchise locations * Implement new corporate menu standards * Coordinate seasonal menu changes across all stores * Ensure consistent branding and offerings **Partner Platform Updates** * Synchronize menus with delivery platforms after changes * Update item availability across multiple partner systems * Coordinate promotional campaigns with external partners * Maintain consistency between in-store and delivery menus **Operational Coordination** * Implement emergency menu changes across all locations * Coordinate inventory-driven menu updates * Synchronize operating hour changes across stores * Update menu rules and availability logic **Marketing Campaign Support** * Deploy promotional menus across multiple stores * Coordinate limited-time offers across all locations * Implement seasonal campaigns with menu changes * Support brand-wide marketing initiatives ### Synchronization Scope **Menu Configuration** * Menu names and descriptions * Default menu settings * Menu status (active/inactive) * External menu ID mappings **Operating Hours** * Daily operating schedules * Special hours for holidays or events * Closed day configurations * Multiple time slot schedules **Menu Items** * Item availability and associations * Category assignments * Modifier group associations * Item-specific menu rules **Partner-Specific Settings** * Platform-specific menu configurations * Partner delivery zones and timing * Pricing and availability adjustments * Custom partner requirements ### Performance Considerations **Batch Processing** * Operations are processed in batches for efficiency * Large store lists may take longer to complete * Progress tracking available for monitoring * Error handling for individual store failures **External Partner Timing** * Partner API rate limits may affect synchronization speed * Some partners may have delayed update processing * Network latency can impact overall completion time * Retry mechanisms handle temporary partner API failures **System Resource Management** * Database operations are optimized for bulk updates * Memory usage is managed for large synchronization jobs * CPU resources are allocated efficiently * Network bandwidth is used optimally **Monitoring and Alerts** * Real-time progress tracking for large operations * Error notifications for failed synchronizations * Success confirmations for completed operations * Performance metrics for optimization ### Error Handling **Store-Level Errors** ```json { "error": "Store synchronization failed", "message": "One or more stores failed to synchronize", "failed_stores": [ { "store_id": "store-123", "error": "Store not found" } ] } ``` **Partner Integration Errors** ```json { "error": "Partner synchronization failed", "message": "Failed to sync with external partner", "partner": "GrubHub", "details": "API rate limit exceeded" } ``` **Authentication Errors** ```json { "error": "Authentication failed", "message": "Invalid cognito_id provided" } ``` **Validation Errors** ```json { "error": "Invalid request", "message": "store_ids array cannot be empty" } ``` ### Best Practices **Planning and Preparation** * Review menu configurations before synchronization * Test synchronization with a small subset of stores first * Coordinate timing with business operations * Prepare rollback procedures for failed synchronizations **Error Prevention** * Validate store IDs before submitting requests * Ensure all specified stores are accessible * Verify partner platform connectivity * Check authentication credentials before operations **Monitoring and Verification** * Monitor synchronization progress in real-time * Verify successful completion across all stores * Check partner platforms for successful updates * Validate customer-facing changes after synchronization **Performance Optimization** * Batch store IDs efficiently for optimal performance * Schedule synchronizations during low-traffic periods * Use appropriate retry strategies for temporary failures * Monitor system resources during large operations ### Integration Guidelines **Supported Partners** * GrubHub: Full menu and operating hours sync * DoorDash: Menu items and availability updates * UberEats: Category and pricing synchronization * Custom partners: Configurable sync parameters **Data Mapping** * Internal menu structures mapped to partner formats * Operating hours converted to partner-specific formats * Item categories aligned with partner taxonomies * Pricing rules applied per partner requirements **Synchronization Timing** * Real-time updates for critical changes * Scheduled batch updates for routine synchronization * Emergency updates for urgent operational changes * Coordinated updates for marketing campaigns **Quality Assurance** * Data validation before sending to partners * Confirmation of successful partner updates * Error handling and retry mechanisms * Audit trails for compliance and troubleshooting ### Security and Compliance **Authentication and Authorization** * Cognito ID validation for user authentication * Permission verification for bulk operations * Role-based access control for sensitive operations * Audit logging for all synchronization activities **Data Protection** * Secure transmission of menu data to partners * Encryption of sensitive configuration information * Privacy compliance for customer-related data * Data retention policies for synchronization logs **Compliance Requirements** * Audit trails for regulatory compliance * Change tracking for operational transparency * User accountability for bulk operations * Documentation of synchronization procedures **Risk Management** * Rollback procedures for failed synchronizations * Backup and recovery for critical menu data * Monitoring for unauthorized access attempts * Alert systems for security-related events # Upsert Store Menu Source: https://developer.lulacommerce.com/api-reference/menus/upsert-store-menu PUT /stores/{{store_id}}/menu?menu_id={{menu_id}} Update or insert (upsert) a store menu with new configuration, operating hours, and settings. This endpoint allows you to update an existing menu or create a new one if it doesn't exist, providing flexibility for menu management operations. Upsert operations are ideal for menu synchronization and bulk updates, allowing you to maintain consistent menu configurations across multiple stores or update existing menus with new operating hours. ### Path Parameters The unique identifier of the store for which to upsert the menu ### Query Parameters The unique identifier of the menu to update, or leave empty to create a new menu ### Request Body Display name for the menu Whether this menu should be the default menu for the store Menu status: "active" or "inactive" Array of operating hours for each day of the week, including existing IDs for updates Day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday) Opening time in HH:MM format (24-hour) Closing time in HH:MM format (24-hour) Whether the store is closed on this day Existing menu hour ID (for updates) Parent menu ID (for existing menu hours) ### Request Example ```json { "menu_name": "Lula item schoping test menu", "is_default": false, "status": "active", "menu_hours": [ { "day_of_week": 0, "open_time": "00:00", "close_time": "01:00", "is_closed": false, "id": "6445fd02-ba77-49c9-9147-914520c46cfb", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 0, "open_time": "10:00", "close_time": "12:00", "is_closed": false, "id": "ca60d563-098a-4353-bac5-76c92b01d85c", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 1, "open_time": "01:00", "close_time": "03:59", "is_closed": false, "id": "3c699321-aa44-4e6a-9a30-e801d61b511a", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 1, "open_time": "10:00", "close_time": "17:00", "is_closed": false, "id": "9cc1f27d-0b60-41ae-8a7c-88e163af9d74", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 2, "open_time": "00:00", "close_time": "03:59", "is_closed": false, "id": "e334adad-c4ea-47c9-8b89-70f3d382b44f", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 2, "open_time": "10:00", "close_time": "17:00", "is_closed": false, "id": "d5de2e83-f6a8-4a3b-969b-8f021fcb7b8c", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 3, "open_time": "00:00", "close_time": "03:59", "is_closed": false, "id": "b7d7470a-20bf-447f-8fb3-166d605d8817", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 3, "open_time": "10:00", "close_time": "17:00", "is_closed": false, "id": "4ca9ce73-7c51-4529-8ed3-1d968d24d6a9", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 4, "open_time": "10:00", "close_time": "17:00", "is_closed": false, "id": "94bc7141-f44f-44e4-bfe4-062d6cb9b6e5", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 5, "open_time": "10:00", "close_time": "17:00", "is_closed": false, "id": "fb1b46d6-3c81-46fc-b45b-6ec9f1a4ad87", "menu_id": "17137644-0017-4284-b15d-4605b092f063" }, { "day_of_week": 6, "open_time": "10:00", "close_time": "17:00", "is_closed": false, "id": "bc421e4a-5b9f-49c3-867e-56114a0912c2", "menu_id": "17137644-0017-4284-b15d-4605b092f063" } ] } ``` **Create Mode (New Menu)** * When menu\_id is not provided or doesn't exist * Creates a new menu with all provided configuration * Generates new IDs for menu and menu hours * Sets creation timestamps and user information **Update Mode (Existing Menu)** * When menu\_id matches an existing menu * Updates menu configuration and operating hours * Preserves existing IDs where provided * Updates modification timestamps **Hybrid Operations** * Can add new menu hours while updating existing ones * Removes menu hours not included in the request * Supports partial updates of operating schedules * Maintains data integrity during complex changes **Multiple Time Slots**: This endpoint supports multiple opening/closing periods for the same day, allowing for complex scheduling like lunch breaks or split shifts. **Efficient Updates**: Include existing IDs in menu\_hours objects to update existing entries rather than recreating them, which preserves audit trails and related data. ### Use Cases **Menu Synchronization** * Sync menu configurations across multiple store locations * Maintain consistent operating hours across franchise locations * Update multiple menus with new corporate policies **Schedule Adjustments** * Modify operating hours for seasonal changes * Add special hours for holidays or events * Implement temporary schedule modifications **Complex Operating Hours** * Configure multiple opening periods per day * Set up lunch break closures or split shifts * Handle 24-hour operations with midnight transitions **Menu Template Application** * Apply standardized menu templates to new stores * Update existing menus to match new corporate standards * Implement brand-wide menu changes efficiently ### Split-Day Operations **Multiple Time Periods per Day** * Early morning hours (00:00-01:00) * Regular business hours (10:00-17:00) * Late evening service (22:00-23:59) **Lunch Break Management** * Morning hours (09:00-12:00) * Afternoon hours (13:00-17:00) * Closed period for lunch (12:00-13:00) **24-Hour Operations** * Continuous service across midnight * Day 0: 22:00-23:59 * Day 1: 00:00-06:00 **Special Event Scheduling** * Extended hours for promotions * Limited hours for maintenance * Holiday-specific operating schedules ### Data Validation **Time Format Validation** * Times must be in HH:MM format (24-hour) * Opening time must be before closing time (within the same day) * Times must be valid (00:00 to 23:59) **Day of Week Validation** * Must be integers between 0 and 6 * 0 = Sunday, 6 = Saturday * Each day can have multiple time periods **Menu Configuration Validation** * Menu name must be non-empty and unique within the store * Status must be "active" or "inactive" * is\_default must be boolean **ID Validation** * Existing IDs must reference valid menu hours * menu\_id in query parameter must match existing menu for updates * Invalid IDs will be ignored and new entries created ### Error Handling **Invalid Menu ID** ```json { "error": "Menu not found", "message": "The specified menu_id does not exist for this store" } ``` **Time Validation Errors** ```json { "error": "Invalid time range", "message": "Opening time must be before closing time", "field": "menu_hours[0]" } ``` **Conflicting Default Menus** ```json { "error": "Multiple default menus", "message": "Cannot set multiple menus as default for the same store" } ``` **Missing Required Fields** ```json { "error": "Validation failed", "message": "menu_name is required", "field": "menu_name" } ``` **Data Overwrite**: Upsert operations can overwrite existing menu configurations. Ensure you include all desired menu hours in the request, as missing entries may be removed. ### Best Practices **Data Preparation** * Always retrieve current menu configuration before updating * Include existing IDs to preserve data relationships * Validate time ranges before submitting requests * Test complex schedules in staging environment **Error Prevention** * Check for time conflicts before submitting * Validate day\_of\_week values are within range * Ensure only one menu per store is set as default * Handle timezone considerations for multi-location businesses **Performance Optimization** * Batch multiple menu updates when possible * Use existing IDs to minimize database operations * Consider the impact of frequent menu changes on customer experience * Implement proper error handling and retry logic **Audit and Compliance** * Track who makes menu changes and when * Maintain history of menu modifications * Document business justification for schedule changes * Review menu performance after updates # Accept Incoming Order Source: https://developer.lulacommerce.com/api-reference/orders/accept-incoming-order PUT {{orders_api_base_url}}/orders/accept/ Accept an incoming order from a delivery service platform and initiate the fulfillment process. This endpoint allows stores to formally accept incoming orders from delivery platforms like DoorDash, UberEats, and Grub Hub. Accepting an order initiates the fulfillment workflow and notifies the delivery platform that the order is being processed. Once an order is accepted, it cannot be rejected through normal processes. Use the cancel order endpoint if you need to cancel after acceptance. ### Request Body The unique identifier of the store accepting the order The unique identifier of the order to accept Estimated time when the order will be ready for pickup/delivery (ISO 8601 format) Additional notes about the order preparation or any special considerations ### Response Indicates whether the order was successfully accepted Confirmation message or error details The accepted order's unique identifier New order status after acceptance (typically "accepted" or "in\_progress") Confirmed estimated ready time (if provided) Unique identifier for the fulfillment tracking record created ### Request Example ```json { "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "order_id": "35d18f08-6d54-421d-9476-8cef629111bc", "estimated_ready_time": "2024-01-15T14:30:00Z", "special_notes": "Extra care required for fragile items" } ``` ### Response Example ```json { "success": true, "message": "Order successfully accepted and fulfillment initiated", "order_id": "35d18f08-6d54-421d-9476-8cef629111bc", "status": "accepted", "estimated_ready_time": "2024-01-15T14:30:00Z", "fulfillment_id": "f60a1ebf-c9fd-4c5a-b25f-db5f59e03851" } ``` When an order is accepted, the following happens automatically: 1. **Status Update**: Order status changes from "pending" to "accepted" 2. **Platform Notification**: The delivery platform (DoorDash, UberEats, etc.) is notified 3. **Fulfillment Creation**: A new fulfillment record is created for tracking 4. **Timer Start**: Preparation timer begins for performance metrics 5. **Inventory Hold**: Items are reserved in inventory (if applicable) 6. **Staff Notification**: Kitchen/preparation staff are notified of new order **Time Sensitive**: Orders typically have acceptance windows (usually 10-15 minutes). Failing to accept within this window may result in automatic cancellation by the delivery platform. **Best Practice**: Always provide realistic estimated\_ready\_time values. Accurate timing improves customer satisfaction and delivery platform ratings. If you don't provide an estimated\_ready\_time, the system will calculate one based on your store's historical preparation times and current order volume. ### Error Responses **Order Already Processed** ```json { "success": false, "message": "Order has already been accepted or is no longer available", "error_code": "ORDER_ALREADY_PROCESSED" } ``` **Invalid Store** ```json { "success": false, "message": "Store not authorized to accept this order", "error_code": "UNAUTHORIZED_STORE" } ``` **Acceptance Window Expired** ```json { "success": false, "message": "Order acceptance window has expired", "error_code": "ACCEPTANCE_EXPIRED" } ``` # Cancel Order Source: https://developer.lulacommerce.com/api-reference/orders/cancel-order POST {{orders_api_base_url}}/orders/cancel/ Cancel an order and handle refunds, inventory adjustments, and platform notifications automatically. This endpoint cancels an order regardless of its current status and handles all necessary cleanup including customer notifications, refunds, inventory adjustments, and delivery platform communications. Canceling orders frequently can negatively impact your store's rating on delivery platforms. Use this endpoint judiciously and consider alternative solutions when possible. ### Request Body The unique identifier of the store canceling the order The unique identifier of the order to cancel Reason for cancellation. Must be one of the predefined reason codes. Additional details about the cancellation reason Employee ID who initiated the cancellation ### Cancellation Reason Codes **Store-Related Reasons:** * `OUT_OF_STOCK` - Required items are not available * `KITCHEN_CLOSED` - Kitchen is closed or unable to prepare * `EQUIPMENT_FAILURE` - Equipment malfunction preventing preparation * `STAFF_SHORTAGE` - Insufficient staff to fulfill order * `STORE_EMERGENCY` - Emergency situation at store **Customer-Related Reasons:** * `CUSTOMER_REQUEST` - Customer requested cancellation * `PAYMENT_ISSUE` - Payment could not be processed * `DELIVERY_ADDRESS_ISSUE` - Delivery address problems **Platform-Related Reasons:** * `PLATFORM_ERROR` - Technical issue with delivery platform * `DUPLICATE_ORDER` - Order was duplicated in system * `FRAUD_SUSPECTED` - Suspected fraudulent order **Other Reasons:** * `WEATHER_RELATED` - Severe weather preventing fulfillment * `OTHER` - Other reason (requires description) ### Response Indicates whether the order was successfully canceled Confirmation message or error details The canceled order's unique identifier Unique identifier for the cancellation record Amount that will be refunded to customer Status of the refund process Whether the delivery platform was successfully notified Whether the customer was successfully notified ### Request Example ```json { "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "order_id": "35d18f08-6d54-421d-9476-8cef629111bc", "reason": "OUT_OF_STOCK", "description": "Main ingredient not available due to supply chain issue", "initiated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8" } ``` ### Response Example ```json { "success": true, "message": "Order successfully canceled and all parties notified", "order_id": "35d18f08-6d54-421d-9476-8cef629111bc", "cancellation_id": "c4f2d9e8-1a3b-4c5d-8e9f-2a3b4c5d6e7f", "refund_amount": "41.02", "refund_status": "processing", "platform_notified": true, "customer_notified": true } ``` When an order is canceled, the following automated processes occur: 1. **Order Status Update**: Status changed to "canceled" 2. **Inventory Release**: Any reserved inventory is released back to available stock 3. **Refund Initiation**: Automatic refund processing begins 4. **Platform Notification**: Delivery platform is notified with reason 5. **Customer Notification**: Customer receives cancellation notification 6. **Analytics Update**: Cancellation metrics are updated for reporting 7. **Audit Trail**: Complete cancellation record is created for compliance **Refund Timing**: Refunds typically process within 3-5 business days, but the exact timing depends on the customer's payment method and the delivery platform's policies. **Best Practice**: When possible, contact the customer directly before canceling to explore alternatives or explain the situation. This can help maintain customer satisfaction even in difficult situations. ### Error Responses **Order Cannot Be Canceled** ```json { "success": false, "message": "Order is already completed and cannot be canceled", "error_code": "ORDER_NOT_CANCELABLE" } ``` **Invalid Reason Code** ```json { "success": false, "message": "Invalid cancellation reason provided", "error_code": "INVALID_REASON" } ``` **Platform Communication Failed** ```json { "success": true, "message": "Order canceled but platform notification failed", "order_id": "35d18f08-6d54-421d-9476-8cef629111bc", "platform_notified": false, "warning": "Manual platform notification may be required" } ``` **Manual Follow-up**: If platform\_notified is false, you may need to manually notify the delivery platform to avoid fulfillment conflicts. # Create New Order Source: https://developer.lulacommerce.com/api-reference/orders/create-new-order POST {{orders_api_base_url}}/orders/create/ Create a new order manually through the system, typically for in-store purchases, phone orders, or direct customer orders. This endpoint allows stores to create new orders directly in the system, bypassing delivery platforms. This is useful for in-store purchases, phone orders, catering orders, or any direct customer transactions. This endpoint creates orders that are immediately available for fulfillment and can be integrated with your existing POS system or used for direct customer service. ### Request Body The unique identifier of the store creating the order Customer information for the order Customer's full name Customer's contact phone number Customer's email address Delivery address (required if order\_type is "delivery") Street address City State or province ZIP or postal code Apartment or unit number Special delivery instructions Array of items to include in the order Unique identifier of the product/item Quantity of this item to order Special preparation instructions for this item Array of modifier IDs and values (e.g., size, extras, customizations) Type of order: "pickup", "delivery", "dine\_in" Source platform (defaults to "LulaDirect" for manual orders) Payment method: "cash", "card", "online", "corporate\_account" General order-level special instructions Scheduled pickup/delivery time (ISO 8601 format). If not provided, order is for immediate fulfillment Employee ID who created the order ### Response Indicates whether the order was successfully created Confirmation message or error details Complete order object with all calculated values Unique order identifier Human-readable order number for customer reference Order subtotal before taxes and fees Calculated tax amount Final total price including all fees and taxes Initial order status (typically "pending" or "confirmed") Estimated time when order will be ready Order creation timestamp Unique identifier for fulfillment tracking ### Request Example ```json { "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "customer": { "customer_name": "John Smith", "contact_phone": "+1 555-123-4567", "email": "john.smith@email.com", "delivery_address": { "street": "123 Main Street", "city": "Chicago", "state": "IL", "zip_code": "60601", "apartment": "Apt 4B", "delivery_instructions": "Ring doorbell twice" } }, "order_items": [ { "item_id": "prod_12345", "quantity": 2, "special_instructions": "Extra hot", "modifiers": [ { "modifier_id": "size_large", "value": "Large" } ] }, { "item_id": "prod_67890", "quantity": 1, "special_instructions": "No ice" } ], "order_type": "delivery", "partner": "LulaDirect", "payment_method": "card", "special_instructions": "Please call when arriving", "scheduled_time": "2024-01-15T18:30:00Z", "created_by": "emp_abc123" } ``` ### Response Example ```json { "success": true, "message": "Order successfully created and added to fulfillment queue", "order": { "id": "ord_new_123456", "order_number": "LD-2024-001234", "subtotal": "28.50", "tax_amount": "2.28", "total_price": "30.78", "status": "confirmed", "estimated_ready_time": "2024-01-15T18:30:00Z", "createdAt": "2024-01-15T17:45:00Z", "fulfillment_id": "ful_abc789", "customer": { "customer_name": "John Smith", "contact_phone": "+1 555-123-4567", "email": "john.smith@email.com" }, "order_items": [ { "id": "oi_item1", "item_name": "Large Coffee", "quantity": 2, "unit_price": "4.50", "total_price": "9.00", "special_instructions": "Extra hot" }, { "id": "oi_item2", "item_name": "Iced Tea", "quantity": 1, "unit_price": "3.25", "total_price": "3.25", "special_instructions": "No ice" } ] } } ``` When an order is created, the following processes occur automatically: 1. **Inventory Check**: Verify item availability 2. **Price Calculation**: Calculate subtotal, taxes, and total 3. **Order Number Generation**: Create unique customer-facing order number 4. **Fulfillment Creation**: Initialize fulfillment tracking 5. **Kitchen Notification**: Alert preparation staff (if applicable) 6. **Customer Notification**: Send confirmation (if email provided) 7. **Payment Hold**: Initiate payment processing (for card payments) **Order Numbers**: The system generates human-readable order numbers (e.g., "LD-2024-001234") for customer reference, separate from the internal UUID. **Scheduled Orders**: Use the scheduled\_time parameter for advance orders. The order will automatically enter the fulfillment queue at the appropriate time. ### Error Responses **Item Not Available** ```json { "success": false, "message": "One or more items are not available", "error_code": "ITEM_UNAVAILABLE", "unavailable_items": ["prod_12345"] } ``` **Invalid Address (for delivery orders)** ```json { "success": false, "message": "Delivery address is outside service area", "error_code": "INVALID_DELIVERY_ADDRESS" } ``` **Payment Processing Error** ```json { "success": false, "message": "Payment method could not be processed", "error_code": "PAYMENT_FAILED" } ``` **Payment Processing**: For card payments, ensure your payment processor is configured correctly. Failed payment processing will prevent order creation. ### Use Cases **Phone Orders** * Customer calls to place order * Staff member creates order in system * Customer pays on pickup/delivery **In-Store Purchases** * Walk-in customer orders * Immediate or scheduled preparation * Integration with POS system **Catering Orders** * Large scheduled orders * Corporate accounts * Advance preparation planning **Special Events** * Pre-orders for events * Bulk order management * Custom pricing arrangements # Get Incoming Orders Source: https://developer.lulacommerce.com/api-reference/orders/get-incoming-orders GET {{orders_api_base_url}}/orders/ Retrieve incoming orders for a specific store that are waiting for processing. This endpoint returns orders with their complete details including customer information, items, and fulfillment status. This endpoint retrieves all incoming orders for a specified store. It includes comprehensive order details, customer information, order items, and fulfillment tracking information. Incoming orders represent new orders that have been received from delivery platforms and are waiting for store confirmation and processing. ### Query Parameters The unique identifier of the store to retrieve orders for Filter orders by status. Common values: "incoming", "accepted", "completed", "cancelled" ### Response Array of order objects with complete details Unique order identifier Order subtotal before taxes and fees Tax amount for the order Applied discount amount (null if no discount) Total order price including tax Order creation timestamp Delivery platform name (e.g., "DoorDash", "UberEats") Customer-provided special instructions Store identifier for this order Delivery platform's order number Customer information Customer's name Customer's phone number Phone country code (null if not provided) Array of fulfillment tracking information Fulfillment identifier Timestamp when order was marked ready Estimated delivery time Current delivery status Array of status change logs with timestamps and employee information Array of items in the order Order item identifier Quantity ordered Item-specific instructions Price per item Total price for this item Product name Product description Product category Complete item details including images, categories, and store item variations ### Response Example ```json [ { "id": "8f40ba13-3290-496c-b08c-50e3110200d5", "original_subtotal": "393.00", "tax_amount": "9.77", "discount": null, "original_price": "393.13", "createdAt": "2023-05-24T18:15:24.638Z", "partner": "DoorDash", "special_instructions": "", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "customer": { "customer_name": "Lula D", "contact_phone": "8559731040", "phone_code": null }, "fulfillments": [ { "id": "5afe3291-c252-4e20-94f7-71d9c3587484", "date_ready": "2023-05-24T18:18:26.992Z", "estimated_date_delivered": "2023-05-24T18:31:14.618Z", "fulfillmentStatus": { "delivery_status_name": "completed" }, "fulfillmentsLogs": [ { "date_created": "2023-05-24T18:15:24.722Z", "description": "DoorDash store mock order received", "order_status_title": "Order received", "employee": null } ] } ], "orderItems": [ { "id": "77aab9bd-5543-4783-8e37-d2e9a29a00cf", "quantity": 3, "store_item_price": "100.00", "store_item_total_price": "300.00", "store_item_name": "Test 123", "store_item_category": "Candy" } ] } ] ``` Use this endpoint to build real-time order dashboards and notify staff when new orders arrive. The fulfillments array contains detailed tracking information showing the complete order journey from receipt to delivery. # Get Order Details Source: https://developer.lulacommerce.com/api-reference/orders/get-order-details GET {{orders_api_base_url}}/orders/details/ Retrieve comprehensive details for a specific order including all items, customer information, fulfillment history, and complete order tracking. This endpoint provides complete details for a specific order, including comprehensive item information, customer details, full fulfillment tracking, and detailed order history. This is ideal for order investigation, customer service, and detailed order management. This endpoint returns the most comprehensive order information available, including complete fulfillment logs and detailed item specifications. ### Query Parameters The unique identifier of the store The unique identifier of the order to retrieve details for ### Response Complete order object with all details Unique order identifier Order subtotal before taxes and fees Tax amount applied to the order Discount amount (null if no discount applied) Original total price Current order price (may differ from original if modified) Final price after all modifications Order creation timestamp Delivery service platform name Customer-provided special instructions Allergen exclusion requests Whether to include disposable items Store processing this order External order reference ID Delivery platform's order number Complete customer information Customer's full name Customer's contact phone number Phone country code Complete fulfillment tracking information Fulfillment tracking ID Items quantity (if applicable) Timestamp when order was marked ready Fulfillment creation timestamp Estimated delivery time Current delivery status Complete history of all status changes with employee information and timestamps Detailed information for each item in the order Order item identifier Quantity ordered Item-specific instructions Price per item Total price for this item Product name Product description Product category Complete product information including images, UPC, categories, and variations ### Response Example ```json { "id": "35d18f08-6d54-421d-9476-8cef629111bc", "original_subtotal": "41.00", "tax_amount": "0.02", "discount": null, "original_price": "41.02", "price": "0.20", "final_price": "0.20", "createdAt": "2023-03-08T12:25:07.433Z", "partner": "UberEats", "special_instructions": "Packing should be good.", "exclude_allergens_items": null, "is_include_disposables": false, "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "order_id": "b40e29e9-3933-4aa4-8504-66278396955a", "dsp_order_number": "", "customer": { "customer_name": "Lula D.", "contact_phone": "+1 312-766-6835", "phone_code": null }, "fulfillments": [ { "id": "f60a1ebf-c9fd-4c5a-b25f-db5f59e03851", "quantity": null, "date_ready": "2023-04-04T22:10:33.233Z", "createdAt": "2023-03-08T12:25:10.551Z", "estimated_date_delivered": "2023-03-08T12:25:10.246Z", "fulfillmentStatus": { "delivery_status_name": "denied" }, "fulfillmentsLogs": [ { "date_created": "2023-03-08T12:25:10.861Z", "description": "UberEats store mock order received", "order_status_title": "Order received", "employee": { "id": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "first_name": "Philip Tribe", "last_name": "LA" } } ] } ], "orderItems": [ { "id": "7fbe2819-5bc6-4340-8dfe-a5605272a32b", "quantity": 1, "special_instructions": "Cancel this order if this item is not available.", "store_item_price": "1.00", "store_item_total_price": "1.00", "store_item_name": "Jumbo Ring Pop - 1", "store_item_description": "Jumbo Ring Pop", "store_item_category": "Others", "item": { "images": [""], "name": "Jumbo Ring Pop", "description": "Jumbo Ring Pop", "upc": "4111626331", "categories": [ { "id": "12bd6794-a17a-48a2-9a14-64c44a20c232", "name": "Others" } ] } } ] } ``` Use this endpoint for customer service inquiries, order investigations, and when you need complete order context for decision-making. The fulfillmentsLogs provide a complete audit trail showing exactly what happened to the order and when, including which employee performed each action. Notice that price differences between original\_price and final\_price may indicate order modifications or issues that required price adjustments. # Get Orders Count Source: https://developer.lulacommerce.com/api-reference/orders/get-orders-count GET {{orders_api_base_url}}/orders/counts/ Retrieve the count of orders by status for a specific store, providing a quick overview of active and completed order volumes. This endpoint provides a summary count of orders grouped by their status, giving you immediate visibility into order volume and distribution. This is particularly useful for dashboard displays and operational monitoring. Use this endpoint to quickly assess store workload and monitor business performance without retrieving detailed order data. ### Query Parameters The unique identifier of the store to get order counts for ### Response Object containing counts for different order statuses Total number of active orders (incoming, accepted, preparing, ready, etc.) Total number of completed/delivered orders ### Response Example ```json { "active": 123, "completed": 1 } ``` ## Use Cases ### Dashboard Widgets Create real-time dashboard displays showing: * Current active order volume * Completed orders for the day/period * Order processing capacity ### Performance Monitoring Track key metrics: * **Active Orders**: Monitor current workload and identify peak times * **Completed Orders**: Measure daily/weekly performance and revenue impact * **Order Velocity**: Calculate completion rates and processing efficiency ### Staff Management Use counts to: * Determine staffing needs during peak hours * Identify when additional help is needed * Monitor order processing capacity ### Business Intelligence Analyze patterns: * Peak order times for scheduling optimization * Daily/weekly volume trends * Capacity planning for busy periods Poll this endpoint regularly to create real-time monitoring dashboards that help staff understand current workload and prioritize tasks. The "active" count includes all orders that require attention or are in progress, while "completed" represents successfully fulfilled orders. High active order counts may indicate processing bottlenecks or the need for additional staff during peak periods. # Get Orders History Source: https://developer.lulacommerce.com/api-reference/orders/get-orders-history GET {{orders_api_base_url}}/orders/history/ Retrieve comprehensive historical order data with advanced analytics, reporting capabilities, and detailed performance metrics. This endpoint provides access to comprehensive historical order data with powerful analytics capabilities. Ideal for business intelligence, performance reporting, trend analysis, and strategic planning. This endpoint includes advanced analytics features like trend calculations, performance metrics, and comparative analysis across different time periods. ### Query Parameters The unique identifier of the store whose order history you want to retrieve Start date for historical data retrieval (ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ) End date for historical data retrieval (ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ) Data aggregation level: "hourly", "daily", "weekly", "monthly" Whether to include advanced analytics and performance metrics Include comparison with the previous equivalent period Filter by specific delivery platform for focused analysis Include detailed item-level analytics in the response ### Response High-level summary for the requested time period Start date of the period End date of the period Total number of orders Total revenue generated Average order value Percentage of orders completed successfully Percentage of orders canceled Data points broken down by the specified granularity Time period identifier Number of orders in this period Revenue for this period Average order value for this period Completion rate for this period Busiest hour in this period (if granularity allows) Performance breakdown by delivery platform Performance metrics for UberEats orders Performance metrics for DoorDash orders Performance metrics for GrubHub orders Performance metrics for LulaDirect orders Advanced analytics and insights (when include\_analytics=true) Order volume and revenue growth trends Identified seasonal patterns and recommendations Key performance indicators and benchmarks AI-generated insights and recommendations for improvement Comparison with previous period (when compare\_period=true) Summary of the previous equivalent period Growth percentages and changes Analysis of trends between periods ### Response Example ```json { "period_summary": { "date_from": "2024-01-01T00:00:00Z", "date_to": "2024-01-31T23:59:59Z", "total_orders": 1247, "total_revenue": "64,859.75", "average_order_value": "52.03", "completion_rate": 94.5, "cancellation_rate": 3.2 }, "time_series_data": [ { "period": "2024-01-01", "orders_count": 45, "revenue": "2,341.25", "average_order_value": "52.03", "completion_rate": 96.0, "peak_hour": "19:00" }, { "period": "2024-01-02", "orders_count": 38, "revenue": "1,977.50", "average_order_value": "52.04", "completion_rate": 95.0, "peak_hour": "18:30" } ], "partner_performance": { "UberEats": { "total_orders": 485, "total_revenue": "25,243.80", "average_order_value": "52.05", "completion_rate": 95.2, "average_prep_time": "18.5 minutes" }, "DoorDash": { "total_orders": 412, "total_revenue": "21,424.20", "average_order_value": "52.01", "completion_rate": 94.8, "average_prep_time": "17.2 minutes" }, "GrubHub": { "total_orders": 245, "total_revenue": "12,745.50", "average_order_value": "52.02", "completion_rate": 93.5, "average_prep_time": "19.8 minutes" }, "LulaDirect": { "total_orders": 105, "total_revenue": "5,446.25", "average_order_value": "51.87", "completion_rate": 96.8, "average_prep_time": "15.3 minutes" } }, "analytics": { "growth_trends": { "monthly_growth": "+12.5%", "revenue_trend": "increasing", "order_volume_trend": "stable_growth" }, "seasonal_patterns": { "peak_days": ["Friday", "Saturday", "Sunday"], "peak_hours": ["17:00-21:00"], "seasonal_recommendations": "Consider extended hours on weekends" }, "performance_indicators": { "efficiency_score": 87.5, "customer_satisfaction_proxy": 94.5, "revenue_per_hour": "$425.30" }, "recommendations": [ "Consider promoting during Tuesday-Thursday slow periods", "UberEats partnership showing strongest performance", "Weekend capacity could be increased to capture more demand" ] }, "comparison": { "previous_period": { "total_orders": 1098, "total_revenue": "57,241.50", "average_order_value": "52.14" }, "growth_metrics": { "order_growth": "+13.6%", "revenue_growth": "+13.3%", "avg_order_value_change": "-0.2%" }, "trend_analysis": "Strong growth in order volume and revenue with stable order values, indicating successful customer acquisition and retention" } } ``` **Hourly Analysis (for operational optimization)** ``` GET {{orders_api_base_url}}/orders/history/?store_id=449235c1-3d04-4519-998b-40d2a621e5e0&date_from=2024-01-15T00:00:00Z&date_to=2024-01-15T23:59:59Z&granularity=hourly ``` **Weekly Trends (for strategic planning)** ``` GET {{orders_api_base_url}}/orders/history/?store_id=449235c1-3d04-4519-998b-40d2a621e5e0&date_from=2024-01-01T00:00:00Z&date_to=2024-03-31T23:59:59Z&granularity=weekly&compare_period=true ``` **Monthly Performance Review** ``` GET {{orders_api_base_url}}/orders/history/?store_id=449235c1-3d04-4519-998b-40d2a621e5e0&date_from=2024-01-01T00:00:00Z&date_to=2024-12-31T23:59:59Z&granularity=monthly&include_analytics=true ``` **Business Intelligence**: Use the analytics data to identify growth opportunities, optimize operations, and make data-driven decisions about staffing, inventory, and marketing. **Data Freshness**: Historical data is updated in near real-time. For the most current hour's data, allow 15-30 minutes for complete processing. **Large Datasets**: When requesting large date ranges with hourly granularity, responses may be substantial. Consider using daily or weekly granularity for broad analysis. ### Use Cases **Revenue Analysis** * Monthly/quarterly revenue trends * Platform performance comparison * Seasonal revenue patterns **Operational Optimization** * Identify peak hours for staffing * Optimize kitchen capacity planning * Improve order completion rates **Strategic Planning** * Market penetration analysis * Growth opportunity identification * Partnership performance evaluation **Performance Monitoring** * KPI tracking and benchmarking * Efficiency improvement initiatives * Customer satisfaction analysis # Get Store Orders Source: https://developer.lulacommerce.com/api-reference/orders/get-store-orders GET {{micro_service_base_url}}/orders/ Retrieve all orders for a specific store with flexible filtering options including date ranges, status, and pagination. This endpoint provides comprehensive access to all orders for a specific store with powerful filtering capabilities. Perfect for store management, reporting, and operational oversight. This endpoint supports advanced filtering and pagination to efficiently handle large volumes of order data while providing flexible search capabilities. ### Query Parameters The unique identifier of the store whose orders you want to retrieve Filter orders by status (e.g., "pending", "accepted", "in\_progress", "completed", "canceled") Filter by delivery platform (e.g., "DoorDash", "UberEats", "GrubHub", "LulaDirect") Start date for filtering orders (ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ) End date for filtering orders (ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ) Page number for pagination Number of orders per page (max 100) Field to sort by ("createdAt", "price", "status", "partner") Sort direction ("asc" or "desc") ### Response Array of order objects matching the filter criteria Unique order identifier Order subtotal before taxes and fees Tax amount applied to the order Discount amount (null if no discount applied) Original total price Current order price Final price after all modifications Order creation timestamp Delivery service platform name Current order status Customer-provided special instructions Customer information including name and contact details Fulfillment tracking information Summary of items in the order Pagination information for the response Current page number Total number of pages available Total number of orders matching the criteria Number of orders in this page Whether there are more pages available Whether there are previous pages available Summary statistics for the filtered orders Total revenue from filtered orders Average order value Count of orders by status Count of orders by delivery platform ### Response Example ```json { "orders": [ { "id": "35d18f08-6d54-421d-9476-8cef629111bc", "original_subtotal": "41.00", "tax_amount": "0.02", "discount": null, "original_price": "41.02", "price": "0.20", "final_price": "0.20", "createdAt": "2023-03-08T12:25:07.433Z", "partner": "UberEats", "status": "completed", "special_instructions": "Packing should be good.", "customer": { "customer_name": "Lula D.", "contact_phone": "+1 312-766-6835" }, "fulfillments": [ { "id": "f60a1ebf-c9fd-4c5a-b25f-db5f59e03851", "status": "delivered", "date_ready": "2023-04-04T22:10:33.233Z" } ], "orderItems": [ { "id": "7fbe2819-5bc6-4340-8dfe-a5605272a32b", "quantity": 1, "store_item_name": "Jumbo Ring Pop - 1", "store_item_total_price": "1.00" } ] } ], "pagination": { "current_page": 1, "total_pages": 5, "total_orders": 247, "orders_per_page": 50, "has_next_page": true, "has_previous_page": false }, "summary": { "total_revenue": "12,847.50", "average_order_value": "52.03", "status_breakdown": { "completed": 198, "in_progress": 15, "pending": 8, "canceled": 26 }, "partner_breakdown": { "UberEats": 95, "DoorDash": 87, "GrubHub": 45, "LulaDirect": 20 } } } ``` **Get Today's Orders** ``` GET {{micro_service_base_url}}/orders/?store_id=449235c1-3d04-4519-998b-40d2a621e5e0&date_from=2024-01-15T00:00:00Z&date_to=2024-01-15T23:59:59Z ``` **Get Pending Orders from UberEats** ``` GET {{micro_service_base_url}}/orders/?store_id=449235c1-3d04-4519-998b-40d2a621e5e0&status=pending&partner=UberEats ``` **Get Last Week's Completed Orders** ``` GET {{micro_service_base_url}}/orders/?store_id=449235c1-3d04-4519-998b-40d2a621e5e0&status=completed&date_from=2024-01-08T00:00:00Z&date_to=2024-01-14T23:59:59Z ``` **Performance Optimization**: When querying large date ranges, consider using smaller page sizes (limit parameter) and implement pagination to maintain fast response times. **Time Zones**: All timestamps are returned in UTC. Convert to your local timezone as needed for display purposes. **Rate Limiting**: This endpoint is subject to rate limiting. For frequent polling, consider using webhooks or the order count endpoint for basic monitoring. ### Use Cases **Daily Operations Dashboard** * Get today's orders with status filtering * Monitor pending orders requiring attention * Track fulfillment performance **Financial Reporting** * Calculate daily/weekly/monthly revenue * Analyze order value trends * Track performance by delivery platform **Performance Analytics** * Monitor order completion rates * Analyze peak order times * Track customer satisfaction metrics **Inventory Planning** * Review historical order patterns * Identify popular items and trends * Plan inventory based on demand # List All Orders Source: https://developer.lulacommerce.com/api-reference/orders/list-all-orders GET {{micro_service_base_url}}/orders/ Retrieve a comprehensive list of all orders for a specific store with filtering capabilities by status and other criteria. This endpoint provides access to all orders for a specified store, allowing you to filter by various criteria such as order status. It returns the same detailed order information as the incoming orders endpoint but with broader filtering options. This endpoint is ideal for building comprehensive order management dashboards and reporting systems. ### Query Parameters Filter orders by their current status * **incoming**: New orders waiting for acceptance * **accepted**: Orders confirmed by store * **preparing**: Orders being prepared * **ready**: Orders ready for pickup * **completed**: Successfully delivered orders * **cancelled**: Cancelled orders * **denied**: Orders rejected by store The unique identifier of the store to retrieve orders for ### Response Array of order objects matching the specified criteria Unique order identifier Order subtotal before taxes and additional fees Total tax applied to the order Discount amount applied (null if no discount) Final order total including all fees and taxes Timestamp when the order was created Name of the delivery service platform Customer-provided special instructions for the order Allergen exclusion requests (null if none) Whether disposable items should be included Store identifier processing this order Order number from the delivery service platform Customer contact and identification information Complete fulfillment tracking with status logs and employee actions Detailed list of all items in the order with pricing and specifications ### Response Example ```json [ { "id": "8f40ba13-3290-496c-b08c-50e3110200d5", "original_subtotal": "393.00", "tax_amount": "9.77", "discount": null, "original_price": "393.13", "createdAt": "2023-05-24T18:15:24.638Z", "partner": "DoorDash", "special_instructions": "", "exclude_allergens_items": null, "is_include_disposables": null, "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "dsp_order_number": "", "customer": { "customer_name": "Lula D", "contact_phone": "8559731040", "phone_code": null }, "fulfillments": [ { "quantity": null, "date_ready": "2023-05-24T18:18:26.992Z", "createdAt": "2023-05-24T18:15:24.715Z", "estimated_date_delivered": "2023-05-24T18:31:14.618Z", "id": "5afe3291-c252-4e20-94f7-71d9c3587484", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "fulfillmentStatus": { "delivery_status_name": "completed" }, "fulfillmentsLogs": [ { "date_created": "2023-05-24T18:15:24.722Z", "description": "DoorDash store mock order received", "order_status_title": "Order received", "fulfillments_id": "5afe3291-c252-4e20-94f7-71d9c3587484", "employee": null }, { "date_created": "2023-05-24T18:16:14.685Z", "description": "", "order_status_title": "Bagging order", "fulfillments_id": "5afe3291-c252-4e20-94f7-71d9c3587484", "employee": { "id": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "first_name": "Philip T", "last_name": "white house " } } ] } ], "orderItems": [ { "id": "77aab9bd-5543-4783-8e37-d2e9a29a00cf", "quantity": 3, "special_instructions": "", "store_item_price": "100.00", "store_item_total_price": "300.00", "store_item_name": "Test 123", "store_item_description": "", "store_item_category": "Candy", "item": { "images": null, "name": "Test 123", "description": "", "upc": null, "categories": [ { "id": "3c185006-271c-4d1e-903f-de21ec3b4234", "name": "Alcohol" } ] } } ] } ] ``` Use different status filters to create targeted views for different operational needs - "incoming" for new order alerts, "completed" for revenue tracking. The fulfillmentsLogs array provides a complete audit trail of all actions taken on the order, including which employee performed each action. Large date ranges with no status filtering may return substantial amounts of data. Consider implementing pagination for high-volume stores. # Create Order Issue Source: https://developer.lulacommerce.com/api-reference/orders/order-issues/create-order-issue POST {{micro_service_base_url}}/orders/{{order_id}}/issues Create a new issue report for an order, documenting problems, complaints, or special situations that require attention. This endpoint allows you to create detailed issue reports for orders when problems occur. Issues can range from missing items and wrong products to delivery problems and customer complaints. Each issue is tracked with priority levels, attachments, and resolution workflows. Issue tracking helps maintain service quality, resolve customer problems efficiently, and identify patterns that can improve operations. ### Path Parameters The unique identifier of the order where the issue occurred ### Request Body The unique identifier of the store where the issue occurred Employee ID or user ID of the person reporting the issue Detailed issue information ID of the specific order item related to the issue (if applicable) Type of issue: "wrong\_items", "missing\_items", "damaged\_items", "delivery\_issue", "payment\_issue", "customer\_complaint", "quality\_issue", "other" Detailed description of the issue Issue priority level: "low", "medium", "high", "critical" Array of URLs pointing to images, documents, or other evidence related to the issue Whether the customer has been contacted about this issue Expected time to resolve the issue (ISO 8601 format) ### Response Indicates whether the issue was successfully created Confirmation message or error details Unique identifier for the created issue Human-readable issue number for reference Initial issue status (typically "open" or "investigating") Timestamp when the issue was created Employee or team assigned to handle the issue ### Request Example ```json { "storeId": "449235c1-3d04-4519-998b-40d2a621e5e0", "reportedBy": "b1e46bf5-0e29-4c7e-8ca1-0d7407c67169", "issue": { "order_item_id": "d2fe3e81-fb54-4d90-9c45-b0f3ed9ed1f1", "issue_type": "wrong_items", "description": "I ordered the DARK chocolate Muddy Bites and the 10oz bag of Peach Rings, but received milk chocolate and gummy bears instead", "priority": "medium", "attachments": [ "https://lula-inventory-service-staging.s3.amazonaws.com/images/dad46dc1-6d6f-4a8f-9602-29f2f5c1231d/Candy/29b4ef50-eeb3-40cb-a04f-112e187fd06a_1732713277583.webp" ], "customer_contacted": true, "expected_resolution_time": "2024-01-15T18:00:00Z" } } ``` ### Response Example ```json { "success": true, "message": "Issue successfully created and assigned for resolution", "issue_id": "issue_123456789", "issue_number": "ISS-2024-001234", "status": "open", "created_at": "2024-01-15T14:30:00Z", "assigned_to": "customer_service_team" } ``` **Issue Types:** * **wrong\_items**: Customer received different items than ordered * **missing\_items**: Items were missing from the order * **damaged\_items**: Items arrived damaged or in poor condition * **delivery\_issue**: Problems with delivery process or timing * **payment\_issue**: Payment processing or billing problems * **customer\_complaint**: General customer dissatisfaction * **quality\_issue**: Product quality below standards * **other**: Issues not covered by other categories **Priority Levels:** * **low**: Minor issues that don't significantly impact customer experience * **medium**: Moderate issues requiring timely resolution * **high**: Serious issues that significantly impact customer satisfaction * **critical**: Urgent issues requiring immediate attention (safety, major losses) **Automatic Assignment**: Issues are automatically assigned to appropriate teams based on issue type and priority. High and critical priority issues trigger immediate notifications. **Evidence Collection**: Always include attachments when possible. Photos and documentation help resolve issues faster and provide valuable feedback for process improvement. ### Issue Creation Workflow 1. **Issue Registration**: Issue is assigned a unique ID and tracking number 2. **Priority Assessment**: System evaluates priority and determines urgency 3. **Team Assignment**: Issue is routed to appropriate resolution team 4. **Customer Notification**: Customer is informed if customer\_contacted is true 5. **Escalation Setup**: Automatic escalation timers are set based on priority 6. **Audit Trail**: Complete tracking begins for resolution monitoring 7. **Analytics Update**: Issue data is added to quality metrics and reporting ### Use Cases **Wrong Items Delivered** * Customer received incorrect products * Include photos of wrong items * Reference specific order items **Missing Items** * Items were missing from delivery * Check against packing list * Verify inventory accuracy **Quality Issues** * Damaged or expired products * Poor product condition * Food safety concerns **Delivery Problems** * Late delivery or wrong address * Driver issues or communication problems * Weather or logistics complications **Customer Complaints** * Service quality issues * Staff behavior concerns * General dissatisfaction ### Error Responses **Invalid Order** ```json { "success": false, "message": "Order not found or not accessible", "error_code": "ORDER_NOT_FOUND", "order_id": "invalid-order-id" } ``` **Invalid Issue Type** ```json { "success": false, "message": "Invalid issue type provided", "error_code": "INVALID_ISSUE_TYPE", "valid_types": ["wrong_items", "missing_items", "damaged_items", "delivery_issue", "payment_issue", "customer_complaint", "quality_issue", "other"] } ``` **Missing Required Fields** ```json { "success": false, "message": "Required fields are missing", "error_code": "MISSING_FIELDS", "missing_fields": ["issue.description", "issue.priority"] } ``` **Invalid Attachment URL** ```json { "success": false, "message": "One or more attachment URLs are invalid", "error_code": "INVALID_ATTACHMENT", "invalid_urls": ["invalid-url-here"] } ``` **Critical Issues**: For critical priority issues involving safety or major financial impact, consider following up with immediate phone or direct communication in addition to creating the issue record. # Update Order Issue Source: https://developer.lulacommerce.com/api-reference/orders/order-issues/update-order-issue PATCH {{micro_service_base_url}}/orders/{{order_id}}/issues/{{issue_id}} Update an existing order issue with resolution notes, status changes, refund information, and other progress updates. This endpoint allows you to update existing order issues as they progress through resolution. You can change status, add resolution notes, process refunds, update priority, and document the complete resolution process. Issue updates maintain a complete audit trail of all changes, ensuring transparency and accountability in the resolution process. ### Path Parameters The unique identifier of the order containing the issue The unique identifier of the issue to update ### Request Body Additional notes or comments about the issue resolution progress Updated priority level: "low", "medium", "high", "critical" Updated issue status: "open", "investigating", "in\_progress", "resolved", "closed", "escalated" Amount to refund to customer (if applicable) Source of refund: "merchant", "platform", "insurance", "store\_credit" Detailed description of how the issue was resolved Whether the customer expressed satisfaction with the resolution Whether additional follow-up is needed Scheduled date for follow-up (ISO 8601 format) Employee ID of person now assigned to handle the issue Employee ID of person making this update ### Response Indicates whether the issue was successfully updated Confirmation message or error details The ID of the updated issue List of fields that were successfully updated Previous status before this update Current status after this update Whether a refund was processed as part of this update Timestamp when the update was applied ### Request Example ```json { "notes": "Customer contacted and confirmed wrong items received. Processing replacement order and refund for inconvenience.", "priority": "medium", "status": "resolved", "refund_amount": 15.50, "refund_source": "merchant", "resolution_description": "Issued full refund for incorrect items and sent replacement order at no charge. Customer very understanding and satisfied with resolution.", "customer_satisfied": true, "follow_up_required": true, "follow_up_date": "2024-01-22T10:00:00Z", "updated_by": "emp_cs_001" } ``` ### Response Example ```json { "success": true, "message": "Issue successfully updated and resolution recorded", "issue_id": "issue_123456789", "updated_fields": [ "notes", "status", "refund_amount", "refund_source", "resolution_description", "customer_satisfied", "follow_up_required", "follow_up_date" ], "previous_status": "investigating", "new_status": "resolved", "refund_processed": true, "timestamp": "2024-01-15T16:45:00Z" } ``` **Status Progression:** 1. **open**: Issue newly created, awaiting initial review 2. **investigating**: Issue under investigation, gathering information 3. **in\_progress**: Active resolution efforts underway 4. **resolved**: Issue resolved, waiting for confirmation 5. **closed**: Issue fully resolved and confirmed 6. **escalated**: Issue escalated to higher authority **Status Change Rules:** * Issues can move forward or backward in the workflow * Certain status changes trigger automatic notifications * Closed issues require manager approval to reopen * Escalated issues follow special handling procedures **Refund Processing**: When refund\_amount is specified, the system initiates the refund process automatically. Processing time depends on the refund\_source and payment method. **Customer Communication**: Always update the issue when you communicate with the customer. This maintains a complete record of all interactions and helps other team members understand the situation. ### Update Tracking When an issue is updated, the system automatically tracks: 1. **Change History**: All field changes with before/after values 2. **User Attribution**: Who made each change and when 3. **Status Timeline**: Complete progression through resolution stages 4. **Communication Log**: Record of all customer interactions 5. **Resolution Metrics**: Time to resolution and satisfaction scores 6. **Pattern Analysis**: Data for identifying recurring issues ### Use Cases **Status Updates** * Move issue through resolution workflow * Track progress and milestones * Communicate current state to stakeholders **Resolution Documentation** * Record final resolution details * Document customer satisfaction * Plan follow-up activities **Refund Processing** * Process partial or full refunds * Track refund sources and amounts * Document financial resolution **Escalation Management** * Escalate complex issues * Reassign to specialists * Update priority based on severity **Quality Improvement** * Add detailed resolution notes * Identify process improvements * Document lessons learned ### Error Responses **Issue Not Found** ```json { "success": false, "message": "Issue not found", "error_code": "ISSUE_NOT_FOUND", "issue_id": "invalid-issue-id" } ``` **Invalid Status Transition** ```json { "success": false, "message": "Invalid status transition", "error_code": "INVALID_STATUS_TRANSITION", "current_status": "closed", "attempted_status": "investigating" } ``` **Refund Processing Error** ```json { "success": false, "message": "Unable to process refund", "error_code": "REFUND_FAILED", "refund_amount": 15.50, "reason": "Payment method no longer valid" } ``` **Permission Denied** ```json { "success": false, "message": "Insufficient permissions to update this issue", "error_code": "PERMISSION_DENIED", "required_role": "customer_service_manager" } ``` **Status Restrictions**: Certain status changes may require manager approval or special permissions. Ensure you have appropriate access before attempting status changes to "closed" or "escalated". ### Field Validation **notes** * Maximum length: 2000 characters * Required when changing status to "resolved" or "closed" * Cannot be empty string **priority** * Must be one of: "low", "medium", "high", "critical" * Critical priority issues trigger immediate notifications * Priority increases require justification in notes **status** * Must follow valid status transition rules * Some transitions require manager approval * Cannot skip required workflow steps **refund\_amount** * Must be positive number * Cannot exceed original order amount * Requires refund\_source when specified **refund\_source** * Must be one of: "merchant", "platform", "insurance", "store\_credit" * Required when refund\_amount is specified * Different sources have different processing times # Get All Order Items Source: https://developer.lulacommerce.com/api-reference/orders/order-items/get-all-order-items GET {{micro_service_base_url}}/orders/{{order_id}}/order-items Retrieve all items within a specific order with complete details, modifications, and fulfillment status for each item. This endpoint returns a comprehensive list of all items within an order. It's ideal for order fulfillment, kitchen display systems, packing lists, and complete order review. This endpoint provides complete item details for all items in an order, making it efficient for bulk operations and comprehensive order management. ### Path Parameters The unique identifier of the order whose items you want to retrieve ### Query Parameters Whether to include detailed modification information for each item Filter items by fulfillment status: "pending", "preparing", "ready", "completed" Filter items by product category ### Response The order identifier these items belong to Total number of items in the order Array of all order items with complete details Unique order item identifier Quantity of this item ordered Item-specific preparation instructions Price per unit for this item Total price for this item (quantity × unit price) Product name as displayed in store Product description Product category classification Current fulfillment status for this item Complete product information including images, UPC, and categories Applied modifications/customizations (when include\_modifications=true) Summary information for the complete order Total quantity of all items Subtotal of all items before taxes Count of items grouped by category Count of items grouped by fulfillment status ### Response Example ```json { "order_id": "35d18f08-6d54-421d-9476-8cef629111bc", "total_items": 2, "items": [ { "id": "7fbe2819-5bc6-4340-8dfe-a5605272a32b", "quantity": 1, "special_instructions": "Cancel this order if this item is not available.", "store_item_price": "1.00", "store_item_total_price": "1.00", "store_item_name": "Jumbo Ring Pop - 1", "store_item_description": "Jumbo Ring Pop", "store_item_category": "Others", "fulfillment_status": "pending", "item": { "images": [ "https://example.com/product-image.jpg" ], "name": "Jumbo Ring Pop", "description": "Jumbo Ring Pop", "upc": "4111626331", "categories": [ { "id": "12bd6794-a17a-48a2-9a14-64c44a20c232", "name": "Others" } ], "subCategories": [], "storeItems": [ { "id": "b7e9d9a6-2e3e-451a-ada9-6c001b17eaa5", "price": "10", "external_id": null, "location": null, "name": "Jumbo Ring Pop - 1", "description": null, "categories": [ { "id": "12bd6794-a17a-48a2-9a14-64c44a20c232", "name": "Others" } ], "subCategories": [] } ] }, "modifications": [] }, { "id": "651daec0-c721-4399-82c8-2ac6afcc1160", "quantity": 4, "special_instructions": "Cancel this order if this item is not available.", "store_item_price": "10.00", "store_item_total_price": "40.00", "store_item_name": "test new item 1", "store_item_description": "", "store_item_category": "Baby", "fulfillment_status": "preparing", "item": { "images": null, "name": "test new item 1", "description": "", "upc": null, "categories": [ { "id": "cef965f2-5a5a-4a30-b166-1350b4c3ff55", "name": "Baby" } ], "subCategories": [ { "id": "4a525cdb-2c2d-4d23-8764-d2c9f3c14142", "name": "For Mom" } ], "storeItems": [ { "id": "cf61e0c0-bff4-42dd-8273-1cbf4f8f5b42", "price": "10.00", "external_id": null, "location": null, "name": "test new item 1", "description": null, "categories": [ { "id": "3c185006-271c-4d1e-903f-de21ec3b4234", "name": "loo" } ], "subCategories": [] } ] }, "modifications": [] } ], "order_summary": { "total_quantity": 5, "subtotal": "41.00", "items_by_category": { "Others": 1, "Baby": 1 }, "items_by_status": { "pending": 1, "preparing": 1 } } } ``` **Get Items by Status** ``` GET {{micro_service_base_url}}/orders/{{order_id}}/order-items?status_filter=pending ``` **Get Items by Category** ``` GET {{micro_service_base_url}}/orders/{{order_id}}/order-items?category_filter=Baby ``` **Get Items Without Modifications** ``` GET {{micro_service_base_url}}/orders/{{order_id}}/order-items?include_modifications=false ``` **Performance Optimization**: When you only need basic item information, set include\_modifications=false to reduce response size and improve performance. **Kitchen Display**: Use status\_filter=pending to show only items that need preparation, perfect for kitchen display systems. ### Use Cases **Order Fulfillment** * Generate complete packing lists * Kitchen preparation workflows * Quality control checklists **Customer Service** * Complete order review with customer * Item substitution discussions * Order modification consultations **Inventory Management** * Track item demand patterns * Monitor category performance * Identify popular product combinations **Reporting & Analytics** * Order composition analysis * Average order value calculations * Product performance metrics ### Error Responses **Order Not Found** ```json { "error": "Order not found", "order_id": "invalid-order-id", "message": "The specified order does not exist" } ``` **No Items Found** ```json { "order_id": "35d18f08-6d54-421d-9476-8cef629111bc", "total_items": 0, "items": [], "message": "No items found matching the specified criteria" } ``` **Access Denied** ```json { "error": "Access denied", "message": "You do not have permission to view this order's items" } ``` **Large Orders**: For orders with many items, consider using pagination or filters to manage response sizes and improve performance. # Get Order Items Source: https://developer.lulacommerce.com/api-reference/orders/order-items/get-order-items GET {{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}} Retrieve detailed information for a specific item within an order including pricing, modifications, and special instructions. This endpoint provides comprehensive details for a specific item within an order. Use this when you need detailed information about a particular order item for customer service, inventory tracking, or fulfillment purposes. This endpoint returns complete item details including product information, pricing breakdown, modifications, and fulfillment status. ### Path Parameters The unique identifier of the order containing the item The unique identifier of the specific order item to retrieve ### Response Unique order item identifier Quantity of this item ordered Item-specific preparation instructions Price per unit for this item Total price for this item (quantity × unit price) Product name as displayed in store Product description Product category classification Item size specification (if applicable) Complete product information Array of product image URLs Official product name Detailed product description Universal Product Code (barcode) Product categories with IDs and names Product subcategories with IDs and names Store-specific product variations and pricing Item modifications or customizations applied Unique modifier identifier Name of the modification Selected modification value Extra cost for this modification Current fulfillment status for this specific item Internal notes for item preparation ### Response Example ```json { "id": "7fbe2819-5bc6-4340-8dfe-a5605272a32b", "quantity": 1, "special_instructions": "Cancel this order if this item is not available.", "store_item_price": "1.00", "store_item_total_price": "1.00", "store_item_name": "Jumbo Ring Pop - 1", "store_item_description": "Jumbo Ring Pop", "store_item_category": "Others", "store_item_size": "1 count", "item": { "images": [ "https://example.com/product-image.jpg" ], "name": "Jumbo Ring Pop", "description": "Jumbo Ring Pop", "upc": "4111626331", "categories": [ { "id": "12bd6794-a17a-48a2-9a14-64c44a20c232", "name": "Others" } ], "subCategories": [], "storeItems": [ { "id": "b7e9d9a6-2e3e-451a-ada9-6c001b17eaa5", "price": "10", "external_id": null, "location": null, "name": "Jumbo Ring Pop - 1", "description": null, "categories": [ { "id": "12bd6794-a17a-48a2-9a14-64c44a20c232", "name": "Others" } ], "subCategories": [] } ] }, "modifications": [ { "modifier_id": "mod_size_large", "modifier_name": "Size", "modifier_value": "Large", "additional_cost": "0.50" } ], "fulfillment_status": "pending", "preparation_notes": "Handle with care - fragile packaging" } ``` **Item Status**: The fulfillment\_status field shows the specific status of this item within the order, which may differ from the overall order status. **Image Handling**: Product images are returned as URLs. Always check if the image URL is valid before displaying to avoid broken image links. ### Error Responses **Order Item Not Found** ```json { "error": "Order item not found", "order_item_id": "invalid-item-id", "message": "The specified order item does not exist in this order" } ``` **Order Not Found** ```json { "error": "Order not found", "order_id": "invalid-order-id", "message": "The specified order does not exist" } ``` **Access Denied** ```json { "error": "Access denied", "message": "You do not have permission to view this order item" } ``` ### Use Cases **Customer Service** * Answer customer questions about specific items * Check item-specific special instructions * Verify product details and pricing **Fulfillment Management** * Check item preparation requirements * Review modification details * Track individual item status **Inventory Tracking** * Verify product information accuracy * Check UPC codes for scanning * Monitor item-level demand **Quality Control** * Review preparation notes * Check for special handling requirements * Verify modifications were applied correctly **Performance**: Use this endpoint sparingly for individual item lookups. For bulk item information, use the "Get All Order Items" endpoint instead. # Update Order Items Source: https://developer.lulacommerce.com/api-reference/orders/order-items/update-order-items PATCH {{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}} Update specific details of an order item including special instructions, product information, and item specifications. This endpoint allows you to update specific details of an order item after the order has been created. You can modify special instructions, update product descriptions, change categories, or adjust item specifications without affecting quantity or pricing. This endpoint is designed for updating item metadata and preparation instructions. For quantity changes or item removal, use the Patch Order Cart endpoint instead. ### Path Parameters The unique identifier of the order containing the item to update The unique identifier of the specific order item to update ### Request Body Updated special preparation instructions for this item Updated product name as displayed in store Updated product description Updated product category classification Updated item size specification Internal notes for kitchen staff or fulfillment team Employee ID who made the update (for audit trail) ### Response Indicates whether the update was successful Confirmation message or error details The ID of the updated order item List of fields that were successfully updated Timestamp when the update was applied ### Request Example ```json { "special_instructions": "Pack item carefully - fragile", "store_item_name": "Pearson Nut Roll King", "store_item_description": "Crunchy, salty peanut roll with caramel center", "store_item_category": "Snacks", "store_item_size": "1 count", "preparation_notes": "Check expiration date before packing", "updated_by": "emp_12345" } ``` ### Response Example ```json { "success": true, "message": "Order item successfully updated", "order_item_id": "7fbe2819-5bc6-4340-8dfe-a5605272a32b", "updated_fields": [ "special_instructions", "store_item_name", "store_item_description", "store_item_category", "store_item_size", "preparation_notes" ], "timestamp": "2024-01-15T14:30:00Z" } ``` When an order item is updated, the following occurs: 1. **Field Validation**: All provided fields are validated for format and content 2. **Audit Log**: Change is recorded with timestamp and user information 3. **Fulfillment Update**: Kitchen/fulfillment systems are notified of changes 4. **History Tracking**: Previous values are preserved for audit trail 5. **Status Check**: Order status is verified to ensure modifications are allowed **Immutable Fields**: Certain fields like quantity, pricing, and core product identifiers cannot be updated through this endpoint. Use the appropriate order modification endpoints for those changes. **Best Practice**: Always include the updated\_by field to maintain a clear audit trail of who made changes to the order. ### Use Cases **Special Instructions Updates** * Add dietary restrictions or allergies * Update preparation preferences * Include delivery instructions **Product Information Corrections** * Fix product name typos * Update descriptions for clarity * Correct category classifications **Fulfillment Notes** * Add handling instructions * Include quality control notes * Specify packing requirements **Customer Service Adjustments** * Update based on customer requests * Clarify ambiguous instructions * Add additional context for staff ### Error Responses **Order Item Not Found** ```json { "success": false, "message": "Order item not found", "error_code": "ITEM_NOT_FOUND", "order_item_id": "invalid-item-id" } ``` **Order Not Modifiable** ```json { "success": false, "message": "Order cannot be modified in current status", "error_code": "ORDER_NOT_MODIFIABLE", "current_status": "completed" } ``` **Invalid Field Value** ```json { "success": false, "message": "Invalid value provided for field", "error_code": "INVALID_FIELD_VALUE", "field": "store_item_category", "provided_value": "InvalidCategory" } ``` **Validation Error** ```json { "success": false, "message": "Field validation failed", "error_code": "VALIDATION_ERROR", "validation_errors": [ { "field": "special_instructions", "error": "Must be less than 500 characters" } ] } ``` **Status Restrictions**: Order items can only be updated when the order is in modifiable status (pending, accepted, in\_progress). Completed or canceled orders cannot be modified. **Character Limits**: Special instructions and descriptions have character limits. Ensure your updates stay within these bounds to avoid validation errors. ### Field Validation Rules **special\_instructions** * Maximum length: 500 characters * Can include basic punctuation and numbers * No HTML or special formatting allowed **store\_item\_name** * Maximum length: 200 characters * Must be unique within the order * Cannot be empty if provided **store\_item\_description** * Maximum length: 1000 characters * Supports basic formatting * Optional field **store\_item\_category** * Must match existing category in system * Case-sensitive matching * Cannot be null if provided **store\_item\_size** * Maximum length: 50 characters * Free-form text field * Commonly used values: "Small", "Medium", "Large", "1 count", etc. # Orders Management Source: https://developer.lulacommerce.com/api-reference/orders/orders-overview Comprehensive order management system for handling incoming orders, order processing, item management, and issue resolution across all delivery platforms. The Orders service provides complete order lifecycle management, from initial receipt through fulfillment and issue resolution. This system handles orders from multiple delivery service platforms (DSPs) like DoorDash, UberEats, and Grub Hub. ## Order Management ### Core Order Operations * **Get Incoming Orders**: Retrieve new orders waiting for processing * **List All Orders**: View all orders with filtering and status options * **Get Orders Count**: Monitor active and completed order volumes * **Get Order Details**: Access comprehensive order information * **Accept Incoming Order**: Confirm and begin order preparation * **Cancel Order**: Cancel orders with reason codes and messaging * **Get Store Orders**: Retrieve orders specific to a store * **Get Orders History**: Access historical order data and analytics ### Advanced Order Features * **Create New Order**: Generate new orders programmatically * **Patch Order Cart**: Modify existing orders by adding/removing items ## Order Items Management Detailed management of individual items within orders: ### Item Operations * **Get Order Items**: Retrieve specific item details within an order * **Get All Order Items**: Access all items for a given order * **Update Order Items**: Modify item details, descriptions, and special instructions ## Order Issues Management Comprehensive issue tracking and resolution system: ### Issue Handling * **Create Order Issue**: Report problems with orders or items * **Update Order Issue**: Manage issue status, priority, and resolution ## Key Features Handle orders from DoorDash, UberEats, Grub Hub, and LulaDirect seamlessly Monitor incoming orders and process them with real-time status updates Modify orders after receipt with item additions, removals, and quantity changes Track and resolve customer issues with comprehensive logging and attachments ## Order Lifecycle ### 1. Order Receipt Orders arrive from delivery platforms and are automatically ingested into the system with complete item details, customer information, and special instructions. ### 2. Order Processing Store employees can accept orders, modify preparation times, and begin the fulfillment process with real-time status tracking. ### 3. Fulfillment Tracking Complete visibility into order progress from preparation through pickup/delivery with detailed logging of each status change. ### 4. Issue Management Handle customer complaints, wrong items, missing products, and refund requests with structured issue tracking. ## Order Status Management * **incoming**: New order waiting for acceptance * **accepted**: Order confirmed and being prepared * **bagging**: Items being packaged * **ready**: Order ready for pickup * **picked\_up**: Driver has collected the order * **completed**: Order successfully delivered * **cancelled**: Order cancelled by store or customer * **denied**: Order rejected by store * **wrong\_items**: Incorrect products delivered * **missing\_items**: Items not included in order * **quality\_issues**: Product quality problems * **delivery\_issues**: Problems with delivery process * **pricing\_discrepancies**: Price-related concerns * **low**: Minor issues that can be addressed during normal operations * **medium**: Moderate issues requiring timely attention * **high**: Critical issues requiring immediate resolution * **urgent**: Emergency situations requiring instant action ## Integration Points ### Delivery Service Platforms * **DoorDash**: Direct API integration for order management * **UberEats**: Real-time order sync and status updates * **Grub Hub**: Automated order processing and fulfillment * **LulaDirect**: Native platform orders with full feature support ### Internal Systems * **Inventory Management**: Real-time stock updates during order processing * **Employee Management**: Associate actions with specific employees * **Customer Management**: Track customer information and preferences * **Analytics**: Order performance and business intelligence ## Business Benefits ### Operational Efficiency * **Centralized Management**: Handle all platform orders from one interface * **Automated Processing**: Reduce manual work with automated order ingestion * **Real-time Visibility**: Monitor order flow and identify bottlenecks ### Customer Experience * **Faster Processing**: Quick order acceptance and preparation times * **Issue Resolution**: Structured approach to handling customer problems * **Accurate Fulfillment**: Detailed item management reduces errors ### Business Intelligence * **Performance Metrics**: Track order volumes, completion rates, and revenue * **Issue Analytics**: Identify recurring problems and improvement opportunities * **Historical Data**: Access complete order history for analysis Order modifications should be handled carefully to maintain customer satisfaction and delivery platform compliance. Use the order count endpoints to monitor business performance and identify peak operating hours for staffing decisions. # Patch Order Cart Source: https://developer.lulacommerce.com/api-reference/orders/patch-order-cart PATCH {{micro_service_base_url}}/orders/{{order_id}}/patch-order Modify order items by adding, removing, or updating quantities after order creation but before completion. This endpoint allows you to modify order contents after the order has been created but before it's completed. You can remove items, reduce quantities, add new items, or update existing items. This is useful for handling out-of-stock situations, customer requests, or inventory adjustments. Order modifications should only be made with customer approval and may affect the final order price. Always communicate changes to the customer. ### Path Parameters The unique identifier of the order to modify ### Request Body The request body should be an array of action objects, each specifying a modification to perform: Type of modification: "remove\_item", "reduce\_quantity", "add\_item", "update\_item" The unique identifier of the order item to modify (required for remove\_item, reduce\_quantity, update\_item) New quantity for the item (required for reduce\_quantity and add\_item actions) Product identifier (required for add\_item actions) Updated special instructions for the item ### Response Updated order identifier Updated order subtotal after modifications Recalculated tax amount Updated original price Delivery platform name Order-level special instructions Customer information remains unchanged Updated fulfillment information with modification logs Complete log of all order changes including modifications Timestamp of the modification Description of what was changed Status title (e.g., "Item quantity edited") Employee who made the modification Updated array of order items after modifications ### Request Example ```json [ { "action_type": "remove_item", "order_item_id": "35bf2e22-a70f-4dda-9de0-eb92ee581d4a" }, { "action_type": "reduce_quantity", "order_item_id": "3133710b-6d3e-4533-8d67-26c7a4a93e29", "quantity": 2 } ] ``` ### Response Example ```json { "id": "a8e2c9ee-0bbd-4e86-ab2c-40e94297b3bd", "original_subtotal": "-35.26", "is_auto_accepted": false, "order_id": null, "tax_amount": "NaN", "discount": null, "original_price": null, "createdAt": "2024-07-04T12:06:57.740Z", "partner": "DoorDash", "special_instructions": "Cancel the order if the first item is not Present", "exclude_allergens_items": "", "is_include_disposables": false, "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "dsp_order_number": "", "custom_fee": null, "tax_remitted": "NaN", "customer": { "customer_name": "Lula D.", "contact_phone": "+1 312-766-6835", "phone_code": null }, "fulfillments": [ { "quantity": null, "date_ready": null, "createdAt": "2024-07-04T12:06:57.756Z", "estimated_date_delivered": "2024-07-04T12:17:14.540Z", "id": "2f71af29-e115-42f1-839f-1137efa73c8a", "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "fulfillmentStatus": { "delivery_status_name": "waiting" }, "fulfillmentsLogs": [ { "date_created": "2024-07-04T12:06:57.758Z", "description": "DoorDash store mock order received", "order_status_title": "Order received", "fulfillments_id": "2f71af29-e115-42f1-839f-1137efa73c8a", "employee": null }, { "date_created": "2024-07-04T12:07:14.577Z", "description": "", "order_status_title": "Bagging order", "fulfillments_id": "2f71af29-e115-42f1-839f-1137efa73c8a", "employee": { "id": "f78c06a0-8a0f-4d0b-a5d1-d7d2b0ffde70", "first_name": "Salman", "last_name": "Saeed Paul" } }, { "date_created": "2024-07-04T12:07:56.205Z", "description": "Removing [1] 'Cheetos Flamin' Hot Cheese Flavored Snacks'.", "order_status_title": "Item quantity edited", "fulfillments_id": "2f71af29-e115-42f1-839f-1137efa73c8a", "employee": { "id": "f78c06a0-8a0f-4d0b-a5d1-d7d2b0ffde70", "first_name": "Salman", "last_name": "Saeed Paul" } } ] } ], "orderItems": [] } ``` **remove\_item** * Completely removes an item from the order * Requires: order\_item\_id * Use when item is out of stock or customer requests removal **reduce\_quantity** * Reduces the quantity of an existing item * Requires: order\_item\_id, quantity (new quantity, not amount to reduce) * Use for partial availability or customer quantity changes **add\_item** * Adds a new item to the order * Requires: item\_id, quantity * Optional: special\_instructions * Use for customer additions or substitutions **update\_item** * Updates item details without changing quantity * Requires: order\_item\_id * Optional: special\_instructions, item modifications * Use for customization changes **Price Recalculation**: The system automatically recalculates taxes, fees, and total price after modifications. Negative subtotals in the response indicate cost reductions. **Best Practice**: Always batch multiple modifications into a single request to avoid multiple price recalculations and to maintain order consistency. ### Error Responses **Invalid Order Item** ```json { "error": "Order item not found", "order_item_id": "invalid-id" } ``` **Order Not Modifiable** ```json { "error": "Order cannot be modified in current status", "current_status": "completed" } ``` **Invalid Quantity** ```json { "error": "Quantity must be greater than 0", "provided_quantity": 0 } ``` **Status Restrictions**: Orders can only be modified in certain statuses (pending, accepted, in\_progress). Completed, canceled, or delivered orders cannot be modified. ### Use Cases **Out of Stock Items** * Remove unavailable items * Reduce quantities for partial availability * Add substitute items with customer approval **Customer Requests** * Add items to existing order * Remove items customer no longer wants * Modify special instructions **Inventory Adjustments** * Reduce quantities when stock is lower than expected * Remove items due to quality issues * Update item specifications **Price Corrections** * Adjust item quantities for pricing corrections * Remove incorrectly priced items * Add corrected items # Change Store Status Source: https://developer.lulacommerce.com/api-reference/stores/change-store-status PUT https://api-staging.luladelivery.store/stores/{store_id}/status This endpoint controls the operational status of a store across delivery service partners. You can open or close the store on all platforms simultaneously, or manage individual platforms (UberEats, DoorDash, GrubHub) separately. This is essential for managing store hours, temporary closures, and platform-specific operations. This endpoint provides granular control over store availability across delivery platforms. You can manage store status globally or per platform, with optional scheduling for automatic status changes. ### Path Parameters The unique identifier of the store to update status for Delivery Service Provider to control. Options: * `"All"` - Controls all platforms simultaneously * `"UberEats"` - Controls only UberEats * `"DoorDash"` - Controls only DoorDash * `"GrubHub"` - Controls only GrubHub Store operational status: * `true` - Opens the store (ONLINE) * `false` - Closes the store (OFFLINE) When the status change should automatically revert. ISO 8601 format with timezone. Example: "2024-11-15T23:59:00-07:00" If omitted, the status change is permanent until manually changed When the status change should take effect (for scheduled changes). Example: "2024-11-15T00:00:00-05:00" Used primarily for scheduling future status changes ## Common Operations ### Open All Platforms Opens the store on all delivery platforms simultaneously. ```json { "dsp_name": "All", "is_active": true, "end_time": "2024-11-15T23:59:00-07:00" } ``` ### Close All Platforms Closes the store on all delivery platforms simultaneously. ```json { "dsp_name": "All", "is_active": false } ``` ### Platform-Specific Control #### Open UberEats Only ```json { "dsp_name": "UberEats", "is_active": true, "end_time": "2024-11-15T23:59:00-07:00" } ``` #### Close DoorDash Only ```json { "dsp_name": "DoorDash", "is_active": false, "end_time": "2024-11-15T23:59:00-07:00" } ``` #### Pause GrubHub ```json { "dsp_name": "GrubHub", "is_active": false, "end_time": "2024-06-21T17:08:30.000Z" } ``` ### Scheduled Operations #### Schedule Store Pause ```json { "dsp_name": "All", "is_active": false, "end_time": "2024-11-15T23:59:00-05:00", "start_time": "2024-11-15T00:00:00-05:00" } ``` ## Response Types ### Successful Status Change Indicates whether the status change was successful Detailed status information after the change (included for "All" operations) Any current pause affecting all platforms Overall store closure status UberEats status after change DoorDash status after change GrubHub status after change ### Simple Success Response For single platform operations or basic operations: ```json { "success": true } ``` ### Detailed Response Example For "All" platform operations with full status: ```json { "success": true, "status": { "current_pause": null, "is_close": false, "UberEats": [ { "success": true, "is_open": true, "status": "ONLINE", "end_time": null, "current_pause": null, "description": [ { "status": "ONLINE" } ], "id": "37fa9980-33ba-4419-92c2-a6e5144fdc82", "partner_store_id": "15be0357-9b4d-4f05-9a5a-9485b5f783e5", "name": "Lula Convenience Store", "status_changed_from": true } ], "DoorDash": [ { "success": true, "is_open": true, "status": "ONLINE", "end_time": null, "current_pause": null, "description": [], "id": "1704fecd-e6ca-45bb-b1b5-776aee294af8", "partner_store_id": "b1015bdb-e831-42ef-b6f8-720fab19321f", "name": "Lula Convenience Store", "status_changed_from": true } ], "GrubHub": [ { "success": true, "is_open": true, "status": "ONLINE", "end_time": null, "current_pause": null, "description": [ { "merchant_status": "PT_PREMIUM", "merchant_status_descriptor": "Premium", "pos_merchant_status": "online", "holds_active_account": true, "accepting_phone_orders": true, "accepting_online_orders": true } ], "id": "d0b3e829-299f-42cc-a768-2f9a908f3355", "partner_store_id": "1240569280", "name": "Lula Convenience Store", "status_changed_from": true } ] } } ``` ## Best Practices Use "All" for consistent customer experience across platforms Customers expect consistent availability across all delivery apps Use individual platform controls when specific integrations have issues This allows you to maintain operations on working platforms Use end\_time for temporary closures (breaks, maintenance, etc.) Without end\_time, status changes are permanent For immediate closures, use "All" with is\_active: false This immediately stops new orders across all platforms **Real-time Effect:** Status changes take effect immediately on all specified platforms. Existing orders in progress are not affected. **Timezone Awareness:** When using end\_time, ensure the timezone offset matches the store's local timezone to avoid unexpected behavior. **Platform Dependencies:** Some platforms may have additional requirements or delays in reflecting status changes. The response indicates the success of the API call, not necessarily the immediate platform reflection. # Create Store Source: https://developer.lulacommerce.com/api-reference/stores/create-store POST https://api-staging.luladelivery.store/stores/store/ This endpoint creates a new store under a specific company. Stores are the operational units that handle orders, inventory, and customer interactions. Each store can have multiple addresses for different purposes and automatically gets configured with delivery service partners. This endpoint creates a new store with all necessary business information including addresses, company association, and delivery service partner integrations. The store will be automatically configured with UberEats, DoorDash, and GrubHub partnerships. Store name as it will appear to customers. Example: "SSP Test Store - final" Store contact email address. Example: "[test.store@example.com](mailto:test.store@example.com)" Store contact phone number in international format. Example: "+14132231249" ID of the company this store belongs to. Example: 1000022 Array of address objects for different store purposes Primary address line. Example: "123 Main Street" City name. Example: "Philadelphia" State or province. Example: "PA" ZIP or postal code. Example: "19104" Type of address: * `0` = Store Address (main operational address) * `1` = Welcome Package Address (shipping address for onboarding materials) Whether to create a billing vendor account for this store. Set to `true` to enable automated billing setup. User ID of the primary point of contact for this store. Example: 1000049 ### Request Example ```json { "name": "SSP Test Store - final", "email": "test.store@example.com", "phone_number": "+14132231249", "company_id": 1000022, "addresses": [ { "line_1": "123 Main Street", "city": "Philadelphia", "state": "PA", "zip": "19104", "address_type": 0 }, { "line_1": "201 S Main St. West Lebanon", "city": "Boston", "state": "NH", "zip": "03784", "address_type": 1 } ], "create_bill_vendor": true, "point_of_contact": 1000049 } ``` ### Response Unique store identifier (UUID format) Indicates whether store setup process is complete Store disabled status Role-based access control enablement status Store name as provided Store contact email Store contact phone number Associated company ID Point of contact user ID Generated billing vendor ID if create\_bill\_vendor was true Array of created address records with full details including IDs Array of delivery service partner configurations (UberEats, DoorDash, GrubHub) Associated vendor/billing ID ### Response Example ```json { "id": "7669f473-6c40-45ee-8737-43c667407b3a", "store_setup_completed": false, "is_disabled": false, "is_rbac_store": false, "name": "SSP Test Store - final", "email": "test.store@example.com", "phone_number": "+14132231249", "company_id": "1000022", "point_of_contact": "1000049", "updatedAt": "2023-09-20T13:27:18.782Z", "createdAt": "2023-09-20T13:27:11.318Z", "bill_vendor_id": "00901CNUBBSWJZLLd82g", "addresses": [ { "id": "f2641a24-c946-4421-9c95-107ecaa8b7af", "address": { "id": "8e48af24-7b57-4786-99f0-17a6a326cefc", "line_1": "123 Main Street", "city": "Philadelphia", "state": "PA", "zip": "19104" }, "address_type": { "description": "Store Address", "address_type": 0 } }, { "id": "c47f36fa-e180-4df6-89fd-6ba89323d5a3", "address": { "id": "48dd9f57-7180-44a8-b106-dad325f52523", "line_1": "201 S Main St. West Lebanon", "city": "Boston", "state": "NH", "zip": "03784" }, "address_type": { "description": "Welcome Package Address", "address_type": 1 } } ], "store_partners": [ { "id": "b8168479-5c75-4bd6-977c-eabad3a3a01c", "partner_name": "UberEats", "order_enabled": false, "menu_enabled": false, "pos_enabled": false }, { "id": "23c1ec9c-bfd1-46d9-a0bc-bf4f456eba5b", "partner_name": "DoorDash", "order_enabled": false, "menu_enabled": false, "pos_enabled": false }, { "id": "d142c4db-7910-471c-8c22-3f1d17fb3c19", "partner_name": "GrubHub", "order_enabled": false, "menu_enabled": false, "pos_enabled": false } ] } ``` **Automatic Partner Setup:** The store is automatically configured with delivery service partners (UberEats, DoorDash, GrubHub) but they start in disabled state. You'll need to configure each partner individually after store creation. **Address Types:** Use address\_type `0` for the main store address where operations happen, and address\_type `1` for the address where welcome packages and onboarding materials should be shipped. **Point of Contact:** Ensure the point\_of\_contact user ID exists and has appropriate permissions before creating the store. **Billing Vendor:** When create\_bill\_vendor is true, a billing vendor account is automatically created and linked to the store for payment processing. # Get Store Status Source: https://developer.lulacommerce.com/api-reference/stores/get-store-status GET https://api-staging.luladelivery.store/stores/{store_id}/status?current_local_date={date} This endpoint retrieves the current operational status of a store across all delivery service partners (UberEats, DoorDash, GrubHub). It provides real-time information about whether the store is accepting orders, any active pauses, and detailed status descriptions for each platform. This endpoint provides comprehensive store status information across all integrated delivery service partners. It shows whether the store is currently accepting orders, any temporary pauses, and platform-specific status details. ### Path Parameters The unique identifier of the store to check status for ### Query Parameters Current local date and time for the store's timezone. Format: "MMM DD YYYY HH:mm:ss" Example: "Nov 15 2024 03:46:34" ### Response Any current pause reason affecting all platforms Overall store closure status across all platforms Alternative closure status indicator Array of UberEats store status objects Whether the status query was successful Whether the store is currently open on UberEats Current status: "ONLINE" or "OFFLINE" When the current status expires (null if permanent) Any active pause reason Detailed status information array Internal store partner record ID UberEats-specific store identifier Store name as it appears on UberEats Array of DoorDash store status objects with similar structure to UberEats Detailed status descriptions including reasons and notes Reason for current status Additional status notes When this status was set When this status expires Experience type (e.g., "ANY\_EXPERIENCE") Array of GrubHub store status objects GrubHub-specific status information GrubHub merchant status code Human-readable status description POS integration status: "online" or "offline" Reason for current status Whether the account is active Whether phone orders are accepted Whether online orders are accepted ### Response Example ```json { "current_pause": null, "is_close": false, "UberEats": [ { "success": true, "is_open": true, "status": "ONLINE", "end_time": null, "current_pause": null, "description": [ { "status": "ONLINE" } ], "id": "37fa9980-33ba-4419-92c2-a6e5144fdc82", "partner_store_id": "15be0357-9b4d-4f05-9a5a-9485b5f783e5", "name": "Lula Convenience Store" } ], "DoorDash": [ { "success": true, "is_open": false, "status": "OFFLINE", "end_time": "2024-11-16T06:59", "current_pause": null, "description": [ { "reason": "POS Integration - Store Availability Webhook", "notes": "Store is closed", "created_at": "2024-11-14T23:03:49.019", "end_time": "2024-11-16T06:59", "experience": "ANY_EXPERIENCE" } ], "id": "1704fecd-e6ca-45bb-b1b5-776aee294af8", "partner_store_id": "b1015bdb-e831-42ef-b6f8-720fab19321f", "name": "Lula Convenience Store" } ], "GrubHub": [ { "success": true, "is_open": false, "status": "OFFLINE", "end_time": null, "current_pause": null, "description": [ { "merchant_status": "PT_PREMIUM_DATA_PROBLEMS", "merchant_status_descriptor": "Account Update/Escalation (RC)", "pos_merchant_status": "offline", "reason": "If you do not expect this location to be offline, please contact Grubhub", "holds_active_account": true, "accepting_phone_orders": true, "accepting_online_orders": false } ], "id": "d0b3e829-299f-42cc-a768-2f9a908f3355", "partner_store_id": "1240569280", "name": "Lula Convenience Store" } ], "is_closed": false } ``` ### Status Interpretation `is_close` and `is_closed` indicate if the store is closed across all platforms A store can be open on some platforms and closed on others Each platform (UberEats, DoorDash, GrubHub) has independent status ONLINE = accepting orders, OFFLINE = not accepting orders `end_time` indicates when the current status will automatically change null end\_time means the status is permanent until manually changed `current_pause` shows temporary holds on operations Pauses can be platform-specific or affect all platforms ### Use Cases Regular status checks to ensure store availability across platforms Investigating why orders aren't coming from specific platforms Verifying automated open/close schedules are working correctly Monitoring the health of integrations with delivery partners **Real-time Data:** Status information is fetched in real-time from each delivery partner's systems, providing the most current operational state. **Timezone Consideration:** The current\_local\_date parameter should reflect the store's local timezone for accurate status reporting, especially for scheduled operations. # Get Store Tax Rate Source: https://developer.lulacommerce.com/api-reference/stores/get-store-tax-rate GET https://api-staging.luladelivery.store/stores/{store_id}/tax-rate This endpoint retrieves the tax rate configuration for a specific store. Tax rates are essential for accurate order calculations and compliance with local tax regulations. The response includes applicable tax percentages and tax jurisdiction information. This endpoint provides the current tax rate information configured for a store. Tax rates are used to calculate taxes on orders and ensure compliance with local tax regulations based on the store's location. ### Path Parameters The unique identifier of the store to retrieve tax rate information for ### Response The tax rate as a decimal (e.g., 0.0875 for 8.75%) The tax jurisdiction or authority that applies to this store Type of tax applied (e.g., "sales\_tax", "vat", "gst") When this tax rate became effective (ISO 8601 format) Currency code for tax calculations (e.g., "USD", "CAD") Whether prices include tax (true) or tax is added separately (false) ### Response Example ```json { "tax_rate": 0.0875, "tax_jurisdiction": "California State Tax", "tax_type": "sales_tax", "effective_date": "2024-01-01T00:00:00Z", "currency": "USD", "tax_inclusive": false } ``` ### Tax Rate Usage Tax rates are automatically applied to order totals during checkout Tax calculation happens in real-time based on current rates Ensures orders comply with local tax regulations and reporting requirements Tax rates may vary by product category or customer type Used for generating tax reports and remittance to tax authorities Historical tax rates are preserved for audit purposes ### Tax Rate Management Tax rates may be updated automatically based on jurisdiction changes Rate changes typically have advance notice periods Rates are determined by store location and applicable tax jurisdictions Stores in different locations may have different tax rates Some jurisdictions apply different rates to different product types The base rate shown may be modified based on product category ### Common Use Cases Verify current tax rates during order calculation and validation Understanding tax impact on revenue and pricing strategies Ensuring proper tax rates are applied for regulatory compliance Synchronizing tax rates with external accounting or POS systems ### Error Scenarios The specified store\_id doesn't exist **Status Code:** 404 Store doesn't have tax rate configuration set up **Status Code:** 404 **Solution:** Contact support to configure tax rates for the store Tax jurisdiction data is incomplete or invalid **Status Code:** 500 **Solution:** Verify store address and tax jurisdiction setup **Rate Precision:** Tax rates are provided with high precision to ensure accurate calculations. Always use the exact decimal values provided. **Rate Changes:** Tax rates can change due to legislative updates. Applications should periodically refresh tax rate information to ensure compliance. **Integration:** This endpoint is commonly used by POS systems, e-commerce platforms, and accounting software to ensure consistent tax calculations across all systems. # Get Onboarding by Company ID Source: https://developer.lulacommerce.com/api-reference/stores/onboarding/get-onboarding-by-company-id GET https://api-staging.luladelivery.store/stores/company/{company_id}/onboarding This endpoint retrieves onboarding status information for all stores belonging to a specific company. This provides a company-wide view of store onboarding progress and operational status across all delivery platforms. This endpoint provides a comprehensive overview of onboarding status for all stores under a company. It's useful for company-level monitoring and management of store operations across multiple locations. ### Path Parameters The unique identifier of the company to retrieve onboarding information for all its stores ### Response The company ID for which onboarding information was retrieved Total number of stores belonging to this company Number of stores that have completed onboarding Number of stores with onboarding in progress or pending Array of store onboarding information Unique identifier for the store Name of the store Overall onboarding status for this store Values: "completed", "in\_progress", "pending", "failed" When the store was created When onboarding was completed (null if not completed) Current operational status across platforms Whether the store is currently operational Number of delivery platforms currently online Total number of configured delivery platforms When status was last checked Detailed status for each delivery platform UberEats status information Whether this platform is active for the store Current platform status Platform-specific store identifier When this platform status was last updated DoorDash status information with similar structure GrubHub status information with similar structure ### Response Example ```json { "company_id": "1000022", "total_stores": 5, "onboarded_stores": 3, "pending_onboarding": 2, "stores": [ { "store_id": "7669f473-6c40-45ee-8737-43c667407b3a", "store_name": "Lula Convenience Store - Main", "onboarding_status": "completed", "created_at": "2023-09-20T13:27:11.318Z", "onboarded_at": "2023-09-20T14:15:22.456Z", "current_status": { "is_operational": true, "platforms_online": 2, "platforms_total": 3, "last_status_check": "2024-11-15T03:46:34.000Z" }, "platform_details": { "UberEats": { "is_active": true, "status": "ONLINE", "partner_store_id": "15be0357-9b4d-4f05-9a5a-9485b5f783e5", "last_updated": "2024-11-15T03:30:00.000Z" }, "DoorDash": { "is_active": true, "status": "ONLINE", "partner_store_id": "b1015bdb-e831-42ef-b6f8-720fab19321f", "last_updated": "2024-11-15T03:30:00.000Z" }, "GrubHub": { "is_active": false, "status": "OFFLINE", "partner_store_id": "1240569280", "last_updated": "2024-11-15T02:15:00.000Z" } } }, { "store_id": "8669f473-6c40-45ee-8737-43c667407b3b", "store_name": "Lula Convenience Store - Branch", "onboarding_status": "in_progress", "created_at": "2023-09-21T10:15:30.123Z", "onboarded_at": null, "current_status": { "is_operational": false, "platforms_online": 0, "platforms_total": 3, "last_status_check": "2024-11-15T03:46:34.000Z" }, "platform_details": { "UberEats": { "is_active": false, "status": "SETUP_PENDING", "partner_store_id": null, "last_updated": "2023-09-21T10:15:30.123Z" }, "DoorDash": { "is_active": false, "status": "SETUP_PENDING", "partner_store_id": null, "last_updated": "2023-09-21T10:15:30.123Z" }, "GrubHub": { "is_active": false, "status": "SETUP_PENDING", "partner_store_id": null, "last_updated": "2023-09-21T10:15:30.123Z" } } } ] } ``` ### Company-Level Insights Track overall onboarding completion rate across all company stores Helps identify if onboarding processes are working efficiently Monitor how many stores are currently operational and accepting orders Low operational rates may indicate systemic issues Identify which delivery platforms have the highest success rates Focus troubleshooting efforts on problematic platforms Assess company readiness for opening additional store locations High success rates indicate good operational processes ### Use Cases Provide company leadership with overview of store operations Useful for board meetings and operational reviews Monitor onboarding progress across all company locations Identify stores that need additional support or attention Analyze patterns in onboarding success and operational efficiency Data can inform process improvements and training needs Identify which stores need immediate attention or support Failed or stuck onboarding processes should be prioritized ### Filtering and Analysis Filter stores by onboarding\_status to focus on specific groups Common filters: "pending", "in\_progress", "failed" Calculate success rates and average onboarding times Track improvements over time to measure process efficiency Compare platform activation success rates across stores Identify if certain platforms consistently cause issues **Data Freshness:** Company-level onboarding data is updated in real-time as individual store statuses change, providing current operational insights. **Scalability:** This endpoint efficiently handles companies with large numbers of stores, making it suitable for enterprise-level operations monitoring. # Get Onboarding by ID Source: https://developer.lulacommerce.com/api-reference/stores/onboarding/get-onboarding-by-id GET https://api-staging.luladelivery.store/stores/onboarding/{onboarding_id} This endpoint retrieves onboarding information for a specific onboarding record using its unique identifier. This is useful for tracking onboarding progress and status when you have the onboarding ID from previous operations. This endpoint allows you to fetch detailed onboarding information using a specific onboarding ID. This is typically used when tracking onboarding processes or when you need to retrieve onboarding details from a stored reference. ### Path Parameters The unique identifier of the onboarding record to retrieve ### Response The unique identifier for this onboarding record The store ID associated with this onboarding The company ID that owns the store Current status of the onboarding process Common statuses: "pending", "in\_progress", "completed", "failed" When the onboarding process was initiated (ISO 8601 format) When the onboarding record was last updated When the onboarding process was completed (null if not completed) Status breakdown for each delivery platform UberEats onboarding status Platform-specific status When this platform was activated Platform-specific store identifier DoorDash onboarding status with similar structure GrubHub onboarding status with similar structure Array of completed onboarding steps Name of the onboarding step Step completion status When this step was completed Additional notes or comments about this step ### Response Example ```json { "onboarding_id": "ob_7669f473-6c40-45ee-8737-43c667407b3a", "store_id": "7669f473-6c40-45ee-8737-43c667407b3a", "company_id": "1000022", "onboarding_status": "completed", "created_at": "2023-09-20T13:27:11.318Z", "updated_at": "2023-09-20T14:15:22.456Z", "completed_at": "2023-09-20T14:15:22.456Z", "platform_status": { "UberEats": { "status": "active", "activated_at": "2023-09-20T14:10:15.123Z", "partner_store_id": "15be0357-9b4d-4f05-9a5a-9485b5f783e5" }, "DoorDash": { "status": "active", "activated_at": "2023-09-20T14:12:30.789Z", "partner_store_id": "b1015bdb-e831-42ef-b6f8-720fab19321f" }, "GrubHub": { "status": "active", "activated_at": "2023-09-20T14:15:22.456Z", "partner_store_id": "1240569280" } }, "onboarding_steps": [ { "step_name": "store_setup_validation", "status": "completed", "completed_at": "2023-09-20T13:30:00.000Z", "notes": "All required store information validated" }, { "step_name": "menu_configuration", "status": "completed", "completed_at": "2023-09-20T13:45:00.000Z", "notes": "Initial menu items configured" }, { "step_name": "platform_activation", "status": "completed", "completed_at": "2023-09-20T14:15:22.456Z", "notes": "All platforms successfully activated" } ] } ``` ### Use Cases Monitor the progress of ongoing onboarding processes Check status periodically during onboarding to track progress Investigate onboarding issues or failures Step-by-step status helps identify where problems occurred Maintain records of when stores were onboarded and activated Useful for compliance and business analytics Synchronize onboarding status with external systems Ensure external systems reflect current onboarding state ### Error Scenarios The specified onboarding\_id doesn't exist **Status Code:** 404 **Solution:** Verify the onboarding ID or check if onboarding was initiated User doesn't have permission to view this onboarding record **Status Code:** 403 **Solution:** Ensure user has appropriate permissions for the associated company Onboarding record exists but data is inconsistent **Status Code:** 500 **Solution:** Contact support for data recovery **Real-time Data:** Onboarding information is updated in real-time as processes complete, providing accurate current status. **Data Retention:** Onboarding records are preserved for audit and troubleshooting purposes, even after completion. # Get Onboarding by Store ID Source: https://developer.lulacommerce.com/api-reference/stores/onboarding/get-onboarding-by-store-id GET https://api-staging.luladelivery.store/stores/{store_id}/status?current_local_date={date} This endpoint retrieves the current onboarding and operational status of a store by its store ID. It provides comprehensive information about the store's availability across all delivery platforms and any onboarding-related status information. This endpoint retrieves detailed onboarding and operational status for a specific store. It's particularly useful for checking the current state of a store's onboarding process and its operational status across delivery platforms. ### Path Parameters The unique identifier of the store to retrieve onboarding status for ### Query Parameters Current local date and time for the store's timezone Format: "MMM DD YYYY HH:mm:ss" Example: "Nov 15 2024 03:46:34" ### Response Any current pause reason affecting all platforms Overall store closure status across all platforms Alternative closure status indicator Array of UberEats store status objects Whether the platform query was successful Whether the store is currently open on UberEats Current platform status: "ONLINE" or "OFFLINE" When current status expires (null if permanent) Any active pause reason for this platform Detailed status descriptions and reasons Internal store partner record ID UberEats-specific store identifier Store name as it appears on UberEats Array of DoorDash store status objects DoorDash-specific status information Reason for current status Additional status notes When this status was set When this status expires Experience type (e.g., "ANY\_EXPERIENCE") Array of GrubHub store status objects GrubHub-specific merchant status information GrubHub internal merchant status code Human-readable status description POS integration status: "online" or "offline" Reason for current status if offline Whether the merchant account is active Whether phone orders are being accepted Whether online orders are being accepted ### Response Example ```json { "current_pause": null, "is_close": false, "UberEats": [ { "success": true, "is_open": true, "status": "ONLINE", "end_time": null, "current_pause": null, "description": [ { "status": "ONLINE" } ], "id": "37fa9980-33ba-4419-92c2-a6e5144fdc82", "partner_store_id": "15be0357-9b4d-4f05-9a5a-9485b5f783e5", "name": "Lula Convenience Store" } ], "DoorDash": [ { "success": true, "is_open": false, "status": "OFFLINE", "end_time": "2024-11-16T06:59", "current_pause": null, "description": [ { "reason": "POS Integration - Store Availability Webhook", "notes": "Store is closed", "created_at": "2024-11-14T23:03:49.019", "end_time": "2024-11-16T06:59", "experience": "ANY_EXPERIENCE" } ], "id": "1704fecd-e6ca-45bb-b1b5-776aee294af8", "partner_store_id": "b1015bdb-e831-42ef-b6f8-720fab19321f", "name": "Lula Convenience Store" } ], "GrubHub": [ { "success": true, "is_open": false, "status": "OFFLINE", "end_time": null, "current_pause": null, "description": [ { "merchant_status": "PT_PREMIUM_DATA_PROBLEMS", "merchant_status_descriptor": "Account Update/Escalation (RC)", "pos_merchant_status": "offline", "reason": "If you do not expect this location to be offline, please contact Grubhub", "holds_active_account": true, "accepting_phone_orders": true, "accepting_online_orders": false } ], "id": "d0b3e829-299f-42cc-a768-2f9a908f3355", "partner_store_id": "1240569280", "name": "Lula Convenience Store" } ], "is_closed": false } ``` ### Onboarding Status Interpretation All platforms show `success: true` and `is_open: true` Store is fully operational and accepting orders Some platforms are online while others are offline May indicate incomplete setup or platform-specific issues Platforms show `success: false` or error descriptions Requires investigation and resolution before going live Platforms may be offline due to scheduled hours or temporary pauses Check end\_time fields to see if status will change automatically ### Use Cases Verify that store onboarding completed successfully across all platforms Essential checkpoint after initiating onboarding process Regular monitoring of store availability and platform health Set up automated monitoring to detect issues quickly Investigate why a store might not be receiving orders Offline platforms won't generate orders Building dashboards to show current store operational status Real-time data suitable for monitoring interfaces **Real-time Status:** This endpoint provides real-time status information directly from delivery partner systems, ensuring accuracy for operational decisions. **Timezone Awareness:** The current\_local\_date parameter ensures status checks account for the store's local timezone, which is important for schedule-based operations. # Start Onboarding Source: https://developer.lulacommerce.com/api-reference/stores/onboarding/start-onboarding PUT https://api-staging.luladelivery.store/stores/{store_id}/status This endpoint initiates the store onboarding process by opening the store on all delivery service platforms. This is a critical step that makes the store live and ready to accept orders from customers across UberEats, DoorDash, and GrubHub. This endpoint starts the store onboarding process by activating the store across all delivery platforms simultaneously. This operation transitions the store from setup/configuration mode to live operational status. ### Path Parameters The unique identifier of the store to start onboarding for ### Request Body Must be set to "All" to activate all delivery service platforms Must be set to `true` to open the store Optional end time for temporary activation. Format: ISO 8601 with timezone Example: "2024-11-15T23:59:00-07:00" ### Request Example ```json { "dsp_name": "All", "is_active": true, "end_time": "2024-11-15T23:59:00-07:00" } ``` ### Response Indicates whether the onboarding activation was successful Detailed status information showing the result of activating each platform Any current pause affecting all platforms (should be null after successful activation) Overall store closure status (should be false after activation) UberEats activation results Whether UberEats activation was successful Whether the store is now open on UberEats Platform status: "ONLINE" if successfully activated Whether the status was changed from previous state UberEats-specific store identifier Store name as it appears on UberEats DoorDash activation results with similar structure GrubHub activation results with similar structure ### Response Example ```json { "success": true, "status": { "current_pause": null, "is_close": false, "UberEats": [ { "success": true, "is_open": true, "status": "ONLINE", "end_time": null, "current_pause": null, "description": [ { "status": "ONLINE" } ], "id": "37fa9980-33ba-4419-92c2-a6e5144fdc82", "partner_store_id": "15be0357-9b4d-4f05-9a5a-9485b5f783e5", "name": "Lula Convenience Store", "status_changed_from": true } ], "DoorDash": [ { "success": true, "is_open": true, "status": "ONLINE", "end_time": null, "current_pause": null, "description": [], "id": "1704fecd-e6ca-45bb-b1b5-776aee294af8", "partner_store_id": "b1015bdb-e831-42ef-b6f8-720fab19321f", "name": "Lula Convenience Store", "status_changed_from": true } ], "GrubHub": [ { "success": true, "is_open": true, "status": "ONLINE", "end_time": null, "current_pause": null, "description": [ { "merchant_status": "PT_PREMIUM", "merchant_status_descriptor": "Premium", "pos_merchant_status": "online", "holds_active_account": true, "accepting_phone_orders": true, "accepting_online_orders": true } ], "id": "d0b3e829-299f-42cc-a768-2f9a908f3355", "partner_store_id": "1240569280", "name": "Lula Convenience Store", "status_changed_from": true } ] } } ``` ### Onboarding Prerequisites Ensure all basic store information is configured Name, addresses, contact information must be complete Store menu should be configured with available items Stores without menu items may not accept orders properly Delivery service partner accounts should be set up Partner integrations are automatically created during store creation Billing and payment processing should be configured Verify bill\_vendor\_id is set during store creation Ensure staff is trained on order fulfillment processes Orders will start coming immediately after activation ### Post-Onboarding Actions Watch for incoming orders to verify system is working Orders typically start within minutes of going live Check that store appears correctly on each delivery platform It may take a few minutes for stores to appear in customer apps Place test orders to ensure fulfillment process works smoothly Use test accounts to avoid affecting real customers Set up regular operating hours if not already configured Initial activation may use default hours **Immediate Effect:** Once successfully activated, the store will immediately start receiving orders from customers on all platforms. **Irreversible Process:** Onboarding makes the store live to customers. Ensure all prerequisites are met before activation. **Support Contact:** If any platform fails to activate, contact technical support with the specific platform error details from the response. # Link Store to Employee Source: https://developer.lulacommerce.com/api-reference/stores/store-employees/link-store-to-employee POST https://api-staging.luladelivery.store/stores/store-employees/ This endpoint links multiple stores to a new employee, creating employee relationships across multiple store locations simultaneously. This is useful for employees who work across multiple stores or for managers overseeing multiple locations. This endpoint creates employee relationships between a new employee and multiple stores in a single operation. It's particularly useful for multi-store employees, area managers, or support staff who need access to multiple store locations. ### Request Body Array of store IDs to link the employee to Example: \["b2b56ffb-e198-49f3-a1bc-f36ac70f9501", "d7c17a59-01e1-48f2-a326-2bbd3c888205"] The unique employee identifier (UUID format) for this employee Example: "30523fd1-e108-41d0-a02d-f5907336f2e4" The company ID that owns the stores being linked Example: 1000022 The user ID of the employee being linked to stores Example: 1000305 ### Request Example ```json { "store_ids": [ "b2b56ffb-e198-49f3-a1bc-f36ac70f9501", "d7c17a59-01e1-48f2-a326-2bbd3c888205", "449235c1-3d04-4519-998b-40d2a621e5e0" ], "employee_id": "30523fd1-e108-41d0-a02d-f5907336f2e4", "company_id": 1000022, "user_id": 1000305 } ``` ### Response Number of stores successfully linked to the employee Array of successfully created store-employee relationships Store ID that was successfully linked Employee ID used for the link Access level granted for this store When the link was created Array of stores that failed to link with error details Store ID that failed to link Reason for the failure Error code for programmatic handling ### Response Example ```json { "count": 2, "successful_links": [ { "store_id": "b2b56ffb-e198-49f3-a1bc-f36ac70f9501", "employee_id": "30523fd1-e108-41d0-a02d-f5907336f2e4", "access_level": "store_employee", "linked_at": "2024-11-15T10:30:00.000Z" }, { "store_id": "d7c17a59-01e1-48f2-a326-2bbd3c888205", "employee_id": "30523fd1-e108-41d0-a02d-f5907336f2e4", "access_level": "store_employee", "linked_at": "2024-11-15T10:30:01.000Z" } ], "failed_links": [ { "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0", "error": "Store not found or not accessible", "error_code": "STORE_NOT_FOUND" } ] } ``` ### Multi-Store Employee Types Manages operations across multiple store locations Typically needs manager-level access to all assigned stores Oversees store performance and compliance across a region May need administrative access for reporting and auditing Works at different stores as needed for coverage Usually assigned basic employee access to maintain flexibility Provides technical or operational support across multiple locations Access should be limited to specific functions they support Conducts training programs at multiple store locations May need temporary elevated access for training purposes ### Batch Operation Benefits Create multiple employee relationships in a single API call Reduces API calls and improves performance Ensures consistent access levels across all linked stores Reduces configuration errors and access inconsistencies Either all stores link successfully or the operation fails safely Prevents partial failures that could cause access issues Creates comprehensive audit log for multi-store employee setup Important for compliance and security tracking ### Validation and Error Handling All store\_ids must belong to the specified company\_id Cross-company linking is not permitted for security All stores must be active and accessible to the requesting user Inactive or restricted stores will be skipped Employee ID must be unique across the system Prevents conflicts and ensures proper identification User ID must correspond to an existing, active user Verify user exists before attempting multi-store linking ### Use Cases Set up area managers or regional supervisors with access to multiple stores Common during leadership team expansion Create flexible staff assignments for busy periods Allows employees to work at multiple locations as needed Grant technical or operational support teams access to multiple stores Useful for maintenance, training, or technical support roles Set up franchise owners or operators with access to all their locations Ensure proper authorization for franchise relationships ### Error Recovery Check failed\_links array to identify stores that didn't link successfully Common failures include inactive stores or permission issues Use single-store linking endpoint for failed stores after resolving issues May require different access levels or additional permissions Confirm that successful links provide the expected access Test access to ensure employee can perform required functions **Partial Success Handling:** This endpoint can succeed partially - some stores may link successfully while others fail. Always check both the count and failed\_links array. **Company Security:** All stores must belong to the same company for security reasons. Cross-company employee access requires separate authorization processes. **Performance Consideration:** While efficient for multiple stores, very large store lists may take longer to process. Consider batching for extremely large operations. # Link User to Store Source: https://developer.lulacommerce.com/api-reference/stores/store-employees/link-user-to-store PUT https://api-staging.luladelivery.store/stores/store-employees/{store_id} This endpoint links an existing user to a specific store, establishing their employee relationship and access permissions. This is used to assign employees to stores and grant them appropriate access levels for store operations. This endpoint creates an employee relationship between an existing user and a store. It's essential for managing store staff access and ensuring employees have the proper permissions to operate within their assigned stores. ### Path Parameters The unique identifier of the store to link the user to ### Request Body The ID of the existing user to link to the store Example: 1000049 The unique employee identifier (UUID format) for this user-store relationship Example: "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8" ### Request Example ```json { "user_id": 1000049, "employee_id": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8" } ``` ### Response Indicates whether the user was successfully linked to the store Details of the created employee relationship The store ID the user is now linked to The user ID that was linked The employee identifier for this relationship Access level granted to the employee When the link was created (ISO 8601 format) User ID of who created this link ### Response Example ```json { "success": true, "employee_relationship": { "store_id": "7669f473-6c40-45ee-8737-43c667407b3a", "user_id": 1000049, "employee_id": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8", "access_level": "store_employee", "linked_at": "2024-11-15T10:30:00.000Z", "linked_by": "1000001" } } ``` ### Employee Access Levels Basic store employee access - can process orders and manage inventory Standard access for front-line employees Store manager access - can manage employees and store settings Elevated access for store management personnel Administrative access - full control over store operations High-level access should be granted carefully Restricted access for specific functions only Useful for part-time or specialized roles ### Prerequisites The user\_id must correspond to an existing user in the system Users must be created before they can be linked to stores The employee\_id should be a valid UUID format Invalid UUID formats will be rejected The target store should be active and properly configured Linking to inactive stores may cause access issues Requesting user must have permission to manage store employees Typically requires store manager or admin level access ### Post-Linking Effects User gains access to store-specific functions and data Access is immediate upon successful linking User is assigned appropriate role-based permissions Permissions are based on the assigned access level Employee relationship is logged for compliance and tracking All employee changes are tracked for security purposes User appears in store employee lists and management interfaces Integration with POS and management systems is automatic ### Use Cases Link new hires to their assigned store locations Part of the standard employee onboarding process Move existing employees between store locations May require unlinking from previous store first Assign employees to stores for temporary coverage Can be reversed when temporary assignment ends Grant specific users access to store operations Ensure access levels match job responsibilities ### Error Scenarios The specified user\_id doesn't exist **Status Code:** 404 **Solution:** Verify user ID or create user first The specified store\_id doesn't exist **Status Code:** 404 User is already linked to this store **Status Code:** 409 **Solution:** Update existing relationship instead The employee\_id format is invalid **Status Code:** 400 **Solution:** Ensure employee\_id is a valid UUID User lacks permission to link employees to stores **Status Code:** 403 **Immediate Access:** Once successfully linked, users gain immediate access to store functions based on their assigned access level. **Security Consideration:** Ensure employee IDs are unique and securely generated to prevent unauthorized access or conflicts. **Audit Compliance:** All employee linking activities are logged for security audits and compliance requirements. # Update Store Source: https://developer.lulacommerce.com/api-reference/stores/update-store PUT https://api-staging.luladelivery.store/stores/{store_id}?company_id={company_id} This endpoint updates an existing store's information including basic details, contact information, and addresses. You can modify store properties while maintaining operational continuity and preserving existing integrations. This endpoint allows you to update various aspects of a store's configuration including name, contact details, point of contact, and addresses. Address updates support both modifying existing addresses and adding new ones. ### Path Parameters The unique identifier of the store to update ### Query Parameters The company ID that owns this store for authorization purposes Updated store name. Example: "bulk ingest test #1" Updated store contact email address. Example: "[0001@bulkingest.com](mailto:0001@bulkingest.com)" Updated store contact phone number. Example: "+12679397993" Updated point of contact user ID. Example: 1000418 Updated address information. Can include existing addresses (with IDs) and new addresses (without IDs) Existing address ID to update. Set to `null` for new addresses Primary address line. Example: "102 W. Mission Ave." City name. Example: "Escondido" State or province. Example: "CA" ZIP or postal code. Example: "92025" Type of address: * `0` = Store Address (main operational address) * `1` = Welcome Package Address (shipping address) ### Request Example ```json { "name": "bulk ingest test #1", "email": "0001@bulkingest.com", "phone_number": "+12679397993", "point_of_contact": 1000418, "addresses": [ { "id": "b6197e9c-8e68-47fe-8dd7-e057d07197ea", "line_1": "102 W. Mission Ave.", "city": "Escondido", "state": "CA", "zip": "92025", "address_type": 0 }, { "id": null, "line_1": "102 W. Mission Ave.", "city": "Escondido", "state": "CA", "zip": "92025", "address_type": 1 } ] } ``` ### Response Indicates whether the update operation was successful ### Response Example ```json { "success": true } ``` ### Address Update Behavior When `id` is provided: Updates the existing address with new information Only the provided fields will be updated When `id` is `null`: Creates a new address record and associates it with the store New addresses will be assigned unique IDs automatically To remove an address: Don't include it in the addresses array Removing the primary store address may affect operations ### Update Impact Basic store details like name, email, and phone number Point of contact can be reassigned to different users Existing addresses are modified, new addresses are created Delivery service partner configurations remain unchanged Store operational status and settings are maintained ### Best Practices Only include fields you want to change Omitted fields will retain their current values Always include existing address IDs when updating addresses Forgetting to include an address ID may create duplicates Verify that the new point\_of\_contact user exists and has appropriate permissions Invalid user IDs will result in update failure Perform updates during low-activity periods to minimize operational impact Store updates don't affect ongoing orders ### Error Scenarios The specified store\_id doesn't exist **Status Code:** 404 The store doesn't belong to the specified company\_id **Status Code:** 403 The point\_of\_contact user ID doesn't exist **Status Code:** 400 Address information is incomplete or invalid **Status Code:** 400 **Operational Continuity:** Store updates are designed to maintain operational continuity. Existing orders, inventory, and partner integrations continue functioning normally during and after updates. **Audit Trail:** All store updates are logged for compliance and troubleshooting purposes. Update timestamps and user information are automatically recorded. # Get Started Source: https://developer.lulacommerce.com/documentation/get-started This guide walks you through the fastest path to value: loading your products, creating a menu, and syncing to your sales channels with Lula Commerce. # Getting Started with Lula Commerce Welcome to Lula Commerce! This guide will help you set up your digital commerce platform and get your store operational across multiple sales channels quickly and efficiently. Lula Commerce is a world-class digital commerce platform that helps retailers win online without the operational burden. Our platform integrates with major delivery services like DoorDash, Uber Eats, and Grubhub, while also providing enterprise-grade direct ordering capabilities. This guide assumes you're working with both our dashboard interface and API. If you prefer to automate your setup end-to-end, browse our [API Documentation](/api-reference) and copy sample requests from each page. ## Before You Begin Before starting your Lula Commerce journey, ensure you have the following: A Lula account with access to your company and stores If you don't have access, request credentials from your Lula representative Your product list in CSV or JSON format including: * Product names * Prices * UPCs/SKUs * Categories * Descriptions (optional) Having high-quality product images will improve customer experience Know which delivery channels you plan to use: * **DoorDash** - Popular food delivery platform * **Uber Eats** - Ride-sharing company's delivery service * **Grubhub** - Established food delivery network * **Lula Direct** - Your own branded ordering platform You can start with one channel and add others later Complete store details including: * Store name and contact information * Physical address * Operating hours * Tax rates for your jurisdiction ## Step 1: Create Your Company and Store Your organization needs to be set up in Lula before you can start selling. This involves creating a company record and at least one store location. ### Company Setup If your organization isn't in Lula yet, your Lula contact will create it for you. For developers or those with API access: ```bash Create Company curl -X POST "https://api.lulacommerce.com/stores/company" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Your Company Name", "email": "contact@yourcompany.com", "phone_number": "+1234567890", "address": { "line_1": "123 Main Street", "city": "Your City", "state": "Your State", "zip": "12345" } }' ``` 📖 **Learn more:** [Create Company API](/api-reference/companies/create-company) ### Store Setup Each physical location needs its own store record: ```bash Create Store curl -X POST "https://api.lulacommerce.com/stores/store/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Your Store Name", "email": "store@yourcompany.com", "phone_number": "+1234567890", "company_id": 1000001, "addresses": [ { "line_1": "123 Store Street", "city": "Store City", "state": "Store State", "zip": "54321", "address_type": 0 } ] }' ``` 📖 **Learn more:** [Create Store API](/api-reference/stores/create-store) Make sure your store details are accurate before proceeding. Incorrect addresses can affect delivery zones and tax calculations. ## Step 2: Load Your Products Choose the import method that works best for your current data format. You can always change formats or update products later. ### CSV Import (Recommended for Spreadsheet Users) If you manage your products in Excel or Google Sheets, CSV import is the fastest option: ```bash Upload CSV curl -X POST "https://api.lulacommerce.com/inventory/ingestion/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@your-products.csv" \ -F "store_id=YOUR_STORE_ID" ``` **CSV Format Requirements:** ```csv name,category,size,quantity,price,external_id,upc,image_url "Coca Cola Classic","Beverages","12 oz",99,265,"CC12OZ","049000012521","https://example.com/coke.jpg" ``` 📖 **Learn more:** [Upload CSV](/api-reference/endpoint/upload-csv) ### JSON Import (Recommended for Developers) For programmatic integration or complex product data: ```bash Upload JSON curl -X POST "https://api.lulacommerce.com/inventory/ingestion/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "name": "Coca Cola Classic", "category": "Beverages", "size": "12 oz", "quantity": 99, "price": 265, "external_id": "CC12OZ", "upc": "049000012521" } ] }' ``` 📖 **Learn more:** [Upload JSON](/api-reference/endpoint/upload-json) ### Update Inventory and Prices After your initial import, you can update inventory levels and prices: ```bash Update Inventory curl -X POST "https://api.lulacommerce.com/catalog/upsert-inventory" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "store_id": "YOUR_STORE_ID", "items": [ { "external_id": "CC12OZ", "quantity": 75, "price": 275 } ] }' ``` 📖 **Learn more:** [Upsert Inventory](/api-reference/catalog/upsert-inventory) ### Verify Your Import After importing, verify your products loaded correctly: ```bash Get Store Inventory curl -X GET "https://api.lulacommerce.com/catalog/store-inventory/YOUR_STORE_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` 📖 **Learn more:** [Get Store Inventory](/api-reference/catalog/get-store-inventory) ## Step 3: Build Your Menu Menus organize your products for customer-facing ordering. You can create different menus for different channels or times of day. ### Create a Store Menu ```bash Create Menu curl -X POST "https://api.lulacommerce.com/menus/store-menu" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "store_id": "YOUR_STORE_ID", "menu_name": "Main Menu", "description": "Our complete product selection" }' ``` 📖 **Learn more:** [Create Store Menu](/api-reference/menus/create-store-menu) ### Add Menu Items Link your products to menu categories: ```bash Create Menu Item curl -X POST "https://api.lulacommerce.com/menus/menu-items" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "menu_id": "YOUR_MENU_ID", "product_id": "YOUR_PRODUCT_ID", "category": "Beverages", "display_order": 1 }' ``` 📖 **Learn more:** [Create Menu Item](/api-reference/menus/menu-items/create-menu-item) ### Set Menu Schedules Configure when your menu is available: ```bash Get Menu Timings curl -X GET "https://api.lulacommerce.com/menus/store-menu-timings/YOUR_STORE_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` 📖 **Learn more:** [Get Store Menu Timings](/api-reference/menus/get-store-menu-timings) ## Step 4: Sync to Sales Channels Once your menu is ready, publish it to your connected delivery channels. ### Sync All Channels ```bash Sync Menus for All Stores curl -X POST "https://api.lulacommerce.com/menus/sync-all-stores" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "company_id": "YOUR_COMPANY_ID" }' ``` 📖 **Learn more:** [Sync Menu for All Stores](/api-reference/menus/sync-menu-for-all-stores) ### Verify Active Menus Confirm your menus are live on all channels: ```bash Get Active Menus curl -X GET "https://api.lulacommerce.com/menus/active-menus/YOUR_STORE_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` 📖 **Learn more:** [Get All Active Menu of Store](/api-reference/menus/get-all-active-menu-of-store) ## Step 5: Test Your Setup Before going live, test the complete order flow to ensure everything works correctly. ### Monitor Incoming Orders ```bash Get Incoming Orders curl -X GET "https://api.lulacommerce.com/orders/incoming" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d "store_id=YOUR_STORE_ID" ``` 📖 **Learn more:** [Get Incoming Orders](/api-reference/orders/get-incoming-orders) ### Accept and Process Orders ```bash Accept Order curl -X POST "https://api.lulacommerce.com/orders/accept" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "order_id": "ORDER_ID", "estimated_pickup_time": "2024-01-15T14:30:00Z" }' ``` 📖 **Learn more:** [Accept Incoming Order](/api-reference/orders/accept-incoming-order) ### View Order Details ```bash Get Order Details curl -X GET "https://api.lulacommerce.com/orders/ORDER_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` 📖 **Learn more:** [Get Order Details](/api-reference/orders/get-order-details) **Testing Strategy**: Use marketplace sandbox environments when available, or place a small real order to validate the complete flow from order placement to fulfillment. ## Environments Lula supports both sandbox and production environments to ensure safe testing and reliable operations. Safe testing environment for development and testing * Test API calls without affecting real data * Practice order fulfillment workflows * Validate integrations before going live Ask your Lula contact for sandbox access if you don't have it yet Live environment for actual business operations * Real customer orders and payments * Live inventory management * Actual delivery partner integration Always test thoroughly in sandbox before deploying to production ## What's Next? Once your basic setup is complete, you can enhance your store with advanced features: ### Fine-tune Your Operations Add size options, toppings, and customizations to your products Set up accurate tax rates for your jurisdiction Launch marketing campaigns to drive sales Monitor performance and gain insights ### Advanced Store Management Manage multiple locations from one platform Set up staff access and permissions Automate inventory updates and management Advanced order processing and fulfillment ## Getting Help Complete API reference with examples Help articles and troubleshooting guides Get in touch with our team **Need personalized assistance?** Your Lula representative is available to help with setup questions, best practices, and optimization strategies. Don't hesitate to reach out! # High-Level Architecture Source: https://developer.lulacommerce.com/documentation/high-level-architecture Understanding Lula Commerce's architecture, core components, data flow, and how we connect your stores to every delivery channel. ## Lula at a Glance Lula Commerce sits between your stores and every delivery channel, acting as a **single source of truth** for products, menus, and orders. You manage items and pricing once in Lula; we publish consistent data everywhere and consolidate activity back into one place. This centralized approach eliminates data inconsistencies and reduces the operational overhead of managing multiple delivery platforms independently. ## Core Components Lula Commerce is built on a microservices architecture with specialized services handling different aspects of your digital commerce operations: Stores products, prices, inventory, and attributes Central repository for all product information across channels Builds store-specific menus, schedules, and availability windows Handles time-based menu variations and channel-specific customizations Receives, acknowledges, and tracks orders end-to-end Provides unified order management regardless of originating channel Applies discounts and offers across channels Promotions are synchronized across all connected platforms Synchronize menus and orders with DoorDash, Uber Eats, Grubhub, and Lula Direct Each connector handles platform-specific integration requirements Push updates to your systems in real time Enables real-time integration with POS systems and other tools Combines data from all channels for performance insights Provides unified analytics across all sales channels ## Typical Data Flow Understanding how data moves through the Lula Commerce platform helps you optimize your operations and integrations: **Ingest products** via CSV/JSON upload or API integration Products are validated, categorized, and stored in the central catalog service. **Create or update menus** and schedules per store Store-specific menus are built from catalog products with custom availability and pricing. **Lula publishes menus** to connected channels Menus are automatically synchronized to DoorDash, Uber Eats, Grubhub, and Lula Direct. **Customers place orders** on a marketplace or via Lula Direct Orders are received from any connected channel and normalized into a standard format. **Orders flow into Lula**; you accept and fulfill from a single queue Unified order management regardless of the originating sales channel. **Status updates and receipts** are propagated back to the channel Real-time synchronization ensures customers receive accurate order status information. **Key Benefit**: This flow ensures **data** consistency across all platforms while providing you with a single interface to manage all operations. ## Security at a Glance Lula Commerce implements enterprise-grade security measures to protect your business data and customer information: * **Encryption in transit** using TLS * **Data access controlled** by role-based permissions * **Least-privilege access** for internal operations * **Scoped API keys** for server-to-server integrations * **Optional IP allowlisting** on request * **Industry best practices** for data protection Lula follows industry best practices for protecting data. If you need a security review or have a questionnaire, contact your Lula representative. ## Reliability and Scale Our platform is designed to grow with your business, from single-location operations to large multi-store chains: Built to support retailers from single stores to large chains Architecture scales horizontally to handle increased load Handle upstream rate limits and retries automatically Smart retry logic ensures reliable integration with delivery partners Health monitoring and alerting across all integrations Proactive monitoring prevents issues before they affect operations Scalable infrastructure to handle traffic spikes and growth High-volume launches require advance coordination with our team **Planning a high-volume launch or migration?** Let us know so we can align capacity and support to ensure a smooth transition. ## Integration Patterns Lula Commerce supports multiple integration approaches to fit your technical requirements: Direct API integration for real-time data exchange and custom workflows CSV/JSON uploads for bulk product updates and initial setup Push notifications for order updates and inventory changes Automated synchronization for regular data updates ## Performance Characteristics Typical response times under 200ms for standard operations Performance may vary based on request complexity and data volume Menu updates propagate to delivery channels within 5-15 minutes Sync times depend on individual platform processing speeds Orders are received and normalized in real-time (under 5 seconds) Fast order processing ensures quick customer confirmation 99.9% uptime SLA with redundant infrastructure Planned maintenance windows are communicated in advance ## Getting Started with Architecture Explore our comprehensive API reference Learn about integration options and best practices Follow our step-by-step setup guide **Need technical support?** Our engineering team is available to help with architecture questions, integration planning, and performance optimization. Contact your Lula representative for technical consultation. # Integrations Source: https://developer.lulacommerce.com/documentation/integrations Connect your stores to major delivery channels and third-party platforms with Lula Commerce's comprehensive integration ecosystem. ## Integrations Overview Lula connects your stores to major delivery channels so you can **manage one catalog and menu** and sell everywhere. Below is a high-level view of what each integration supports. Details vary by partner and region, but the workflows are similar. With Lula's unified approach, you configure once and reach customers across all major platforms without managing multiple integrations separately. ## Delivery Channel Integrations **Complete marketplace integration with full feature support** * **Menu sync**: Publish items, prices, and availability * **Store settings**: Hours, tax, and fees alignment * **Orders**: Receive, accept, cancel, and update status * **Inventory**: Mark items or modifiers out of stock Most comprehensive integration with real-time inventory management **Full-featured integration with advanced menu management** * **Menu sync**: Categories, items, options, and pricing * **Store settings**: Hours and service availability * **Orders**: Receive, accept, cancel, and update status * **Inventory**: Item availability updates Supports complex menu structures with modifiers and variants **Streamlined integration for essential operations** * **Menu sync**: Items, pricing, and schedules * **Store settings**: Service hours * **Orders**: Receive, accept, cancel, and update status Reliable integration with focus on core functionality **Unified under Uber Eats platform** * Seamless transition from legacy Postmates integration * All Uber Eats features available Legacy Postmates accounts migrated to Uber Eats ## Lula Direct Platform **Lula's direct-to-consumer experience** for your website or app. Use it to offer delivery or pickup without a marketplace middleman. **White-label ordering experience** * Customizable branding and styling * Mobile-responsive design * Seamless checkout process **Build custom experiences** * JavaScript/React components * Mobile app integration * API-first architecture **Catalog and pricing from Lula** Same products, prices, and availability as delivery channels Ensures consistency across all customer touchpoints **Orders and status updates** flow through the same queue Unified order management regardless of channel origin Reduces operational complexity with single order interface **Integrated payment solutions** Support for major payment providers and methods Secure, PCI-compliant payment processing built-in ## Third-Party Platform Integrations **POS and Inventory Systems** * PDI Technologies * SSCS Back-Office System * ADD Systems * Conexxus Standards **Secure Payment Solutions** * Stripe * Square * PayPal * Amazon Pay **Expanding Marketplace** * Amazon delivery services * Regional delivery platforms * Custom API integrations ## Integration Workflow Understanding the integration process helps you plan your rollout effectively: **Decide which channels** to enable per store Consider your target market, delivery zones, and customer preferences. **Confirm your pricing, taxes, and fees** Ensure consistent pricing strategy across all channels. **Load products and build your menus** in Lula Import existing catalog or create new menu structure. **Connect your channels** with your Lula representative Our team handles technical setup and credential management. **Publish and validate menus** in each marketplace Review menu appearance and pricing across all platforms. **Place one test order per channel** and confirm fulfillment End-to-end testing ensures smooth operations before launch. **Need help choosing channels or designing your rollout?** We're happy to advise based on what we see across the industry. ## Integration Capabilities by Category **Centralized menu control across all platforms** * Real-time menu synchronization * Platform-specific customizations * Scheduled menu changes * Bulk menu operations Changes made once in Lula propagate to all connected channels **Unified order management system** * Real-time order reception * Automated order acknowledgment * Status update propagation * Cancellation handling Single interface for orders from all channels **Real-time inventory synchronization** * Item availability updates * Modifier stock management * Automatic out-of-stock handling * Inventory level monitoring Prevents overselling across all platforms **Consolidated financial operations** * Unified reporting across channels * Commission and fee tracking * Tax calculation and compliance * Settlement reconciliation Financial data aggregated for simplified accounting ## API Integration Options For businesses requiring custom integrations or advanced functionality: **Full-featured REST APIs** * Complete CRUD operations * Real-time data access * Webhook notifications * Comprehensive documentation **Efficient bulk data management** * CSV/JSON file uploads * Batch processing * Data validation * Import/export tools ## Integration Support Comprehensive API reference and integration guides Work with our team to build seamless integrations SDKs, testing environments, and technical support ## Getting Started with Integrations **Evaluate which integrations** will benefit your business most Consider your current channels, customer base, and growth plans. **Reach out to our integration team** We'll help you design the optimal integration strategy. **Follow the integration checklist** Our team guides you through each step of the process. **Ready to integrate?** Contact your Lula representative to start connecting your preferred channels and platforms. Our integration specialists will ensure a smooth setup process tailored to your business needs. ## Performance and Reliability **Menu updates** propagate within 5-15 minutes across channels Sync times vary by platform processing speeds **Orders received** and processed in real-time (under 5 seconds) Fast order processing ensures quick customer confirmation **99.9% integration uptime** with automatic failover Resilient connections maintain service during partner outages **Automatic retry logic** for failed operations Smart retry mechanisms prevent data loss **Questions about specific integrations?** Our technical team can provide detailed information about platform-specific features, limitations, and best practices. Contact us for integration consultation. # Lula Direct SDK Source: https://developer.lulacommerce.com/documentation/lula-direct-sdk Integrate Lula Direct's first-party eCommerce delivery platform into your React Native, iOS, and Android applications with our comprehensive SDK. ## Overview The Lula Direct SDK provides everything you need to embed a **branded shopping experience** directly into your mobile or web applications. Built for React Native, iOS (Swift), and Android (Kotlin), the SDK offers complete control over your digital storefront while leveraging Lula's powerful commerce platform. The SDK handles authentication, deep linking, order processing, and native payment integration automatically - allowing you to launch a branded ordering experience in under a week. ## When to Use Lula Direct SDK **Native mobile experiences** * Embed storefront in React Native apps * Native iOS (Swift) integration * Native Android (Kotlin) integration * Seamless in-app shopping **Pre-built components** * Complete WebView-based storefront * Automatic JWT authentication * Ready-to-use order flows * Launch in under a week **White-label control** * Your app, your brand * Custom WebView configuration * Deep linking to products * Native payment integration **Minimal code required** * Single component implementation * Handles authentication automatically * Built-in order management * Real-time inventory sync ## Getting Started Follow these steps to integrate Lula Direct SDK into your application: **Add the SDK and required packages** ```bash npm theme={null} npm install @lula-commerce/direct-sdk react-native-webview @react-native-async-storage/async-storage expo-jwt ``` ```bash yarn theme={null} yarn add @lula-commerce/direct-sdk react-native-webview @react-native-async-storage/async-storage expo-jwt ``` For native iOS/Android integration, you'll also need: * iOS: JWTKit library * Android: Auth0 JWT library **Provide your application credentials** Required: * `secretKey` - JWT signing key (≥32 characters) * `appBundleId` - Your app's bundle identifier * `memberId` - Your Lula member ID Store your secret key securely. Never commit it to version control. **Configure the SDK when your app starts** ```javascript Production theme={null} import { initLulaSDK } from "@lula-commerce/direct-sdk"; initLulaSDK({ secretKey: process.env.LULA_SECRET_KEY, appBundleId: "com.yourcompany.app" }, true); ``` ```javascript Development theme={null} import { initLulaSDK } from "@lula-commerce/direct-sdk"; initLulaSDK({ secretKey: "dev-secret-key-at-least-32-characters-long", appBundleId: "com.yourcompany.app.dev", baseUrl: "http://localhost:3000" // Optional }); ``` Store secret keys securely using environment variables **Add LulaDirectView component to your app** ```javascript React Native theme={null} import { LulaDirectView } from "@lula-commerce/direct-sdk"; function StoreScreen() { return ( { console.log("Order:", order); // Navigate to confirmation }} enableApplePay={true} enableGooglePay={true} /> ); } ``` **Validate your integration** * Test order flows end-to-end * Verify payment methods (Apple Pay/Google Pay) * Test deep linking to products/categories * Validate error handling * Deploy to production Use development environment for testing before production deployment ## Core Concepts ### How It Works The Lula Direct SDK uses a WebView-based approach to embed the Lula storefront into your native application. Here's how the key components work together: The SDK generates secure JWT tokens using your `secretKey` and `appBundleId`. These tokens authenticate API requests and contain customer information for personalized experiences. `LulaDirectView` renders the Lula storefront in a React Native WebView with automatic authentication, deep linking support, and bi-directional message passing. JWT tokens are cached in AsyncStorage for 24 hours (configurable) to minimize regeneration and improve performance. When a cached token expires, the SDK automatically generates a new token and caches it. The WebView sends events (order completion, missing data) to your app via `postMessage`, triggering your callback functions. ### Key Features **Seamless embedding** * React Native WebView component * Automatic authentication * Deep linking support * Native payment methods **Secure token-based auth** * Automatic token generation * Token caching with expiration * HS256 signing algorithm * 24-hour default expiry **Complete order handling** * Order completion callbacks * Real-time status updates * Cart modification support * Order history access **Platform-specific payments** * Apple Pay (iOS) * Google Pay (Android) * Secure payment processing * PCI compliance built-in ## API Reference ### Component Props #### `LulaDirectView` The main React Native component for embedding the Lula Direct storefront. It handles WebView initialization, JWT authentication, URL construction, and message passing between the native app and the web storefront. | Prop | Type | Required | Default | Description | | ----------------- | -------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `memberId` | string | **Yes** | - | Your Lula member ID for authentication. Used in URL construction and JWT payload. | | `storeId` | string | No | - | Specific store ID to display. If omitted, the storefront may show all stores for the member or a default store. | | `hideNav` | boolean | No | `true` | Controls visibility of the Lula navigation bar in the embedded storefront. | | `customerInfo` | object | No | `{}` | Customer details used for JWT authentication and pre-filling checkout information. See CustomerInfo interface below. | | `deepLinkPath` | string | No | - | Path to navigate to within the storefront (e.g., `/product/123`, `/category/beer`). Encoded as both a JWT claim and URL parameter. | | `onOrderComplete` | function | No | - | Callback fired when an order is successfully completed. Receives order data parsed from WebView message with type `ORDER_COMPLETE`. | | `onMissingData` | function | No | - | Callback fired when the storefront requires additional customer information. Receives field names from WebView message with type `MISSING_DATA`. | | `enableApplePay` | boolean | No | `false` | Enables Apple Pay support on iOS. Sets `allowsBackForwardNavigationGestures` to true. | | `enableGooglePay` | boolean | No | `false` | Enables Google Pay support on Android. Reserved for future Google Pay-specific WebView settings. | | `sdkConfig` | object | No | - | Partial SDK configuration to override global settings for this instance. See LulaSDKConfig below. | | `storeUrl` | string | No | - | **Deprecated**. Base URL override for the Lula service. Use `sdkConfig.baseUrl` instead. | #### `CustomerInfo` Interface Customer information object passed to `LulaDirectView`. All fields are optional and used to pre-populate the storefront and generate the JWT token. Customer's full name. Included in JWT payload as `member.name` for pre-filling checkout forms. Customer's email address. Included in JWT payload as `member.email` for account identification and order confirmations. Customer's phone number. Included in JWT payload as `member.phone` for delivery updates and customer service. Customer's address object. Included in JWT payload as `member.address` for delivery and billing purposes. Primary address line (street address) Secondary address line (apartment, suite, etc.) City name State or province code ZIP or postal code Country code or name Age verification flag indicating if customer is 21 years or older. Required for purchasing restricted products like alcohol. Included in JWT payload as `member.age21`. Setting this to false or omitting it may prevent purchase of age-restricted items ```typescript TypeScript Interface theme={null} interface CustomerInfo { name?: string; email?: string; phone?: string; address?: { line1?: string; line2?: string; city?: string; state?: string; postalCode?: string; country?: string; }; age21?: boolean; } ``` #### WebView Message Events The component listens for messages from the WebView and triggers callbacks based on the message type: **Fired when**: An order is successfully completed in the storefront **Callback**: `onOrderComplete(order)` **Payload**: Order object containing order details (structure determined by Lula backend) ```javascript Example Handler theme={null} onOrderComplete={(order) => { console.log("Order ID:", order.id); console.log("Total:", order.total); // Navigate to confirmation screen navigation.navigate('OrderConfirmation', { orderId: order.id }); }} ``` **Fired when**: The storefront requires additional customer information **Callback**: `onMissingData(fields)` **Payload**: Array or object containing field names that need to be provided ```javascript Example Handler theme={null} onMissingData={(fields) => { console.log("Required fields:", fields); // Show form to collect missing information setMissingFields(fields); setShowDataModal(true); }} ``` ### SDK Configuration #### `initLulaSDK(config, isProd?)` Initialize the SDK with configuration options. This should be called once when your application starts, before using `LulaDirectView`. **Parameters:** * `config` (Partial\) - Configuration object with properties to override * `isProd` (boolean, optional) - If `true`, uses production defaults; otherwise uses development defaults **Returns:** Complete `LulaSDKConfig` object with merged configuration Base URL for the Lula Direct service. All storefront URLs are constructed by appending paths to this base. **Default Values:** * Development: `https://dev.lulacommerce.com` * Production: `https://client.lulacommerce.com` Can be overridden for local development (e.g., `http://localhost:8000`) Secret key used for JWT signing with HS256 algorithm. **Must be at least 32 characters long.** **Security Requirements:** * Store securely using environment variables * Never hardcode in client-side code for production * Consider backend JWT generation for sensitive applications **Default Values:** * Development: `dev-secret-key-at-least-32-characters-long` * Production: **Must be provided** (no default) Production apps must provide a secure secret key Your application's bundle identifier (iOS) or package name (Android). Used as the JWT `iss` (issuer) claim. **Examples:** * iOS: `com.yourcompany.yourapp` * Android: `com.yourcompany.yourapp` **Default Values:** * Development: `com.yourapp.dev` * Production: **Must be provided** (no default) JWT token expiration time in minutes. Tokens are cached and reused until expiration. **Default:** `1440` (24 hours) **Considerations:** * Longer expiry = fewer token regenerations but potential security concerns * Shorter expiry = more frequent regenerations but better security * Cached tokens are automatically cleared on user logout via `clearLulaJWTCache()` Default deep link path used when no `deepLinkPath` is specified in `generateLulaJWT()`. **Default:** `/store/default` **Examples:** * `/store/123` * `/category/featured` * `/product/new-arrivals` ```javascript Development Setup theme={null} import { initLulaSDK } from "@lula-commerce/direct-sdk"; initLulaSDK({ secretKey: "your-dev-secret-key-at-least-32-chars", appBundleId: "com.yourcompany.app.dev", baseUrl: "http://localhost:3000", // Optional: for local testing }); ``` ```javascript Production Setup theme={null} import { initLulaSDK } from "@lula-commerce/direct-sdk"; initLulaSDK( { secretKey: process.env.LULA_SECRET_KEY, appBundleId: "com.yourcompany.app", }, true // Use production defaults ); ``` ### Utility Functions #### `generateLulaJWT(config)` Generates a JWT token for Lula Direct authentication using the HS256 algorithm. The token is automatically cached in AsyncStorage and reused until expiration. **Parameters:** `LulaJWTConfig` object **Returns:** `Promise` - The JWT token **Behavior:** 1. Checks AsyncStorage for a valid cached token 2. If cached token exists and hasn't expired, returns it immediately 3. Otherwise, generates a new token with the current timestamp 4. Caches the new token with its expiration timestamp 5. Returns the token **JWT Payload Structure:** ```json theme={null} { "iss": "com.yourapp.bundle", // From sdkConfig.appBundleId "aud": "lula-direct", // Fixed audience "exp": 1234567890, // Expiration timestamp "iat": 1234567890, // Issued at timestamp "member": { "id": "memberId", // From config.memberId "name": "John Doe", // From config.userName "email": "john@example.com", // From config.userEmail "phone": "5551234567", // From config.userPhone "address": {...}, // From config.userAddress "age21": true // From config.isAdult }, "hideNav": true, // From config.hideNav "path": "/category/beer" // From config.deepLinkPath } ``` Member ID for authentication. If not provided, defaults to `"user123"` (not recommended for production). User's display name. Included in JWT `member.name` claim. User's email address. Included in JWT `member.email` claim. User's phone number. Included in JWT `member.phone` claim. User's address object. Included in JWT `member.address` claim. Structure is flexible. Age verification flag. Included in JWT `member.age21` claim. Whether to hide navigation in the storefront. Included in JWT `hideNav` claim. Path to navigate to. Included in JWT `path` claim. Falls back to `sdkConfig.defaultPath` if not provided. ```javascript Basic Usage theme={null} import { generateLulaJWT } from "@lula-commerce/direct-sdk"; const jwt = await generateLulaJWT({ memberId: "YOUR_MEMBER_ID", userName: "Jane Doe", userEmail: "jane@example.com", isAdult: true }); ``` ```javascript With Deep Linking theme={null} const jwt = await generateLulaJWT({ memberId: "MEMBER_123", userName: "John Smith", userEmail: "john@example.com", userPhone: "5551234567", isAdult: true, deepLinkPath: "/category/beer" }); ``` #### `getLulaUrl(path)` Constructs a full URL by combining the configured `baseUrl` with the provided path. Automatically handles path formatting. **Parameters:** * `path` (string) - Relative path (e.g., `/product/123`) **Returns:** `string` - Complete URL **Behavior:** * Ensures path starts with `/` * Handles company-specific subdomains (`.lulacommerce.com`) * Works with custom development URLs ```javascript Example theme={null} import { getLulaUrl } from "@lula-commerce/direct-sdk"; // With production config (baseUrl: https://client.lulacommerce.com) const url = getLulaUrl("/product/XYZ789"); // Returns: "https://client.lulacommerce.com/product/XYZ789" // With custom config (baseUrl: http://localhost:3000) const localUrl = getLulaUrl("store/123"); // Returns: "http://localhost:3000/store/123" ``` #### `clearLulaJWTCache()` Clears the cached JWT token and its expiration timestamp from AsyncStorage. Should be called when the user logs out or switches accounts to ensure a fresh token is generated on next login. **Parameters:** None **Returns:** `Promise` **Storage Keys Cleared:** * `lula_jwt_token` - The cached JWT token string * `lula_jwt_expiry` - The token expiration timestamp ```javascript On Logout theme={null} import { clearLulaJWTCache } from "@lula-commerce/direct-sdk"; async function handleLogout() { // Clear user session await clearUserSession(); // Clear Lula JWT cache await clearLulaJWTCache(); // Navigate to login navigation.navigate('Login'); } ``` ```javascript On User Switch theme={null} async function switchUser(newUserId) { // Clear cached token for previous user await clearLulaJWTCache(); // Load new user data const userData = await loadUserData(newUserId); // SDK will generate new token with new user's info setCurrentUser(userData); } ``` ## Advanced Usage ### Manual URL Generation For custom WebView setups or external browser opening: ```javascript Example theme={null} import { generateLulaJWT, getLulaUrl } from "@lula-commerce/direct-sdk"; async function getAuthenticatedStoreUrl() { const jwt = await generateLulaJWT({ memberId: "YOUR_MEMBER_ID", userName: "Jane Doe", userEmail: "jane@example.com", deepLinkPath: "/category/beer" }); const storePath = `/us/q?memberID=YOUR_MEMBER_ID&storeID=STORE_123&hideNav=true&token=${jwt}`; const fullUrl = getLulaUrl(storePath); return fullUrl; } ``` The JWT token is appended as a `token` query parameter for authentication. ## Native Platform Integration ### iOS (Swift) Implementation #### Configuration ```swift Swift theme={null} struct LulaConfig { static let BASE_URL = "https://client.lulacommerce.com" static let SECRET_KEY = "YOUR_SECRET_KEY" static let APP_BUNDLE_ID = "com.yourcompany.yourapp" static let JWT_EXPIRY = 1440 // 24 hours in minutes } ``` #### JWT Generation ```swift Swift theme={null} import JWTKit func generateLulaJWT( memberId: String, customerInfo: [String: Any], deepLinkPath: String? = nil ) throws -> String { let now = Date() let expiryDate = Calendar.current.date( byAdding: .minute, value: LulaConfig.JWT_EXPIRY, to: now ) ?? now let payload = LulaJWTPayload( iss: IssuerClaim(value: LulaConfig.APP_BUNDLE_ID), aud: AudienceClaim(value: "lula-direct"), exp: ExpirationClaim(value: expiryDate), iat: IssuedAtClaim(value: now), member: MemberClaim( id: memberId, name: customerInfo["name"] as? String, email: customerInfo["email"] as? String, phone: customerInfo["phone"] as? String, age21: customerInfo["age21"] as? Bool ?? false ), hideNav: true, path: deepLinkPath ?? "/store/default" ) let signers = JWTSigners() signers.use(.hs256(key: LulaConfig.SECRET_KEY.data(using: .utf8)!)) return try signers.sign(payload) } ``` #### WebView Integration ```swift Swift theme={null} import WebKit class LulaWebViewController: UIViewController, WKScriptMessageHandler { private var webView: WKWebView! override func viewDidLoad() { super.viewDidLoad() let config = WKWebViewConfiguration() let contentController = WKUserContentController() contentController.add(self, name: "lulaBridge") config.userContentController = contentController webView = WKWebView(frame: view.bounds, configuration: config) view.addSubview(webView) do { let jwt = try generateLulaJWT( memberId: "YOUR_MEMBER_ID", customerInfo: [ "name": "John Doe", "email": "john@example.com", "age21": true ] ) let url = "\(LulaConfig.BASE_URL)/us/q?memberID=YOUR_MEMBER_ID&hideNav=true&token=\(jwt)" webView.load(URLRequest(url: URL(string: url)!)) } catch { print("Error generating JWT: \(error)") } } func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) { guard let body = message.body as? [String: Any], let type = body["type"] as? String else { return } switch type { case "orderComplete": if let order = body["order"] as? [String: Any] { print("Order completed: \(order)") } case "missingData": if let fields = body["fields"] as? [String] { print("Missing data: \(fields)") } default: break } } } ``` ### Android (Kotlin) Implementation #### Configuration ```kotlin Kotlin theme={null} object LulaConfig { const val BASE_URL = "https://client.lulacommerce.com" const val SECRET_KEY = "YOUR_SECRET_KEY" const val APP_BUNDLE_ID = "com.yourcompany.yourapp" const val JWT_EXPIRY = 1440 // 24 hours in minutes } ``` #### JWT Generation ```kotlin Kotlin theme={null} import com.auth0.jwt.JWT import com.auth0.jwt.algorithms.Algorithm import java.util.Date fun generateLulaJWT( memberId: String, customerInfo: Map, deepLinkPath: String? = null ): String { val nowMillis = System.currentTimeMillis() val expiryMillis = nowMillis + (LulaConfig.JWT*EXPIRY * 60 \_ 1000) val algorithm = Algorithm.HMAC256(LulaConfig.SECRET_KEY) val memberClaim = mapOf( "id" to memberId, "name" to (customerInfo["name"] as? String), "email" to (customerInfo["email"] as? String), "phone" to (customerInfo["phone"] as? String), "age21" to (customerInfo["age21"] as? Boolean ?: false) ) return JWT.create() .withIssuer(LulaConfig.APP_BUNDLE_ID) .withAudience("lula-direct") .withIssuedAt(Date(nowMillis)) .withExpiresAt(Date(expiryMillis)) .withClaim("member", memberClaim) .withClaim("hideNav", true) .withClaim("path", deepLinkPath ?: "/store/default") .sign(algorithm) } ``` #### WebView Integration ```kotlin Kotlin theme={null} import android.webkit.JavascriptInterface import android.webkit.WebView import android.webkit.WebViewClient import androidx.appcompat.app.AppCompatActivity class LulaWebViewActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val webView = WebView(this) setContentView(webView) webView.settings.apply { javaScriptEnabled = true domStorageEnabled = true } webView.webViewClient = WebViewClient() webView.addJavascriptInterface(LulaBridge(), "lulaBridge") val jwt = generateLulaJWT( memberId = "YOUR_MEMBER_ID", customerInfo = mapOf( "name" to "John Doe", "email" to "john@example.com", "age21" to true ) ) val url = "${LulaConfig.BASE_URL}/us/q?memberID=YOUR_MEMBER_ID&hideNav=true&token=$jwt" webView.loadUrl(url) } inner class LulaBridge { @JavascriptInterface fun postMessage(json: String) { // Parse JSON and handle orderComplete/missingData events } } } ``` ## Security Considerations **Important Security Guidelines** ### Secret Key Management 1. **Never hardcode production keys** in client-side code 2. **Use environment variables** for configuration 3. **Consider backend JWT generation** for production apps 4. **Use secure storage**: * iOS: Keychain * Android: EncryptedSharedPreferences * React Native: react-native-encrypted-storage ### WebView Security ```javascript React Native // WebView security settings theme={null} { const { nativeEvent } = syntheticEvent; console.error("WebView error: ", nativeEvent); }} /> ``` ### JWT Best Practices * Monitor token expiration (default: 24 hours) * Clear tokens on user logout * Implement token refresh mechanisms * Validate token structure and claims ## Troubleshooting ### Common Issues **Possible causes and solutions:** * Verify `react-native-webview` is correctly installed and linked * Check `baseUrl` in `initLulaSDK` is correct and reachable * Ensure `memberId` is provided in `initLulaSDK` or `LulaDirectView` * Check console for errors during initialization or JWT generation **Token validation issues:** * Verify `secretKey` matches your Lula Direct account * Ensure `appBundleId` is correctly configured * Confirm `secretKey` is at least 32 characters long * Check JWT expiration (default: 24 hours) * Call `clearLulaJWTCache()` to refresh token **Navigation problems:** * Ensure `deepLinkPath` is a valid Lula Direct path: * `/store/STORE_ID` * `/product/PRODUCT_ID` * `/category/CATEGORY_ID` * Verify JWT generation includes the `deepLinkPath` * Check path format matches Lula's routing structure **Insufficient customer information:** * Provide complete `customerInfo` in `LulaDirectView` * Include required fields: `name`, `email`, `phone` * Add `age21` verification for restricted products * Check `onMissingData` callback for specific requirements **Apple Pay / Google Pay issues:** * Verify `enableApplePay` is set on iOS devices * Verify `enableGooglePay` is set on Android devices * Check device supports the payment method * Ensure payment credentials are configured in Lula ### Native Integration Issues **WebView not loading:** * Verify generated URL is correct * Check network connectivity and SSL certificates * Enable required WebView settings * Review WKWebView console logs **JWT generation errors:** * Verify JWTKit library is installed * Check secret key length (≥32 characters) * Ensure proper date handling for expiration * Validate payload structure **WebView not loading:** * Enable JavaScript and DOM storage * Check network permissions in manifest * Verify URL format and accessibility * Review WebView client logs **JWT generation errors:** * Verify Auth0 JWT library dependency * Check algorithm configuration (HS256) * Ensure proper time calculation * Validate claim structure ## Additional Resources REST API reference for custom integrations Platform integrations and capabilities Complete getting started guide ## Support **Need help?** Contact your Lula representative for: * SDK access and credentials * Technical implementation support * Production deployment coordination * Troubleshooting assistance The SDK is licensed under the MIT License. # Welcome to Lula Commerce Source: https://developer.lulacommerce.com/documentation/welcome-intro Your comprehensive guide to growing delivery sales and simplifying operations with Lula Commerce's unified platform for convenience retailers. ## Platform Overview Lula Commerce helps **convenience retailers grow delivery sales** and simplify operations by unifying products, menus, pricing, and orders across delivery channels like DoorDash, Uber Eats, Grubhub, and Lula Direct. Our platform gives you **one place to manage your catalog and menus**, publish changes everywhere, and see all orders in one view. Whether you run one store or hundreds, Lula is built to be simple to adopt and scale with your business. Lula Commerce acts as a single source of truth, eliminating the complexity of managing multiple delivery platforms independently while ensuring consistent customer experiences across all channels. ## What You Can Do with Lula **Manage your product catalog once** and publish it to every channel * Central product repository * Consistent data across platforms * Bulk import and update capabilities **Create store menus, schedules, and availability** in minutes * Store-specific menu configurations * Time-based availability windows * Channel-specific customizations **Keep prices, taxes, and fees consistent** across channels * Unified pricing strategy * Automatic tax calculations * Synchronized fee structures **Receive, accept, and fulfill orders** from all marketplaces in one flow * Single order queue * Unified fulfillment process * Real-time status updates **Run campaigns and promotions** that apply everywhere * Cross-channel promotions * Targeted discounts * Automated campaign deployment **Track performance** with consolidated reporting * Unified dashboard * Cross-channel insights * Performance metrics ## Who This Documentation Is For **Decision makers who want a clear picture of how Lula works** * Strategic overview of platform capabilities * Business value and ROI insights * Implementation planning guidance Focus on business outcomes and operational benefits **Day-to-day users who will keep products, menus, and stores up to date** * Practical operational procedures * Menu and catalog management * Store configuration and maintenance Step-by-step guides for daily platform usage **Technical teams who will connect systems to Lula's APIs** * API documentation and integration guides * Technical implementation details * System integration patterns Comprehensive technical reference with code examples **Documentation Approach**: This site is written for a **non-technical audience first**, with optional deep links to the API reference when you need the technical details. ## How These Docs Are Organized **Your first setup and key concepts** Essential onboarding steps to get your first store operational with Lula Commerce. **How the pieces fit together** Understanding Lula's platform architecture, data flow, and core components. **How Lula connects to delivery channels** Detailed information about DoorDash, Uber Eats, Grubhub, and Lula Direct integrations. **Build branded ordering experiences** Comprehensive guide to implementing Lula Direct for your website or mobile app. **Endpoint-level details for automation** Complete technical reference when you're ready to integrate and automate operations. ## Platform Benefits **Reduce operational complexity** * Single interface for all channels * Automated synchronization * Centralized order management **Grow your delivery business** * Reach more customers * Consistent brand experience * Optimized pricing strategies **Built to grow with you** * Single store to enterprise chains * Flexible integration options * Robust infrastructure ## Key Features at a Glance **Central product and pricing management** * Product information storage * Price and inventory tracking * Attribute management * Bulk operations support Single source of truth for all product data **Store-specific menu creation and scheduling** * Custom menu configurations * Availability window management * Channel-specific variations * Automated publishing Flexible menu management for different store needs **Unified order processing across all channels** * Real-time order reception * Centralized fulfillment queue * Status tracking and updates * Customer notifications Streamlined operations regardless of order source **Comprehensive performance insights** * Cross-channel reporting * Sales performance metrics * Customer behavior analysis * Operational insights Data-driven decision making with consolidated analytics ## Getting Help When you need assistance, Lula Commerce provides multiple support channels: **Direct access to your account team** Reach out to your dedicated Lula representative for personalized support and guidance. **Built-in support system** Use the in-product help feature to contact support directly from the platform. **Technical reference materials** Access detailed API documentation linked from these guides when you need technical specifics. **Support Philosophy**: Our support team is committed to helping you succeed with Lula Commerce, whether you need technical guidance, operational assistance, or strategic advice. ## Success Stories **60+ hours saved in setup and ongoing management** Automated processes and unified workflows significantly reduce manual work Time savings allow focus on core business growth **\$250K+ saved annually in labor costs** AI-powered automation replaces manual tasks across operations Significant ROI through operational automation **22% average increase in basket sizes** Optimized customer experiences drive higher order values Enhanced customer experience translates to business growth ## What's Next **Begin your Lula Commerce journey** Follow our comprehensive setup guide to get your first store operational. **Learn how Lula works** Get familiar with the platform's architecture and data flow. **Plan your channel strategy** Understand available integrations and choose the right channels for your business. Get up and running with your first store setup Understand how Lula Commerce works under the hood Dive into technical documentation for developers **Ready to get started?** When you're ready, continue to [Getting Started](/documentation/get-started) to set up your first store and begin your journey with Lula Commerce. # Get Started Source: https://developer.lulacommerce.com/introduction Lula Commerce API documentation. ## Welcome to Lula's Customer API Documentation You'll find the docs and APIs required to integrate directly with the Lula Platform. Lula helps convenience stores and chains earn more by enabling delivery. The Inventory APIs enable automated updating of your stores' inventory on a regular cadence. Using this seamless integration you can: * Add, remove, or edit any item you wish to list on the delivery marketplaces * Keep item prices up-to-date * Update item quantities * and more... ### Support If you require any support, do not hesitate to contact [support@luladelivery.com](mailto:support@luladelivery.com) # Migrating from Item Ingest v1 to Item Ingest v2 Source: https://developer.lulacommerce.com/migrating_v1_v2 Highlighting the main changes between our v1 and v2 APIs ## Main Updates Here's a quick table defining the updates between the v1 and v2 APIs ### Endpoint Updates | v1 API | v2 API | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `https://lsm.luladelivery.store/api/v2/stores/{store_id}/inventory` | `https://api-prod.luladelivery.store/inventory/ingestion?store_id={store_id}` | | `PUT` | `POST` | ### JSON Payload Updates | v1 API | v2 API | | ------- | ---------------------------- | | `count` | `quantity` | | N/A | `description (string)` added | | N/A | `active (boolean)` added | ### API Response | v1 API | v2 API | | -------------- | ------------- | | `202 Accepted` | `201 Created` |