Skip to main content

Release Notes 2024: MarketTime Public API

MarketTime Public API Releases

We have recently updated our API suite with new APIs and modifications to existing ones. Accessing our API endpoints requires authentication using your unique API key, obtainable by contacting MarketTime here. It is essential to safeguard your API key to prevent unauthorized access to your data. For documentation and examples of all our public APIs, please visit https://markettime.com/api.

Releases

November 25, 2024

New

POST Item Endpoint

  • We added a sequenceID attribute to the SCS object in the POST Item endpoint. This enables you to specify the order in which your SCS records should appear in the MT user interface.
    • The sequenceID is optional. 
    • A duplicate sequence ID cannot be posted. If a sequence ID is duplicated, the system will generate an error.
    • When posting a sequence ID, the numbers should follow a numeric order such as 1, 2, 3, 4, 5, and so on. If the sequence ID is posted out of order, such as 1, 2, 4, 5, 3, the system will automatically rearrange and import the records in the correct order. However, all numbers in the sequence must be included. If a number is omitted from the sequence, the system will generate an error.
    • The SCS record cannot be updated via the PUT Items endpoint.
URL: /mtpublic/api/v1/{whoAmI}/items

Get Orders Endpoint

  • We have added the Account Number and Ship to Account Number query parameters to the GET Orders endpoint. This enhancement allows you to filter and retrieve specific orders by applying either the Account Number or the Ship to Account Number in the API request.
URL: /mtpublic/api/v1/{whoAmI}/orders/get

 

October 18, 2024

New

POST Endpoint: Insert Ship to Location Salesperson Assignment

  • This endpoint can only be called by the repgroup (R ID).
  • You can assign salesperson(s) to a ship to location(s) via this endpoint.
    • You will be able to assign a maximum of six salespersons to one ship to location.
      • The Salesperson Type field indicates the ranking (1-6) of the salesperson, where "1" represents the primary salesperson for the ship-to location. Each Salesperson Type must be unique and cannot be repeated.
  • You should not provide a recordID when calling the Post endpoint.
  • You must provide the SalespersonID and the ShiptoLocationID to assign the salesperson to the ship to location.
  • You can retrieve the SalespersonID and ShiptoLocationID by calling the corresponding Salesperson and Ship to Location Get endpoints.
URL: /mtpublic/api/v1/{whoAmI}/customers/{customerId}/repgroupsalespersoncustomer

PUT Endpoint: Update Ship to Location Salesperson Assignment

  • This endpoint can only be called by the repgroup (R ID).
  • You must have the recordID in the request body to be able to call this endpoint.
  • You can only update the Salesperson Type and DivisionID via this endpoint.
URL: /mtpublic/api/v1/{whoAmI}/customers/{customerId}/repgroupsalespersoncustomer

GET List of Ship to Location Salesperson Assignment

  • This endpoint can only be called by the repgroup (R ID).
  • You can retrieve the salesperson ship to location assignment by calling the Get endpoint.
URL: /mtpublic/api/v1/{whoAmI}/customers/{customerId}/repgroupsalespersoncustomer/get

POST Endpoint: Insert List of Repgroup Customer Manufacturer

  • This endpoint can only be called by the repgroup (R ID).
  • You can create repgroup retailer manufacturer (RGRM) records for each ship to location that you have.
    • You must provide the ShiptoLocationID to create an RGRM record for the ship to location.
    • You can retrieve the ShiptoLocationID by calling the corresponding Ship to Location Get endpoint.
  • You should not provide a recordID when calling the Post endpoint.
URL: /mtpublic/api/v1/{whoAmI}/customer/{customerID}/repgroupcustomermanufacturer

PUT Endpoint: Update Repgroup Customer Manufacturer

  • This endpoint can be called by the repgroup (R ID) or the manufacturer (M ID).
    • If you are calling as a manufacturer, you must provide the manufacturerID in the request body.
  • You must have the recordID in the request body to be able to call the put endpoint.
  • You can update the ship to location on an RGRM record via this endpoint.
  • You can also perform a bulk update (replace) action with this endpoint. You will be able to update up to 50 records at a time.

          

URL: /mtpublic/api/v1/{whoAmI}/customer/{customerID}/repgroupcustomermanufacturer

GET List of Repgroup Customer Manufacturer

  • This endpoint can be called by the repgroup (R ID) or the manufacturer (M ID).
    • If you are calling as a manufacturer, you must provide the repgroupID as a parameter.
  • You can retrieve the RGRM record by calling the Get endpoint.
