How to

Fulfill gifts with your OMS

Create merchant-managed gift orders in your system and report order placement and shipment to Superfiliate.

Automate merchant-managed gifting through your own order management system (OMS) or fulfillment provider. Your backend places the gift order and reports order placement and shipment back to Superfiliate.

The flow is: enroll the creator → creator submits their gift details → reward becomes ready to send → your OMS places the order → report order placement → report shipment. Use the gift/reward ID throughout this flow; the creator, campaign, and OMS order each have their own IDs.

Before you start

First, import your product catalog through the API and configure the available variants in your merchant-managed gifting campaign. The import guide covers product IDs, variants, and keeping the catalog updated.

Create server-side credentials with gifting_rewards.write (which includes reward reads) and webhooks.write if subscribing to updates. Keep credentials on your backend; see API Keys.

Find gifts ready to send

For merchant-managed gifting, follow Add creators to gifting campaigns to enroll the creator, and let them submit their address and product selections. Subscribe to gifting_reward_updated with Create webhook, or poll the ready-to-send rewards. The following subscription sends updates to your backend:

curl -X POST "https://api.superfiliate.com/api/v1/webhooks" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://yourstore.com/webhooks/superfiliate/gifts",
  "topic": "gifting_reward_updated"
}'

curl "https://api.superfiliate.com/api/v1/gifting_rewards?gifting_stage=ready_to_send&page=1&items=25" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET"

This list returns an array and only includes merchant-managed gifts with submitted details. Add campaign_id=345678 to restrict it to a campaign. For webhooks, verify the signature, durably queue the work, then acknowledge with a 2xx response. The delivery body is the reward object directly. Only queue order creation when gifting_stage is ready_to_send. Deliveries can repeat or arrive late, so check your saved order mapping before creating anything. For a delayed delivery, reconcile the reward’s current stage through the rewards list before placing an order; an old ready-to-send notification should not trigger fulfillment for a gift that has since been canceled or shipped.

Create and register the gift order

When polling, collect reward IDs from all pages into your work queue before advancing their stages; updating a filtered list while paging through it can skip records. For each ready-to-send reward, use its shipping_address, creator details, and selected_products to create a gift order in your OMS or fulfillment provider. Use the reward ID as your idempotency key there and save the resulting external order ID. Ensure concurrent workers cannot create two orders for the same reward. Once your OMS confirms creation, register that order in Superfiliate:

curl -X POST "https://api.superfiliate.com/api/v1/gifting_rewards/123456/fulfill" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "order_placed",
  "external_provider": "your_oms",
  "external_order_id": "gift-order-123"
}'

Here, 123456 is the Superfiliate reward ID and gift-order-123 is your OMS order ID. For status: order_placed, both external_provider and external_order_id are required. Check the response has gifting_stage: order_placed and the expected order references under fulfillment.

If the OMS order succeeds but this API request fails, retry registration with the saved order ID. Do not create another OMS order. Use a durable retry queue for network failures, rate limits, and server errors. Resolve validation errors before retrying; see Errors and Rate Limiting.

Record shipment

After your provider confirms shipment, update the same reward with the actual carrier and tracking details. Always send status explicitly; omitting it defaults to shipped.

curl -X POST "https://api.superfiliate.com/api/v1/gifting_rewards/123456/fulfill" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "shipped",
  "external_provider": "your_oms",
  "external_order_id": "gift-order-123",
  "carrier": "UPS",
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "https://www.ups.com/track/1Z999AA10123456784"
}'

The fulfillment endpoint accepts merchant-managed rewards after creator details are submitted. Reuse the same order references on retries. Identical retries are supported; conflicting order references or changed details after shipment are rejected. Fulfillment updates also emit webhooks, so your handler should create orders only for ready-to-send gifts. A successful response records shipment in Superfiliate; your fulfillment provider remains responsible for shipping the package.

Test gift fulfillment

• Let a test creator submit their address and product choices. Confirm your integration receives the ready-to-send reward with those details.
• Confirm one gift order is created in your OMS and its external order ID is recorded against the same Superfiliate reward.
• Replay the webhook and retry the placement request. Confirm your OMS still has one order and Superfiliate keeps the same order reference. Simulate a failed registration after OMS creation and confirm retrying registers the existing order.
• Send the shipment update and confirm the reward's fulfillment details contain the expected carrier and tracking information, with gifting_stage: shipped. Replay both the update and resulting webhook; confirm no extra order is created and the gift does not return to an earlier stage.