Products

Products are the foundation of your commerce catalog—each product represents something you sell, whether physical goods requiring shipping, digital downloads, or intangible services. The Products API gives you precise control over every aspect of your offerings: pricing across currencies, rich media galleries, custom attributes for variants, shipping dimensions, tax classification, and arbitrary metadata for your own business logic.

The product object

A product object contains everything needed to list, sell, and fulfill an item: core identification fields (name, description, reference), pricing information, categorization for reporting and filtering, media assets for customer-facing displays, physical dimensions for shipping calculations, and extensible custom data for application-specific needs. Products belong to a specific application and can be referenced in order line items.

Properties

Name
about
Type
string
Description
Full product description with marketing copy, features, specifications, and any details customers need before purchase. Can include multiple paragraphs. Shown on product pages and detailed order views.
attributesobjectProduct variants or configurable options that customers can select.Click or tap to expand
- Name
  name
  Type
  string
  Description
  Attribute name (e.g., "Size", "Color", "Material"). Between 1-100 characters.
- Name
  value
  Type
  string
  Description
  Attribute value (e.g., "Medium", "#FF0000", "Cotton"). Between 1-500 characters.
Name
archived_at
Type
timestamp|null
Description
When this product was archived (soft-deleted). null for active products. Archived products don't appear in active listings but remain in historical orders. Archiving is reversible—setting this to null reactivates the product.
Name
category
Type
string
Description
Product category for grouping, filtering, and reporting. Categories are application-specific and reflect your business structure. Examples: clothing, software, consulting, electronics. Max 100 characters.
Name
created_at
Type
timestamp
Description
When this product was first created. Set automatically and never changes. Use for audit trails and chronological sorting.
Name
custom_data
Type
object
Description
Arbitrary key-value pairs for application-specific metadata. Any string key with string value. Max 50 keys, each key/value under 500 characters. Store custom attributes, integration IDs, or business-specific data.
Name
description
Type
string
Description
Short description or tagline for the product. Appears in condensed views like order line items. Keep under 100 characters for best display. Max 200 characters.
dimensionsobjectProduct dimensions for shipping calculations (physical products) or file sizes (digital products).Click or tap to expand
- Name
  height
  Type
  number
  Description
  Height in unit specified by unit_dimension.
- Name
  length
  Type
  number
  Description
  Length in unit specified by unit_dimension.
- Name
  weight
  Type
  number
  Description
  Weight in unit specified by unit_dimension.
- Name
  width
  Type
  number
  Description
  Width in unit specified by unit_dimension.
Name
id
Type
string
Description
Unique identifier for this product. Generated automatically during creation. Used for lookups, order line items, and inventory tracking.
mediaobjectProduct media assets displayed to customers during browsing and checkout.Click or tap to expand
- Name
  brand_logo
  Type
  string
  Description
  File ID of the product brand's logo. Used when product has distinct brand identity. Should have transparent background. File must be uploaded to files.zebo.dev first.
- Name
  demo_video
  Type
  string
  Description
  File ID of instructional video showing product in use, explaining functionality, or providing setup instructions. Educational focus. File must be uploaded to files.zebo.dev first.
- Name
  downloads
  Type
  array
  Description
  Array of file IDs for downloadable files: PDF manuals, instruction guides, warranty documents, digital assets, templates. Each file must be uploaded to files.zebo.dev first.
- Name
  gallery
  Type
  array
  Description
  Array of file IDs for additional product images showing different angles, details, contexts, or variations. Order matters—displayed in sequence. Each file must be uploaded to files.zebo.dev first.
- Name
  hero_image
  Type
  string
  Description
  File ID of primary product image displayed prominently on product pages, search results, and checkout. High-quality image on clean background. File must be uploaded to files.zebo.dev first.
- Name
  infographic
  Type
  string
  Description
  File ID of educational image explaining features, specifications, dimensions, or usage. Often includes text overlays, diagrams, size charts. File must be uploaded to files.zebo.dev first.
