All requests require a valid API token.

Include your token in your request headers, as Authorization: Bearer {token} (without the curly braces).

The account owner can generate API tokens from within the Goflow web app, by visiting Settings › API Tokens.

While browsing the documentation, you may see some endpoints marked as beta. These endpoints, like all public API endpoints, are fully production-ready, have been thoroughly tested and are running on production hardware with full availability.

The beta designation is primarily for transparency. These endpoints haven't been in production long enough for us to be confident that the schema is set in stone. We may still need to tweak it a tiny bit in the future (though we very rarely do).

Rest assured that if any changes are necessary, we'll reach out to you directly to ensure a smooth transition.

To access a beta endpoint, you must explicitly opt in by including a contact email address as an X-Beta-Contact header:

X-Beta-Contact: contact@mydomain.com

We'll use this email address to contact you in case there are any changes to these beta endpoints that may affect your code.

Your privacy is of utmost importance to us. Your email address will never be shared with anyone outside of Goflow, and we will never send you anything that is not related to the API.

All REST API endpoints follow this pattern:

https://{your_subdomain}.api.goflow.com/v1/{resource}

This subdomain is the same as the one used to access the general Goflow portal. For example, if you generally access Goflow at:

https://companyname.goflow.com

...then you would access the API at:

https://companyname.api.goflow.com/v1/{resource}

Note: The Goflow API is only accessible over HTTPS. For extra security, accessing the API over plain-text HTTP does not automatically redirect to HTTPS. You will get an error that we only support HTTPS.

The API uses ISO 8601 for all dates. All dates returned from the API have both the date and time set, and are always in UTC. For example:

2025-01-31T18:30:20Z

We recommend that you follow the same pattern when sending dates to the API. For example, to filter a list of orders for a given date:

/orders?filters[date:gte]=2025-01-01T00:00:00Z&filters[date:lt]=2025-01-02T00:00:00Z

...will return all orders whose date is January 1st 2025 in UTC.

If you need to filter based on a different timezone, we recommend doing the timezone conversion on your end, before passing it to the API filters. For example, to apply the above filter based on EST, convert the start and end of the day from EST to UTC:

/orders?filters[date:gte]=2024-12-31T19:00:00Z&filters[date:lt]=2025-01-01T19:00:00Z

...will return all orders whose date is January 1st 2025 in EST.

Many list endpoints, which are accessed via a GET request to the root of the resource (such as /orders), include support for passing along filters to narrow down the results. This section describes how filters work in general. Refer to the documentation for each resource to see the available filters for each specific endpoint.

• The filters query - All filters should be passed in via the filters query parameter. For example:

  /orders?filters[status]=shipped
  

  ...will only return orders whose status is shipped.

• Multiple filters - To use multiple filters, you may set multiple fields on the filters key. For example:

  /orders?filters[status]=shipped&filters[invoice_number]=123
  

  ...will return orders whose status is shipped, but only if its invoice_number is also 123.

• Multiple values - To filter for multiple values in the same field, you may set the same field multiple times to a different value. For example:

  /orders?filters[status]=shipped&filters[status]=ready_for_pickup
  

  ...will return orders whose status is either shipped or ready_for_pickup.

• Nested fields - To filter based on a nested field, you can use "dot notation" as the key. For example:

  /orders?filters[store.id]=123
  

  ...will return orders whose store ID is 123.

• Operators - In addition to regular key/value filters, many fields also support supplying an operator for the filter. For example:

  /orders?filters[status:not]=shipped
  

  ...will only return orders whose status is not shipped.

  To filter based on whether a given field is set or not, without checking for a specific value, use the special boolean exists operator. For example:

  /orders?filters[invoice_number:exists]=false
  

  As you can see, operators are supplied as part of the key, separated from the field by a : (colon). Here is a list of operators and their meaning:

  Operator	Meaning
  eq	Equals (Default)
  not	Not equals
  exists	Exists
  gt	Greater than
  lt	Less than
  gte	Greater than or equal to
  lte	Less than or equal to

  For additional examples of operator usage, review the section on dates.

  Support for these operators varies by endpoint and field type. As mentioned, refer to the documentation of each endpoint to see the list of supported filters and operators.

  Note on whitespace: All input strings in the API are trimmed of any surrounding whitespace. This prevents errors when you're passing user input directly to the API.

  As a side effect, in the rare case where an existing record has a field with surrounding whitespace, you will not be able to search for it in the API. Your query string term will be trimmed and won't match the record's value.

All list pages, which are accessed via a GET request to the root of the resource (such as /orders), return their data as paginated chunks. The basic schema for the response is:

{
    "data": [/* ... */],
    "next": string|null
}

The actual chunk of records is returned in an array under the data property. If there are more records after the current chunk, the next property will contain a URL from which to fetch the next chunk. If this is the last chunk in the set, the next property will be null.

Some endpoints, such as PATCH requests, support partial updates. For these endpoints, you may completely omit any fields you do not intend to update.

For example, to update the tracking number of a shipment box, submit this JSON body as a PATCH request to the edit shipment box endpoint:

{
    "tracking_number": "9274890388405702033589"
}

...and only the tracking_number field will be updated. All other fields, such as cost, weight and dimensions will remain unchanged.

Note: omitting a field is not the same as passing it as null. Omitting a field ignores that field entirely, whereas setting it to null will actually set the field to null in Goflow (or return a validation error, where applicable).

Some resources in the API support bulk actions using feeds, which let you post multiple API requests within a single HTTP request. For example, using the orders/shipments/feeds endpoint, you may submit a whole list of order shipment requests at once.

Unlike other endpoints, the actions in a feed are processed asynchronously. The response will include a location property, which contains the endpoint for this feed:

