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).