- Name
  promo_video
  Type
  string
  Description
  File ID of marketing video showcasing appeal, lifestyle context, or brand story. Typically 30-90 seconds. File must be uploaded to files.zebo.dev first.
- Name
  thumbnail
  Type
  string
  Description
  File ID of small, optimized image for cart previews, order summaries, receipts, mobile views. Square or 4:3 aspect ratio. File must be uploaded to files.zebo.dev first.
- Name
  web_page_url
  Type
  string
  Description
  Canonical URL of product's dedicated landing page with detailed information, reviews, and purchase options.
Name
name
Type
string
Description
Customer-facing product title shown in order summaries, invoices, and receipts. Keep concise and descriptive. Between 1-100 characters. Examples: Premium Cotton T-Shirt, Annual Subscription, Video Editing Service.
Name
reference
Type
string
Description
Optional external reference or SKU from your internal systems. Map products to inventory management, ERP, or catalog system. Examples: SKU-12345, PROD-SHIRT-BLUE-M, SERVICE-CONSULTING-HR.
shipmentobjectDelivery method for the product. Only applicable for physical and digital products (null for services).Click or tap to expand
- Name
  type
  Type
  string
  Description
  Shipment type: delivery for physical products with carrier/tracking, download or stream for digital products with access URLs.
Name
tax_code
Type
string
Description
Tax classification code for calculating sales tax, VAT, or regional taxes. Max 50 characters.
Name
type
Type
string
Description
Product category: physical (requires shipping), digital (electronic delivery), service (intangible), voucher (gift cards/credits), custom (other), or cause (donations). Determines valid shipment options and dimensions.
Name
unit_dimension
Type
string
Description
Measurement unit for quantities when dimensions matter. For products sold by weight, volume, or length rather than discrete units. Examples: kg, lbs, liters, meters, sq_ft. Max 20 characters.
Name
updated_at
Type
timestamp|null
Description
Last time this product was modified. Updated automatically on any field change. Use to detect stale data or show "last modified" timestamps. null if never updated.

POST/products/create

Create a product

Create a new product in your catalog with pricing, media, attributes, and fulfillment details. Products must have a name and type—all other fields are optional but enhance the customer experience and enable richer functionality. Once created, products can be referenced in order line items, tracked in inventory systems, and displayed in customer-facing catalogs.

The product type determines which optional fields are relevant: physical products should include dimensions and shipment details for carrier calculations, digital products benefit from download URLs and file sizes, services typically need only core information. You can update products later as your catalog evolves.

Request attributes

Name
about
Type
string
Description
Full product description with features and specifications. Max 5000 characters.
attributesobjectProduct variants or options customers can select.Click or tap to expand
- Name
  name
  Type
  string
  Description
  Attribute name (1-100 characters).
- Name
  value
  Type
  string
  Description
  Attribute value (1-500 characters).
Name
category
Type
string
Description
Product category for grouping and filtering. Max 100 characters.
Name
custom_data
Type
object
Description
Application-specific key-value pairs. Max 50 keys, each key/value under 500 characters.
Name
description
Type
string
Description
Short product tagline. Max 200 characters.
Name
dimensions
Type
object
Description
Product dimensions for shipping (physical) or file size (digital).
mediaobjectMedia assets: images, videos, downloads. All files must be uploaded to files.zebo.dev before referencing.Click or tap to expand
- Name
  brand_logo
  Type
  string
  Description
  Brand logo file ID.
- Name
  demo_video
  Type
  string
  Description
  Demo video file ID.
- Name
  downloads
  Type
  array
  Description
  Array of downloadable file IDs.
- Name
  gallery
  Type
  array
  Description
  Array of additional image file IDs.
- Name
  hero_image
  Type
  string
  Description
  Primary image file ID.
- Name
  infographic
  Type
  string
  Description
  Infographic file ID.
- Name
  promo_video
  Type
  string
  Description
  Promotional video file ID.
- Name
  thumbnail
  Type
  string
  Description
  Thumbnail image file ID.
