Start Here

Giftpack APIs let your backend create and operate reward, incentive, merchandise, and recipient-choice workflows. Giftpack handles catalog availability, recipient experiences, fulfillment, and delivery updates while your system owns the business trigger and customer data.

The production base URL is:

https://developer.giftpack.ai

Use the API Reference for the complete request and response schemas. Use this guide to choose the right resource family and understand how the resources progress after creation.

Choose a Workflow

Resource Model

Smart Gifting uses a campaign as the program container and a giftee as the recipient-specific lifecycle:

Campaign -> Giftee -> Redemption -> Fulfillment -> Delivery

Direct catalog orders use a marketplace order as the order container and a marketplace order receiver as each recipient-specific lifecycle:

Marketplace Order -> Receiver -> Claim or Selection -> Fulfillment -> Delivery

Do not treat giftee and marketplace_order_receiver as interchangeable. Their event names identify different order families even when their fulfillment states look similar.

Request Lifecycle

Create and update requests return the current resource state. Recipient actions, fulfillment, shipping, and delivery continue asynchronously.

For reliable integrations:

• Save the returned resource ID.
• Subscribe to the matching webhook event family.
• Treat webhook event id as the deduplication key.
• Reconcile with a GET endpoint when your system detects a missed or delayed event.
• Do not automatically retry a state-changing request unless its API operation explicitly documents an idempotency contract.

First Request

After creating an API key in Giftpack, verify access with the webhook event catalogue:

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

The response lists the webhook event types currently supported by the API. This endpoint, rather than a hard-coded client list, is the authoritative event catalogue.

Next Steps

1. Read Authentication and Security before storing or using an API key.
2. Select a workflow under Implementation Recipes.
3. Configure and verify webhooks before launching a production integration.
4. Use the API Reference for endpoint-specific required fields and response models.

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 and Security

Core Giftpack /v1 operations use a workspace-scoped API key in the X-API-KEY header. API keys must only be used by trusted server-side applications.

Access Requirements

API key management is available from Developer Settings. The workspace and current user must have access to the Giftpack Open API feature and the required developer-setting permissions.

If the Developer page is unavailable, ask a workspace administrator to confirm the workspace plan and your role before building the integration.

Create and Store a Key

1. Sign in to Giftpack.
2. Open Developer Settings.
3. Create an API key for the intended environment.
4. Store the key in a server-side secret manager.

Never place an API key in browser JavaScript, a mobile application, logs, screenshots, support tickets, or source control.

Use separate credentials for staging and production. Revoke a key immediately if it may have been exposed.

Authenticate a Request

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

The API key identifies the workspace. Resource authorization is enforced server-side, so an ID from another workspace does not grant access to that resource.

Environment and Transport

• Send production requests to https://developer.giftpack.ai.
• Use HTTPS for every request.
• Keep credentials in environment-specific secret storage.
• Do not reuse a production key in local development.

Some connector operations in the API Reference use bearer tokens or provider-specific authentication. Follow the security scheme shown on the individual operation; do not assume a Giftpack API key can call a connector endpoint.

Operational Practices

• Rotate credentials according to your organization's security policy.
• Limit key access to the service that needs it.
• Redact X-API-KEY from request and error logs.
• Record the operation, resource ID, HTTP status, and timestamp for support diagnostics.
• Validate webhook signatures independently from API request authentication.

The public contract does not promise a universal rate limit or one retry policy for every operation. Use endpoint-specific headers and the API Reference when available, and contact Giftpack before planning high-volume bursts.

Errors and Recovery

Giftpack operations use standard HTTP status codes. Error responses documented by the API Reference use application/problem+json.

Problem Response

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Property email is required but is missing.",
  "instance": "https://developer.giftpack.ai/errors/example",
  "errors": [
    {
      "location": "body.email",
      "message": "The email field is required.",
      "value": null
    }
  ]
}

Fields

• type: URI identifying the problem type. It may be about:blank.
• title: Stable human-readable summary of the problem.
• status: HTTP status associated with this response.
• detail: Explanation of this specific failure.
• instance: URI identifying this occurrence when supplied.
• errors: Optional field-level details with location, message, and value.

Not every field is guaranteed on every error. Write parsers that tolerate omitted optional fields and unknown future fields.

Recovery by Status

The API Reference is authoritative for the responses documented by each operation.

Retry Safety

GET requests can normally be retried with capped exponential backoff. State-changing requests require more care:

• Do not blindly retry POST or PATCH requests after a timeout.
• First check whether the operation documents idempotency or returns a resource that can be reconciled.
• Persist returned IDs before beginning the next step.
• Use your own business reference fields where the endpoint supports them.
• Prevent concurrent workers from submitting the same logical operation.

A transport timeout means the client did not receive a response; it does not prove that the server did not complete the request.

Support Diagnostics

When escalating an issue, provide the endpoint, method, UTC timestamp, HTTP status, relevant resource IDs, and a redacted problem response. Never include an API key or unredacted recipient data.

Webhooks and Async Events

