> ## Documentation Index
> Fetch the complete documentation index at: https://redo-44af351d-docs-return-item-identifiers-endpoint.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create custom event

> Create a custom event to trigger flows with merchant-defined event names and properties.

Custom events allow merchants to trigger flows based on events from their own systems.
Events can include custom properties that are accessible in email and SMS templates,
and are persisted for segmentation and historical queries.

## Identity Resolution
The API resolves customers using the following priority order:
1. `customer.id` — Redo customer ObjectId (highest priority)
2. `customer.email` — customer email address
3. `customer.phoneNumber` — customer phone number

At least one identifier must be provided. If no matching customer is found, one will
be created automatically. If `customer.id` is provided but not found, the API falls
back to email/phone rather than returning 404.

## Datetime Formatting
All datetime values must be formatted as ISO 8601 (RFC 3339) strings, e.g., `2026-04-02T12:00:00Z`.
This applies to `eventTimestamp`, any date-valued properties in `data`, and any date-valued `customFields`.
Strings matching this format are automatically detected and indexed as dates for segmentation.

## Rate Limiting
This endpoint is rate-limited to 100 requests per second per store.




## OpenAPI

````yaml /api-schema/openapi.yaml post /stores/{storeId}/events
openapi: 3.1.0
info:
  contact:
    email: engineering-admin@getredo.com
    name: Redo Engineering
  description: |
    ## Endpoints

    Endpoints are authenticated using the Bearer authorization scheme, using the
    REDO_API_SECRET.

    ```txt
    GET /v2.2/resource HTTP/1.1
    Authorization: Bearer 77bb7598b7a972475cc7c7e171ec33af
    Host: api.getredo.com
    ```

    ## Webhooks

    Webhooks are authenticated using the Bearer authorization scheme, using
    a secret supplied by the subscriber.

    ```txt
    POST /events HTTP/1.1
    Authorization: Bearer subscriberauth123
    Host: subscriber.example.com
    ```

    Webhook events are delivered in order for each individual subject (e.g.
    return).

    If the response is not a 2xx status code, the event will be retried multiple
    times before discarding it.
  title: Redo API
  version: 2.2.1
servers:
  - url: https://api.getredo.com/v2.2
security: []
tags:
  - name: Checkout Buttons
  - name: Coverage Info
  - name: Coverage Products
  - name: Custom Events
  - name: Customer Portal
  - name: Customer Subscriptions
  - name: Customers
  - name: Inbound Shipments
  - name: Inventory Items
  - name: Inventory Levels
  - name: Invoices
  - name: Merchant Admin
  - name: Orders
  - name: Products
  - name: Returns
  - name: Storefront
  - name: Webhooks
