Data Structures

Project

Description

A representation of a book or eBook that is to be published or has already been published. The only difference between unpublished and published projects is that a published project has a content ID. The content ID is a unique value, assigned by the creation API, that allows you to reference the project.

Example

This is a sample JSON-formatted project object.

"project" : {
    "project_type": "hardcover",
    "bibliography": {
        "title": "Books...With Jackets",
        "authors": [{"first_name": "arthur", "last_name": "the author"}],
        "category": 1,
        "description": "read it, you'll like it",
        "keywords": ["cat and dog", "pickle"],
	"edition": "First",
        "copyright_year": 2000,
        "copyright_citation": "by Arthur Author",
        "publisher": "Lulu.com",
        "license": "Public Domain",
        "language": "EN",
        "country_code": "US"
    },
    "file_info": {
        "contents": [{"mimetype": "application/pdf", "file_id": 5320}],
        "cover": [{"mimetype": "application/pdf", "file_id": 5483}]
    },
    "program_code": "",
    "access": "public",
    "distribution": [], 
    "allow_ratings": false,
    "drm": false,
    "isbn": { "intent": "assigned" },
    "physical_attributes": {
        "color": false,
        "trim_size": "US_TRADE",
        "binding_type": "jacket-hardcover",
        "paper_type": "regular"
    },
    "pricing": [
        {"total_price": 39.95, "product": "print", "discount_percent": 10, "currency_code": "EUR"}
    ]
}

Fields

Field Data Type Required? Description
content_id integer no The unique project identifier. This value may not be provided for a create call, but is required for all other calls
project_type string yes The type of project. Supported values are: "softcover", "hardcover", and "ebook". Once this value is set for a project, it can not be changed.
program_code string no The partner or publisher program in which the project is entered. See Lulu Publisher Program for details
access string yes The visibility for this project. Supported values are: "private" and "public". See below for an explanation of how this impact sales.
distribution list of strings no Where the product should be sold. Supported values are: "lulu_marketplace", "retail_channels", an empty list, or any combination. If the property is missing from the project data structure, this defaults to "lulu_marketplace". See below for an explanation of how this impact sales.
allow_ratings boolean no Can users rate and review your book within the Lulu marketplace? The default is True.
drm boolean yes for eBooks Should DRM be applied to the eBook? This value is not supported for physical books.
bibliography
data structure yes The project's bibliographic information
isbn
data structure no ISBN information for the project. If no isbn structure is found, the API assumes that no ISBN should be assigned to the project.
physical attributes
data structure yes for physical books The physical properties of the book. This value is not supported for eBooks.
pricing
list of data structures yes Pricing information for the project. You can specify one pricing object per medium, as defined by pricing.product.
file_info
data structure yes Cover and content document information.

Bibliography

Description

A data structure representing the bibliographic information for this project.

Fields

Field Data Type Required? Description
title string yes The title of the project. Must be less than 256 characters.
authors
list of data structures yes A list of the authors of this project. At least one author is required to create a project.
category integer yes An Integer representation of the category for this project. See the list of available categories.
description string yes A description of the book or eBook. This is displayed to buyers in the marketplace.
copyright_year integer no The 4-digit year that the book was copyrighted.
keywords list of strings no A list of keywords to help buyers find this project. Each keyword can be up to three words. The total length of keywords must not exceed 512 characters. These words will be used in the search system.
license string no The license under which the project is published. For example: "Public Domain", "Creative Commons Attribution-Share Alike 2.5". The default value is "Standard Copyright License".
copyright_citation string no The name of the copyright holder.
publisher string no The name of the publisher.
edition string no The edition of the project being published. This is a free-form string, but to follow industry standards, this should be similar to "First edition" or "14th". There is a 32 character limit.
language string yes The 2-letter ISO 639-1 code representing the language in which the project is written.
country_code string yes The 2-letter ISO 3166-1 code representing the country of origin of the project.

Authors

Description

A data structure representing the a single author for the project. This structure does not create a relationship between the Lulu user account and this project.

Future versions of this data structure will allow you to reference specific Lulu Account Ids.

Fields

Field Data Type Required? Description
first_name string yes (or last_name) The first name of the author. There is a 32 character limit on this field.
last_name string yes (or first_name) The last name of the author. There is a 32 character limit on this field.

ISBN

Description

A data structure representing the ISBN information for this project.

Note: Some distribution channels require an ISBN, while others forbid one. It is important that your project include an ISBN if you expect it to be treated as a book by any retailer other than Lulu.

Fields