URL: /mtpublic/api/v1/{whoAmI}/customer/{customerID}/repgroupcustomermanufacturer/get

July 15, 2024

New

Public API UI and Documentation Improvement

MarketTime's public API now features a new look and improved documentation on the corporate website. The enhanced documentation is user-friendly and readable, offering descriptions for each field and highlighting all required fields for each endpoint.

Improved Validation for All Endpoints:

We have improved error messaging across all endpoints to help users quickly identify and resolve issues with API calls.

Updates to Existing APIs

Post List of Customer Ship to Locations Endpoint:

  • You can now use the retailer External ID instead of the buyer ID (B123) when creating new ship-to locations.
    • To create a new ship-to location with an external ID, you must first set up the external ID in the MarketTime database. This can be done by inserting the external ID via the Post Customer endpoint under the external ID field.
    • Set the useRetailerExternalID field to "true" and provide the external ID in the customer ID field if you want to use the external ID.
      • You do not need to provide the retailer ID in the request body if the useRetailerExternalID is set to true.
      • URL: /mtpublic/api/v1/{whoAmI}/customers/{customerID}/shiptolocation/list

Post List of Customer Contacts Endpoint:

  • You can now use the retailer External ID instead of the buyer ID (B123) when creating customer contacts.
    • To create a customer contact with an external ID, you must first set up the external ID in the MarketTime database. This can be done by inserting the externalID via the Post Customer endpoint under the external ID field.
    • If you intend using the external ID, set the useRetailerExternalID field to "true" and provide the external ID in the customer ID field.
      • You do not need to provide the retailer ID in the request body if useRetailerExternalID is set to true.
  • URL: /mtpublic/api/v1/{whoAmI}/customers/{customerID}/contact/list

