openapi: 3.0.3
info:
  title: Gooten API
  description: >-
    The Gooten API is a REST interface for the Gooten print-on-demand and global
    manufacturing / fulfillment platform. It is hosted at api.print.io (the
    platform Gooten was built on) and lets you browse the product catalog and
    per-region SKUs, retrieve print templates, create print-ready products from
    artwork, quote shipping and order prices, and submit and manage manufacturing
    orders. The API is organized around resource-oriented URLs and standard HTTP
    verbs (GET, POST, PUT, DELETE) and returns JSON. All requests must use HTTPS.


    Authentication is by two credentials passed as query parameters. Every
    request requires a `RecipeID` (a public identifier for your integration).
    Order-writing and billing operations additionally require a
    `PartnerBillingKey` (a private key that must never be exposed client-side and
    must be URL-encoded). Most catalog endpoints live under the source API base
    `/api/v/5/source/api`; print-ready product (PRP) management lives under the
    versioned base `/api/v2/recipes/{recipeId}`.


    This description was authored by API Evangelist from Gooten's public
    documentation. Field-level request/response shapes are modeled from the
    documented examples and are approximate; consult the Gooten docs for exact
    payloads.
  version: '5'
  contact:
    name: Gooten
    url: https://www.gooten.com/api-documentation/getting-started/
servers:
  - url: https://api.print.io
    description: Gooten API (hosted on the Print.io platform)
security:
  - recipeId: []
tags:
  - name: Products
    description: Catalog products, per-region SKUs, supported countries and currencies.
  - name: Shipping
    description: Shipping option lookup and order price estimates for a cart.
  - name: Orders
    description: Submit, retrieve, search, and update manufacturing orders.
  - name: Print Assets
    description: Product templates and print-ready product (PRP) management.
