Skip to main content

 

Documentation & User Guides | FotoWare

Using the Shopping Cart API

All requests in the shopping cart API are made on behalf of a customer (who is also the request user) and therefore require authentication as that user. Every user (except the Guest user) has a personal shopping cart and a personal order history. When adding items to the shopping cart, the user must have "Order" permission on the assets being added. It is not possible for a customer to access another customer's personal shopping cart or personal order history.

See Endpoints regarding authentication and how to test if the shopping cart API is available.

Adding Assets to to the Shopping Cart

This API adds the default renditions of a given set of assets to the customer's personal shopping cart.

All assets MUST be given by their URL in their originating archive (href, not linkstance, see "Asset Representation"). The customer MUST have "Order" permission in the archives containing all assets. FOR EACH asset, at least one processing profile of the archive MUST be available. IF AT LEAST ONE asset fails these requirements, then the request fails with 403 Forbidden.

If the default processing profile of the archive is not available for an asset, then an alternative profile will be selected. This will be "Original File", if available, or the first available profile (in definition order). If no profile is available, then the request fails.

The default processing profile of an archive is:

  1. "Original file", if no processing profile is set for the archive
  2. The processing profile that is set for the archive, if any
  3. The default processing profile of the processing profile set that is set for the archive, if any

In cases 2 and 3, the default processing profile of the archive may be applicable only to images, so it is not available for non-image assets, so adding a non-image asset to the cart will cause the entire request to fail.

Request

Response

POST api_descriptor.order.cart
Content-Type: application/vnd.fotoware.assetlinklist+json

with a request body of

{
  data: [
    {href: "..."},
    {...},
    ...
  ]
}

where

  • data is an array of assets to add to the cart, and
  • href is the URL of the asset to add to the cart.
204 No Content

If AT LEAST ONE asset cannot be added, then the response is:

403 Forbidden

If AT LEAST ONE asset does not exist, then the response is:

400 Bad Request

Querying the Shopping Cart

This API can be used to get the contents of the shopping cart.

Request

Response

GET api_descriptor.order.cart
Accept: application/vnd.fotoware.order+json
200 OK
Content-Type: application/vnd.fotoware.order+json

The response body is the Order representation of the shopping cart.

The following request can be used to get the number of ordered items in the shopping cart:

Request

Response

GET api_descriptor.order.cart
Accept: application/vnd.fotoware.count+json
200 OK
Content-Type: application/vnd.fotoware.count+json


{"count": 123}

Modifying the Shopping Cart

This request can be used to change the contents of the shopping cart. For example, it can add or remove ordered items, change renditions for ordered assets, add custom order data or add a customer's comment to the order.

Request

Response

PUT api_descriptor.order.cart
Content-Type: application/vnd.fotoware.cart-update+json

with a request body of

{
  "orderItems": [
    {
      "itemData": [{...}, ...],
      "rendition": "...",
    },
    {...},
    ...
  ],
  "orderData": [{...}, ...],
  "userComment": "..."
}
204 No Content

If the user does not have "Order" permission in the archives of any of the assets in the request, then the response is

403 Forbidden

If any of the assets or renditions in the request do not exist, then the response is

400 Bad Request

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 shopping cart.

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

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.
userComment String Comment by the customer on the order.  

For each ordered item, the rendition must refer to an asset in an archive where the customer has "Order" permission and to a processing profile which is available in the archive and for the given asset.

Note:

  • Some processing profiles are available to images only. Which processing profiles are available for an asset can be determined from the Asset representation.
  • The list of renditions must be obtained from an Asset representation that was requested from an archive, e.g., using the asset's href URL. Using an Asset representation from an album does not work.

If the site configuration defines Custom Order Data, then all item fields or order item fields that have a value must have valid values according to the configured validation rules. However, when updating the shopping cart, it is NOT required that all required custom order data fields have values. This is only required when submitting the order.

Submitting the Shopping Cart to an Order

This request submits the customer's personal shopping cart to a new order.

Request

Response

POST api_descriptor.order.history
Content-Type: application/vnd.fotoware.cart-update+json
Accept: application/vnd.fotoware.order-submission-info+json


{...}

with a request body of 