Put Customer Ship to Location and Put Customer Contact Endpoint:

  • The Put Customer Ship to Location and Customer Contact endpoints now allow you to update a customer's ship-to location and contact records using the retailer External ID instead of the buyer ID (B123).
    • When updating a customer's ship to location or contact, set the useRetailerExternalID field to "true" and provide the external ID in the customer ID field.
    • If you have already inserted an external ID when creating your ship-to location or contact, you can use those external IDs in place of the ship-to location ID or the contact ID, respectively.
  • URLs: 
    • Put Customer Ship to Location: /mtpublic/api/v1/{whoAmI}/customers/{customerId}/shiptolocation/{shipToLocationId}
    • Put Customer Contact: /mtpublic/api/v1/{whoAmI}/customers/{customerId}/contact/{contactI

 

Post Customer Endpoint

  • We have increased the maximum number of ship-to locations that can be posted via this endpoint from 5 to 50. 
    • URL: /mtpublic/api/v1/{whoAmI}/customers

Get Customer Endpoint

  • We have increased the maximum number of ship-to locations that can be retrieved via this endpoint from 50 to 250. 
    • URL: /mtpublic/api/v1/{whoAmI}/customers/get

Coming Soon

Validations to Existing APIs

We will be implementing some validation to the the current version (v.1) of the public API. This improvement is to ensure that bad data is not passed into MarketTime via the APIs. These validation seeks to create parity between the MarketTime app's functionality and the API, and ensure seamless integration between the public API and the MarketTime app.

Please modify your current process to align with the upcoming validation.

Post, Put and Upsert Customer Endpoints

  • Customer Name: The customer name field on the post, put, and upsert customer endpoints will be limited to 50 characters, ensuring consistency with the MarketTime UI. If a longer name is passed in, the API will return an error.

  • Status: The status field on the post, put, and upsert endpoints will only accept the three statuses visible on the MarketTime UI: ACTIVE, INACTIVE, or LEAD. Any other status will result in an error.

  • URLs: 
    • Post: /mtpublic/api/v1/{whoAmI}/customers
    • Put Customer: /mtpublic/api/v1/{whoAmI}/customers/{whoseInfoDoIWantToUpdate}

      Upsert Customer: /mtpublic/api/v1/{whoAmI}/customers/{whoseInfoDoIWantToUpsert}/upsert

Put Salesperson Endpoint

  • We are implementing validation to ensure the uniqueness of a salesperson's email. You will not be able to update a salesperson's record with an email that is already associated with another salesperson. 
    • URL: /mtpublic/api/v1/{whoAmI}/salespersons/{whoseInfoDoIWantToUpdate}

May 20, 2024

List of New Public APIs

Get List of Manufacturer Shipping Methods

  • Who can call this endpoint (WhoAmI)?:
    • This API can be called by both the Repgroup (E.g. repgroupID: R124) and Manufacturer (E.g. manufacturerID: M124) users in MT.
  • Description:
    • The Get List of Manufacturer Shipping Methods will enable the end user to retrieve the list of shipping methods for a manufacturer.
URL: /mtpublic/api/v1/{whoAmI}/manufacturers/shippingMethods

Item Volume Pricing Upsert API

  • Who can call this endpoint (WhoAmI)?:
    • The Item Volume Pricing Upsert API can be called by both the Repgroup (E.g. repgroupID: R124) and Manufacturer (E.g. manufacturerID: M124) users in MT.
  • Description:
    • This API will enable the end user to update (put) or insert (post) the volume price of an item in MT, depending on the object provided in the call.
    • The end user would need to pass in the volumePrice RecordID in the request body to update the record. You can get the volumePrice RecordID by calling the Get Item Pricing Details endpoint.
  • URL:/mtpublic/api/v1/{whoAmI}/items/volumePricing/upsert

Get List of Contacts for Customers:

  • Who can call this endpoint (WhoAmI)?:
    • This endpoint can only be called by the Repgroup (E.g. repgroupID: R124)  in MT.
  • Description:
    • This API will enable the end user to retrieve the list of contacts for a customer.
URL: /mtpublic/api/v1/{whoAmI}/customers/{whoseInfoDoIWantToGet}/contacts

Updates to Existing APIs

Get Orders Endpoint

  • You can now retrieve the following records by calling the Get Orders Endpoint:

    • Order Promotions

    • Order Writer Name
    • Salesperson Name
    • Repgroup
    • Order Payment Token
URL: /mtpublic/api/v1/{whoAmI}/orders/get

Post Order Endpoint

  • We added Retailer External ID, Manufacturer External ID and Ship to External ID fields to the Post Orders API.  In place of the Retailer ID (B ID), Manufacturer ID (M ID) or Retailer Ship to ID, you can create a new order in MarketTime with your own Retailer External ID, Manufacturer External ID and Ship to External ID.
    • To create new orders with externalID values, you must first set up these externalIDs in the MarketTime database.

      • Retailer External ID: Add it in the Account Number field on the Repgroup Retailer Manufacturer table on the MarketTime UI or post it via the Post Customer endpoint under the externalID field.

      • Manufacturer External ID: Post it via the Post Manufacturer endpoint under the externalID field.

      • Ship to External ID: Post it via the Post Ship to Location for Customer endpoint under the externalID field.

    • To use an externalID when posting an order, set the externalID to "True" and provide the external ID in the body of the request.
  • You will be able to retrieve the Retailer External ID, Manufacturer External ID and Ship to External ID via the Get Orders call.
URL: 

Post: /mtpublic/api/v1/{whoAmI}/orders

Get: /mtpublic/api/v1/{whoAmI}/orders/get

Put Orders Endpoint

  • MT Manufacturers can now update only the Manufacturer Order Status via the Put Orders Endpoint.
URL: /mtpublic/api/v1/{whoAmI}/orders/{whatOrderDoIWantToUpdate}

Post Salesperson Endpoint

  • You can now add externalID and externalID2 in the Post Salesperson request.
URL: /mtpublic/api/v1/{whoAmI}/salespersons

Put Salesperson Endpoint

  • You can update a salesperson's record using the ExternalID created via the Post Salesperson endpoint instead of the Salesperson ID. To do this, set the externalID to "True" and include the external ID in the body of the request.
URL: /mtpublic/api/v1/{whoAmI}/salespersons/{whoseInfoDoIWantToUpdate}

Get Salesperson Endpoint

  • You can now filter the Get Salesperson query by the recordID.
URL: /mtpublic/api/v1/{whoAmI}/salespersons/get

Get Items Endpoint

  • You can now filter the Get Items query by manufacturerID and name (item name) 
    • URL: /mtpublic/api/v1/{whoAmI}/items/get

April 9, 2024

New

Post and Put Salesperson API:

  • Who can call this endpoint (WhoAmI)?:
    • The Post and Put Salesperson API can only be called by the Repgroup (E.g. repgroupID: R124) user in MT.
  • Description:
    • The Post Salesperson API will enable the Repgroup insert (create) the salesperson (S12345) record in the MarketTime database, making the record visible in the MT UI.
    • The Put Salesperson API will enable the Repgroup update the salesperson (S12345) record in the MarketTime database, making the update visible in the MT UI.
  • URL:
Post Salesperson API: /mtpublic/api/v1/{whoAmI}/salespersons

Put Salesperson API: /mtpublic/api/v1/{whoAmI}/salespersons/{whoseInfoDoIWantToUpdate}

 

Item Upsert (Update or Insert Item Details) API:

  • Who can call this endpoint (WhoAmI)?:
    • The Item Upsert API can be called by both the Repgroup (E.g. repgroupID: R124) and Manufacturer (E.g. manufacturerID: M124) users in MT.
  • Description:
    • This API will enable the end user to update (put) or insert (post) items in MT depending on the object provided in the call. The end user can pass either their Item Number or RecordID in the call to update the item record.
  • URL: /mtpublic/api/v1/{whoAmI}/items/upsert

Bulk Items Import API:

  • Who can call this endpoint (WhoAmI)?:
    • This API can be called by both the Repgroup (E.g. repgroupID: R124) and Manufacturer (E.g. manufacturerID: M124) users in MT.
  • Description:
    • This API will enable the end user import items in bulk into MT. This API provides a replace functionality, where Replace = True will delete the existing items and replace with the new items to be imported. Where Replace = False will update existing records with new records if a match is found and create new records if no match is found.
  • URL: /mtpublic/api/v1/{whoAmI}/items/import

Customer Upsert (Update or Insert Customer Details) API:

  •  Who can call this endpoint (WhoAmI)?
    •  This API can only be called by the Repgroup (E.g. repgroupID: R124) user in MT.
  • Description:
    • This API provides the functionality for the end user to update (PUT) or insert (POST) customers in MT, depending on the object provided in the call. The end user has the option to pass either their Item Number or RecordID in the call to update the item record. Additionally, the Upsert Customers API includes an externalID field, allowing the repgroup to provide an externalID in place of the recordID.
  • URL: /mtpublic/api/v1/{whoAmI}/customers/{whoseInfoDoIWantToUpsert}/upsert

Item Price Code Upsert (Update or Insert Item Price Code) API:

  • Who can call this endpoint (WhoAmI)?:
    • This API can be called by both the Repgroup (E.g. repgroupID: R124) and Manufacturer (E.g. manufacturerID: M124) users in MT.
  • Description:
    • This API will enable the end user to update (PUT) or insert(POST) the price codes for an item  in MT, depending on the object provided in the call.
    • The Item Price Code Upsert API will not allow the end user to create or update the Repgroup Retailer Manufacturers record for Pricing Method in MT.
  • URL: /mtpublic/api/v1/{whoAmI}/items/priceCode/upsert

Customer Pricing Method Upsert API:

  • Who can call this endpoint (WhoAmI)?
    •  This API can only be called by the Repgroup (E.g. repgroupID: R124) user in MT.
  • Description:
    • This API allows the Repgroup to either update (PUT) or insert (POST) the Item Pricing Method (Price Code) into the Repgroup Retailer Manufacturers record in MT, depending on the object provided in the call. This capability empowers the end user to assign an item price code to a customer.
URL: /mtpublic/api/v1/{whoAmI}/customers/{retailerID}/pricecode/{manufacturerID}/assign/upsert

Post List of Customer Contact API:

  • Who can call this endpoint (WhoAmI)?
    •   This API can only be called by the Repgroup (E.g. repgroupID: R124) user in MT.
  • Description:
    • This endpoint enables the end user to generate a list of contacts for a customer. However, it does not permit the creation of a primary contact. Creating a primary contact will be done through the Post Customers endpoint.
URL: /mtpublic/api/v1/{whoAmI}/customers/{customerID}/contact/list

 Put Customer Contact API:

  • Who can call this endpoint (WhoAmI)?
    • This API can only be called by the Repgroup (E.g. repgroupID: R124) user in MT.
  • Description:
    • This endpoint allows the end user to update a customer contact record. Additionally, the end user has the capability to update the primary contact using this API.
  • URL: /mtpublic/api/v1/{whoAmI}/customers/{customerId}/contact/{contactId}

Post Customer Ship to Location API:

  • Who can call this endpoint (WhoAmI)?
    • This API can only be called by the Repgroup (E.g. repgroupID: R124) user in MT.
  • Description:
    • This endpoint will enable the end user to create a ship to location record for a customer. This endpoint will not allow the user to create a primary ship to location. Creating a primary contact will be done through the Post Customers endpoint.
  • URL: /mtpublic/api/v1/{whoAmI}/customers/{customerID}/shiptolocation

Post Customer List of Ship to Locations API:

  • Who can call this endpoint (WhoAmI)?
    • This API can only be called by the Repgroup (E.g. repgroupID: R124) user in MT.
  • Description:
    • This endpoint will enable the end user to create a list of ship to locations record for a customer. This endpoint will not allow the user to create a primary ship to location. Creating a primary contact will be done through the Post Customers endpoint.
  • URL: /mtpublic/api/v1/{whoAmI}/customers/{customerID}/shiptolocation/list

Put Customer Ship to Location:

  • Who can call this endpoint (WhoAmI)?
    • This API can only be called by the Repgroup (E.g. repgroupID: R124) user in MT.
  • Description:
    • This endpoint will enable the end user to update a ship to location for a customer. The end user will also be able to update the primary ship to location using this API.
  • URL:/mtpublic/api/v1/{whoAmI}/customers/{customerId}/shiptolocation/{shipToLocationId}

Post and Put Customer CC Token API:

  • Who can call this endpoint (WhoAmI)?
    • This API can only be called by the Repgroup (E.g. repgroupID: R124) user in MT.
  • Description:
    • The Post Customer CC Token endpoint will allow the user to create a new CC token record for a customer in MT.
    • The Put Customer CC Token endpoint will allow the user to update a CC token record for a customer in MT.
  • URL: 
    • Post Customer CC Token API: /mtpublic/api/v1/{whoAmI}/customers/{customerID}/paymentinfo
    • Put Customer CC Token API: /mtpublic/api/v1/{whoAmI}/customers/{whoseInfoDoIWantToUpdate}/paymentinfo/{paymentinfoId}

Get Order Shipment Details API:

  • Who can call this endpoint (WhoAmI)?
    • This API can only be called by the Manufacturer (E.g. manufacturerID: M124) user in MT.
  • Description:
    • This endpoint will allow the user to retrieve shipment details from an order.
  • URL: /mtpublic/api/v1/{whoAmI}/orders/{orderId}/trackingdetails/get

Post and Put Order Shipment Details APIs:

  • Who can call this endpoint (WhoAmI)?
    •   This API can only be called by the Manufacturer (E.g. manufacturerID: M124) user in MT.
  • Description:
    • The Post Order Shipment Detail endpoint enables the creation of a shipment detail record for an order in MT.
      The Put Order Shipment Detail endpoint enables the user to update a shipment detail record for an order in MT.
  • URL: 
    • Post Order Shipment Details API: /mtpublic/api/v1/{whoAmI}/orders/{orderId}/trackingdetails
    • Put Order Shipment Details API: /mtpublic/api/v1/{whoAmI}/orders/trackingdetails/{trackingDetailID}

Post mtCharge Process Payment API:

  • Who can call this endpoint (WhoAmI)?
    •     This API can only be called by the Manufacturer (E.g. manufacturerID: M124) user in MT.
  • Description:
    • This endpoint will allow the user to process mtCharge payments in MT.
  • URL: /mtpublic/api/v1/{whoAmI}/payments/processPayment

Post mtCharge Request Payment Update API:

  • Who can call this endpoint (WhoAmI)?

                This API can only be called by the Manufacturer (E.g. manufacturerID: M124) user in MT.

  • Description:
    • This endpoint enaables the user to request an alternative form of payment from the customer.
  • URL: /mtpublic/api/v1/{whoAmI}/payments/requestPaymentUpdate

Updates to Existing APIs

Post Customer (Create New Customer) API:

  • This endpoint now permits the repgroup to create a list of ShipToLocations, with a maximum limit of 5. Additionally, it mandates the creation of a primary ShipToLocation when creating a customer.
  • The end user can create up to 5 lists of contacts using this endpoint, with the requirement of specifying a primary contact when creating a customer.
  • The Repgroup is now able to create a Repgroup Retailer Manufacturer (RGRM) record simultaneously when creating a customer.
  • URL: /mtpublic/api/v1/{whoAmI}/customers

Post Orders (Create New Order) API:

  • The repgroup now has the capability to create a Repgroup Retailer Manufacturer record (accountNumber and shipToAccountNumber) concurrently when an order is created.
  • URL: /mtpublic/api/v1/{whoAmI}/orders

Bug Fixes

  • Get Items Endpoint:
    • Fixed the inability for an end user to filter query by the recordDeleted parameter.
Last updated:
Was this article helpful?