Create a product

POST/v1/api/store/{team_slug}/product

v1Operation ID v1_public_products_store

Creates one of your own products and returns it.

• A simple product (type: simple) is one item with one price: a mug, a setup fee you sell as a product. On sales order lines it is a user_simple line.
• A variant product (type: variant) comes in sizes, colors or both (variant_type). Send the option lists (size_data, color_data) and one entry in product for each size and color combination you sell. Each combination becomes a variant with its own price; on sales order lines it is a db_variant line that names the variant id.

Creating a product creates no stock. Amounts here use thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

Permission

Needs the Manage Products permission at the level that can create products.

Business rules

• Send prices as a whole number of thousandths: 12500 is 12.50.
• A variant product needs variant_type and at least one entry in product; each entry needs default_price, plus size_id and size_label for sizes and color_id, color_label and color_hex for colors.
• On create, the entries in product are not checked against each other or against size_data and color_data: send each combination once, with the ids and names your lists use. Adding variants later (Add a variant) does check both.
• Titles need not be unique.
• dimension_x, dimension_y and dimension_z are saved but not returned by this answer or the products list.

Path parameters

• team_slugstringrequired

  Your team slug, shown as Team ID next to your API key in Profile.

  • Example your-team

Request body

application/json, required.

What kind of product?

Send one of these 2 bodies. Picked by type.

simple

Simple product

variant

Variant product

Simple productsimpleVariant productvariant

Simple product

One item with one price.

• typestringrequired
  • Always "simple"
• default_priceintegerrequired

  Required. Send a whole number of thousandths: 12500 is 12.50.

• titlestringrequired

  Required on create. The product name shown on orders.

• barcodestring

  The product's barcode. Saved as sent.

• brandstring

  The product's brand.

• descriptionstring

  A description of the product.

• dimension_xnumber
• dimension_ynumber
• dimension_znumber
• price_datamap of objects

  Prices for pricing groups, keyed by pricing group id: {"<pricing group id>": {"price": 11000}}. A line priced with that group uses this price instead of default_price. Send a whole number of thousandths: 11000 is 11.00.

  Fields of each item (1)

  • priceintegerrequired

    Send a whole number of thousandths: 11000 is 11.00.

• supplier_idstring

  The supplier's code for the product.

• taxableboolean

  Whether sales tax applies to it.

• vendor_idstring

  The vendor you buy it from.

• weightnumber

  The product's weight. Simple products only.

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/product' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "brand": "Northwind",    "default_price": 12500,    "supplier_id": "MUG-11",    "taxable": true,    "title": "Enamel mug",    "type": "simple"  }'

Variant product

Sizes, colors or both, one variant per combination.

• typestringrequired
  • Always "variant"
• productarray of objectsrequired

  One entry per size and color combination you sell.

  • At least 1 item
  Fields of each item (13)

  • default_priceintegerrequired

    Required. This variant's selling price. Send a whole number of thousandths: 9000 is 9.00.

  • barcodestring

    Saved as sent; not checked.

  • color_hexstring

    For products with colors, such as #1F2937.

  • color_idstring

    For products with colors: your id for the color. The rule depends on the case:

    • When creating a product: use an id from color_data.
    • When adding a variant to a color-only product: send a new id to add a color. Reusing an existing id is a duplicate (422).
    • When adding a variant to a size-and-color product: reuse an id from color_data to add a new size in an existing color, or send a new id to add a color.
  • color_labelstring

    For products with colors. For a color the product already has, its current name is kept.

  • enableboolean

    Saved as sent (default true); returned as enable. Nothing enforces it: phase a variant out to stop selling it.

  • price_datamap of objects

    Prices for pricing groups, keyed by pricing group id: {"<pricing group id>": {"price": 11000}}. A line priced with that group uses this price instead of default_price. Send a whole number of thousandths: 11000 is 11.00.

    Fields of each item (1)

    • priceintegerrequired

      Send a whole number of thousandths: 11000 is 11.00.

  • size_idstring

    For products with sizes: your id for the size. The rule depends on the case:

    • When creating a product: use an id from size_data.
    • When adding a variant to a size-only product: send a new id to add a size. Reusing an existing id is a duplicate (422).
    • When adding a variant to a size-and-color product: reuse an id from size_data to add a new color for an existing size, or send a new id to add a size.
  • size_labelstring

    For products with sizes. For a size the product already has, its current name is kept.

  • supplier_idstring

    The supplier's code for this variant.

  • track_inventoryboolean

    Saved as sent (default true); not checked.

  • vendor_idstring
  • weightnumber

    The variant's weight.

• titlestringrequired

  Required on create. The product name shown on orders.

• variant_typestringrequired

  Which options the product has.

  • One of: "size", "color", "size_color"
• barcodestring

  The product's barcode. Saved as sent.

• brandstring

  The product's brand.

• color_dataarray of objects

  Required for color and size_color: the colors.

  Fields of each item (3)

  • hexstringrequired

    Such as #1F2937.

  • idstringrequired

    Your id for the color. It never changes.

  • labelstringrequired
• descriptionstring

  A description of the product.

• dimension_xnumber
• dimension_ynumber
• dimension_znumber
• size_dataarray of objects

  Required for size and size_color: the sizes, in display order.

  Fields of each item (2)

  • idstringrequired

    Your id for the size, such as M. It never changes; the label can.

  • labelstringrequired

    The size name shown on orders.

• supplier_idstring

  The supplier's code for the product.

• taxableboolean

  Whether sales tax applies to it.

• vendor_idstring

  The vendor you buy it from.

