Products
A basic unit of ecommerce setup representing physical or digital goods. A single product may have many variations depending upon multiple attributes associated to it like a color, size etc. Mainly there are two kinds of products, a basic product without any variation and a product with multiple variations.
Product Object¶
Below is the json representation of the product object, followed by a data table
Product Object
{
"category": null,
"collections": [],
"content": {
"description": "Slim Metallic Body. Lithium Polymer Power-bank.",
"summary": ""
},
"created_at": "2022-01-03T16:24:00.113Z",
"id": "77dfb23f-4f79-45ca-baaf-3af5efddfcfd",
"kind": "with-variants",
"metadata": {
"google_product_category": "Electronics > Communications > Telephony > Mobile Phone Accessories"
},
"name": "10000 mAh Power Bank",
"slug": "10000-mah-power-bank",
"status": "published",
"tags": [],
"updated_at": "2022-12-26T10:26:33.673Z",
"variant_attributes": [
{
"kind": "Color",
"properties": [
"champagne",
"gun metal"
]
}
],
"variants": []
}
Fields¶
All Fields¶
| Field | Data Type | Description |
|---|---|---|
category | object | Category object. The category to which this product belongs to, see category section in organization page. Relation: Product can belong to only one category |
collections | object array | Array of collection objects. See collection section in organization.page. Relation: Product can belong to multiple collections |
content | object | Summary and description of the product. See below content section for more details |
created_at | string | UTC timestamp at which the product was created. |
id | string | UUID of the product. |
kind | string | Kind of the product. Possible values are basic and with-variants |
metadata | object | An object containing various metadata fields required for seo and marketing. See metadata section for more details. |
name | string | Name of the product. |
slug | string | Unique url fragment used for displaying the product page in the frontend. If the frontend application uses a different url fragment for the product page, its important to add a necessary redirect. |
status | string | Status of the product. See status section in this page for more details. |
tags | string array | Array of strings. Tags associated with a product. |
updated_at | string | UTC timestamp at which the product was last modified. |
variant_attributes | object array | Array of variant_attribute object. See below variant_attribute object for more details. |
variants | object array | Array of variant object. See variants page for more details. Relation: Product can have many variants |
Objects¶
Content Object
| Field | Data Type | Description |
|---|---|---|
summary | string | Short brief of the product. |
description | string | Full details of the product. Generally longer and more detailed than a summary. |
Variant Attribute Object
Metadata Object
Metadata object captures various feilds related to seo and marketing across webpages, google and facebook.
| Field | Data Type | Description |
|---|---|---|
meta_title | string | Title for storefront <meta> tag in product page. |
meta_keywords | string | Keywords for storefront <meta> tag in product page. |
meta_description | string | Description for storefront <meta> tag in product page. |
google_product_category | string | Product category for this product. Needed for GTM and Google Merchant Center integration. |
google_catalog_url | string | Catalog url for this product. Needed for GTM and Google Merchant Center integration. |
facebook_product_category | string | Product category for this product. Needed for facebook catalog and ads integration. |
facebook_catalog_url | string | Catalog url for this product. Needed for facebook catalog and ads integration. |
Status State Machine¶
status field represents whether a product is sellable on storefront. When a product is in published state it can be sold, while draft is the initial state of the product during which multiple edits can be made. An archived product can be considered as a decommissioned product and it cannot be sold on the storefront anymore.
Possible values: draft, published and archived. Below diagram shows possible transitions on the product status.
graph LR
A[draft] --> |publish| B[published];
A[draft] --> |archive| C[archived];
B --> |archive| C;
C --> |publish| B;API¶
List Products¶
GET /api/platform/v1/products
The result set is paginated and can be controlled by various query parameters
Query Params
| Field | Data Type | Description |
|---|---|---|
page | integer | Page number of the result set. Values start from 1. |
per_page | integer | How many items should be present in a given page. |
search | string | Search string to search products. |
sort_by[field_name] | string | Sort result set based on the field_name of the product. Field names can be any primitive field mentioned in the product object. Possible values: asc and desc |
status | string | See status for details and possible values |
curl command
Response Body
This api responds with array of product objects.
Create Product¶
POST /api/platform/v1/products
Only name is required to get started with creating a product. Later using update api more details can be added to the product, it can also be upgraded to a product with variants with variants attributes api.
Request Body
Same as product object except depedent associated object fields.
curl command
Response Body
response json data object is product object
{
"status": "success",
"data": {
"id": "9d444ac8-92bb-4b56-a9cd-8b8866c05fb0",
"name": "Cool T Shirt",
"slug": "cool-t-shirt",
"status": "draft",
"kind": "basic",
"variant_attributes": null,
"content": null,
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T05:21:01.092Z",
"updated_at": "2023-04-12T05:21:01.108Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tags": [],
"collections": [],
"variants": [{
"id": "89cf4e66-f8b7-4048-9fff-d114897561ed",
"product_id": "9d444ac8-92bb-4b56-a9cd-8b8866c05fb0",
"position": 0,
"sku": null,
"name": "Default Variant",
"status": "active",
"attribute_values": null,
"price_units": null,
"list_price_units": null,
"is_default": true,
"is_backorderable": false,
"properties": null,
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T05:21:01.103Z",
"updated_at": "2023-04-12T05:21:01.103Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tax_number": null,
"store_tax_code_id": null,
"description": null,
"gtin_code": null,
"stock_items": [],
"media": []
}]
}
}
Get Product¶
GET /api/platform/v1/products/{id}
curl command
Response Body
response json data object is product object
{
"status": "success",
"data": {
"id": "9d444ac8-92bb-4b56-a9cd-8b8866c05fb0",
"name": "Cool T Shirt",
"slug": "cool-t-shirt",
"status": "draft",
"kind": "basic",
"variant_attributes": null,
"content": null,
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T05:21:01.092Z",
"updated_at": "2023-04-12T05:21:01.108Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tags": [],
"collections": [],
"variants": [{
"id": "89cf4e66-f8b7-4048-9fff-d114897561ed",
"product_id": "9d444ac8-92bb-4b56-a9cd-8b8866c05fb0",
"position": 0,
"sku": null,
"name": "Default Variant",
"status": "active",
"attribute_values": null,
"price_units": null,
"list_price_units": null,
"is_default": true,
"is_backorderable": false,
"properties": null,
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T05:21:01.103Z",
"updated_at": "2023-04-12T05:21:01.103Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tax_number": null,
"store_tax_code_id": null,
"description": null,
"gtin_code": null,
"stock_items": [],
"media": []
}]
}
}
Update Product¶
PATCH /api/platform/v1/products/{id}
Request Body
All the fields in the product object can be updated except for those that are related objects.
curl command
Response Body
response json data object is product object
{
"status": "success",
"data": {
"id": "9d444ac8-92bb-4b56-a9cd-8b8866c05fb0",
"name": "Summer T Shirt",
"slug": "cool-t-shirt",
"status": "draft",
"kind": "with-variants",
"variant_attributes": [{
"kind": "color",
"properties": ["red"]
}],
"content": null,
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T05:21:01.092Z",
"updated_at": "2023-04-12T09:26:47.911Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tags": [],
"collections": [],
"variants": [{
"id": "89cf4e66-f8b7-4048-9fff-d114897561ed",
"product_id": "9d444ac8-92bb-4b56-a9cd-8b8866c05fb0",
"position": 0,
"sku": "COOLT",
"name": "color: red",
"status": "inactive",
"attribute_values": [{
"kind": "color",
"value": "red"
}],
"price_units": null,
"list_price_units": null,
"is_default": true,
"is_backorderable": false,
"properties": null,
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T05:21:01.103Z",
"updated_at": "2023-04-12T06:09:25.139Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tax_number": null,
"store_tax_code_id": null,
"description": null,
"gtin_code": null,
"stock_items": [],
"media": []
}]
}
}
Delete Product¶
DELETE /api/platform/v1/products/{id}
If a product has no dependent orders, it can be deleted. If it has existing orders associated with it, it can only be archived.
curl command
Response Body
response json data object is product object
{
"status": "success",
"data": {
"id": "9d444ac8-92bb-4b56-a9cd-8b8866c05fb0",
"name": "Cool T Shirt",
"slug": "cool-t-shirt",
"status": "draft",
"kind": "basic",
"variant_attributes": null,
"content": null,
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T05:21:01.092Z",
"updated_at": "2023-04-12T05:21:01.108Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tags": [],
"collections": [],
"variants": [{
"id": "89cf4e66-f8b7-4048-9fff-d114897561ed",
"product_id": "9d444ac8-92bb-4b56-a9cd-8b8866c05fb0",
"position": 0,
"sku": null,
"name": "Default Variant",
"status": "active",
"attribute_values": null,
"price_units": null,
"list_price_units": null,
"is_default": true,
"is_backorderable": false,
"properties": null,
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T05:21:01.103Z",
"updated_at": "2023-04-12T05:21:01.103Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tax_number": null,
"store_tax_code_id": null,
"description": null,
"gtin_code": null,
"stock_items": [],
"media": []
}]
}
}
Transition Product Status¶
POST /api/platform/v1/products/{id}/transition
This api should be used to make state transitions as discussed in status section.
Request Body
| Field | Data Type | Description | Required |
|---|---|---|---|
name | string | Name of the transition. One of publish or archive |
curl command
Response Body
response json data object is product object
{
"status": "success",
"data": {
"id": "64ea2096-a004-4967-b856-cca6f5ad9dc2",
"name": "Cool T Shirt",
"slug": "cool-t-shirt",
"status": "archived",
"kind": "basic",
"variant_attributes": null,
"content": {
"summary": "",
"description": ""
},
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T11:09:43.386Z",
"updated_at": "2023-04-12T11:45:41.339Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tags": [],
"collections": [],
"variants": [{
"id": "89d8433a-9ccb-4cd6-b1e0-b1bd844ceafa",
"product_id": "64ea2096-a004-4967-b856-cca6f5ad9dc2",
"position": 0,
"sku": null,
"name": "Default Variant",
"status": "inactive",
"attribute_values": null,
"price_units": null,
"list_price_units": null,
"is_default": true,
"is_backorderable": false,
"properties": null,
"metadata": null,
"extradata": null,
"created_at": "2023-04-12T11:09:43.409Z",
"updated_at": "2023-04-12T11:12:50.555Z",
"account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
"tax_number": null,
"store_tax_code_id": null,
"description": null,
"gtin_code": null,
"stock_items": [],
"media": []
}]
}
}
// TODO