Introduction

Instead of building a separate rewards portal or manually coordinating vendors, you can orchestrate gifting events directly from your existing enterprise systems such as CRM, HRIS, or internal operations platforms. The API allows your application to trigger, manage, and monitor engagement moments programmatically while Giftpack handles fulfillment, availability, logistics, and compliance.

Giftpack is not structured like a traditional e-commerce API. Rather than centering on product catalogs and checkout transactions, the system models gifting as relationship events. Recipient identity, timing, and business context are treated as first-class inputs alongside the item being sent. This allows integrations to map naturally to real-world triggers such as onboarding, anniversaries, deal closures, retention campaigns, or customer engagement milestones.

The API provides lifecycle visibility across each stage of the gifting process, including redemption status, fulfillment progress, and delivery tracking. These endpoints allow your systems to measure outcomes, automate follow-up actions, and incorporate gifting into reporting and operational workflows.

Core Concept

At a system level, gifting in Giftpack follows a lifecycle model:

Intent → Campaign → Recipient → Redemption → Fulfillment → Tracking

Each stage represents a state transition in the engagement lifecycle:

• Intent defines the business trigger or purpose.
• Campaign acts as the engagement container.
• Recipient represents the identity participating in the campaign.
• Redemption captures the recipient’s action.
• Fulfillment handles the operational delivery process.
• Tracking provides post-action visibility and analytics.

Lifecycle Diagram

BUSINESS EVENT
    │
    ▼
[ Intent ]
    │
    │  (Synchronous API)
    ▼
[ Campaign Created ]
    │
    │  (Synchronous API)
    ▼
[ Recipient Attached ]
    │
    │  (Synchronous API)
    ▼
[ Redemption Link Issued ]
    │
    │  ────── User Action (Asynchronous) ──────
    ▼
[ Redemption Claimed ]
    │
    │  (Webhook: giftee.preparing)
    ▼
[ Shipment Processing ]
    │
    │  (Webhook: giftee.shipped)
    ▼
[ Tracking / Delivered ]
    │
    │  (Webhook: giftee.delivered / giftee.failed / giftee.returned)
    ▼
[ Final Tracking State ]
    │
    │  (Webhook: giftee.reviewed)
    ●

This lifecycle model applies consistently across smart gifting (AutoMatch™) campaigns, marketplace orders, swag workflows, and enterprise automation use cases. Understanding this model is essential for building reliable integrations, especially in asynchronous and event-driven environments.

Definitions

These definitions describe the core domain objects used across Giftpack API integrations. Understanding how these objects relate to each other is essential before building workflows. Giftpack operates on three primary layers:

1. Engagement Layer (Campaign-driven lifecycle)
2. Commerce Layer (Marketplace and Swag transactions)
3. Supply & Operations Layer (Vendors and fulfillment infrastructure)

Recipient
  └─ may belong to Recipient Group
  └─ becomes Giftee when attached to Campaign

Campaign (Engagement Container)
  ├─ defines Redemption rules
  ├─ manages Giftee states
  └─ may generate Fulfillment Orders

Commerce Layer
  ├─ Marketplace Order (direct transaction)
  └─ Swag Order (inventory-based transaction)

Redemption
  ├─ Link-based
  ├─ Email-based
  └─ Transitions state before fulfillment

Authentication & Security

All requests to the Giftpack Integration API must be authenticated using a valid API key.

Authentication is mandatory for every endpoint and enforced at the workspace boundary. Unauthorized or improperly authenticated requests are rejected before business logic is executed.

API Keys

Each Giftpack workspace may generate one or more API keys through the Giftpack dashboard.

API keys are used to:

• Authenticate API requests
• Identify the originating workspace
• Enforce resource-level authorization
• Apply usage controls and rate limits

API keys are workspace-scoped. They cannot access resources outside their originating workspace.

Giftpack does not share API keys across workspaces under any circumstances.

Obtaining an API Key

To generate an API key:

1. Log in to your Giftpack dashboard
2. Navigate to Integration Hub → API Keys
3. Generate a new API key under Giftpack Integration

API keys are immediately active upon creation. Key generation events are logged internally for audit and traceability purposes.

Using the API Key

Include your API key in the X-API-KEY header for every request.

GET /v1/recipients HTTP/1.1
Host: developer.giftpack.ai
X-API-KEY: YOUR_API_KEY

Requests without a valid API key will return an authentication error. Authentication occurs before request processing and resource evaluation.

Authorization Model

Authorization is enforced at the workspace level. An API key can only access:

