> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colossal.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Colossal

> Colossal app events. Full list of events and their payload schemas.

The Colossal app emits events when things happen in your project: orders placed, products published, payments processed. These events trigger [automations](/automations/overview).

Some event payloads are privacy-safe snapshots. Customer name and email fields can be blank, and checkout payloads may omit shopper details when the event does not need them.

Each event follows a consistent envelope format:

<ParamField path="event" type="object">
  <Expandable title="properties">
    <ParamField path="signal_type" type="string">
      The event type identifier
    </ParamField>

    <ParamField path="org_id" type="integer">
      Organization ID
    </ParamField>

    <ParamField path="project_id" type="integer">
      Project ID
    </ParamField>

    <ParamField path="entity_id" type="string">
      Primary entity identifier
    </ParamField>

    <ParamField path="entity_type" type="string">
      Type of entity (e.g. `"order"`, `"product"`, `"invoice"`)
    </ParamField>

    <ParamField path="payload" type="object">
      Event-specific payload (see below)
    </ParamField>

    <ParamField path="correlation_id" type="string | null">
      Optional trace/correlation ID
    </ParamField>

    <ParamField path="source" type="string">
      One of `"user"`, `"workflow"`, or `"system"`
    </ParamField>

    <ParamField path="timestamp" type="string">
      ISO 8601 UTC timestamp
    </ParamField>
  </Expandable>
</ParamField>

### Orders

<AccordionGroup>
  <Accordion title="ORDER_CREATED">
    Cart converted into an order during checkout, before payment.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="order_uid" type="string">
          Unique order identifier
        </ParamField>

        <ParamField path="total_price" type="number">
          Order total
        </ParamField>

        <ParamField path="total_amount" type="number">
          Order total
        </ParamField>

        <ParamField path="customer" type="Customer">
          Customer details
        </ParamField>

        <ParamField path="line_items" type="LineItem[]">
          Items in the order
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="ORDER_CONFIRMED">
    Payment processed successfully, before fulfillment.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="order_uid" type="string">
          Unique order identifier
        </ParamField>

        <ParamField path="total_price" type="number">
          Order total before tax
        </ParamField>

        <ParamField path="total_amount" type="number">
          Order total including tax
        </ParamField>

        <ParamField path="subtotal_amount" type="number">
          Subtotal before tax
        </ParamField>

        <ParamField path="tax" type="number">
          Tax amount
        </ParamField>

        <ParamField path="customer" type="Customer">
          Customer details
        </ParamField>

        <ParamField path="line_items" type="LineItem[]">
          Items in the order
        </ParamField>

        <ParamField path="has_subscription" type="boolean">
          Whether order contains a subscription
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="ORDER_COMPLETED">
    Order fully complete. Payment processed and fulfillment finished.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="order_uid" type="string">
          Unique order identifier
        </ParamField>

        <ParamField path="total_price" type="number">
          Order total before tax
        </ParamField>

        <ParamField path="total_amount" type="number">
          Order total including tax
        </ParamField>

        <ParamField path="subtotal_amount" type="number">
          Subtotal before tax
        </ParamField>

        <ParamField path="tax" type="number">
          Tax amount
        </ParamField>

        <ParamField path="customer" type="Customer">
          Customer details
        </ParamField>

        <ParamField path="line_items" type="LineItem[]">
          Items in the order
        </ParamField>

        <ParamField path="has_subscription" type="boolean">
          Whether order contains a subscription
        </ParamField>

        <ParamField path="fulfillment_method" type="string">
          Fulfillment method (e.g., `digital`)
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="ORDER_CANCELLED">
    Order cancelled.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="order_uid" type="string">
          Unique order identifier
        </ParamField>

        <ParamField path="cancelled_at" type="string">
          ISO 8601 timestamp of cancellation
        </ParamField>

        <ParamField path="total_amount" type="number">
          Order total
        </ParamField>

        <ParamField path="currency" type="string">
          Currency code
        </ParamField>

        <ParamField path="customer" type="Customer">
          Customer details
        </ParamField>

        <ParamField path="payment_provider" type="string">
          Payment provider
        </ParamField>

        <ParamField path="refund_reason" type="string">
          Reason, if provided
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="ORDER_REFUNDED">
    Order refunded.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="order_uid" type="string">
          Unique order identifier
        </ParamField>

        <ParamField path="refunded_at" type="string">
          ISO 8601 timestamp of refund
        </ParamField>

        <ParamField path="total_amount" type="number">
          Order total refunded
        </ParamField>

        <ParamField path="currency" type="string">
          Currency code
        </ParamField>

        <ParamField path="customer" type="Customer">
          Customer details
        </ParamField>

        <ParamField path="payment_provider" type="string">
          Payment provider
        </ParamField>

        <ParamField path="refund_reason" type="string">
          Reason, if provided
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Customers

