Documentation Summary

REST API

API Calls

With the exception of the call to request a JWT, all API calls use bearer token authorisation with the JWT to authorise requests.

Because the API is deployment-specific (instance-specific), each instance of the API has its own URL.

All calls that return custom field values (product metadata fields, order fields, user profile fields etc.) only return values stored in the Storefront database. Values dynamically retrieved from remote data sources (such as third party web services and APIs) are not returned.

Token

Get Token

`POST` {DeploymentURL}/restapi/token

This call receives an API key returns a JWT to authorize subsequent API calls.

Request Body

Name Type Description
apikey\* String An API Key created within the API configuration settings.

200: OK

{ "jwttoken" : "{JWT}" }

Users

Get User By ID

`GET` {DeploymentURL}/restapi/users/{UserID}

This call returns a User object based on the User ID provided. Where there is both a User ID and Username with matching values, the API will favour the User ID.

Request Body

Name Type Description
UserID\* Integer The Internal ID of the user.

200: OK

{
    "Id": "{UserID}",
    "LoginName": "{Username}",
    "CustomUserFields": [
        {
            "Name": "{UserProfileFieldName}",
            "Value": "{UserProfileFieldValue}"
        },
        {
            "Name": "{UserProfileFieldName}",
            "Value": "{UserProfileFieldValue}"
        }
    ],
    "CustomUserGroups": [
        {
            "Id": "{UserGroupID}",
            "Name": "{UserGroupName}"
        },
        {
            "Id": "{UserGroupID}",
            "Name": "{UserGroupName}"
        }		
    ]
}

404: Not Found No user was found matching the criteria.

Get User By Username

`GET` {DeploymentURL}/restapi/users/{Username}

This call returns a User object based on the Username provided. Where there is both a User ID and Username with matching values, the API will favour the User ID.

Path Parameters

Name Type Description
Username\* String The public username of the user.

200: OK

{
    "Id": "{UserID}",
    "LoginName": "{Username}",
    "CustomUserFields": [
        {
            "Name": "{UserProfileFieldName}",
            "Value": "{UserProfileFieldValue}"
        },
        {
            "Name": "{UserProfileFieldName}",
            "Value": "{UserProfileFieldValue}"
        }
    ],
    "CustomUserGroups": [
        {
            "Id": "{UserGroupID}",
            "Name": "{UserGroupName}"
        },
        {
            "Id": "{UserGroupID}",
            "Name": "{UserGroupName}"
        }		
    ]
}

404: Not Found No user was found matching the criteria.

Get Login Ticket

`POST` {DeploymentURL}/restapi/users/{Username}/loginticket

This call returns a ticket to sign the user into the deployment without a password. Login tickets are single-use and expire after 24-hours. To sign a user into the deployment, redirect the user to the to the /Login.aspx?ticket=”{LoginTicket}”\&logonName=”{Username}” page with the listed arguments.

Path Parameters

Name Type Description
Username String The public username of the user.

200: OK

{ "loginticket": "{LoginTicket}" }

409: Conflict A user account with these details already exists in the target deployment.

Update User Profile Fields

`PATCH` {DeploymentURL}/restapi/users/{Username}

This call updates a user’s profile fields in the target deployment based on provided properties.

Path Parameters

Name Type Description
Username\* String The public username of the user.

Request Body

Name Type Description
CustomUserFields\* List <p>A list of User Profile field names and respective field values.</p><p>{ “Name”: “{UserProfileFieldName}”, “Value”: “{UserProfileFieldValue}”}</p>

200: OK

404: Not Found No user was found matching the criteria.

Permissions

Add Users To Groups

`POST` {DeploymentURL}/restapi/permissions

This call adds users to groups based on the provided relationships. Each group can only be specified once in the request.

Path Parameters

Name Type Description
  String  

Request Body

Name Type Description
UserGroupName List A list of Usernames to add to the group. Multiple UserGroupNames can be specified.

200: OK The operation completed successfully.

Remove Users From Groups

`DELETE` {DeploymentURL}/restapi/permissions

This call removes users from groups based on the provided relationships. Each group can only be specified once in the request.

Request Body

Name Type Description
UserGroupName List A list of Usernames to remove from the group. Multiple UserGroupNames can be specified.

200: OK The operation completed successfully.

Products

Get Products

`GET` {DeploymentURL}/restapi/products

This call returns the list of all active products in the target deployment. This list can be filtered by specifying a comma-separated list of Product IDs.

Path Parameters

Name Type Description
id List A list of comma-separated Product IDs to filter the results.

200: OK Returned if at least one product is found.

[
    {
        "ProductId": "{ProductID}",
        "Name": "{ProductName}",
        "Description": "{ProductDescription}",
        "CustomProductFields": [
            {
                "Name": "{ProductMetadataFieldName}",
                "Value": "{ProductMetadataFieldValue}"
            },
            {
                "Name": "{ProductMetadataFieldName}",
                "Value": "{ProductMetadataFieldValue}"
            }
        ],
        "CustomProductCategories": [
            {
                "Id": "{ProductCategoryID}",
                "DisplayName": "{ProductCategoryName}"
            },
            {
                "Id": "{ProductCategoryID}",
                "DisplayName": "{ProductCategoryName}"
            }
        ]
    },
    {
        "ProductId": "{ProductID}",
        "Name": "{ProductName}",
        "Description": "{ProductDescription}",
        "CustomProductFields": [
            {
                "Name": "{ProductMetadataFieldName}",
                "Value": "{ProductMetadataFieldValue}"
            },
            {
                "Name": "{ProductMetadataFieldName}",
                "Value": "{ProductMetadataFieldValue}"
            }
        ],
        "CustomProductCategories": [
            {
                "Id": "{ProductCategoryID}",
                "DisplayName": "{ProductCategoryName}"
            },
            {
                "Id": "{ProductCategoryID}",
                "DisplayName": "{ProductCategoryName}"
            }
        ]
    }
]

404: Not Found No products were found matching the criteria.

Orders

Get Orders

`GET` {DeploymentURL}/restapi/orders

This call returns the list of all orders placed between the specified dates. This list can alternatively be filtered by specifying a comma-separated list of order IDs (but one of the two approaches must be used).

Query Parameters

Name Type Description
from DateTime A date with an optional time component (yyyy-MM-dd or yyyy-MM-ddTHH:mm). If the hours and minutes are omitted, the call uses ‘00:00:00’. Must be used in conjunction with the “to” parameter.
to DateTime A date with an optional time component (yyyy-MM-dd or yyyy-MM-ddTHH:mm). If the hours and minutes are omitted, the call uses ‘23:59:59’ (to include all records from the relevant day). Must be used in conjunction with the “from” parameter.
id List A list of comma-separated internal order IDs to filter the results. Cannot be used in conjunction with “from” or “to”.

200: OK Returned if at least one order is found.