• Recipients
• Campaigns
• Marketplace Orders
• Swag Orders
• Credits
• Providers
• Other resources belonging to its workspace

Cross-workspace access is strictly prohibited. Authorization decisions are enforced server-side and cannot be overridden by client parameters.

Key Lifecycle Management

Enterprise integrations should implement proper key lifecycle controls.

Recommended practices:

• Use separate API keys for staging and production environments
• Rotate API keys periodically
• Revoke API keys immediately if compromise is suspected
• Avoid sharing API keys across teams or systems

If an API key is revoked, all subsequent requests using that key will be rejected.

Giftpack does not automatically rotate API keys. Key management is the responsibility of the integrating organization.

Transport Security

All API requests must be made over HTTPS.

• Minimum TLS Version: TLS 1.2
• Plain HTTP requests are rejected

All data in transit is encrypted using industry-standard TLS encryption.

This includes:

• Recipient data
• Shipping information
• Order metadata
• Authentication headers

Giftpack does not support unsecured transport connections.

Rate Limiting

API requests are subject to rate limiting to ensure platform stability and fair usage. If a rate limit is exceeded, the API will return:

• HTTP status 429
• RATE_LIMIT_EXCEEDED error code

Integrations should:

• Implement retry logic
• Use exponential backoff strategies
• Avoid aggressive polling

For high-volume or burst-based enterprise workloads, contact Giftpack to discuss rate configuration.

Data Privacy & PII Handling

Giftpack APIs may process personally identifiable information (PII), including:

• Recipient names
• Email addresses
• Shipping addresses

Developers are responsible for:

• Ensuring lawful basis for data processing
• Obtaining necessary recipient consent where applicable
• Complying with relevant data protection regulations (e.g., GDPR, CCPA)
• Minimizing unnecessary data storage

Giftpack processes data solely for the purpose of executing gifting and reward workflows. Giftpack does not use recipient data for advertising or unrelated profiling.

Logging & Audit Considerations

For enterprise environments, integrations should:

• Log outbound API requests
• Log response codes and error states
• Monitor abnormal authentication failures
• Monitor unexpected rate-limit events

Giftpack maintains internal logging for:

• Authentication attempts
• Key usage
• Security-relevant events

Authentication Error Responses

Authentication and authorization errors follow a consistent structure.

{
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "action": "Verify your API key and include it in the X-API-KEY header"
}

Common authentication-related error codes include:

• UNAUTHORIZED
• FORBIDDEN
• RATE_LIMIT_EXCEEDED

Security Best Practices

For production deployments:

• Store API keys in secure environment variables
• Never expose API keys in frontend or client-side applications
• Do not commit API keys to version control
• Restrict internal access to production keys
• Use server-to-server integrations whenever possible

If an API key is suspected to be compromised:

1. Revoke the key immediately
2. Generate a replacement key
3. Review recent API logs for abnormal usage

Error Handling and Status Map

The Giftpack API uses conventional HTTP status codes and returns structured error payloads.

All error responses include a machine-readable error code and a request_id. Always log the request_id when contacting support.

Error Response Format

All errors follow this structure:

{
  "error": {
    "code": "invalid_request",
    "message": "Recipient email is required.",
    "request_id": "req_123"
  }
}

Fields

• code – Machine-readable error identifier
• message – Human-readable explanation
• request_id – Unique request trace identifier for debugging

The request_id should be retained in your logs for operational troubleshooting.

HTTP Status Codes

Giftpack uses standard HTTP status semantics:

• 200 / 201 – Request succeeded
• 400 – Validation or malformed request
• 401 – Missing or invalid API key
• 403 – Insufficient permissions
• 404 – Resource not found
• 409 – Conflict (e.g., duplicate resource or state violation)
• 429 – Rate limit exceeded
• 5xx – Internal server error

Retry Guidelines

Not all errors should be retried.

Safe to Retry

• 429 (Rate limit exceeded)
• 5xx (Server errors)

Use exponential backoff when retrying. Avoid aggressive immediate retries.

Do Not Retry

• 400 (Validation errors)
• 401 / 403 (Authentication or permission failures)
• 404 (Invalid resource reference)
• 409 (Business logic conflicts)

These indicate client-side issues that require correction before resubmission.

Asynchronous Status vs HTTP Status

A successful HTTP response does not guarantee fulfillment completion.

For example:

• 201 Created confirms a campaign was created
• It does not confirm redemption
• It does not confirm shipment
• It does not confirm delivery

Giftpack operations often progress asynchronously.

To determine lifecycle state:

