Skip to main content

FAQ

FAQ Categories​

API Invocation​

Problem Description:​

In some APIs, we support both cursor-based (token) and page-based pagination (page). However, developers sometimes face challenges in fetching metadata efficiently.

Cause:​

Page-based pagination is simpler but less efficient for large datasets. Cursor-based pagination (token) offers better performance and accuracy when fetching paginated data, as it directly links to the next dataset batch.

Solution:​

  • Recommendation: Use cursor-based pagination (token) for API calls. Use page-based pagination only when token-based pagination is unavailable.
  • How to Use: Refer to the Cursor Pagination Documentation for implementation details.

Q: What should I do if images are not displaying properly?​

Problem Description:​

Images are not displaying in certain parts of the site.

Cause:​

The issue may occur if the images are not properly configured in the theme settings.

Solution:​

  1. Navigate to Theme Editor → Global Settings → Media Design.
  2. Add or configure the required images as per the settings.

Q: Why does the API allow creating a product even when required fields are passed as empty values?​

Problem Description:​

Some customers have observed that creating a product succeeds even when required fields are passed as empty. This occurs because some APIs handle default values internally.

Cause:​

Certain APIs may have default values for required fields. If a required field is passed as empty, the API initializes it with a predefined default value instead of returning an error.

Solution:​

  • Check Parameter Requirements: Before making an API call, carefully review the required parameters and their expected values in the API documentation.
  • Contact Us for Clarifications: If the behavior of required fields seems unclear or inappropriate for your use case, please contact our support team for further assistance.

Q: In PHP, how do I get the correct response when the log shows a normal 200 status?​

Problem Description:​

When using PHP to call the API, the log shows a normal 200 status code, but the response body appears empty or incorrect.

Solution:​

If you are using a PSR-7 compatible HTTP client (e.g., Guzzle), use the following code to retrieve the response content:

$response->getBody()->getContents();

Q: What are the rules for orders and tracking numbers?​

Currently, orders cannot be split or merged. Multiple orders can share the same tracking number. And a single order can have multiple packages, each with its own tracking number.

Q: What is the logic behind the total_price field?​

Taxes: total_price represents the final amount paid by the customer, including taxes if applicable.

Additional Fees: total_price includes extra charges like additional_total, total_shipping, total_tax, shipping_tax_total, and tips (total_tip_received).

Formula:

📘 Field Explanation

sub_total: Total price of products.

total_shipping: Total shipping fees.

additional_total: Additional charges.

total_tax: Total product tax.

shipping_tax_total: Total shipping tax.

total_tip_received: Total tips received.

total_discount: Total discounts (e.g., product and code discounts).

If sub_total is tax-exclusive (order.config.product_tax_included == false):

total_price = (sub_total + total_shipping + additional_total + total_tax + shipping_tax_total + total_tip_received) - total_discount

If sub_total is tax-inclusive (order.config.product_tax_included == true):

total_price = (sub_total + total_shipping + additional_total + shipping_tax_total + total_tip_received) - total_discount

PayPal Payments: total_price reflects the amount the customer pays, excluding any PayPal transaction fees, which are handled separately by the platform.

Q: What is the purpose of the buyer_accepts_marketing field?​

The buyer_accepts_marketing field indicates whether a customer consents to receive marketing promotions:

  • Accepted: Merchants can send promotional emails or discount offers.
  • Not Accepted: Customers are excluded from marketing campaigns.

This field does not directly affect the order list or its information.

Q: Does the customer.orders_count field include canceled or unpaid orders?​

orders_count includes all orders created by the customer in the current store, regardless of their status (e.g., canceled or unpaid).

Q: Can a customer use different currencies for payments in the same store?​

Yes, stores can support multi-currency payments. All payments are converted into the store's primary market currency for consistency.

Q: I created an order via API, but why can't I see it in the shop admin dashboard?​

This is typically because the order lacks a shipping address. The admin dashboard filters out and does not display orders considered "invalid" due to missing address information. However, these orders may still be retrievable via the API.

Q: Why does the id of a line item in an order response change between API calls?​

The line item id for an unpaid (incomplete) order might not be persistent. Once the order is successfully paid for, the line item IDs will become stable and remain unchanged in subsequent API queries.

Q: Why does the create order API return record not found?​

When you receive this error from the create order API, please check the following steps:

  • Verify that the Product ID, Variant ID, and other related parameters are correct.
  • If all IDs are confirmed to be accurate but the request still fails, check whether the store has configured at least one payment channel.
  • The store must have at least one payment method enabled; otherwise, the order creation will fail with a “record not found” error.

Q: Why do product images show a loading state after creation via the Product Image API?​

The loading state appears when images aren't hosted on Shoplazza's native storage. The system initiates a transfer process for external images, during which the loading indicator is displayed. This is temporary and resolves automatically once the transfer completes.

Q: How to obtain the CDN domain for image resources?​

To retrieve the image CDN domain:

  1. Check for the IMAGE-DOMAIN header in the API response headers.
  2. If the IMAGE-DOMAIN header value is not available or empty, the system will automatically fall back to the default domain: img.staticdj.com.

Note: The IMAGE-DOMAIN header provides the current active CDN endpoint for image assets. When implementing, always include fallback logic to handle cases where the header might be absent.

Q: How can I update a single product variant without affecting other variants under the same product?​

Use the dedicated Update Variant API. Important: If you use the "Update Product" API, it will replace the entire variant list of the product with the variants provided in the request body. Any existing variants not included in the request will be deleted. To avoid this, use the variant-specific endpoint or ensure your "Update Product" request includes all variants you wish to keep.

