🤝 Understanding App Function Responses

Understanding how your App Function returns data is crucial, especially for Synchronous Actions where the response directly influences the merchant's operation. This guide details the structure, behavior, and utility tools for handling function responses.

1. The Core Contract: `Response` 💡

Every App Function is expected to return an object conforming to the Response contract. While the structure is required for all functions, its effect on the platform varies significantly based on the execution type.

Field	Type	Required	Description
`success`	`boolean`	Yes	Indicates if your function logic completed successfully.
`data`	`object`	No	A payload containing data to be returned or applied to the Salla operation (used primarily for Synchronous Actions).
`error`	`string`	No	A human-readable error message. Required if `success` is `false` for Synchronous Actions.
`status`	`number`	No	(Optional) An HTTP status code (e.g., 200, 400). Set via the `Response` utility class.
`message`	`string`	No	(Optional) An informative message. Set via the `Response` utility class.

2. Response Behavior by Execution Type 🔄

The platform handles the Response differently depending on whether your function is an Asynchronous Event or a Synchronous Action.

2.1 Responses for Synchronous Actions (Blocking)

For synchronous actions (e.g., shipment.creating), your response is critical. The merchant is blocked and waiting for your function's decision.

Return Value	Platform Action	Example Use Case
`success: true`	Proceeds. The action completes, and any data in the `data` field is merged or applied to the resulting entity.	Validating an address and proceeding with shipment creation.
`success: false`	Rejects. The action is halted, and the `error` message is displayed to the merchant immediately.	Rejecting a promotion if a custom rule is violated.

Example: Accepting a Synchronous Action

Example: Rejecting a Synchronous Action

This immediately stops the operation and tells the merchant why.

Special Case: `shipment.creating` Event

The shipment.creating event requires the use of the specialized Shipment utility class to successfully modify or complete the shipment details (e.g., setting a tracking number, generating a label).

2.2 Responses for Asynchronous Events (Non-Blocking)

For asynchronous events (e.g., order.created, Product Viewed), your response is informational only. The original action has already completed, and the user is not waiting.

Return Value	Platform Action	Example Use Case
`success: true`	Logged. The response is logged for debugging purposes, but doesn't affect the operation.	Sending a notification after an order is created.
`success: false`	Logged. The error is logged, but the original action remains successful.	Failed to sync with external CRM, but order creation succeeded.

Example: Asynchronous Merchant Event

Example: Asynchronous Customer Event

3. The Response Utility Class 🛠️

The Response utility class provides a structured way to create responses. It's particularly useful for Customer Events and some Merchant Events that require more detailed response handling.

3.1 Using Resp.success()

Create a successful response with data, optional status code, and optional message.

3.2 Using Resp.error()

Create an error response for handling failures.

3.3 Response Utility Methods

Method	Description	Required	Default
`Resp.success()`	Create a successful response	Yes (for success)	-
`Resp.error()`	Create an error response	Yes (for errors)	-
`.setData(data)`	Set response data object	Yes (pass `{}` if no data)	`{}`
`.setStatus(code)`	Set HTTP status code	No	`200`
`.setMessage(msg)`	Set human-readable message	No	-

3.4 When to Use Response Utility vs Plain Object

Scenario	Recommended Approach	Reason
Customer Events	`Response` utility	Provides structured responses for tracking/analytics
Synchronous Actions	Plain object	Simpler, faster (performance critical)
Merchant Events (Simple)	Plain object	Straightforward, less overhead
Merchant Events (Complex)	`Response` utility	Better error handling and status codes
Error Handling	Either (Response utility recommended)	Response utility provides better error structure

4. Error Handling Patterns 🚨

Proper error handling ensures your functions fail gracefully and provide useful debugging information.

4.1 Basic Error Handling

4.2 Validation Error Handling

4.3 External API Error Handling

4.4 Error Handling with Response Utility

5. Best Practices ✅

5.1 Keep Responses Focused

Return only the data that's necessary for the operation or debugging.

5.2 Provide Meaningful Error Messages

Error messages should be clear, actionable, and user-friendly (especially for synchronous actions).

5.3 Handle Async vs Sync Differently

Remember that synchronous actions block the user, while async events don't.

5.4 Always Return a Response

Every function must return a response object, even if the operation fails.

5.5 Log for Debugging, Not for Response

Use console.log() for debugging information, not for returning data to the platform.

5.6 Validate Before Processing

