PartsTech Custom Cart API

openapi: 3.2.0
info:
  version: 2.021.1
  title: PartsTech Custom 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: custom-cart
  description: Custom Cart
  x-displayName: Custom Cart
paths:
  /punchout/cart/custom/create:
    post:
      summary: Create Custom Cart
      description: 'Creates a new punchout session and forms a cart by adding the same items provided in the list of `orderItemId`, even previously ordered items. A new `orderItemId` is created and assigned to each item added to the new cart. An `orderItemId` can only be used in an order request once, so this method can be used to create a cart for stock ordering through the PartsTech API. Using the `orderItemId` of previously ordered items in inventory, this method can be used to easily add those items to a new cart to be ordered again.


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

        '
      operationId: customCartCreate
      x-operation-name: CommandPunchoutCartCustomCreate
      tags:
      - custom-cart
      security:
      - bearerAuth:
        - user
      - apiKeyAuth:
        - user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - orderItems
              properties:
                urls:
                  $ref: '#/components/schemas/URLs'
                additionalInformation:
                  $ref: '#/components/schemas/PunchoutAdditionalInformation'
                orderItems:
                  type: array
                  minItems: 1
                  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).
                        example: 0ze4f01824764a61991b9d090fdc1813
                        type: string
                      quantity:
                        description: The requested quantity for a part.
                        type: integer
                        minimum: 1
                        maximum: 999
      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: http://localhost:80/redirect-url
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidRequestError'
                - $ref: '#/components/schemas/RequiredAdditionalParametersError'
                - $ref: '#/components/schemas/CartPartNotFoundError'
              examples:
                InvalidRequest:
                  value:
                    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.
                NotConsistentRequest:
                  value:
                    error:
                      code: NotConsistentRequest
                      message: OrderItem [some_hash] belongs to store [actual_store_id], but was requested with store [received_store_id].
                PartNotFound:
                  value:
                    error:
                      code: PartNotFound
                      message: Some order items were not found, please check each order item response
                    orderItemErrors:
                    - orderItemId: '[some_hash]'
                      message: Order Item was not found
                    - orderItemId: '[some_hash2]'
                      message: Order Item has been already bought or in progress
                NotUniquePart:
                  value:
                    error:
                      code: NotUniquePart
                      message: The part [part_number_id] under the store [store_id] was sent twice.
                OutdatedPart:
                  value:
                    error:
                      code: OutdatedPart
                      message: Order Item [order_item_id] [part_number_id] is not valid for this operation
  /punchout/cart/custom/order:
    post:
      summary: Order Custom Cart
      description: 'Places orders for quoted items by `orderItemId`. Quoted items from different sessions can be included in a single request. Each order in the request is associated with a specific store (supplier location) and requires a `storeId`. An order must include a list of items with their respective `orderItemId` and requested `quantity`. Each `orderItemId` can only be used once and the maximum accepted quantity per item is 99.


        It is optional to include supplier `notes` and a `poNumber` in each order. If provided, they will overwrite any supplier notes or PO number previously entered in PartsTech for that store''s order. If these fields are omitted, PartsTech will use the supplier notes and PO number from the cart details of the punchout session, if present. Any supplier notes and PO numbers from the cart are sent in the cart callback data to the partner application.


        It is important to provide a `poNumber` for PartsTech to send to suppliers in order requests. While the partner application should send a `poNumber` when creating a session, users can edit the cart''s PO fields. If there is no PO number in the cart callback data for a store''s quote, the partner application should include a `poNumber` in that store''s order request. Otherwise, PartsTech will have to use the PartsTech generated orderId as the PO number in supplier order requests, making it difficult for users to match delivered parts to the correct work order.


        The response includes a list of orders sent to suppliers. It is in the same schema as order data in the cart callback.

        '
      operationId: submitItems
      x-operation-name: CommandPunchoutCartCustomOrder
      tags:
      - custom-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
                    - orderItems
                    properties:
                      storeId:
                        description: PartsTech's ID for a supplier location.
                        type: integer
                        example: 1
                      poNumber:
                        type:
                        - string
                        - 'null'
                        description: Optional. If a value is included here, any PO number provided earlier in the quoting process for the order will be overwritten.
                        example: Some PoNumber
                      notes:
                        type:
                        - string
                        - 'null'
                        description: Optional. If a value is included here, any supplier notes provided earlier in the quoting process for the order will be overwritten.
                        example: Some Notes
                      orderItems:
                        type: array
                        minItems: 1
                        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: 2
                urls:
                  $ref: '#/components/schemas/URLs'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - orders
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/PunchoutPurchasedOrder'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidRequestError'
                - $ref: '#/components/schemas/RequiredAdditionalParametersError'
                - $ref: '#/components/schemas/CartPartNotFoundError'
                - type: object
                  required:
                  - error
                  properties:
                    error:
                      $ref: '#/components/schemas/Error'
              examples:
                InvalidRequest:
                  value:
                    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.
                NotConsistentRequest:
                  value:
                    error:
                      code: NotConsistentRequest
                      message: OrderItem [some_hash] belongs to store [actual_store_id], but was requested with store [received_store_id].
                PartNotFound:
                  value:
                    error:
                      code: PartNotFound
                      message: Some order items were not found, please check each order item response
                    orderItemErrors:
                    - orderItemId: '[some_hash]'
                      message: Order Item was not found
                    - orderItemId: '[some_hash2]'
                      message: Order Item has been already bought or in progress
                NotUniquePart:
                  value:
                    error:
                      code: NotUniquePart
                      message: The part [part_number_id] under the store [store_id] was sent twice.
                RequiredAdditionalParameters:
                  value:
                    error:
                      code: RequiredAdditionalParametersError
                      message: Supplier requires additional parameters that should be filled in the cart.
                    sessionId: Session id
                    redirectUrl: http://localhost:80/redirect-url
        '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/custom/availability:
    post:
      summary: Check Custom Cart Availability
      description: 'Provides real-time pricing and availability information directly from supplieres for each provided item by `orderItemId`. 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: checkItemsAvailability
      x-operation-name: QueryPunchoutCartCustomAvailability
      tags:
      - custom-cart
      security:
      - bearerAuth:
        - user
      - apiKeyAuth:
        - user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - orderItems
              properties:
                orderItems:
                  type: array
                  minItems: 1
                  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).
                        example: 0ze4f01824764a61991b9d090fdc1813
                        type: string
                      quantity:
                        description: The requested quantity for a part.
                        type: integer
                        minimum: 1
                        maximum: 999
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - orders
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/PunchoutOrder'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidRequestError'
                - $ref: '#/components/schemas/RequiredAdditionalParametersError'
                - $ref: '#/components/schemas/CartPartNotFoundWithOrdersError'
                - type: object
                  required:
                  - error
                  properties:
                    error:
                      $ref: '#/components/schemas/Error'
              examples:
                InvalidRequest:
                  value:
                    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.
                PartNotFound:
                  value:
                    error:
                      code: PartNotFound
                      message: Some order items were not found, please check each order item response
                    orderItemsErrors:
                    - orderItemId: '[some_hash]'
                      message: Order item was not found
                    - orderItemId: '[some_hash2]'
                      message: Order item has been already bought or in progress
                    orders:
                    - See orders property in the success response
                NotUniquePart:
                  value:
                    error:
                      code: NotUniquePart
                      message: The part [part_number_id] under the store [store_id] was sent twice.
                RequiredAdditionalParameters:
                  value:
                    error:
                      code: RequiredAdditionalParametersError
                      message: Supplier requires additional parameters that should be filled in the cart.
                    sessionId: Session id
                    redirectUrl: http://localhost:80/redirect-url
        '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:
    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.
    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'
    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'
    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
    PartPrice:
      type: object
      required:
    

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