AboutContactLogin

Index

Self-fulfilled URL Access

Zenfolio provides an advanced method for accessing self-fulfilled orders through special URLs. These URLs can be used to download order details, receipt or photos. It can also be used to download pending order or update state of an order.

Privilege

To make use of any of the following functionality, the authenticated user should have the URL download order privilege.

NOTE: Access to self-fulfillment URLs is available exclusively to High Volume accounts. Please contact us for more details.

When an account is given the URL access to self-fulfilled orders, the sub account users can also make use of the same functionality but only Partner and Assistant sub-accounts are given access to the URLs.

The URL access can be disabled by setting the API access in preferences to Do not allow accessing my account through Zenfolio API's. For more information refer the support center article.

Constructing URLs

Format of the URL:

http://zenfolio.com/{UserName}/order-tools/{action}

Here {UserName} should be replaced with the actual name of the user. The {action} is the type of request that needs to be performed. The supported values for action are list, download and update. Each of these actions supports a set of query strings and specific values for each. If the URL is constructed with invalid action or query string parameters then an appropriate error is returned through the header. For more information on specific errors see Return Codes.

Authentication

To verify the identity of the user accessing the URL, each request needs to have the authentication token passed. The authentication token can be obtained by using the Zenfolio APIs. The token can be passed as a query string parameter named token or using the HTTP headers.

To pass the authentication using query string, append a parameter named token to the URL.

Example:

/order-tools/list?token=AiBt0LW92zb1f/g-p1GXQXpOunNpFyQWS5/LxU=

The token can also be passed through a HTTP header named X-Zenfolio-Token.

Example:

X-Zenfolio-Token: AiBt0LW92zb1f/g-p1GXQXpOunNpFyQWS5/LxU=

Any URL requested without passing token through a query string or through header would return an authentication error. For detailed information on authentication, refer to the Zenfolio API documentation.

list

This URL lists pending orders for a photographer. The list can be filtered by state of the order and by providing the list of gallery ids.

/order-tools/list?state=(waiting|processing)&gallery-ids=<CSV of gallery IDs>

By default, all pending orders are listed unless a different state is specified. The state can be either waiting or processing.

To filter the order by a set of galleries, provide the list for gallery ids separated by comma and pass it through the parameter named gallery-ids.

/order-tools/list?state=waiting&gallery-ids=376225641,248578574&token=...

download

The download action offers different options to download order details, receipt and images associated with it. The receipt and the order details are downloaded in the form of a CSV file and can be opened by using any spreadsheet tool.

Images can also be downloaded along with receipt and order details. When specified it downloads the original images associated with the order.

The query string parameter options is used to specify the content that are required to download, it accepts the values products to download order details, receipt to download receipt and photos to download original images. The parameter ref is used to pass the order reference ID.

Multiple files can be requested by separating the options with a semi-colon. When multiple files are requested, all the files are compressed into a zip file and downloaded.

/order-tools/download?options=products;receipt;photos&ref=ZF-0295-36708-3&token=...

When the options parameter is empty then the order product details, receipt and photos are downloaded as a zip file.

update

A self-fulfilled order's state can be updated by passing the order reference ID and the state. The list of commands allowed to update the state of an order are accept, ship and cancel. The state of an order can only be moved forward. For example setting an order state to accept for an order that is marked as shipped is invalid.

By default an email is sent when a state is changed successfully, this can be overridden by passing a query string that would suppress sending a mail to the customer.

/order-tools/update?state=ship&ref=ZF-0295-36708-3&email=0&token=...

Response Codes

The response is returned through HTTP headers only and no text response is returned to the browser window. In here you can find various responses the URL would throw which would be helpful in diagnosing in case of any issues.

  • 200 - OK: A status code of 200 indicates that the action has completed successfully
  • 403 - Forbidden - User not authorized: The user is not given the URL access to orders. Contact our support center to enable access to the account. The error can also be thrown when a sub account other than a Partner or Assistant is trying to access the URL. This is also the case when an order that do not belong to the photographer is accessed.
  • 403 - Invalid user: The error occurs when the user name is not properly specified in the URL.
  • 403 - Not authenticated: The error occurs when the user token cannot be validated properly. To better understand the URL token, refer the API documentation on Authentication.
  • 403 - API access forbidden: Typical case when the API access is disabled in the user preference.
  • 400 - Invalid order: When any order other than a self-fulfilled is requested.
  • 400 - Invalid state: The cause of this exception can happen in couple of places. While accessing list of pending orders, if the query string parameter state contains any values other than waiting or processing. The second case is while updating state of an order, when a state is specified to move back or if the same state is specified again.
  • 404 - Order not found: Double check to make sure the order reference ID passed through the parameter ref is correct.
  • 404 - Videos not ready: When an attempt is made to download a video that is still being processed.
  • 404 - Order has no photos: When an attempt is made to download an order with deleted images.