Always validate required data and settings before processing.

6. Common Patterns and Examples 📚

6.1 Webhook Notification Pattern

6.2 Analytics Tracking Pattern

6.3 Data Validation Pattern

6.4 External API Integration Pattern

7. Quick Reference 🎯

7.1 Response Format Comparison

Aspect	Plain Object	Response Utility
Syntax	Simple object literal	Method chaining
Use Case	Synchronous actions, simple events	Customer events, complex error handling
Performance	Faster (less overhead)	Slightly more overhead
Error Handling	Basic	Advanced (status codes, messages)
Type Safety	Good	Excellent

7.2 Response Fields Quick Reference

Field	When to Use	Example
`success: true`	Operation completed successfully	`{ success: true, data: {...} }`
`success: false`	Operation failed	`{ success: false, error: "..." }`
`data`	Return relevant data	`{ success: true, data: { order_id: 123 } }`
`error`	Provide error message	`{ success: false, error: "Validation failed" }`
`status`	Set HTTP status code (Response utility)	`Resp.success().setStatus(201)`

7.3 Execution Type Quick Reference

Type	Response Impact	Performance	Example
Synchronous Action	Critical - Affects operation	Must be < 500ms	`shipment.creating`
Asynchronous Event	Informational - Logged only	Can take up to 30s	`order.created`, `Product Viewed`

8. Troubleshooting 🔍

Issue: Response Not Affecting Operation

Symptom: Your function returns success: false, but the operation still completes.

Solution: Check if you're using an asynchronous event. Async events don't affect the original operation - they execute in the background after the action completes.

Issue: Synchronous Action Too Slow

Symptom: Merchant experiences delays when performing actions.

Solution: Remove slow operations (external API calls, complex calculations) from synchronous actions. Keep them simple and fast.

Issue: Error Message Not Displayed

Symptom: Error message in response doesn't show to merchant.

Solution: For synchronous actions, ensure error field is a string and success is false. For async events, errors are logged but not displayed to users.

Summary 📝

Synchronous Actions: Response is critical - affects operation, must be fast (< 500ms)

Asynchronous Events: Response is informational - logged only, doesn't affect operation

Plain Object: Simple, fast, good for sync actions

Response Utility: Structured, good for customer events and complex error handling

Error Handling: Always provide clear, actionable error messages

Best Practices: Keep responses focused, validate data, handle errors gracefully

Next Steps 🚀

Now that you understand App responses:

📋 Testing App Functions — Learn how to test your functions and verify responses

🚀 Get Started — Create your first App Function

📚 Event Reference — Explore all available events and their response requirements

🛠️ Salla APIs — Access Salla APIs from your functions

Responses

🤝 Understanding App Function Responses#

1. The Core Contract: Response 💡#

2. Response Behavior by Execution Type 🔄#

2.1 Responses for Synchronous Actions (Blocking)#

Example: Accepting a Synchronous Action#

Example: Rejecting a Synchronous Action#

Special Case: shipment.creating Event#

2.2 Responses for Asynchronous Events (Non-Blocking)#

Example: Asynchronous Merchant Event#

Example: Asynchronous Customer Event#

3. The Response Utility Class 🛠️#

3.1 Using Resp.success()#

3.2 Using Resp.error()#

3.3 Response Utility Methods#

3.4 When to Use Response Utility vs Plain Object#

4. Error Handling Patterns 🚨#

4.1 Basic Error Handling#

4.2 Validation Error Handling#

4.3 External API Error Handling#

4.4 Error Handling with Response Utility#

5. Best Practices ✅#

5.1 Keep Responses Focused#

5.2 Provide Meaningful Error Messages#

5.3 Handle Async vs Sync Differently#

5.4 Always Return a Response#

5.5 Log for Debugging, Not for Response#

5.6 Validate Before Processing#

6. Common Patterns and Examples 📚#

6.1 Webhook Notification Pattern#

6.2 Analytics Tracking Pattern#

6.3 Data Validation Pattern#

6.4 External API Integration Pattern#

7. Quick Reference 🎯#

7.1 Response Format Comparison#

7.2 Response Fields Quick Reference#

7.3 Execution Type Quick Reference#

8. Troubleshooting 🔍#

Issue: Response Not Affecting Operation#

Issue: Synchronous Action Too Slow#

Issue: Error Message Not Displayed#

Summary 📝#

Next Steps 🚀#