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 are available for you to test, but their exact details are still in flux, and may change at any time.

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.

Our REST API endpoints are organized by resource type. You'll need to use different endpoints depending on your app's requirements.

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}

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, regardless of the time.

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, regardless of the time.

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.

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.

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.