# Superfiliate Partner API

> REST API for Superfiliate partners: customers, campaigns, conversions, orders, custom reports, and webhooks. Authenticate every request with `Authorization: Bearer <client_id>:<client_secret>`.

- Base URL: `https://api.superfiliate.com`
- Authentication: `Authorization: Bearer <client_id>:<client_secret>` on every request
- Full documentation as one markdown file: https://docs.superfiliate.com/llms-full.txt
- Machine-readable OpenAPI 3.0 spec: https://api.superfiliate.com/api/v1/docs.json

## Guides

- [Agent Guides](https://docs.superfiliate.com/docs/dry-run-api): Use agent-readable docs and dry-run requests to validate your Partners API integration.
- [Getting Started](https://docs.superfiliate.com/docs/getting-started): Create a key in Settings → Developers, authenticate, and make your first request.
- [Authentication](https://docs.superfiliate.com/docs/authentication): One bearer header, scoped credentials, and the endpoint access they unlock.
- [API Keys](https://docs.superfiliate.com/docs/api-keys): Create, copy, and revoke credentials in Settings → Developers.
- [Attribution](https://docs.superfiliate.com/docs/attribution): Track conversions and attribute revenue to creators through their links and discount codes on a Custom OMS (non-Shopify) store.
- [Import creators and codes](https://docs.superfiliate.com/docs/import-creators): Migrate existing creators and referral codes with the CSV import tool or the API.
- [Sync discount codes](https://docs.superfiliate.com/docs/sync-discount-codes): Use code notifications and the API to create and update discounts in your commerce platform.
- [Add creators to gifting campaigns](https://docs.superfiliate.com/docs/gifting): Find or create customers and add them to a gifting or seeding campaign.
- [Import your product catalog](https://docs.superfiliate.com/docs/import-products): Import products and variants from your Custom OMS through the API, then choose them for gifting campaigns.
- [Fulfill gifts with your OMS](https://docs.superfiliate.com/docs/fulfill-gifts): Create merchant-managed gift orders in your system and report order placement and shipment to Superfiliate.
- [Rate Limiting](https://docs.superfiliate.com/docs/rate-limiting): A leaky bucket per store: 50 requests of burst, refilling at 2 per second.
- [Pagination](https://docs.superfiliate.com/docs/pagination): Walk large collections with the page and items query parameters.
- [Errors](https://docs.superfiliate.com/docs/errors): Conventional status codes and a JSON envelope that always looks the same.
- [Webhooks](https://docs.superfiliate.com/docs/webhooks): Get customer changes pushed to your endpoint, verify signatures, and handle retries.

## API Reference

- [GET /api/dry-run/v1/attribution — Get attribution installation](https://docs.superfiliate.com/agents/reference/attribution/dry-run-get-attribution-installation): Returns the shop-specific script tag used to install Superfiliate attribution tracking.
- [GET /api/dry-run/v1/campaigns — List campaigns](https://docs.superfiliate.com/agents/reference/campaigns/dry-run-list-campaigns): 
- [GET /api/dry-run/v1/conversions — Search for conversions](https://docs.superfiliate.com/agents/reference/conversions/dry-run-search-conversions): 
- [POST /api/dry-run/v1/conversions/{id}/reject — Reject a conversion](https://docs.superfiliate.com/agents/reference/conversions/dry-run-reject-conversion): Rejects one conversion, with the same rules and side effects as **Reject conversion** in the Superfiliate app.
- [GET /api/dry-run/v1/customers — Search for customers](https://docs.superfiliate.com/agents/reference/customers/dry-run-search-customers): 
- [POST /api/dry-run/v1/customers — Create customer](https://docs.superfiliate.com/agents/reference/customers/dry-run-create-customer): Creates a customer when the email is new.
- [PUT /api/dry-run/v1/customers/{id} — Update customer](https://docs.superfiliate.com/agents/reference/customers/dry-run-update-customer): Updates only the supplied code, first_name, last_name, email, phone, instagram_handle, and tiktok_handle.
- [POST /api/dry-run/v1/customers/{id}/enroll — Enroll a customer](https://docs.superfiliate.com/agents/reference/customers/dry-run-enroll-customer): Enrolls a customer to a campaign, if not already enrolled to a campaign.
- [POST /api/dry-run/v1/customers/{id}/add_balance — Add balance](https://docs.superfiliate.com/agents/reference/customers/dry-run-add-balance): Adds balance to a customer.
- [GET /api/dry-run/v1/customers/{id}/insights — Get customer insights](https://docs.superfiliate.com/agents/reference/customers/dry-run-get-customer-insights): 
- [POST /api/dry-run/v1/customers/{id}/redact — Redact a customer](https://docs.superfiliate.com/agents/reference/customers/dry-run-redact-customer): Redacts the customer's personal data and records the redaction request for future synchronization.
- [GET /api/dry-run/v1/gifting_campaigns — List gifting campaigns](https://docs.superfiliate.com/agents/reference/gifting/dry-run-list-gifting-campaigns): Lists seeding campaigns belonging to your shop, including campaigns without submitted gifts.
- [POST /api/dry-run/v1/gifting_campaigns/{id}/enroll — Enroll a customer in a gifting campaign](https://docs.superfiliate.com/agents/reference/gifting/dry-run-enroll-customer-in-gifting-campaign): Enrolls an existing Superfiliate customer in an active seeding/gifting campaign.
- [GET /api/dry-run/v1/gifting_rewards — List gifting rewards](https://docs.superfiliate.com/agents/reference/gifting/dry-run-list-gifting-rewards): Lists creator details submitted for merchant-managed gifting campaigns.
- [POST /api/dry-run/v1/gifting_rewards/{id}/fulfill — Fulfill a gifting reward (Beta)](https://docs.superfiliate.com/agents/reference/gifting/dry-run-fulfill-gifting-reward): Records fulfillment for a merchant-managed gift after the creator submits their details.
- [GET /api/dry-run/v1/products — List products](https://docs.superfiliate.com/agents/reference/products/dry-run-list-products): Lists external OMS products and their variants for the authenticated shop.
- [GET /api/dry-run/v1/products/{id} — Fetch product](https://docs.superfiliate.com/agents/reference/products/dry-run-get-product): Fetches one external OMS product and its variants for the authenticated shop.
- [POST /api/dry-run/v1/products — Upsert product](https://docs.superfiliate.com/agents/reference/products/dry-run-create-product): Creates or updates an external OMS product by `source` and `external_id`.
- [POST /api/dry-run/v1/reports — Create custom report](https://docs.superfiliate.com/agents/reference/reports/dry-run-create-report): Creates a custom report that appears in the reporting UI.
- [GET /api/dry-run/v1/reports — List reports](https://docs.superfiliate.com/agents/reference/reports/dry-run-list-reports): Lists all saved reports for the authenticated shop.
- [GET /api/dry-run/v1/reports/{id}/data — Fetch report data](https://docs.superfiliate.com/agents/reference/reports/dry-run-fetch-report-data): Runs a saved report and returns its rows.
- [GET /api/dry-run/v1/webhooks — List webhooks](https://docs.superfiliate.com/agents/reference/webhooks/dry-run-list-webhooks): 
- [POST /api/dry-run/v1/webhooks — Create webhook](https://docs.superfiliate.com/agents/reference/webhooks/dry-run-create-webhook): 
- [DELETE /api/dry-run/v1/webhooks/{id} — Remove webhook](https://docs.superfiliate.com/agents/reference/webhooks/dry-run-delete-webhook): 
- [GET /api/v1/attribution — Get attribution installation](https://docs.superfiliate.com/reference/attribution/get-attribution-installation): Returns the shop-specific script tag used to install Superfiliate attribution tracking. Requires `attribution.read`.
- [GET /api/v1/campaigns — List campaigns](https://docs.superfiliate.com/reference/campaigns/list-campaigns): Requires `campaigns.read`.
- [GET /api/v1/conversions — Search for conversions](https://docs.superfiliate.com/reference/conversions/search-conversions): Requires `conversions.read`.
- [POST /api/v1/conversions/{id}/reject — Reject a conversion](https://docs.superfiliate.com/reference/conversions/reject-conversion): Rejects one conversion, with the same rules and side effects as **Reject conversion** in the Superfiliate app. Requires `conversions.write`.
- [GET /api/v1/customers — Search for customers](https://docs.superfiliate.com/reference/customers/search-customers): Requires `customers.read`.
- [POST /api/v1/customers — Create customer](https://docs.superfiliate.com/reference/customers/create-customer): Creates a customer when the email is new. Requires `customers.write`.
- [PUT /api/v1/customers/{id} — Update customer](https://docs.superfiliate.com/reference/customers/update-customer): Updates only the supplied code, first_name, last_name, email, phone, instagram_handle, and tiktok_handle. Requires `customers.write`.
- [POST /api/v1/customers/{id}/enroll — Enroll a customer](https://docs.superfiliate.com/reference/customers/enroll-customer): Enrolls a customer to a campaign, if not already enrolled to a campaign. Requires `customers.write`.
- [POST /api/v1/customers/{id}/add_balance — Add balance](https://docs.superfiliate.com/reference/customers/add-balance): Adds balance to a customer. Requires `customers.write`.
- [GET /api/v1/customers/{id}/insights — Get customer insights](https://docs.superfiliate.com/reference/customers/get-customer-insights): Requires `customers.read`.
- [POST /api/v1/customers/{id}/redact — Redact a customer](https://docs.superfiliate.com/reference/customers/redact-customer): Redacts the customer's personal data and records the redaction request for future synchronization. Requires `customers.write`.
- [GET /api/v1/gifting_campaigns — List gifting campaigns](https://docs.superfiliate.com/reference/gifting/list-gifting-campaigns): Lists seeding campaigns belonging to your shop, including campaigns without submitted gifts. Requires `gifting_campaigns.read`.
- [POST /api/v1/gifting_campaigns/{id}/enroll — Enroll a customer in a gifting campaign](https://docs.superfiliate.com/reference/gifting/enroll-customer-in-gifting-campaign): Enrolls an existing Superfiliate customer in an active seeding/gifting campaign. Requires `gifting_campaigns.write`.
- [GET /api/v1/gifting_rewards — List gifting rewards](https://docs.superfiliate.com/reference/gifting/list-gifting-rewards): Lists creator details submitted for merchant-managed gifting campaigns. Requires `gifting_rewards.read`.
- [POST /api/v1/gifting_rewards/{id}/fulfill — Fulfill a gifting reward (Beta)](https://docs.superfiliate.com/reference/gifting/fulfill-gifting-reward): Records fulfillment for a merchant-managed gift after the creator submits their details. Requires `gifting_rewards.write`.
- [GET /api/v1/products — List products](https://docs.superfiliate.com/reference/products/list-products): Lists external OMS products and their variants for the authenticated shop. Requires `products.read`.
- [GET /api/v1/products/{id} — Fetch product](https://docs.superfiliate.com/reference/products/get-product): Fetches one external OMS product and its variants for the authenticated shop. Requires `products.read`.
- [POST /api/v1/products — Upsert product](https://docs.superfiliate.com/reference/products/create-product): Creates or updates an external OMS product by `source` and `external_id`. Requires `products.write`.
- [POST /api/v1/reports — Create custom report](https://docs.superfiliate.com/reference/reports/create-report): Creates a custom report that appears in the reporting UI. Requires `reports.write`.
- [GET /api/v1/reports — List reports](https://docs.superfiliate.com/reference/reports/list-reports): Lists all saved reports for the authenticated shop. Requires `reports.read`.
- [GET /api/v1/reports/{id}/data — Fetch report data](https://docs.superfiliate.com/reference/reports/fetch-report-data): Runs a saved report and returns its rows. Requires `reports.read`.
- [GET /api/v1/webhooks — List webhooks](https://docs.superfiliate.com/reference/webhooks/list-webhooks): Requires `webhooks.read`.
- [POST /api/v1/webhooks — Create webhook](https://docs.superfiliate.com/reference/webhooks/create-webhook): Requires `webhooks.write`.
- [DELETE /api/v1/webhooks/{id} — Remove webhook](https://docs.superfiliate.com/reference/webhooks/delete-webhook): Requires `webhooks.write`.

## Optional

- [API reference overview](https://docs.superfiliate.com/reference): every endpoint with its required scope
- Support: hello@superfiliate.com