{
  "orderItems": [
    {
      "itemData": [{...}, ...],
      "rendition": "...",
    },
    {...},
    ...
  ],
  "orderData": [{...}, ...],
  "userComment": "..."
}
201 Created
Location: ORDER_URL
Content-Type: application/vnd.fotoware.order-submission-info+json


{
  orderLocation="...",
  orderReference="...",
  checkoutPageLocation="..." | null
}

If the user does not have "Order" permission in the archives of any of the assets in the request, then the response is

403 Forbidden

If any of the assets or renditions in the request do not exist, then the response is

400 Bad Request

The request parameters are explained above under Modifying the Shopping Cart

If the request was successful, then the response contains the following attributes:

Attribute

Type

Description

orderLocation Link (string) URL of the order. Links to an Order representation.
orderReference String

A human-readable string that uniquely identifies the order on the site.

May be shown in notifications and used for communication with users.

Same as the orderReference attribute in the Order representation.

checkoutPageLocation Link (string)

URL of the checkout page to show to the user. This page SHOULD be shown to the customer in a browser window in order to proceed with the ordering process.

Depending on the site settings, this may be the standard FotoWeb checkout page or a custom page (which may include payment options).

A native application may provide its own native checkout user interface and ignore this parameter.

This is equal to the checkoutPageLocation attribute of the Order representation.

After a successful request, the customer's shopping cart is empty.

If the site configuration defines Custom Order Data, then all item fields or order item fields that have a value must have valid values according to the configured validation rules. Furthermore, all required custom order data fields MUST have values.

If custom integration is NOT enabled in the site settings, then:

  • The order is in state pending.
  • The order appears in the list of pending orders, which can be requested using the Order Management API.
  • To proceed with the order process, an administrator must approve the order. This can be done interactively by an administrator in the FotoWeb interface or by an API client or third-party interactive application using the Order Management API.

If custom integration is enabled in the site setting, then:

  • The order is in state created.
  • The order does NOT appear in the list of pending orders.
  • To proceed with the order process, a custom integration must do one of the following:
    • Approve the order using the Order Management API (for example after successful payment).
    • Submit the order to the list of pending orders using the Order Management API. The order then has to be approved by an administrator. This can be done interactively by an administrator in the FotoWeb interface or by an API client or third-party interactive application using the Order Management API.

Approval of the order is always done by a different entity (e.g., an administrator using the interactive FotoWeb interface or a third-party application or a checkout server after verifying payment).

Normally, the customer is notified by email when an order has been approved or rejected. An API client can track the state of a pending order as follows:

  • By periodically requesting the Order representation of the order form the orderLocation URL (polling)
  • By periodically requesting the customer's order history (see above) and checking the state of the most recent orders

 

Downloading Renditions from an Approved Order

Once an order has been approved, a customer can download the ordered renditions. The process is exactly the same as downloading renditions from collections where a user has download permission, and it is described in Renditions.

The rendition URL is obtained from rendition.download attribute in the Order representation of the order:

{
  ...,
  "orderItems": [
    {
      ...,
      "rendition": "...",
      ...
    },
    {...},
    ...
  ],
  ...

Download of renditions from an approved order does not require any permissions in the archives of the assets (e.g., the customer does not need to have "Download" permission, and SHOULD NOT have "Download" permission anyway, because it would allow the customer to simply download all renditions of all assets without ordering and paying for them).

A rendition can be downloaded from an order IF AND ONLY IF the rendition.download attribute is not null. This is the only condition that a client should check when deciding whether to show a "download" button or whether to attempt to download the rendition. A rendition can usually be downloaded if:

  • The order is in state approved.
  • The order has not expired (state != 'expired').
  • The order item has not expired (expired == false).

Attempting to download from an unapproved or expired order or order item results in the rendition request to fail with 403 Forbidden. The rendition request will also fail with 403 Forbidden if the request user is not the customer that placed the order. It will fail with 400 Bad Request if the order does not exist.

Putting items from an Order back into the Shopping Cart

Customers can copy items from one of their orders back into their shopping cart. The following API request performs this operation:

Request

Response

REORDER order_url
204 No Content

If the order contains any assets to which the customer does not have "Order" access, then the response is:

403 Forbidden
  • Was this article helpful?