Merchant

merchant API resource representing merchant entities in the B2B pricing application, including categorization details.

Overview

The merchant resource represents merchant entities in the B2B pricing application. This resource stores merchant information including categorization details.

→ For business context (purpose, usage notes, how this resource is used in the solution), see Merchants dataset in the User Guide.

Resource Endpoint

/api/v2/ingest/object/{prefix}MERCHANT{suffix}

Supported Methods

Method	Return Type	Description
POST	Response	Ingest (create/update) merchant records via UPSERT operation

Request Headers

Header	Required	Description
Authorization	Yes	Your Personal Access Token (PAT) from platform.peak.ai
Content-Type	Yes	Must be application/json

Properties

Primary Keys

• merchant_id (string) - Unique identifier for the merchant
• updated_at (datetime) - Timestamp of when the record was last updated

Attributes

About Required + Nullable: every attribute key must appear in each payload (Required: Yes). Nullable: Yes means the value can be null when you don't have data; Nullable: No means a non-null value is required. See Schema definition structure for the underlying rules.

Attribute	Data Type	Required	Nullable	Description
merchant_id	string	Yes	No	Unique identifier for each merchant. Used to join merchant metadata to quotations and sales for model training and guardrails.
updated_at	datetime	Yes	No	Timestamp when the record was updated. Used to identify the most up-to-date data in the UI and to match merchant metadata to the date of each quote in model training.
merchant_name	string	Yes	No	Merchant name. Used in the UI to identify merchants.
merchant_category	string	Yes	Yes	Merchant category. Used in model training as a feature to determine the optimal quote price.
merchant_subcategory	string	Yes	Yes	Merchant sub-category. Used in model training as a feature to determine the optimal quote price.

Relationships

Outbound References

This resource has relationships to:

• quote_line - Merchants can be associated with multiple quote lines
• sale - Merchants can have multiple sales records

Inbound References

None

JSON Representation

{
  "solutionName": "QP_OOTB",
  "data": [
    {
      "merchant_id": "MERCH-001",
      "updated_at": "2025-01-28T10:00:00Z",
      "merchant_name": "Global Trading Co",
      "merchant_category": "Distributor",
      "merchant_subcategory": "Wholesale"
    }
  ],
  "operationType": "UPSERT"
}

Example Request

curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/QP_MERCHANT_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "QP_OOTB",
    "data": [
      {
        "merchant_id": "MERCH-001",
        "updated_at": "2025-01-28T10:00:00Z",
        "merchant_name": "Global Trading Co",
        "merchant_category": "Distributor",
        "merchant_subcategory": "Wholesale"
      }
    ],
    "operationType": "UPSERT"
  }'

Important Notes

• Custom Attributes: Custom attributes can be added with POST /api/v2/schema/{objectName}/add-attribute, where {objectName} is this table's fully qualified warehouse name ({prefix}MERCHANT{suffix} — for example, QP_MERCHANT_OOTB), as returned by Describe a solution's schema
• Data Validation: All attributes are validated according to their defined data types

Related Resources

• customer - Related business entities
• quote_line - Quote line items referencing merchants
• sale - Sales records associated with merchants