{
    "openapi": "3.1.0",
    "info": {
        "title": "Xaff API",
        "version": "1.0.0",
        "description": "Server-to-server. Token-authenticated, stateless, no session and no CSRF.\n\nEvery response carries a `request_id`. Quote it when contacting support \u2014 it is in every log line, audit event and security event for that request.\n\n**`offer_id`** is the offer\u2019s number as the platform shows it (`1042`, a string or an integer) or its public id; both are accepted.\n\n**Idempotency is required** on lead submission: send `Idempotency-Key` as a header or `idempotency_key` in the body. Repeating a key replays the stored response verbatim \u2014 including its status \u2014 with `Idempotent-Replay: true`; reusing one with a different payload is a 409.\n\n**Do not branch on the status class alone.** A status is not the same thing as an envelope: lead submission answers 423 with a *data* envelope when the offer is paused, because the lead was accepted and stored. Each response below states which envelope it carries, and a status that can carry either is declared as a `oneOf`.\n\nThe full error catalogue is published at `/docs/errors`."
    },
    "servers": [
        {
            "url": "https://xaff.io",
            "description": "This instance"
        }
    ],
    "components": {
        "securitySchemes": {
            "affiliateToken": {
                "type": "http",
                "scheme": "bearer",
                "description": "An affiliate API token, issued in the partner cabinet. Scoped, hashed at rest, revocable."
            },
            "callbackSignature": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Callback-Token",
                "description": "Advertiser callback credential. Sent with X-Timestamp and X-Signature: an HMAC-SHA256 over \"{timestamp}.{raw body}\"."
            }
        },
        "schemas": {
            "Success": {
                "type": "object",
                "required": [
                    "data",
                    "request_id"
                ],
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "reason_code": {
                                "type": "string",
                                "description": "Present when a lead was accepted but not delivered. Read this to decide whether the traffic is worth continuing.",
                                "enum": [
                                    "OFFER_PAUSED",
                                    "ADVERTISER_BALANCE_STOP",
                                    "INTEGRATION_UNAVAILABLE",
                                    "OFFER_APPROVAL_REQUIRED",
                                    "PRIVATE_OFFER",
                                    "INTEGRATION_OFFER_ACCESS_DENIED",
                                    "FRAUD_RULE",
                                    "ACCOUNT_SUSPENDED",
                                    "OFFER_DISABLED"
                                ]
                            }
                        },
                        "additionalProperties": true
                    },
                    "request_id": {
                        "type": "string",
                        "description": "Quote this when contacting support. It appears in every log line for the request."
                    }
                }
            },
            "Error": {
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "object",
                        "required": [
                            "code",
                            "message",
                            "request_id"
                        ],
                        "properties": {
                            "code": {
                                "type": "string",
                                "enum": [
                                    "MALFORMED_REQUEST",
                                    "INVALID_CURSOR",
                                    "MISSING_TOKEN",
                                    "UNAUTHENTICATED",
                                    "SIGNATURE_REQUIRED",
                                    "SIGNATURE_INVALID",
                                    "SIGNATURE_EXPIRED",
                                    "FORBIDDEN",
                                    "IP_NOT_ALLOWED",
                                    "NOT_FOUND",
                                    "DUPLICATE_LEAD",
                                    "IDEMPOTENCY_CONFLICT",
                                    "IDEMPOTENCY_IN_PROGRESS",
                                    "SIGNATURE_REPLAYED",
                                    "CONVERSION_ALREADY_FINAL",
                                    "OFFER_DISABLED",
                                    "VALIDATION_FAILED",
                                    "GEO_NOT_ALLOWED",
                                    "OFFER_NOT_AVAILABLE",
                                    "UNKNOWN_CLICK_ID",
                                    "OFFER_NOT_STRAIGHT_SALE",
                                    "CURRENCY_MISMATCH",
                                    "CLICK_NOT_ATTRIBUTABLE",
                                    "ORDER_CLICK_MISMATCH",
                                    "ORDER_CONFLICT",
                                    "OFFER_PAUSED",
                                    "OFFER_APPROVAL_REQUIRED",
                                    "ACCOUNT_SUSPENDED",
                                    "ADVERTISER_BALANCE_STOP",
                                    "RATE_LIMITED",
                                    "INTERNAL_ERROR",
                                    "INTEGRATION_UNAVAILABLE"
                                ]
                            },
                            "message": {
                                "type": "string"
                            },
                            "request_id": {
                                "type": "string"
                            },
                            "fields": {
                                "type": "object",
                                "description": "Present on VALIDATION_FAILED. One entry per field, each an array of {code, message}.",
                                "additionalProperties": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "code": {
                                                "type": "string",
                                                "enum": [
                                                    "REQUIRED",
                                                    "INVALID_FORMAT",
                                                    "OUT_OF_RANGE",
                                                    "NOT_ALLOWED",
                                                    "ALREADY_EXISTS",
                                                    "DUPLICATE_IN_FILE",
                                                    "GROUP_INCOMPLETE",
                                                    "GROUP_CONFLICT",
                                                    "GEO_MODE_MISMATCH",
                                                    "AMBIGUOUS",
                                                    "COUNTRY_INACTIVE",
                                                    "ADVERTISER_INACTIVE",
                                                    "CATEGORY_INACTIVE",
                                                    "RENAMED_COLUMN",
                                                    "NO_ACTIVE_GEO",
                                                    "TOO_LONG"
                                                ]
                                            },
                                            "message": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "paths": {
        "/api/v1/advertiser/callback": {
            "post": {
                "summary": "Report a status change for one of your conversions.",
                "operationId": "api.v1.advertiser.callback",
                "security": [
                    {
                        "callbackSignature": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The callback was received. `data.result` says what it achieved: `applied`, `duplicate` (an identical payload was already processed \u2014 recorded once, no second ledger movement) or `ignored` (received on purpose without a transition, for instance a conversion already in that status). All three are successes: a CRM that retries on any non-2xx would otherwise resend forever over a status we have already understood.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Success"
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Received, but the external status is not in this integration\u2019s status map. The raw value is stored against the conversion, no transition is made, and an operational notification is raised for a human to map it.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Success"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "- `UNAUTHENTICATED` \u2014 The API token is missing, invalid, expired or revoked.\n- `SIGNATURE_REQUIRED` \u2014 This callback credential requires a signature and timestamp header.\n- `SIGNATURE_INVALID` \u2014 The HMAC does not match the request body.\n- `SIGNATURE_EXPIRED` \u2014 The timestamp is outside the \u00b1300 second window.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "- `IP_NOT_ALLOWED` \u2014 The source address is not on this credential\u2019s allowlist.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "- `NOT_FOUND` \u2014 Unknown, belongs to another account, or a private offer you have not been granted \u2014 deliberately indistinguishable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "- `SIGNATURE_REPLAYED` \u2014 That exact signature has already been used.\n- `ORDER_CLICK_MISMATCH` \u2014 That order_id is already attributed to a different click_id. An order belongs to the click it was first reported with.\n- `ORDER_CONFLICT` \u2014 The same order was being updated by a concurrent request. Nothing was applied; send the event again.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "- `VALIDATION_FAILED` \u2014 Field validation failed. `error.fields` names each one.\n- `UNKNOWN_CLICK_ID` \u2014 No click of yours matches that click_id \u2014 unknown, or on another advertiser\u2019s offer, deliberately indistinguishable. The order is not attributed and the attempt is logged.\n- `CURRENCY_MISMATCH` \u2014 A settlement amount in a currency other than the offer\u2019s. There is no currency conversion: an order sold in another currency is accepted and waits for `settlement_amount` in the offer currency.\n- `CLICK_NOT_ATTRIBUTABLE` \u2014 The affiliate behind the click is not active, so a new order cannot be attributed to it.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "423": {
                        "description": "- `ACCOUNT_SUSPENDED` \u2014 This account cannot submit data: it is suspended, blocked or archived. Also the answer to an advertiser callback whose credential is valid but whose advertiser account is not active.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "- `RATE_LIMITED` \u2014 Too many requests.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "- `INTERNAL_ERROR` \u2014 Unexpected. Quote the request_id when contacting support.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/advertiser/conversions": {
            "post": {
                "summary": "Report an order created or changed on your shop for a straight-sale click.",
                "operationId": "api.v1.advertiser.conversions",
                "security": [
                    {
                        "callbackSignature": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The event was received. `data.result` is `created` (first event of a new order), `applied`, `unmapped` (the status has no mapping; the order state was still recorded), `stale` (older than the state already recorded \u2014 kept for history, applied to nothing) or `duplicate` (an identical event was already processed \u2014 no second conversion and no second ledger movement). Required: `click_id`, `order_id`, `status`; RevShare also `currency` and the commission base amount. Optional: `order_total`, `paid_amount` (omit or null until money is actually collected), `payment_status`, `payment_method`, `occurred_at`, `event_id`, `event_version`, `net_amount`, `refunded_amount` (the cumulative refunded part of the agreed base), `settlement_amount` + `settlement_currency` (the agreed base in the offer currency, for an order sold in another one). A payout sent by the advertiser is ignored, and the affiliate payout is never returned.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Success"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "- `MISSING_TOKEN` \u2014 No credential at all: neither an `X-Callback-Token` header nor a bearer token reached us. Distinct from UNAUTHENTICATED, which means a credential arrived and was not recognised \u2014 so check that the header is being sent before you check its value.\n- `UNAUTHENTICATED` \u2014 The API token is missing, invalid, expired or revoked.\n- `SIGNATURE_REQUIRED` \u2014 This callback credential requires a signature and timestamp header.\n- `SIGNATURE_INVALID` \u2014 The HMAC does not match the request body.\n- `SIGNATURE_EXPIRED` \u2014 The timestamp is outside the \u00b1300 second window.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "- `IP_NOT_ALLOWED` \u2014 The source address is not on this credential\u2019s allowlist.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "- `SIGNATURE_REPLAYED` \u2014 That exact signature has already been used.\n- `ORDER_CLICK_MISMATCH` \u2014 That order_id is already attributed to a different click_id. An order belongs to the click it was first reported with.\n- `ORDER_CONFLICT` \u2014 The same order was being updated by a concurrent request. Nothing was applied; send the event again.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "- `VALIDATION_FAILED` \u2014 Field validation failed. `error.fields` names each one.\n- `UNKNOWN_CLICK_ID` \u2014 No click of yours matches that click_id \u2014 unknown, or on another advertiser\u2019s offer, deliberately indistinguishable. The order is not attributed and the attempt is logged.\n- `OFFER_NOT_STRAIGHT_SALE` \u2014 The click belongs to an offer that is not on a straight-sale model (CPA or RevShare); send status changes for it to /advertiser/callback.\n- `CURRENCY_MISMATCH` \u2014 A settlement amount in a currency other than the offer\u2019s. There is no currency conversion: an order sold in another currency is accepted and waits for `settlement_amount` in the offer currency.\n- `CLICK_NOT_ATTRIBUTABLE` \u2014 The affiliate behind the click is not active, so a new order cannot be attributed to it.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "423": {
                        "description": "- `ACCOUNT_SUSPENDED` \u2014 This account cannot submit data: it is suspended, blocked or archived. Also the answer to an advertiser callback whose credential is valid but whose advertiser account is not active.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "- `RATE_LIMITED` \u2014 Too many requests.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "- `INTERNAL_ERROR` \u2014 Unexpected. Quote the request_id when contacting support.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/affiliate/leads": {
            "post": {
                "summary": "Submit a lead.",
                "operationId": "api.v1.affiliate.leads.store",
                "security": [
                    {
                        "affiliateToken": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "The lead was accepted and queued for delivery to the advertiser. `data.payout` is indicative: it becomes binding only when the qualifying goal event fires. Repeating the same `Idempotency-Key` with the same payload replays this exact response, status included, with `Idempotent-Replay: true` \u2014 there is no separate 200 for a replay.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Success"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "- `MALFORMED_REQUEST` \u2014 The body could not be parsed, or the content type is wrong.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "- `UNAUTHENTICATED` \u2014 The API token is missing, invalid, expired or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "- `FORBIDDEN` \u2014 Authenticated, but the token lacks the required scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "- `NOT_FOUND` \u2014 Unknown, belongs to another account, or a private offer you have not been granted \u2014 deliberately indistinguishable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "- `IDEMPOTENCY_CONFLICT` \u2014 The idempotency key was reused with a different payload.\n- `IDEMPOTENCY_IN_PROGRESS` \u2014 The original request is still being processed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "410": {
                        "description": "- `OFFER_DISABLED` \u2014 The offer is disabled. Nothing is stored for it \u2014 unlike a paused offer, which stores the lead and answers 423.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "- `VALIDATION_FAILED` \u2014 Field validation failed. `error.fields` names each one.\n- `GEO_NOT_ALLOWED` \u2014 That GEO is not configured or not active for this offer.\n- `OFFER_NOT_AVAILABLE` \u2014 The offer has no active goal to attribute the lead to.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "423": {
                        "description": "Accepted and stored, but not delivered: the offer is paused, your access request has not been approved yet, or the advertiser\u2019s balance policy blocks new leads. The body is a normal data envelope \u2014 `data.transaction_id` and `data.reason_code` (`OFFER_PAUSED`, `OFFER_APPROVAL_REQUIRED` or `ADVERTISER_BALANCE_STOP`) let the two sides reconcile. From the affiliate\u2019s side this is not a failure; the lead can still be sent to processing by a manager once whatever blocked it is resolved \u2014 or moved to trash or rejected, which is the same manual decision. Only a `disabled` offer refuses outright (410 `OFFER_DISABLED`), because it stores nothing for a manager to reprocess. A private offer you have not been granted answers 404 `NOT_FOUND`, exactly as an unknown id; without approved access a submission that cannot be stored answers 423 `OFFER_APPROVAL_REQUIRED` as an error, without field details.\n\nAlso returned with an error envelope:\n\n- `OFFER_APPROVAL_REQUIRED` \u2014 This offer needs an approved access request and the submission could not be stored as sent. Nothing was stored, and which field or GEO was wrong is not said until access is approved. A submission that can be stored is stored as failed instead and answers 423 with `data.reason_code` OFFER_APPROVAL_REQUIRED.\n- `ACCOUNT_SUSPENDED` \u2014 This account cannot submit data: it is suspended, blocked or archived. Also the answer to an advertiser callback whose credential is valid but whose advertiser account is not active.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/Success"
                                        },
                                        {
                                            "$ref": "#/components/schemas/Error"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "- `RATE_LIMITED` \u2014 Too many requests.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "- `INTERNAL_ERROR` \u2014 Unexpected. Quote the request_id when contacting support.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}