Premium widget with advanced features
vendorId: type: string description: Vendor ObjectId example: 507f1f77bcf86cd799439011 productType: type: string maxLength: 255 description: Product type/category example: Widgets tags: type: array items: type: string maxLength: 255 maxItems: 250 description: Product tags example: - premium - bestseller - new status: type: string enum: - ACTIVE - DRAFT - ARCHIVED description: Product status example: DRAFT handle: type: string maxLength: 255 description: URL-friendly product handle example: widget-pro-deluxe options: type: array items: $ref: '#/components/schemas/ProductOptionInput' maxItems: 3 description: Product options (e.g., Color, Size) variants: type: array items: $ref: '#/components/schemas/ProductVariantInput' maxItems: 100 description: Product variants metafields: type: array items: $ref: '#/components/schemas/ProductMetafieldInput' description: Custom metafields seo: $ref: '#/components/schemas/SeoInput' description: SEO settings category: type: string description: Product category/collection example: Electronics templateSuffix: type: string description: Custom template suffix images: type: array maxItems: 250 description: Product images (replaces existing on update) items: type: object required: - src properties: src: type: string format: uri example: https://cdn.example.com/widget.jpg altText: type: string maxLength: 255 medias: type: array maxItems: 250 description: >- Digital files for download after purchase. On update, omit to keep existing files. items: type: object required: - file - name properties: file: type: string format: uri description: https URL of the uploaded file name: type: string minLength: 1 size: type: integer minimum: 0 type: type: string maxLength: 255 variant: type: string maxLength: 255 variantId: type: string maxLength: 255 assignedTo: type: string maxLength: 255 vendor: type: string description: Vendor display name on the Shopify product brandName: type: string description: Brand name collections: type: array items: type: string minLength: 1 description: Shopify collection ids to add the new product to. maxItems: 250 isDigital: type: boolean description: Marks the product as a digital product (use with medias) additionalProperties: false Product: type: object properties: _id: type: string description: Product ObjectId example: 507f1f77bcf86cd799439013 title: type: string description: Product title example: Widget Pro handle: type: string description: URL-friendly product handle example: widget-pro status: type: string enum: - active - draft - archived description: Product status example: active vendorId: type: string description: Associated vendor ObjectId example: 507f1f77bcf86cd799439011 variants: type: array items: type: object properties: _id: type: string description: Mongo subdocument id id: type: string description: Shopify variant id (numeric) once synced admin_graphql_api_id: type: string description: Shopify variant GID once synced title: type: string description: Variant title (e.g. "Red / Large") sku: type: string price: type: number inventory: type: number optionValues: type: array description: Resolved option name/value pairs items: type: object properties: name: type: string value: type: string selectedOptions: type: array description: Shopify-shaped option name/value pairs items: type: object properties: name: type: string value: type: string inventoryQuantities: type: array description: Per-location stock for this variant items: type: object properties: locationId: type: string name: type: string quantity: type: integer availableQuantity: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object required: - success - error properties: success: type: boolean enum: - false description: Indicates the request failed error: type: object required: - message properties: message: type: string description: Human-readable error message example: Resource not found code: type: string description: >- Stable machine-readable error code. The frontend uses this as its localisation key (e.g. errors.api.). Server errors
always report INTERNAL_SERVER_ERROR.
example: NOT_FOUND
errorId:
type: string
description: >-
Correlation id for support/log lookup. Present on opaque 5xx
responses so a user can quote a reference for the underlying
(server-side logged) error.
example: err_1783365360839_j281w7b
details:
type: object
description: >-
Additional client-error context (e.g. field-level validation
errors). Never populated for server errors.
ProductOptionInput:
type: object
required:
- name
- values
properties:
name:
type: string
description: Option name (e.g., Color, Size)
example: Color
values:
type: array
items:
type: string
description: Possible values for this option
example:
- Red
- Blue
- Green
ProductVariantInput:
type: object
properties:
optionValues:
type: array
items:
type: object
properties:
name:
type: string
example: Color
value:
type: string
example: Red
description: Option values for this variant
price:
type: string
pattern: ^\d+(\.\d{1,2})?$
description: Variant price
example: '29.99'
compareAtPrice:
type: string
pattern: ^\d+(\.\d{1,2})?$
description: Original/compare price
example: '39.99'
sku:
type: string
maxLength: 255
description: Stock keeping unit
example: WIDGET-RED-L
barcode:
type: string
maxLength: 255
description: EAN/barcode
inventoryQuantity:
type: integer
minimum: -1000000000
maximum: 1000000000
description: >-
Inventory quantity at location. May be negative for oversold or
backordered stock, which only actually sells when the variant
inventoryPolicy is CONTINUE.
example: 100
locationId:
type: string
description: Shopify location ID (required if inventoryQuantity is provided)
example: gid://shopify/Location/123456
requiresShipping:
type: boolean
description: Whether variant requires shipping
example: true
taxable:
type: boolean
description: Whether variant is taxable
example: true
inventoryPolicy:
type: string
enum:
- DENY
- CONTINUE
description: Behavior when out of stock
example: DENY
ProductMetafieldInput:
type: object
required:
- namespace
- key
- value
properties:
namespace:
type: string
description: Metafield namespace
example: custom
key:
type: string
description: Metafield key
example: color_family
value:
type: string
description: Metafield value
example: red
type:
type: string
description: Metafield type
example: single_line_text_field
description:
type: string
description: Metafield description
SeoInput:
type: object
properties:
title:
type: string
maxLength: 255
description: SEO title tag
example: Premium Widget - Best Price Online
description:
type: string
maxLength: 320
description: SEO meta description
example: >-
High-quality widgets at competitive prices. Free shipping on orders
over $50.
securitySchemes:
bearerAuth:
type: apiKey
in: header
name: x-access-token
description: >-
JWT minted from a merchant API key (`mk_live_…`) by POST /authenticate.
Send the token value directly, with no "Bearer" prefix. Tokens last 14
days and can be renewed at POST /refresh-token; revoking the key refuses
the next request made with any token minted from it.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.