openapi: 3.0.3
info:
  title: TI store inventory subscription API
  description: This API allows the user to subscribe to inventory back-in-stock notifications. When a part has stocked up, this API will generate a notification that is sent to your configured API via an HTTP POST request.
  version: 2.0.0
  contact:
    name: API Support
    url: https://api-portal.ti.com/support
servers:
  - url: 'https://transact.ti.com/v2'
    description: External Production API Gateway

security:
  - OAuth2: []

tags: 
  - name: Inventory subscriptions (test)
  - name: Inventory subscriptions
paths:
  '/store/subscriptions/inventory/test':
    post:
      tags:
        - Inventory subscriptions (test)
      security:
        - OAuth2: [] 
      description: >-
        Trigger a test notification to your system. This API will generate a mock notification and send to your configured API via an HTTP POST request according to the spec. It will then return the status code returned from your API, and - if unsuccessful - the response body (if any) via "Message"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryNotificationTestResponse'
              examples:
                successful:
                  value:
                    status: accepted
                failed:
                  value:
                    status: failed
                    responseCode: 401
                    message: "{\"Error\": \"Something went wrong\"}"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  '/store/subscriptions/inventory':
    get:
      description: >-
        Get all active subscriptions
      tags:
        - Inventory subscriptions
      operationId: getSubscriptionList
      security:
        - OAuth2: [] 
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventorySubscription'
              example:
                - tiPartNumber: "AFE7799IABJ"
                  requestedQty: 1000
                  currency: "USD"
                  autoSubscribe: true
                  expiration: 30
                  expirationDate: "2022-07-29"
                  creationTs: "2022-06-29T03:34:25+0000"
                  lastUpdatedTs: "2022-06-29T03:34:25+0000"
                - tiPartNumber: "OPA333AID"
                  requestedQty: 2500
                  currency: "CNY"
                  autoSubscribe: true
                  expiration: 30
                  expirationDate: "2022-07-30"
                  creationTs: "2022-06-30T03:34:25+0000"
                  lastUpdatedTs: "2022-06-30T03:34:25+0000"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      description: >-
        Create/update subscription
      tags:
        - Inventory subscriptions
      operationId: upsertSubscription
      security:
        - OAuth2: [] 
      requestBody:
        description: >-
          The subscription you want to create or update. If an active subscription exists for requested OPN, the subscription is updated with the new expiration and new requested qty. If an active subscription doesn't exist for requested OPN, a new subscription is created based on the specification.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventorySubscription'
            examples:
              AFE7799IABJ:
                value:
                  tiPartNumber: "AFE7799IABJ"
                  requestedQty: 1000
                  currency: "USD"
                  autoSubscribe: true
                  expiration: 30
              OPA333AID:
                value:
                  tiPartNumber: "OPA333AID"
                  requestedQty: 2500
                  currency: "CNY"
                  autoSubscribe: true
                  expiration: 30
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventorySubscription'
              examples:
                AFE7799IABJ:
                  value:
                    tiPartNumber: "AFE7799IABJ"
                    requestedQty: 1000
                    currency: "USD"
                    autoSubscribe: true
                    expiration: 30
                    expirationDate: "2022-07-29"
                    creationTs: "2022-06-29T03:34:25+0000"
                    lastUpdatedTs: "2022-06-29T03:34:25+0000"
                OPA333AID:
                  value:
                    tiPartNumber: "OPA333AID"
                    requestedQty: 2500
                    currency: "CNY"
                    autoSubscribe: true
                    expiration: 30
                    expirationDate: "2022-07-30"
                    creationTs: "2022-06-30T03:34:25+0000"
                    lastUpdatedTs: "2022-06-30T03:34:25+0000"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      callbacks:
        inventoryStockupEvent:
          '${companyProfile.inventoryAPI}':
            post:
              summary: >-
                Inventory Notification of stockup for subscribed part
              tags:
                - InventoryNotification
              description: >-
                The Inventory stockup notification spec sent to your API to notify you of a stockup
              security:
                - Basic: []
                - ApiKey: []
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/InventoryNotification'
              responses:
                '200':
                  description: >-
                    Acknowledgment of receipt of inventory notification
                  content:
                    application/json:
                      schema:
                        $ref: '#/components/schemas/InventoryNotificationResponse'
    delete:
      description: >-
        Delete all subscriptions for your Company Profile.
      tags:
        - Inventory subscriptions
      security:
        - OAuth2: [] 
      responses:
        '204':
          description: >-
            No Content - successful response
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  '/store/subscriptions/inventory/{tiPartNumber}':
    parameters:
      - name: tiPartNumber
        in: path
        description: >- 
          URL encoded unique identifier for the product (Orderable Part Number)

          Note: Part numbers that include /NOPB must be encoded prior to making the API call or the response will be a “not found” error. For example, LP2982AIM5-3.3/NOPB would need to be encoded as LP2982AIM5-3.3%2FNOPB. In addition, please make sure the encoding process does not have linefeed or new line breaks, such as: LP2989IM-2.5%2FNOPB%0A%0A, as this too will result in a product “not found” error. 
        required: true
        schema:
          type: string
          example: AFE7799IABJ
    get:
      description: >-
        Get a single active inventory subscription for you Company Profile matching the specified product identifier
      tags:
        - Inventory subscriptions
      operationId: getSubscriptionByProductId
      security:
        - OAuth2: [] 
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventorySubscription'
              examples:
                AFE7799IABJ:
                  value:
                    tiPartNumber: "AFE7799IABJ"
                    requestedQty: 1000
                    currency: "USD"
                    autoSubscribe: true
                    expiration: 30
                    expirationDate: "2022-07-29"
                    creationTs: "2022-06-29T03:34:25+0000"
                    lastUpdatedTs: "2022-06-29T03:34:25+0000"
                OPA333AID:
                  value:
                    tiPartNumber: "OPA333AID"
                    requestedQty: 2500
                    currency: "CNY"
                    autoSubscribe: true
                    expiration: 30
                    expirationDate: "2022-07-30"
                    creationTs: "2022-06-30T03:34:25+0000"
                    lastUpdatedTs: "2022-06-30T03:34:25+0000"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      description: >-
        Delete single active inventory subscription for your Company Profile.
      tags:
        - Inventory subscriptions
      security:
        - OAuth2: [] 
      responses:
        '204':
          description: >-
            No Content - successful response
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    OAuth2:
      type: 'oauth2'
      description: >-
        This API uses OAuth 2 with Client Credentials. See https://api-portal.ti.com/order-api-authentication
      flows:
        clientCredentials: 
          refreshUrl: 'https://transact.ti.com/v1/oauth'
          tokenUrl: 'https://transact.ti.com/v1/oauth'
          scopes: {}
  parameters:
    currencyParameter:
      name: currency
      in: query
      description: >-
        Specific currency for pricing information. Specify the currency using ISO 4217 alphabetic codes. If not specified, pricing in USD will be provided.
      required: false
      schema:
        type: string
        default: "USD"
        example: "USD" 
    excludeEVMsParameter:
      name: exclude-evms
      in: query
      description: >-
        Flag to exclude EVM (Evaluation Module) products from the result.  If not specified, EVMs are included.
      required: false
      schema:
        type: boolean
        default: false
        example: true
    pageParameter:
      name: page
      in: query
      description: >-
        The index of the page (starting at 0) to be returned from this request
      required: true
      schema:
        type: integer
        format: int32
        default: 0
        example: 0
    sizeParameter:
      name: size
      in: query
      description: >-
        The page size between 1 and 100 to be returned
      required: true
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 20
        example: 20
  responses:
    UnprocessableEntity:
      description: 422 Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: ERR-TICOM-INV-API-1001
                type: Validation
                section: InventorySubscription
                field: tiPartNumber
                reason: Invalid tiPartNumber
                message: "tiPartNumber 'DOESNOTEXIST' is not a valid product. Please provide a valid tiPartNumber."
              - errorCode: ERR-TICOM-INV-API-1001
                type: Validation
                section: InventorySubscription
                field: currency
                reason: Invalid currency
                message: "currency 'DOESNOTEXIST' is not a valid currency. Please provide a valid currency."
    Unauthorized:
      description: 401 Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: ERR-TICOM-INV-API-1004
                type: Security
                reason: "Invalid Credentials"
                message: "Provide a valid Bearer token"
    Forbidden:
      description: 403 Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: ERR-TICOM-INV-API-1004
                type: Security
                reason: "Invalid Credentials"
                message: "Provide a valid Bearer token"
    NotFound:
      description: 404 Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: ERR-TICOM-INV-API-1002
                type: ResourceNotFound
                section: Path
                field: tiPartNumber
                reason: "Resource could not be found"
                message: "Product not found for 'DOESNOTEXIST'"
    MethodNotAllowed:
      description: 405 Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: TI-API-00356
                type: Validation
                reason: Invalid method
                message: "PATCH is not a supported method."
    TooManyRequests:
      description: 429 Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: TI-API-00235
                type: Security
                reason: Too many requests
                message: Rate Limit Quota Hit.
    InternalServerError:
      description: 500 Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: TI-API-00556
                type: Unknown
                reason: Service unavailable
                message: This service is temporarily unavailable. Please contact support.
  schemas:
    Error:
      title: Error
      description: >-
        Standard error response
      type: object
      properties:
        errors:
          type: array
          description: >-
            Error messages
          items:
            type: object
            properties:
              errorCode:
                type: string
                description: >-
                  Unique code for the error returned.
                example: "ERR-TICOM-INV-API-1001"
              type:
                type: string
                description: >-
                  Classification of the error.
                example: Validation
              section:
                type: string
                description: >-
                  Used primarily for validation errors. Provides the section of the request where the vaiolating field can be found.
                example: "InventorySubscription"
              field:
                type: string
                description: >-
                  The name of the field that failed validation, if applicable
                example: "tiPartNumber"
              reason:
                type: string
                description: >-
                  The reason for the error. Details why the request was rejected.
                example: >-
                  Invalid tiPartNumber.
              message:
                type: string
                description: >-
                  Details of the specific error and the to take to resolve. For validation errors, this message includes details such as the value that was invalid as well as the constraints.
                example: >-
                  tiPartNumber 'DOESNOTEXIST' is not a valid product. Please provide a valid tiPartNumber.
    Product:
      title: Product
      description: Product attributes
      type: object
      properties:
        tiPartNumber:
          type: string
          description: >- 
            The unique identifier of the product (the orderable part number).
          example: "AFE7799IABJ"
        genericPartNumber:
          type: string
          description: >- 
            The generic part number of the product (also referred to as the base part number)
          example: "AFE7799"
        buyNowURL:
          type: string
          description: >-
            The URL to purchase the product in the TI store
          example: "https://www.ti.com/product/AFE7799/part-details/AFE7799IABJ"
        quantity:
          type: integer
          description: >- 
            The inventory quantity currently on hand for sale in the TI store
          format: int32
          example: 5435
        limit:
          type: integer
          description: >-
            The order limit on TI.com store
          example: 50
        pricing:
          type: array
          description: >-
            Price break information by currency
          items:
            $ref: '#/components/schemas/Pricing'
        description:
          type: string
          description: >-
            Description of the product
          example: "8-Bit 200MSPS Low-Power Analog-to-Digital Converter (ADC) With Internal Sample and Hold"
        minimumOrderQuantity:
          type: integer
          description: >-
            The minimum order quantity (MOQ) of the product for the TI store
          format: int32
          example: 1          
        standardPackQuantity:
          type: integer
          description: >- 
            The standard package quantity (SPQ) of the product
          format: int32
          example: 126          
        exportControlClassificationNumber:
          type: string
          description: >-
            The Export Control Classification Number (ECCN) for the product
          example: "EAR99"
        htsCode:
          type: string
          description: >-
            The 10-digit Harmornized Tariff Schedule Code for the product
          example: "8542390001"          
        pinCount:
          type: integer
          description: >-
            The pin count of the product
          format: int32
          example: 5
        packageType:
          type: string
          description: >-
            The package type of the product
          example: "SOT-23 (DBV)"
        packageCarrier:
          type: string
          description: >-
            The carrier type for the product
          example: "Large T&R"
        customReel:
          type: boolean
          description: >-
            Indicates whether custom reel carrier is available
          example: true
        lifeCycle:
          type: string
          description: >-
            The product lifecycle status
          example: "ACTIVE"
    Pricing:
      title: Pricing
      description: Price breaks by quantity
      type: object
      properties:
        currency:
          type: string
          description: >-
            Pricing currency ISO 4217 code
          example: "USD"
        priceBreaks:
          type: array
          description: >-
            Price breaks
          items:
            type: object
            properties:
              priceBreakQuantity:
                type: integer
                description: >-
                  Price break quantity
                format: int32
              price:
                type: number
                description: >- 
                  The corresponding price for the price break quantity
          example:
            - priceBreakQuantity: 1
              price: 2.03
            - priceBreakQuantity: 10
              price: 1.43
            - priceBreakQuantity: 25
              price: 1.35
            - priceBreakQuantity: 100
              price: 1.10
            - priceBreakQuantity: 200
              price: 1.00
            - priceBreakQuantity: 350
              price: 0.95
            - priceBreakQuantity: 600
              price: 0.90
            - priceBreakQuantity: 750
              price: 0.85
    InventorySubscription:
      title: Inventory Subscription
      description: >-
        Subscription for an out of stock product. Active subscriptions will trigger inventory notifications to an API configured in your company profile.
      type: object
      properties:
        tiPartNumber:
          type: string
          description: >-
            The unique identifier of the product (the orderable part number) to which this subscription applies.
          example: "AFE7799IABJ"
        requestedQty:
          type: integer
          format: int32
          description: >-
            The inventory quantity for this subscription. Defines the minimum limit for which an an inventory notification should be triggered. For example, if RequestedQty = 1000, then a restock from 0 to 500 for the requested product will not trigger a notification; however, a restock from 0 to 1500 would trigger an inventory notification to your API.
          example: 1000
        currency:
          type: string
          description: >-
            Specific currency to be provided in the pricing provided in the inventory notification. Specify the currency using ISO 4217 alphabetic codes. If not specified, pricing in USD will be provided.
          example: "USD"
        autoSubscribe:
          type: boolean
          default: true
          description: >-
            Flag to enable/disable auto-renewal of the subscription. By default, once an inventory notification is sent, the subscription is removed. However, if AutoSubscribe is true, the subscription will remain active until it reaches its expiration date or is deleted by you.
          example: true
        expiration:
          type: integer
          format: int32
          default: 30
          description: >-
            The duration in days for the subscription. This defines the length of the subscription, and once the number of days has been reached, a new subscription must be created.
          minimum: 1
          maximum: 30
          example: 30
        expirationDate:
          type: string
          format: date
          description: >-
            The date this subscription will expire, in the format YYYY-MM-DD
          readOnly: true
          example: "2022-06-29"
        creationTs:
          type: string
          format: date-time
          description: >-
            The timestamp when this subscription was created, in the format YYYY-MM-DD'T'HH24:mm:ss+ZZZZ
          readOnly: true
          example: "2022-06-29T03:34:25+0000"
        lastUpdatedTs:
          type: string
          format: date-time
          description: >-
            The timestamp when this subscription was last updated, in the format YYYY-MM-DD'T'HH24:mm:ss+ZZZZ
          readOnly: true
          example: "2022-06-29T03:34:25+0000"
    InventoryNotification:
      title: Inventory Notification
      description: The notification sent to API on inventory stockup event for a subscribed product meeting requestedQty.
      type: object
      required:
        - type
        - data
      properties:
        type:
          type: string
          description: >-
            The type of the notification. For inventory subscriptions, notifications from these subscriptions are classified as "inventory"
          example: "inventory"
        data:
          $ref: '#/components/schemas/Product'
    InventoryNotificationResponse:
      title: Inventory Notification Response
      description: The standard response to Inventory Notifications - the acknowledgment of successful receipt
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: >-
            The status of the notificiation receipt. Standard successful response should be "accepted"
          default: "accepted"
          example: "accepted"
    InventoryNotificationTestResponse:
      title: Inventory Notification Test Response
      description: >-
        The extended response for notification tests that includes response code and response message for connectivity testing.
      allOf:
        - $ref: '#/components/schemas/InventoryNotificationResponse'
        - type: object
          properties:
            responseCode:
              type: integer
              format: int32
              description: >-
                The HTTP status code of the response received by the API. Used primarily in unsuccessful responses and used for debugging connectivity. Will return 0 for IO errors and failure to receive any response.
              example: 401
            message:
              type: string
              description: >-
                The message returned from the API (if applicable). Used primarily for unsuccessful responses, and used for debugging connectivity
              example: "{\"Error\": \"Something went wrong\"}"