How to

Add creators to gifting campaigns

Find or create customers and add them to a gifting or seeding campaign.

Add creators to an existing gifting or seeding campaign using their Superfiliate customer IDs. This works for Shopify and merchant-managed campaigns, whether or not the creator belongs to an affiliate program.

Create API credentials

In Settings → Developers, create a key with customers.write and gifting_campaigns.write. Each write scope also permits reads for that resource. These permissions must be explicitly granted to the key. Keep credentials on your server; see API Keys.

Find or create the customer

Call GET /api/v1/customers?email=john@example.com. If the array is empty, call POST /api/v1/customers with an email and optional first name, last name, phone and social handles. Save the returned id; this is a Superfiliate ID, separate from a Shopify or OMS customer ID. Use the creator’s email, not the email of a shopper they referred.

curl "https://api.superfiliate.com/api/v1/customers?email=john@example.com" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET"

curl -X POST "https://api.superfiliate.com/api/v1/customers" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"john@example.com","first_name":"John"}'

You can also call POST directly: an existing email returns that customer and updates any supplied non-blank profile fields. Omit fields you do not intend to update. The remaining examples assume the returned customer ID is 789012; replace it with your actual ID.

Choose the gifting campaign

Call GET /api/v1/gifting_campaigns?active=true and save the desired campaign ID. These IDs are separate from affiliate program IDs returned by /api/v1/campaigns.

curl "https://api.superfiliate.com/api/v1/gifting_campaigns?active=true&fulfillment_mode=merchant_managed&page=1&items=25" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET"

For Shopify campaigns, use fulfillment_mode=shopify. Request successive pages until an empty array is returned. The next example assumes you chose gifting campaign 345678.

Enroll the customer

curl -X POST "https://api.superfiliate.com/api/v1/gifting_campaigns/345678/enroll" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":789012}'

{
  "id": 123456,
  "customer_id": 789012,
  "gifting_campaign_id": 345678,
  "status": "unlocked"
}

Save the returned id as the gift/reward ID. Here, 123456 identifies the gift, not the creator or campaign. Use it later when reporting OMS fulfillment.

Repeated calls return the latest existing gift without issuing another, including when that gift is claimed or expired. An archived or expired campaign returns 422; a missing customer or campaign returns 404. Recurring campaigns continue to refresh gifts on their configured schedule.

See the endpoint reference for the full contract. To test without writes, use the matching dry-run endpoint with campaign 900901, customer 900002 and bearer token superfiliate-dry-run-agent.

For merchant-managed campaigns, continue with Fulfill gifts with your OMS to automate order placement and report shipment.

To give the same creator a referral code, enroll them separately in an affiliate program using the same customer ID. Follow Import through the API for enrollment and Sync discount codes to create the discount in your Custom OMS checkout.

Test gifting enrollment

• Enroll a test creator in your intended campaign and confirm the returned customer and campaign IDs match. Check that their gift appears in the app.
• Repeat the enrollment request and confirm the same gift ID is returned without issuing another gift.
• For a manual campaign, have the creator claim the gift and submit their details. For merchant-managed campaigns, continue with the fulfillment test before enabling automatic order creation.