HTTP/1.1 202 Accepted
{
    "id": 123,
    "location": "https://domain.com/v1/orders/shipments/feeds/123"
}

Once all requests have been processed, the feed's endpoint will return the responses for each request, respectively:

HTTP/1.1 207 Multi-Status
{
    "status": "pending" | "done"
    "responses": null | [
        {
            "index": 0,
            "status_code": 201|422, /* Or any other status code */
            "request": { /* The original request */ },
            "error": null | string
        }
    ]
}

Note: For some feeds where there would be no details in the successful response, such as the Vendor Products feed, the responses array may only contain error responses, if any.

If the feed's status is still pending, then responses will be null. Once the feed is done processing, the responses will hold a list of responses, one for each request.

Expiry Note: Feed results are kept by Goflow for 12 hours after the feed is done processing. After that timeframe, the endpoint will return a 404.

Every endpoint in the API is rate limited, to prevent abuse and keep the API available to all users.

All REST API responses include X-Rate-Limit headers, which show how many requests the client has made, and the total number allowed per minute.

When the limit has been exceeded, a 429 HTTP response code will be returned. It will also include a Retry-After header with the number of seconds to wait until retrying your request.

In addition to rate limits, some asynchronous requests, particularly reports, are subject to quota limits.

Quota limits differ from rate limits. While rate limits cap the number of requests within a period, quota limits restrict the number of records generated asynchronously within a given period. Upon reaching the quota, any additional requests are queued for processing when the quota replenishes.

When processing a given request, the full result-set will be generated, even if it exceeds the current quota limit. Any overage will roll over, reducing the available quota for the next period.

Example: Consider a report with a quota limit of 100 records per day. If a report generates 250 records, no additional reports of that type will be processed today or tomorrow. On the day after tomorrow, any queued requests, along with new requests, will begin processing.

This example uses smaller numbers for clarity, but the actual quota limits are significantly higher.

Refer to the documentation of each endpoint to see its exact quota limit. Furthermore, the Report Quotas endpoint provides comprehensive information on quota policies for each report type, along with real-time data on current quota usage.

Reports are generated asynchronously, similar to responses of Feeds for Bulk Actions. Request to generate a report, and the response will include a location property, which contains the endpoint for this report:

HTTP/1.1 202 Accepted
{
    "id": 123,
    "location": "https://domain.com/v1/reports/123"
}

The report is generated and stored in a file with the format of your choosing (json, jsonl, or csv). You may fetch the report status and metadata from the endpoint returned in the above-mentioned location URL.

Once the report was successfully generated, the report's endpoint will return the file_url of the generated file:

HTTP/1.1 200 OK
{
    /* Partial */
    "status": "completed",
    "completed": {
        "records_count": 265,
        "file_url": "https://path-to-file.jsonl",
    },
}

Note: the above is a partial view of the response. Refer to the report endpoint's documentation for the full details.

If the report's status is still queued or processing, then completed will be null. Once the report is fully generated, completed.file_url will point to the URL from which to fetch the generated report file.

The URL at completed.file_url will redirect you to the actual file on our CDN. Make sure to follow the HTTP redirect header when downloading the file.

Expiry Note: Generated reports are kept by Goflow for 12 hours from when the report was fully generated. After that timeframe, the endpoint will return a 404.

401 Unauthorized

The client doesn't have correct authentication credentials.

403 Forbidden

The client doesn't have the correct permissions for the given endpoint.

404 Not Found

The requested resource was not found.

409 Conflict

The request conflicts with another process. You may try the same request again.

422 Unprocessable Entity

The request body contains semantic errors, or doesn't pass validation. This is typically caused by incorrect formatting, omitting required fields, or logical errors such as attempting to ship an order that's already shipped.

HTTP/1.1 422 Unprocessable Entity
{
    "message": "The given data is invalid",
    "errors": [
        "name": [
            "Name required"
        ]
    ]
}

429 Too Many Requests

The client has exceeded the rate limit.

HTTP/1.1 429 Too Many Requests
{
    "message": "API rate limit exceeded. See the rate-limiting section in our API documentation.",
    "retry_after_seconds": 7.8832487
}

503 Service Unavailable

The Goflow API is temporarily unavailable, for scheduled maintenance.

5xx Errors

An internal error occurred in Goflow.

The orders resource represents sales orders. Orders are generally imported directly from the channels, but may have also been entered manually, or uploaded from a file. No matter the source, Goflow standardizes the orders so they all look the same.

The Orders Documents resource returns URLs that point directly to specific order documents.

The URLs returned by this endpoint are publicly-accessible, and do not require authentication. They're valid for a limited time, after which they expire. You can always call this endpoint again to get fresh URLs.

The Order Lines resource represents lines in an order.

The Order Warehouse resource represents the fulfillment warehouse for a given order.

If the order is set to reserve inventory, the warehouse's "reserved inventory" will include the product quantities in this order.

The Orders Cancellation endpoint provides the ability to cancel orders.

The Orders Holds resource allows you to add and remove order holds.

The Order Splits resources allows you to split an order into multiple different orders. This is useful when you're planning to fulfill different parts of an order at different times, from different warehouses, or using different methods (i.e. Direct Fulfillment vs. Purchase to Order or Dropship).

If the order already has packed shipment boxes, they will carry over to the new orders, respectively.

Note: When splitting an order, the original order is deleted in Goflow. The new chunks are each saved as individual standalone orders. Each order will have its own id, but they'll all share the original order's order_number. To tie them together, their original_order_id will always contain the original order's id.

The Order Acknowledgment resource allows you to confirm or reject orders from specific channels.

Note: Order Acknowledgments are currently only supported in the API for the following channels: amazon_vendor_usa, amazon_vendor_mexico, and amazon_vendor_canada.