Supplier Attributes Import APIs

The Supplier Attributes Import APIs enable you to programmatically update attributes for your vendors, and resellers in Productiv.

Prerequisites

Querying the Supplier Attributes Import APIs involves sending an access_token as part of the Authorization header. For instructions on how to generate an access token, see Authorization.

Endpoints

Batch Update Supplier Attributes

POST https://public-api.productiv.com/push/v1/suppliers/batch/attributes

Include the following headers and path parameters with your request:

Headers

Parameter	Value
Content-Type	application/json
Authorization	`Bearer access_token`

Required Scope https://api.productiv.com/apps.write

Request Body Schema

[
    {
        "supplierId": String,
        "customFields": [
            {
                "name": String,
                "value": Any
            }
        ]
    }
]

Supplier Update Object

Every vendor update object should have the following properties in the object:

Property	Datatype	Description
supplierId	`string`	Unique identifier for the vendor (VendorId), or reseller (ResellerId) being updated, obtained from the Supplier List API
customFields	`array`	List of CustomField objects, see definition below. Note that new custom fields currently cannot be configured through the API, only the existing custom field's values can be created or updated

Response

If the request is successful, a JSON response is returned. The JSON object contains the following parameters:

Parameter	Datatype	Description
NumSuccessfulUpdates	`number`	Number of successfully processed updates
FailedUpdates	`array`	List of FailedUpdate objects (see definition below)
ResponseTimeMs	`number`	Time taken by the server to process the request in milliseconds

Example Response

{
  "NumSuccessfulUpdates": 10,
  "FailedUpdates": [
    {
      "supplierId": "supplierId",
      "customFields": [
        {
          "name": "cost center",
          "value": "123 - New York",
          "reason": "123 - New York is not a valid value for the cost center custom field"
        }
      ]
    }
  ],
  "ResponseTimeMs": 1000
}

Batch Delete Supplier Attributes

DELETE https://public-api.productiv.com/push/v1/suppliers/batch/attributes

Include the following headers and path parameters with your request:

Headers

Parameter	Value
Content-Type	application/json
Authorization	`Bearer access_token`

Required Scope https://api.productiv.com/apps.write

Request Body Schema

[
    {
        "supplierId": String,
        "customFields": [
            {
                "name": String,
            }
        ]
    }
]

Supplier Delete Object

See Supplier Update Object above. Note that the value attribute must be left undefined for DELETE requests.

Response

If the request is successful, a JSON response is returned. The JSON object contains the following parameters:

Parameter	Datatype	Description
NumSuccessfulUpdates	`number`	Number of successfully processed updates
FailedUpdates	`array`	List of FailedUpdate objects (see definition below)
ResponseTimeMs	`number`	Time taken by the server to process the request in milliseconds

Example Response

{
  "NumSuccessfulUpdates": 10,
  "FailedUpdates": [
    {
      "supplierId": "supplierId",
      "customFields": [
        {
          "name": "cost center - invalid",
          "reason": "cost center - invalid is not a valid custom field"
        }
      ]
    }
  ],
  "ResponseTimeMs": 1000
}

Objects

This section describes the objects referenced above in the Request and Response schema.

CustomField

Property	Datatype	Description
name	`string`	Name for the custom field being updated, referred to as `FieldName` in the supplier list response. Either `name` or `key` must be present, but not both.
key	`string`	Key for the custom field being updated, referred to as `FieldKey` in the supplier list response. Either `name` or `key` must be present, but not both.
value	`any`	Value to set the custom field to. See CustomFieldValue object below. Note that for DELETE requests value must be undefined.

CustomFieldValue

Custom fields can be one of the following types: singleselect, multiselect, text, number, date, currency, hyperlink. The datatype for value above depends on the type of custom field you are trying to edit.

Type	Datatype	Description
singleselect	`string`	The value must be one of the allowed values as configured in the product for the custom field.
multiselect	`array`	List of strings. Each value must be one of the allowed values for the field as configured in the product for the custom field.
text	`string`	Free-form text
number	`number`	Number
date	`string`	YYYY-MM-DD format
currency	`object`	See Currency object below
hyperlink	`object`	See Hyperlink object below

Currency

Property	Datatype	Description
currencyCode	`string`	ISO 4217 currency code
amount	`number`	Amount

Hyperlink

Property	Datatype	Description
label	`string`	Label for the hyperlink
url	`string`	URL for the hyperlink

FailedUpdate

Property	Datatype	Description
supplierId	`string`	Unique identifier for the vendor (VendorId), or reseller (ResellerId) that could not be updated

FailedUpdateCustomField

Property	Datatype	Description
name	`string`	Identifier for the custom field being updated
value	`any`	Value the custom field could not be set to
reason	`string`	Reason for the update failure