openapi: 3.2.0
info:
  title: Emotive Open Orders API
  version: v1
  description: 'The public Emotive Open API for eCommerce integrations: order tracking, manual opt-outs, and custom events. Emotive documents these endpoints in prose on its knowledge base and Lists developer reference but publishes no machine-readable specification for them. This document was GENERATED by API Evangelist strictly from the request/response examples, header rules, body-parameter tables and HTTP status-code tables Emotive publishes on the pages listed in x-origin. No field, endpoint, or status code appears here that Emotive does not publish. Fields that Emotive documents only inside screenshots (the full Orders request/response parameter tables) are represented from the published cURL/Python payload example rather than from the images.'
  contact:
    name: Emotive Support
    email: support@emotive.io
    url: https://help.emotive.io/
  x-origin:
  - url: https://help.emotive.io/docs/integrations/open-api-integration-orders
    format: documentation
    method: generated
    retrieved: '2026-08-13'
    note: Orders endpoint, Authorization scheme, required body parameters, full payload example, HTTP status-code tables.
  - url: https://help.emotive.io/docs/integrations/custom-site-api
    format: documentation
    method: generated
    retrieved: '2026-08-13'
    note: Authentication, content types, HTTP response-code conventions and the Orders API base URL.
  - url: https://emotive.gitbook.io/emotive-lists/reference/api-reference/unsubscribe
    format: documentation
    method: generated
    retrieved: '2026-08-13'
    note: Manual opt-out endpoint, headers, body and 200/400 response bodies.
  - url: https://emotive.gitbook.io/emotive-lists/reference/api-reference/custom-events
    format: documentation
    method: generated
    retrieved: '2026-08-13'
    note: Custom events endpoint, body parameter table and 200/401 response bodies.
servers:
- url: https://api.emotiveapp.co
  description: Emotive Open API (all three documented paths answer here; the apex host emotiveapp.co answers identically)
- url: https://emotiveapp.co
  description: Apex host named by the Lists developer reference for the opt-out and custom-event paths
security:
- TokenAuth: []
tags:
- name: Orders
  description: Order tracking for custom eCommerce sites.
paths:
  /ecommerce/v1/orders/:
    post:
      tags:
      - Orders
      operationId: createOrder
      summary: Track an order
      description: Send order data to Emotive so it can be attributed to an SMS subscriber. Orders sent without all required data, or with invalid values, return 400.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '201':
          $ref: '#/components/responses/Created'
        '292':
          $ref: '#/components/responses/QueuedForExecution'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    Product:
      type: object
      required:
      - title
      - sku
      properties:
        title:
          type: string
        sku:
          type: string
    LineItem:
      type: object
      required:
      - product
      - price
      properties:
        product:
          $ref: '#/components/schemas/Product'
        collection:
          $ref: '#/components/schemas/Collection'
        variant:
          $ref: '#/components/schemas/Variant'
        price:
          type: number
        quantity:
          type: integer
        notes:
          type: string
        extra_data:
          type: object
          additionalProperties: true
    Variant:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
    Collection:
      type: object
      properties:
        title:
          type: string
        id:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
          description: Explains what happened and how to correct it
          if applicable.: null
    ShippingAddress:
      type: object
      properties:
        name:
          type: string
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state_code:
          type: string
        zip:
          type: string
        country_code:
          type: string
        notes:
          type: string
        extra_data:
          type: object
          additionalProperties: true
    Order:
      type: object
      required:
      - customer
      - line_items
      - total_price
      - order_id
      - order_date
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
        shipping_address:
          $ref: '#/components/schemas/ShippingAddress'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        discount_codes:
          type: string
          example: TEST15
        total_price:
          type: number
          example: 0
        currency:
          type: string
          example: USD
        order_id:
          type: integer
          example: 12346
        order_date:
          type: string
          description: Order timestamp, e.g. 2020-02-02 10:10:10 or 2020-02-02T10:10:10
        is_subscribed_order:
          type: boolean
        email_opt_in:
          type: boolean
        text_opt_in:
          type: boolean
        notes:
          type: string
        extra_data:
          type: object
          additionalProperties: true
        customer_tags:
          type: array
          items:
            type: string
    Detail:
      type: object
      properties:
        detail:
          type: string
    Customer:
      type: object
      required:
      - phone
      properties:
        id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        phone:
          type: string
          description: E164 formatted subscriber phone number.
          example: '+14132737194'
        email:
          type: string
        notes:
          type: string
        extra_data:
          type: object
          additionalProperties: true
  responses:
    Conflict:
      description: Conflict
    BadRequest:
      description: Bad Request (missing or invalid data provided). The response body contains an "error" attribute explaining what happened and how to correct it, if applicable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PayloadTooLarge:
      description: Request entity too large
    InternalServerError:
      description: Internal server error
    Unauthorized:
      description: Unauthorized / Authentication Failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Detail'
          example:
            detail: Authentication credentials were not provided.
    Forbidden:
      description: Forbidden
    NotFound:
      description: Resource not found
    QueuedForExecution:
      description: Accepted (request accepted, and queued for execution)
    MethodNotAllowed:
      description: Method not allowed
    OK:
      description: OK
    Created:
      description: Created
    ServiceUnavailable:
      description: Service unavailable
    PreconditionFailed:
      description: Precondition failed
    NotImplemented:
      description: Not implemented
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Encoded token authorization over HTTPS. The header value is the word "Token", a space, then the API key Emotive provides. Example: `Authorization: Token <api_token>`. Tokens are unique to an Emotive brand user; contact support@emotive.io or create a List Growth API signup flow to obtain one.'