Connect Hermes to Refersion

List Affiliates. Retrieves a paginated list of affiliates for the authenticated merchant. Includes affiliate profile information, offer details, and performance metrics. Supports filtering by status, search term, performance metrics, and offer IDs. The `status=approved` filter returns both regular APPROVED and locked-APPROVED affiliates; check the `locked` field on each record to distinguish them. The `status=denied` filter returns both DENIED and BANNED affiliates; banned records expose `status: "BANNED"` so they can be distinguished per row.

Get Affiliate Counts. Returns the count of affiliates grouped by status (pending, approved, denied) for the authenticated merchant. The deniedCount includes BANNED affiliates — banned affiliates are counted within the denied bucket. When called without filter parameters, results are cached for 1 minute. Supports the same filter parameters as GET /affiliates. When filters are supplied, the cache is bypassed and counts reflect the filtered result set. Performance-specific filters (the 34-parameter matrix across the pending, 30-day, and total buckets, plus hasPendingConversions and lastConversionDaysAgo) narrow only the approvedCount; pendingCount and deniedCount are not affected by those filters.

Get Affiliate Activity. Retrieves weekly conversion, payment, and click activity for a specific affiliate merged into a single timeline ordered by `date` descending and capped at 10 entries. Each source (conversion, payment, click) is independently bounded to the rolling last 10 weeks and capped at 5 entries before the merge. The response shape is polymorphic on `type`. Conversion entries include `conversionCount`, `total`, and `currency`; payment entries include `paidConversionCount`, `total`, and `currency`; click entries include `clickCount` (no `total` or `currency`).

Update Affiliate. Updates an affiliate's details including status, lock state, offer assignment, custom fields, URL configuration, merchant-assigned external identifier, and parent affiliate assignment. Supports partial updates - only the fields provided in the request body will be updated. Any transition between the valid public statuses (APPROVED, PENDING, DENIED) is permitted. Transitioning from APPROVED to DENIED is blocked if the affiliate has pending or unpaid conversions. Setting status to DELETED or DISABLED is not allowed via this endpoint — DISABLED is an internal flag managed via the `locked` field, and deletion uses the DELETE endpoint. The `locked` field abstracts the internal DISABLED state: `locked: true` locks an APPROVED affiliate, and `locked: false` unlocks it. `locked` is only accepted when the affiliate's current status is APPROVED, and it cannot be combined with `status` in the same request. The `parentAffiliateId` field accepts another affiliate ID owned by the authenticated client. Passing `null` clears the existing parent relationship.

Generate Affiliate Tracking Link. Generates an affiliate tracking link for the specified affiliate. When the affiliate ID is set to 0, the endpoint uses the default test affiliate for the account. Optional parameters allow for test link generation, custom URLs, and marketing asset association.

Get Affiliate Custom Fields. Retrieves all custom registration fields configured by the merchant for a given affiliate, along with the affiliate's corresponding values.

Update Affiliate Custom Field Value. Updates an affiliate's value for a specific custom registration field by modifying the affiliate's custom_fields JSON column.

Delete Affiliate Custom Field Value. Clears an affiliate's value for a specific custom registration field by removing the entry from the affiliate's custom_fields JSON data. The custom field definition itself is not modified or deleted. This operation is idempotent.

Get Click Data. Retrieves click tracking data based on supplied query parameters. Returns click information including affiliate details, timestamps, IP addresses, user agents, and referral data. Supports pagination and filtering by date range and affiliate ID.

Create Manual Credit. Creates a manual credit conversion for an affiliate. Supports PENDING, APPROVED, and DENIED statuses. For APPROVED and DENIED statuses, a notification is dispatched and a conversion_info record is created.

Credit Order to Affiliate. Credits an existing order from the conversion queue to a specified affiliate. The order is queued for processing and will be converted asynchronously.

Get Conversion Counts. Returns counts of conversions grouped by status (pending, approved, paid, denied, unqualified) for the authenticated merchant. Supports the same filters as the conversions list endpoint, excluding status, page, limit, sortBy, and sortOrder. Unfiltered requests are cached for 1 minute per client; filtered requests bypass the cache.

List Conversions. Retrieves a paginated list of conversions for the authenticated merchant. Supports filtering by status, order ID, affiliate, date range, offer, and platform. Supports sorting by order ID, affiliate, type, revenue, commission, date, source, and status.

Get Conversion Detail. Retrieves the full detail view for a single conversion owned by the authenticated client. The response includes affiliate info, offer info, click details, payment method, autoPay status, VIP status, and Amazon approval eligibility. Returns 404 for conversions that do not exist, are not owned by the authenticated client, or have HIDDEN status.

Update Conversion Status. Updates the status of a single conversion. Supports transitions between PENDING, APPROVED, DENIED, and UNQUALIFIED statuses based on a defined transition matrix. Creates an audit trail and dispatches webhook notifications for APPROVED and DENIED transitions.

List Offers. Retrieves a paginated list of offers for the authenticated client. Returns offer information including commission settings, attribution window, and various configuration options. Supports pagination, optional search filtering by offer name or ID, filtering by offer type (multi-value, OR semantics), and performance-range filtering across 17 metrics (Min/Max bounds for the pending, 30-day, and total buckets).

Update Offer. Updates an existing offer. Allows partial updates of one or more fields including name, default status, attribution window, private status, and commission. If offerId is 0, the client's default offer will be updated.

Duplicate Offer. Duplicates an offer owned by the authenticated client. Returns the new offer ID.

Delete Offer. Soft-deletes an offer owned by the authenticated client. The default offer and offers with assigned affiliates cannot be deleted. Refersion attempts to move a Marketplace listing that uses the deleted offer to the active default offer; with no active default offer, it attempts to turn the listing off.

Search Orders. Searches for orders by order ID and determines if an affiliate can be credited. Returns available orders and any other affiliates that already have conversions for the same order.

List Webhook Endpoints. Lists the webhook endpoints for the authenticated Refersion user. Cursor-paginated. Some users may receive a 402 if their plan doesn't include webhook access. The user's webhook configuration is auto-provisioned on first call — no endpoints yet just means an empty list, not an error. Each row has the endpoint's id, url, subscribed topics, and `isSubscribedToAllTopics` (true means `topics` is empty but every event type is delivered).

Create Webhook Endpoint. Registers a webhook endpoint for the authenticated Refersion user — lets an account subscribe programmatically instead of only through the webhook settings portal. Some users can only subscribe to a limited set of event types — anything else returns 422. Some users may receive a 402 if their plan doesn't include webhook access. The user's webhook configuration is auto-provisioned on first call. The 201 response's id is also what `DELETE /v3/webhooks/endpoints/{endpointId}` accepts.

Update Webhook Endpoint. Updates the delivery URL, subscribed event types, or both, for one webhook endpoint belonging to the authenticated Refersion user. `endpointId` is always resolved within the user's own webhook configuration, so another user's id returns the same 404 as an unknown one. Omitted fields are left unchanged; `topics` REPLACES the subscription rather than merging into it. Some users can only use a limited set of event types — anything else returns 422. Some users may receive a 402 if their plan doesn't include webhook access. Like delete, this never auto-provisions a configuration — a user with none gets 404.

Delete Webhook Endpoint. Removes one webhook endpoint belonging to the authenticated Refersion user. `endpointId` is always resolved within the user's own webhook configuration, so another user's id returns the same 404 as an unknown one. Deleting the same endpoint twice returns 404 on the second call (not idempotent-204 by design), and this operation never auto-provisions a configuration — a user with none simply gets 404.