Webhooks report recipient and fulfillment transitions that happen after an API request returns. Use them as the primary lifecycle signal, and use GET operations for reconciliation.

Event Catalogue

Retrieve the current catalogue instead of hard-coding an older list:

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

The current catalogue contains two resource families.

giftee

Recipient lifecycle events for Smart Gifting orders, including campaigns initiated through integrations, scheduled programs, and automated reward workflows.

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed
• giftee.cancel
• giftee.resume
• giftee.delete

marketplace_order_receiver

Recipient lifecycle events for orders placed directly through Gift Mall or the Merchandise Catalog, outside Smart Gifting campaign workflows.

• marketplace_order_receiver.created
• marketplace_order_receiver.launched
• marketplace_order_receiver.shipped
• marketplace_order_receiver.delivered
• marketplace_order_receiver.failed
• marketplace_order_receiver.returned
• marketplace_order_receiver.reviewed
• marketplace_order_receiver.delete

Payload Contract

Each delivery is a JSON object. data is a structured resource snapshot, not an escaped JSON string.

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "type": "giftee.shipped",
  "data": {
    "id": "23e4567-e89b-12d3-a456-426655440000",
    "type": "giftee",
    "email": "recipient@example.com",
    "status": 12,
    "delivery_status": 2,
    "budget": 100,
    "campaign": {
      "id": "323e4567-e89b-12d3-a456-426655440000"
    },
    "recipient": {
      "id": "423e4567-e89b-12d3-a456-426655440000"
    },
    "delivery_tracking_code": "TRACKING-CODE"
  },
  "created_at": "2026-09-01 15:23:33"
}

• id is the durable event occurrence ID and should be your deduplication key.
• type identifies the resource family and transition.
• data captures the resource state when the event occurred. Fields differ by resource family and lifecycle stage.
• created_at is the occurrence time. Deliveries can arrive out of order, so use this value when ordering transitions.
• Delete events retain the final stored snapshot after the live resource is removed.

Signature Verification

Giftpack sends the lowercase hexadecimal HMAC-SHA256 digest of the raw request body in X-Giftpack-Signature.

const crypto = require('crypto');

function verifyGiftpackWebhook(rawBody, signature, secret) {
  if (!signature) return false;

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const actualBuffer = Buffer.from(signature, 'utf8');
  const expectedBuffer = Buffer.from(expected, 'utf8');

  return (
    actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

Verify the signature before parsing or processing the payload. Store webhook secrets in server-side secret storage.

Delivery and Retry Behavior

• Giftpack sends an HTTP POST with a JSON body.
• Any 2xx response marks the delivery successful.
• A request can remain open for up to 60 seconds.
• Failed deliveries are retried after approximately 1, 5, and 15 minutes, for at most four delivery attempts including the initial request.
• Duplicate delivery is possible. Process id idempotently.
• Delivery order is not guaranteed.

Return a 2xx quickly after validating and durably accepting the event. Move expensive work to a queue.

Event Log Status

Webhook event and request logs use these numeric statuses:

• -1: failed
• 0: processing
• 1: success

The event detail response includes the structured webhook_event_data, attempt count, and individual request records for troubleshooting.

Production Checklist

• Subscribe only to the event families your workflow creates.
• Verify X-Giftpack-Signature against the unmodified raw body.
• Deduplicate by event id.
• Store created_at and allow out-of-order arrival.
• Return 2xx only after the event is safely accepted.
• Monitor events that reach failed status.
• Use the dashboard test action before enabling a production endpoint.

Implementation Recipes

Choose the resource family that matches how the recipient receives the reward. The API Reference remains authoritative for every required field and response model.

curl https://developer.giftpack.ai/v1/marketplaceorders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "marketplace_order_name": "September employee rewards",
    "marketplace_order_start_date": "2026-09-01",
    "marketplace_order_end_date": "2026-09-30",
    "marketplace_order_type": "Normal",
    "submit": false,
    "receivers": [
      {
        "member_id": "9a1232aa-238f-421c-82e7-45693d1b25b4",
        "country": "US",
        "gift_message": "Thank you for your contribution.",
        "email_notification": true,
        "sms_notification": false,
        "marketplace_feature": false,
        "donation_feature": false,
        "products": [
          {
            "marketplace_product_id": "961be65a-88d8-4040-8808-843ccf5da624",
            "marketplace_product_variant_id": "961be65a-a96a-412d-b22a-325f07d85647",
            "product_quantity": 1
          }
        ]
      }
    ]
  }'

curl https://developer.giftpack.ai/v1/pointrecipients/MEMBER_ID/points \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "credits": 1,
    "points": 100,
    "expired_at": "2027-09-01",
    "notes": "Annual recognition allocation"
  }'

Before Production

• Validate required fields against the current API Reference.
• Test with non-production recipients and credentials.
• Persist every returned resource ID.
• Configure the matching webhook family.
• Verify signatures and deduplicate events.
• Define how your system reconciles timeouts before retrying a state-changing request.