• weightnumber

  The product's weight. Simple products only.

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/product' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "brand": "Northwind",    "color_data": [      {        "hex": "#000000",        "id": "black",        "label": "Black"      }    ],    "product": [      {        "color_hex": "#000000",        "color_id": "black",        "color_label": "Black",        "default_price": 9000,        "size_id": "S",        "size_label": "S"      },      {        "color_hex": "#000000",        "color_id": "black",        "color_label": "Black",        "default_price": 9000,        "size_id": "M",        "size_label": "M"      }    ],    "size_data": [      {        "id": "S",        "label": "S"      },      {        "id": "M",        "label": "M"      }    ],    "title": "Classic Tee",    "type": "variant",    "variant_type": "size_color"  }'

Response

200Successful response.

• dataobjectrequired

  One of, picked by type:

  Simple productsimple

  • typestringrequired
    • Always "simple"
  • default_priceinteger | number | string | nullrequired

    The selling price. Null when not set. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

  • idstringrequired
  • phased_outbooleanrequired
  • titlestring | nullrequired
  • trashedbooleanrequired
  • barcodestring | null
  • brandstring | null
  • color_dataarray of any
  • deleted_atstring (date-time) | null
  • deleted_byobject | null

    Who did it, as {id, name}; null when on sale or nobody was recorded.

    Child fields (2)

    • idstring
    • namestring
  • deleted_variant_countnull
  • descriptionstring | null
  • enableboolean
  • phased_out_atstring (date-time) | null
  • phased_out_byobject | null

    Who did it, as {id, name}; null when on sale or nobody was recorded.

    Child fields (2)

    • idstring
    • namestring
  • phased_out_variant_countnull
  • price_dataobject | array

    Prices for pricing groups, as saved: keyed by the pricing group's internal number (not its hash id), each {"price": <thousandths>}. An empty list [] when there are none.

  • size_dataarray of any
  • supplier_idstring | null
  • taxableboolean
  • track_inventoryboolean
  • variant_countnull
  • vendor_idstring | null
  • weightnumber | string | null

  Variant productvariant

  • typestringrequired
    • Always "variant"
  • color_dataarray of objectsrequired
    Fields of each item (3)

    • idstringrequired
    • labelstring | nullrequired
    • hexstring | null
  • idstringrequired
  • size_dataarray of objectsrequired
    Fields of each item (2)

    • idstringrequired
    • labelstring | nullrequired
  • titlestring | nullrequired
  • trashedbooleanrequired
  • variant_typestringrequired
    • One of: "size", "color", "size_color"
  • brandstring | null
  • default_priceinteger | number | string | null

    Not used for variant products: each variant has its own. Null when not set. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

  • descriptionstring | null
  • enableboolean
  • supplier_idstring | null
  • taxableboolean
  • vendor_idstring | null
• statusintegerrequired
• successbooleanrequired

Errors

• 401The API key is missing or wrong (unauthenticated).

• 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

  When

  Your role cannot create products. This 403 has a short body, {"message": "Insufficient Permission"}, with no success or error.

  Fix

  Ask a team owner to set Manage Products to "Users CAN view, update and create products".

• 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

• 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

  When

  type or title is missing, a simple product has no default_price, a variant product is missing variant_type, its option lists or product, or a price is not a number. error.code is validation_failed.

  Fix

  Fix each field named in error.fields; its keys are field paths such as contact.0.phone.

• 500A business rule refused the request (see the operation's errors), or something failed inside YoPrint. Refusals use the error envelope with a code such as action_not_allowed; an unexpected failure answers {"message": "Server Error"}. Repeating a refusal gets the same answer; after an unexpected failure, read the record back before you retry a change.

  When

  A price is not a whole number of thousandths, such as 12.5.

  Fix

  Send whole numbers: 12500 for 12.50.

Related

• POSTAdd a variant to a product/v1/api/store/{team_slug}/product/{hash_id}/variant
• PATCHUpdate a product (PATCH)/v1/api/store/{team_slug}/product/{hash_id}
• POSTAdd a line item to a sales order or quote/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/order_item

Example request: Simple product

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/product' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "brand": "Northwind",    "default_price": 12500,    "supplier_id": "MUG-11",    "taxable": true,    "title": "Enamel mug",    "type": "simple"  }'

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/product' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "brand": "Northwind",    "color_data": [      {        "hex": "#000000",        "id": "black",        "label": "Black"      }    ],    "product": [      {        "color_hex": "#000000",        "color_id": "black",        "color_label": "Black",        "default_price": 9000,        "size_id": "S",        "size_label": "S"      },      {        "color_hex": "#000000",        "color_id": "black",        "color_label": "Black",        "default_price": 9000,        "size_id": "M",        "size_label": "M"      }    ],    "size_data": [      {        "id": "S",        "label": "S"      },      {        "id": "M",        "label": "M"      }    ],    "title": "Classic Tee",    "type": "variant",    "variant_type": "size_color"  }'

Example response 200

Response

{
  "data": {
    "barcode": null,
    "brand": "Northwind",
    "color_data": [],
    "default_price": 12500,
    "deleted_at": null,
    "deleted_by": null,
    "deleted_variant_count": null,
    "description": null,
    "enable": true,
    "id": "HuUud6gosvykdV",
    "phased_out": false,
    "phased_out_at": null,
    "phased_out_by": null,
    "phased_out_variant_count": null,
    "price_data": [],
    "size_data": [],
    "supplier_id": "MUG-11",
    "taxable": true,
    "title": "Enamel mug",
    "track_inventory": true,
    "trashed": false,
    "type": "simple",
    "variant_count": null,
    "vendor_id": null,
    "weight": null
  },
  "status": 200,
  "success": true
}