Lulu - the Ruby gem for the Universal Publishing Platform API
The Lulu Print API allows you to use Lulu as your production and fulfillment network. The API provides access the same functionality that Lulu uses internally to normalize files and send Print-Jobs to our production partners around the world.
The Lulu Print API is a RESTful API that communicates with JSON encoded messages. Communication is secured with OpenID Connect and transport layer security (HTTPS).
Working with the API requires intermediate level programming skills and a general understanding of web APIs. Take a look at Lulu xPress if you want to check out Lulu's services without having to do technical work upfront.
You have to create an account to start using the Lulu Print API. Your account will automatically receive a client-key and a client-secret.
The API is available in a production and a sandbox environment. The sandbox can be used for development and testing purposes. Print-Jobs created on the sandbox will never be forwarded to a real production and can be paid for with test credit cards.
To access the sandbox, you have to create a separate account at https://developers.sandbox.lulu.com/. The sandbox API URL is https://api.sandbox.lulu.com/
The Lulu API uses OpenID Connect, an authentication layer built on top of OAuth 2.0. Instead of exchanging username and password, the API uses JSON Web Token (JWT) to authorize client requests.
To interact with the API you need a client-key and a client-secret. Open the Client Keys & Secret page to generate them.
<img src="assets/keyAndSecretExample.png">
To interact with the API you first have to generate an OAuth token. This requires the following parameters:
client_key
client_secret
grant-type
must be set toclient_credentials
You have to send a POST request to the token endpoint a special Authorization header. For your convenience, you can copy the authorization string directly from your API Keys page:
curl -X POST https://api.lulu.com/auth/realms/glasstree/protocol/openid-connect/token \\
-d 'grant_type=client_credentials' \\
-H 'Content-Type: application/x-www-form-urlencoded' \\
-H 'Authorization: Basic ZjJjNDdmMTctOWMxZi00ZWZlLWIzYzEtMDI4YTNlZTRjM2M3OjMzOTViZGU4LTBkMjQtNGQ0Ny1hYTRjLWM4NGM3NjI0OGRiYw=='
The request will return a JSON response that contains an access_token
key:
{
\"access_token\":\"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkI...\",
\"expires_in\":3600,
\"refresh_expires_in\":604800,
\"refresh_token\":\"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6...\",
\"token_type\":\"bearer\",
\"not-before-policy\":0,
\"session_state\":\"a856fb91-eafc-460e-8f6a-f09325062c88\"
}
Store this access_token
and use it to authorize all further requests. The token will expire after a few minutes, but you can always request a fresh token from the server as outlined above. We recommend to use an OAuth capable client lib in your favorite programming language to simplify working with client credentials and tokens. Some might even automatically refresh your token after it expired.
To authenticate subsequent API requests, you must provide a valid access token in the HTTP header of the request:
Authorization: Bearer {access_token}
:
curl -X GET https://api.lulu.com/{some_api_endpoint}/ \\
-H 'Authorization: Bearer {access_token}' \\
-H 'Content-Type: application/json'
Lulu’s Print API offers a wide range of products. Each product is represented by a 27 character code call pod_package_id:
Trim Size + Color + Print Quality + Bind + Paper + PPI + Finish + Linen + Foil = pod_package_id
Here are a few examples:
pod_package_id | Description |
---|---|
0850X1100BWSTDLW060UW444MNG |
0850X1100 : trim size 8.5” x 11”BW : black-and-whiteSTD : standard quality LW : linen wrap binding060UW444 : 60# uncoated white paper with a bulk of 444 pages per inch M : matte cover coating N : navy colored linenG : golden foil stamping |
0600X0900FCSTDPB080CW444GXX |
0600X0900 : trim size 6” x 9” FC : full colorSTD : standard qualityPB : perfect binding080CW444 : 80# coated white paper with a bulk of 444 ppiG : gloss cover coatingX : no linenX : no foil |
0700X1000FCPRECO060UC444MXX |
7" x 10" black-and-white premium coil-bound book printed on 60# cream paper with a matte cover |
0600X0900BWSTDPB060UW444MXX |
6" x 9" black-and-white standard quality paperback book printed on 60# white paper with a matte cover |
For a full listing of Lulu SKUs and product specification, download the Product Specification Sheet. Also, please download and review our Production Templates for additional guidance with formatting and file preparation. If you have general questions about which Lulu products are right for your business, please contact one of our experts through our Technical Support form.
Now you can start to create Print-Jobs. A Print-Job request consists of at least three data fields:
line_items
(required): the list of books that shall be printedshipping_address
(required): the (end) customer’s address where Lulu should send the books - including a phone number.contact_email
(required): an email address for questions regarding the Print-Job - normally, you want to use the email address of a developer or shop owner, not the end customershipping_option_level
(required): Lulu offers five different quality levels for shipping:MAIL
- Slowest ship method. Depending on the destination, tracking might not be available.PRIORITY_MAIL
- priority mail shippingGROUND
- Courier based shipping using ground transportation in the US.EXPEDITED
- expedited (2nd day) delivery via air mail or equivalentEXPRESS
- overnight delivery. Fastest shipping available.
external_id
(optional): a reference number to link the Print-Job to your system (e.g. your order number)
The shipping address must contain a phone number. This is required by our shipping carriers. If the shipping address does not contain a phone number, the default phone number from the account will be used. If neither the account nor the shipping address contain a phone number, the Print-Job can not be created.
You can find the detailed documentation for Creating a new Print-Job below.
After sending a Print-Job, you can check its status. Normally, a Print-Job goes through the following stages:
<img src="assets/print-job-stages.svg">
- CREATED: Print-Job created
- UNPAID: Print-Job can be paid
- PAYMENT_IN_PROGRESS: Payment is in Progress
- PRODUCTION_DELAYED: Print-Job is paid and will move to production after the mandatory production delay.
- PRODUCTION_READY: Production delay has ended and the Print-Job will move to "in production" shortly.
- IN_PRODUCTION: Print-Job submitted to printer
- SHIPPED: Print-Job is fully shipped
There are a few more status that can occur when there is a problem with the Print-Job:
- REJECTED: When there is a problem with the input data or the file, Lulu will reject a Print-Job with a detailed error message. Please contact our experts if you need help in resolving this issue.
- CANCELED: You can cancel a Print-Job as long as it is not “in production” with an API request to the status endpoint. In rare cases, Lulu might also cancel a Print-Job if a problem has surfaced in production and the order cannot be fulfilled.
Once an order has been shipped, Lulu will provide tracking information in the Print-Job endpoint.
This SDK is automatically generated by the OpenAPI Generator project:
- API version: 1.0
- Package version: 1.0.0
- Build package: org.openapitools.codegen.languages.RubyClientCodegen
To build the Ruby code into a gem:
gem build lulu.gemspec
Then either install the gem locally:
gem install ./lulu-1.0.0.gem
(for development, run gem install --dev ./lulu-1.0.0.gem
to install the development dependencies)
or publish the gem to a gem hosting service, e.g. RubyGems.
Finally add this to the Gemfile:
gem 'lulu', '~> 1.0.0'
If the Ruby gem is hosted at a git repository: https://github.com/GIT_USER_ID/GIT_REPO_ID, then add the following in the Gemfile:
gem 'lulu', :git => 'https://github.com/GIT_USER_ID/GIT_REPO_ID.git'
Include the Ruby code directly using -I
as follows:
ruby -Ilib script.rb
Please follow the installation procedure and then run the following code:
# Load the gem
require 'lulu'
# Setup authorization
Lulu.configure do |config|
# Configure OAuth2 access token for authorization: oauth2
config.access_token = 'YOUR ACCESS TOKEN'
end
api_instance = Lulu::PrintJobCostCalculationsApi.new
opts = {
inline_object: Lulu::InlineObject.new # InlineObject |
}
begin
#Create a Print-Job cost calculation
result = api_instance.print_job_cost_calculations_create(opts)
p result
rescue Lulu::ApiError => e
puts "Exception when calling PrintJobCostCalculationsApi->print_job_cost_calculations_create: #{e}"
end
All URIs are relative to https://api.lulu.com
Class | Method | HTTP request | Description |
---|---|---|---|
Lulu::PrintJobCostCalculationsApi | print_job_cost_calculations_create | POST /print-job-cost-calculations/ | Create a Print-Job cost calculation |
Lulu::PrintJobsApi | print_jobs_costs | GET /print-jobs/{id}/costs/ | Retrieve Print-Job Costs |
Lulu::PrintJobsApi | print_jobs_create | POST /print-jobs/ | Create a new Print-Job |
Lulu::PrintJobsApi | print_jobs_list | GET /print-jobs/ | Retrieve a list of Print-Jobs |
Lulu::PrintJobsApi | print_jobs_read | GET /print-jobs/{id}/ | Retrieve a single Print-Job |
Lulu::PrintJobsApi | print_jobs_statistics | GET /print-jobs/statistics/ | Retrieve the number of Print-Jobs in each status |
Lulu::PrintJobsApi | print_jobs_status_read | GET /print-jobs/{id}/status/ | Retrieve Print-Job Status |
Lulu::ShippingOptionsApi | deprecated_shipping_options_list | GET /shipping-options/ | Retrieve List of Shipping Options |
Lulu::ShippingOptionsApi | shipping_options_list | GET /print-shipping-options/ | Retrieve List of Shipping Options |
- Lulu::BadRequestError
- Lulu::ConflictError
- Lulu::Discount
- Lulu::Error
- Lulu::ForbiddenError
- Lulu::InlineObject
- Lulu::InlineObject1
- Lulu::InlineResponse200
- Lulu::InlineResponse2001
- Lulu::InlineResponse2001LineItemCosts
- Lulu::InlineResponse2002
- Lulu::InlineResponse200LineItems
- Lulu::InlineResponse200Reprint
- Lulu::InlineResponse201
- Lulu::InlineResponse2011
- Lulu::InlineResponse201Discounts
- Lulu::InlineResponse201LineItemCosts
- Lulu::InlineResponse201ShippingCost
- Lulu::LegacyAddress
- Lulu::Pagination
- Lulu::PrintFileNormalization
- Lulu::PrintJob
- Lulu::PrintJobCost
- Lulu::PrintJobCostCalculation
- Lulu::PrintJobCostCalculationLineItem
- Lulu::PrintJobCostWithLineItemIds
- Lulu::PrintJobDetail
- Lulu::PrintJobLineItem
- Lulu::PrintJobLineItemCost
- Lulu::PrintJobLineItemDetail
- Lulu::PrintJobStatus
- Lulu::PrintJobStatusName
- Lulu::PrintJobsStatistics
- Lulu::PrintjobcostcalculationsLineItems
- Lulu::PrintjobcostcalculationsShippingAddress
- Lulu::PrintjobsCosts
- Lulu::PrintjobsEstimatedShippingDates
- Lulu::PrintjobsLineItems
- Lulu::PrintjobsPrintableNormalization
- Lulu::PrintjobsPrintableNormalizationCover
- Lulu::PrintjobsPrintableNormalizationInterior
- Lulu::PrintjobsPrintableNormalizationInteriorNormalizedFile
- Lulu::PrintjobsShippingAddress
- Lulu::PrintjobsStatus
- Lulu::PrintjobsStatusMessages
- Lulu::PrintjobsStatusMessagesPrintableNormalization
- Lulu::ShippingOption
- Lulu::ShippingOptionLevel
- Lulu::ShorthandPrintFileNormalization
- Lulu::UnauthorizedError
- Lulu::UnavailableError
- Type: OAuth
- Flow: password
- Authorization URL:
- Scopes: N/A