• Query the resource status via GET endpoints
• Or listen to webhook events

Always treat HTTP success as request acceptance, not business completion.

Idempotency Considerations

If your integration performs retries, ensure that duplicate requests do not create unintended side effects.

Where applicable:

• Use unique external identifiers
• Store your own request tracking IDs
• Avoid blind retries on 4xx errors

Giftpack may reject duplicate resource creation depending on endpoint logic.

Rate Limiting Behavior

When rate limits are exceeded:

• HTTP status 429 is returned
• Retry after a delay

Integrations should:

• Implement exponential backoff
• Avoid tight polling loops
• Prefer webhook-based updates over frequent GET polling

Support and Diagnostics

If you encounter unexpected errors:

• Log the full error payload
• Record the request_id
• Provide the request_id when contacting Giftpack support

This allows rapid traceability in server logs.

Webhooks and Async Events

Giftpack workflows are asynchronous.

A successful API response confirms that a request was accepted. Lifecycle updates such as redemption, fulfillment, shipping, and delivery are communicated through webhook events.

Production integrations must treat webhooks as the primary state update mechanism. Polling status endpoints should only be used for reconciliation or recovery.

Supported Event Types

Webhook event types are managed and displayed directly in the Giftpack dashboard. To view or configure available event triggers:

https://giftpack.ai/app/developer/webhooks

The dashboard UI reflects the currently supported and production-ready event types. The UI should be considered the source of truth for available webhook events.

Example event types currently supported:

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed

Event availability may evolve over time. Always refer to the dashboard when configuring production integrations.

Webhook Configuration

Webhooks are configured per workspace via the dashboard. Each webhook configuration includes:

• name
• endpoint
• event_types
• active toggle
• Workspace-scoped secret key

Example configuration:

{
  "name": "Giftpack Delivery Updates",
  "endpoint": "https://example.com/webhooks/giftpack",
  "event_types": [
    "giftee.created",
    "giftee.shipped",
    "giftee.delivered"
  ]
}

Multiple webhook configurations may exist per workspace.

Delivery Model

Webhook delivery follows an at-least-once delivery model.

This means:

• Events may be delivered more than once
• Delivery order is not strictly guaranteed
• Integrations must implement idempotent handlers

A webhook delivery is considered successful when your endpoint returns any 2xx HTTP status code.

Non-2xx responses will trigger additional attempts.

Receiver Endpoint Contract

Your webhook endpoint must:

• Accept POST requests with JSON payload
• Return a 2xx HTTP status to acknowledge success
• Complete within a reasonable timeout window
• Handle duplicate events safely

Example acknowledgment:

HTTP/1.1 200 OK
Content-Type: application/json

{"ok": true}

Webhook handlers should use the webhook event ID as a deduplication key.

Event Log and Delivery Attempts

Giftpack provides a full webhook event log in the dashboard. Each webhook event contains:

• Event metadata
• Raw payload
• Delivery status
• Attempt count
• Per-attempt request and response diagnostics

Delivery status codes in logs:

• 0 – failed
• 1 – processing
• 2 – success

The event detail API exposes both:

• Webhook event (logical event)
• Webhook event requests (individual delivery attempts)

Example event detail object:

{
  "webhook_event_id": "wev_01H...",
  "webhook_setting_id": "whs_01H...",
  "webhook_event_type": "giftee.shipped",
  "webhook_event_resource_type": "giftee",
  "webhook_event_resource_id": "gft_01H...",
  "webhook_event_status": 2,
  "webhook_event_attempts": 1,
  "webhook_event_data": "{...raw payload...}",
  "webhook_event_created_at": "2026-02-20T02:00:00.000Z",
  "webhook_event_updated_at": "2026-02-20T02:00:01.000Z"
}

Each attempt record includes:

• Target endpoint
• HTTP response status
• Response headers
• Response body
• Timestamp

This log enables full delivery traceability and simplifies integration debugging.

Webhook Test Console

Giftpack provides a built-in Webhook Test Console in the dashboard. The test console allows you to:

• Select a webhook endpoint
• Choose an event type
• Send a simulated event payload
• View the live response from your endpoint

This enables:

• End-to-end validation
• Payload inspection
• Immediate response diagnostics

Example test response:

{
  "event_data": {
    "type": "giftee.created",
    "resource_type": "giftee",
    "resource_id": "gft_01H..."
  },
  "response_http_status": "200",
  "response_http_headers": {"content-type": "application/json"},
  "response_http_body": "{\"ok\":true}"
}

The test console is intended for development and validation prior to production activation.