[
    {
        "orderId": "{OrderID}",
        "externalId": ""{ExternalOrderID}",
        "userId": "{UserID}",
        "dateTimeOrderPlaced": "{YYYY-MM-DD}T{HH:SS}",
        "approvalWorkflowName": "{WorkflowName}",
        "orderReviewer": "{UserID}",
        "reviewerComment": "{ApproverComment}",
        "handlingCharge": {
            "unit": {CurrencyUnit},
            "amount": {Price}
        },
        "shippingCharge": {
            "unit": {CurrencyUnit},
            "amount": {Price}
        },
        "orderTotal": {
            "unit": {CurrencyUnit},
            "amount": {Price}
        },
        "orderTax": {
            "unit": {CurrencyUnit},
            "amount": {Price}
        },
        "orderWeight": {Weight},
        "orderParts": [
            {
                "id": "{ShipmentID}",
                "orderId": "{OrderID}",
                "documentIdList": [
                    "{ItemID}"
                ],
                "shippingAddress": {
                    "{AddressFieldName}": "{AddressFieldValue}",
                    "{AddressFieldName}": "{AddressFieldValue}"
                }
            }
        ],
        "documentIdList": [
            "{ItemID}"
        ],
        "CustomShippingFields": [
            {
                "Name": "{ShippingFieldName}",
                "Value": "{ShipmentValue}"
            },
            {
                "Name": "{ShippingFieldName}",
                "Value": "{ShipmentValue}"
            }
        ]
    },
    {
        "orderId": "{OrderID}",
        "externalId": ""{ExternalOrderID}",
        "userId": "{UserID}",
        "dateTimeOrderPlaced": "{YYYY-MM-DD}T{HH:SS}",
        "approvalWorkflowName": "{WorkflowName}",
        "orderReviewer": "{UserID}",
        "reviewerComment": "{ApproverComment}",
        "handlingCharge": {
            "unit": {CurrencyUnit},
            "amount": {Price}
        },
        "shippingCharge": {
            "unit": {CurrencyUnit},
            "amount": {Price}"
        },
        "orderTotal": {
            "unit": {CurrencyUnit},
            "amount": {Price}
        },
        "orderTax": {
            "unit": {CurrencyUnit},
            "amount": {Price}
        },
        "orderWeight": {Weight},
        "orderParts": [
            {
                "id": "{ShipmentID}",
                "orderId": "{OrderID}",
                "documentIdList": [
                    "{ItemID}"
                ],
                "shippingAddress": {
                    "{AddressFieldName}": "{AddressFieldValue}",
                    "{AddressFieldName}": "{AddressFieldValue}"
                }
            }
        ],
        "documentIdList": [
            "{ItemID}"
        ],
        "CustomShippingFields": [
            {
                "Name": "{ShippingFieldName}",
                "Value": "{ShipmentValue}"
            },
            {
                "Name": "{ShippingFieldName}",
                "Value": "{ShipmentValue}"
            }
        ]
    }
]

404: Not Found No orders were found matching the criteria.

Get Order Payment Fields

`GET` {DeploymentURL}/restapi/orders/{OrderID}/payment_field

This call returns a list payment fields for the relevant order. Payment fields are deliberately not included in the GET Orders response for security and performance reasons. Fields without field definitions (ad-hoc fields) and secure fields are not returned. This call does not support split payment.

Path Parameters

Name Type Description
OrderID\* String The internal Order ID for which to get payment field data.

200: OK Returns an array of CustomField objects that correspond to the order’s payment fields.

[
        {
                "Name": "{PaymentFieldName}",
                "Value": "{PaymentFieldValue}"
        },
        {
                "Name": "{PaymentFieldName}",
                "Value": "{PaymentFieldValue}"
        }
]

400: Bad Request Invalid request.

404: Not Found The specified order or its payment fields not found.

Approve Order

`PATCH` {DeploymentURL}/restapi/orders/{OrderID}/approve

This call attempts to approve the order. If there are multiple approval workflows, all of these are approved in the single API call. Every ordered document that is subject to approval requires the approval action input structure that contains the Approve and Comment properties.

Path Parameters

Name Type Description
OrderID\* String The internal Order ID to approve.

Request Body

Name Type Description
Actions List <p>A list of approval actions. All items in an order must be included, approval comments are optional.
{ “Actions”: [</p><p>{ “OrderItemId”: “{DocumentID}”, “Approve”: {false/true}, “Comment”: “{Comment}” },</p><p>{ “OrderItemId”: “{DocumentID}”, “Approve”: {false/true}, “Comment”: “{Comment}” }</p><p>] }</p>

200: OK The approval process completed successfully.

400: Bad Request The input data is invalid, or approval may not be required for the specified order.

404: Not Found The specified order was not found.

409: Conflict The ‘409’ response is returned when the order was placed very recently (typically before less than 1 second) and the approval steps have not been fully constructed yet.

504: Gateway Timeout The ‘504’ response typically occurs when there too many approval steps (tiers) and the call could not finish successfully in a timely manner.

