Once an invited user completes signup, payment, or another key conversion in your product, you can call this endpoint to report the event to PartnerShare, completing attribution, reward calculation, commission tallying, and downstream data.
1. Applicable scenarios
Signup event: Report immediately once a user completes signup, to establish the attribution relationship and the invited-user relationship.
Payment event: Report after a user completes payment, places an order, or subscribes, used to calculate amount-based rewards, commission, or conversion revenue.
Custom event: Business actions such as activation, upgrade, renewal, or milestone completion can also be reported uniformly as conversion events.
Rewards & settlement: Once an event is successfully reported, PartnerShare tallies rewards, attributes effectiveness, and proceeds with downstream commission settlement according to the campaign rules.
2. Endpoint info
| Item | Description |
|---|---|
| Method | POST |
| Path | /api/open/v1/track/conversion |
| Host | https://api-service.partnershare.net |
| Format | application/json |
| Auth | X-Api-Key + X-Api-Timestamp + X-Api-Sign |
| Purpose | The brand’s server calls this after a user completes signup, payment, or another business conversion, to report the result to PartnerShare for attribution, reward calculation, effectiveness tracking, and commission settlement. |
3. Request headers
| Header | Required | Description |
|---|---|---|
X-Api-Key | Yes | The API Key assigned by PartnerShare |
X-Api-Timestamp | Yes | Second-precision timestamp |
X-Api-Sign | Yes | Signature generated from request parameters, timestamp, and the API Secret |
Content-Type | Yes | Fixed as application/json |
See “API Authentication & Signature Mechanism” for the signing algorithm. We recommend all conversion events be initiated server-side — never expose the API Secret in the frontend.
4. Request parameters
4.1 Attribution parameters #
PartnerShare first needs to confirm “which promoter drove this conversion.” For external integration, only these two attribution methods are supported — choose one, with click_id preferred.
| Parameter | Type | Required | Description |
|---|---|---|---|
click_id | string | One of two | Click-tracking ID, usually from the ps_click_id cookie on the landing page — higher attribution accuracy, recommended first choice |
invite_code | string | One of two | Referral invite code, usually from a landing-page parameter or the ps_ref cookie — for cases where click_id isn’t available |
If you have both click_id and invite_code, we recommend prioritizing click_id for more stable attribution.
4.2 Event parameter #
| Parameter | Type | Required | Description |
|---|---|---|---|
event_name | string | Yes | Event name. We recommend signup for a signup event and purchase for a payment event; you may also use a custom name for extended business scenarios |
For external integration, you only need to pass event_name — we recommend using a unified business event name that both frontend/backend and your ops/finance teams understand consistently.
4.3 User parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
invited_user_id | string | Important | The invited user’s unique ID within the brand’s own system. Recommended required for signup events; also recommended for subsequent payment/custom events to keep the same user identifiable |
invited_user_name | string | No | The invited user’s display name, useful for data viewing and ops troubleshooting |
For payment or custom events, if this same user already had a successful signup-event report and this request doesn’t include click_id or invite_code, PartnerShare will prioritize the confirmed attribution from that user’s prior signup event to auto-complete this conversion’s attribution.
4.4 Transaction parameters (commonly used for payment events) #
| Parameter | Type | Required | Description |
|---|---|---|---|
transaction_id | string | Strongly recommended | Transaction/order number, used for de-duplication and traceability |
conversion_value | float | Depends on reward rule | Conversion amount. Required if the reward rule settles by percentage |
transaction_cycle_count | int | No | Number of billing cycles for installment rewards, e.g., 12 |
5. Request examples
5.1 Signup event example #
json #
{
"click_id": "clk_7f8c0d1a2b3c",
"invite_code": "LN088",
"event_name": "signup",
"invited_user_id": "user_10001",
"invited_user_name": "Tom"
}
5.2 Payment event example #
json #
{
"click_id": "clk_7f8c0d1a2b3c",
"event_name": "purchase",
"invited_user_id": "user_10001",
"transaction_id": "order_202604220001",
"conversion_value": 99.9
}
6. Response examples
6.1 Success #
json #
{
"code": 0,
"message": "Signup event reported successfully",
"data": {
"conversion_id": 1024,
"campaign_id": 145,
"affiliate_id": 204,
"event_type": 1,
"event_name": "signup",
"status": 1
}
}
6.2 Failure #
json #
{
"code": 6000000,
"message": "This conversion event already exists",
"data": null
}
7. Error codes
| Code | Description |
|---|---|
0 | Request successful |
1000004 | Auth failed — e.g., invalid API Key, wrong signature, expired timestamp, or IP not whitelisted |
1000005 | Request parameters or business preconditions failed validation — see message for details |
6000000 | Business validation failed — e.g., duplicate conversion event report — see message for details |
Business-level errors are returned with HTTP 200 — always check the code field in the response body to determine success; code = 0 means the call succeeded.
8. Integration notes
Report signup events immediately once a user completes signup — don’t delay it until login or profile completion.
Payment events must be submitted after the same user’s signup event has already been reported successfully. If you also pass click_id or invite_code, they must be consistent with the signup event’s attribution.
If a payment event requires strict de-duplication, always pass transaction_id. If using percentage-based rewards, also pass conversion_value.
If a payment event doesn’t include click_id or invite_code, make sure that user’s signup event was already reported successfully — otherwise attribution cannot be completed.
Where possible, preserve ps_click_id and ps_ref throughout the full flow, so both signup and payment events get more stable attribution.
