API Docs

Changelog

[1.17.0] 10-19-2026

Added

AI upscaling

  • Orders: set ai_upscale: true on a print area in line_items[].print_areas when creating an order, and Dreamship upscales the artwork with AI whenever the resize you chose would otherwise stretch it beyond its own pixels. Artwork that is already large enough is used as is.
  • Products: set ai_upscale: true on a print area in print_areas when creating or updating a product. Product responses now include print_areas[].ai_upscale. The first order that needs the upscale pays for it, and later orders of the product reuse it at no charge until the artwork or its placement changes. Not available on personalized products, since each of their orders brings its own artwork. Leaving it out of an update keeps the print area's current setting.
  • A flat fee is added for each print area we upscale, not multiplied by line item quantity. No fee is charged when no upscale was needed.
  • The check uses the uploaded file's pixel dimensions, so artwork enlarged in another tool before upload counts as large enough and is not upscaled.
  • Orders now include ai_upscale_cost, the total upscale fees on the order. Each line item print area includes ai_upscale (upscaling was requested) and ai_upscale_charged (this print area's fee is on this order; false when no upscale was needed or an earlier order of the same product already paid for it).
  • Both are settled once the artwork has been downloaded and measured, before the order is charged, so the response to creating an order shows ai_upscale_cost: "0.00" and ai_upscale_charged: false.
  • Submitting a test order that includes AI upscaling, set on the order or on the product, returns a 400 on line_items.

Gift boxes

  • New line_items[].gift_box_item_variant when creating an order: the ID of a gift box item variant. It adds one gift box per unit of that line item, on top of any gift boxes sent as their own line items. The line item's item must have gift_box_offered: true and the variant must belong to an item with is_gift_box: true, or the order is refused with a 400 on gift_box_item_variant.
  • Blank items (blank_item: true), such as gift boxes, can now be ordered by item_variant with no print_areas, and products for them can be created with no print areas.

Webhooks

  • business-billing-status-updated: sent when your balance plus any credit line drops below your low balance threshold, and again once it is back 10% above it. The threshold starts at $1,000; once you subscribe, change it on the Billing page. The payload is your business: id, balance, effective_balance, low_balance_threshold, max_advance and billing_status (ok or low).
  • payment-method-status-updated: sent when a saved payment method stops being usable or becomes usable again, for example a card that keeps getting declined, a Payoneer account that needs reconnecting, or a method left unused for 30 days. Adding or removing a method does not send it. The payload is the payment method: id, type, display, status and is_auto_billing_payment_method.

New values

  • Order rejected_status:
    • needs_review: an AI personalized order's generated artwork is waiting to be reviewed before it is submitted.
    • fulfillment_request_withdrawn: the fulfillment request was withdrawn on Shopify. Request fulfillment from Dreamship there again, then resubmit, or cancel the order.
    • sample_discount_unavailable: the sample discount no longer applies. Submitting again places the order at full price.
  • Discount type: loyalty_reward_token, sample_order.
  • Tracking carrier: la_poste.
  • Ship zone group: cyprus, lithuania, romania.

Changed

Validation errors

  • Each entry in errors[].details now has the field it is about as its key, instead of repeating the message. Problems inside nested objects come back as one string message each, keyed by a path such as line_items[1].quantity, instead of an object message with a null key. The top-level error.key is now always invalid. Errors from Dreamship's own order checks, such as Invalid quantity - Line Item (0), are unchanged.

Before:

{"error": {"key": "This field is required.", "status_code": 400, "message": "Invalid data.",
  "errors": [{"field": "address", "details": [{"message": "This field is required.", "key": "This field is required."}]}]}}

After:

{"error": {"key": "invalid", "status_code": 400, "message": "Invalid data.",
  "errors": [{"field": "address", "details": [{"message": "This field is required.", "key": "address"}]}]}}

Orders to Mexico

  • vat_number is required for orders shipping to Mexico: the recipient's RFC or CURP. Without it, submitting returns a 400 on vat_number. Orders with more than 10 line items are submitted in the background and get rejected_status: vat_error instead. Leave vat_currency out; vat_unit_value is not used.

Items

  • size_chart_link now links to the item's size chart page on dreamship.com when it has one, and is an empty string instead of null when there is no size chart.

Products

  • Products that wait more than a day for their artwork to validate now fail with error_reason: "stuck_processing", instead of waiting indefinitely.

Tickets

  • requested_action: "reprint" is refused for orders with the prepaid shipping method (400 on requested_action).

Fixed

  • In order responses, a line item with more than one print area showed the first print area's url and url_error on every print area. Each print area now shows its own.
  • Filtering orders by trackings_created_at returned an order twice when two of its trackings fell in the range.

[1.16.0] 07-30-2026

All changes below are additive and backwards compatible. No request payloads changed, and nothing was removed.

Added

  • print_areas[].sizes on items: each print area now lists the sizes it applies to, so a single item can have a "Front (XS-L)" area and a separate "Front (XL-3XL)" area, or a mug with 11oz and 15oz wrap and bottom areas. Use it to route each design to the print area that covers the size you are printing.
  • A print area that applies to every size returns the item's full size list, so sizes is never empty and you can always read one uniform list.
  • print_areas[].name: human readable label for the print area, for example "Front (XS-L)". Use it anywhere a person sees the print area. Keep using key as the stable identifier for uploads and orders.
  • options on items: an item may carry one option axis beyond Color and Size, for example Finish (Matte / Glossy) or Pack (1-Pack / 3-Pack / 5-Pack). Each option returns id, name, affects_appearance, position, and its values.
  • option_values on item variants: the option value a variant carries, as { "option": "Finish", "value": "Glossy" }. A variant is now Color x Size x option value, so account for the third axis if you enumerate variants.
  • option_value on mockup templates: the id of the option value a mockup is for, or null when the mockup applies to every option value. If you match mockups to variants, match on color, size, and now option_value when it is set.
  • Print areas nested inside mockup templates include name and sizes as well. Note that on the mockup-template-groups endpoint size is a nested { id, name, availability } object rather than a bare id.

Deprecated

  • print_areas[].size on both the item and mockup-template-groups endpoints. It still returns its previous value (the first entry from sizes), so nothing breaks. Migrate reads to sizes when convenient.

Unchanged

  • Artwork uploads and order submission still reference print areas by key. Request formats are identical.
  • Items without options return options: [] and variants return option_values: [], so existing items behave exactly as before.

What you need to do

  • Nothing for your current items.
  • Before selling new-style items (per-size print areas or an extra option): read sizes to route uploads, handle options / option_values if you enumerate variants, and match option_value if you use mockup templates.

[1.15.0] 02-12-2025

  • Added the ability to create products with Items instead of Product Templates.
  • Added mockup template group endpoints.

[1.14.0] 06-14-2024

  • Shipping labels can now be added to select line items when creating orders.

[1.13.0] 10-26-2023

  • Ability to create tickets through API
  • Order
    • Added line_item_ticket information onto order

[1.12.0] 10-20-2023

  • Order
    • Added rush_production field to rush the order for an additional charge
  • Item Variant
    • Added rush_production_first_cost and rush_production_additional_cost to help calculate the costs of rush producing an order.
  • Ship Zone Method Item Variant
    • Added holiday_shipping_surcharge_cost to show the added cost of shipping an item during holiday season.

[1.11.0] 8-1-2023

  • Dreamship Plus launch
  • Breaking
    • GET /items was incorrectly using the wrong pagination wrapper class. All results should now match the rest of the API.
      {“paging”: {...}, “data”: [...]}
    • Print Areas
      • print_areas[i].cost is deprecated. Use additional_cost on Print Area if attempting to calculate print costs.
    • Ship Zones
      • All cost fields on the ship_zones[i] and ship_zones[i].ship_zones_methods[i] are deprecated on the /items/{id} endpoints. Use the v1/items/{item_id}/ship-zones endpoints to pull shipping cost data now. See the sample endpoint data above for integrating the endpoint.
      • The items/{item_id}/us-shipping-methods and items/{item_id}/international-shipping-methods endpoints are deprecated and will no longer work after Aug 6, 2023. Use the ship-zone endpoints above.
      • Ship zones have been standardized across all Items into the following “group” values:
        • us
        • us_non_contiguous
        • canada
        • australia
        • uk_and_europe
        • rest_of_world
      • Ship zone methods values are the same as before:
        • economy
        • ground
        • express
        • two_day
      • If a ship zone does not exist on an item, it is not possible to ship to those countries.
  • Item Variants
    • The cost field on the Item Variant objects are deprecated. Use the basic_cost, plus_cost, and enterprise_cost to get the product/print costs for an item variant depending on your business subscription plan. Note, pro_cost will only show up if you have a pro plan with Dreamship.

[1.10.0] 1-1-2023

  • Various fixes

[1.9.0] 11-22-2022

  • Removed shopify_shops from order read/write.
  • Removed channel_shops from order read. Use shop_products instead.

[1.8.0] 12-3-2021

  • Added X-Dreamship-Signature to webhook headers. A signature segement is a sha256 hash of an api key and the data being sent. If you have multiple api keys, X-Dreamship-Signature will be multiple segments seperated by commas.

[1.7.0] 11-16-2021

  • Added vat_number and vat_currency fields to Order, and vat_unit_value to LineItem on the Order create endpoint.

[1.6.0] 9-20-2021

  • The endpoints us-shipping and international-shipping are deprecated in favor of us-shipping-methods and international-shipping-methods. New data includes shipping methods.
  • ship_zone_methods added to ship_zones
  • Deprecated cost, delivery_days_min, and delivery_days_max on ship_zone. The ship_zone_methods now hold that information.
  • name, pattern, primary_hex, secondary_hex added to colors on product.

[1.5.0] 8-12-2021

US and International shipping tables are now available for each item. https://docs.dreamship.com/reference#shipping

[1.4.0] 6-11-2021

This release adds functionality for the new custom shops features along with a variety of smaller fixes and additions.

Shops

The Shop resource has been abstracted and rebuilt to support both Shopify shops and Custom shops. Custom shops allow a better way to categorize both products and orders created in the app and over the API.

Shop

  • Create Shop resource objects using Create Shop endpoint
  • Edit Shop resource objects using Update Shop endpoint. Can be used to change the name and key of object, as well as used to set the status to inactive or active.

Product

  • shops field added to Product Create endpoint. Include a list of shop keys to publish your product to Custom or Shopify shops.
  • shop_key filter added Get Products endpoint

Order

  • shop_key field added to Create Order endpoint. Include a shop key to associate your orders to a custom shop.
  • shop_key filter added to Get Orders endpoint

Note Products can be published to multiple shops. The order's shop relationship cannot be implicitly inferred from the product. If you want to associate an order with a custom shop you must explicitly pass the shop_key field when creating orders.

Other Additions

Item

  • production_days_min field added
  • production_days_max field added

Deprecated

Product

  • shopify_shops is deprecated. Use shops moving forward to set which shops to publish a product to.
  • channel_products is deprecated. Use shop_products to see which shops products have been published to.

[1.3.0] 3-23-2021

This minor version fixes small issues on Order subtotal cost fields .

Fixes

Order subtotal_cost was previously sending discounted_subtotal_cost.
We've changed subtotal_cost field to accurately show subtotal_cost and added the discounted_subtotal_cost field to the Order object.

[1.2.0] 3-18-2021

This minor version focuses on adding new fields related to payment changes which give users better insight into order costs.

Added

Added to Order object

  • subtotal_cost
  • paid_amount
  • refunded_amount
  • processing_cost

Added to Line Item object

  • product_cost
  • shipping_cost
  • print_cost
  • item_cost
  • discounted_item_cost
  • subtotal_cost
  • total_cost

Deprecated

Order costs

The costs field on the order object is deprecated and will be removed in the next major version release. Use the total_cost field instead.

[1.1.0] 2-2-2021

This minor version adds new endpoints for Dreamship catalog items, allowing users to browse catalog data, availability and pricing.

Added

  • New Item endpoint.
  • New Category endpoint. Includes additional category/item endpoint.