Best Practices

Best Practices

Before starting app development, it is very important that you carefully read the API documentation to ensure solid implementation.
Below, we've prepared a best practices guide to help ensure that, by the time you submit your app for approval, these guidelines are being followed to ensure technical quality and usability.

• Use pagination
  This is highly important, especially for merchants who have a large amount of data returned in requests.
  We recommend reading the Pagination documentation.

• The User-Agent header must contain the app name and email address.
  This ensures security and clarity in the logs generated by your application.
  We recommend reading the Identify your app documentation.

• Use webhooks to manage request volume appropriately
  Avoid making multiple requests for the same operation within a short time window.
  For example, if your app needs to access the products and/or orders endpoint, it is recommended to use the webhook for newly created and notified products, so that requests to the API occur only when triggered by an actual event — this prevents repetitive requests when no data has changed in the merchant's account.

• Ensure use of the necessary scopes and permissions
  It’s important that the diagram you submit with the scopes required by your app matches what merchants will need to “accept” in order to use it.
  You should also ensure that scope usage is intentional and includes only what is necessary for your app to function.

• The app’s language must align with the geographies selected for publishing.

• Pay attention to the request rate limit
  The API implements a rate limit to control traffic and maintain service stability. By default, this limit allows 2 requests per second. That means if you send 20 requests simultaneously, they’ll be processed within this limit and will take approximately 10 seconds to complete.
  It's important to note that this limit applies per merchant and application making requests. However, if the merchant is on the Next plan, the base limit is multiplied by 10, allowing a higher volume of requests.
  The response will include headers that indicate the available and used limit:

  • x-rate-limit-limit: indicates the maximum limit.
  • x-rate-limit-remaining: how many requests remain before hitting the limit.
  • x-rate-limit-reset: how long (in milliseconds) until the limit resets.
    We recommend reading the Rate Limit documentation.