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

# Send a funnel event

> Call from a trusted server or a no-code tool when a person does something you want to attribute, such as a webinar signup or a course sale. Uses the store's Orders API key. Maximum 64 KiB; 600 requests per minute per store, counted apart from the Orders API. Name the person with one of `email`, `emailHash` or `visitorId`. A raw `email` is hashed on arrival and is not stored. Send the same `eventId` on a retry. Without `eventId`, each call writes a new event. The names `comment`, `dm_sent`, `link_click`, `store_order`, `identify`, `consentwithdrawn`, `custom` and `saleofdataoptin` are reserved for SideShift.



## OpenAPI

````yaml /openapi/commerce-orders.yaml post /events
openapi: 3.0.3
info:
  title: SideShift Orders API
  version: 1.0.0
  description: >-
    Verified custom-store purchases, cumulative refunds and funnel events. Uses
    a store Orders API key, not platform OAuth. Store tracking must be enabled.
servers:
  - url: https://app.sideshift.app/api/commerce
security:
  - StoreOrdersKey: []
paths:
  /events:
    post:
      tags:
        - Events
      summary: Send a funnel event
      description: >-
        Call from a trusted server or a no-code tool when a person does
        something you want to attribute, such as a webinar signup or a course
        sale. Uses the store's Orders API key. Maximum 64 KiB; 600 requests per
        minute per store, counted apart from the Orders API. Name the person
        with one of `email`, `emailHash` or `visitorId`. A raw `email` is hashed
        on arrival and is not stored. Send the same `eventId` on a retry.
        Without `eventId`, each call writes a new event. The names `comment`,
        `dm_sent`, `link_click`, `store_order`, `identify`, `consentwithdrawn`,
        `custom` and `saleofdataoptin` are reserved for SideShift.
      operationId: submitStoreEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreEvent'
            example:
              event: registered
              email: shopper@example.com
              occurredAt: '2026-11-11T12:30:00.000Z'
              eventId: signup-1042
      responses:
        '200':
          description: >-
            Accepted. A repeat of the same `eventId` for the same store and
            event returns the first event's ID and writes nothing.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - id
                    properties:
                      id:
                        type: string
                        description: SideShift's ID for the event.
              example:
                data:
                  id: 3f0c8f0e-5a63-4a6b-9a39-0d6c3b8b2a55
        '400':
          description: >-
            Invalid JSON or fields, a reserved or malformed event name, no
            person field, both `email` and `emailHash`, a value without a
            currency, a time in the future or older than 90 days, an unknown
            field, or a `visitorId` that cannot be tracked and no email to use
            instead.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Human-readable error message.
        '401':
          description: Missing, invalid, rotated, disconnected-store or Shopify-store key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Human-readable error message.
        '404':
          description: Store tracking is not enabled for this deployment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '413':
          description: Request exceeds 64 KiB.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Human-readable error message.
        '429':
          description: Rate limit exceeded. Honor Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Human-readable error message.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
        '500':
          description: >-
            Internal error. Retry the same request with the same `eventId` and
            backoff.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Human-readable error message.
components:
  schemas:
    StoreEvent:
      type: object
      additionalProperties: false
      required:
        - event
      description: >-
        Name the person with `email`, `emailHash` or `visitorId`; at least one
        is required. Send `email` or `emailHash`, not both. Send `valueCents`
        and `currency` together or not at all.
      properties:
        event:
          type: string
          description: >-
            The event name. 1 to 60 lower-case letters, digits or underscores.
            The names `comment`, `dm_sent`, `link_click` and `store_order` are
            reserved and return 400.
          pattern: ^[a-z0-9_]{1,60}$
          example: registered
        email:
          type: string
          format: email
          maxLength: 320
          description: >-
            The person's email. SideShift hashes it on arrival, as the browser
            script does, and does not store it.
        emailHash:
          type: string
          description: >-
            SHA-256, as 64 lowercase hex characters, of the person's email with
            leading and trailing spaces removed and made lowercase. The same
            value window.sideshift.identify sends.
          pattern: ^[0-9a-f]{64}$
        visitorId:
          type: string
          description: >-
            The visitor ID from the SideShift script, from
            window.sideshift.getVisitorId.
          pattern: ^[a-zA-Z0-9_-]{16,128}$
        occurredAt:
          type: string
          format: date-time
          description: >-
            When the event happened, as an ISO 8601 time with a UTC offset.
            Defaults to the time of the request. At most five minutes in the
            future and at most 90 days in the past.
        eventId:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            Your own ID for this event, for safe retries. A repeat for the same
            store and event name writes nothing. It cannot hold an email address
            or a phone number.
        valueCents:
          type: integer
          minimum: 0
          maximum: 100000000000
          description: >-
            The value of the event in the currency minor unit, despite the Cents
            suffix. Send it with `currency`.
        currency:
          type: string
          description: >-
            Supported uppercase ISO 4217 currency code. Send it with
            `valueCents`.
          example: USD
  securitySchemes:
    StoreOrdersKey:
      type: http
      scheme: bearer
      bearerFormat: ss_orders_…
      description: >-
        Store-specific secret generated in Website & sales. Never expose in
        browser code.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.