Items (Ordered Documents)

Get Items

`GET` {DeploymentURL}/restapi/items

This call returns the list of all ordered documents whose status changed between the specified dates. This list can alternatively be filtered by specifying a comma-separated list of document IDs.

Query Parameters

Name Type Description
from DateTime A date with an optional time component (yyyy-MM-dd or yyyy-MM-ddTHH:mm). If the hours and minutes are omitted, the call uses ‘00:00:00’. Must be used in conjunction with the “to” parameter.
to DateTime A date with an optional time component (yyyy-MM-dd or yyyy-MM-ddTHH:mm). If the hours and minutes are omitted, the call uses ‘23:59:59’ (to include all records from the relevant day). Must be used in conjunction with the “from” parameter.
id List A list of comma-separated internal item IDs to filter the results. Cannot be used in conjunction with “from” or “to”.

200: OK Returned if at least one item is found.

{
    {
        "OrderItemId": "{DocumentID}",
        "ExternalId": "{ExternalDocumentID}",
        "OrderId": "{OrderID}",
        "ProductId": "{ProductID}",
        "Description": "{Description}",
        "Quantity": {Quantity},
        "Price": {
            "unit": "{CurrencyUnit}",
            "amount": {Price}
        },
        "Status": {OrderItemStatus},
        "CustomFormFillFields": [
            {
                "Name": "{FormFillingFieldName}",
                "Value": "{FormFillingFieldValue}"
            },
            {
                "Name": "{FormFillingFieldName}",
                "Value": "{FormFillingFieldValue}"
            },
            {
                "Name": "{FormFillingFieldName}",
                "Value": "{FormFillingFieldValue}"
            }
        ],
        "CustomPrintingFields": [
        		{
                "Name": "{PrintingOptionsFieldName}",
                "Value": "{PrintingOptionsFieldValue}"
            },
        		{
                "Name": "{PrintingOptionsFieldName}",
                "Value": "{PrintingOptionsFieldValue}"
            },
        		{
                "Name": "{PrintingOptionsFieldName}",
                "Value": "{PrintingOptionsFieldValue}"
            }
        ]
    },
    {
        "OrderItemId": "{DocumentID}",
        "ExternalId": "{ExternalDocumentID}",
        "OrderId": "{OrderID}",
        "ProductId": "{ProductID}",
        "Description": "{Description}",
        "Quantity": {Quantity},
        "Price": {
            "unit": {CurrencyUnit},
            "amount": {Price}
        },
        "Status": {OrderItemStatus},
        "CustomFormFillFields": [
            {
                "Name": "{FormFillingFieldName}",
                "Value": "{FormFillingFieldValue}"
            },
            {
                "Name": "{FormFillingFieldName}",
                "Value": "{FormFillingFieldValue}"
            },
            {
                "Name": "{FormFillingFieldName}",
                "Value": "{FormFillingFieldValue}"
            }
        ],
        "CustomPrintingFields": [
        		{
                "Name": "{PrintingOptionsFieldName}",
                "Value": "{PrintingOptionsFieldValue}"
            },
        		{
                "Name": "{PrintingOptionsFieldName}",
                "Value": "{PrintingOptionsFieldValue}"
            },
        		{
                "Name": "{PrintingOptionsFieldName}",
                "Value": "{PrintingOptionsFieldValue}"
            }
        ]
    }
]

404: Not Found No items were found matching the criteria

Update Item Status

`PATCH` {DeploymentURL}/restapi/items

This call updates the Order Item Status value for the ordered items that match the filtering criteria (comma separated list of IDs).

Query Parameters

Name Type Description
id List A list of comma-separated internal item IDs to update.

Request Body

Name Type Description
Status Enumeration The item status to assign the listed items. See Enumerations for possible values. Only the ‘Shipped’, ‘Packed’, ‘Printed’ or ‘Rejected’ statuses are allowed in this call.

200: OK The operation completed successfully for at least one item.

404: Not Found No items were found matching the criteria.