PartsTech Session Cart API

openapi: 3.2.0
info:
  version: 2.021.1
  title: PartsTech Session Cart API
  description: '# Rate Limiting


    Requests can be limited by user requests, by private partner requests and by all requests with partner''s credentials.'
  x-logo:
    url: https://partstech.com/wp-content/uploads/2025/03/PartsTech_OEC-compnay_logo.svg
    altText: PartsTech logo
servers:
- url: https://api.partstech.com
  description: Production server
- url: https://api.beta.partstech.com
  description: Beta server
tags:
- name: session-cart
  description: Cart by Session
  x-displayName: Cart by Session
paths:
  /punchout/cart/submit:
    post:
      summary: Submit Cart
      description: 'Orders all of the parts in the cart for the provided punchout `sessionId`.


        Returns the orders that were placed.'
      operationId: submitCart
      x-operation-name: CommandPunchoutCartSubmit
      tags:
      - session-cart
      security:
      - bearerAuth:
        - user
      - apiKeyAuth:
        - user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sessionId
              properties:
                sessionId:
                  type: string
                  description: The unique identifier of a punchout session.
                  example: 1ag3d2b5240e4jcbbe3ee9c49c929fe4
                orderParams:
                  type:
                  - array
                  - 'null'
                  description: To provide additional options for specific orders, such as `poNumber` and `notes`.
                  items:
                    type: object
                    required:
                    - storeId
                    properties:
                      storeId:
                        type: integer
                        description: PartsTech's ID for a supplier location. Identifies an order in the cart.
                      poNumber:
                        type:
                        - string
                        - 'null'
                        description: Optional. If a value is included here, any PO number provided earlier in the quoting process for the specified order will be overwritten.
                        deprecated: true
                      notes:
                        type:
                        - string
                        - 'null'
                        description: Optional. If a value is included here, any supplier notes provided earlier in the quoting process for the specified order will be overwritten.
                poNumber:
                  type:
                  - string
                  - 'null'
                  description: 'Optional.


                    If a value is included here, it will overwrite any previously provided PO numbers for all orders in the session.

                    '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PunchoutPurchasedCartResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidRequestError'
                - $ref: '#/components/schemas/RequiredAdditionalParametersError'
                - $ref: '#/components/schemas/EmptyCartError'
        '402':
          description: Some orders are not available for purchasing
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/OrderAvailabilityError'
                - $ref: '#/components/schemas/OrderNotPlacedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/Error'
                  example:
                    error:
                      code: NotFound
                      message: Session was not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockedSessionError'
        '432':
          description: Integration Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
  /punchout/cart/info:
    post:
      summary: Get Cart
      description: 'Gets the current cart information for the provided `sessionId`.


        **Note**: For desktop applications that lack the ability to use cart callback functionality, this method should be used to get cart information. In this case, our cart buttons cannot be used. The partner application will need to add a button on the PartsTech punchout for users to click when they are ready to transfer cart items to the partner application.'
      operationId: getCart
      x-operation-name: QueryPunchoutCartInfo
      tags:
      - session-cart
      security:
      - bearerAuth:
        - user
      - apiKeyAuth:
        - user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sessionId
              properties:
                sessionId:
                  type: string
                  example: 1ag3d2b5240e4jcbbe3ee9c49c929fe4
                  description: The unique identifier of a punchout session.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PunchoutCartResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidRequestError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/Error'
                  example:
                    error:
                      code: NotFound
                      message: Session was not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockedSessionError'
  /punchout/cart/availability:
    post:
      summary: Check Cart Availability
      description: 'Gets real-time pricing and availability information directly from suppliers for each cart item of the provided `sessionId`. Pricing and availability can change from the time an item is quoted, to the time it is ordered. This method should be used before attempting to place an order, so users can be notified of any price changes or unavailable items.


        **Note**: While the PartsTech API is optimized to deliver quick responses, this endpoint depends on the response times of suppliers'' APIs, which may vary.


        If all items are available in the requested quantities, a successful response with a 200 HTTP status code will be returned. The response will include a list of orders with the current cost of each item. Make sure to check other pricing fields for any changes that would affect the total cost, such as `shippingPrice` or `fet` (if applicable).


        If there are pricing changes, it is recommended to update the necessary values in the work order and inform the user about the changes. The user can decide whether to proceed with the order at the updated total cost or not.


        When one or more items are unavailable for ordering, a response with a 402 HTTP status code will be returned. The response will contain details about the availability error, including which items were unavailable and errors fields specifying the reason for each item.


        In such cases, it is highly recommended to inform the user about the unavailable items and let them decide on the next steps. They may choose to proceed with ordering the available items and return later for the currently unavailable ones when they become available. Alternatively, they can punchout to PartsTech to explore alternative items that are currently available for immediate ordering.'
      operationId: checkCartAvailability
      x-operation-name: QueryPunchoutCartAvailability
      tags:
      - session-cart
      security:
      - bearerAuth:
        - user
      - apiKeyAuth:
        - user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sessionId
              properties:
                sessionId:
                  type: string
                  example: 1ag3d2b5240e4jcbbe3ee9c49c929fe4
                  description: The unique identifier of a punchout session.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PunchoutCartResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidRequestError'
                - $ref: '#/components/schemas/RequiredAdditionalParametersError'
        '402':
          description: Some orders are not available for purchasing
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/OrderAvailabilityError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/Error'
                  example:
                    error:
                      code: NotFound
                      message: Session was not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockedSessionError'
        '432':
          description: Integration Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
