Unified Endpoint API

This endpoint allows for sending an arbitrary JSON document to one endpoint. Kargo will translate the request into whatever operation is necessary for the payload, based on data in the payload.

Overview

The unified endpoint API provides a flexible integration pattern where you can send various types of payloads (SKU Master Items, Orders, Shipments, etc.) to a single endpoint. Kargo automatically determines the appropriate operation based on the payload structure and content.

Integration Flow

1. Get a bearer token using your Client ID and Secret
2. Prepare a request with facilitySlug and businessSlug for the applicable facility
3. Inject the JSON as the payload field in the request

Authentication

Before making requests to the unified endpoint, you must obtain a bearer token. See the Authentication documentation for details on how to authenticate using your Client ID and Secret.

Request Format

Endpoint

POST /public_graphql

Headers

• Content-Type: application/json
• Authorization: Bearer <YOUR_TOKEN_HERE>

Request Body Structure

mutation ProcessPayload($input: ProcessPayloadInput!) {
  processPayload(input: $input) {
    message
    success
    loggingId
  }
}

Variables

Field	Type	Required	Description
businessSlug	String	Yes	The business identifier
facilitySlug	String	Yes	The facility identifier
payload	JSON Object	Yes	The arbitrary JSON payload containing your data

Example Request

curl --request POST \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  --url https://api.kargo.com/public_graphql \
  --data '{
    "query": "mutation ProcessPayload($input: ProcessPayloadInput!) {\n  processPayload(input: $input) {\n    message\n    success\n    loggingId\n  }\n}",
    "variables": {
      "input": {
        "businessSlug": "your-business-slug",
        "facilitySlug": "your-facility-slug",
        "payload": {
          
        }
      }
    }
  }'

note

The payload field accepts any arbitrary JSON structure. Simply replace the empty payload object with your own JSON data. Kargo will automatically detect the entity type and perform the appropriate operation based on your payload contents.

Response Format

The unified endpoint returns a consistent response structure:

{
  "data": {
    "processPayload": {
      "message": "string",
      "success": true,
      "loggingId": "string"
    }
  }
}

Response Fields

Field	Type	Description
message	String	A human-readable message describing the result
success	Boolean	Indicates whether the operation was successful
loggingId	String	A unique identifier for tracking and debugging purposes

Payload Structure

The payload field is flexible and accepts any arbitrary JSON structure. You can send:

• Sales Orders - Create or update sales order information
• Purchase Orders - Submit purchase order data
• Item Master Changes - Update SKU master data and product information
• Shipments - Send shipment details and tracking information
• Exceptions - Report and track exceptions
• Custom entity data - Any other business-specific data structures

Kargo automatically detects the entity type and performs the appropriate operation based on the payload contents. Simply structure your JSON data according to your business needs, and the system will handle the translation and processing.

Error Handling

If an error occurs during processing, the response will include:

• success: false
• A descriptive message explaining the error
• A loggingId that you can reference when contacting support

Best Practices

1. Always include a loggingId: Save the returned loggingId from each request for debugging and support purposes
2. Handle errors gracefully: Check the success field and handle failures appropriately in your integration
3. Order modification behavior: When modifying an existing order, the default behavior is to overwrite all previous order items with the new ones provided in the payload. To add or remove specific items, simply send the complete new order with all items as you want them to be

Related Documentation

• Authentication - How to obtain bearer tokens
• GraphQL API - Alternative API integration methods
• Flat File Integration - CSV-based integration option