Transport Requirements

While the current UI may allow both http and https endpoints, production integrations should always use HTTPS.

Using HTTPS ensures:

• Encrypted transport
• Protection against interception
• Compliance with enterprise security requirements

Integration Best Practices

For reliable webhook handling:

• Use idempotent event processing
• Log all incoming events
• Store event IDs for deduplication
• Avoid long synchronous processing inside the webhook handler
• Offload heavy work to background jobs
• Monitor failed delivery attempts

Webhook-based integration is the authoritative source of lifecycle updates. Do not assume that synchronous API responses represent final state.

Webhook Signature Verification

To ensure webhook events originate from Giftpack and have not been tampered with, each webhook request is signed using a workspace-specific webhook secret.

Production integrations must verify webhook signatures.

Signature Header Format

Each webhook request includes the following header:

X-GIFTPACK-SIGNATURE: t=1708459200,v1=abcdef1234567890...

Components

• t — Unix timestamp (seconds)
• v1 — HMAC SHA-256 signature

The signature is generated using:

HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

The raw request body must be used exactly as received.

Verification Process

To verify a webhook request:

1. Extract the X-GIFTPACK-SIGNATURE header.
2. Parse the timestamp (t) and signature (v1).
3. Retrieve the raw request body (before JSON parsing).
4. Compute:

expected_signature = HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

1. Compare the computed signature with v1 using a timing-safe comparison.
2. Reject the request if:

• Signature does not match
• Timestamp is too old (recommended: >5 minutes)

Replay Attack Protection

To prevent replay attacks:

• Validate that the timestamp is recent (within ±300 seconds).
• Store processed event IDs and reject duplicates.
• Do not accept unsigned webhook payloads.

Example time window:

current_time - timestamp <= 300 seconds

Example (Node.js)

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;

  const elements = signatureHeader.split(',');
  const timestamp = elements.find(e => e.startsWith('t='))?.split('=')[1];
  const signature = elements.find(e => e.startsWith('v1='))?.split('=')[1];

  if (!timestamp || !signature) return false;

  const payload = `${timestamp}.${rawBody}`;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );

  const currentTime = Math.floor(Date.now() / 1000);
  const tolerance = 300; // 5 minutes

  if (Math.abs(currentTime - Number(timestamp)) > tolerance) {
    return false;
  }

  return isValid;
}

Express example:

app.post('/webhooks/giftpack',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-giftpack-signature'];
    const isValid = verifySignature(
      req.body.toString(),
      signature,
      process.env.GIFTPACK_WEBHOOK_SECRET
    );

    if (!isValid) {
      return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body.toString());

    // Process event safely

    res.status(200).json({ ok: true });
});

Secret Management

Webhook secrets:

• Are unique per webhook configuration
• Must be stored securely (environment variables)
• Should never be exposed in client-side code
• Should be rotated if compromise is suspected

If a secret is rotated, update your integration immediately.

Failure Handling

If verification fails:

• Return a non-2xx HTTP status
• Do not process the payload
• Log the failure for security monitoring

Repeated signature failures may indicate:

• Secret mismatch
• Misconfigured endpoint
• Malicious traffic

Delivery Model Reminder

Webhook delivery follows an at-least-once model. Duplicate events are possible.

Always:

• Verify signature
• Validate timestamp
• Deduplicate using event ID

Built by Cases

Giftpack API is designed around real business workflows.

Instead of navigating endpoints directly, choose the business case you are implementing. Each case below outlines:

• Business intent
• API sequence
• Expected lifecycle
• Relevant webhook events

Detailed webhook verification and signature handling are documented in the Webhooks and Async Events section.

Create Campaign
      ↓
Add Giftee
      ↓
Generate Redemption Link
      ↓
Recipient Claims
      ↓
Order Processing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

POST /v1/campaigns

POST /v1/giftees

POST /v1/campaigns/{campaignId}/giftees/{gifteeId}/redeemlink

giftee.created
giftee.launched
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
giftee.reviewed

Select Product
      ↓
Create Marketplace Order
      ↓
Preparing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

GET /v1/providers/{providerCode}/products

GET /v1/providers/{providerCode}/products/{productId}

POST /v1/marketplaceorders

giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned

Enable Points
      ↓
Allocate Points
      ↓
Recipient Redeems
      ↓
Giftee Created
      ↓
Fulfillment Lifecycle

POST /v1/pointrecipients/{memberId}/enablepointfeature

PATCH /v1/pointrecipients/{memberId}/points

giftee.created
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned