Orders

Manage orders across your shops. You can create orders directly or using GTINs (see Finding GTINs).

Get Orders

Retrieve orders with optional filters.

query {
  getOrders(shopId: "shop_123", shipped: false, limit: 10) {
    id
    orderNumber
    shopId
    shipped
    cancelled
    grandTotal
    shippingCost
    createdAt {
      _seconds
      _nanoseconds
    }
    shippingAddress {
      name
      address1
      city
      country
    }
  }
}

Filter Parameters

Parameter	Type	Description
shopId	ID	Filter by shop
shipped	Boolean	Filter by shipped status
cancelled	Boolean	Filter by cancelled status
createdAfter	TimestampInput	Orders created after this time
updatedAfter	TimestampInput	Orders updated after this time
limit	Int	Max number of results

Get a Single Order

getOrder now returns the full orderItems collection (previously the array came back empty). You can also request per-item and per-order cost breakdowns and ShipStation shipping options.

query {
  getOrder(id: "order_123") {
    id
    orderNumber
    shipped
    cancelled
    grandTotal
    shippingOptions {
      carrierCode
      serviceCode
      packageCode
    }
    cost {
      printingCost
      fulfillmentCost
      shippingCost
      discount
      totalCost
      customerPaid
      profit
      estimated
      currency
    }
    orderItems {
      id
      name
      price
      quantity
      images {
        url
        placement
        type
      }
      cost {
        printingCost
        fulfillmentCost
        totalCost
        currency
      }
    }
  }
}

Per-item and per-order cost

OrderItem.cost and Order.cost are computed on-demand only when selected — they trigger extra Firestore reads, so request them only when needed.

Field	Description
printingCost	Decoration / print cost (sum of per-placement printing prices × quantity, plus digitization fees for embroidery)
fulfillmentCost	Blank product / PO unit cost × quantity, including supplier upcharge
shippingCost	Resolved from blank product shippingPriceId and the destination country (Order-level only). null when not calculable.
discount	Tier discount applied to printing cost (Order-level only)
totalCost	printingCost + fulfillmentCost + shippingCost − discount
customerPaid	Order.grandTotal (Order-level only)
profit	customerPaid − totalCost (Order-level only)
estimated	true until the order has been invoiced (Order-level only)
currency	Order currency, defaults to USD

Order status & tracking

Order exposes a derived lifecycle status, fine-grained tags, and inline shipments so you can poll fulfillment without inspecting individual flags.

query {
  getOrder(id: "order_123") {
    status
    statusTags
    shipped
    cancelled
    shipments {
      trackingCode
      trackingUrl
      carrierName
      shippedAt { _seconds _nanoseconds }
    }
  }
}

Field	Description
status	Coarse, normalized status derived server-side: "production" | "unsynced" | "shipped" | "cancelled". Mirrors Riverr's internal search-index normalization. Precedence (last match wins): cancelled > shipped > unsynced (not fully mapped) > production. Eventually consistent — a brand-new order reads "production" until the mapping pipeline runs.
statusTags	Finer pipeline tags (e.g. "pre-production", "in-production", "routed", "partially-shipped", "shipped", "draft"). Typed as a list for forward-compatibility; internal-only tags are filtered out. Empty until the pipeline has run. Treat as "current state", not history.
shipments	All shipments for the order (every parcel). See Tracking & Fulfillment.

Create an Order

createOrder and createOrderFromGtin now both return the full orderItems in the mutation response (previously they came back as an empty array). You can optionally pass shippingOptions with ShipStation-aware fields (carrierCode, serviceCode, packageCode); these are persisted on the order document and surfaced back as Order.shippingOptions.

mutation {
  createOrder(
    input: {
      orderNumber: "ORD-2001"
      shopId: "shop_123"
      shippingAddress: {
        name: "Jane Smith"
        address1: "456 Oak Ave"
        city: "Los Angeles"
        state: "CA"
        zip: "90001"
        country: "US"
      }
      shippingOptions: {
        carrierCode: "stamps_com"
        serviceCode: "usps_priority"
        packageCode: "package"
      }
      orderItems: [
        {
          productId: "prod_123"
          variantId: "var_456"
          quantity: 2
          price: 29.99
          name: "Custom T-Shirt"
        }
      ]
    }
  ) {
    id
    orderNumber
    grandTotal
    shipped
    cancelled
    shippingOptions {
      carrierCode
      serviceCode
      packageCode
    }
    orderItems {
      id
      name
      price
      quantity
    }
  }
}

Update an Order

Update the status of an existing order.

mutation {
  updateOrder(id: "order_123", input: { shipped: true }) {
    id
    orderNumber
    shipped
    cancelled
  }
}

Create an Order from GTIN

See Finding GTINs for the full guide on creating orders using GTINs.

orderItems[].images.type is an enum — valid values are printing (the artwork to be printed) and mockup (the visual proof). placement is a string ID; look up the valid IDs for your enterprise via the getPlacements query.

mutation {
  createOrderFromGtin(
    input: {
      orderNumber: "ORD-3001"
      shopId: "shop_123"
      shippingAddress: {
        name: "John Doe"
        address1: "123 Main St"
        city: "New York"
        country: "US"
      }
      shippingOptions: {
        carrierCode: "stamps_com"
        serviceCode: "usps_priority"
        packageCode: "package"
      }
      orderItems: [
        {
          gtin: "00123456789012"
          quantity: 1
          price: 19.99
          images: [
            {
              url: "https://cdn.example.com/artwork.png"
              placement: "1"
              type: printing
            }
            {
              url: "https://cdn.example.com/mockup.png"
              placement: "1"
              type: mockup
            }
          ]
        }
      ]
    }
  ) {
    id
    orderNumber
    shipped
    shippingOptions {
      carrierCode
      serviceCode
      packageCode
    }
    orderItems {
      id
      name
      images {
        url
        placement
        type
      }
      cost {
        printingCost
        fulfillmentCost
        totalCost
      }
    }
    cost {
      printingCost
      fulfillmentCost
      shippingCost
      totalCost
    }
  }
}