<AccordionGroup>
  <Accordion title="CUSTOMER_CREATED">
    New customer account created.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="customer_uid" type="string">
          Unique customer identifier
        </ParamField>

        <ParamField path="email" type="string">
          Customer email address
        </ParamField>

        <ParamField path="full_name" type="string">
          Customer full name
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="CUSTOMER_UPDATED">
    Customer details updated.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="customer_uid" type="string">
          Unique customer identifier
        </ParamField>

        <ParamField path="email" type="string">
          Customer email address
        </ParamField>

        <ParamField path="full_name" type="string">
          Customer full name
        </ParamField>

        <ParamField path="changed_fields" type="string[]">
          List of fields that changed
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Invoices

<AccordionGroup>
  <Accordion title="INVOICE_CREATED">
    New invoice created.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="invoice_uid" type="string">
          Unique invoice identifier
        </ParamField>

        <ParamField path="invoice_number" type="string?">
          Human-readable invoice number
        </ParamField>

        <ParamField path="customer_uid" type="string?">
          Customer identifier
        </ParamField>

        <ParamField path="order_uid" type="string?">
          Associated order identifier
        </ParamField>

        <ParamField path="currency" type="string">
          Currency code (e.g., `USD`)
        </ParamField>

        <ParamField path="subtotal" type="integer">
          Subtotal in cents
        </ParamField>

        <ParamField path="tax" type="integer">
          Tax in cents
        </ParamField>

        <ParamField path="total" type="integer">
          Total in cents
        </ParamField>

        <ParamField path="status" type="string">
          Invoice status
        </ParamField>

        <ParamField path="source" type="string">
          Invoice source (e.g., `order`)
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="INVOICE_PAID">
    Invoice paid.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="invoice_uid" type="string">
          Unique invoice identifier
        </ParamField>

        <ParamField path="invoice_number" type="string?">
          Human-readable invoice number
        </ParamField>

        <ParamField path="customer_uid" type="string?">
          Customer identifier
        </ParamField>

        <ParamField path="order_uid" type="string?">
          Associated order identifier
        </ParamField>

        <ParamField path="currency" type="string">
          Currency code
        </ParamField>

        <ParamField path="total" type="integer">
          Total paid in cents
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Payments

<AccordionGroup>
  <Accordion title="PAYMENT_SUCCEEDED">
    Payment completed successfully.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="payment_uid" type="string">
          Unique payment identifier
        </ParamField>

        <ParamField path="invoice_uid" type="string">
          Associated invoice identifier
        </ParamField>

        <ParamField path="amount" type="integer">
          Amount in cents
        </ParamField>

        <ParamField path="currency" type="string">
          Currency code
        </ParamField>

        <ParamField path="payment_provider" type="string">
          Payment provider (e.g., `stripe`)
        </ParamField>

        <ParamField path="payment_method" type="string?">
          Payment method (e.g., `card`)
        </ParamField>

        <ParamField path="card_brand" type="string?">
          Card brand (e.g., `visa`)
        </ParamField>

        <ParamField path="card_last4" type="string?">
          Last 4 digits of card
        </ParamField>

        <ParamField path="transaction_id" type="string?">
          Provider transaction ID
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PAYMENT_FAILED">
    Payment failed.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="payment_uid" type="string">
          Unique payment identifier
        </ParamField>

        <ParamField path="invoice_uid" type="string">
          Associated invoice identifier
        </ParamField>

        <ParamField path="amount" type="integer">
          Amount in cents
        </ParamField>

        <ParamField path="currency" type="string">
          Currency code
        </ParamField>

        <ParamField path="payment_provider" type="string">
          Payment provider
        </ParamField>

        <ParamField path="payment_method" type="string?">
          Payment method
        </ParamField>

        <ParamField path="failure_code" type="string?">
          Failure code
        </ParamField>

        <ParamField path="failure_message" type="string?">
          Failure message
        </ParamField>

        <ParamField path="decline_code" type="string?">
          Decline code from provider
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Products

