How to

Sync discount codes

Use code notifications and the API to create and update discounts in your commerce platform.

Automatically create a checkout discount when a creator receives a referral code in Superfiliate, then keep it in sync as the code changes. For a Custom OMS (non-Shopify) store, Superfiliate exposes the code and offer configuration; your backend creates the usable discount in your commerce platform. Existing discounts can stay active while you connect this flow.

Before you start

Create server-side credentials with discounts.read and webhooks.write. Confirm that your custom commerce integration is active, and keep credentials on your backend. See API Keys.

Subscribe to code changes

Register one subscription for each topic before enrolling creators. The example uses a different URL for each topic so your receiver knows which action to take; deliveries contain the code object directly, without a topic wrapper. Then reconcile existing codes through the Alpha discount lookup:

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/discount_code_created",
  "topic": "discount_code_created"
}'

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/discount_code_updated",
  "topic": "discount_code_updated"
}'

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/discount_code_deleted",
  "topic": "discount_code_deleted"
}'

Verify each delivery’s raw-body signature with the secret of the API key that created the subscription, using the webhook guide. Save the work to a durable queue before returning a 2xx response. Deliveries can repeat or arrive out of order; reconcile against the current lookup before applying a delayed creation or update. For a deletion, retain the delivered code snapshot and your local mapping so you can disable the corresponding discount.

Apply the offer in your commerce platform

After affiliate enrollment returns JOHN for program 345678, look up the offer. The response is an array, even when filtering by one code:

curl "https://api.superfiliate.com/api/v1/discount_codes?campaign_id=345678&code=JOHN" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET"

[
  {
    "id": 456789,
    "code": "JOHN",
    "campaign_id": 345678,
    "lead_reward_unit": "percentage",
    "lead_reward_value": "10.0",
    "lead_discount_min_value": "50.0",
    "lead_discount_new_customers_only": true,
    "lead_apply_once_per_customer": true
  }
]

This example gives eligible new customers 10% off orders that meet the 50.00 minimum, once per customer. Create those rules in your discount engine before sharing the code. These are illustrative settings; use the values returned for your program.

• Upsert or disable local codes idempotently so retries do not create duplicates. If the code text changes, retire the old checkout code as part of the update. Reconcile periodically with the lookup API to catch missed notifications.
• Confirm your discount engine can enforce the configured offer and eligibility rules. Resolve unsupported rules before activating a code.
• Test the code in your checkout, then include the code actually applied in the backend paid-order request as discount_code. The browser checkout event uses discountCodes, an array. Follow the examples in Attribution. A redirect does not apply the discount for you.

Affiliate programs (/campaigns) and gifting campaigns (/gifting_campaigns) use different IDs. If a creator should receive both a referral code and a gift, configure both flows; gifting enrollment alone does not establish the referral-code setup. See Add creators to gifting campaigns.

Test discount synchronization

• Enroll a test creator and confirm their code is created in your commerce platform with the configured shopper offer and eligibility rules.
• Replay a webhook and confirm it does not create duplicate discounts. Change the code and confirm the old code stops working. Delete a code and confirm its local discount is disabled. Check delayed deliveries do not restore a retired code.
• Check eligible and ineligible customers, the minimum spend, and a second use by the same customer. Confirm checkout enforces your actual offer configuration.
• Complete a test purchase with the code and confirm the authenticated order includes the code actually applied. Follow the end-to-end tests in Attribution.