Pixels

9 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

List pixel destinations

GET/v1/pixel-destinations

Pixel destinations per store (Meta, TikTok, Google Analytics 4, Google Ads conversion) with their public settings. Access tokens are never returned.

Authentication: API key (Bearer)
Permission: sell:read
Idempotency-Key: Not used
Success: 200

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/pixel-destinations" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Adds a destination for one store. settings depend on kind (Meta pixelId, TikTok pixelCode, GA4 measurementId, Google Ads conversionId and conversionLabel; optional testEventCode). credentials (access token or API secret) is required for Meta, TikTok and GA4, refused for Google Ads, and goes to the secrets manager.

Authentication: API key (Bearer)
Permission: sell:manage
Idempotency-Key: Not used
Success: 201

Request body · application/jsonrequired

storeIdstring · uuidrequired
kindstringrequired
One ofmetatiktokga4google_ads
settingsmap<string, any>required
credentialsstring
min 8 chars · max 4096 chars
enabledboolean
Default true

Responses

201Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/pixel-destinations" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
  "kind": "meta",
  "settings": {}
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Retrieve a pixel destination

GET/v1/pixel-destinations/{id}

One pixel destination (no secret).

Authentication: API key (Bearer)
Permission: sell:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/pixel-destinations/db63e441-e2d4-4f33-a3cc-5cec-34b" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Update a pixel destination

PATCH/v1/pixel-destinations/{id}

Changes settings, replaces the stored secret (credentials) or turns a destination on or off.

Authentication: API key (Bearer)
Permission: sell:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Request body · application/jsonrequired

settingsmap<string, any>
credentialsstring
min 8 chars · max 4096 chars
enabledboolean

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PATCH "$GIEP_API_URL/v1/pixel-destinations/db63e441-e2d4-4f33-a3cc-5cec-34b" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {},
  "credentials": "string",
  "enabled": false
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Remove a pixel destination

DELETE/v1/pixel-destinations/{id}

Removes a destination that never delivered anything; one with delivery history answers 409 destination_has_history (turn it off instead).

Authentication: API key (Bearer)
Permission: sell:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X DELETE "$GIEP_API_URL/v1/pixel-destinations/db63e441-e2d4-4f33-a3cc-5cec-34b" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Send a test event and return the platform's answer

POST/v1/pixel-destinations/{id}/test

Sends one test event to the platform and returns its answer (HTTP status and detail). Meta and TikTok need a test event code first, so a live pixel is never touched; Google Ads fires in the browser only and cannot be tested here. Audited.

Authentication: API key (Bearer)
Permission: sell:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/pixel-destinations/db63e441-e2d4-4f33-a3cc-5cec-34b/test" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Server-side delivery health per pixel destination

GET/v1/pixel-destinations/health

Server-side delivery health per destination: delivered, retrying and dead-lettered events, success rate, last success and failure, last error.

Authentication: API key (Bearer)
Permission: sell:read
Idempotency-Key: Not used
Success: 200

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/pixel-destinations/health" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Stores with their pixel consent setting

GET/v1/pixel-destinations/stores

Stores with their pixel consent setting.

Authentication: API key (Bearer)
Permission: sell:read
Idempotency-Key: Not used
Success: 200

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/pixel-destinations/stores" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Require shopper consent before pixels load for a store

PUT/v1/pixel-destinations/stores/{storeId}

With consentRequired: true, no pixel loads and no event is sent for a shopper who has not accepted. New stores start with it on.

Authentication: API key (Bearer)
Permission: sell:manage
Idempotency-Key: Not used
Success: 200

Path parameters

storeIdstringrequired

Request body · application/jsonrequired

consentRequiredbooleanrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PUT "$GIEP_API_URL/v1/pixel-destinations/stores/string" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "consentRequired": false
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}