<AccordionGroup>
  <Accordion title="PRODUCT_CREATED">
    New product created.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique product identifier
        </ParamField>

        <ParamField path="name" type="string">
          Product name
        </ParamField>

        <ParamField path="handle" type="string">
          URL-friendly handle
        </ParamField>

        <ParamField path="description" type="string?">
          Product description
        </ParamField>

        <ParamField path="variant_properties" type="object?">
          Variant property definitions
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_UPDATED">
    Product details modified.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique product identifier
        </ParamField>

        <ParamField path="name" type="string">
          Product name
        </ParamField>

        <ParamField path="handle" type="string">
          URL-friendly handle
        </ParamField>

        <ParamField path="description" type="string?">
          Product description
        </ParamField>

        <ParamField path="variant_properties" type="object?">
          Variant property definitions
        </ParamField>

        <ParamField path="is_archived" type="boolean">
          Whether product is archived
        </ParamField>

        <ParamField path="changed_fields" type="string[]">
          List of fields that changed
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_PUBLISHED">
    Product made visible in the storefront.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique product identifier
        </ParamField>

        <ParamField path="name" type="string">
          Product name
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_DRAFT_DISCARDED">
    Product draft discarded.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique product identifier
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_ARCHIVED">
    Product archived.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique product identifier
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_UNARCHIVED">
    Product restored from archive.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique product identifier
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Product variants

<AccordionGroup>
  <Accordion title="PRODUCT_VARIANT_CREATED">
    New variant added to a product.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique variant identifier
        </ParamField>

        <ParamField path="product_uid" type="string">
          Parent product identifier
        </ParamField>

        <ParamField path="name" type="string?">
          Variant name
        </ParamField>

        <ParamField path="properties" type="object?">
          Variant properties (e.g., `{"tier": "pro"}`)
        </ParamField>

        <ParamField path="inventory_count" type="integer?">
          Inventory count
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_VARIANT_UPDATED">
    Variant details changed.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique variant identifier
        </ParamField>

        <ParamField path="product_uid" type="string">
          Parent product identifier
        </ParamField>

        <ParamField path="name" type="string?">
          Variant name
        </ParamField>

        <ParamField path="properties" type="object?">
          Variant properties
        </ParamField>

        <ParamField path="inventory_count" type="integer?">
          Inventory count
        </ParamField>

        <ParamField path="is_archived" type="boolean">
          Whether variant is archived
        </ParamField>

        <ParamField path="changed_fields" type="string[]">
          List of fields that changed
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_VARIANT_DELETED">
    Variant removed from a product.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique variant identifier
        </ParamField>

        <ParamField path="product_uid" type="string">
          Parent product identifier
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Product prices

