Tinvio E-commerce Profiles API

openapi: 3.2.0
info:
  title: Tinvio Com E-commerce Profiles API
  version: '1.0'
  contact:
    email: build.with@jaz.ai
    name: API Support
    url: https://jaz.ai
  description: 'Operations tagged E-commerce Profiles across 2 of this provider''s published API definitions: tinvio-com-openapi-original.yaml, tinvio-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.getjaz.com
tags:
- description: Create, update, search, and delete e-commerce profiles, replace their event mappings, and view the event catalogue.
  name: E-commerce Profiles
paths:
  /api/v1/e-commerce-event-catalogue:
    get:
      description: 'Every canonical event type and what a profile may do with it: the account classes a mapping may point at, the tax side, and whether the family refuses a tax profile outright. Read this before building a profile: sending a tax profile to a family that refuses one fails the whole save rather than being ignored.'
      operationId: list-e-commerce-event-catalogue
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get E-commerce Event Catalogue
      tags:
      - E-commerce Profiles
    servers:
    - url: https://api.getjaz.com
  /api/v1/e-commerce-profiles:
    post:
      description: 'Create an e-commerce profile: the clearing account that carries what the platform owes, and the account and tax profile each event type posts to. Fetch the event catalogue first: some families refuse a tax profile, and sending one fails the whole save.'
      operationId: create-e-commerce-profile
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create E-commerce Profile
      tags:
      - E-commerce Profiles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEcommerceProfileRequest'
        description: The e-commerce profile to create.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/e-commerce-profiles/search:
    post:
      description: Search the organization's e-commerce profiles. Coded fields (status, outerAxis, innerAxis, journalDatePolicy) are stored as their enum names, so match those rather than the labels a screen shows.
      operationId: search-e-commerce-profile
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search E-commerce Profiles
      tags:
      - E-commerce Profiles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchEcommerceProfilesRequest'
        description: Search criteria.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/e-commerce-profiles/{resourceId}:
    delete:
      description: Soft-delete an e-commerce profile. Refused while any connected store still posts through it; making the profile inactive does not change that, because it changes no reference. Returns deleted false where nothing was deleted.
      operationId: delete-e-commerce-profile
      parameters:
      - description: Resource ID of the e-commerce profile.
        in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Delete E-commerce Profile
      tags:
      - E-commerce Profiles
    put:
      description: Update an e-commerce profile. Null on each field means no change. Sending an eventMappings or clearingAccounts list REPLACES the whole of it, so use the dedicated endpoints when that is all you mean to change.
      operationId: update-e-commerce-profile
      parameters:
      - description: Resource ID of the e-commerce profile.
        in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Update E-commerce Profile
      tags:
      - E-commerce Profiles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEcommerceProfileRequest'
        description: The fields to change.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/e-commerce-profiles/{resourceId}/event-mappings:
    put:
      description: 'Replace a profile''s whole event mapping. The list sent becomes the mapping: anything left out is dropped. An empty list clears it, leaving a profile that can post nothing until it is mapped again.'
      operationId: update-e-commerce-profile-event-mapping
      parameters:
      - description: Resource ID of the e-commerce profile.
        in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Replace E-commerce Profile Event Mappings
      tags:
      - E-commerce Profiles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEcommerceProfileEventMappingsRequest'
        description: The complete event mapping.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/e-commerce-profiles/{resourceId}/status:
    put:
      description: 'Stop or start a profile. INACTIVE refuses new conversions and pauses every connected store posting through it, which also unlinks those stores. That unlink is one-way, so the stores are reassigned afterwards rather than restored. It does NOT make the profile deletable: delete asks whether a store still references it, and this changes no reference.'
      operationId: update-e-commerce-profile-status
      parameters:
      - description: Resource ID of the e-commerce profile.
        in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Set E-commerce Profile Status
      tags:
      - E-commerce Profiles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEcommerceProfileStatusRequest'
        description: The status to set.
        required: true
    servers:
    - url: https://api.getjaz.com
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/ErrorResponseData'
          description: Error details.
      type: object
    UpdateEcommerceProfileEventMappingsRequest:
      properties:
        eventMappings:
          description: 'The complete mapping. An empty list clears it, leaving a profile that can

            post nothing until it is mapped again.'
          items:
            $ref: '#/components/schemas/EcommerceEventMappingInput'
          maxItems: 500
          type: array
        resourceId:
          description: Resource ID of the profile, from the URL path.
          type: string
      required:
      - eventMappings
      - resourceId
      type: object
    DateExpression:
      properties:
        between:
          description: Match dates between these two dates (exactly two, in YYYY-MM-DD format).
          items:
            type: string
          type: array
        eq:
          description: Match dates equal to this, in YYYY-MM-DD format.
          type: string
        gt:
          description: Match dates after this, in YYYY-MM-DD format.
          type: string
        gte:
          description: Match dates on or after this, in YYYY-MM-DD format.
          type: string
        isNotNull:
          description: Match records where the date is set. Pass the placeholder date "0001-01-01".
          example: '0001-01-01'
          type: string
        isNull:
          description: Match records where the date is not set. Pass the placeholder date "0001-01-01".
          example: '0001-01-01'
          type: string
        lt:
          description: Match dates before this, in YYYY-MM-DD format.
          type: string
        lte:
          description: Match dates on or before this, in YYYY-MM-DD format.
          type: string
        notBetween:
          description: Match dates outside these two dates (exactly two, in YYYY-MM-DD format).
          items:
            type: string
          type: array
      required:
      - between
      type: object
    EcommerceEventMappingInput:
      properties:
        accountResourceId:
          description: Account this event posts to. Must be a class the catalogue allows for it.
          type: string
        eventType:
          description: 'A canonical event type, e.g. SALE_GOODS or FEE_COMMISSION. Give this or

            family, never both. A named eventType wins over its family.'
          example: SALE_GOODS
          maxLength: 50
          type: string
        family:
          description: 'A family, e.g. REVENUE or FEE, mapping every event in it at once. Give this

            or eventType, never both.'
          example: REVENUE
          maxLength: 50
          type: string
        taxProfileResourceId:
          description: 'Tax profile for this event. Families that refuse one reject the whole profile

            save rather than ignoring it -- the catalogue''s refusesTaxProfile says which.'
          type: string
      required:
      - accountResourceId
      type: object
    BaseResponse:
      properties:
        data:
          description: The response object.
      type: object
    SetEcommerceProfileStatusRequest:
      properties:
        resourceId:
          description: Resource ID of the profile, from the URL path.
          type: string
        status:
          description: 'ACTIVE or INACTIVE. INACTIVE also pauses and unlinks every connected store

            posting through this profile; that unlink is one-way. It does NOT make the

            profile deletable, because delete asks whether a store still references it.'
          enum:
          - ACTIVE
          - INACTIVE
          type: string
      required:
      - resourceId
      - status
      type: object
    UpdateEcommerceProfileRequest:
      properties:
        clearingAccountResourceId:
          description: Account that carries what the platform owes.
          type: string
        clearingAccounts:
          description: Sending a list REPLACES every per-payment-method clearing account. Null leaves them alone.
          items:
            $ref: '#/components/schemas/EcommerceClearingAccountInput'
          maxItems: 100
          type: array
        eventMappings:
          description: Sending a list REPLACES the whole mapping. Null leaves it alone.
          items:
            $ref: '#/components/schemas/EcommerceEventMappingInput'
          maxItems: 500
          type: array
        innerAxis:
          description: How lines are grouped inside a journal.
          enum:
          - BY_ACCOUNT
          - BY_EVENT
          - BY_ORDER
          - BY_LINE
          type: string
        journalDatePolicy:
          description: Which date values the journal.
          enum:
          - DOCUMENT_DATE
          - PERIOD_END
          - PAYOUT_DATE
          type: string
        journalReferenceTemplate:
          description: Journal reference template. Blank resets to the default.
          maxLength: 255
          type: string
        lineDescriptionTemplate:
          description: Journal line description template. Blank resets to the default.
          maxLength: 255
          type: string
        name:
          description: Display name (max 255, case-insensitive unique per organization).
          maxLength: 255
          type: string
        outerAxis:
          description: How many journals one settlement becomes.
          enum:
          - PER_DOCUMENT
          - PER_DAY
          - PER_MONTH
          type: string
        platformCode:
          description: 'The platform (SHOPIFY, LAZADA, ...) this profile''s mapping is built for.

            Null means no change. A profile cannot be saved without one, so this can

            only be omitted when the profile already has a platform; it cannot be

            cleared back to pooled.'
          example: SHOPIFY
          maxLength: 64
          type: string
        resourceId:
          description: Resource ID of the profile, from the URL path.
          type: string
        status:
          description: 'ACTIVE or INACTIVE. INACTIVE stops new conversions and pauses every connected

            store posting through this profile, which also unlinks them. That unlink is

            one-way, so the merchant reassigns the stores they want afterwards. Prefer the

            dedicated status endpoint when status is all that changes: a mapping list sent

            wrong here replaces the whole mapping.'
          enum:
          - ACTIVE
          - INACTIVE
          type: string
      required:
      - resourceId
      type: object
    SearchEcommerceProfilesRequest:
      properties:
        filter:
          allOf:
          - $ref: '#/components/schemas/EcommerceProfileFilter'
          description: Filter conditions. Combine with and and or for complex queries.
        limit:
          default: 100
          description: Maximum number of results per page (max 1000).
          maximum: 1000
          minimum: 1
          type: integer
        offset:
          default: 0
          description: Zero-indexed row offset into the result set. Sort is required when offset is set.
          maximum: 65536
          minimum: 0
          type: integer
        query:
          description: 'Structured search query using Jaz search operators. Parsed automatically into filter fields.

            Explicit filter fields override query results on conflict.

            Example: "status:unpaid AND $500+".'
          maxLength: 1000
          type: string
        sort:
          allOf:
          - $ref: '#/components/schemas/EcommerceProfileSortFilter'
          description: Sort order. Required when offset is set.
      type: object
    EcommerceProfileSortFilter:
      properties:
        order:
          description: Sort direction, ASC or DESC.
          enum:
          - ASC
          - DESC
          type: string
        sortBy:
          description: Fields to sort by, in priority order.
          items:
            enum:
            - resourceId
            - name
            - status
            - platformCode
            - createdAt
            - updatedAt
            type: string
          maxItems: 10
          type: array
          uniqueItems: true
      required:
      - order
      - sortBy
      type: object
    EcommerceClearingAccountInput:
      properties:
        accountResourceId:
          description: Account settlements on this payment method balance to.
          type: string
        paymentMethod:
          description: Payment method as the platform names it, e.g. PAYPAL.
          example: PAYPAL
          maxLength: 50
          type: string
      required:
      - accountResourceId
      - paymentMethod
      type: object
    StringExpression:
      properties:
        contains:
          description: Match values containing this substring.
          type: string
        endWith:
          description: Match values ending with this term (case sensitive).
          type: string
        eq:
          description: Match values equal to this.
          type: string
        in:
          description: Match values equal to any of these.
          items:
            type: string
          maxItems: 100
          type: array
        isBlank:
          description: Match records where the field is null or empty ("true") or neither ("false").
          type: string
        isNotBlank:
          description: Match records where the field is neither null nor empty ("true").
          type: string
        isNull:
          description: Match records where the field is null ("true") or not null ("false").
          type: string
        likeIn:
          description: Match values containing any of these substrings.
          items:
            type: string
          maxItems: 100
          type: array
        neq:
          description: Match values not equal to this.
          type: string
        notContains:
          description: Match values not containing this substring.
          type: string
        notEndWith:
          description: Match values not ending with this term (case sensitive).
          type: string
        notStartWith:
          description: Match values not starting with this term (case sensitive).
          type: string
        reg:
          description: Match values containing any of these terms. This is a substring match, not a regular expression, despite the name.
          items:
            type: string
          maxItems: 100
          type: array
        startWith:
          description: Match values starting with this term (case sensitive).
          type: string
      required:
      - in
      - likeIn
      - reg
      type: object
    ErrorResponseData:
      properties:
        error_type:
          description: Error category, for example validation_error, invalid_request_body, or internal_server_error.
          example: validation_error
          type: string
        errors:
          description: Error messages describing what went wrong.
          items:
            type: string
          type: array
      type: object
    EcommerceProfileFilter:
      properties:
        and:
          description: Combine with another filter using AND.
          type: object
        clearingAccount:
          allOf:
          - $ref: '#/components/schemas/OrganizationAccountNestedFilter'
          description: Filter by the clearing account's own name or code. Fields inside are OR'd.
        clearingAccountResourceId:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by clearing account resource ID.
        createdAt:
          allOf:
          - $ref: '#/components/schemas/DateExpression'
          description: Filter by creation date, in YYYY-MM-DD format.
        innerAxis:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: 'Filter by inner axis, stored as the enum name: BY_ACCOUNT, BY_EVENT, BY_ORDER, BY_LINE.'
        journalDatePolicy:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by journal date policy, stored as the enum name.
        name:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by name.
        or:
          description: Combine with another filter using OR.
          type: object
        outerAxis:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: 'Filter by outer axis, stored as the enum name: PER_DOCUMENT, PER_DAY, PER_MONTH.'
        platformCode:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: 'Filter by platform, e.g. SHOPIFY or LAZADA. isNull finds pooled profiles

            (existing rows that predate the platform being required).'
        resourceId:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by resource ID.
        status:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: 'Filter by status, ACTIVE or INACTIVE. Stored as the enum name, so match it

            exactly rather than by the label a screen shows.'
      type: object
    CreateEcommerceProfileRequest:
      properties:
        clearingAccountResourceId:
          description: 'Account that carries what the platform owes: every settlement balances to it,

            at the document''s net. Required.'
          type: string
        clearingAccounts:
          description: 'Per-payment-method clearing accounts. Absent or empty means every settlement

            uses clearingAccountResourceId.'
          items:
            $ref: '#/components/schemas/EcommerceClearingAccountInput'
          maxItems: 100
          type: array
        eventMappings:
          description: 'Where each event type posts. An entry names either an eventType or a family,

            never both; a family maps every event in it at once and a named eventType wins

            over its family. Fetch the catalogue first -- some families refuse a tax

            profile outright and sending one fails the whole save.'
          items:
            $ref: '#/components/schemas/EcommerceEventMappingInput'
          maxItems: 500
          type: array
        innerAxis:
          description: 'How lines are grouped inside a journal: BY_ACCOUNT, BY_EVENT, BY_ORDER or

            BY_LINE. Defaults to BY_EVENT.'
          enum:
          - BY_ACCOUNT
          - BY_EVENT
          - BY_ORDER
          - BY_LINE
          type: string
        journalDatePolicy:
          description: 'Which date values the journal: DOCUMENT_DATE, PERIOD_END or PAYOUT_DATE.

            Defaults to DOCUMENT_DATE. A policy whose date the document lacks falls back

            to the document date.'
          enum:
          - DOCUMENT_DATE
          - PERIOD_END
          - PAYOUT_DATE
          type: string
        journalReferenceTemplate:
          description: 'Journal reference template. Blank resets to the default. Placeholders

            {sourceType}, {externalId}, {documentDate} and {periodEnd} are substituted.'
          maxLength: 255
          type: string
        lineDescriptionTemplate:
          description: Journal line description template. Blank resets to the default.
          maxLength: 255
          type: string
        name:
          description: Display name (max 255, case-insensitive unique per organization). Required.
          example: Shopify SG
          maxLength: 255
          type: string
        outerAxis:
          description: 'How many journals one settlement becomes: PER_DOCUMENT, PER_DAY or PER_MONTH.

            Defaults to PER_MONTH.'
          enum:
          - PER_DOCUMENT
          - PER_DAY
          - PER_MONTH
          type: string
        platformCode:
          description: 'The platform (SHOPIFY, LAZADA, ...) this profile''s mapping is built for.

            Required: a profile cannot be saved without one. Fetch the catalogue''s event

            list scoped to this platform before mapping events.'
          example: SHOPIFY
          maxLength: 64
          type: string
      required:
      - clearingAccountResourceId
      - name
      - platformCode
      type: object
    OrganizationAccountNestedFilter:
      properties:
        accountClass:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by account class.
        accountType:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by account type.
        code:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by account code.
        name:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by account name.
        resourceId:
          allOf:
          - $ref: '#/components/schemas/StringExpression'
          description: Filter by account resource ID.
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Organization API key. Pass it in the x-jk-api-key header on every request.
      in: header
      name: x-jk-api-key
      type: apiKey
x-refined-from:
- tinvio-com-openapi-original.yaml
- tinvio-com-openapi.yml