Table of Contents
Using the Order Management API
02. April 2025
Table of Contents
All requests in the order management API are made on behalf of an administrator and require authentication as a user that has the Approve Orders permission. You can use the non-interactive OAuth to do so. Alternatively, any other authentication mechanism can be used, as long as the authenticated request user has the Approve Orders permission.
All requests of this API return 403 Forbidden if the request user does not have this permission.
A user that has "Approve Orders" permission can approve ALL pending orders and allow users to download ordered renditions.
Interactive login credentials for an administrator user SHOULD ONLY be given to trusted persons.
API credentials for administrator users SHOULD NOT be stored in a native application that runs on a device that is under the control of regular users (e.g., mobile apps installed by customers on their phones). Order management by this API SHOULD be done by server-side components only, for example, a web server with a custom checkout page that is integrated with a payment solution.
Querying the List of Pending Orders
Pending orders are orders with a state attribute of "pending". They have been submitted but need approval by an administrator. Using this API, a client can get the list of all pending orders on a site in order to display them to an administrative user or approve or reject them automatically.
| Request | Response |
|---|---|
GET api_descriptor.order.admin.pending Accept: application/vnd.fotoware.orderlist+json |
200 OK Content-Type: application/vnd.fotoware.orderlist+json The body of the response is an Order List representation of the list of pending orders. |
The following request can be used to get the total number of pending orders on the site, e.g., in order to update a badge in a user interface:
| Request | Response | ||
|---|---|---|---|
GET api_descriptor.order.admin.pending Accept: application/vnd.fotoware.count+json |
|
Querying the Global Order History
Using this API, a client can query all orders on the site (including pending and un-submitted orders, but not including users' shopping carts) or all approved or all rejected orders. This is useful for generating reports or for changing the approval states of already approved or rejected orders:
| Request | Response |
|---|---|
GET api_descriptor.order.admin.history Accept: application/vnd.fotoware.orderlist+json GET api_descriptor.order.admin.approved Accept: application/vnd.fotoware.orderlist+json GET api_descriptor.order.admin.rejected Accept: application/vnd.fotoware.orderlist+json |
200 OK Content-Type: application/vnd.fotoware.orderlist+json The body of the response is an Order List representation of the requested list of orders. |
It is also possible to get the total number of all orders in each of these lists, for example:
| Request | Response | ||
|---|---|---|---|
GET api_descriptor.order.admin.history Accept: application/vnd.fotoware.count+json |
|
Updating an Order
This request can be used to modify an existing order that is in pending or created state.
| Request | Response | ||
|---|---|---|---|
PATCH order_url Content-Type: application/vnd.fotoware.order-update+json with a request body of
|
204 No Content If
then the response is: 400 Bad Request If the order does not exist, then the response is: 404 Not Found |
The request contains the following parameters:
| Attribute | Type | Description | Example | |
|---|---|---|---|---|
orderItems |
List of objects | Complete list of ordered items. This replaces the existing list. | Set to [] to empty the order. |
|
orderItems.itemData |
List of objects | Custom order data for an ordered item. See Custom Order Data | ||
orderItems.rendition |
Link (string) |
Rendition URL of rendition to order. This also identifies the asset. The rendition URL can be obtained from an Asset representation. See also Renditions. |
To order an original file, put in the
The administrator may not have "Browse" access to some of the archives containing assets in this order. Modifying renditions or adding new renditions as the administrator may not always be possible. |
|
orderItems.adminComment |
String | Comment by the administrator on the order item | ||
orderItems.expires |
ISO8601 Date/Time |
Time when order item expires, After the expiration time, the customer cannot download this rendition any more. |
||
orderData |
List of objects |
Custom order data for the order. See Custom Order Data Completely replaces existing custom order data. |
Set to [] to remove all custom order data. |
|
adminComment |
String | Comment by the administrator on the order. | ||
expires |
ISO8601 Date/Time |
Time when this order expires, After the expiration time, the customer cannot download any renditions from this order any more. |
For each ordered item, the rendition must refer to an asset in an archive where the customer who placed the order has Order permission and to a processing profile that is available in the archive and for the given asset.
Submitting an Order
This request allows a custom integration to submit an order to the list of pending orders. For example, an integration may, after successful payment, require administrator approval of an order. The order must be in state created.
| Request | Response |
|---|---|
SUBMIT order_url |
204 No Content If the order is not in state 400 Bad Request If the order does not exist, then the response is: 404 Not Found |
If the request was successful, then the order is in state pending and appears in the pending order list. It can be approved by an administrator using the interactive FotoWeb interface or on behalf of an administrator by an API client or third-party interactive application.
Approving or rejecting an Order
This API can be used to approve or reject a pending order.
Any order administrator can approve or reject orders.
| Request | Response | ||
|
The following requests can be used to approve and reject orders: APPROVE order_url REJECT order_url It is also possible to update an order and to approve or reject it in the same request: APPROVE order_url Content-Type: application/vnd.fotoware.order-update+json Accept: application/vnd.fotoware.order+json REJECT order_url Content-Type: application/vnd.fotoware.order-update+json Accept: application/vnd.fotoware.order+json For both of these requests, the request body looks as follows:
|
200 OK Content-Type: application/vnd.fotoware.order+json The body of the response is an Order representation of the approved or rejected order. If the order does not exist, then the response is: 404 Not Found If the order is not in one of the states 400 Bad Request |
The request body (if present) is the same as for the request to update an order (see Updating an Order).
This means that the client MUST add all renditions that will be in the approved or rejected order to the orderItems array, otherwise the order will be cleared. If no modifications should be made to the order, it is best to first get the Order representation of the order and then use it to fill in the request data for this request.
Approving or rejecting an order causes an email notification to be sent to the customer.