Field Data Type Required? Description
intent string yes Whether the project has or should have an ISBN. There are three supported values: "none", "assigned", and "provided". "None" indicates that you do not wish to have an ISBN. "Assigned" indicates that you would like Lulu to assign an ISBN that we have registered. "Provided" indicates that you already have an ISBN for this project which you have registered yourself.
number string yes (if intent is "provided" The ISBN that is or should be assigned to the book. When provided for creation, either a 10- or 13- digit ISBN will be accepted with or without dashes. However, it will be stored and retrieved as a 13-digit value without dashes.
publisher string yes (if intent is "provided" The publisher name as registered with the ISBN agency from which the ISBN was obtained. It is very important that this be exactly as it is registered with the ISBN agency.
contact_info
data structure yes (if intent is "provided" The contact information for the publisher as registered with the ISBN agency from which the ISBN was obtained. It is very important that this be exactly as it is registered with the ISBN agency.

Contact Information

Description

A data structure representing the contact information for the publisher of the project. All fields must be exactly as they are registered with the ISBN agency.

Fields

Field Data Type Required? Description
name string yes The name of the publisher.
street1 string yes The first portion of the street address.
street2 string no The second portion of the street address.
city string yes The city for the supplied address.
state string yes The two character state code for the supplied address. Only required if the country has states.
postal_code string yes The postal code for the supplied address.
country string yes The two character country code for the supplied address.
phone string yes The contact telephone number.

Physical Attributes

Description

A data structure representing what the book will look like when it is manufactured. This structure is only specified for physical books. It is essential that all information in this structure be accurate, as it determines which printers can manufacture the book, and the cost of manufacturing.

Due to the nature of the manufacturing process, there are limits to what can be manufactured. For details about the minimum and maximum number of pages for each binding type and paper weight, see this page.

Fields

Field Data Type Required? Description
binding_type string yes The requested book binding type. The available options depend on the project type. Softcover books support: "perfect", "saddle-stitch", and "coil". Hardcover books support: "jacket-hardcover" and "casewrap-hardcover".
trim_size string yes The size of the book. See the list of available trim sizes.
paper_type string yes The quality of paper to use. The valid paper types are: "premium", "regular", and "publisher-grade".
color boolean yes Does the project contain full color pages in the interior of the book. If any page in the book includes color, this must be True.

Pricing

Description

The pricing information for this project. This allows you to control the details of how your users are billed for this project. The royalty for creators is 80% of net proceeds (difference between the purchase price and the manufacturing cost). However, creators can purchase their own books at manufacturing cost. This is determined by comparing the account ID of the buyer with the account ID that was used to create the book, either through the site or the API. If you publish using your user's accounts, and they buy the book, there will be no royalty paid. To determine the manufacturing cost, use the GetBaseCost API.

Fields

Field Data Type Required? Description
product string yes The medium the buy will retrieve the book through. Valid options are "print" for books, and "download" for eBooks.
currency_code string yes The currency used when pricing the book. Supported values are: "USD", "GBP", and "EUR". When purchased, the price will be converted to the user's currency based on current conversion rates.
royalty float no The creator's royalty. This value is ignored for create and update APIs as the value is calculated from the price.
total_price float yes The price that end-users will be charged for this product.
discount_percent int no A discount you would like to apply to the price of the book. Your project will be listed on Lulu.com for the total_price less the discount percentage. On all retail distribution channels, it will be listed at the total_price. If discount_percent is not specified, no discount will be applied. Valid percentages are: 0, 5, 10, 15, 20, 25, 30, 40, 50, 60, and 75, 100

File Information

Description

The components of the book.

Fields

Field Data Type Required? Description
cover list of data structures yes The cover of the book.
contents list of data structures yes The files used to create the book's interior.

File

Description

A representation of the files used to create the cover and book interior. All files must have been uploaded through the file management APIs or through the site before they can be referenced here.

Fields

Field Data Type Required? Description
mimetype string yes The mimetype of the file. Only two values are currently supported: "application/pdf" and "application/epub+zip". This value is currently ignored during Create and Update API calls.
file_id integer yes (if filename not provided) The file identifier of a previously uploaded or generated file to use. This is the preferred way of referring to a file in the system.
filename string yes (if file_id not provided) The name of the uploaded file to use. Note: this is no longer the preferred method of indicating a file. Use the file id instead. See uploading files (deprecated) for more information on filenames.

Where is it sold?

Description

Lulu supports a variety of ways to sell your book. When working with projects, you can determine where it will be sold. This is specified with a combination of the access and distribution fields.

The supported values for access are:

  • public - The book is available to everybody within the Lulu.com Bookstore
  • private - The book is only available to the user who published the book.

The supported values for distribution are:

  • lulu_marketplace - Sell the book on the Lulu.com Bookstore
  • retail_channels - Sell the book on all external channels that support this book
  • empty list - A special value that indicates you don't want the book available on Lulu.com through the bookstore. Projects with this value are still available for sale, but the buyer must know the full URL of the product page to buy the project. This is referred to as direct access on Lulu.com

By combining these values, the user can control where the book is sold.

Note: If you want to specify an empty list for the distribution field, you must include the field in your project data structure. If you leave the field out of the data structure completely, the API will default to "lulu_marketplace".