paths:
  /stores/{storeId}/events:
    post:
      tags:
        - Custom Events
      summary: Create custom event
      description: >
        Create a custom event to trigger flows with merchant-defined event names
        and properties.


        Custom events allow merchants to trigger flows based on events from
        their own systems.

        Events can include custom properties that are accessible in email and
        SMS templates,

        and are persisted for segmentation and historical queries.


        ## Identity Resolution

        The API resolves customers using the following priority order:

        1. `customer.id` — Redo customer ObjectId (highest priority)

        2. `customer.email` — customer email address

        3. `customer.phoneNumber` — customer phone number


        At least one identifier must be provided. If no matching customer is
        found, one will

        be created automatically. If `customer.id` is provided but not found,
        the API falls

        back to email/phone rather than returning 404.


        ## Datetime Formatting

        All datetime values must be formatted as ISO 8601 (RFC 3339) strings,
        e.g., `2026-04-02T12:00:00Z`.

        This applies to `eventTimestamp`, any date-valued properties in `data`,
        and any date-valued `customFields`.

        Strings matching this format are automatically detected and indexed as
        dates for segmentation.


        ## Rate Limiting

        This endpoint is rate-limited to 100 requests per second per store.
      operationId: Custom event create
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/custom-event-request.schema'
            examples:
              full_example:
                summary: Every field populated
                value:
                  eventName: Purchase Milestone Reached
                  customer:
                    id: 665f1a2b3c4d5e6f7a8b9c0d
                    email: stewart@example.com
                    phoneNumber: '+11234567890'
                    firstName: Stewart
                    lastName: Thompson
                    location:
                      street1: 123 Main St
                      street2: Apt 4B
                      city: Seattle
                      state: Washington
                      stateCode: WA
                      postalCode: '98101'
                      country: United States
                      countryCode: US
                      ianaTimeZoneName: America/Los_Angeles
                      latitude: 47.6062
                      longitude: -122.3321
                    customFields:
                      Age at Signup: 25
                      Birthday: '1976-07-04T12:00:00Z'
                      Loyalty Tier: Gold
                      Accepts Marketing: true
                  eventTimestamp: '2026-04-02T12:00:00Z'
                  value: 299.99
                  valueCurrency: USD
                  uniqueId: milestone-test-001
                  data:
                    Milestone Type: 100th_purchase
                    Total Spent: 5000
                    VIP Tier: gold
                    Enrolled At: '2025-01-01T00:00:00Z'
                    Campaign Source: email_drip
                    Last Purchase Date: '2026-03-15T00:00:00Z'
                    $extra:
                      Most Recent Order IDs:
                        - 1
                        - 2
                        - 3
                      Profile Snapshot:
                        tier: gold
                        memberSince: '2024-01-01'
              medium_example:
                summary: Event with customer profile and data
                value:
                  eventName: Order Placed
                  customer:
                    email: stewart@example.com
                    firstName: Stewart
                    lastName: Thompson
                    customFields:
                      Birthday: '1976-07-04T12:00:00Z'
                      Loyalty Tier: Gold
                  value: 149.99
                  valueCurrency: USD
                  data:
                    Order Id: ord_456
                    Item Count: 3
                    Category: apparel
              minimal:
                summary: Required fields only
                value:
                  eventName: Page Viewed
                  customer:
                    email: stewart@example.com
        required: true
      responses:
        '202':
          description: >-
            Event accepted and queued for processing. No response body is
            returned.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid request body or missing required customer identifier
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Store not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Rate limit exceeded
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
components:
  parameters:
    store-id.param:
      description: Store ID
      in: path
      name: storeId
      required: true
      schema:
        example: 64e5a8a1af49a89df37e4ee7
        type: string
  schemas:
    custom-event-request.schema:
      additionalProperties: true
      description: >
        Custom event to trigger flows with merchant-defined event names and
        properties.
      properties:
        eventName:
          description: >-
            The name of the custom event (e.g., 'User Registered', 'Loyalty
            Reward Earned').
          type: string
        customer:
          description: >
            Customer identity and profile fields. At least one of `id`, `email`,
            or `phoneNumber` is required for identity resolution.
          type: object
          additionalProperties: false
          anyOf:
            - required:
                - id
            - required:
                - email
            - required:
                - phoneNumber
          properties:
            id:
              description: >-
                Redo customer ObjectId. Used for identity resolution. Takes
                priority over email and phoneNumber when provided.
              type: string
            email:
              description: Customer email address. Used for identity resolution.
              format: email
              type: string
            phoneNumber:
              description: >-
                Customer phone number in E.164 format. Used for identity
                resolution.
              type: string
            firstName:
              description: >-
                Customer first name. Applied with patch semantics — does not
                erase existing value if omitted.
              type: string
            lastName:
              description: >-
                Customer last name. Applied with patch semantics — does not
                erase existing value if omitted.
              type: string
            location:
              description: >-
                Customer location for profile enrichment. All fields are
                optional.
              type: object
              additionalProperties: false
              properties:
                street1:
                  description: Primary street address.
                  type: string
                street2:
                  description: Secondary address line (apartment, suite, etc.).
                  type: string
                city:
                  description: City name.
                  type: string
                state:
                  description: State or province name.
                  type: string
                stateCode:
                  description: State or province abbreviation (e.g., "CA", "NY").
                  type: string
                postalCode:
                  description: Postal or ZIP code.
                  type: string
                country:
                  description: Country name.
                  type: string
                countryCode:
                  description: ISO 3166-1 alpha-2 country code (e.g., "US", "GB").
                  type: string
                ianaTimeZoneName:
                  description: IANA time zone identifier (e.g., "America/New_York").
                  type: string
                latitude:
                  description: Geographic latitude coordinate.
                  type: number
                longitude:
                  description: Geographic longitude coordinate.
                  type: number
            customFields:
              description: >
                Merchant-defined customer attributes as key-value pairs. Values
                can be strings, numbers, or booleans. Date values should be
                passed as ISO 8601 strings (e.g., "2026-04-02T12:00:00Z") and
                are automatically detected and indexed as dates.
              type: object
              additionalProperties:
                oneOf:
                  - type: string
                  - type: number
                  - type: boolean
        data:
          description: >
            Custom properties for this event (must not exceed 400 properties).
            The size of the event payload must not exceed 5 MB, and each string
            cannot be larger than 100 KB. For a full list of data limits on
            event payloads, see
            [Limitations](/docs/guides/integrations/custom-events#rate-limits).


            Note any top-level property that is not an object can be used to
            create segments. The `$extra` property records any non-segmentable
            values that can be referenced later, e.g., HTML templates are useful
            on a segment but are not used to create a segment.
          type: object
          additionalProperties:
            description: >
              Segmentable event property. Each key you add becomes available for
              audience segmentation and automation conditions. Supported types
              are string, number, boolean, and date (ISO 8601 strings like
              "2025-01-15T00:00:00Z" are auto-detected as dates). Values of 0,
              null, and empty string ("") are treated as unset and will not be
              stored.
            anyOf:
              - type: string
              - type: number
              - type: boolean
          properties:
            $extra:
              description: >
                Non-segmentable metadata bucket. Values inside `$extra` are
                stored on the event but excluded from segmentation indexes.
                Unlike top-level data properties, values of 0, null, and empty
                string are NOT stripped inside `$extra`. Use this for large
                text, debug info, nested objects, arrays, or any data you want
                to reference in templates but not segment on.
              type: object
              additionalProperties: true
        eventTimestamp:
          description: >-
            ISO 8601 timestamp when the event occurred. Defaults to current time
            if not provided.
          format: date-time
          type: string
        value:
          description: >-
            Monetary or conversion value associated with the event (e.g.,
            purchase amount).
          type: number
        valueCurrency:
          description: ISO 4217 currency code for the value field (e.g., "USD", "EUR").
          type: string
        uniqueId:
          description: >
            Merchant-controlled deduplication key (1-255 characters). If
            provided, subsequent events with the same uniqueId for the same
            store are silently deduplicated. Use this for safe retries and
            at-least-once delivery patterns.
          type: string
      required:
        - eventName
        - customer
      title: Custom Event Request
      type: object
    error.schema:
      description: >-
        Problem details. See [RFC 7807 Section
        3](https://datatracker.ietf.org/doc/html/rfc7807#section-3).
      properties:
        detail:
          description: Human-readable description of the problem.
          title: Detail
          type: string
        instance:
          description: A URI reference that identifies this problem.
          format: uri-reference
          type: string
        title:
          description: Human-readable summary of the problem type.
          title: Title
          type: string
        type:
          default: about:blank
          description: A URI reference that identifies the problem type.
          format: uri-reference
          type: string
      title: Problem details
      type: object
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http

````