CloudSignal pushes item-based production and shipment events (order validated, item produced, item shipped with tracking, item error, item cancelled) as small JSON POSTs to a configured CloudCore API interface, retrying up to 100 attempts over 7 days until a 200/204 is returned.
openapi: 3.0.1
info:
title: Cloudprinter CloudCore API
description: >-
The Cloudprinter.com CloudCore API is a JSON REST interface for the global
print-on-demand and print-fulfillment network. All calls are HTTP POST and
authenticate with a CloudCore apikey supplied in the JSON request body. The
API exposes product catalog lookups, real-time price and shipping quotes,
order creation and management, and shipping reference data. Production and
shipment events are delivered separately via CloudSignal webhooks.
termsOfService: https://www.cloudprinter.com/terms-conditions
contact:
name: Cloudprinter.com Support
url: https://www.cloudprinter.com/contact
version: '1.0'
servers:
- url: https://api.cloudprinter.com/cloudcore/1.0
description: CloudCore API v1.0 production server
security:
- apikeyBody: []
tags:
- name: Orders
description: Create, list, retrieve, cancel, and audit print orders.
- name: Products
description: List products and retrieve product specifications and options.
- name: Quotes
description: Request real-time product and shipping price quotes.
- name: Shipping
description: Shipping levels, supported countries, and states reference data.
paths:
/orders/:
post:
operationId: listOrders
tags:
- Orders
summary: List orders
description: Request a list of all orders for the account.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyRequest'
responses:
'200':
description: A list of orders.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderListResponse'
'403':
$ref: '#/components/responses/Forbidden'
/orders/info:
post:
operationId: getOrderInfo
tags:
- Orders
summary: Get order info
description: >-
Retrieve comprehensive details for a specific order including addresses,
items, files, and current state.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderReferenceRequest'
responses:
'200':
description: Order details.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'403':
$ref: '#/components/responses/Forbidden'
'410':
$ref: '#/components/responses/NotFound'
/orders/add:
post:
operationId: addOrder
tags:
- Orders
summary: Add order
description: >-
Create a new order with items, addresses, options, and print file
references. Items may reference a quote hash or specify a shipping level
directly.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddOrderRequest'
responses:
'201':
description: Order created.
content:
application/json:
schema:
$ref: '#/components/schemas/AddOrderResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
/orders/cancel:
post:
operationId: cancelOrder
tags:
- Orders
summary: Cancel order
description: Request cancellation of an order that has not yet entered production.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderReferenceRequest'
responses:
'200':
description: Cancellation accepted.
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
'410':
$ref: '#/components/responses/NotFound'
/orders/log:
post:
operationId: getOrderLog
tags:
- Orders
summary: Order log
description: Retrieve the historical state changes for an order.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderReferenceRequest'
responses:
'200':
description: Order state-change log.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderLogResponse'
'403':
$ref: '#/components/responses/Forbidden'
'410':
$ref: '#/components/responses/NotFound'
/orders/quote:
post:
operationId: getOrderQuote
tags:
- Quotes
summary: Order quote
description: >-
Calculate product prices and shipping options for a list of items in a
destination country. Each returned quote carries a unique hash valid for
48 hours that can be referenced when adding an order.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QuoteRequest'
responses:
'200':
description: Quote results with product prices and shipping options.
content:
application/json:
schema:
$ref: '#/components/schemas/QuoteResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
/products:
post:
operationId: listProducts
tags:
- Products
summary: List products
description: Request a list of all products already enabled for the account.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyRequest'
responses:
'200':
description: A list of products.
content:
application/json:
schema:
$ref: '#/components/schemas/ProductListResponse'
'403':
$ref: '#/components/responses/Forbidden'
/products/info:
post:
operationId: getProductInfo
tags:
- Products
summary: Product info
description: >-
Get detailed specifications, available options, and pricing for a single
product by its product reference.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductInfoRequest'
responses:
'200':
description: Product specification and options.
content:
application/json:
schema:
$ref: '#/components/schemas/ProductInfo'
'403':
$ref: '#/components/responses/Forbidden'
'410':
$ref: '#/components/responses/NotFound'
/shipping/levels:
post:
operationId: getShippingLevels
tags:
- Shipping
summary: Shipping levels
description: Retrieve the available shipping service tiers (cp_fast, cp_saver, cp_ground, cp_postal).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyRequest'
responses:
'200':
description: Available shipping levels.
'403':
$ref: '#/components/responses/Forbidden'
/shipping/countries:
post:
operationId: getShippingCountries
tags:
- Shipping
summary: Shipping countries
description: List supported delivery destination countries.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyRequest'
responses:
'200':
description: Supported countries.
'403':
$ref: '#/components/responses/Forbidden'
/shipping/states:
post:
operationId: getShippingStates
tags:
- Shipping
summary: Shipping states
description: Get the regions or states available for a specific country.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShippingStatesRequest'
responses:
'200':
description: States for the given country.
'403':
$ref: '#/components/responses/Forbidden'
components:
securitySchemes:
apikeyBody:
type: apiKey
in: header
name: apikey
description: >-
CloudCore API key from the Cloudprinter.com dashboard. The API key is
supplied in the JSON request body as the "apikey" field on every call;
this scheme is declared as a header for tooling compatibility.
responses:
BadRequest:
description: Invalid request parameters.
Forbidden:
description: Missing or invalid credentials.
Conflict:
description: Conflict - the order is in a state that does not allow the operation.
NotFound:
description: Resource not found.
schemas:
ApiKeyRequest:
type: object
required:
- apikey
properties:
apikey:
type: string
description: CloudCore API key.
OrderReferenceRequest:
type: object
required:
- apikey
- reference
properties:
apikey:
type: string
reference:
type: string
description: The unique order reference.
ShippingStatesRequest:
type: object
required:
- apikey
- country
properties:
apikey:
type: string
country:
type: string
description: ISO 3166-1 alpha-2 country code.
ProductInfoRequest:
type: object
required:
- apikey
- product
properties:
apikey:
type: string
product:
type: string
description: The product reference.
QuoteRequest:
type: object
required:
- apikey
- country
- items
properties:
apikey:
type: string
country:
type: string
description: ISO 3166-1 alpha-2 destination country code.
state:
type: string
description: State or region code, required for some countries (e.g. US).
currency:
type: string
description: ISO 4217 currency code for returned prices.
items:
type: array
items:
$ref: '#/components/schemas/QuoteItem'
QuoteItem:
type: object
required:
- reference
- product
- count
properties:
reference:
type: string
description: Caller-supplied item reference.
product:
type: string
description: Product reference.
count:
type: integer
description: Number of copies.
options:
type: array
items:
$ref: '#/components/schemas/Option'
QuoteResponse:
type: object
properties:
quotes:
type: array
items:
type: object
properties:
hash:
type: string
description: Unique quote hash, valid for 48 hours.
price:
type: string
currency:
type: string
shipping_options:
type: array
items:
type: object
properties:
level:
type: string
price:
type: string
currency:
type: string
Option:
type: object
required:
- type
properties:
type:
type: string
description: Option type reference (e.g. type_cover_paper, type_book_binding).
count:
type: integer
File:
type: object
required:
- type
- url
properties:
type:
type: string
description: File type - product, cover, or book.
enum:
- product
- cover
- book
url:
type: string
format: uri
description: Publicly reachable URL of the print-ready file.
md5sum:
type: string
description: MD5 checksum used to validate the downloaded file.
Address:
type: object
required:
- type
- firstname
- lastname
- street1
- zip
- city
- country
properties:
type:
type: string
description: Address type - delivery or invoice.
firstname:
type: string
lastname:
type: string
company:
type: string
street1:
type: string
street2:
type: string
zip:
type: string
city:
type: string
state:
type: string
country:
type: string
description: ISO 3166-1 alpha-2 country code.
email:
type: string
phone:
type: string
OrderItem:
type: object
required:
- reference
- product
- count
properties:
reference:
type: string
product:
type: string
count:
type: integer
shipping_level:
type: string
description: Shipping level reference (e.g. cp_saver). Use this or a quote hash.
quote:
type: string
description: Quote hash from a prior /orders/quote call.
options:
type: array
items:
$ref: '#/components/schemas/Option'
files:
type: array
items:
$ref: '#/components/schemas/File'
AddOrderRequest:
type: object
required:
- apikey
- reference
- email
- addresses
- items
properties:
apikey:
type: string
reference:
type: string
description: Unique order reference supplied by the caller.
email:
type: string
addresses:
type: array
items:
$ref: '#/components/schemas/Address'
items:
type: array
items:
$ref: '#/components/schemas/OrderItem'
AddOrderResponse:
type: object
properties:
reference:
type: string
order:
type: string
description: Cloudprinter order identifier.
Order:
type: object
properties:
reference:
type: string
order:
type: string
state:
type: string
email:
type: string
addresses:
type: array
items:
$ref: '#/components/schemas/Address'
items:
type: array
items:
$ref: '#/components/schemas/OrderItem'
OrderListResponse:
type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/Order'
OrderLogResponse:
type: object
properties:
log:
type: array
items:
type: object
properties:
date:
type: string
format: date-time
state:
type: string
message:
type: string
ProductListResponse:
type: object
properties:
products:
type: array
items:
type: object
properties:
reference:
type: string
name:
type: string
category:
type: string
ProductInfo:
type: object
properties:
reference:
type: string
name:
type: string
options:
type: array
items:
type: object
properties:
type:
type: string
name:
type: string
price_units:
type: array
items:
type: string
description: Price unit type (e.g. price_unit_pr_order, price_unit_pr_page).