paths:
  /api/v/5/source/api/products:
    get:
      operationId: listProducts
      tags:
        - Products
      summary: List products
      description: >-
        Lists catalog products. In Gooten a "product" is a category (for
        example "Canvas Wraps") that has many SKUs / variants beneath it.
      parameters:
        - $ref: '#/components/parameters/RecipeID'
        - name: countryCode
          in: query
          required: false
          description: Two-character ISO 3166-1 alpha-2 country code for the shipping destination.
          schema:
            type: string
            example: US
        - name: all
          in: query
          required: false
          description: When true, returns the full catalog rather than only enabled products.
          schema:
            type: boolean
      responses:
        '200':
          description: A list of products.
          content:
            application/json:
              schema:
                type: object
                properties:
                  HadError:
                    type: boolean
                  Products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v/5/source/api/productvariants:
    get:
      operationId: listProductVariants
      tags:
        - Products
      summary: List product variants (SKUs)
      description: >-
        Lists the available variants (SKUs) and pricing for a product. SKUs can
        differ by region - for example US canvas wraps use inch formats and
        European ones use centimeter formats - so a country code is required.
      parameters:
        - $ref: '#/components/parameters/RecipeID'
        - name: productId
          in: query
          required: true
          description: The product identifier obtained from the products endpoint.
          schema:
            type: string
        - name: countryCode
          in: query
          required: true
          description: Two-character ISO 3166-1 alpha-2 country code for the shipping destination.
          schema:
            type: string
            example: US
        - name: currencyCode
          in: query
          required: false
          description: ISO currency code for returned pricing. Defaults to USD.
          schema:
            type: string
            default: USD
        - name: compression
          in: query
          required: false
          description: When true, reduces the response payload size.
          schema:
            type: boolean
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
        - name: page
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A list of product variants (SKUs) with pricing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  HadError:
                    type: boolean
                  ProductVariants:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProductVariant'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v/5/source/api/countries:
    get:
      operationId: listCountries
      tags:
        - Products
      summary: List supported shipping countries
      description: >-
        Returns the countries Gooten can ship to, each with a name, ISO code,
        support flag, measurement system, flag image URL, and default currency.
      parameters:
        - $ref: '#/components/parameters/RecipeID'
      responses:
        '200':
          description: A list of supported shipping countries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  HadError:
                    type: boolean
                  Countries:
                    type: array
                    items:
                      $ref: '#/components/schemas/Country'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v/5/source/api/currencies:
    get:
      operationId: listCurrencies
      tags:
        - Products
      summary: List supported currencies
      description: Returns the currencies supported for pricing and order submission.
      parameters:
        - $ref: '#/components/parameters/RecipeID'
      responses:
        '200':
          description: A list of supported currencies.
          content:
            application/json:
              schema:
                type: object
                properties:
                  HadError:
                    type: boolean
                  Currencies:
                    type: array
                    items:
                      type: string
                      example: USD
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v/5/source/api/shippingprices:
    post:
      operationId: getShippingOptions
      tags:
        - Shipping
      summary: Get shipping options for a cart
      description: >-
        Returns the available shipping options and their costs for a set of
        line items shipping to a given destination.
      parameters:
        - $ref: '#/components/parameters/RecipeID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingPricesRequest'
      responses:
        '200':
          description: Available shipping options.
          content:
            application/json:
              schema:
                type: object
                properties:
                  HadError:
                    type: boolean
                  ShippingOptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/ShippingOption'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v/5/source/api/price:
    post:
      operationId: getPriceEstimate
      tags:
        - Shipping
      summary: Get an order price estimate
      description: >-
        Estimates the total cost of an order - product cost, shipping,
        surcharges, taxes, and fees - for a cart in a chosen currency, before the
        order is submitted.
      parameters:
        - $ref: '#/components/parameters/RecipeID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceEstimateRequest'
      responses:
        '200':
          description: An order price estimate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v/5/source/api/orders:
    get:
      operationId: getOrders
      tags:
        - Orders
      summary: Get an order by ID or search orders
      description: >-
        Retrieves a single order by its Safe Order ID (pass `Id`), or searches
        orders by criteria such as last name, email, postal code, and date range
        when `Id` is omitted. Search requires the PartnerBillingKey.
      parameters:
        - $ref: '#/components/parameters/RecipeID'
        - name: Id
          in: query
          required: false
          description: The Safe Order ID of a specific order to retrieve.
          schema:
            type: string
        - $ref: '#/components/parameters/PartnerBillingKey'
        - name: lastName
          in: query
          required: false
          schema:
            type: string
        - name: email
          in: query
          required: false
          schema:
            type: string
        - name: postalCode
          in: query
          required: false
          schema:
            type: string
        - name: startDate
          in: query
          required: false
          description: Search lower bound, format yyyy-mm-dd.
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          required: false
          description: Search upper bound, format yyyy-mm-dd.
          schema:
            type: string
            format: date
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: An order or a page of matching orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: submitOrder
      tags:
        - Orders
      summary: Submit an order
      description: >-
        Submits a new manufacturing order. Requires ship-to and billing
        addresses, one or more line items (SKU, quantity, artwork images, and a
        ship type or carrier method), and a Payment object carrying the
        PartnerBillingKey. Returns the new order Id.
      parameters:
        - $ref: '#/components/parameters/RecipeID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '200':
          description: The created order identifier.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Id:
                    type: string
                  HadError:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v/5/source/api/orderbilling:
    get:
      operationId: getOrderBilling
      tags:
        - Orders
      summary: Get billing information for an order
      description: >-
        Returns the full billing breakdown for an order - product cost, per-item
        shipping cost, subtotal, shipping, surcharges, taxes, fees, discounts,
        and total. Requires the PartnerBillingKey.
      parameters:
        - name: orderid
          in: query
          required: true
          description: The order ID to retrieve billing for.
          schema:
            type: string
        - $ref: '#/components/parameters/RecipeID'
        - $ref: '#/components/parameters/PartnerBillingKey'
        - name: currency
          in: query
          required: false
          description: Currency for the returned amounts.
          schema:
            type: string
      responses:
        '200':
          description: The billing breakdown for the order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v/5/source/api/shippingAddress:
    put:
      operationId: updateShippingAddress
      tags:
        - Orders
      summary: Update the shipping address for an order
      description: >-
        Updates the ship-to address on an existing order, provided the order is
        still in an editable status. Requires the PartnerBillingKey.
      parameters:
        - name: orderId
          in: query
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RecipeID'
        - $ref: '#/components/parameters/PartnerBillingKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Address'
      responses:
        '200':
          description: Update result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v/5/source/api/shippingMethod:
    put:
      operationId: updateShippingMethod
      tags:
        - Orders
      summary: Update the shipping method for order items
      description: >-
        Changes the shipping method for one or more items in an order. Shipping
        method changes automatically adjust order pricing. Requires the
        PartnerBillingKey.
      parameters:
        - name: orderId
          in: query
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RecipeID'
        - $ref: '#/components/parameters/PartnerBillingKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - OrderItemIds
                - NewShippingMethod
              properties:
                OrderItemIds:
                  type: array
                  items:
                    type: string
                NewShippingMethod:
                  type: string
                  enum:
                    - standard
                    - expedited
                    - overnight
      responses:
        '200':
          description: Update result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v/5/source/api/producttemplates:
    get:
      operationId: listProductTemplates
      tags:
        - Print Assets
      summary: List product templates for a SKU
      description: >-
        Returns the template data describing how to build print-ready art for a
        SKU - the number of image spaces, required sizes, and coordinates used to
        render and validate artwork.
      parameters:
        - $ref: '#/components/parameters/RecipeID'
        - name: sku
          in: query
          required: true
          description: The SKU to retrieve template data for.
          schema:
            type: string
      responses:
        '200':
          description: Template data for the SKU.
          content:
            application/json:
              schema:
                type: object
                properties:
                  HadError:
                    type: boolean
                  Template:
                    $ref: '#/components/schemas/ProductTemplate'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/recipes/{recipeId}/printreadyproducts:
    parameters:
      - $ref: '#/components/parameters/RecipeIdPath'
    get:
      operationId: listPrintReadyProducts
      tags:
        - Print Assets
      summary: List print-ready products
      description: Lists the print-ready products (PRPs) configured for your recipe.
      parameters:
        - name: page
          in: query
          required: false
          description: Page number; defaults to 1.
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: A page of print-ready products.
          content:
            application/json:
              schema:
                type: object
                properties:
                  PrintReadyProducts:
                    type: array
                    items:
                      $ref: '#/components/schemas/PrintReadyProduct'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPrintReadyProduct
      tags:
        - Print Assets
      summary: Create a print-ready product
      description: >-
        Creates a print-ready product that binds a Gooten SKU to your artwork
        design, positioned by template space (SpaceDesc and/or SpaceId).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintReadyProductInput'
      responses:
        '200':
          description: The created print-ready product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintReadyProduct'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    put:
      operationId: updatePrintReadyProduct
      tags:
        - Print Assets
      summary: Update a print-ready product
      description: Updates an existing print-ready product with the same payload shape as creation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintReadyProductInput'
      responses:
        '200':
          description: The updated print-ready product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintReadyProduct'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/recipes/{recipeId}/printreadyproducts/{productId}:
    parameters:
      - $ref: '#/components/parameters/RecipeIdPath'
      - name: productId
        in: path
        required: true
        description: The print-ready product identifier.
        schema:
          type: string
    delete:
      operationId: deletePrintReadyProduct
      tags:
        - Print Assets
      summary: Delete a print-ready product
      description: Deletes a print-ready product by its identifier.
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v2/recipes/{recipeId}/printreadyproducts/variants:
    parameters:
      - $ref: '#/components/parameters/RecipeIdPath'
    get:
      operationId: listPrintReadyProductVariants
      tags:
        - Print Assets
      summary: List print-ready product variants
      description: Lists the variants of your print-ready products, optionally filtered by product name.
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: productName
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A page of print-ready product variants.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Variants:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    recipeId:
      type: apiKey
      in: query
      name: RecipeID
      description: >-
        Public RecipeID from the Gooten Admin, required on every request.
        Order-writing and billing endpoints additionally require a private
        PartnerBillingKey query parameter (URL-encoded).
  parameters:
    RecipeID:
      name: RecipeID
      in: query
      required: true
      description: Your public RecipeID from the Gooten Admin.
      schema:
        type: string
    PartnerBillingKey:
      name: partnerBillingKey
      in: query
      required: true
      description: Your private Partner Billing Key, URL-encoded. Never expose this client-side.
      schema:
        type: string
    RecipeIdPath:
      name: recipeId
      in: path
      required: true
      description: Your RecipeID from the Gooten Admin.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid RecipeID / PartnerBillingKey.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: Gooten error envelope. Responses carry a HadError flag and error details.
      properties:
        HadError:
          type: boolean
        Errors:
          type: array
          items:
            type: object
            properties:
              Message:
                type: string
              PropertyName:
                type: string
              ErrorReference:
                type: string
    GenericResult:
      type: object
      properties:
        HadError:
          type: boolean
        Id:
          type: string
    Product:
      type: object
      properties:
        Id:
          type: string
        Name:
          type: string
        CategoryName:
          type: string
    ProductVariant:
      type: object
      properties:
        Sku:
          type: string
        ProductId:
          type: string
        Price:
          type: object
          properties:
            Price:
              type: number
            CurrencyCode:
              type: string
    Country:
      type: object
      properties:
        Name:
          type: string
        Code:
          type: string
        IsSupported:
          type: boolean
        MeasurementCode:
          type: string
        FlagUrl:
          type: string
        DefaultCurrency:
          type: string
    ShippingPricesRequest:
      type: object
      required:
        - ShipToPostalCode
        - ShipToCountry
        - CurrencyCode
        - Items
      properties:
        ShipToPostalCode:
          type: string
        ShipToCountry:
          type: string
        ShipToState:
          type: string
        CurrencyCode:
          type: string
        Items:
          type: array
          items:
            type: object
            required:
              - SKU
              - Quantity
            properties:
              SKU:
                type: string
              Quantity:
                type: integer
    ShippingOption:
      type: object
      properties:
        Method:
          type: string
        Price:
          type: number
        CurrencyCode:
          type: string
    PriceEstimateRequest:
      type: object
      required:
        - Items
        - Payment
      properties:
        ShipToAddress:
          $ref: '#/components/schemas/Address'
        Items:
          type: array
          items:
            type: object
            required:
              - SKU
              - Quantity
            properties:
              Quantity:
                type: integer
              SKU:
                type: string
              ShipType:
                type: string
        Payment:
          type: object
          properties:
            CurrencyCode:
              type: string
            PartnerBillingKey:
              type: string
    Address:
      type: object
      properties:
        FirstName:
          type: string
        LastName:
          type: string
        Line1:
          type: string
        Line2:
          type: string
        City:
          type: string
        State:
          type: string
        CountryCode:
          type: string
        PostalCode:
          type: string
        Phone:
          type: string
        Email:
          type: string
        IsBusinessAddress:
          type: boolean
    OrderItem:
      type: object
      required:
        - Quantity
        - SKU
      properties:
        Quantity:
          type: integer
        SKU:
          type: string
        ShipType:
          type: string
          description: Ship type, or provide ShipCarrierMethodId instead.
        ShipCarrierMethodId:
          type: integer
        Images:
          type: array
          items:
            type: object
            properties:
              Url:
                type: string
              SpaceId:
                type: string
              Index:
                type: integer
              ThumbnailUrl:
                type: string
        SourceId:
          type: string
        Meta:
          type: object
          additionalProperties: true
    OrderInput:
      type: object
      required:
        - ShipToAddress
        - BillingAddress
        - Items
        - Payment
      properties:
        ShipToAddress:
          $ref: '#/components/schemas/Address'
        BillingAddress:
          $ref: '#/components/schemas/Address'
        Items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        Payment:
          type: object
          required:
            - PartnerBillingKey
          properties:
            PartnerBillingKey:
              type: string
            CurrencyCode:
              type: string
        SourceId:
          type: string
        IsPartnerSourceIdUnique:
          type: boolean
        IsInTestMode:
          type: boolean
        Meta:
          type: object
          additionalProperties: true
    Order:
      type: object
      properties:
        Id:
          type: string
        Status:
          type: string
        ShipToAddress:
          $ref: '#/components/schemas/Address'
        BillingAddress:
          $ref: '#/components/schemas/Address'
        Items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        BillingSummary:
          $ref: '#/components/schemas/BillingSummary'
        HadError:
          type: boolean
    BillingSummary:
      type: object
      properties:
        ProductCost:
          type: number
        ShippingCost:
          type: number
        SubTotal:
          type: number
        Surcharges:
          type: number
        Taxes:
          type: number
        Fees:
          type: number
        Discounts:
          type: number
        Total:
          type: number
        CurrencyCode:
          type: string
    ProductTemplate:
      type: object
      properties:
        Sku:
          type: string
        Spaces:
          type: array
          items:
            type: object
            properties:
              Id:
                type: string
              Description:
                type: string
              Width:
                type: number
              Height:
                type: number
              FinalX:
                type: number
              FinalY:
                type: number
    PrintReadyProductInput:
      type: object
      required:
        - Sku
      properties:
        Sku:
          type: string
        Name:
          type: string
        Images:
          type: array
          items:
            type: object
            properties:
              Url:
                type: string
              SpaceId:
                type: string
              SpaceDesc:
                type: string
    PrintReadyProduct:
      allOf:
        - $ref: '#/components/schemas/PrintReadyProductInput'
        - type: object
          properties:
            Id:
              type: string