<AccordionGroup>
  <Accordion title="PRODUCT_PRICE_CREATED">
    Price tier added to a variant.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique price identifier
        </ParamField>

        <ParamField path="variant_uid" type="string">
          Parent variant identifier
        </ParamField>

        <ParamField path="name" type="string?">
          Price name (e.g., `Monthly`)
        </ParamField>

        <ParamField path="price" type="object">
          Price details (`{amount, type}`)
        </ParamField>

        <ParamField path="currency" type="string">
          Currency code
        </ParamField>

        <ParamField path="recurring_interval" type="string?">
          Billing interval (e.g., `month`)
        </ParamField>

        <ParamField path="trial_duration" type="string?">
          Trial period (e.g., `14d`)
        </ParamField>

        <ParamField path="is_default" type="boolean">
          Whether this is the default price
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_PRICE_UPDATED">
    Price tier changed.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique price identifier
        </ParamField>

        <ParamField path="variant_uid" type="string">
          Parent variant identifier
        </ParamField>

        <ParamField path="name" type="string?">
          Price name
        </ParamField>

        <ParamField path="price" type="object">
          Price details
        </ParamField>

        <ParamField path="currency" type="string">
          Currency code
        </ParamField>

        <ParamField path="recurring_interval" type="string?">
          Billing interval
        </ParamField>

        <ParamField path="trial_duration" type="string?">
          Trial period
        </ParamField>

        <ParamField path="is_default" type="boolean">
          Whether this is the default price
        </ParamField>

        <ParamField path="changed_fields" type="string[]">
          List of fields that changed
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_PRICE_DELETED">
    Price tier removed.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique price identifier
        </ParamField>

        <ParamField path="variant_uid" type="string">
          Parent variant identifier
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Product media

<AccordionGroup>
  <Accordion title="PRODUCT_MEDIA_ADDED">
    Media files attached to a variant.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="variant_uid" type="string">
          Variant identifier
        </ParamField>

        <ParamField path="media_uids" type="string[]">
          List of added media identifiers
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_MEDIA_REMOVED">
    Media files removed from a variant.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="variant_uid" type="string">
          Variant identifier
        </ParamField>

        <ParamField path="media_uids" type="string[]">
          List of removed media identifiers
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Product deliverables

<AccordionGroup>
  <Accordion title="PRODUCT_DELIVERABLE_CREATED">
    New deliverable created.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique deliverable identifier
        </ParamField>

        <ParamField path="type" type="string">
          Deliverable type (e.g., `digital_download`)
        </ParamField>

        <ParamField path="name" type="string">
          Deliverable name
        </ParamField>

        <ParamField path="config" type="object?">
          Type-specific configuration
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_DELIVERABLE_UPDATED">
    Deliverable details changed.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique deliverable identifier
        </ParamField>

        <ParamField path="type" type="string">
          Deliverable type
        </ParamField>

        <ParamField path="name" type="string">
          Deliverable name
        </ParamField>

        <ParamField path="config" type="object?">
          Type-specific configuration
        </ParamField>

        <ParamField path="changed_fields" type="string[]">
          List of fields that changed
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_DELIVERABLE_ARCHIVED">
    Deliverable archived.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="uid" type="string">
          Unique deliverable identifier
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

### Product variant deliverables

<AccordionGroup>
  <Accordion title="PRODUCT_VARIANT_DELIVERABLE_ADDED">
    Deliverable attached to a variant.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="variant_uid" type="string">
          Variant identifier
        </ParamField>

        <ParamField path="deliverable_uid" type="string">
          Deliverable identifier
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="PRODUCT_VARIANT_DELIVERABLE_REMOVED">
    Deliverable removed from a variant.

    <ParamField path="payload" type="object">
      <Expandable title="properties">
        <ParamField path="variant_uid" type="string">
          Variant identifier
        </ParamField>

        <ParamField path="deliverable_uid" type="string">
          Deliverable identifier
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

## Shared types

<ParamField path="Customer" type="object">
  <Expandable title="properties">
    <ParamField path="uid" type="string">
      Unique customer identifier
    </ParamField>

    <ParamField path="email" type="string">
      Customer email address
    </ParamField>

    <ParamField path="first_name" type="string">
      First name
    </ParamField>

    <ParamField path="last_name" type="string">
      Last name
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="LineItem" type="object">
  <Expandable title="properties">
    <ParamField path="uid" type="string">
      Unique line item identifier
    </ParamField>

    <ParamField path="name" type="string">
      Product name
    </ParamField>

    <ParamField path="sku" type="string">
      Product SKU
    </ParamField>

    <ParamField path="price" type="number">
      Unit price
    </ParamField>

    <ParamField path="quantity" type="integer">
      Quantity ordered
    </ParamField>

    <ParamField path="category" type="string">
      Product category
    </ParamField>
  </Expandable>
</ParamField>
