Create a product

Creates a product in the specified shop. shop_id must be a shop belonging to the authenticated account.

POST/products

Authorization

AuthorizationBearer token (JWT) · headerrequired

Request body

requiredapplication/json

shop_idintegerrequired

ID of the shop (required on create)

namestringrequired

Product name.

slugstring

URL slug. Auto-generated from name if omitted.

statusstring

default: "hidden"

Allowed:visiblehiddenblocked

classstring

Product class. Defaults to Product.

default: "Product"

Allowed:ProductProductBundleSubscriptionGiftCard

descriptionstring

short_descriptionstring

deliverableboolean

Whether the product requires physical delivery. Defaults to true. Set to false for digital goods, event tickets, subscriptions, etc. Returned as is_deliverable in responses.

tracks_stockboolean

Whether stock is tracked for this product's variants.

has_prices_per_variantboolean

Required when variants have different prices. Must be true if any variant sets its own regular_price; the API returns 422 otherwise.

has_weights_per_variantboolean

Whether variants carry individual weights.

regular_priceinteger

Regular price in cents, applied to all variants (for non-bundle products). Use per-variant regular_price inside variants when has_prices_per_variant is true.

sale_priceinteger

Sale price in cents, applied to all variants.

sale_price_starts_atstring<date-time>

ISO 8601 datetime when the sale price activates.

sale_price_ends_atstring<date-time>

ISO 8601 datetime when the sale price expires.

product_type_namestring

Product type name. Created automatically if it doesn't exist.

vendor_namestring

Vendor name. Created automatically if it doesn't exist.

tagsstring[]

Tag names. Replaces all existing tags unless _policies.keep_attributes is set.

cart_quantity_multipleinteger

Enforces cart quantities to be multiples of this value.

variant_optionsobject

Names for up to 3 variant option axes (e.g. "Color", "Size").

Show properties

option1string

option2string

option3string

variantsVariantInput[]

Variant definitions. By default, variants not present in the array are removed; set _policies.keep_variants: true to preserve them.

Show properties

Array of VariantInput

idinteger

Existing variant ID. Required when updating a specific variant.

positioninteger

skustring

option1string

option2string

option3string

regular_priceinteger

Regular price in cents. Required per-variant when has_prices_per_variant is true.

sale_priceinteger

Sale price in cents.

online_stockinteger

Available online stock units.

weight_in_gramsinteger

barcode_numberstring

statusstring

Allowed:visiblehidden

available_if_no_stockboolean

Allow purchase even when stock reaches zero.

default: false

collectionsobject[]

Collections to assign the product to. Pass id to reference an existing collection, or title to create/find by name. Replaces all existing collections unless _policies.keep_collections: true.

Show properties

Array of object

idstring

Collection ID

titlestring

Collection title (used to find or create)

custom_attributesobject[]

Custom meta-field attributes.

Show properties

Array of object

namestring

valuestring

field_typestring

Allowed:stringintsplit_stringtext

field_groupstring

requiredboolean

default: false

filterableboolean

default: true

volume_discount_idinteger

Assigns an existing volume discount to this product.

relationsobject[]

Related products (e.g. "goes well with"). Replaces all existing relations unless _policies.keep_relations: true.

Show properties

Array of object

idstring

Relation ID, when updating an existing relation.

namestring

Relation name (e.g. "related", "upsell").

child_idstring

Related product ID or slug.

child_typestring

custom_variant_optionsobject

Custom variant option metadata (id/name/type) for up to 3 option axes, keyed by option1/option2/option3.

bundle_optionsobject[]

Configurable bundle option groups (customer picks items from each group). Only applies to class: ProductBundle.

Show properties

Array of object

idinteger

Bundle option ID, when updating.

namestring

min_countinteger

max_countinteger

default: 1

max_per_iteminteger

bundle_itemsobject[]

Show properties

Array of object

idinteger

Bundle item ID, when updating.

product_idinteger

variant_idinteger

Required unless variant_sku is given.

variant_skustring

Required unless variant_id is given.

unitsinteger

additional_priceinteger

Additional price in cents if this item is selected.

bundle_itemsobject[]

