Prodigi Orders API

openapi: 3.0.1
info:
  title: Prodigi Print API
  description: >-
    The Prodigi Print API (v4.0) is a RESTful, JSON-based API for global
    print-on-demand fulfillment. It lets merchants create and manage print
    orders, request real-time quotes for pricing and shipping, and query the
    product catalogue by SKU. Orders progress through Prodigi's fulfillment
    stages, with per-order callbacks pushing status and shipment updates to a
    merchant-supplied callback URL.
  termsOfService: https://www.prodigi.com/terms/
  contact:
    name: Prodigi Support
    email: hi@prodigi.com
    url: https://www.prodigi.com/print-api/docs/
  version: '4.0'
servers:
  - url: https://api.prodigi.com/v4.0
    description: Production
  - url: https://api.sandbox.prodigi.com/v4.0
    description: Sandbox
security:
  - ApiKeyAuth: []
tags:
  - name: Orders
    description: Create, retrieve, list, and act on print orders.
  - name: Quotes
    description: Request pricing and shipping breakdowns before ordering.
  - name: Products
    description: Query the product catalogue by SKU.
paths:
  /orders:
    post:
      operationId: createOrder
      tags:
        - Orders
      summary: Create a new print order.
      description: >-
        Submits a new order for fulfillment. Supply a recipient, one or more
        items with their SKUs and print assets, and a shipping method. An
        optional idempotencyKey makes the request safely retryable.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Order created (or returned via idempotency).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Invalid request.
        '401':
          description: Missing or invalid API key.
    get:
      operationId: listOrders
      tags:
        - Orders
      summary: List orders.
      description: Returns a paged list of orders for the given filtering options.
      parameters:
        - name: top
          in: query
          description: Maximum number of orders to return.
          schema:
            type: integer
        - name: skip
          in: query
          description: Number of orders to skip for paging.
          schema:
            type: integer
        - name: createdFrom
          in: query
          description: Return orders created on or after this UTC timestamp.
          schema:
            type: string
            format: date-time
        - name: createdTo
          in: query
          description: Return orders created on or before this UTC timestamp.
          schema:
            type: string
            format: date-time
        - name: status
          in: query
          description: Filter by order stage.
          schema:
            type: string
            enum: [InProgress, Complete, Cancelled]
        - name: merchantReference
          in: query
          description: Filter by the merchant's own reference.
          schema:
            type: string
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '401':
          description: Missing or invalid API key.
  /orders/{orderId}:
    get:
      operationId: getOrder
      tags:
        - Orders
      summary: Retrieve a specific order.
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: The requested order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Order not found.
  /orders/{orderId}/actions:
    get:
      operationId: getOrderActions
      tags:
        - Orders
      summary: Get available actions for an order.
      description: >-
        Returns which actions (cancel, updateShippingMethod, updateRecipient,
        updateMetadata) are currently available for the order given its
        fulfillment stage.
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Available actions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderActionsResponse'
  /orders/{orderId}/actions/cancel:
    post:
      operationId: cancelOrder
      tags:
        - Orders
      summary: Cancel an order.
      description: >-
        Requests cancellation of an order. Only available while the order has
        not progressed past the point of cancellation.
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Cancellation outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionOutcomeResponse'
  /orders/{orderId}/actions/updateShippingMethod:
    post:
      operationId: updateShippingMethod
      tags:
        - Orders
      summary: Update the shipping method of an order.
      parameters:
        - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shippingMethod
              properties:
                shippingMethod:
                  $ref: '#/components/schemas/ShippingMethod'
      responses:
        '200':
          description: Update outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionOutcomeResponse'
  /orders/{orderId}/actions/updateRecipient:
    post:
      operationId: updateRecipient
      tags:
        - Orders
      summary: Update the recipient of an order.
      parameters:
        - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Recipient'
      responses:
        '200':
          description: Update outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionOutcomeResponse'
  /orders/{orderId}/actions/updateMetadata:
    post:
      operationId: updateMetadata
      tags:
        - Orders
      summary: Update the metadata of an order.
      parameters:
        - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Update outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionOutcomeResponse'
  /quotes:
    post:
      operationId: createQuote
      tags:
        - Quotes
      summary: Get a quote.
      description: >-
        Returns an array of quotes, each providing a breakdown of pricing, lab
        allocation, and shipping arrangements for a given set of items, a
        destination country, and a shipping method.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '200':
          description: Quote results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '400':
          description: Invalid request.
  /products/{sku}:
    get:
      operationId: getProductDetails
      tags:
        - Products
      summary: Get product details for a SKU.
      description: >-
        Returns all available data for a SKU, including available destinations,
        attributes, and required assets and dimensions.
      parameters:
        - name: sku
          in: path
          required: true
          description: The product SKU.
          schema:
            type: string
      responses:
        '200':
          description: Product details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetailsResponse'
        '404':
          description: SKU not found.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Prodigi API key, sent in the X-API-Key header on every request.
  parameters:
    OrderId:
      name: orderId
      in: path
      required: true
      description: The Prodigi order id (prefixed with "ord_").
      schema:
        type: string
  schemas:
    ShippingMethod:
      type: string
      description: The shipping service level for the order.
      enum: [Budget, Standard, StandardPlus, Express, Overnight]
    Address:
      type: object
      required:
        - line1
        - townOrCity
        - postalOrZipCode
        - countryCode
      properties:
        line1:
          type: string
        line2:
          type: string
        townOrCity:
          type: string
        stateOrCounty:
          type: string
        postalOrZipCode:
          type: string
        countryCode:
          type: string
          description: Two-letter ISO country code.
    Recipient:
      type: object
      required:
        - name
        - address
      properties:
        name:
          type: string
        email:
          type: string
        phoneNumber:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    Asset:
      type: object
      required:
        - printArea
      properties:
        printArea:
          type: string
          description: The print area this asset applies to, typically "default".
        url:
          type: string
          description: Publicly reachable URL of the print-ready asset.
        md5Hash:
          type: string
        pageCount:
          type: integer
          description: Number of pages; required for photobook products.
    OrderItem:
      type: object
      required:
        - sku
        - copies
        - sizing
        - assets
      properties:
        merchantReference:
          type: string
        sku:
          type: string
        copies:
          type: integer
        sizing:
          type: string
          enum: [fillPrintArea, fitPrintArea, stretchToPrintArea]
        attributes:
          type: object
          additionalProperties: true
        recipientCost:
          $ref: '#/components/schemas/Cost'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
    Cost:
      type: object
      properties:
        amount:
          type: string
        currency:
          type: string
    CreateOrderRequest:
      type: object
      required:
        - shippingMethod
        - recipient
        - items
      properties:
        merchantReference:
          type: string
        shippingMethod:
          $ref: '#/components/schemas/ShippingMethod'
        idempotencyKey:
          type: string
        callbackUrl:
          type: string
          description: URL to which Prodigi posts order status callbacks.
        recipient:
          $ref: '#/components/schemas/Recipient'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        metadata:
          type: object
          additionalProperties: true
        branding:
          type: object
          additionalProperties: true
    OrderStatus:
      type: object
      properties:
        stage:
          type: string
          enum: [InProgress, Complete, Cancelled]
        issues:
          type: array
          items:
            type: object
            additionalProperties: true
        details:
          type: object
          additionalProperties: true
    Shipment:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        carrier:
          type: object
          additionalProperties: true
        dispatchDate:
          type: string
          format: date-time
        tracking:
          type: object
          additionalProperties: true
        fulfillmentLocation:
          type: object
          additionalProperties: true
        items:
          type: array
          items:
            type: object
            additionalProperties: true
    Order:
      type: object
      properties:
        id:
          type: string
          description: The Prodigi order id, prefixed with "ord_".
        created:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        callbackUrl:
          type: string
        merchantReference:
          type: string
        shippingMethod:
          $ref: '#/components/schemas/ShippingMethod'
        idempotencyKey:
          type: string
        status:
          $ref: '#/components/schemas/OrderStatus'
        charges:
          type: array
          items:
            type: object
            additionalProperties: true
        shipments:
          type: array
          items:
            $ref: '#/components/schemas/Shipment'
        recipient:
          $ref: '#/components/schemas/Recipient'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        metadata:
          type: object
          additionalProperties: true
        branding:
          type: object
          additionalProperties: true
        packingSlip:
          type: object
          additionalProperties: true
    OrderResponse:
      type: object
      properties:
        outcome:
          type: string
        order:
          $ref: '#/components/schemas/Order'
    OrderListResponse:
      type: object
      properties:
        outcome:
          type: string
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    OrderActionsResponse:
      type: object
      properties:
        outcome:
          type: string
        cancel:
          type: string
          description: Availability of the cancel action.
        changeRecipientDetails:
          type: string
        changeShippingMethod:
          type: string
        changeMetadata:
          type: string
    ActionOutcomeResponse:
      type: object
      properties:
        outcome:
          type: string
        order:
          $ref: '#/components/schemas/Order'
    QuoteItem:
      type: object
      required:
        - sku
        - copies
        - assets
      properties:
        sku:
          type: string
        copies:
          type: integer
        attributes:
          type: object
          additionalProperties: true
        assets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
    QuoteRequest:
      type: object
      required:
        - destinationCountryCode
        - items
      properties:
        shippingMethod:
          $ref: '#/components/schemas/ShippingMethod'
        destinationCountryCode:
          type: string
          description: Two-letter ISO country code for the shipping destination.
        currencyCode:
          type: string
          description: Three-letter ISO currency code for the returned costs.
        items:
          type: array
          items:
            $ref: '#/components/schemas/QuoteItem'
    Quote:
      type: object
      properties:
        shipmentMethod:
          type: string
        costSummary:
          type: object
          properties:
            items:
              $ref: '#/components/schemas/Cost'
            shipping:
              $ref: '#/components/schemas/Cost'
        shipments:
          type: array
          items:
            type: object
            additionalProperties: true
        items:
          type: array
          items:
            type: object
            additionalProperties: true
    QuoteResponse:
      type: object
      properties:
        outcome:
          type: string
        quotes:
          type: array
          items:
            $ref: '#/components/schemas/Quote'
    ProductDetailsResponse:
      type: object
      properties:
        outcome:
          type: string
        product:
          type: object
          properties:
            sku:
              type: string
            description:
              type: string
            productDimensions:
              type: object
              additionalProperties: true
            attributes:
              type: object
              additionalProperties: true
            printAreas:
              type: object
              additionalProperties: true
            variants:
              type: array
              items:
                type: object
                additionalProperties: true