Skip to main content

 

Documentation & User Guides | FotoWare

Using the Order Management API

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. The easiest way is to use server-to-server authentication using the full API key. 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 an 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
200 OK
Content-Type: application/vnd.fotoware.count+json


{"count": 123 }

Querying the Global Order History

Using this API, a client can query all orders on the site (including pending and unsubmitted 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
            
200 OK
Content-Type: application/vnd.fotoware.count+json


{"count": 123 }

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

{
  "orderItems": [
    {
      "rendition": "...",
      "itemData": [{...}, ...],
      "adminComment": "...",
      "expires": "2016-01-01T00:00:00Z"
    },
    {...},
    ...
  ],
  "orderData": [{...}, ...],
  "adminComment": "...",
  "expires": "2016-01-01T00:00:00Z"
}
204 No Content 

If

  • The custom that placed the order does not have "Order" permission in any of the archives containing assets in the request OR IF
  • AT LEAST ONE of the assets or renditions does not exist OR IF
  • The order is not in state pending or created,

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 href attribute of the element in the renditions attribute of an Asset representation, whose original attribute us true:

for rendition in asset.renditions:

  if rendition.original:

    orderItems[i].rendition = rendition.href

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, null if it never 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, null if if never 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 which 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 created, then the response is:

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: 

{
  "orderItems": [
    {
      itemData: [{...}, ...],
      "adminComment": "...",
      "expires": "2016-01-01T00:00:00Z"
    },
    {...},
    ...
  ],
  "orderData": [{...}, ...],
  "adminComment": "...",
  "expires": "2016-01-01T00:00:00Z"
}
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 pendingcreatedrejected or approved, then the response is:

400 Bad Request

The request body (if present) is the same as for the request to update an order (see "Updating an Order" above).

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.

  • Was this article helpful?