Fixed bundle items (always included, no customer choice). Only applies to class: ProductBundle.

Show properties

Array of object

idinteger

Bundle item ID, when updating.

product_idinteger

variant_idinteger

Required unless variant_sku is given.

variant_skustring

Required unless variant_id is given.

unitsinteger

default: 1

_policiesobject

Control update behaviour. All flags default to false (destructive replace). Set to true to preserve existing data when the corresponding field is not included in the request.

Show properties

keep_variantsboolean

Keep existing variants not listed in variants.

default: false

keep_collectionsboolean

Keep existing collection assignments not listed in collections.

default: false

keep_relationsboolean

Keep existing product relations not listed in relations.

default: false

keep_attributesboolean

Keep existing custom attributes not listed in custom_attributes.

default: false

ensure_uniquestring

If set, the product is not created when another product already has the same value for this field (returns 409 instead).

Allowed:titleslug

Responses

201

Product created

_linksHalLinks

idinteger

namestring

Product display name.

slugstring

class_namestring

statusstring

Allowed:visiblehidden

descriptionstring

short_descriptionstring

is_bundleboolean

is_deliverableboolean

has_optionsboolean

tagsstring[]

currency_codestring

bundle_price_modestring

Allowed:pricesum

bundle_discountnumber

regular_pricenumber

In cents

pricenumber

Effective price in cents

sale_pricenumber

In cents

sale_price_starts_atstring<date-time>

sale_price_ends_atstring<date-time>

has_multiple_pricesboolean

discount_percentagenumber

safety_stockinteger

availableboolean

stockinteger

Current stock

online_stockinteger

all_stockinteger

Stock across all locations

vendorstring

variant_optionsobject[]

Show properties

Array of object

namestring

valuestring

global_tagsstring[]

stocksobject

stocks_per_locationobject

cart_max_quantityinteger

cart_quantity_multipleinteger

list_pricesobject[]

Show properties

Array of object

price_list_idinteger

pricenumber

created_onstring<date-time>

updated_onstring<date-time>

403

Not authorized to create products in this shop

422

Validation error or missing shop_id

_embeddedobject

Show properties

errorsobject[]

Show properties

Array of object

fieldstring

messagesstring[]

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Bodyapplication/json

Request body

Request

curl -s -X POST \
  -H "Authorization: Bearer $BOLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shop_id":1,"name":"Organic Cotton Tee","status":"visible","sale_price":2999,"regular_price":3999}' \
  "https://api.onbolder.com/v2/products"

curl -X POST 'https://api.onbolder.com/v2/products' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "shop_id": 1,
  "name": "Organic Cotton Tee",
  "slug": "organic-cotton-tee",
  "status": "visible",
  "sale_price": 2999,
  "regular_price": 3999
}'

const response = await fetch("https://api.onbolder.com/v2/products", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"shop_id\": 1,\n  \"name\": \"Organic Cotton Tee\",\n  \"slug\": \"organic-cotton-tee\",\n  \"status\": \"visible\",\n  \"sale_price\": 2999,\n  \"regular_price\": 3999\n}"
});

import requests

response = requests.post(
    "https://api.onbolder.com/v2/products",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"shop_id\": 1,\n  \"name\": \"Organic Cotton Tee\",\n  \"slug\": \"organic-cotton-tee\",\n  \"status\": \"visible\",\n  \"sale_price\": 2999,\n  \"regular_price\": 3999\n}",
)

Response

{
  "id": 103,
  "name": "Organic Cotton Tee",
  "slug": "organic-cotton-tee",
  "status": "visible",
  "price": 2999,
  "regular_price": 3999,
  "currency_code": "USD",
  "created_on": "2024-06-20T14:22:00Z",
  "_links": {
    "self": {
      "href": "https://api.onbolder.com/v2/products/103"
    },
    "products:update": {
      "href": "https://api.onbolder.com/v2/products/103",
      "method": "put"
    },
    "products:delete": {
      "href": "https://api.onbolder.com/v2/products/103",
      "method": "delete"
    }
  }
}

{
  "_embedded": {
    "errors": [
      {
        "field": "string",
        "messages": [
          "string"
        ]
      }
    ]
  }
}