- Name
  web_page_url
  Type
  string
  Description
  Product landing page URL.
Name
name
Type
string
Description
Product name shown to customers. Between 1-100 characters.
priceobjectProduct pricing information.Click or tap to expand
- Name
  currency
  Type
  string
  Description
  Three-letter currency code (e.g., usd, ghs).
- Name
  value
  Type
  integer
  Description
  Price in smallest currency unit (cents for USD, pesewas for GHS). Must be positive.
Name
reference
Type
string
Description
External reference or SKU from your systems.
Name
shipment
Type
object
Description
Delivery method. Required for physical/digital products.
Name
tax_code
Type
string
Description
Tax classification code. Max 50 characters.
Name
type
Type
string
Description
Product type: physical, digital, service, voucher, custom, or cause.
Name
unit_dimension
Type
string
Description
Measurement unit for quantities. Max 20 characters. Examples: kg, lbs, liters.

Request

POST

/products/create

curl https://api.zebo.dev/products/create \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "description": "Comfortable everyday wear",
    "about": "Our premium cotton t-shirt is made from 100% organic cotton...",
    "price": {
      "currency": "usd",
      "value": 2999
    },
    "category": "clothing",
    "attributes": [
      { "name": "Size", "value": "Medium" },
      { "name": "Color", "value": "Blue" }
    ],
    "media": {
      "hero_image": "file_abc123",
      "gallery": ["file_def456", "file_ghi789"]
    },
    "custom_data": {
      "season": "summer",
      "material": "organic_cotton"
    }
  }'

Response

{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "description": "Comfortable everyday wear",
    "category": "clothing",
    "reference": "SKU-SHIRT-BLUE-M-2024",
    "created_at": "2026-02-08T23:45:00Z"
  }
}

POST/products/lookup

Lookup a product

Retrieve the complete details of a previously created product by its ID. This returns all product information including media assets, attributes, dimensions, shipment configuration, and custom metadata. Use this to display product details in your catalog, verify product information before adding to orders, or refresh cached product data.

The endpoint requires only the product ID—all other details come from the stored product record. Products are scoped to your authenticated application, so you can only lookup products you own. If the product doesn't exist or has been archived, you'll receive an error.

Request attributes

Name
product_id
Type
string
Description
Unique product identifier returned when you created the product.

Request

POST

/products/lookup

curl https://api.zebo.dev/products/lookup \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_abc123xyz789"
  }'

Response

{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "description": "Comfortable everyday wear",
    "category": "clothing",
    "reference": "SKU-SHIRT-BLUE-M-2024",
    "attributes": [
      {
        "name": "Size",
        "value": "Medium"
      },
      {
        "name": "Color",
        "value": "Blue"
      }
    ],
    "created_at": "2026-02-08T23:45:00Z",
    "updated_at": "2026-02-08T23:50:15Z",
    "archived_at": null
  }
}

POST/products/update

Update a product

Modify an existing product's details by providing only the fields you want to change. Any field you omit remains unchanged—this is a partial update, not a replacement. Use this to adjust pricing, update descriptions, change categorization, or modify any product attribute without reconstructing the entire object.

The endpoint requires the product ID and at least one field to update. Some fields like name, about, and tax_code cannot be cleared once set—they can only be updated to new non-empty values. This protects data integrity for fields that affect downstream systems like invoicing and tax calculations.

Request attributes

Name
about
Type
string
Description
Full product description. Cannot be cleared once set—only updated to a new non-empty value.
Name
attributes
Type
object
Description
Product attributes as key-value pairs. Replaces existing attributes when provided.
Name
category
Type
string
Description
Product category. Cannot be cleared once set—only changed to a different category.
Name
custom_data
Type
object
Description
Custom metadata. Replaces existing custom data when provided.
Name
description
Type
string
Description
Short product tagline. Can be updated or cleared.
Name
images
Type
array
Description
Array of image URLs. Replaces existing images when provided.
Name
metadata
Type
object
Description
Additional metadata. Replaces existing metadata when provided.
Name
name
Type
string
Description
Product name. Cannot be cleared once set—only updated to a new non-empty value.
priceobjectProduct pricing. Provide both currency and value to update.Click or tap to expand
- Name
  currency
  Type
  string
  Description
  Three-letter currency code (e.g., usd, ghs).