components:
  schemas:
    PaidOrderStore:
      description: Store Data for Paid Orders
      allOf:
      - $ref: '#/components/schemas/OrderStore'
      - type: object
        required:
        - sellerId
        properties:
          sellerId:
            type:
            - string
            - 'null'
    Brand:
      type: object
      description: Contains brand information about a part.
      required:
      - brandID
      - brandName
      properties:
        brandID:
          type: string
          example: BBCM
          description: The ID of a brand from the Autocare Association.
        brandName:
          type: string
          example: Alba
          description: The name of a brand.
        id:
          description: PartsTech's ID for a brand.
          type:
          - integer
          - 'null'
          example: 1
        displayName:
          type:
          - string
          - 'null'
          example: Alba
        lineCode:
          type:
          - string
          - 'null'
      example:
        brandID: BBHK
        brandName: Bosch
        id: 551
        displayName: Bosch
    OrderAvailabilityError:
      description: Some orders are not available for purchasing
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
        errorDetails:
          type: array
          items:
            type: object
            required:
            - supplier
            - store
            properties:
              supplier:
                $ref: '#/components/schemas/BriefSupplier'
              store:
                $ref: '#/components/schemas/BriefStore'
              errors:
                type: array
                items:
                  type: string
              parts:
                type: array
                items:
                  type: object
                  required:
                  - orderItemId
                  - partId
                  - quantity
                  properties:
                    orderItemId:
                      type: string
                      description: The unique identifier for an item added to a cart. This ID allows PartsTech to reference a specific item in a specific session and its cart details (e.g. PO number, supplier notes, delivery method).
                    partId:
                      type: string
                    quantity:
                      type: integer
                    errors:
                      type: array
                      items:
                        type: string
        localInventoryItemErrors:
          type: array
          items:
            type: object
            required:
            - itemId
            - inventoryUID
            - partId
            - quantity
            - errors
            properties:
              itemId:
                type: string
                example: 0ze4f01824764a61991b9d090fdc1813
                description: 'The unique identifier for an item added to a cart.

                  This ID allows PartsTech to reference a specific item in a specific session and its cart details (e.g. PO number, supplier notes, delivery method)."

                  '
              inventoryUID:
                type: string
                example: 123123123
                description: ID of item in local inventory.
              partId:
                type: string
                example: ABCD-12345
                description: PartsTech's ID for a part. Consists of `brandId`-`partNumber`.
              quantity:
                type: integer
                example: 2
                description: The requested quantity for a part.
              errors:
                type: array
                description: List of errors.
                items:
                  type: string
      example:
        error:
          code: OrderAvailabilityError
          message: Some orders are not available for purchasing
    PunchoutOrderPart:
      type: object
      required:
      - orderItemId
      - partId
      - quantity
      - price
      - partName
      - partNumber
      - partstechCatalogURL
      - availability
      - bundled
      - brand
      properties:
        orderItemId:
          type: string
          example: 0ze4f01824764a61991b9d090fdc1813
          description: The unique identifier for an item added to a cart. This ID allows PartsTech to reference a specific item in a specific session and its cart details (e.g. PO number, supplier notes, delivery method).
        partId:
          type: string
          example: ABCD-12345
          description: PartsTech's ID for a part. Consists of `brandId`-`partNumber`.
        lineCardId:
          type:
          - string
          - 'null'
          example: 123
          description: PartsTech's ID for a line code. Makes part selection much more accurate when provided in requests to create a cart or search the PartsTech Catalog.
        quantity:
          type: integer
          example: 2
          description: The requested quantity for a part.
        price:
          $ref: '#/components/schemas/PartPrice'
        partName:
          type: string
          example: Motorcraft Engine Oil Filter
          description: The name of the part. Part name is typically the brand name + the part type name. For tires it is typically the brand name + model. There is a shop setting that can be enabled to remove the brand name from this field for all parts (tires excluded).
        partNumber:
          type: string
          example: 12345
          description: The manufacturer part number.
        variationId:
          type:
          - string
          - 'null'
          deprecated: true
        imageUrl:
          type:
          - string
          - 'null'
          format: url
          description: The URL of the part image that PartsTech uses for the part.
          example: https://image.partstech.com/d1/images/e4/11/71/w110_e411711499973c7640e852e84ed20fca0cd5c9d2.png
        partstechCatalogURL:
          type: string
          format: url
          description: The URL of the part's description on PartsTech.
          example: https://punchout.partstech.com/Motorcraft-Engine-Oil-Filter/details/BBRH-FL-500-S?part_term=5340
        availability:
          type: boolean
          example: true
          description: Returns true if the part is available at the time of quoting.
        backOrder:
          type: boolean
          example: true
          description: Returns true if the requested quantity is more than the available quantity and the remaining quantity will be back ordered.
        bundled:
          type: boolean
          example: true
          description: Returns true if the part is included in a bundled deal with one or more other parts in the order.
        vehicleId:
          type:
          - integer
          - 'null'
          description: PartsTech's ID for a vehicle.
        vehicleName:
          type:
          - string
          - 'null'
          description: Name of the vehicle selected for fitment during the PartsTech session. Typically consists of year, make, model, and engine.
        brand:
          $ref: '#/components/schemas/Brand'
        taxonomy:
          $ref: '#/components/schemas/ResponseTaxonomy'
        partCategory:
          $ref: '#/components/schemas/PartCategory'
        tireSize:
          type:
          - string
          - 'null'
          deprecated: true
        searchedAsPartNumber:
          type:
          - string
          - 'null'
        rewards:
          $ref: '#/components/schemas/Rewards'
        selectedLaborItems:
          type:
          - array
          - 'null'
          description: 'Labor items that were selected by user.


            Labor items may be attached to items and cart/punchout session.


            Selected labor items are not used (they will not be copied or returned) in next methods:

            - [Create Custom Cart](#operation/customCartCreate)

            - [Order Custom Cart](#operation/submitItems)

            - [Check Custom Cart Availability](#operation/checkItemsAvailability)

            '
          items:
            $ref: '#/components/schemas/PunchoutLaborItem'
        storesAvailability:
          type:
          - array
          - 'null'
          items:
            type: object
            minProperties: 2
            required:
            - quantity
            properties:
              specificName:
                type: string
                example: In network
              store:
                $ref: '#/components/schemas/BriefStore'
              quantity:
                type: integer
                example: 3
              main:
                type: boolean
                example: true
        attributes:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Attribute'
        deliveryNotes:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryNote'
        itemizedQuote:
          $ref: '#/components/schemas/ItemizedItemQuote'
    PartPrice:
      type: object
      required:
      - cost
      - core
      - fet
      properties:
        list:
          type:
          - number
          - 'null'
          format: float
          example: 1.2
          description: Not all parts will have a list price. This property will contain the null value for parts without a list price.
        price:
          type: number
          format: float
          example: 1.6
          description: Total price charged to the user for an item, includes discounts and core charge if applicable.
        cost:
          type: number
          format: float
          example: 1.24
          description: Cost of an item for the user including any discounts. Excludes any core charges.
        core:
          type: number
          format: float
          example: 0.4
          description: A fee for certain part types that is returned to the purchaser when the old part that is being replaced is returned to the store.
        fet:
          type:
          - number
          - 'null'
          description: The Federal Excise Tax (FET) applies to tires used on the road with a maximum load capacity greater than 3500 pounds. This tax is charged to the purchaser of the tire from the tire supplier. Only 100% accurate FET values are sent through the PartsTech API.
          format: float
          example: 1.2
        retail:
          type:
          - number
          - 'null'
          description: The price to charge customers. PartsTech calculates this price by taking the ``cost`` and then applying the appropriate mark up from the user's retail pricing configuration. This property will be null if there is no applicable mark up to the item or if the user has not set up their retail pricing configuration.
          format: float
          example: 2
        discount:
          type:
          - number
          - 'null'
          description: The discount for an item. There can be a discount when an item is quoted or purchased as part of a bundled deal from participating suppliers.
          format: float
          example: 0.2
        map:
          type:
          - number
          - 'null'
          description: Minimum Advertised Price
          format: float
          example: 1.9
    OrderNotPlacedError:
      description: The Order(s) cannot be placed due to required credit card transaction
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
        sessionId:
          type:
          - string
          - 'null'
          description: The identifier of a punchout session.
        redirectUrl:
          type:
          - string
          - 'null'
          format: url
      example:
        error:
          code: OrderNotPlacedError
          message: Order cannot be placed without going through the cart. One of the suppliers requires credit card transaction.
        sessionId: Session id
        redirectUrl: http://localhost:80/redirect-url
    ItemizedItemQuote:
      type:
      - object
      - 'null'
      required:
      - tax
      - lines
      properties:
        tax:
          type: number
          format: float
        lines:
          type: array
          items:
            $ref: '#/components/schemas/ItemizedQuotePricingLine'
    Rewards:
      type:
      - array
      - 'null'
      minItems: 0
      items:
        type: object
        properties:
          program:
            type:
            - string
            - 'null'
          points:
            type:
            - integer
            - 'null'
          bonusPoints:
            type:
            - integer
            - 'null'
    Attribute:
      type: object
      properties:
        name:
          type: string
        label:
          type: string
        value:
          type: string
        type:
          type: string
          enum:
          - Vehicle
          - Part
          - Both
        dbInfo:
          type:
          - object
          - 'null'
          required:
          - dbName
          - tableName
          - idFieldName
          - idValue
          properties:
            dbName:
              type: string
            tableName:
              type: string
            idFieldName:
              type: string
            idValue:
              type: string
    PartCategory:
      type:
      - string
      - 'null'
      enum:
      - Maintenance
      - Service
      - Consumable
    PunchoutOrder:
      type: object
      required:
      - supplier
      - store
      - delivery
      - buyerShop
      - tax
      - totalPrice
      - totalDiscount
      - coreCharge
      - fet
      - shippingPrice
      - paymentType
      - parts
      properties:
        supplier:
          $ref: '#/components/schemas/CartSearchSupplier'
        store:
          oneOf:
          - $ref: '#/components/schemas/OrderStore'
          - $ref: '#/components/schemas/PaidOrderStore'
        delivery:
          description: Delivery details
          type: object
          required:
          - price
          properties:
            name:
              type:
              - string
              - 'null'
              example: hotshot
              description: Type of delivery
            price:
              type: number
              format: float
              example: 1.24
              description: Cost of delivery
        buyerShop:
          $ref: '#/components/schemas/Address'
        tax:
          type: number
          format: float
          example: 9.01
          description: Sales tax, if applicable. Typically shops are tax-exempt.
        totalPrice:
          type: number
          format: float
          example: 25
          description: Total price charged to the user for an order, includes discounts and core charge if applicable.
        totalDiscount:
          type: number
          format: float
          example: 5
          description: Total discounts for an order
        coreCharge:
          type: number
          format: float
          example: 12
          description: A fee for certain part types that is returned to the purchaser when the old part that is being replaced is returned to the store.
        fet:
          type: number
          description: The Federal Excise Tax (FET). The tax imposed by the federal government on tires used on the road with a maximum load capacity greater then 3500 pounds. Only 100% accurate FET values are present in this field.
          format: float
          example: 1.2
        shippingPrice:
          type: number
          format: float
          example: 1.24
          description: Cost of delivery.
        paymentType:
          type: string
          enum:
          - CreditCard
          - Wholesale
        parts:
          type: array
          items:
            $ref: '#/components/schemas/PunchoutOrderPart'
        poNumber:
          type:
          - string
          - 'null'
          example: 2743
          description: The purchase order number
        notes:
          type:
          - string
          - 'null'
          example: Notes
          description: Supplier notes
    DeliveryNote:
      type: object
      required:
      - label
      - text
      - date
      properties:
        label:
          type:
          - string
          - 'null'
        text:
          type:
          - string
          - 'null'
    LockedSessionError:
      description: Another current action blocks executing
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      example:
        error:
          code: LockedSession
          message: One of cart operations in progress
    EmptyCartError:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      example:
        error:
          code: EmptyCartError
          message: Can`t process cart. Cart is empty
    PunchoutCartResponse:
      type: object
      required:
      - sessionId
      - orders
      properties:
        sessionId:
          type: string
          example: 1ag3d2b5240e4jcbbe3ee9c49c929fe4
          description: The unique identifier of a punchout session.
        orders:
          type: array
          items:
            $ref: '#/components/schemas/PunchoutOrder'
        localInventoryItems:
          type: array
          items:
            $ref: '#/components/schemas/CartLocalInventoryItem'
        redirectUrl:
          type: string
          example: https://app.partstech.com/api-search/your_partnerId/your_test_userId/1ag3d2b5240e4jcbbe3ee9c49c929fe4/
        selectedLaborItems:
          type:
          - array
          - 'null'
          description: 'Labor items that were selected by user.


            Labor items may be attached to items and cart/punchout session.


            Selected labor items are not used (they will not be copied or returned) in next methods:

            - [Create Custom Cart](#operation/customCartCreate)

            - [Order Custom Cart](#operation/submitItems)

            - [Check Custom Cart Availability](#operation/checkItemsAvailability)

            '
          items:
            $ref: '#/components/schemas/PunchoutLaborItem'
    RequiredAdditionalParametersError:
      description: Supplier requires additional parameters that should be filled in the cart.
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
        sessionId:
          type:
          - string
          - 'null'
          description: The identifier of a punchout session.
        redirectUrl:
          type:
          - string
          - 'null'
          format: url
      example:
        error:
          code: RequiredAdditionalParametersError
          message: Supplier requires additional parameters that should be filled in the cart.
        sessionId: Session id
        redirectUrl: http://localhost:80/redirect-url
    PunchoutPurchasedCartResponse:
      type: object
      required:
      - sessionId
      - orders
      properties:
        sessionId:
          type: string
          example: 1ag3d2b5240e4jcbbe3ee9c49c929fe4
          description: The unique identifier of a punchout session.
        orders:
          type: array
          items:
            $ref: '#/components/schemas/PunchoutPurchasedOrder'
        localInventoryItems:
          type: array
          items:
            $ref: '#/components/schemas/CartLocalInventoryItem'
        redirectUrl:
          type: string
          example: https://app.partstech.com/api-search/your_partnerId/your_test_userId/1ag3d2b5240e4jcbbe3ee9c49c929fe4/
        selectedLaborItems:
          type:
          - array
          - 'null'
          description: 'Labor items that were selected by user.


            Labor items may be attached to items and cart/punchout session.


            Selected labor items are not used (they will not be copied or returned) in next methods:

            - [Create Custom Cart](#operation/customCartCreate)

            - [Order Custom Cart](#operation/submitItems)

            - [Check Custom Cart Availability](#operation/checkItemsAvailability)

            '
          items:
            $ref: '#/components/schemas/PunchoutLaborItem'
    CartSearchSupplier:
      allOf:
      - $ref: '#/components/schemas/BriefSupplier'
      - type: object
        required:
        - allowStoreSelect
        - availabilitySelect
        properties:
          allowStoreSelect:
            type: boolean
            description: If true for a supplier, users have the option to select a specfic store when sourcing parts.
          availabilitySelect:
            type: boolean
            description: If true for a supplier, users are required to select a specific store when sourcing parts.
          postOrderUpdates:
            type: boolean
            description: If true for a supplier, order can be updated after they placed.
    PunchoutPurchasedOrder:
      allOf:
      - type: object
        required:
        - id
        - orderUrl
        properties:
          id:
            description: The PartsTech ID for the order.
            type: integer
            example: 128577
          orderUrl:
            type: string
            example: https://app.partstech.com/some-invoice-url
            description: The URL of the PartsTech order details page.
      - $ref: '#/components/schemas/PunchoutOrder'
    InvalidRequestError:
      description: Malformed request. The request body is not parse-able or with invalid content.
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
        validationErrors:
          type: array
          items:
            type: string
      example:
        error:
    

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/partstech/refs/heads/main/openapi/partstech-session-cart-api-openapi.yml