Site Flow Order Submission | hp's Developer Portal

Order Submission

Creation of an order in Site Flow is primarily done through an API call to the order submission API Endpoint. This call is an HTTP POST which contains the information necessary for Site Flow to create a valid order as the body of the call.

Create Order Endpoint

This API endpoint submits an order into Site Flow for immediate processing. The order submission endpoint is different than other Site Flow API endpoints in that it has a different base URL ( https://orders.oneflow.io vs https://pro-api.oneflowcloud.com ).

The order submission endpoint is also an asynchronous endpoint meaning that a basic acknowledgement response is returned if the order JSON structure is valid, but a valid order is not determined until later. Various processing steps like Autoflows, calculated attributes and more complex order structure validation like SKUs, Attributes and shipping methods are not validated until a later time.

The authentication method for order submission is the same as all other endpoints.

NOTE: Once an order has been submitted successfully, it will start processing immediately.

HTTP Request

Method	URL
POST	https://orders.oneflow.io/api/order

The body of the request should be a valid order structure in JSON format. The Site Flow Order Structure page describes the format of this JSON structure in detail.

HTTP Response

The response will happen right after the order request has been stored correctly. This response will be returned regardless of whether the order is valid or not. The response body will include the following fields:

{ 
    "_id": "5910757 faab8ec6f60127999", 
    "url": "https://s3.amazonaws.com/order/5910757faab8ec6f60127999", 
    "timestamp": "2017-04-08T13:41:19.998Z", 
    "sourceAccountId": "51 bb2fc71745777ba63f3f11" 
}

Field	Description
_id	The order identifier. The system will keep this identifier and will save it within the new order
url	Url to the stored original order content
timestamp	Date and time of the order submission request
sourceAccountId	Requester’s account id

Rate limitations during scaling

The asynchronous order submission API is designed to scale up and down depending on the current load on the system. The API limits the number of request it accepts during the time it is scaling up to avoid failed order submissions. During spikes of order submissions it is possible that 5XX error responses are returned due to this rate limitation. This will require requesters to handle possible 5XX responses and re-try the submission request after a few seconds while the system provisions new instances.

Validation of successful order submission.

Due to the asynchronous nature of Site Flow order submission, requestors cannot depend on a 201 created response to determine if an order was successfully created in the system.

Any submitted order that errors due to internal validation, or similar pre-order failure, will show up in the View Submission Errors dialog in the Orders tab in Site Flow. This allows Site Flow operators with the proper roles to view the reason for order submission errors and respond to them. In some cases these errors can be resolved by the Site Flow operator and re-submitted.

To be notified programmatically of order errors we recommend setting up a trigger on the Setup tab in Site Flow based on the Order Errored event as shown below:

The trigger method of being notified of order submission errors will prevent the requestor of having to query the system repeatedly to find out if the order submission was successful, but will require that a webhook be setup to capture this postback notification. The content of this postback is determined by a template defined in Site Flow and can be in JSON, XML, HTML formats.

If a postback is not an option, the order can be queried over the API using the internal order ID ( _id ) that was provided in the response to the order submission call above.

HTTP Request

Method	URL
GET	https://pro-api.oneflowcloud.com/api/order/details/{orderId}

If the order errored, the response to this call will return a 404 response with the following payload:

{
    "success": false,
    "error": {
        "ofError": true,
        "statusCode": 404,
        "code": 211,
        "message": "Order not found"
    }
}

A successful order will return the complete order JSON structure.

NOTE: Under heavy order submission loads it may take the system some time to process the order submission and return a successful query response. It is recommended to re-try this query after a few seconds in the case of a 404 response in the even that the order has not yet been created by the system.

Other Useful Order calls

Cancel an Order (by source ID)

This endpoint allows you to cancel a specific order, using the source account name and ID.

HTTP Request

Method	URL
PUT	https://pro-api.oneflowcloud.com/api/order/{sourceAccountName}/{sourceOrderId}/cancel

No request body is necessary.

URL Parameters

Parameter	Description
sourceAccountName	The name of the source account that the order originated from
sourceOrderId	The source order ID, specified when the order was submitted

HTTP Response

If the order was found and wasn’t already cancelled, the response body is the cancelled order (in JSON format).

Get an Order (by source ID)

This endpoint allows you to get a specific order, using the source ID that you provided in the original order submission JSON.

HTTP Request

Method	URL
GET	https://pro-api.oneflowcloud.com/api/order/bysourceid/{sourceOrderId}

URL Parameters

Parameter	Description
sourceOrderId	The source order ID, specified when the order was submitted

HTTP Response

If the order was found, the response body is the order with the source order id (in JSON format).