- Name
  value
  Type
  integer
  Description
  Price in smallest currency unit. Must be greater than 0.
Name
product_id
Type
string
Description
Unique product identifier.
Name
tax_code
Type
string
Description
Tax classification code. Cannot be cleared once set—only changed to a different code.
Name
type
Type
string
Description
Product type: physical or digital. Changes affect available shipment options.

Request

POST

/products/update

curl https://api.zebo.dev/products/update \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_abc123xyz789",
    "price": {
      "currency": "usd",
      "value": 3499
    },
    "description": "Premium everyday comfort",
    "category": "apparel"
  }'

Response

{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "description": "Premium everyday comfort",
    "category": "apparel",
    "reference": "SKU-SHIRT-BLUE-M-2024",
    "created_at": "2026-02-08T23:45:00Z",
    "updated_at": "2026-02-09T15:30:00Z"
  }
}

POST/products/publish

Publish a product

Make a product publicly available by publishing it. Publishing sets active to true, making the product available through Zebo checkout—customers can access shareable product links and complete purchases. This also controls visibility in your storefront.

The published_at timestamp is set only on the first publish and never changes, even if you unpublish and republish later. This preserves the original publication date for historical tracking. The endpoint fails if the product is already published—unpublish it first if you need to modify publication state.

Request attributes

Name
product_id
Type
string
Description
Unique product identifier.

Request

POST

/products/publish

curl https://api.zebo.dev/products/publish \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_abc123xyz789"
  }'

Response

{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "active": true,
    "category": "apparel",
    "created_at": "2026-02-08T23:45:00Z",
    "published_at": "2026-02-09T16:30:00Z",
    "updated_at": "2026-02-09T16:30:00Z"
  }
}

POST/products/unpublish

Unpublish a product

Remove a product from public availability by unpublishing it. Unpublishing sets active to false while preserving the published_at timestamp—you retain the historical record of when the product was first published. Inactive products are unavailable through Zebo checkout: shareable product links stop working and customers can't complete purchases. This also hides the product from your storefront.

The endpoint fails if the product is already unpublished. Unlike archiving, unpublished products remain in your catalog and can be republished at any time. Use this for temporary removal from sale: seasonal products, out-of-stock items, or products under revision. Existing orders with the product remain unaffected.

Request attributes

Name
product_id
Type
string
Description
Unique product identifier.

Request

POST

/products/unpublish

curl https://api.zebo.dev/products/unpublish \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_abc123xyz789"
  }'

Response

{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "active": false,
    "category": "apparel",
    "created_at": "2026-02-08T23:45:00Z",
    "published_at": "2026-02-09T16:30:00Z",
    "updated_at": "2026-02-09T17:15:00Z"
  }
}

POST/products/archive

Archive a product

Permanently retire a product from your catalog by archiving it. Archiving sets archived_at timestamp and active to false. Archived products can't be published, modified, or added to new orders. This action is irreversible—archived products cannot be unarchived.

The endpoint fails if the product is already archived. Archive products you'll never sell again: discontinued items, replaced products, legacy SKUs. Unlike unpublishing (temporary), archiving signals permanent retirement. Existing orders with archived products remain unaffected—archiving only prevents future use.

Request attributes

Name
product_id
Type
string
Description
Unique product identifier.

Request

POST

/products/archive

curl https://api.zebo.dev/products/archive \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_abc123xyz789"
  }'

Response

{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "active": false,
    "category": "apparel",
    "created_at": "2026-02-08T23:45:00Z",
    "archived_at": "2026-02-09T18:00:00Z",
    "updated_at": "2026-02-09T18:00:00Z"
  }
}