Welcome to the Propello Published API documentation. This guide provides a comprehensive reference to the API, including authentication, pagination, and instructions for making your first API call.

You'll find the complete API Reference here.

Getting Started with Propello API

To use the Propello Published API, follow these steps:

Create Your Published API Key: Generate a Published API key in Propello and assign the necessary roles for accessing the desired APIs.
Authenticate:
- Call the Authenticate endpoint.
- Provide your API Key in the Authorization field and click "Try It!"
- Copy the JWT from the access_token field in the response.
Invoke an API using Readme.io:
- Navigate to the desired API endpoint.
- Complete any required fields. Use the X-Active-Store header for specifying the store id (obtain valid store ids for your system via the List Stores API).
- Paste the copied JWT into the Authorization field without quotes or braces.
- Click "Try It!" to execute the call.

Deferred Processing Required for Large Responses

All Propello LIST APIs can be run as a background job (deferred processing). Submitting a request as a background job is mandatory if your usage pattern involves paginating more than 15 pages deep into the results.

You can potentially avoid the use of background jobs by either:

Rather than paginating by using page= on the query string, order your results by update_datetime or create_datetime and request results greater than the most recent value retrieved by the prior API call. We prefer this style of incremental result traversal because it is more efficient.
Use a higher limit. The default response returns 25 items per page, but a limit as high as 500 is permitted.

If you request a page number greater than the maximum number of pages that API allows to be retrieved, you will receive an HTTP 413 response. In this case, set the query string parameter is_async to true. You will be provided with a request id in the response.

You can call the Check Deferred Execution Status API (available under Integrations), provide your request_id, and the API will tell you if the job is completed. If the job is completed, you can retrieve the file containing the results of the API call using the link provided in the response.

Instead of polling the Check Deferred Execution Status API you may choose to receive a notification at a callback URL that you provide in the callback_url query string parameter. In this case, when the job completes, a message containing the path to the results file will be delivered in real time to your callback API endpoint.

The results file is stored in NDJSON format. In this format, each line in the file is one result from the results attribute of the API response. You cannot (and should not, for memory reasons) try to parse the entire file as a single JSON object. Instead, the file should be read in incrementally line by line and each line parsed as its own independent JSON object.

Supported ISO8601 Date/Time String Formats

Our APIs require date strings in specific formats for accurate parsing. Below are the supported formats:

Basic Format: YYYY-MM-DDTHH:MM:SS (e.g., 2025-03-12T21:15:57)
With Microseconds: YYYY-MM-DDTHH:MM:SS.mmmmmm (e.g., 2025-03-12T21:15:57.123456)
With Timezone Offset: YYYY-MM-DDTHH:MM:SS+HH:MM or -HH:MM (e.g., 2025-03-12T21:15:57+00:00)

Note: The ISO 8601 Z suffix (e.g., 2025-03-12T21:15:57Z) is not supported and will cause errors. Use +00:00 to indicate UTC instead.

Pagination

When API responses are spread across multiple pages, use the sample code provided here to navigate through the results. Up to 15 pages can be requested, and you can specify a value for the limit parameter to override the default of 25. The maximum value honored for limit is 500. Beyond that limit, use a background job or filter and order on the same field to traverse the results by value.

Change Sets

For APIs which support an "update_datetime" filter, only those entities which have changed since the specified datetime will be considered. However, some Propello entities may contain attributes that are of no interest when they change. Therefore, some APIs may provide a "changeset_name" filter. Each "changeset_name" is a grouping of a subset of the entity's attributes, and only entities which have changed since the specified datetime for that subset of entities will be considered. Each API which supports the "changeset_name" filter will list of out the supported values for "changeset_name", and a list of all the attributes which will be considered for each "changeset_name" value.

Troubleshooting

I am getting an HTTP 401 or 403

Verify the server URL: Use https://api.epicorretailcloud.com for production or https://api.toogoerp.net for development/staging.
Ensure you are including a User-Agent HTTP header in your requests.

I am getting an HTTP 429

The message will be one of either "Too Many Requests" or "Limit Exceeded".

If "Too Many Requests", introduce a backoff mechanism into your code, similar to the example code for pagination posted above.
If "Limit Exceeded", this means all of your allocated requests for the day have been consumed and you will need to wait until the next day or contact support for assistance.

I am getting a "timed out" error message

In this case, use deferred processing. Set is_async to true and optionally provide a callback_url or use the polling status API to determine when your results file is ready for retrieval.