PX Connect API Manual

Introduction

Welcome

The PXConnect GraphQL API exposes a single, unified supplier catalogue — products, categories, and their selectable options — normalised across every connected supplier (4over, Midocean, and custom suppliers) into one consistent schema.

Every request is authenticated with a JWT bearer token and may be scoped to a supplier with the SupplierCode header. The API can be called two ways:

Transport Endpoint Notes
Native GraphQL POST /graphql Full Hot Chocolate endpoint. Send a standard GraphQL request body.
REST wrapper POST /api/suppliersdata/graphql JWT-guarded controller that forwards your query string to the GraphQL engine.

Start with Authentication to obtain a token, then jump to the Queries section for the full, typed field reference.

API Endpoints

# Staging: <your-api-url>
# REST wrapper (staging): <your-api-url>/api/suppliersdata/graphql

Headers

# JWT obtained from POST /api/auth/token
Authorization: Bearer <YOUR_JWT_TOKEN>
# Optional — scopes the query to a single supplier
SupplierCode: <supplier-code>

Version

1.0

Authentication

All endpoints are protected and require a JSON Web Token (JWT) in the Authorization header.

1. Obtain a token

POST /api/auth/token
Content-Type: application/json

{
  "email": "<your-email>",
  "password": "<your-password>"
}

Response

{
  "token": "<your-jwt-token>",
  "refreshToken": "<your-refresh-token>",
  "expiresAt": "<expiry-datetime>"
}

2. Send the token on every request

Both formats are accepted:

Authorization: Bearer <your-jwt-token>
Authorization: <your-jwt-token>

Supplier-scoped endpoints and queries additionally accept a supplier selector:

SupplierCode: <supplier-code>

3. Refresh an expired token

POST /api/auth/refresh
Content-Type: application/json

{ "refreshToken": "<your-refresh-token>" }

Token lifetime

Token Lifetime
Access token 60 minutes
Refresh token 30 days

REST GraphQL Wrapper

In addition to the native POST /graphql endpoint, a JWT-guarded REST wrapper is exposed for clients that prefer a plain controller route.

  • Method: POST
  • Route: /api/suppliersdata/graphql
  • Auth: Authorization header required. Optional SupplierCode header.

Request body

{
  "query": "query { options(language: \"en\") { brand { key value } } }",
  "variables": {},
  "operationName": null
}

Response

{
  "data": {
    "options": {
      "brand": [ { "key": "nike", "value": "Nike" } ]
    }
  }
}

Behaviour

Condition Result
Query executes successfully 200 OK with data
query is missing 400 Bad Request
Internal exception during execution 200 OK with an errors payload

Note: the current wrapper executes the query field only. variables and operationName are accepted in the body but are not forwarded to GraphQL execution. For variable-driven queries, call the native POST /graphql endpoint directly.

Supplier Configuration

Returns the suppliers assigned to a user and the dynamic attributes available to them.

  • Method: POST
  • Route: /api/suppliersdata/configuration
  • Auth: Authorization header required.

Request body

{ "userEmail": "<your-email>" }

Response

{
  "userEmail": "<your-email>",
  "assignedSuppliers": [
    { "supplierName": "Supplier One",  "supplierCode": "supplier_one",  "isCustomSupplier": false },
    { "supplierName": "Supplier Two",  "supplierCode": "supplier_two",  "isCustomSupplier": false },
    { "supplierName": "Custom Brand",  "supplierCode": "custom_brand",  "isCustomSupplier": true  }
  ],
  "dynamicAttributes": []
}

Behaviour

Condition Result
Configuration found 200 OK
userEmail missing 400 Bad Request
User not found 400 Bad Request
Unexpected failure 500 Internal Server Error

Webhook Callback

Receives product-sync completion / failure callbacks from a supplier worker. On receipt the server records the sync result, updates credential status, writes a history entry, sends a completion email, and notifies the Blazor dashboard.

  • Method: POST
  • Route: /api/suppliersdata/webhook/callback
  • Auth: Authorization and SupplierCode headers required.

Request body

{
  "status": "success",
  "processedProductCount": 125,
  "message": "Optional failure details"
}

Success response

{ "success": true, "message": "Callback received", "code": 200 }

Failure response

{ "success": false, "message": "SupplierCode is required", "code": 400 }

Side effects

  • On status: success, the user’s processed-product count is incremented.
  • A supplier history entry is written for both success and failure.
  • The API credential sync status is updated.
  • A completion email is sent when the user has an email address.
  • A dashboard refresh notification is sent to BlazorUI:BaseUrl when configured.

Errors

GraphQL responses always return HTTP 200 — application-level problems are reported in the errors array of the body, following the GraphQL spec.

{
  "errors": [
    {
      "message": "The current user is not authorized to access this resource.",
      "extensions": { "code": "AUTH_NOT_AUTHORIZED" }
    }
  ]
}

