PartsTech Punchout Cart API

openapi: 3.2.0
info:
  version: 2.021.1
  title: PartsTech Punchout Cart API
  description: "\n# Rate Limiting\n\nRequests can be limited by user requests, by private partner requests and by all requests with partner's credentials.\nIt has several time intervals:\n  - *Per day* restricts count of requests made in one day.\n  - *Requests per second* restricts count of requests made in one second.\n  - *Concurrent requests* restricts count of parallel requests.\n  - *Sliding 15 minutes* restricts count of requests made in last 15 minutes.\n\n**Note**: Every method has own separate sets of the limits.\n\n## Headers\nUse the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.\nThe HTTP header is returned only for one general limit or for limit that user reached.\n\n\n*Headers*\n  - the rate limit ceiling for that given endpoint:\n  ```\n  x-rate-limit-limit: 1000\n  ```\n  - the number of requests left:\n  ```\n  x-rate-limit-remaining: 570\n  ```\n  - the remaining window before the rate limit resets, in UTC [epoch seconds](https://en.wikipedia.org/wiki/Unix_time):\n  ```\n  x-rate-limit-reset: 1552003200\n  ```\n\nWhen an application exceeds the rate limit for a given standard API endpoint,\nthe API will return a HTTP 429 “Too Many Requests” response code, and the following error will be returned in the response body:\n```\n{\n  \"error\": {\n    \"code\": \"TooManyRequests\",\n    \"message\": \"Some description\"\n  }\n}\n```\n\n# Pagination\n\nWhen you call an API method to retrieve information, it can be returned to you in portions.\nCheck out more detail below on pagination in API methods, including how to use them and which methods follow the pattern.\n\nAPI methods that supports pagination will return the `Link` header. It will include available urls of `first`, `last`, `previous` and `next` pages.\n\n```\nLink: <https://api.partstech.com/purchases?page=1>; rel=\"first\"\nLink: <https://api.partstech.com/purchases?page=1>; rel=\"previous\"\nLink: <https://api.partstech.com/purchases?page=3>; rel=\"next\"\nLink: <https://api.partstech.com/purchases?page=142>; rel=\"last\"\n```\n\n# MOTOR Compliance Requirements\n\nAll MOTOR-powered endpoints (Labor, Maintenance Schedules, Fluids, and Specifications) return a `Link` header\ncontaining the URL to MOTOR's OEM Compliance Requirements documentation.\n\nThe header follows the [RFC 8288 (Web Linking)](https://tools.ietf.org/html/rfc8288) format:\n\n```\nLink: <https://www.motor.com/oem-compliance-requirements/>; rel=\"compliance\"\n```\n\n# Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:\n\n```\n{\n  \"error\": {\n    \"code\": \"InternalErrorCode\",\n    \"message\": \"Some description\"\n  }\n}\n```\n\n# Error Responses\nSome default error responses used in the API.\n\nHttp Code  | Explanation | Content Type | Used error codes\n----------------|-------------|------------------|---------\n400 | Bad Request. The request was unacceptable. | `application/json` | `InvalidRequestSyntax`\n401 | Unauthorized. The request requires user or partner credentials or bearer token. Also used for invalid credentials or bearer token. | `application/json` | `InvalidToken`, `UserAuthenticationFailed`, `PartnerAuthenticationFailed`\n402 | Request Failed. The parameters were valid but the request failed. | `application/json` | Different codes, depend on method.\n403 | Forbidden. Also used for unauthorized requests such as improper credentials scopes or permissions issues. | `application/json` | `IncorrectMode`, `DisabledApiUsage`, `UserIsNotActivated`, `HaveNotPermission`, `NotAvailableMethod`\n404 | Some data in the request is not found. Or incorrect url was used. | `application/json`, `text/html`, no content | `NotFound`\n405 | Method not allowed. | `application/json`, `text/html`, no content |\n406 | Unacceptable content type. Client sent an accepts header for a content type which does not exist on the server. | No content |\n409 | Locked. One of the another operations that is in progress blocks this method call. | `application/json` | `LockedSession`\n429 | Too Many Requests | `application/json` | `TooManyRequests`\n432 | Integration Error | `application/json` |\n500 | Internal Server Error. (This is rare.) | `application/json` | `InternalError`\n501 | Not Implemented | `application/json` | `MethodNotImplemented`\n503 | The backend server is not available. (This is rare.) | No content |\n"
  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: punchout-cart
  description: Cart with Punchout
  x-displayName: Cart with Punchout