Authorization​

Q: The API request returns a 403 error, indicating a lack of permissions.​

Problem Description:​

The API request fails with a 403 error due to insufficient permissions for the private app.

Cause:​

This issue occurs because the required permissions for the private app have not been granted in the store’s settings.

Solution:​

  1. Verify Permissions: Ensure that the necessary permissions are configured for the private app:

    • Go to the Store Admin’s Index Page.
    • Navigate to Manage Private App.
    • Update the permission settings for the private app as needed.

  2. Current Limitations:

    • Currently, we do not support write shop permissions for private apps.
    • This permission will be enabled in a future update.

App Management​

Q: How can I improve my app's rating?​

User Interface Optimization:​

  • Ensure buttons, navigation bars, and forms are user-friendly and functional.
  • Provide clear setup instructions and interactive features.
  • Add real-time feedback for user actions.

Performance Optimization (Lighthouse Score):​

  • Focus on metrics like FCP, LCP, and TTI.
  • Optimize large files, use lazy loading for images, and improve server response times.

App Usability:​

  • Ensure your app is bug-free and responsive across devices.

Q: How can I install an unpublished APP for production testing in my store?​

To test an APP that is not yet published in the store’s app marketplace, use the following URL format:

https://{{storeDomain}}/admin/oauth/redirect_from_partner_center?client_id={{app_client_id}}

Replace:

  • storeDomain → your store’s domain name
  • app_client_id→ the Client ID of the APP you want to test

This link allows the store to install the unpublished APP directly for detailed business testing.

Q: Common Questions about Vulnerability Scans​

Q1: When do vulnerability scans usually start?​

A: Vulnerability scans are typically initiated after significant system changes or during routine security audits.

Q2: Do single scans provide a report and remediation recommendations?​

A: Yes, each scan provides a detailed report and recommended fixes for identified issues.

Q3: How should I handle vulnerabilities I believe are false positives?​

A: Low-risk vulnerabilities can be ignored if they don’t impact service. For medium or high-risk items, submit a reevaluation request with evidence.

Q4: How do vulnerability scans work, and are additional resources needed?​

A: Scans use automated tools to test for known issues. No extra resources are typically required.

Q5: How should I verify vulnerabilities have been resolved?​

A: Re-run the scan after applying fixes to confirm resolution.

Q6: What should I do if creating or restarting a scan task fails?​

A: Verify that all required parameters are correct. If issues persist, contact support.

Q7: How long does it take to generate a scan report?​

A: The time varies depending on the scan's complexity. Contact support for delays.

Q: Will developers be able to switch stores under their account?​

Current Status:​

This feature is not currently available.

Future Plans:​

Switching between stores under the same account is planned for a future update.

Account Management​

Q: How can developers delete their developer account?​

Current Status:​

At present, we do not offer a feature to delete developer accounts.

Solution:​

If you need to delete your developer account, please contact our support team for assistance.

Future Plans:​

We are evaluating the feasibility of developing a developer account deletion feature in the future.

Q: Will developers be able to switch stores under their account?​

Current Status:​

This feature is not currently available.

Future Plans:​

The ability for developers to switch between stores under the same account is planned for a future update. Stay tuned for announcements regarding its release.

Webhook​

Q: How does Shoplazza handle failed webhook delivery attempts?​

Problem Description:​

When a webhook delivery fails (i.e., your endpoint responds with a non-2xx HTTP status code), Shoplazza retries delivery multiple times over two days using an exponential backoff strategy.

Solution:​

  1. Retry Mechanism: Shoplazza attempts to deliver the webhook up to 19 times over two days.
  2. Webhook Deletion: If all attempts fail, the webhook is deleted, and you will need to recreate it.

Q: What should I do if webhook events are not received?​

Problem Description:​

Webhook events may fail to reach your server due to IP restrictions or misconfigured endpoints.

Solution:​

  1. Whitelist Shoplazza IPs: Allow requests from Shoplazza’s external IPs (e.g., 34.210.253.121).
  2. Verify Endpoint Configuration: Ensure your endpoint is set up correctly to handle POST requests.
  3. Monitor Logs: Check server logs for errors or blocked requests.

APP Store​

Q: If a merchant uninstalls and reinstalls the WhatsApp & Chat Buttons app within the same billing cycle, do they need to pay again?​

Current Behavior:​

Yes, merchants will need to pay again. When the app is uninstalled, the subscription is terminated, and a new subscription must be initiated upon reinstallation.

Reason:​

The subscription relationship ends upon app uninstallation. Therefore, reinstalling the app requires creating a new subscription, even if it occurs within the same billing cycle.

Recommendation:​

Merchants should consider the impact of uninstalling apps during an active billing cycle, as reinstallation will trigger a new payment. If this policy raises concerns, feel free to contact support for clarification.

Theme Extension​

Q:How can I customize theme blocks and POD functionality using theme extensions?​

Reason:​

Shoplazza does provide CLI capabilities for theme customization and POD implementation. Please reach out to our technical team who will provide you with the relevant documentation and guidance for these advanced customization features.

Q:Why is my CLI command returning a 403 error and how can I resolve it?​

Reason:​

The 403 error occurs when your app client ID isn't whitelisted for CLI access. Please contact our technical support team via the techsupport email to have your app client ID added to the whitelist. This is a mandatory security measure before CLI tools can be utilized.