The REST endpoints (/api/auth/*, /api/suppliersdata/configuration, /api/suppliersdata/webhook/callback) use conventional HTTP status codes:

Code Meaning
200 OK Success
400 Bad Request Missing or invalid input
401 Unauthorized Missing / invalid / expired token
500 Internal Server Error Unexpected server failure

 

Operations

Operations

Categories

Description

Returns the category hierarchy for the active supplier, paginated. Each entry in categories is a root-to-leaf path (an array of Category levels). The supplier is determined from the SupplierCode HTTP header. Categories are scoped to the authenticated user’s saved category list.

Response

Returns a CategoryHierarchyResponse!

Arguments
Name Description
language – String! ISO language code for localised names and descriptions, e.g. en. Falls back to English then any available language.
page – Int! 1-based page number.
pageSize – Int! Number of records per page.
modificationDate – String Optional ISO date (YYYY-MM-DD). Only categories modified on or after this date are returned.
name – String Optional. Filter results by category name.

Example

Query
query Categories(
  $language: String!,
  $page: Int!,
  $pageSize: Int!,
  $modificationDate: String,
  $name: String
) {
  categories(
    language: $language,
    page: $page,
    pageSize: $pageSize,
    modificationDate: $modificationDate,
    name: $name
  ) {
    categories {
      level
      name
      description
      image
      cat_code
    }
    totalCount
  }
}
Variables
{
  "language": "en",
  "page": 1,
  "pageSize": 10,
  "modificationDate": "2026-01-01",
  "name": "abc123"
}
Response
{
  "data": {
    "categories": {
      "categories": [
        [
          {
            "level": 1,
            "name": "Drinkware",
            "description": "High-quality drinkware for daily use and gifting",
            "image": "https://example.com/images/drinkware.jpg",
            "cat_code": "drinkware_one"
          },
          {
            "level": 2,
            "name": "Bottle",
            "description": "Various types of bottles",
            "image": null,
            "cat_code": "bottle_two"
          },
          {
            "level": 3,
            "name": "Mugs",
            "description": "Ceramic and glass mugs",
            "image": null,
            "cat_code": "mugs_three"
          }
        ]
      ],
      "totalCount": 1
    }
  }
}

Options

Description

Returns static, catalogue-wide selectable options — brand, material, gender, colour, size. Values are aggregated across all products for the active supplier via a MongoDB aggregation pipeline. Each option is returned as a key/value pair.

Response

Returns a SupplierOptions!

Arguments
Name Description
language – String! ISO language code, e.g. en.

Example

Query
query Options($language: String!) {
  options(language: $language) {
    brand {
      key
      value
    }
    material {
      key
      value
    }
    gender {
      key
      value
    }
    color {
      key
      value
    }
    size {
      key
      value
    }
  }
}
Variables
{"language": "en"}
Response
{
  "data": {
    "options": {
      "brand": [{"key": "ecodrink", "value": "EcoDrink"}],
      "material": [{"key": "ceramic", "value": "Ceramic"}],
      "gender": [{"key": "unisex", "value": "Unisex"}],
      "color": [{"key": "black_blk-16", "value": "Black"}],
      "size": [{"key": "xl", "value": "XL"}]
    }
  }
}

DynmaicOptions

Description

Returns dynamic, print-related selectable options aggregated from product attribute data. Covers print configuration options such as stock type, lamination, foil colour, binding, folding, and many more. Values are normalised to lowercase underscore keys via regex during aggregation. Note: this field name contains a typo in the live schema — query it as dynmaicOptions (not dynamicOptions).

Response

Returns a DynamicOptions!

Arguments
Name Description
language – String! ISO language code, e.g. en.

Example

Query
query DynmaicOptions($language: String!) {
  dynmaicOptions(language: $language) {
    brand {
      key
      value
    }
    size {
      key
      value
    }
    shape {
      key
      value
    }
    stock {
      key
      value
    }
    colorspec {
      key
      value
    }
    coating {
      key
      value
    }
    spot_uv_sides {
      key
      value
    }
    scoring_options {
      key
      value
    }
    drill_hole {
      key
      value
    }
    bundling_service {
      key
      value
    }
    shrink_wrapping {
      key
      value
    }
    lamination {
      key
      value
    }
    foil_color {
      key
      value
    }
    second_raised_color {
      key
      value
    }
    raised_foil_side {
      key
      value
    }
    raised_spot_uv_height {
      key
      value
    }
    raised_spot_uv_side {
      key
      value
    }
    radius_of_corners {
      key
      value
    }
    business_card_box_size {
      key
      value
    }
    product_color {
      key
      value
    }
    product_material {
      key
      value
    }
    score_and_fold {
      key
      value
    }
    eddm_service_option {
      key
      value
    }
    rider_pins {
      key
      value
    }
    branding {
      key
      value
    }
    perforation {
      key
      value
    }
    cover_coating {
      key
      value
    }
    product_style {
      key
      value
    }
    cover_stock {
      key
      value
    }
    numbering {
      key
      value
    }
    page_count {
      key
      value
    }
    sheets_per_pad {
      key
      value
    }
    wraparound_cover {
      key
      value
    }
    hardware {
      key
      value
    }
    catalog_version {
      key
      value
    }
    product_orientation {
      key
      value
    }
    mailing_service {
      key
      value
    }
    number_of_tabs {
      key
      value
    }
    binding_type {
      key
      value
    }
    binding_edge {
      key
      value
    }
    folding_options {
      key
      value
    }
    button_backing_options {
      key
      value
    }
    button_shape_options {
      key
      value
    }
    shirt_size_multi_picker {
      key
      value
    }
    unwind_options {
      key
      value
    }
    fastener_options {
      key
      value
    }
    handle_options {
      key
      value
    }
    die_cut_options {
      key
      value
    }
    sleeve {
      key
      value
    }
    white_mask_front {
      key
      value
    }
    mount_position {
      key
      value
    }
    pockets {
      key
      value
    }
    business_card_slit {
      key
      value
    }
    flap_style {
      key
      value
    }
    blank_envelopes {
      key
      value
    }
    cd_slit {
      key
      value
    }
    edge_color {
      key
      value
    }
    qty_per_book {
      key
      value
    }
    blank_second_sheets {
      key
      value
    }
    slits {
      key
      value
    }
    variable_data {
      key
      value
    }
    opening_side {
      key
      value
    }
    window_options {
      key
      value
    }
    clear_case {
      key
      value
    }
    edge_join_options {
      key
      value
    }
  }
}
Variables
{"language": "en"}
Response
{
  "data": {
    "dynmaicOptions": {
      "brand": [{"key": "ecodrink", "value": "EcoDrink"}],
      "size": [{"key": "medium", "value": "Medium"}],
      "shape": [{"key": "rectangle", "value": "Rectangle"}],
      "stock": [{"key": "14pt_gloss", "value": "14pt Gloss"}],
      "colorspec": [{"key": "4_4_full_color", "value": "4/4 Full Colour"}],
      "coating": [{"key": "gloss_aq", "value": "Gloss AQ"}],
      "spot_uv_sides": [],
      "scoring_options": [],
      "drill_hole": [],
      "bundling_service": [],
      "shrink_wrapping": [],
      "lamination": [{"key": "soft_touch", "value": "Soft Touch"}],
      "foil_color": [{"key": "gold", "value": "Gold"}],
      "second_raised_color": [],
      "raised_foil_side": [],
      "raised_spot_uv_height": [],
      "raised_spot_uv_side": [],
      "radius_of_corners": [],
      "business_card_box_size": [],
      "product_color": [],
      "product_material": [],
      "score_and_fold": [],
      "eddm_service_option": [],
      "rider_pins": [],
      "branding": [],
      "perforation": [],
      "cover_coating": [],
      "product_style": [],
      "cover_stock": [],
      "numbering": [],
      "page_count": [],
      "sheets_per_pad": [],
      "wraparound_cover": [],
      "hardware": [],
      "catalog_version": [],
      "product_orientation": [{"key": "portrait", "value": "Portrait"}],
      "mailing_service": [{"key": "standard", "value": "Standard"}],
      "number_of_tabs": [],
      "binding_type": [{"key": "saddle_stitch", "value": "Saddle Stitch"}],
      "binding_edge": [],
      "folding_options": [{"key": "half_fold", "value": "Half Fold"}],
      "button_backing_options": [],
      "button_shape_options": [],
      "shirt_size_multi_picker": [],
      "unwind_options": [],
      "fastener_options": [],
      "handle_options": [],
      "die_cut_options": [],
      "sleeve": [],
      "white_mask_front": [],
      "mount_position": [],
      "pockets": [],
      "business_card_slit": [],
      "flap_style": [],
      "blank_envelopes": [],
      "cd_slit": [],
      "edge_color": [],
      "qty_per_book": [],
      "blank_second_sheets": [],
      "slits": [],
      "variable_data": [{"key": "yes", "value": "Yes"}],
      "opening_side": [],
      "window_options": [],
      "clear_case": [],
      "edge_join_options": []
    }
  }
}

Products

Description

Returns the normalised, language-filtered product catalogue for the active supplier, paginated. Products without a SKU are silently excluded. The supplier is determined from the SupplierCode HTTP header. Results are scoped to the authenticated user’s saved category list.

Response

Returns a ProductResponse!

Arguments
Name Description
language – String! ISO language code, e.g. en. Falls back to English then any available language.
page – Int! 1-based page number.
pageSize – Int! Number of records per page.
modificationDate – String Optional ISO date (YYYY-MM-DD). Only products modified on or after this date are returned.
itemCode – String Optional. Filters results to a single product by the supplier’s item code.

Example

Query
query Products(
  $language: String!,
  $page: Int!,
  $pageSize: Int!,
  $modificationDate: String,
  $itemCode: String
) {
  products(
    language: $language,
    page: $page,
    pageSize: $pageSize,
    modificationDate: $modificationDate,
    itemCode: $itemCode
  ) {
    products {
      sku
      templateCode
      itemCode
      supplier
      createdAt
      updatedAt
      media {
        images {
          isPrimary
          url
          urlHigh
          type
        }
        digitalAssets {
          url
          type
        }
      }
      measurements {
        grossWeight {
          value
          unit
        }
        netWeight {
          value
          unit
        }
        width {
          value
          unit
        }
        height {
          value
          unit
        }
        length {
          value
          unit
        }
        volume {
          value
          unit
        }
        diameter {
          value
          unit
        }
        circumference {
          value
          unit
        }
        grammage {
          value
          unit
        }
      }
      metadata {
        creationDateTime
        modifiedDate
        isDiscontinued
      }
      product {
        templateTitle
        variantName
        longDescription
        description
        brand
        material
        gender
        tags
        commentsNotes
        dynamicAttributes
        customAttributes
        runsize
        specificAttributes {
          name
          value
        }
        variationDependencies
        relatedItems
        moqPrint
        moqWithoutPrint
        currency
        eanOrGtin
        isPrintable
      }
      categories {
        level
        name
        description
        image
        cat_code
      }
      variantAttributes {
        color {
          name
          code
          pms
          hex
          group
          description
          pmsCode
          pmsColorReference
          cmyk
          colorShade
        }
        size
        sizeGrid
      }
      pricing {
        pricelist {
          min
          max
          gross
          net
        }
        additionalCharges {
          name
          chargePerOrder
          chargePerItem
          quantityFrom
        }
        modifiedDate
        expiresAt
        effectiveFrom
      }
      complianceSustainability {
        isEco
        countryOfOrigin
        greenPoints
        greenPointsFile
        certifications {
          name
          url
        }
        co2Total
        co2EmissionBenchmark
        recycledContent
      }
      stockManagement {
        currentStock
        stockLocation
        location {
          name
          code
          qty
        }
        unit
        nextStockDate
        nextStockQuantity
      }
      packaging {
        innerCarton {
          qty
          price
          dimensions {
            length
            width
            height
            unit
          }
          weight {
            net
            unit
          }
          volume {
            value
            unit
          }
          packagingType
        }
        outerCarton {
          qty
          price
          dimensions {
            length
            width
            height
            unit
          }
          weight {
            gross
            unit
          }
          volume {
            value
            unit
          }
          packagingType
        }
      }
      shipping {
        carrier
        tierCharges {
          type
          qty
          price
        }
      }
      seo {
        metaKeywords
      }
      printing {
        printData {
          location
          locationCode
          locationMaxWidth
          locationMaxHeight
          locationDiameter
          locationUnit
          shape
          nextColourCostIndicator
          maxColors
          method
          methodCode
          priceDependency
          points {
            distance_from_left
            distance_from_top
            sequence_no
          }
          setupCharges {
            type
            value
          }
          pricing {
            colorPricing {
              numPosition
              numColours
              tiers {
                colorQuantityFrom
                colorQuantityTo
                grossPrice
                netPrice
                nextPrice
                vdpNetPrice
                vdpGrossPrice
              }
              setupCharges {
                type
                value
              }
            }
            sizePricing {
              numPosition
              size {
                value
                unit
              }
              area {
                from
                to
                unit
              }
              tiers {
                sizeQuantityFrom
                sizeQuantityTo
                grossPrice
                netPrice
                nextPrice
                vdpNetPrice
                vdpGrossPrice
              }
              setupCharges {
                type
                value
              }
            }
          }
          coordinates {
            topLeftX
            topLeftY
            topRightX
            topRightY
            bottomLeftX
            bottomLeftY
            bottomRightX
            bottomRightY
            width
            height
            unit
            diameter
          }
          leadTime {
            standard
            maxQty
          }
          images {
            blankImage
            markedImage
          }
          printNotes
        }
        artworkTemplates {
          type
          url
        }
      }
    }
    totalCount
  }
}
Variables
{
  "language": "en",
  "page": 1,
  "pageSize": 10,
  "modificationDate": "2026-01-01",
  "itemCode": "xyz789"
}
Response
{
  "data": {
    "products": {
      "products": [
        {
          "sku": "TEST-001-BLK",
          "templateCode": "TMPL-001",
          "itemCode": "TMPL-001-BLK",
          "supplier": "test_supplier",
          "createdAt": "2025-08-15T09:00:00Z",
          "updatedAt": "2025-08-15T09:00:00Z",
          "media": {
            "images": [
              {
                "isPrimary": true,
                "url": "https://example.com/images/mug-black-front.jpg",
                "urlHigh": "https://example.com/images/mug-black-front-highres.jpg",
                "type": "main"
              },
              {
                "isPrimary": false,
                "url": "https://example.com/images/mug-black-side.jpg",
                "urlHigh": "https://example.com/images/mug-black-side-highres.jpg",
                "type": "side"
              }
            ],
            "digitalAssets": [
              {
                "url": "https://example.com/assets/mug-manual.pdf",
                "type": "document"
              },
              {
                "url": "https://example.com/assets/mug-video.mp4",
                "type": "video"
              }
            ]
          },
          "measurements": {
            "grossWeight": {"value": 0.35, "unit": "kg"},
            "netWeight": {"value": 0.3, "unit": "kg"},
            "width": {"value": 80, "unit": "mm"},
            "height": {"value": 95, "unit": "mm"},
            "length": {"value": 80, "unit": "mm"},
            "volume": {"value": 0.608, "unit": "l"},
            "diameter": {"value": 80, "unit": "mm"},
            "circumference": {"value": 251.2, "unit": "mm"},
            "grammage": {"value": 275, "unit": "g/m2"}
          },
          "metadata": {
            "creationDateTime": "2025-08-15T09:00:00Z",
            "modifiedDate": "2025-08-15T09:00:00Z",
            "isDiscontinued": false
          },
          "product": {
            "templateTitle": "Classic Ceramic Mug",
            "variantName": "Black Ceramic Mug",
            "longDescription": "A durable black ceramic mug perfect for everyday use.",
            "description": "A durable black ceramic mug for everyday use.",
            "brand": "EcoDrink",
            "material": "Ceramic",
            "gender": "Unisex",
            "tags": "ceramic mug, black mug, promotional mug, drinkware",
            "commentsNotes": "Suitable for promotional branding.",
            "dynamicAttributes": {"finish": "Glossy", "dishwasherSafe": "Yes"},
            "customAttributes": {
              "catalogPage": "42",
              "internalNote": "Top seller Q3"
            },
            "runsize": {"sizes": ["S", "M", "L", "XL"], "defaultSize": "M"},
            "specificAttributes": [
              {"name": "Weight", "value": "275g"},
              {"name": "Capacity", "value": "350ml"}
            ],
            "variationDependencies": ["material", "color", "size"],
            "relatedItems": ["TMPL-001-WHT", "TMPL-001-RED"],
            "moqPrint": 50,
            "moqWithoutPrint": 50,
            "currency": "USD",
            "eanOrGtin": "0123456789012",
            "isPrintable": true
          },
          "categories": [
            {
              "level": 1,
              "name": "Drinkware",
              "description": "High-quality drinkware for daily use and gifting",
              "image": "https://example.com/images/drinkware.jpg",
              "cat_code": "drinkware_one"
            },
            {
              "level": 2,
              "name": "Bottle",
              "description": "Various types of bottles",
              "image": null,
              "cat_code": "bottle_two"
            },
            {
              "level": 3,
              "name": "Mugs",
              "description": "Ceramic and glass mugs",
              "image": null,
              "cat_code": "mugs_three"
            }
          ],
          "variantAttributes": {
            "color": {
              "name": "Black",
              "code": "BLK-16",
              "pms": "Black C",
              "hex": "#000000",
              "group": "Blacks",
              "description": "Deep matte black finish",
              "pmsCode": "PMS-Black-C",
              "pmsColorReference": "Pantone Black C",
              "cmyk": "0,0,0,100",
              "colorShade": "dark"
            },
            "size": "XL",
            "sizeGrid": "350ml,450ml"
          },
          "pricing": {
            "pricelist": [
              {"min": 1, "max": 49, "gross": 5.99, "net": 4.79},
              {"min": 50, "max": 999, "gross": 4.99, "net": 3.99}
            ],
            "additionalCharges": [
              {
                "name": "Ink mixing charge",
                "chargePerOrder": 60,
                "chargePerItem": 0,
                "quantityFrom": 1
              },
              {
                "name": "Rush order fee",
                "chargePerOrder": 25,
                "chargePerItem": 0,
                "quantityFrom": 1
              }
            ],
            "modifiedDate": "2025-08-01T10:00:00Z",
            "expiresAt": "2025-12-31T23:59:59Z",
            "effectiveFrom": "2025-08-01T00:00:00Z"
          },
          "complianceSustainability": {
            "isEco": true,
            "countryOfOrigin": "CN",
            "greenPoints": 16,
            "greenPointsFile": "https://example.com/assets/green-points.pdf",
            "certifications": [
              {
                "name": "DoC",
                "url": "https://example.com/certificates/doc-mug.pdf"
              },
              {
                "name": "BPA-Free",
                "url": "https://example.com/certificates/bpa-free.pdf"
              }
            ],
            "co2Total": 0.43,
            "co2EmissionBenchmark": 0.5,
            "recycledContent": 20
          },
          "stockManagement": {
            "currentStock": 1200,
            "stockLocation": "PL",
            "location": [
              {"name": "US-WH1", "code": "US-WH1", "qty": 800},
              {"name": "EU-WH2", "code": "EU-WH2", "qty": 400}
            ],
            "unit": "pcs",
            "nextStockDate": "2025-09-15",
            "nextStockQuantity": 2000
          },
          "packaging": {
            "innerCarton": [
              {
                "qty": 12,
                "price": 0,
                "dimensions": {
                  "length": 40,
                  "width": 30,
                  "height": 20,
                  "unit": "cm"
                },
                "weight": {"net": 4.2, "unit": "kg"},
                "volume": {"value": 0.024, "unit": "m3"},
                "packagingType": "Box"
              }
            ],
            "outerCarton": [
              {
                "qty": 48,
                "price": 0,
                "dimensions": {
                  "length": 60,
                  "width": 40,
                  "height": 30,
                  "unit": "cm"
                },
                "weight": {"gross": 18.5, "unit": "kg"},
                "volume": {"value": 0.072, "unit": "m3"},
                "packagingType": "Box"
              }
            ]
          },
          "shipping": [
            {
              "carrier": "FedEx",
              "tierCharges": [
                {"type": "standard", "qty": "1-100", "price": "15.00"},
                {"type": "express", "qty": "1-100", "price": "25.00"}
              ]
            }
          ],
          "seo": {
            "metaKeywords": "ceramic mug, black mug, promotional mug, eco-friendly drinkware"
          },
          "printing": {
            "printData": [
              {
                "location": "Front",
                "locationCode": "FRT-01",
                "locationMaxWidth": 80,
                "locationMaxHeight": 60,
                "locationDiameter": 0,
                "locationUnit": "mm",
                "shape": "Rectangle",
                "priceDependency": "monocolor",
                "nextColourCostIndicator": true,
                "maxColors": 4,
                "method": "Screen Print",
                "methodCode": "SCR-001",
                "printNotes": "Ensure artwork is high-resolution for best results.",
                "points": [],
                "setupCharges": [{"type": "Setup", "value": 10}],
                "pricing": {
                  "colorPricing": [
                    {
                      "numPosition": 1,
                      "numColours": 2,
                      "tiers": [
                        {
                          "colorQuantityFrom": 1,
                          "colorQuantityTo": 49,
                          "grossPrice": 0.6,
                          "netPrice": 0.48,
                          "nextPrice": 0.44,
                          "vdpNetPrice": 0.48,
                          "vdpGrossPrice": 0.6
                        },
                        {
                          "colorQuantityFrom": 50,
                          "colorQuantityTo": 99,
                          "grossPrice": 0.55,
                          "netPrice": 0.44,
                          "nextPrice": 0.4,
                          "vdpNetPrice": 0.44,
                          "vdpGrossPrice": 0.55
                        },
                        {
                          "colorQuantityFrom": 100,
                          "colorQuantityTo": null,
                          "grossPrice": 0.5,
                          "netPrice": 0.4,
                          "nextPrice": null,
                          "vdpNetPrice": 0.4,
                          "vdpGrossPrice": 0.5
                        }
                      ],
                      "setupCharges": [{"type": "Setup", "value": 25}]
                    },
                    {
                      "numPosition": 1,
                      "numColours": 4,
                      "tiers": [
                        {
                          "colorQuantityFrom": 1,
                          "colorQuantityTo": 49,
                          "grossPrice": 0.8,
                          "netPrice": 0.64,
                          "nextPrice": 0.6,
                          "vdpNetPrice": 0.64,
                          "vdpGrossPrice": 0.8
                        },
                        {
                          "colorQuantityFrom": 50,
                          "colorQuantityTo": null,
                          "grossPrice": 0.75,
                          "netPrice": 0.6,
                          "nextPrice": null,
                          "vdpNetPrice": 0.6,
                          "vdpGrossPrice": 0.75
                        }
                      ],
                      "setupCharges": [{"type": "Setup", "value": 50}]
                    }
                  ],
                  "sizePricing": [
                    {
                      "numPosition": 1,
                      "size": {"value": 80, "unit": "mm"},
                      "area": {"from": 50, "to": 200, "unit": "cm2"},
                      "tiers": [
                        {
                          "sizeQuantityFrom": 1,
                          "sizeQuantityTo": 100,
                          "grossPrice": 0.5,
                          "netPrice": 0.4,
                          "nextPrice": 0.56,
                          "vdpNetPrice": 0.4,
                          "vdpGrossPrice": 0.5
                        },
                        {
                          "sizeQuantityFrom": 101,
                          "sizeQuantityTo": null,
                          "grossPrice": 0.7,
                          "netPrice": 0.56,
                          "nextPrice": null,
                          "vdpNetPrice": 0.56,
                          "vdpGrossPrice": 0.7
                        }
                      ],
                      "setupCharges": [{"type": "Setup", "value": 30}]
                    }
                  ]
                },
                "coordinates": {
                  "topLeftX": 10,
                  "topLeftY": 20,
                  "topRightX": 90,
                  "topRightY": 20,
                  "bottomLeftX": 10,
                  "bottomLeftY": 80,
                  "bottomRightX": 90,
                  "bottomRightY": 80,
                  "width": 80,
                  "height": 60,
                  "unit": "mm",
                  "diameter": 0
                },
                "leadTime": {"standard": "7 days", "maxQty": 500},
                "images": {
                  "blankImage": "https://example.com/images/print-blank.jpg",
                  "markedImage": "https://example.com/images/print-marked.jpg"
                }
              }
            ],
            "artworkTemplates": [
              {
                "type": "PSD",
                "url": "https://example.com/templates/mug-template.psd"
              },
              {
                "type": "AI",
                "url": "https://example.com/templates/mug-template.ai"
              },
              {
                "type": "PDF",
                "url": "https://example.com/templates/mug-template.pdf"
              }
            ]
          }
        }
      ],
      "totalCount": 1
    }
  }
}

Types

Types

Product

Description

A unified, language-filtered supplier product. Stored in MongoDB in the unified_products collection (global) or a user GUID collection (supplier-specific). Products without a SKU are silently excluded from all query results.

Fields
Field Name Description
sku – String Stock Keeping Unit — the platform’s unique identifier for this product variant. Products that have no SKU value are excluded from all query results.
templateCode – String Template code identifying the product family that this variant belongs to.
itemCode – String The supplier’s own item/product code from their catalogue.
supplier – String Supplier identifier — matches the value of the SupplierCode HTTP request header used when the data was ingested (e.g. 4over, midocean).
createdAt – DateTime UTC timestamp when this product document was created in MongoDB.
updatedAt – DateTime UTC timestamp of the last update to this product document in MongoDB.
media – Media Product images and downloadable digital assets (print templates, spec PDFs, etc.).
measurements – Measurements Physical dimensions and weights of the product (all values are nullable doubles).
metadata – Metadata Lifecycle metadata: creation date, last modification date, and discontinuation flag.
product – ProductDetails Core product details filtered to the requested language.
categories – [Category!]! Category nodes this product belongs to, filtered to the requested language.
variantAttributes – VariantAttributes Colour and size variant attributes for this specific product variant.
pricing – Pricing Quantity-based pricing tiers and additional charges.
complianceSustainability – ComplianceSustainability Environmental and compliance data: eco flags, certifications, CO2 estimates, recycled content.
stockManagement – StockManagement Current stock levels across warehouse locations with next restock details.
packaging – Packaging Inner-carton and outer-carton packaging specifications for freight calculation.
shipping – [Shipping!]! Shipping carrier options with tiered quantity-based charges.
seo – Seo SEO metadata (meta keywords) for this product.
printing – Printing Print decoration data: locations, methods, colour/size pricing, coordinates, and artwork templates.
Example
{
  "sku": "4OVER-BC-001-RED",
  "templateCode": "BC-001",
  "itemCode": "BC001-R",
  "supplier": "4over",
  "createdAt": "2026-04-20T12:00:00.000Z",
  "updatedAt": "2026-04-20T12:00:00.000Z",
  "media": Media,
  "measurements": Measurements,
  "metadata": Metadata,
  "product": ProductDetails,
  "categories": [Category],
  "variantAttributes": VariantAttributes,
  "pricing": Pricing,
  "complianceSustainability": ComplianceSustainability,
  "stockManagement": StockManagement,
  "packaging": Packaging,
  "shipping": [Shipping],
  "seo": Seo,
  "printing": Printing
}

ProductDetails

Description

Core product details. Stored in MongoDB as multilingual dictionaries (Dictionary<string, string> keyed by language code). The API returns the value for the requested language, falling back to English then any available language.

Fields
Field Name Description
templateTitle – String Localised product title.
variantName – String Localised variant name describing this specific variant (e.g. a colour name).
longDescription – String Extended localised marketing description.
description – String Short localised product description.
brand – String Brand name, language-filtered.
material – String Material composition, language-filtered (e.g. 100% Cotton, Recycled PET).
gender – String Target gender, language-filtered (e.g. Men, Women, Unisex).
tags – String Searchable tags, language-filtered, typically comma-separated.
commentsNotes – String Internal notes or supplier comments, language-filtered.
dynamicAttributes – JSON Flexible print-related attributes stored as a JSON object. Structure varies by supplier — parsed from a multilingual Dictionary in the database.
customAttributes – JSON Supplier-specific custom attribute bag as a JSON object. Structure varies by supplier — parsed from a multilingual Dictionary in the database.
runsize – JSON Run-size configuration as a JSON object, parsed from a BSON document in the database.
specificAttributes – [SpecificAttribute!]! Structured key/value attribute pairs for typed filtering and display (language-filtered).
variationDependencies – [String!]! SKUs of related product variants within the same template family.
relatedItems – [String!]! SKUs of cross-sell or complementary products.
moqPrint – Float Minimum order quantity when ordering with print decoration applied.
moqWithoutPrint – Float Minimum order quantity for blank (undecorated) orders.
currency – String Pricing currency code, e.g. USD, EUR.
eanOrGtin – String EAN-13 or GTIN barcode value.
isPrintable – Boolean Whether this product supports print decoration.
Example
{
  "templateTitle": "Standard Business Card",
  "variantName": "Fire Red",
  "longDescription": "xyz789",
  "description": "abc123",
  "brand": "Gildan",
  "material": "100% Cotton",
  "gender": "Unisex",
  "tags": "abc123",
  "commentsNotes": "abc123",
  "dynamicAttributes": {"key": "value"},
  "customAttributes": {"key": "value"},
  "runsize": {"key": "value"},
  "specificAttributes": [SpecificAttribute],
  "variationDependencies": ["xyz789"],
  "relatedItems": ["abc123"],
  "moqPrint": 50,
  "moqWithoutPrint": 10,
  "currency": "USD",
  "eanOrGtin": "4099988000012",
  "isPrintable": true
}

SpecificAttribute

Description

A typed product attribute as a name/value pair, language-filtered. Used for structured display and filtering (e.g. { name: "Finish", value: "Matte" }).

Fields
Field Name Description
name – String Attribute label, language-filtered from the database.
value – String Attribute value, language-filtered from the database.
Example
{"name": "Finish", "value": "Matte"}

Media

Description

All media assets attached to a product — images and downloadable digital assets.

Fields
Field Name Description
images – [Image!] Product images. The primary hero image has isPrimary set to true.
digitalAssets – [DigitalAsset!] Downloadable files such as print templates, spec sheets, or artwork guides.
Example
{
  "images": [Image],
  "digitalAssets": [DigitalAsset]
}

Image

Description

A single product image with an optional high-resolution variant.

Fields
Field Name Description
isPrimary – Boolean True for the main hero image; false for supplementary angles or detail shots.
url – String Standard-resolution image URL.
urlHigh – String High-resolution image URL for zoom or print preview.
type – String Image role (e.g. front, back, detail, lifestyle). Free-form string from the supplier.
Example
{
  "isPrimary": true,
  "url": "xyz789",
  "urlHigh": "abc123",
  "type": "front"
}

DigitalAsset

Description

A downloadable digital asset linked to a product, such as a print template or specification PDF.

Fields
Field Name Description
url – String Download URL for the asset.
type – String Asset type, e.g. template, pdf, eps, ai. Free-form string from the supplier.
Example
{"url": "abc123", "type": "template"}

Measurements

Description

Physical dimensions and weights of the product. All sub-fields are nullable Measurement pairs.

Fields
Field Name Description
grossWeight – Measurement Total weight including packaging.
netWeight – Measurement Weight of the product only, excluding packaging.
width – Measurement Product width.
height – Measurement Product height.
length – Measurement Product length or depth.
volume – Measurement Product volume.
diameter – Measurement Diameter for round or cylindrical products.
circumference – Measurement Circumference for round products.
grammage – Measurement Paper grammage in g/m2 for paper or print products.
Example
{
  "grossWeight": Measurement,
  "netWeight": Measurement,
  "width": Measurement,
  "height": Measurement,
  "length": Measurement,
  "volume": Measurement,
  "diameter": Measurement,
  "circumference": Measurement,
  "grammage": Measurement
}

Measurement

Description

A scalar measurement with a numeric value and an explicit unit. Both fields are nullable.

Fields
Field Name Description
value – Float Numeric measurement value (nullable double).
unit – String Unit of measure, e.g. mm, cm, kg, g, ml, cbm.
Example
{"value": 210, "unit": "mm"}

Metadata

Description

Lifecycle metadata for a product document in MongoDB.

Fields
Field Name Description
creationDateTime – DateTime UTC timestamp when this product document was first created.
modifiedDate – DateTime UTC timestamp of the last modification to this product document.
isDiscontinued – Boolean True if the supplier has discontinued this product.
Example
{
  "creationDateTime": "2026-04-20T12:00:00.000Z",
  "modifiedDate": "2026-04-20T12:00:00.000Z",
  "isDiscontinued": false
}

Category

Description

A single node in the category hierarchy. In the database, category names and descriptions are stored as multilingual dictionaries and filtered to the requested language before being returned.

Fields
Field Name Description
level – Int Depth of this node in the hierarchy. 1 is the root/top level.
name – String Localised category name, language-filtered from the multilingual DB field.
description – String Optional localised description, language-filtered from the multilingual DB field.
image – String URL of the representative category image.
cat_code – String Supplier’s own category code.
Example
{
  "level": 1,
  "name": "Drinkware",
  "description": "High-quality drinkware for daily use and gifting",
  "image": "https://example.com/images/drinkware.jpg",
  "cat_code": "drinkware_one"
}

VariantAttributes

Description

Colour and size attributes that identify this variant within its template product family.

Fields
Field Name Description
color – ColorDetails Full colour specification including PMS codes, hex, CMYK, and descriptive fields.
size – String Size label for this variant, e.g. M, A4, 100x200mm.
sizeGrid – String Size grid/chart identifier linking this variant to a standardised size chart.
Example
{
  "color": ColorDetails,
  "size": "M",
  "sizeGrid": "EU-APPAREL"
}

ColorDetails

Description

Full colour specification for a product variant.

Fields
Field Name Description
name – String Localised colour name.
code – String Supplier’s internal colour code.
pms – String Pantone Matching System colour name.
hex – String Web hex colour value without the # prefix (e.g. FF0000).
group – String Colour family group for filtering (e.g. Reds, Blues, Neutrals).
description – String Additional colour description or supplier notes.
pmsCode – String Numeric PMS code.
pmsColorReference – String Full PMS reference string for artwork specification (e.g. Pantone Red 032 C).
cmyk – String CMYK breakdown as a comma-separated string (e.g. 0,100,100,0).
colorShade – String Shade label within the colour group (e.g. light, dark, bright).
Example
{
  "name": "Fire Red",
  "code": "C-RED",
  "pms": "Red 032 C",
  "hex": "FF0000",
  "group": "Reds",
  "description": "xyz789",
  "pmsCode": "032",
  "pmsColorReference": "Pantone Red 032 C",
  "cmyk": "0,100,100,0",
  "colorShade": "bright"
}

Pricing

Description

Pricing information for a product — quantity-break price tiers, additional charges, and the effective date range. All numeric values are nullable doubles.

Fields
Field Name Description
pricelist – [PriceTier!]! Quantity-based price tiers. Each tier defines a min/max quantity band with gross and net prices.
additionalCharges – [AdditionalCharge!]! Additional charges on top of the unit price (e.g. screen setup, handling).
modifiedDate – DateTime When this pricing record was last updated in the supplier’s system.
expiresAt – DateTime Date after which this pricing expires and should no longer be used.
effectiveFrom – DateTime Date from which this pricing is valid.
Example
{
  "pricelist": [PriceTier],
  "additionalCharges": [AdditionalCharge],
  "modifiedDate": "2026-04-20T12:00:00.000Z",
  "expiresAt": "2026-04-20T12:00:00.000Z",
  "effectiveFrom": "2026-04-20T12:00:00.000Z"
}

PriceTier

Description

A quantity-break price tier. All numeric fields are nullable doubles.

Fields
Field Name Description
min – Float Minimum quantity for this tier (inclusive).
max – Float Maximum quantity for this tier (inclusive). Null indicates no upper bound.
gross – Float Gross (list) price per unit in the supplier’s currency.
net – Float Net (trade) price per unit in the supplier’s currency.
Example
{"min": 1, "max": 99, "gross": 1.5, "net": 1.2}

AdditionalCharge

Description

An additional charge applied to an order beyond the unit price (e.g. setup fee, handling).

Fields
Field Name Description
name – String Charge name, language-filtered (e.g. Screen Setup, Handling).
chargePerOrder – Float Flat fee charged once per order regardless of quantity.
chargePerItem – Float Per-unit fee added to each ordered item.
quantityFrom – Float Minimum quantity at which this charge applies.
Example
{
  "name": "Screen Setup",
  "chargePerOrder": 25,
  "chargePerItem": 0.5,
  "quantityFrom": 1
}

ComplianceSustainability

Description

Environmental and regulatory compliance data for the product.

Fields
Field Name Description
isEco – Boolean True if the product meets eco-certification criteria.
countryOfOrigin – String ISO country code of the manufacturing country, e.g. CN, DE, TR.
greenPoints – Float Sustainability score on a supplier-specific scale.
greenPointsFile – String URL to the eco certification document.
certifications – [Certification!]! Compliance and sustainability certifications (e.g. FSC, OEKO-TEX, BSCI).
co2Total – Float Total estimated CO2 emissions in kg for producing one unit.
co2EmissionBenchmark – Float Industry benchmark CO2 value used for comparison.
recycledContent – Float Recycled material percentage (e.g. 30 means 30%).
Example
{
  "isEco": true,
  "countryOfOrigin": "CN",
  "greenPoints": 8,
  "greenPointsFile": "xyz789",
  "certifications": [Certification],
  "co2Total": 1.4,
  "co2EmissionBenchmark": 2,
  "recycledContent": 30
}

Certification

Description

A named compliance or sustainability certification associated with a product.

Fields
Field Name Description
name – String Certification name, e.g. FSC, OEKO-TEX, BSCI, ISO9001.
url – String Link to the certificate or certification body website.
Example
{"name": "FSC", "url": "abc123"}

StockManagement

Description

Stock availability for the product across warehouse locations.

Fields
Field Name Description
currentStock – Float Total available stock units across all locations.
stockLocation – String Primary warehouse location code (e.g. WH-001, NY-DIST). This is an internal warehouse identifier, not a display name.
location – [StockLocation!]! Stock breakdown by individual warehouse or fulfilment location.
unit – String Unit of stock quantity, e.g. pcs, box, roll.
nextStockDate – String Expected date of the next stock arrival in YYYY-MM-DD format.
nextStockQuantity – Float Expected quantity arriving on the next stock date.
Example
{
  "currentStock": 500,
  "stockLocation": "WH-001",
  "location": [StockLocation],
  "unit": "pcs",
  "nextStockDate": "2026-07-15",
  "nextStockQuantity": 1000
}

StockLocation

Description

Stock quantity at a single warehouse or fulfilment location.

Fields
Field Name Description
name – String Location display name, language-filtered from the multilingual DB field.
code – String Internal location code identifier.
qty – Float Units available at this location (nullable double).
Example
{"name": "Amsterdam DC", "code": "AMS-01", "qty": 250}

Packaging

Description

Inner-carton and outer-carton packaging specifications for freight and packing slip use.

Fields
Field Name Description
innerCarton – [InnerCarton!]! Inner (retail) carton specifications — dimensions, net weight, and quantity per carton.
outerCarton – [OuterCarton!]! Outer (master shipping) carton specifications — dimensions, gross weight, and quantity per carton.
Example
{
  "innerCarton": [InnerCarton],
  "outerCarton": [OuterCarton]
}

InnerCarton

Description

Inner (retail) carton specification.

Fields
Field Name Description
qty – Float Units per inner carton.
price – Float Inner carton price if separately purchasable.
dimensions – Dimensions External dimensions of the inner carton (L x W x H).
weight – InnerCartonWeight Net weight of the inner carton.
volume – Volume Volume of the inner carton.
packagingType – String Packaging material type, language-filtered. Examples: box, bag, poly_bag, blister, tube.
Example
{
  "qty": 12,
  "price": 0,
  "dimensions": Dimensions,
  "weight": InnerCartonWeight,
  "volume": Volume,
  "packagingType": "box"
}

OuterCarton

Description

Outer (master shipping) carton specification.

Fields
Field Name Description
qty – Float Units per outer carton.
price – Float Carton price if applicable.
dimensions – Dimensions External dimensions of the outer carton (L x W x H).
weight – OuterCartonWeight Gross weight of the outer carton.
volume – Volume Volume of the outer carton.
packagingType – String Packaging material type, language-filtered. Examples: corrugated, wooden.
Example
{
  "qty": 144,
  "price": 0,
  "dimensions": Dimensions,
  "weight": OuterCartonWeight,
  "volume": Volume,
  "packagingType": "corrugated"
}

Dimensions

Description

External dimensions of a carton or package.

Fields
Field Name Description
length – Float Length.
width – Float Width.
height – Float Height.
unit – String Unit of measurement, e.g. mm, cm.
Example
{"length": 300, "width": 200, "height": 100, "unit": "mm"}

InnerCartonWeight

Description

Net weight of an inner carton.

Fields
Field Name Description
net – Float Net weight value (nullable double).
unit – String Weight unit, e.g. kg, g.
Example
{"net": 0.5, "unit": "kg"}

OuterCartonWeight

Description

Gross weight of an outer (master shipping) carton.

Fields
Field Name Description
gross – Float Gross weight value (nullable double).
unit – String Weight unit, e.g. kg.
Example
{"gross": 8.5, "unit": "kg"}

Volume

Description

A volume value with a unit.

Fields
Field Name Description
value – Float Volume amount (nullable double).
unit – String Volume unit, e.g. cbm, ml, l.
Example
{"value": 0.006, "unit": "cbm"}

Shipping

Description

A shipping option for a product via a named carrier with tiered quantity-based charges.

Fields
Field Name Description
carrier – String Carrier name or code (e.g. DHL, UPS, FedEx). Free-form string from the supplier.
tierCharges – [TierCharge!]! Quantity-tiered shipping charge bands for this carrier.
Example
{"carrier": "DHL", "tierCharges": [TierCharge]}

TierCharge

Description

A single shipping charge tier.

Fields
Field Name Description
type – String Charge type descriptor (e.g. unit, flat). Free-form string from the supplier.
qty – String Minimum quantity threshold for this tier.
price – String Shipping price for this tier in the supplier’s currency.
Example
{"type": "unit", "qty": "1", "price": "9.95"}

Seo

Description

SEO metadata for the product listing.

Fields
Field Name Description
metaKeywords – String Comma-separated meta keywords for search engine indexing.
Example
{"metaKeywords": "business cards, print, custom"}

Printing

Description

All print decoration data for the product.

Fields
Field Name Description
printData – [PrintData!]! Decoration locations on the product. Each entry describes one printable area with its method, colour limits, pricing tiers, coordinate overlay, and lead time.
artworkTemplates – [ArtworkTemplate!]! Downloadable artwork template files provided by the supplier (PDF, AI, EPS, etc.).
Example
{
  "printData": [PrintData],
  "artworkTemplates": [ArtworkTemplate]
}

PrintData

Description

A single printable decoration location on the product. Most string fields are language-filtered from multilingual dictionaries in the database. Coordinates, images, and leadTime are only included when their data is non-null/non-empty.

Fields
Field Name Description
location – String Decoration location name, language-filtered (e.g. Front Centre, Left Chest).
locationCode – String Machine code for this decoration location (e.g. FC, LC).
locationMaxWidth – Float Maximum printable width for this location, in locationUnit.
locationMaxHeight – Float Maximum printable height for this location, in locationUnit.
locationDiameter – Float Maximum print diameter for circular locations, in locationUnit. Zero for non-circular areas.
locationUnit – String Unit for all location dimensions (e.g. mm, cm, inches).
shape – String Print area shape, language-filtered. Typical values: rectangle, circle, oval, custom.
nextColourCostIndicator – Boolean! True if each additional ink colour increases the price for this location.
maxColors – Float Maximum number of ink colours permitted on this decoration location.
method – String Decoration method, language-filtered. Typical values: screen_print, embroidery, dtg, heat_transfer, engraving, sublimation, rotary_screen.
methodCode – String Machine code for the decoration method (e.g. SP, EMB, DIG).
priceDependency – String Determines which factor drives print price variation. Known values: monocolor, multicolor, size, position.
points – [PrintPoint!]! Boundary points of a non-rectangular print area polygon, ordered by sequence_no.
setupCharges – [SetupCharge!]! One-off setup charges for this decoration location (e.g. screen setup, artwork preparation).
pricing – PrintPricing Colour-count-based and/or size-based print pricing tiers for this location.
coordinates – PrintCoordinates Corner coordinates of the print area on the product image for live preview overlay.
leadTime – PrintLeadTime Production lead time for this decoration method.
images – PrintImages Blank and marked product images for this location.
printNotes – String Free-text decoration notes or constraints from the supplier, language-filtered.
Example
{
  "location": "Front Centre",
  "locationCode": "FC",
  "locationMaxWidth": 90,
  "locationMaxHeight": 50,
  "locationDiameter": 0,
  "locationUnit": "mm",
  "shape": "rectangle",
  "nextColourCostIndicator": true,
  "maxColors": 4,
  "method": "screen_print",
  "methodCode": "SP",
  "priceDependency": "monocolor",
  "points": [PrintPoint],
  "setupCharges": [SetupCharge],
  "pricing": PrintPricing,
  "coordinates": PrintCoordinates,
  "leadTime": PrintLeadTime,
  "images": PrintImages,
  "printNotes": "abc123"
}

ArtworkTemplate

Description

A downloadable artwork template provided by the supplier for print-ready file setup.

Fields
Field Name Description
type – String Template file type (e.g. pdf, ai, eps, psd). Free-form string from the supplier.
url – String Download URL for the template file.
Example
{"type": "pdf", "url": "abc123"}

SetupCharge

Description

A one-off print setup charge (e.g. screen, plate, artwork preparation fee).

Fields
Field Name Description
type – String Charge type label (e.g. screen, embroidery_setup, artwork). Free-form string from the supplier.
value – Float Charge amount in the supplier’s currency (nullable double).
Example
{"type": "screen", "value": 25}

PrintPricing

Description

Print pricing broken into colour-count-based and size-based tiers. Which type applies is indicated by priceDependency on the parent PrintData.

Fields
Field Name Description
colorPricing – [ColorPricing!] Pricing tiers indexed by number of ink colours. Used when priceDependency is monocolor or multicolor.
sizePricing – [SizePricing!] Pricing tiers indexed by print area size. Used when priceDependency is size.
Example
{
  "colorPricing": [ColorPricing],
  "sizePricing": [SizePricing]
}

ColorPricing

Description

Pricing matrix for a given number of ink colours and decoration positions.

Fields
Field Name Description
numPosition – Float Number of decoration positions this pricing applies to.
numColours – Float Number of ink colours this pricing entry covers.
tiers – [ColorPricingTier!] Quantity-break price tiers for this colour and position combination.
setupCharges – [SetupCharge!] Setup charges specific to this colour count.
Example
{
  "numPosition": 1,
  "numColours": 2,
  "tiers": [ColorPricingTier],
  "setupCharges": [SetupCharge]
}

ColorPricingTier

Description

A single quantity-break price tier within a colour-based pricing matrix.

Fields
Field Name Description
colorQuantityFrom – Float Minimum order quantity for this tier (inclusive).
colorQuantityTo – Float Maximum order quantity for this tier (inclusive).
grossPrice – Float Gross (list) print price per unit.
netPrice – Float Net (trade) print price per unit.
nextPrice – Float Net price for the next colour break, provided for comparison.
vdpNetPrice – Float Variable Data Printing net price per unit.
vdpGrossPrice – Float Variable Data Printing gross price per unit.
Example
{
  "colorQuantityFrom": 50,
  "colorQuantityTo": 99,
  "grossPrice": 2.5,
  "netPrice": 1.9,
  "nextPrice": 1.7,
  "vdpNetPrice": 2.1,
  "vdpGrossPrice": 2.8
}

SizePricing

Description

Pricing matrix for a specific print area size.

Fields
Field Name Description
numPosition – Float Number of decoration positions this pricing applies to.
size – Measurement Specific print size dimension this pricing applies to.
area – Area Area range (from/to) this pricing applies to.
tiers – [SizePricingTier!] Quantity-break price tiers for this size.
setupCharges – [SetupCharge!] Setup charges for this print size.
Example
{
  "numPosition": 1,
  "size": Measurement,
  "area": Area,
  "tiers": [SizePricingTier],
  "setupCharges": [SetupCharge]
}

SizePricingTier

Description

A single quantity-break price tier within a size-based pricing matrix.

Fields
Field Name Description
sizeQuantityFrom – Float Minimum order quantity for this tier (inclusive).
sizeQuantityTo – Float Maximum order quantity for this tier (inclusive).
grossPrice – Float Gross (list) print price per unit.
netPrice – Float Net (trade) print price per unit.
nextPrice – Float Net price for the next size tier, provided for comparison.
vdpNetPrice – Float Variable Data Printing net price per unit.
vdpGrossPrice – Float Variable Data Printing gross price per unit.
Example
{
  "sizeQuantityFrom": 50,
  "sizeQuantityTo": 249,
  "grossPrice": 3,
  "netPrice": 2.2,
  "nextPrice": 2,
  "vdpNetPrice": 2.5,
  "vdpGrossPrice": 3.3
}

PrintCoordinates

Description

Corner pixel/unit coordinates of the print area on the product image. All values are nullable doubles. Only returned when at least one coordinate value is non-null.

Fields
Field Name Description
topLeftX – Float X coordinate of the top-left corner.
topLeftY – Float Y coordinate of the top-left corner.
topRightX – Float X coordinate of the top-right corner.
topRightY – Float Y coordinate of the top-right corner.
bottomLeftX – Float X coordinate of the bottom-left corner.
bottomLeftY – Float Y coordinate of the bottom-left corner.
bottomRightX – Float X coordinate of the bottom-right corner.
bottomRightY – Float Y coordinate of the bottom-right corner.
width – Float Width of the print area in the stated unit.
height – Float Height of the print area in the stated unit.
unit – String Coordinate unit (e.g. px, mm).
diameter – Float Diameter for circular print areas.
Example
{
  "topLeftX": 120,
  "topLeftY": 80,
  "topRightX": 123.45,
  "topRightY": 123.45,
  "bottomLeftX": 123.45,
  "bottomLeftY": 123.45,
  "bottomRightX": 987.65,
  "bottomRightY": 123.45,
  "width": 90,
  "height": 50,
  "unit": "mm",
  "diameter": 0
}

PrintLeadTime

Description

Production lead time for a decoration method, language-filtered from the multilingual DB field.

Fields
Field Name Description
standard – String Standard lead time label (e.g. 5-7 business days). Language-filtered from the DB.
maxQty – Float Maximum quantity that can be fulfilled within the standard lead time.
Example
{"standard": "5-7 business days", "maxQty": 500}

PrintImages

Description

Blank and marked product images for a decoration location. Only returned when at least one of the image URLs is non-empty.

Fields
Field Name Description
blankImage – String URL to the product image without any print area highlight.
markedImage – String URL to the product image with the print area highlighted, used for placement preview.
Example
{
  "blankImage": "xyz789",
  "markedImage": "xyz789"
}

Area

Description

A size area range with a unit, used in size-based print pricing matrices.

Fields
Field Name Description
from – Float Minimum area value for this range (nullable double).
to – Float Maximum area value for this range (nullable double).
unit – String Area unit, e.g. cm2.
Example
{"from": 0, "to": 100, "unit": "cm²"}

PrintPoint

Description

A single boundary point of a non-rectangular print area polygon. Collect all points in ascending sequence_no order to reconstruct the print shape.

Fields
Field Name Description
distance_from_left – Float Horizontal distance from the left edge of the product image.
distance_from_top – Float Vertical distance from the top edge of the product image.
sequence_no – Float 1-based position of this point in the polygon point sequence.
Example
{"distance_from_left": 120, "distance_from_top": 80, "sequence_no": 1}

SupplierOptions

Description

Static catalogue-wide options returned by the options query. Aggregated from product data across all products for the active supplier.

Fields
Field Name Description
brand – [OptionItem!] Distinct brand values across all supplier products.
material – [OptionItem!] Distinct material values across all supplier products.
gender – [OptionItem!] Distinct gender values across all supplier products.
color – [OptionItem!] Distinct colour values across all supplier products.
size – [OptionItem!] Distinct size values across all supplier products.
Example
{
  "brand": [{"key": "ecodrink", "value": "EcoDrink"}],
  "material": [{"key": "ceramic", "value": "Ceramic"}],
  "gender": [{"key": "unisex", "value": "Unisex"}],
  "color": [{"key": "black_blk-16", "value": "Black"}],
  "size": [{"key": "xl", "value": "XL"}]
}

DynamicOptions

Description

Dynamic print-related options returned by the dynmaicOptions query. Values are aggregated from product attribute data and normalised to lowercase underscore keys via regex. These cover the full range of print configuration options used across all connected suppliers.

Fields
Field Name Description
brand – [OptionItem!]! Brand options extracted from print product data.
size – [OptionItem!]! Size/format options (e.g. A4, A5, 90x50mm).
shape – [OptionItem!]! Product shape options (e.g. rectangle, round, oval).
stock – [OptionItem!]! Paper/material stock options (e.g. 14pt Gloss, 100lb Uncoated).
colorspec – [OptionItem!]! Ink colour specification options (e.g. 4/4 Full Colour, 1/0 Black).
coating – [OptionItem!]! Surface coating options (e.g. Gloss AQ, Matte, UV).
spot_uv_sides – [OptionItem!]! Spot UV application side options.
scoring_options – [OptionItem!]! Scoring and creasing options.
drill_hole – [OptionItem!]! Drill hole options.
bundling_service – [OptionItem!]! Bundling service options.
shrink_wrapping – [OptionItem!]! Shrink-wrapping options.
lamination – [OptionItem!]! Lamination type options (e.g. Soft Touch, Gloss Film, Matte).
foil_color – [OptionItem!]! Foil stamping colour options.
second_raised_color – [OptionItem!]! Second raised colour options.
raised_foil_side – [OptionItem!]! Raised foil application side options.
raised_spot_uv_height – [OptionItem!]! Raised spot UV height options.
raised_spot_uv_side – [OptionItem!]! Raised spot UV application side options.
radius_of_corners – [OptionItem!]! Corner radius options for rounded-corner products.
business_card_box_size – [OptionItem!]! Business card box size options.
product_color – [OptionItem!]! Product colour options (for print products).
product_material – [OptionItem!]! Product material options (for print products).
score_and_fold – [OptionItem!]! Score and fold style options.
eddm_service_option – [OptionItem!]! EDDM (Every Door Direct Mail) service options.
rider_pins – [OptionItem!]! Rider pin quantity options.
branding – [OptionItem!]! Branding and imprint method options.
perforation – [OptionItem!]! Perforation options.
cover_coating – [OptionItem!]! Cover coating options.
product_style – [OptionItem!]! Product style and format options.
cover_stock – [OptionItem!]! Cover stock weight and type options.
numbering – [OptionItem!]! Numbering service options.
page_count – [OptionItem!]! Page count options for multi-page products.
sheets_per_pad – [OptionItem!]! Sheets per pad options for notepad products.
wraparound_cover – [OptionItem!]! Wraparound cover options.
hardware – [OptionItem!]! Hardware and fastener component options.
catalog_version – [OptionItem!]! Catalogue version and edition options.
product_orientation – [OptionItem!]! Product orientation options (portrait, landscape).
mailing_service – [OptionItem!]! Mailing service level options.
number_of_tabs – [OptionItem!]! Number of index tab options.
binding_type – [OptionItem!]! Binding type options (e.g. saddle stitch, perfect bind, coil).
binding_edge – [OptionItem!]! Binding edge options (e.g. left, top).
folding_options – [OptionItem!]! Folding style options (e.g. Half Fold, Tri-Fold, Z-Fold).
button_backing_options – [OptionItem!]! Button backing style options.
button_shape_options – [OptionItem!]! Button shape options.
shirt_size_multi_picker – [OptionItem!]! Shirt size multi-select picker options.
unwind_options – [OptionItem!]! Label unwind direction options.
fastener_options – [OptionItem!]! Fastener type options.
handle_options – [OptionItem!]! Handle style options (e.g. for bags).
die_cut_options – [OptionItem!]! Die-cut shape options.
sleeve – [OptionItem!]! Sleeve style options.
white_mask_front – [OptionItem!]! White mask front print options.
mount_position – [OptionItem!]! Mount position options.
pockets – [OptionItem!]! Pocket and slip options.
business_card_slit – [OptionItem!]! Business card slit options.
flap_style – [OptionItem!]! Flap style options for envelopes and folders.
blank_envelopes – [OptionItem!]! Blank envelope inclusion options.
cd_slit – [OptionItem!]! CD slit and slot options.
edge_color – [OptionItem!]! Edge colour options.
qty_per_book – [OptionItem!]! Quantity-per-book options.
blank_second_sheets – [OptionItem!]! Blank second sheet inclusion options.
slits – [OptionItem!]! Slit and perforation line options.
variable_data – [OptionItem!]! Variable data printing options.
opening_side – [OptionItem!]! Document opening side options.
window_options – [OptionItem!]! Window cut-out options for envelopes or folders.
clear_case – [OptionItem!]! Clear and transparent case options.
edge_join_options – [OptionItem!]! Edge join and binding method options.
Example
{
  "brand": [{"key": "ecodrink", "value": "EcoDrink"}],
  "size": [{"key": "medium", "value": "Medium"}],
  "shape": [{"key": "rectangle", "value": "Rectangle"}],
  "stock": [{"key": "14pt_gloss", "value": "14pt Gloss"}],
  "colorspec": [{"key": "4_4_full_color", "value": "4/4 Full Colour"}],
  "coating": [{"key": "gloss_aq", "value": "Gloss AQ"}],
  "spot_uv_sides": [],
  "scoring_options": [],
  "drill_hole": [],
  "bundling_service": [],
  "shrink_wrapping": [],
  "lamination": [{"key": "soft_touch", "value": "Soft Touch"}],
  "foil_color": [{"key": "gold", "value": "Gold"}],
  "second_raised_color": [],
  "raised_foil_side": [],
  "raised_spot_uv_height": [],
  "raised_spot_uv_side": [],
  "radius_of_corners": [],
  "business_card_box_size": [],
  "product_color": [],
  "product_material": [],
  "score_and_fold": [],
  "eddm_service_option": [],
  "rider_pins": [],
  "branding": [],
  "perforation": [],
  "cover_coating": [],
  "product_style": [],
  "cover_stock": [],
  "numbering": [],
  "page_count": [],
  "sheets_per_pad": [],
  "wraparound_cover": [],
  "hardware": [],
  "catalog_version": [],
  "product_orientation": [{"key": "portrait", "value": "Portrait"}],
  "mailing_service": [{"key": "standard", "value": "Standard"}],
  "number_of_tabs": [],
  "binding_type": [{"key": "saddle_stitch", "value": "Saddle Stitch"}],
  "binding_edge": [],
  "folding_options": [{"key": "half_fold", "value": "Half Fold"}],
  "button_backing_options": [],
  "button_shape_options": [],
  "shirt_size_multi_picker": [],
  "unwind_options": [],
  "fastener_options": [],
  "handle_options": [],
  "die_cut_options": [],
  "sleeve": [],
  "white_mask_front": [],
  "mount_position": [],
  "pockets": [],
  "business_card_slit": [],
  "flap_style": [],
  "blank_envelopes": [],
  "cd_slit": [],
  "edge_color": [],
  "qty_per_book": [],
  "blank_second_sheets": [],
  "slits": [],
  "variable_data": [{"key": "yes", "value": "Yes"}],
  "opening_side": [],
  "window_options": [],
  "clear_case": [],
  "edge_join_options": []
}