paths:
  /punchout/cart/create:
    post:
      summary: Create Cart
      description: 'Creates a new punchout session and forms a cart with the provided parts. Orders are separated by supplier store.


        For partners that use our Catalog quoting API, use this method to create a cart for placing orders.


        In this method PartsTech attempts to find the correct parts for each order, given the part information that is provided in the request. The more part information that is provided in the request, the more accurate and efficient the parts selection will be. In addition to the required fields, providing at least each part''s `lineCardId` will enable a much more accurate parts selection. In some cases, providing only the `storeId` and `partId` is not enough to uniquely identify a part.


        Returns a unique `sessionId` and `redirectUrl` to get access to the punchout session through the site.

        '
      operationId: createCart
      x-operation-name: CommandPunchoutCartCreate
      tags:
      - punchout-cart
      security:
      - bearerAuth:
        - user
      - apiKeyAuth:
        - user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - orders
              properties:
                orders:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                    - storeId
                    - parts
                    properties:
                      storeId:
                        description: PartsTech's ID for a supplier location.
                        type: integer
                        example: 1
                      parts:
                        type: array
                        minItems: 1
                        items:
                          type: object
                          required:
                          - partId
                          - quantity
                          properties:
                            partId:
                              description: PartsTech's ID for a part. Consists of `brandId`-`partNumber`.
                              type: string
                              example: ABCD-12345
                            lineCardId:
                              description: PartsTech's ID for a line code. Makes part selection much more accurate when provided in the request. It is required for tire suppliers with the `availabilitySelect` option. For other suppliers it is not required.
                              type:
                              - integer
                              - 'null'
                              example: 123
                            quantity:
                              description: The requested quantity for a part.
                              type: integer
                              example: 10
                              minimum: 1
                              maximum: 999
                            vehicleId:
                              description: PartsTech's ID for a vehicle.
                              type:
                              - integer
                              - 'null'
                              default: null
                            partTypeId:
                              description: The ID of a part type from the Autocare Association's PCdb.
                              type:
                              - integer
                              - 'null'
                              default: null
                            selectedStore:
                              description: The supplier store to get the part from. Only required for suppliers with the `availabilitySelect` option. The value to include here is a `specificName` from `storesAvailability` of the part.
                              type:
                              - string
                              - 'null'
                      poNumber:
                        type:
                        - string
                        - 'null'
                        description: Prefilling of purchase order number in the order. Will be sent to the Supplier when the order is placed.
                        example: Some PoNumber
                      notes:
                        type:
                        - string
                        - 'null'
                        description: Prefilling of supplier notes in the order. Will be sent to the Supplier when the order is placed, if it's supported by the Supplier's API.
                        example: Some Notes
                urls:
                  $ref: '#/components/schemas/URLs'
                additionalInformation:
                  $ref: '#/components/schemas/PunchoutAdditionalInformation'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - sessionId
                - redirectUrl
                properties:
                  sessionId:
                    type: string
                    example: 1ag3d2b5240e4jcbbe3ee9c49c929fe4
                    description: The unique identifier of a punchout session.
                  redirectUrl:
                    type: string
                    example: https://app.partstech.com/api-search/your_partnerId/your_test_userId/1ag3d2b5240e4jcbbe3ee9c49c929fe4/
        '400':
          $ref: '#/components/responses/DataAvailabilityError'
  /punchout/cart/update:
    post:
      summary: Update Cart
      description: 'Updates the requested `quantity` of items in the cart of the provided punchout `sessionId`. Can be used to keep the PartsTech cart in sync with the partner application when users change the requested quantity of quoted items in a work order.


        Returns the updated cart information.

        '
      operationId: updateCart
      x-operation-name: CommandPunchoutCartUpdate
      tags:
      - punchout-cart
      security:
      - bearerAuth:
        - user
      - apiKeyAuth:
        - user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sessionId
              - updates
              properties:
                sessionId:
                  type: string
                  example: 1ag3d2b5240e4jcbbe3ee9c49c929fe4
                  description: The unique identifier of a punchout session.
                updates:
                  type: array
                  description: The items to be updated.
                  items:
                    type: object
                    required:
                    - orderItemId
                    - quantity
                    properties:
                      orderItemId:
                        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).
                        type: string
                        example: 0ze4f01824764a61991b9d090fdc1813
                      quantity:
                        description: The requested quantity for a part.
                        type: integer
                        minimum: 1
                        maximum: 999
                        example: 10
                  example:
                  - orderItemId: orderItemId1
                    quantity: 25
                  - orderItemId: orderItemId2
                    quantity: 3
      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/EmptyCartError'
        '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/add-part:
    post:
      summary: Add Part
      description: 'Adds an item to the cart of the provided punchout `sessionId`.


        In this method PartsTech attempts to find the correct part to add to the cart, given the part information that is provided in the request. The more part information that is provided in the request, the more accurate and efficient the parts selection will be. In addition to the required fields, providing at least the part''s `lineCardId` will enable a much more accurate parts selection. In some cases, providing only the `storeId` and `partId` is not enough to uniquely identify a part.


        Returns the updated cart information.

        '
      operationId: addPartToCart
      x-operation-name: CommandPunchoutCartAddPart
      tags:
      - punchout-cart
      security:
      - bearerAuth:
        - user
      - apiKeyAuth:
        - user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sessionId
              - requestedPart
              properties:
                sessionId:
                  type: string
                  example: 1ag3d2b5240e4jcbbe3ee9c49c929fe4
                  description: The unique identifier of a punchout session.
                requestedPart:
                  type: object
                  required:
                  - partId
                  - storeId
                  properties:
                    partId:
                      description: PartsTech's ID for a part. Consists of `brandId`-`partNumber`.
                      type: string
                      example: ABCD-12345
                    storeId:
                      description: PartsTech's ID for a supplier location.
                      type: integer
                      example: 1052
                    lineCardId:
                      description: PartsTech's ID for a line code. Makes part selection much more accurate when provided in the request. It is required for tire suppliers with the `availabilitySelect` option. For other suppliers it is not required.
                      type:
                      - integer
                      - 'null'
                      example: 123
                    quantity:
                      description: The requested quantity for a part.
                      type: integer
                      minimum: 1
                      maximum: 999
                      example: 3
                    vehicleId:
                      description: PartsTech's ID for a vehicle.
                      type:
                      - integer
                      - 'null'
                      example: 2
                    partTypeId:
                      description: The ID of a part type from the Autocare Association's PCdb.
                      type:
                      - integer
                      - 'null'
                      default: null
                    selectedStore:
                      description: The supplier store to get the part from. Only required for suppliers with the `availabilitySelect` option. The value to include here is a `specificName` from `storesAvailability` of the part.
                      type:
                      - string
                      - 'null'
      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'
                - type: object
                  description: Part not found
                  properties:
                    error:
                      $ref: '#/components/schemas/Error'
                  example:
                    error:
                      code: PartNotFound
                      messsage: Can`t find part with such parameters
                - type: object
                  description: Part not available
                  properties:
                    error:
                      $ref: '#/components/schemas/Error'
                  example:
                    error:
                      code: PartNotAvailable
                      messsage: Part is not available
        '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/remove-parts:
    post:
      summary: Remove Parts
      description: 'Removes items from the cart of the provided punchout `sessionId` by `orderItemId`. Can be used to keep the PartsTech cart in sync with the partner application when users remove quoted items from a work order.


        Returns the updated cart information.

        '
      operationId: removeItemsFromCart
      x-operation-name: CommandPunchoutCartRemovePart
      tags:
      - punchout-cart
      security:
      - bearerAuth:
        - user
      - apiKeyAuth:
        - user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sessionId
              - removals
              properties:
                sessionId:
                  type: string
                  example: 1ag3d2b5240e4jcbbe3ee9c49c929fe4
                  description: The unique identifier of a punchout session.
                removals:
                  type: array
                  description: Collection of `orderItemId`.
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                  example:
                  - orderItem1
                  - orderItem2
      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/EmptyCartError'
        '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'
components:
  schemas:
    PartCategory:
      type:
      - string
      - 'null'
      enum:
      - Maintenance
      - Service
      - Consumable
    Rewards:
      type:
      - array
      - 'null'
      minItems: 0
      items:
        type: object
        properties:
          program:
            type:
            - string
            - 'null'
          points:
            type:
            - integer
            - 'null'
          bonusPoints:
            type:
            - integer
            - 'null'
    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:
          code: InvalidRequestSyntax
          message: Cannot parse request. Invalid data format
        validationErrors:
        - credentials.user.key - This value should not be blank.
        - credentials.user.id - This value should be of type string.
        - credentials.partner - This value should not be blank.
    URLs:
      type: object
      properties:
        callbackUrl:
          description: The URL for the partner app to receive quote data when the user clicks Submit Quote. If not provided, the Submit Quote button will be removed from the cart.
          type:
          - string
          - 'null'
          format: url
          example: http://localhost:80/some-callback-url
        callbackOrderUrl:
          description: The URL for the partner app to receive order data when the user clicks Buy Now. If not provided, the Buy Now button will be removed from the cart.
          type:
          - string
          - 'null'
          format: url
          example: http://localhost:80/some-callback-order-url
        returnUrl:
          description: The URL loaded after a cart button is clicked.
          type:
          - string
          - 'null'
          format: url
          example: http://localhost:80/some-return-url
    ResponseTaxonomy:
      type:
      - object
      - 'null'
      description: "Part taxonomy has three levels of classification. \nCategory, subcategory, and part type. \nCategory is the most broad and each category contains subcategories.\nEach subcategory contains part types. \nPart type is the most specific classification for a part. \nFor example, the taxonomy for brake pads are the following\n\\- Category = Brake - Subcategory = Disc Pads and Brake Shoes - Part Type = Disc Brake Pad Set.\n"
      required:
      - partTypeId
      properties:
        partTypeId:
          type: integer
          example: 14216
          description: The ID of a part type from the Autocare Association's PCdb.
        partTypeName:
          type:
          - string
          - 'null'
          example: Air Filter Set
          description: The name of a part type.
        partTypeDescription:
          type:
          - string
          - 'null'
          example: Initial fill additive for turbochargers.
          description: The description of a part type.
        categoryId:
          type:
          - integer
          - 'null'
          example: 12
          description: The ID of a part category from the Autocare Association's PCdb. Category is the highest level of part taxonomy.
        categoryName:
          type:
          - string
          - 'null'
          example: Air and Fuel Delivery
          description: The name of a category.
        subCategoryId:
          type: integer
          example: 153
          description: The ID of a subcategory from the Autocare Association's PCdb.
        subCategoryName:
          type:
          - string
          - 'null'
          example: Filters
          description: The name of a subcategory.
      example:
        partTypeId: 8852
        partTypeName: Windshield Wiper Blade
        categoryId: 22
        categoryName: Wiper and Washer
        subCategoryId: 236
        subCategoryName: Windshield Wiper Arm, Blade, and Related Components
    DeliveryNote:
      type: object
      required:
      - label
      - text
      - date
      properties:
        label:
          type:
          - string
          - 'null'
        text:
          type:
          - string
          - 'null'
    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
    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
    BriefStore:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          example: 1
          description: PartsTech's ID for a store.
        name:
          type: integer
          example: 5904 - Springfield, MA
          description: The name of a store
    Error:
      title: Error Definition
      type: object
      required:
      - code
      - message
      properties:
        code:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
    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.
    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
       

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