Using the Shopping Cart API

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.

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

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

204 No Content

403 Forbidden

400 Bad Request

Querying the Shopping Cart

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

GET api_descriptor.order.cart
Accept: application/vnd.fotoware.order+json

200 OK
Content-Type: application/vnd.fotoware.order+json

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

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.

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

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

204 No Content

403 Forbidden

400 Bad Request

The request contains the following parameters:

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.

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


{...}

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

201 Created
Location: ORDER_URL
Content-Type: application/vnd.fotoware.order-submission-info+json


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

403 Forbidden

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:

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:

REORDER order_url

204 No Content

403 Forbidden